Styleguide setup

Β·

3 min read

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",
  },

SVG

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! πŸ’ͺ🏻