Documentation and living style guides

Documentation that stays accurate because it reads from the same tokens and components as production – not a PDF from last year with the wrong button colour.

Why static docs fail

Designers and developers need to agree on spacing, colour, and component behaviour. A wiki page with screenshots drifts the moment someone merges a token rename without updating the wiki. Living style guides fix that by rendering real components with real styles.

What ‘living’ means

• Examples import the same SCSS (or compiled CSS) as the product
• Token tables are generated from source maps or JSON exported from SCSS
• Breaking changes to a component show up in the guide on the next build

Storybook, Pattern Lab, and Fractal are common hosts. The tool matters less than the rule: one source of styles, many surfaces (app, docs, tests).

Exporting tokens for docs

Docs tools often want JSON, not SCSS. Export at build time rather than maintaining two lists:

// scripts/export-tokens.scss - compile or run via sass
@use '../scss/tokens/core' as core;
@use '../scss/tokens/brand-acme' as brand;

// A small script reads compiled custom properties or a dedicated JSON partial
// Style Dictionary is a common choice for SCSS + JSON + iOS/Android output

/* tokens.json - generated, not hand-edited */
{
  "color": {
    "primary": { "value": "#0066cc" },
    "surface": { "value": "#ffffff" }
  },
  "space": {
    "sm": { "value": "0.5rem" },
    "md": { "value": "1rem" }
  }
}

Style Dictionary (or a small custom script) reads token source and emits SCSS, CSS custom properties, and JSON in one pass. The style guide reads JSON for tables; the app reads SCSS or CSS.

Documenting components in SCSS

Put usage notes where authors look – comments above mixins and component partials, plus a short README in the package root. SassDoc generates reference pages from structured comments:

/// Primary action button
/// @group components
/// @param {Color} $bg [$color-primary] - background colour
/// @example scss
///   .btn { @include button-primary; }
@mixin button-primary($bg: $color-primary) {
  display: inline-flex;
  padding: $space-sm $space-md;
  background: $bg;
  border-radius: $radius-md;
}

SassDoc is not a replacement for rendered examples – pair generated API docs with Storybook stories that @use the same partial.

Minimal style guide without heavy tooling

A static HTML page that links your compiled CSS and shows each component with copy-paste markup is enough for small teams. Build it in CI when SCSS changes:

<!-- styleguide/index.html -->
<link rel="stylesheet" href="../dist/main.css">
<section>
  <h2>Button</h2>
  <button class="btn btn--primary">Primary</button>
  <pre><code>&lt;button class="btn btn--primary"&gt;...&lt;/button&gt;</code></pre>
</section>

Upgrade to Storybook when component count, variants, and interactive states make manual HTML tedious.

Governance hooks

• CI fails if style guide build breaks (missing partial, bad import)
• Visual regression (Chromatic, Percy, lost-pixel) catches unintended style changes
• Changelog on the token package when public names change

Try it

• Add SassDoc comments to two mixins and generate a reference page.
• Build a one-page HTML style guide that imports your compiled CSS.
• List one token or component that docs currently get wrong – plan a single-source fix.