Skip to content
Limitations live only in our minds.
But if we use our imaginations,
our possibilities become limitless
Jamie Paolinetti

Styleguide setup

Regardless of which tool I use to build my styleguides, it helps a lot to have a checklist of packages I need for (almost) every project setup.

Styles #

Node-sass is a library that provides binding for Node.js to LibSass, the C version of the popular stylesheet preprocessor, Sass.

npm install node-sass --save-dev

PostCSS is a tool for transforming styles with JS plugins. These plugins can lint your CSS, support variables and mixins, transpile future CSS syntax, inline images, and more.

npm install postcss postcss-cli postcss-preset-env postcss-import --save-dev

To configure postcss, add .postcss.config.js in project root folder

πŸ™ GitHub snippet

A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.

npm install stylelint stylelint-scss stylelint-order --save-dev

To configure stylelint, add .stylelintrc.json in project root folder

πŸ™ GitHub snippet

A Sass mixin that helps you compose media queries in an elegant way.

npm install sass-mq --save-dev

Add sass-mq configuration in styles folder src/scss/00-settings/_sass-mq-config.scss

πŸ™ GitHub snippet

In a static project, as a styleguide, to use sass-mq in our styles, we have to import it from node_modules and add our configuration

// src/scss/00-settings/__settings.scss

@import 'node_modules/sass-mq/_mq.scss';
@import 'sass-mq-config';

In projects that use webpack, we could add sass-mq using this syntax

// With webpack (and boilerplates such as create-react-app)
@import '~sass-mq';

This project is the Sass version of Normalize.css, a collection of HTML element and attribute rulesets to normalize styles across all browsers.

npm install normalize-scss --save-dev

Import normalize-scss from node_modules

// src/scss/02-generic/__generic.scss

@import 'node_modules/normalize-scss/sass/_normalize.scss';

Styles structure #

  • scssΒ folder contains BEMIT SASS file structure
  • cssΒ folder contains compiled CSS output
β”œβ”€β”€ src/
β”‚ β”œβ”€β”€ scss/
β”‚ β”‚ β”œβ”€β”€ 00-settings/
β”‚ β”‚ β”œβ”€β”€ 01-tools/
β”‚ β”‚ β”œβ”€β”€ 02-generic/
β”‚ β”‚ β”œβ”€β”€ 03-elements/
β”‚ β”‚ β”œβ”€β”€ 04-objects/
β”‚ β”‚ β”œβ”€β”€ 06-components/
β”‚ β”‚ β”œβ”€β”€ 07-utilities/
β”‚ β”‚ β”œβ”€β”€ style.scss
β”‚ β”œβ”€β”€ css/
β”‚ β”‚ β”œβ”€β”€ style.css

πŸ“š More info

BEMIT: Taking the BEM Naming Convention a Step Further

Styles scripts #

Use package.json scriptsΒ object to list all styles commands

"scripts": {
"_____________________________Styles_____________________________": "",
"stylelint": "stylelint 'src/scss/**/*.scss' || echo \"Stylelint failed for some file(s).\"",
"cleanup:dev": "rimraf dist src/css/*.css",
"scss:to:css:dev": "node-sass --output-style expanded src/scss/ -o src/css/",
"css:to:postcss:dev": "postcss src/css --dir dist/css",
"styles:dev": "npm run stylelint && npm run scss:to:css:dev && npm run css:to:postcss:dev",


Node.js tool for optimizing SVG files

npm install svgo --save-dev

Create two folders, one for original SVG files src/svgΒ and a second one optimized SVGs src/svgo

β”œβ”€β”€ src/
β”‚ β”œβ”€β”€ svg/
β”‚ β”‚ git.svg
β”‚ β”‚ nodejs.svg
β”‚ β”‚ vuejs.svg
β”‚ β”œβ”€β”€ svgo/
β”‚ β”‚ git.svg (optimized)
β”‚ β”‚ nodejs.svg (optimized)
β”‚ β”‚ vuejs.svg (optimized)

Add SVGO script configuration

πŸ™ GitHub snippet

SVG scripts #

Use package.json scriptsΒ object to list all SVG manipulation commands

"scripts": {
"_____________________________SVG________________________________________________": "",
"clean:svgo": "rimraf src/icons/svgo/*",
"svg:optimize": "npm run clean:svgo && node scripts/svgo.js",

Ok now I am ready to develop my components and build a styleguide! πŸ’ͺ🏻

View on GitHub

Comment on or Hashnode

Take me to the next post!