Skip to main content
Version: 0.13

For developers

You're reading the right section if you want to work on swatchbook's code — fix bugs, add blocks, extend the MCP tool set, rewrite how HMR flows. If you want to use swatchbook in your own Storybook, the Quickstart and Reference are the right doors.

This section assumes you've already skimmed CONTRIBUTING.md on GitHub, which covers dev setup, checks, commit conventions, and the release flow. What lives here is the how-does-the-code-work reference — the kind of thing a new contributor needs to build a mental model before making their first real change.

What's in this section​

  • Architecture — the repo map, the one data structure everything revolves around (Project), and how data moves from a token file on disk to a rendered doc block. Includes the static build path, the dev/HMR path, and how the MCP server plugs in.
  • Sharp corners — the "someone will bleed on this" list. Shapes that trip newcomers. Read this after Architecture so the rules have context.

Where the source lives​

.
├── packages/
│   ├── core/        # DTCG loader, CSS emission
│   ├── addon/       # Storybook addon (toolbar, preview, virtual module)
│   ├── blocks/      # MDX doc blocks + provider + hooks
│   ├── switcher/    # Framework-agnostic axis popover UI
│   └── mcp/         # MCP server for AI agents
├── apps/
│   ├── storybook/   # Dogfood Storybook — runs the addon against the reference fixture
│   └── docs/        # This Docusaurus site
└── packages/tokens/ # Multi-axis DTCG reference fixture

Quick orientation — typical work shapes​

  • Fixing a block's rendering — start in packages/blocks/src/<BlockName>.tsx. Look at packages/blocks/test/<block>.test.tsx for the existing assertions. Add your story under apps/storybook/src/stories/.
  • Changing how tokens load — packages/core/src/load.ts is the entry; packages/core/src/themes/ has the resolver and layered paths; packages/core/src/types.ts is the shape that flows out.
  • Adding an MCP tool — packages/mcp/src/server.ts — one file, one server.registerTool(…) call per tool. The MCP server is stateless beyond its in-memory Project reference.
  • Tweaking HMR behavior — packages/addon/src/virtual/plugin.ts is the addon-side watcher + channel broadcaster. packages/mcp/src/bin.ts mirrors the pattern for the MCP server. Keep them in lockstep.