Skip to main content
Version: 0.13

swatchbook

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

Two things in one:

  • Doc blocks. TokenNavigator, TokenTable, ColorPalette, TypographyScale, TokenDetail, and per-type previews for motion, shadow, border, and gradient. React components for MDX.
  • 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.
Try it right here

The yinyang icon in the top-right of this page drives the same switcher against this docs site's own DTCG tokens — flip mode, a11y, or typeface to see the concept in action on the page you're reading.

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. 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 — the emitted CSS is the same shape either way. For how your stories react to toolbar flips, see consuming the active theme.

What the addon includes​

Installation​

Register @unpunnyfuns/swatchbook-addon in .storybook/main.ts. It includes the toolbar, preview decorator, MDX blocks, ThemeSwitcher, and useToken(), and takes swatchbook-core, swatchbook-blocks, and swatchbook-switcher as transitive dependencies. import { TokenTable, ThemeSwitcher, useToken } from '@unpunnyfuns/swatchbook-addon' resolves from any consumer file. Each sub-package is also publishable on its own for projects that want only a slice — the switcher in a Docusaurus navbar, say, or the core loader in a build script without React.

No external compile step​

The addon publishes tokens to the Storybook preview through a Vite virtual module, recomputed on each reload. Edits to token files propagate via Vite's HMR. Parsing uses Terrazzo; the token pipeline covers the mechanism.

Doc blocks​

The blocks are React components for MDX: TokenDetail, TokenTable, TokenNavigator, ColorPalette, TypographyScale, FontFamilySample, FontWeightScale, StrokeStyleSample, Diagnostics, and per-type previews for motion, shadow, border, and gradient. They read the active tuple from the preview decorator's provider and re-render when the toolbar flips an axis. Filter, scoping, and sort props are supported. See the blocks reference, the authoring guide, and the token-dashboard template.

Toolbar​

The Swatchbook icon in Storybook's toolbar opens a popover containing preset pills, one dropdown per modifier axis, and a color-format selector: hex, rgb, hsl, oklch, or raw.

useToken hook​

useToken(path) returns { value, cssVar, type?, description? } and re-runs on theme change. Paths come from a generated .swatchbook/tokens.d.ts.

For AI agents​

The optional @unpunnyfuns/swatchbook-mcp package ships a stdio Model Context Protocol server that exposes your token graph — paths, axes, alias chains, diagnostics, per-theme resolved values — to AI assistants like Claude Desktop or Claude Code. Point it at your swatchbook.config.ts (or a bare DTCG resolver) and an agent can introspect and reason about the system without spinning up Storybook. Fourteen read-only tools; live-reloads on token edits.

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.