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) are exported from @unpunnyfuns/swatchbook-blocks only. The addon does not re-export them.

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?.

Hooks

All hooks live in this package — they are not re-exported from @unpunnyfuns/swatchbook-addon. They read from the nearest SwatchbookProvider (mounted automatically by the addon's preview decorator inside Storybook).

useSwatchbookData()

Returns the full ProjectSnapshot the provider is holding (themes, axes, presets, tokens, diagnostics, …). Useful for custom blocks that need graph-level information the canned blocks don't expose.

useActiveTheme()

Returns the current composed permutation ID as a string (e.g. "Dark · Brand A").

useActiveAxes()

Returns the active tuple as Readonly<Record<string, string>>.

useColorFormat()

Returns the active color format ('hex' | 'rgb' | 'hsl' | 'oklch' | 'raw') — the display setting toggled from the toolbar popover. Pair with formatColor(value, format) (also exported) to render colors the same way the built-in blocks do. hex falls back to space-separated rgb() for out-of-gamut colors, marked with a ⚠ warning.

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.
• ❌ Don't import block-side hooks or contexts from @unpunnyfuns/swatchbook-addon — they live in this package only.