KSS-Scheibo

KSS-Scheibo is a builder template for KSS-node that turns CSS/SCSS documentation comments into a living styleguide with custom sections for colors, wrappers, RequireJS, body classes, and HTML language attributes.

What is KSS-Scheibo?

KSS-Scheibo is a Node.js package and builder template that plugs into kss-node, the styleguide generator for CSS and SCSS. It accepts KSS-style documentation comments in your stylesheets plus an optional kss-scheibo.json configuration file, and generates a static HTML living styleguide. The package is published on npm as kss-scheibo and developed by scheibome, with source on GitHub.

Key Features

• Custom builder template — Replaces the default KSS-node builder; point --builder at node_modules/kss-scheibo/kss_styleguide/scheibo-template/.
• Color section — Use the Colors custom option to display SCSS color variables as swatches in the styleguide.
• Wrapper section — The Wrapper custom option lets you wrap component markup with custom HTML, e.g., a grey background, via the <wrapper-content/> placeholder.
• Section insertion — Insert an existing section's markup into another using <insert-markup>2.1-0</insert-markup>, with the digit after the dash selecting which example to embed.
• RequireJS support — Add RequireJS globally or per section so fullscreen component demos can load JavaScript modules.
• Global HTML and body classes — Set htmllang, htmlclass, and bodyclass options in the config; per-section classes are also supported.
• Theme colors — Customize the styleguide's color scheme via themeColor and themeTextColor.
• Node API — Import build and watch from kss-scheibo to generate the styleguide programmatically and rebuild on file changes.

Who is it for?

• Front-end developers building and documenting component libraries in SCSS: write KSS comments once and get a living styleguide without hand-maintaining a docs site.
• Design system teams that need custom demos with real JavaScript: use RequireJS and fullscreen modes to test components in isolation.
• KSS-node users who want a more configurable builder than the default: the custom sections and theme options extend the standard KSS workflow.
• Open-source maintainers publishing a component library on npm; they can use the Node build/watch API to automate styleguide generation in CI.

What can you do with KSS-Scheibo?

• Document color tokens: define SCSS variables like $color-primary: #FF6400 in KSS comments and the Colors section renders them as a named palette.
• Demo composite components: compose sections by inserting one component's markup inside another with <insert-markup>, useful for forms that reuse inputs.
• Build fullscreen examples with JavaScript: attach RequireJS and data-main scripts to individual fullscreen examples to test interactive behavior.
• Customize the styleguide chrome: set the theme color, text color, and global body/HTML classes to match your brand.

How does KSS-Scheibo work?

Install the package with npm install kss-scheibo --save-dev. Then create a kss-homepage.md and document your styles with KSS-style comments. Configure kss-scheibo.json at the package root to set the builder path, source, destination, and custom sections, and run the KSS CLI node node_modules/kss/bin/kss --config yourconfigname.json, or use the exported build and watch functions from kss-scheibo in a Node script.

FAQ

Is KSS-Scheibo free to use?

KSS-Scheibo is an open-source npm package, so there is no license fee. It is an MIT-licensed project (per the npm license badge), hosted on GitHub.

Does KSS-Scheibo work without kss-node?

No. KSS-Scheibo is a builder template for kss-node, so you must have kss-node installed to generate the styleguide. It uses the KSS CLI or the kss-node programmatic API.

What are the custom sections available?

The package supports Colors, Wrapper, RequireJS, HTMLclass, BodyClass, and HtmlLang as custom sections. Each is enabled by listing it in the custom array of the configuration file, and each has its own syntax for defining content in the KSS comments.

How do I include one section inside another?

Use the <insert-markup> tag with a reference like 2.1-0 in your KSS markup example. The number before the dash is the KSS reference, and the number after the dash is an index (starting at 0) selecting which example variant to insert.

Can I change the global language attribute?

Yes. Set the htmllang option in the configuration to a BCP 47 language tag, for example "de", and enable the HtmlLang custom section.