Blocks

Published as @unpunnyfuns/swatchbook-blocks. MDX-embeddable doc blocks. Each block reads the active token graph from the addon's virtual module and reacts to axis changes.

Install

npm install -D @unpunnyfuns/swatchbook-blocks

Inside Storybook, register @unpunnyfuns/swatchbook-addon alongside these blocks — its preview decorator mounts a SwatchbookProvider (exported from this package) that the blocks read from. Outside Storybook, wrap your tree in SwatchbookProvider and pass a ProjectSnapshot directly.

SwatchbookProvider, useSwatchbookData, useActiveTheme, useActiveAxes, useColorFormat, and the backing contexts (SwatchbookContext, ThemeContext, AxesContext, ColorFormatContext) live in @unpunnyfuns/swatchbook-blocks. @unpunnyfuns/swatchbook-addon re-exports them verbatim, so either import path works depending on which packages your consumer already pulls in.

Usage

Inside Storybook

import { ColorPalette, TokenTable, TokenDetail } from '@unpunnyfuns/swatchbook-blocks';

<ColorPalette filter="color.*" />
<TokenTable filter="size.*" type="dimension" />
<TokenDetail path="color.accent.bg" />

The addon's preview decorator wraps every story and docs render in a SwatchbookProvider, so no setup is required on the author's side.

Using blocks outside Storybook

Blocks are pure presentation. Given a ProjectSnapshot — the shape the addon internally publishes into virtual:swatchbook/tokens — they render in any React tree: unit tests, standalone docs apps, custom tooling.

import { SwatchbookProvider, TokenTable } from '@unpunnyfuns/swatchbook-blocks';
import snapshot from './tokens-snapshot.json';

export function TokenDocs() {
  return (
    <SwatchbookProvider value={snapshot}>
      <TokenTable filter='color.*' />
    </SwatchbookProvider>
  );
}

SwatchbookProvider is the canonical entry point. The virtual:swatchbook/tokens module is the Storybook addon's internal wiring — do not import from it directly in consumer code.

Groups

Four groups by shape of use:

• Overview blocks — survey many tokens at once. TokenNavigator, TokenTable, plus the per-type scales and palettes.
• Inspector blocks — single-token deep-dive. TokenDetail and its subparts.
• Sample blocks — one-token visual atoms you can drop inline.
• Utility blocks — Diagnostics.

Most overview blocks take filter? (path glob), sortBy?, sortDir?, and caption?.

For authoring custom blocks against the same provider the built-ins read from, see the Hooks reference — useSwatchbookData, useActiveTheme, useActiveAxes, useColorFormat.

Reactivity

All blocks subscribe to Storybook's globalsUpdated channel event and re-render when the active axis tuple or color format changes. This works both inside story renders and inside MDX doc blocks (where the preview HooksContext isn't available — we use the channel directly).

Do / don't

• ✅ Use blocks in MDX *.mdx docs pages for rich token references.
• ✅ Filter aggressively — <TokenTable filter="color.*" type="color" /> beats unfiltered tables for browsability.
• ✅ Use blocks outside Storybook by wrapping the tree in SwatchbookProvider and passing a ProjectSnapshot. The blocks themselves are framework-free.
• ✅ Either @unpunnyfuns/swatchbook-blocks or @unpunnyfuns/swatchbook-addon works as an import source — the addon re-exports the blocks surface so you don't have to pin a second dependency in consumer projects that already have the addon.