Integrations

Display-side integrations that plug swatchbook's DTCG tokens into third-party tooling running inside Storybook. Each integration ships as a subpath of @unpunnyfuns/swatchbook-integrations and hooks into the addon via the integrations[] option in .storybook/main.ts.

Philosophy

Swatchbook's purpose is displaying DTCG tokens in Storybook, not replacing downstream build pipelines. Integrations wire the token graph into whichever runtime library a story needs — Tailwind's @theme block, a JS theme accessor for CSS-in-JS, and so on — without requiring the addon itself to know anything about that library. Integration packages own the library-specific logic.

Production artifacts (writing tokens.js / tailwind.config.css to disk for a consumer's own build) are not swatchbook's job — run Terrazzo's CLI against the same DTCG sources if you need artifacts outside Storybook.

Available integrations

Subpath	Covers	How consumers use it
/tailwind	Tailwind v4	Plug in, write bg-<prefix>-surface-default / p-<prefix>-md utilities anywhere. The addon auto-applies the generated @theme block.
/css-in-js	emotion, styled-components, any ThemeProvider consuming a JS theme object	Plug in, then import { theme, color, space } from 'virtual:swatchbook/theme' where needed. Named exports, explicit import.

Recipe coverage

Mapped against the @storybook/addon-themes getting-started recipes — swatchbook's toolbar replaces addon-themes outright (multi-axis, DTCG-native), and integrations cover the emitter side:

Library	Covered by
Tailwind	/tailwind integration
Bootstrap	CSS-var consumption + toolbar data-* attrs (no integration needed — Bootstrap's $theme-colors aliases --<prefix>-* directly)
PostCSS	CSS-var consumption + toolbar data-* attrs (same)
emotion	/css-in-js integration
styled-components	/css-in-js integration
MUI	not covered — needs resolved-value emission at factory time. See the note in /css-in-js

Wiring an integration

All integrations plug into the addon's options in .storybook/main.ts:

.storybook/main.ts

import { defineMain } from '@storybook/react-vite/node';
import tailwindIntegration from '@unpunnyfuns/swatchbook-integrations/tailwind';
import cssInJsIntegration from '@unpunnyfuns/swatchbook-integrations/css-in-js';

export default defineMain({
  addons: [
    {
      name: '@unpunnyfuns/swatchbook-addon',
      options: {
        configPath: '../swatchbook.config.ts',
        integrations: [tailwindIntegration(), cssInJsIntegration()],
      },
    },
  ],
});

Some integrations (Tailwind) are purely global stylesheet contributions and the addon applies them to the preview automatically. Others (CSS-in-JS) expose named JS exports for consumers to import where they want them. The per-integration page documents which pattern applies.

Token-file edits flow through HMR: each integration's output stays in lockstep with the active project without a server restart.

Writing your own integration

The mechanism is sketched in the architecture doc. In short: implement the SwatchbookIntegration contract from @unpunnyfuns/swatchbook-core, export a factory from your package, drop the factory's result into integrations[].