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, ColorTable, TokenTable, TokenDetail } from '@unpunnyfuns/swatchbook-blocks';

<ColorPalette filter="color.**" />
<ColorTable 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, ColorTable, 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, so we use the channel directly).

Do / don't

• ✅ Use blocks in MDX *.mdx docs pages for token reference tables.
• ✅ 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.