emperor-toolbox v0.0.3

Emperor Toolbox

Enhance the generation of stylesheets with the power of Sass.

Features

Auto import from Google fonts

Declare your fonts once in the variables file and the library will automatically import them.

Example

// variables.scss
$fonts: (
    primary: 'Open Sans',
    secondary: 'Lato',
    accent: 'Montserrat',
);

// Compiles as:
@import url('https://fonts.googleapis.com/css?family=Open+Sans');
@import url('https://fonts.googleapis.com/css?family=Lato');
@import url('https://fonts.googleapis.com/css?family=Montserrat');

You can also set different font providers

Ease the use of variables

Thanks to the built-in tools you can easily load any variable with an improved method.

Example

// Autoload fallback fonts
html {
    font-family: font(primary);
}

label {
    font-family: font(accent, secondary);
}

// Compiles as:
html {
    font-family: 'Open Sans', arial, sans-serif;
}

label {
    font-family: 'Montserrat', 'Lato', arial, sans-serif;
}

Improved error management

While in development mode, you only need to run the command once. In case of a compilation error, a notification will popup with the required information to fix it and the compilation will not complete. As soon as you fix the error it will compile again on save.

That same message will display on the terminal, so you can check there if you prefer.

Debugger overlay

Set the $debug to true and you will be able to easily know which rules are being applied.

You can debug box layout, the media queries, etc.

Modes

There are two working modes, development and production, each one has a specific npm command. The value of this modes is given by the tasks each one provides.

While running the dev command, you will be able to see the sourcemap of your files, all the selectors on extended mode, and all your comments on the CSS file. You can be as explicit as you want with the documentation on the files.

The prod command generates a smaller file, faster for the server to load.

Commands

• npm run dev : Applies the following tasks:
  • compile
  • autoprefix
  • sourcemap
• npm run prod : Applies the following tasks:
  • compile
  • autoprefix
  • strip comments
  • minify

Definition of the tasks

This are the available tasks:

• compile : generates .css version of Sass files.
• sourcemap: generates relational sourcemap for the browser inspector.
• strip comments : removes all comments (/* /, /** /, // /!*)
• autoprefixer : adds vendor prefixes as defined in .browserslistrc

Architecture

This projects defines the following folder structure.

core

This folder contains various required variables and tools for the library.

:warning: You don't need to edit any of this files.

settings

Your variables, lists and maps. Set all your variables in this folder.

:recycle: You can override any of this settings to your liking.

Its recommended that you name your variables by its abstract key. Avoid specific names such as $black, naming $dark would be a better practice.

tools

Set of different utilities to ease the code generation. Here you can generate your map-get alias to ease following use. There are many built-in functions you can use.

Example

// tools/_functions.scss
/*
 * Gets one or many fonts from the map '$fonts'
 * @param string $fontsParam The key or keys
 * @return string The value or values for all the given keys
 */
@function font($fontsParam...) { // }

elements

Redefine the styles for the bare HTML selectors, like h1, table, input...

Example

// elements/_tables.scss
table {
    // The specific rules for this element
}
tr {
    // The specific rules for this element
}

pages

Specific pages styles. Each page has to have it's own sass file. The first line of each file will be its id selector.

Example

// pages/_contact.scss
#page_contact {
    // The specific rules for this page
}

components

Custom classes or ids.

.gallery {
    // The specific rules for this element
}

vendors

External libraries for extensions, modules, etc...

Example

// vendor/_font-awesome.scss
.fa {
    // Library rules
}

All this files must be imported on the main.scss, which will compile in your main.css.

Media queries

You can set your breakpoints on settings/variables. Each media query uses some of those variables.

The breakpoints must define the width when there is a media query change (including the unit px). For example, if you set s: 480px, the mobile media query will be applied to devices from 0 - 479px. At 480px the next media query will be applied.

This are the defined media queries. They should cover most of your needs.

• mobile: small screens. From 0 to s (exluded).
• tablet: medium screens. From s (included) to m (exluded).
• desktop: large screens. From m (included) onwards.
• no-desktop: same as mobile AND tablet. From 0 to m (excluded).
• no-mobile: same as tablet AND desktop. From s (included) onwards.