Skip to main content
Version: 0.5

swatchbook

A Storybook addon and MDX blocks for documenting DTCG design tokens.

Two things in one:

  • Doc blocks. TokenNavigator, TokenTable, ColorPalette, TypographyScale, TokenDetail, and a handful of type-specific previews. Drop them into MDX pages and your token reference writes itself.
  • A multi-axis theme switcher. Flip dark mode, brand, contrast, density — whatever dimensions your design system has — from one toolbar button. Each dimension is a DTCG resolver modifier; each becomes a dropdown in a single popover. Tokens repaint live as readers flip axes. See why axes, not themes for the shape.

Who it's for​

Design-system authors who already have DTCG tokens (or are authoring them) — especially systems with more than one independent dimension (brand × mode, contrast × mode, density, and so on) — and want a browsable, interactive reference without building a custom docs site.

If your system has exactly one dimension and no plans for more, @storybook/addon-themes' single-string-ID model is simpler and probably a better fit.

What it's not​

Swatchbook isn't a runtime theme-switcher for production apps, a CSS-variable framework, or a component styling system. It emits CSS variables and data-<prefix>-* attributes on <html> inside the Storybook preview so tokens repaint when an author toggles an axis — 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). For how your stories react to toolbar flips, see theme reactivity.

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 organized per-$type (one file for each of color, size, typography, motion, border, shadow, gradient, stroke, font, number), with resolver-driven mode × brand × contrast axes. Every block, panel, and toolbar control is wired up against those tokens.

How to read these docs​

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.