KSS Documentation

KSS, or Knyle Style Sheets, is a documentation syntax for CSS that allows developers to create a living style guide from CSS comments. It's structured to be both human-readable and machine-parsable, enabling automated tools to generate style guides from your CSS files. Here's an example of a comprehensive KSS comment block for a CSS stylesheet, including all the main options it can have:

/*
A button suitable for giving a user a call to action.

Style guide: Components.Buttons.Primary

:hover             - Highlights when hovered.
:disabled          - Dims the button when it cannot be interacted with.
.small             - A smaller button for less important actions.
.large             - A larger button for more important actions.

Markup:
<button class="btn {{modifier_class}}">Button</button>

Modifiers:
- .small - A small version of the primary button
- .large - A large version of the primary button

State classes:
- .is-active - Highlights the button as active
- .is-disabled - Shows the button as disabled

Variables:
- $btn-background-color: Color of the button background.
- $btn-text-color: Color of the button text.

$btn-background-color: #007bff;
$btn-text-color: #ffffff;

@brand Primary

@dependencies
- forms.css
- grid.css

@requires
- mixins.css
- variables.css

@implementations
- Web: components/button/button.css
- iOS: components/button/button.swift
- Android: components/button/button.xml
*/
.btn {
  background-color: $btn-background-color;
  color: $btn-text-color;
  /* other styles */
}

This example includes:

  • Description and Title: A brief description of the component or style and optionally a title.
  • Style Guide Reference: Indicates where in the style guide this component or style belongs.
  • States and Modifiers: Describes different states (:hover, :disabled) and modifiers (.small, .large) that the element can have, including their descriptions.
  • Markup: Provides an HTML snippet as an example of how to implement the described style.
  • Variables: Lists any CSS variables (custom properties) used in the style, including their default values.
  • Brand: Optional brand or category this component belongs to.
  • Dependencies: Other CSS files or assets this component depends on.
  • Requires: Additional resources or files that are required for this component.
  • Implementations: Links or references to implementations of the component in different technologies or platforms.

This structured comment allows developers and designers to understand the purpose, usage, and variations of a component at a glance. It can be processed by tools like KSS Node to generate a living style guide, ensuring documentation stays up-to-date with the code.