NOTE: This is an annotated copy of the official KSS spec, which is available at github.com/kneath/kss. This copy includes annotations of the spec which only apply to the kss-node implementation available at github.com/kss-node/kss-node. The kss-node-specific notes will be clearly marked with the text: kss-node only:
KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and style guide format. It is not a preprocessor, CSS framework, naming convention, or specificity guideline.
KSS is a set of guidelines to help you produce an HTML style guide tied to CSS documentation that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine. It is designed with CSS preprocessors (such as Sass or LESS) in mind, and flexible enough to accommodate a multitude of CSS frameworks (such as Bootstrap or Foundation).
KSS focuses on how people work with CSS — it does not define code structures, naming conventions, or methods for abstraction. It is important to understand that the style guide format and documentation format are intrinsically tied to one another.
Not every CSS rule should be documented. You should document a rule declaration when the rule can accurately describe a visual UI element in the style guide. Each element should have one documentation block describing that particular UI element's various states.
KSS documentation is hierarchical in nature — any documentation block at any point within the style guide hierarchy applies to the documentation blocks beneath that level. This means that documentation for 2.1 applies to documentation for 2.1.3.
The basic format for KSS documentation can be explained best in an example:
/*
Button
Your standard button suitable for clicking.
:hover - Highlights when hovering.
:disabled - Dims the button when disabled.
.primary - Indicates button is the primary action.
.smaller - A little bit smaller now.
Styleguide 2.1.3
*/
.button {
...
}
.button.primary {
...
}
.button.smaller {
...
}
.button:hover {
...
}
.button:disabled {
...
}When using a preprocessor that supports the functionality, use // to prefix your comment sections (Sass example):
// Button
//
// Your standard button suitable for clicking.
//
// :hover - Highlights when hovering.
// :disabled - Dims the button when disabled.
// .primary - Indicates button is the primary action.
// .smaller - A little bit smaller now.
//
// Styleguide 2.1.3
.button {
...
&.primary {
...
}
&.smaller {
...
}
&:hover {
...
}
&:disabled {
...
}
}Each KSS documentation block consists of two required parts and a few optional parts:
- a heading (required)
- a description of what the style does or looks like (optional)
- kss-node only: the name of file containing the HTML markup the CSS applies to, or a copy of the markup inline (optional)
- a list of modifier classes or pseudo-classes and how they modify the style (optional)
- a reference to the style's position in the style guide (required)
- kss-node only: a numerical weight that can be used to re-position a style outside of the normal alphabetical order (optional)
The description should be plain sentences of what the CSS rule or hierarchy does or looks like. A good description gives guidance toward the application of elements the CSS rules style. The first paragraph in the description will be used as the heading for that style guide section.
// Activity feed
//
// A feed of activity items. Within each section, there should be many
// articles which are the feed items.CSS rules that depend on specific HTML structures should describe those structures using <element#id.class:pseudo> notation. For example:
// A feed of activity items. Within each <section.feed>, there should be many
// <article>s which are the feed items.To describe the status of a set of rules, you should prefix the description with Experimental or Deprecated.
Experimental indicates CSS rules that apply to experimental styling. This can be useful when testing out new designs before they launch (staff only), alternative layouts in A/B tests, or beta features.
// Experimental: An alternative signup button styling used in AB Test #195.Deprecated indicates that the rule is slated for removal. Rules that are deprecated should not be used in future development. This description should explain what developers should do when encountering this style.
// Deprecated: Styling for legacy wikis. We'll drop support for these wikis on
// July 13, 2007.If the UI element you are documenting has multiple states or styles depending on added classes or pseudo-classes, you should document them using modifiers.
// :hover - Subtle hover highlight.
// .stars-given - A highlight indicating you've already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled - Dims the button to indicate it cannot be used.kss-node only:
You can include sample markup in your style guide entries. This is not only helpful for newcomers to a project, but is also used by the kss-node generator to include samples in your style guide. Just start a paragraph in your section with Markup: like so:
// Button
//
// Buttons can and should be clicked.
//
// Markup:
// <button class="button {{modifier_class}}">Button</button>
//
// :hover - Highlight the button when hovered.
//
// Styleguide 1.1If you include {{modifier_class}} in the markup, the generated style guide will be able to use the correct CSS class when it displays the sample for each of the modifiers.
Instead of using inline HTML markup, you could point at a separate file that contains your HTML. kss-node supports either a plain *.html file or a Handlebars *.hbs file. The kss-node generator will search for the markup file in any of the --source folders.
// Button
//
// Markup: button.hbs
//
// Styleguide 1.1Lastly, if your application or component library is built with Node.js, instead of using the markup section, you could use the JavaScript API provided to parse the KSS documentation and build a style guide using the HTML templating library of your choice.
If the UI element you are documenting has an example in the style guide, you should reference it using the "Styleguide [ref]" syntax.
// Styleguide 2.1.3.References can be integer sections separated by periods. Each period denotes a hierarchy of the style guide. Style guide references can point to entire sections, a portion of the section, or a specific example.
References may also be period seperated word keys. Leading words denote hierarchy.
// Styleguide Forms.CheckboxesFinally, references may be more readable word phrases.
// Styleguide Forms - Special CheckboxesIf there is no example, then you must note that there is no reference.
// No styleguide reference.kss-node only: If word keys or word phrases are used, kss-node will automatically generate a hierarchal number for each section since "section 4.1.3" is easier to communicate to others than "section forms - widgets - special checkboxes".
kss-node only: If the webified Styleguide spelling annoys you, you can use Style guide instead:
// Style guide: Forms.Checkboxeskss-node only:
In a styleguide, a palette of colors is important. Just start a paragraph in your section with Colors: and describe one color by line like so:
// Colors
//
// Buttons can and should be clicked.
//
// Colors:
// ColorName: #fad - color description
// $name-can-be-variable: white - description and name are optional
// #000
//
// Styleguide 1.1:to separe color name and color code.-to separe code from description
The color code is the only one requirement, name and description are optional
If a line do not respect this format, it will be ignored.
kss-node only:
If you are using word keys or word phrases as your style guide references, kss-node will sort all sections using alphabetical order. This can be problematic if, for example, you want the documentation about sass.variables to come before the docs about sass.mixins.
With kss-node, you can specify a numeric weight for style guide section that overrides the default alphabetical ordering of sibling sections. If no weight is specified for a section, the default weight of 0 is used. Lighter weights (like -10) will "rise above" sibling sections with the default weight of 0 and heavier weights (like 10) will "sink below".
For example:
// Sass mixins
//
// Style guide: sass.mixins
// Sass colors
//
// Style guide: sass.colors
// Sass variables
//
// Weight: -10
//
// Style guide: sass.variables
// Sass
//
// Weight: -1
//
// Style guide: sass
// Components
//
// Style guide: componentsThe above KSS docs will produce a style guide hierarchy like this:
1: Sass
1.1: Sass variables
1.2: Sass colors
1.3: Sass mixins
2: Components
First, you'll notice that kss-node has auto-generated hierarchal numbering for you. Also note that the weights only affect the ordering of siblings in the hierarchy; the weight of sass.variables only affects its ordering relative to sass.colors and sass.mixins.
Finally, any sibling sections with the same weight will be put into alphabetical order next to each other. In our example, if a new sass.modules section is added with Weight: -10, it would be alphabetically sorted before the sass.variables section with Weight: -10.
If you use a CSS preprocessor like Sass or LESS, you should document all helper code (like functions or mixins).
// gradient($start, $end)
//
// Creates a linear gradient background, from top to bottom.
//
// Compatible in IE6+, Firefox 2+, Safari 4+.
//
// $start - The color hex at the top.
// $end - The color hex at the bottom.
//
// Styleguide sass.mixins.gradient
@mixin gradient($start, $end) {
...
}Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.
If the mixin takes parameters, you should document each parameter and describe what sort of input it expects (hex, number, etc).
// $start - The color hex at the top.
// $end - The color hex at the bottom.You must list out what browsers this helper method is compatible in.
// Compatible in IE6+, Firefox 2+, Safari 4+.If you do not know the compatibility, you should state as such.
// Compatibility untested.In order to fully take advantage of KSS, you should create a living style guide. A living style guide is a part of your application and includes all of the CSS, Javascript, and layout the rest of your application does.
The style guide should be organized by numbered sections. These sections can go as deep as you like. Every element should have a numbered section to refer to.
kss-node only: If word keys or word phrases are used instead of numbered sections, kss-node will automatically generate a hierarchal number for each section based on the alphabetical and weight-based sorting of the sections.
For example:
1. Buttons
1.1 Form Buttons
1.1.1 Generic form button
1.1.2 Special form button
1.2 Social buttons
1.3 Miscelaneous buttons
2. Form elements
2.1 Text fields
2.2 Radio and checkboxes
3. Text styling
4. Tables
4.1 Number tables
4.2 Diagram tables
The goal here is to create an organizational structure that is flexible, but rigid enough to be machine processed and referenced inside of documentation.
This style guide is automatically generated from KSS documentation using the ruby library.
kss-node only: And this style guide is automatically generated from KSS documentation using the kss-node generator: http://kss-node.github.io/kss-node/
The actual templates generating the style guide just reference the Styleguide section and example HTML. The modified states are generated automatically. Refer to the README for more information on how to generate style guides using the KSS ruby library.
kss-node only: Refer to the kss-node README for more information on how to generate style guides using the kss-node generator.
Overall, keep in mind that style guides should adapt to the application they are referencing and be easy to maintain and as automatic as possible.
There are several software projects that read and parse KSS-compliant documentation to produce full-blown style guides in HTML. See the KSS project's README for more information.
kss-node only: Naturally, we prefer kss-node.
KSS was inspired by TomDoc. Without it, KSS wouldn't exist today!