Giulia Chiola

Posted on Jan 16, 2021 • Updated on Oct 14, 2021 • Originally published at giuliachiola.dev

Styleguide setup

#css #styleguide #designsystem

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

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

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

stylelint

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

sass-mq

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';

normalize-scss

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

svgo

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