Skip to content
swatchbook logoswatchbook logoswatchbook

Blocks

The MDX-embeddable doc blocks for token reference pages live in @unpunnyfuns/swatchbook-blocks. Each block reads the active token graph from a SwatchbookProvider and re-renders when the active axis tuple flips.

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" />

Install

Section titled “Install”
Terminal window
npm install -D @unpunnyfuns/swatchbook-blocks

Two ways to mount

Section titled “Two ways to mount”

Inside Storybook, register @unpunnyfuns/swatchbook-addon; its preview decorator wraps every story and docs render in a SwatchbookProvider, so blocks work with no setup on the author’s side. Outside Storybook, mount the provider yourself and pass a wire snapshot; Provider covers the props, axis control, and the host seam, and Rendering blocks standalone walks the whole path, from the snapshot build script to axis switching.

SwatchbookProvider, the hooks, and the backing contexts (ThemeContext, AxesContext, ColorFormatContext) are re-exported verbatim from @unpunnyfuns/swatchbook-addon, so either import path works depending on which packages your consumer already pulls in.

Groups

Section titled “Groups”
  • Provider: SwatchbookProvider props, axis control, useSetAxes, the /host seam.
  • 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.
  • Presenters: the $type-keyed registry behind every per-type visual, how to override one, and how to embed a presenter directly.
  • Hooks: useSwatchbookData, useActiveTheme, useActiveAxes, useColorFormat, plus color formatting, for authoring custom blocks against the same provider the built-ins read from.
  • Diagnostics block: project-load diagnostics as a block.

Most overview blocks take filter? (path glob), sortBy?, sortDir?, and caption?; see Overview blocks for the full prop set.

Reactivity

Section titled “Reactivity”

Blocks re-render when the active axis tuple or color format changes, in both story renders and MDX doc blocks. See the hooks reference for how the subscription works.