Skip to content

About

A minimal, production-friendly Storybook environment for a Context-Based Design Systems workshopping.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

29 Commits

Folders and files

Repository files navigation

CBDS Components

The code half of a workshop on design-to-code fidelity. The premise: the richer the context in a Figma file, the higher-fidelity the coded component you can generate from it.

The design half lives in the CBDS UI Kit Demo Figma project, where every component set carries a structured description (purpose, behavior, composition, usage, accessibility contract, code-generation notes) and the interaction annotations name real motion tokens. This repo is where that context gets cashed in.

Why this repo looks the way it does

Three things the workshop is really about, and where each one shows up here:

Design to code, via AI. The components in src/components/ were not hand-written from a screenshot. They were generated by pointing an assistant at a Figma component that already knew how to describe itself. The gap between a good result and a bad one is almost entirely the quality of what the design file had to say.

Context is the product. A Figma component set that carries only geometry gives a generator geometry. One that also states its purpose, its behavior, which states are pseudo-classes rather than props, its ARIA contract, and which nested parts already exist in code — that produces something you would merge. Every component set in the CBDS file now carries that, and it is why Chip arrived knowing that its focus ring is :focus-visible, that state is not a prop, and that dismissing it must move focus.

Somebody inherits this. A design system is handed to an engineering team that was not in the room. What they inherit here is a token file that names its own source, a build that fails loudly when code drifts from design, descriptions that survive the person who wrote them, and a component tree ordered by dependency depth so the reading order is obvious. Hygiene is not tidiness — it is the difference between a system a new team can extend and one they quietly rewrite.

Prerequisites

  • Node.js 20 or newer

Getting started

npm install
npm run tokens      # Figma DTCG -> CSS custom properties
npm run storybook

Storybook opens at http://localhost:6006.

What's here, and what isn't

This library ships only the bottom of the dependency graph. Everything above it is generated live during the workshop, so the starting point stays legible.

Tier Components Depends on
Foundations Tokens, Motion —
Primitives Icon, Avatar Indicator nothing
Atomics Progress Bar, Chip Icon
Generated live Button, Tabs, Accordion, Alert, Dialog… increasingly deep composition

Button and Alert were deliberately removed — they are the first things we build together, and their Figma descriptions are the richest in the file.

Themes

The color semantic collection in Figma has three modes, and all three ship:

  • Light — :root
  • Dark — [data-theme='dark']
  • Brutalist — [data-theme='brutalist']

Switch between them with the paintbrush in the Storybook toolbar.

The token pipeline

Figma variables ──► tokens/dtcg/tokens.tokens.json   (W3C DTCG, canonical)
Figma styles    ──► tokens/json/global.json           (elevation + text styles)
                              │  npm run tokens
                              ▼
                    src/styles/tokens.css             :root — light + primitives
                    src/styles/tokens.dark.css        [data-theme='dark']
                    src/styles/tokens.brutalist.css   [data-theme='brutalist']
                    src/styles/tokens.d.ts            union type of every token

tokens/dtcg/tokens.tokens.json is the source of truth: 446 tokens across six collections, every one carrying the description written on the Figma variable. Regenerate it from a live Figma read:

# 1. Dump variables through the Figma Console MCP plugin bridge (figma_execute)
# 2. Convert that dump to DTCG
node tokens/from-figma.mjs <dump.json>
# 3. Rebuild the stylesheets
npm run tokens

Read the dump through the plugin bridge, not figma_export_tokens — that tool serves a cached snapshot which can lag behind the file.

Drift detection

npm run tokens reports any --cbds-* variable a component references that no token defines. Design and code drifting apart is the failure mode this workshop is about, so the build says it out loud:

DRIFT: 1 token(s) referenced by components but not defined:
  --cbds-corner-radius-025

Adding a component

src/components/MyComponent/
  MyComponent.tsx           # component
  MyComponent.stories.tsx   # stories — title: 'Primitives/…' or 'Atomics/…'
  MyComponent.module.css    # styles, using CBDS tokens only
  index.ts

Style exclusively through tokens — color: var(--cbds-text-primary), padding: var(--cbds-spacing-200) — never raw hex or px. That is what makes all three themes work for free, and what the drift check enforces.

Then export it from src/index.ts — one line in the matching tier, one in the types block. That file is the package's public surface: if it is not exported there, it is not in the bundle.

Bundling for a product

The components ship as an npm package. The app around them — Storybook, the stories, Story UI, src/main.tsx — does not: the library build only follows what src/index.ts exports, so the workshop tooling stays in the workshop.

npm run package

That one command rebuilds tokens, bundles the components, emits type declarations, copies the token stylesheets into dist/, and wraps the result in an installable tarball:

dist/
  index.js          ES module — every component
  index.d.ts        types
  styles.css        every component's CSS Modules, bundled
  tokens/
    tokens.css      :root — light + primitives
    tokens.dark.css [data-theme='dark']
    …

Component CSS is bundled automatically. The token layer is not — it is global CSS that no component imports, so the bundler never sees it and a copy step brings it along. Without it the package ships components whose every var(--cbds-*) resolves to nothing.

React is a peer dependency, deliberately. Two copies of React in one app breaks hooks, so the consuming product supplies it. clsx and @phosphor-icons/react stay real dependencies and install themselves.

Using it in a product

No registry needed to try it — pack a tarball and install it straight from disk:

npm run package             # → cbds-components-0.1.0.tgz
# in the Next.js (or Vite, or Remix) app
npm install ../cbds-components/cbds-components-0.1.0.tgz

Import the tokens before the component styles — the cascade depends on it — then use the components:

import 'cbds-components/tokens.css';   // must come first
import 'cbds-components/theme.css';    // optional: semantic aliases
import 'cbds-components/styles.css';

import { Chip, Icon, ProgressBar } from 'cbds-components';

Add import 'cbds-components/tokens/dark.css' for the dark theme, then set data-theme="dark" on <html>.

Use the tarball rather than npm link — linking resolves React through this repo's node_modules as well as the app's, which is exactly the duplicate-React failure the peer dependency exists to avoid.

Publishing for real

The package is still private: true, which blocks npm publish but not npm pack — the tarball workflow above works as-is, with no way to publish by accident. When it should live in a registry, set private: false, bump the version, and point publishConfig at your registry. Nothing else about the build changes; only the consumer's install line does.

Storybook MCP

@storybook/addon-mcp is enabled, so while Storybook is running it serves an MCP endpoint at http://localhost:6006/mcp. An MCP client (Claude Code, Cursor, etc.) can use it to list components, read their props and docs, and get story preview URLs.

Start Storybook first (npm run storybook); the server only exists while it runs. Then connect your agent. This works with most agents:

npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

In Claude Code you can add it directly instead:

claude mcp add --transport http storybook-mcp http://localhost:6006/mcp

Agent instructions for using the server (check docs-list/docs-show before guessing props, and so on) live in AGENTS.md, which CLAUDE.md imports. If you change the port, use the new one in the command.

Story UI

Story UI generates Storybook stories from natural language, and is how components get built during the session.

The panel's source lives in src/stories/StoryUI/ and is checked in, because .storybook/manager.ts imports it. To generate with it, put an Anthropic API key in a .env file at the repo root (it is gitignored):

ANTHROPIC_API_KEY=sk-ant-...

Then run Storybook and Story UI together:

npm run storybook-with-ui

Open Story UI › Story Generator in the sidebar. New components in src/components/ are picked up without a restart.

After upgrading @tpitre/story-ui, run npx story-ui update to refresh the checked-in panel files, then clear node_modules/.vite and restart.

Scripts

Command Does
npm run tokens Rebuild CSS from DTCG, and report drift
npm run storybook Storybook dev server
npm run build Tokens, typecheck, production build
npm run package Bundle the components and pack a tarball for use in a product
npm run build:lib Bundle to dist/ without packing (package runs this first)
npm run build-storybook Static Storybook
npm run lint ESLint
npm run dev Vite dev server (standalone smoke test, not Storybook)

About

A minimal, production-friendly Storybook environment for a Context-Based Design Systems workshopping.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages