Skip to main content
Version: 0.4

Swatchbook

A Storybook addon and MDX blocks for documenting DTCG design tokens. It parses your token files through Terrazzo, composes them across a resolver's modifier axes (mode × brand × contrast × …), and renders a browsable reference inside your Storybook — searchable token panel, a toolbar that flips axes so readers can see every token in every context, tuple-aware TokenDetail blocks, ColorPalette, TypographyScale, and more.

Who it's for​

Design-system authors who already have DTCG tokens (or are authoring them) and want a browsable, interactive reference without building a custom docs site.

What it's not​

Swatchbook isn't a runtime theme-switcher, a CSS-variable framework, or a component styling system. It emits CSS vars and data-<prefix>-* attributes on <html> inside the Storybook preview so tokens repaint when an author toggles an axis in the toolbar — that's a documentation affordance, not a production theming API. For production theme switching, use your framework's theming tools (or call @unpunnyfuns/swatchbook-core's emitCss at build time and wire it up yourself).

What the addon gives you​

  • Doc blocks — TokenDetail, TokenTable, TokenNavigator, ColorPalette, TypographyScale, FontFamilySample, FontWeightScale, StrokeStyleSample, Diagnostics, motion/shadow/border previews. Once the addon is wired up, authoring pages with these blocks is the primary day-to-day swatchbook interaction. See the blocks reference, the authoring guide, and the token-dashboard template for a turnkey browsable tree + diagnostics + table composition.
  • Toolbar — a single Swatchbook icon button opens a popover with preset pills, one dropdown per modifier axis (so a reader can browse tokens in every context), and a color-format picker (hex / rgb / hsl / oklch / raw) that controls how blocks display colors.
  • useToken hook — typed lookups from component code, reactive to the active theme.

See it live​

The live Storybook runs the addon against this repo's tokens-reference fixture — a multi-file DTCG token set with two layers (ref and sys) and resolver-driven axes. Every block, panel, and toolbar control is wired up against those tokens.

How to read these docs​

  • Quickstart — install, configure, run.
  • Blocks — the MDX doc blocks you'll spend most of your time with: the reference lists what's available and the authoring guide walks through composing them.
  • Concepts — the mental model: theming inputs, axes, presets, diagnostics.
  • Guides — the multi-axis walkthrough covers one-time setup.
  • Reference — API surface for the remaining packages (addon, core, config).

What these docs assume​

You're comfortable with Storybook (CSF, decorators, MDX docs). For DTCG itself, you've skimmed the 2025.10 spec or at least seen $value / $type / alias syntax before — we won't re-teach the spec here.