Style Guide Example

An example of living style guide using KSS

🎯 Purpose

The content of this style guide is not important because the purpose of this project is to practice kss-node and list tips for a further real usage.

The design is fully inspired by the awesome website every-layout.dev.

👨‍💻 Development

1. Install all the dependencies: npm install
2. Start the development server: npm run dev
3. Open a browser to http://localhost:3000
4. Modify the files in src/ and template/ folders

🔨 Building Tools

In order to keep the building tools simple, I decided to use only npm scripts instead of a task runner (Grunt, Gulp...) or a module bundler (Webpack, Rollup...).

Dependencies

• chokidar-cli: watch files and re-run build script when files have been modified during development
• browser-sync: synchronize and update browser when files have been modified during development
• npm-run-all: run multiple npm scripts in parallel or sequential in a cross-platform way
• stylelint and stylelint-scss: lint SCSS code

Tips

• npm-run-all seems to work only with defined npm scripts (e.g. run-p chokidar [options] browser-sync [options] does not work). Although the documentation is pretty clear, it was not obvious to me as a first time user 😅

🎨 Styles

In order to make the code more flexible, I decided to use the Sass preprocessor (with SCSS syntax) instead of pure CSS.

Any other preprocessor (LESS, Stylus...) is also a good choice.

Dependencies

• node-sass: compile .scss files to .css
• node-sass-package-importer: import easily dependencies from node_modules folder
• postcss-cli and autoprefixer: prefix automatically CSS properties for the supported browers in the .browserslistrc file
• sass-rem: convert px unit into rem, because when the user system is in Chinese, the minimum font-size is 12px in Chrome (very old bug 😱)

TODO

• Add minification of the generated main.css file for production

📖 Style Guide

In order to make the development faster, I decided to use the KSS style guide generator.

DocumentCSS and stylemark may also work well.

Dependencies

• kss: generate the style guide

Project Structure

• kss-config.json contains the options to run KSS CLI.
• src/ contains the .scss files of the styles to present in the style guide.
• template/ contains the files to customize the design of the style guide. It is not necessary and using the default template or overriding the default styles work well too.
• docs/ contains the generated style guide files and is used for the GitHub page.

Tips

• In the Markup block of the KSS comments, the class attribute must include {{ modifier_class }} to generate all the variant styles (e.g. Markup: <button class="button primary {{ modifier_class }}">Apply</button>).
• The placeholder KSS option allows to customize the placeholder text to use for the modifier classes (e.g. the default value generates <button class="button primary [modifier_class]">Apply</button>). However in this style guide all the modifier classes are actually pseudo-classes (:focus, :disabled...) and I did not find a way to remove the placeholder. Therefore I used an empty string, although it adds an extra space (e.g. <button class="button primary ">Apply</button>).
• The custom KSS option is very usefull to add custom properties to the KSS comments, but be careful to not use an existing property. Then they are accessible in the style guide template.
• The style guide template is made with handlebars. Although the syntax is easy to understand, it is recommended to look at the documentation for advanced customization.

Useful Links

• KSS Spec
• KSS Wiki
• KSS Demo
• KSS Real Example
• Build a Style Guide Straight from Sass