Hygieia Styleguide (based on github.com/stamkracht/michelangelo)
Table of contents
About
This is a custom template for the KSS-node living style guide.
Demo
Have a look at the demo styleguide generated with dummy content to get an impression of the Michelangelo theme with the ITCSS architecture.
Get started
Go to your project directory. If you haven't installed KSS-node yet, install it locally* npm install kss --save-dev.
*Don't install KSS-node globally, it will cause problems in the long run when you have multiple projects using KSS-node.
Now, install the Hygieia package locally.
npm install hygieia --save-dev
Create a kss-config file touch kss-config.json and specify the required config:
- title
- builder: refer to the Hygieia template
- source
- destination
- homepage
- css
- js
Read the KSS-node docs for more information about the config, or use the example below. Note: the source config should refer to your styles directory.
{
"title" : "Hygieia Styleguide",
"mask" : "*.scss",
"placeholder" : "[modifier]",
"//": "relative to this file.",
"builder" : "node_modules/hygieia/kss_styleguide/custom-template/",
"source" : "src/",
"destination" : "kss_styleguide/styleguide/",
"//": "relative to source.",
"homepage" : "../kss_styleguide/kss-homepage.md",
"//": "relative to the generated style guide.",
"css": [],
"js" : []
}
After setting up the config file, run kss --config kss-config.json to generate your living styleguide*. Locate your styleguide at the specified path in your config file and open it in the browser. Cowabunga!
*If you get the error command not found: kss. Fix this by adding ./node_modules/.bin to your PATH.
Usage
KSS-node and documentation syntax
KSS-node is an implementation of Knyle Style Sheets. This is a documentation syntax for css that can be used to create a living style guide. KSS-node has a few additional features such as adding a copy of the markup inline or external.
To get familiar with the documentation syntax it is highly advised to read through the annotated copy of the official KSS spec on the KSS-node repository.
Pro tip
When you're dealing with a high amount of example markup and you don't want to cause any code-bloat, seperate your example markup from your css modules. Create a directory in your kss_styleguide directory (name it anyway you want), and place the markup files in there. In your css module, link to the file for your example markup. (e.g., Markup: ../kss_styleguide/markup/components.form.html)
Hygieia specifications
Color grid
This is a grid overview of all your project colors. Every color item consists of 4 parts (the color variable and hexadecimal are required).
- color example
- color name
- color variable
- color hexadecimal
In the example below you can see we have a heading, a description, and we list our colors. To make the colors work you must first define your hexadecimal after the dash, then optionally add a color name.
// Primary Colors
//
// The primary colors for branding.
//
// $leonardo - #2980b9; Leader blue
// $donatello - #8e44ad; Purple tech
// $raphael - #c0392b; Sai
// $michelangelo - rgb(232, 126, 4); Cowabunga
// $splinter - #FDE3A7
//
// Styleguide Settings.ColorsResponsive
The specific styling for the styleguide is written mobile first. Which makes it possible to test your project's styling directly on any device size.
Smooth scrolling
When clicking on a sub navigation item, the page animate scrolls to that specific item, so smooooth.
Prefixed styles
All styles written for the styleguide are prefixed with .kss-. They do not interfere with your project styles.
ITCSS architecture
The example src directory is a boilerplate for ITCSS methodology. A methodology created by Harry Roberts.
Customize
Inside the node package directory, go to kss_styleguide/custom-template/kss-assets/css/ to change the styling of this theme. Run sass --watch --sourcemap=none kss.scss:kss.css to watch for changes and compile the scss files.
You can quickly change the primary color by changing the value of the variable $cowabunga in kss-settings.scss.