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
- Install all the dependencies:
npm install - Start the development server:
npm run dev - Open a browser to
http://localhost:3000 - Modify the files in
src/andtemplate/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-allseems 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
.scssfiles to.css - node-sass-package-importer: import easily dependencies from
node_modulesfolder - postcss-cli and autoprefixer: prefix automatically CSS properties for the supported browers in the
.browserslistrcfile - sass-rem: convert
pxunit intorem, because when the user system is in Chinese, the minimumfont-sizeis12pxin Chrome (very old bug 😱)
TODO
- Add minification of the generated
main.cssfile 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.jsoncontains the options to run KSS CLI.src/contains the.scssfiles 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
Markupblock of the KSS comments, theclassattribute must include{{ modifier_class }}to generate all the variant styles (e.g.Markup: <button class="button primary {{ modifier_class }}">Apply</button>). - The
placeholderKSS 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
customKSS 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.