Skip to content
swatchbook logoswatchbook logoswatchbook

For developers

These are notes for working on swatchbook’s code, whether that’s fixing a bug, adding a block, extending the MCP tool set, or reworking HMR. CONTRIBUTING.md covers dev setup, checks, commit conventions, and the release flow; these pages map the code itself.

Where the source lives

Section titled “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 Astro Starlight site
└── packages/tokens/ # Multi-axis DTCG reference fixture

Quick orientation: typical work shapes

Section titled “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.