swatchbook-blocks

React MDX doc blocks for swatchbook.

Render your DTCG tokens in .mdx stories: swatch grids, type-specific previews, per-token inspectors. The blocks react to the toolbar's axis flips without any wiring in your story code.

Most consumers pick this up transitively via @unpunnyfuns/swatchbook-addon; import { TokenTable } from '@unpunnyfuns/swatchbook-addon' works out of the box. Install this package directly when you want blocks without the Storybook addon, such as unit tests or a standalone React app wrapping tokens in a custom surface.

Install

npm install @unpunnyfuns/swatchbook-blocks

Usage

Inside Storybook the addon mounts a SwatchbookProvider for you:

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

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

Outside Storybook, wrap your tree in SwatchbookProvider and pass a ProjectSnapshot:

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

<SwatchbookProvider value={snapshot}>
  <TokenTable filter="color.**" />
</SwatchbookProvider>;

Block catalogue, props, and composition patterns live in the blocks reference and the authoring guide.

Boundaries

Blocks read from SwatchbookProvider, not the addon's internal virtual:swatchbook/tokens module; don't import that directly. And useGlobals / useArgs from storybook/preview-api throw in a docs context, so don't call them inside custom blocks.

Credits

Token parsing and resolver evaluation come from Terrazzo by the Terrazzo team via @unpunnyfuns/swatchbook-core.

Documentation

unpunnyfuns.github.io/swatchbook: concepts, guides, and full API reference.