Building Design System

The Drift Between Figma and Your Repo

You started with a shared component library. Now you have three different "Button" components, five variations of your primary blue, and a Slack channel dedicated to "why did the header break on mobile?" Design systems are supposed to be the source of truth, but without a systematic workflow, they become the source of chaos. We've seen the repo where margin: 16px is hardcoded in 400 files, and the Figma file that hasn't been updated since the last quarter because the design tech debt is too high to clear.

The problem isn't that your engineers or designers are incompetent. The problem is that maintaining a design system manually is a full-time job that most teams can't staff, and AI agents need structured input to generate consistent UI code. When tokens are loose and component APIs are undocumented, every new feature request becomes a negotiation between design intent and engineering reality. You end up with a UI Design System Pack that feels like a constraint rather than an accelerator, and developers start copy-pasting styles from StackOverflow because the system is too brittle to trust.

Why Manual Token Management Burns Engineering Velocity

When your design system is just a Figma file and a GitHub repo with no validation, the drift starts immediately. Engineering teams hardcode values because the tokens are too abstract or the documentation is outdated. Designers update a component in Figma, but the codebase lags by weeks. The cost isn't just hours; it's the cognitive load. Every time a developer wonders "should I use spacing-md or gap-2?", you lose flow state. Over a quarter, that drift compounds into a maintenance tax that eats 20-30% of your frontend velocity ^[2].

This tax hits harder when you scale. You bring in new hires who spend weeks learning the unwritten rules of the UI. You ship updates that break accessibility contrast ratios because no one checked the semantic token layer. You waste days on regression testing just to swap a color because the primitives aren't decoupled from the components. Without automation and clear communication, your design system becomes a liability. Teams end up with "design system fatigue," where the system is viewed as a bureaucratic hurdle rather than a force multiplier. If you're struggling with the gap between design intent and implementation, a Design-to-Code Handoff Pack can help bridge that divide, but you still need a solid foundation of living tokens to make it stick.

How a Multi-Squad Team Avoids the Primary Blue Trap

Imagine a fintech team with 200 endpoints and four frontend squads. They inherit a legacy UI where "primary" means #0055ff in one repo and #0044cc in another. They try to fix it by manually updating CSS variables, but they miss the dark mode overrides, and the accessibility contrast ratios break on three pages. The fix requires a systematic approach, not a brute-force search-and-replace.

A team that implements a structured token workflow avoids this. They define primitives first—raw values like --color-primary-500: #0055ff—then map semantic tokens like --color-action-primary to those primitives ^[5]. When they update the primitive, the semantic layer propagates automatically. This decoupling means the design team can tweak the brand color without touching the component code. The engineering team gets a single source of truth that works across web, mobile, and desktop.

Once the tokens are defined, the component layer must be equally rigorous. Every component comes with an explanation and "best practice" usage patterns so that design and development interpretation remains aligned ^[3]. Using Storybook CSF 3, the team writes stories that cover edge cases: what happens when the button text is long? What's the focus ring color for keyboard navigation? The stories use typed StoryObj definitions and JSDoc summaries that AI agents can parse to generate context-aware code. When a developer asks an AI to "create a secondary button," the agent reads the JSDoc, checks the semantic tokens, and outputs code that matches the system exactly. With a validation script running on every PR, broken tokens and missing descriptions are rejected before they merge, keeping the system living and consistent across all squads.

From Static Docs to Living, Validated UI Infrastructure

Once this skill is installed, your design system stops being a document and becomes executable infrastructure. You get a W3C Design Tokens compliant JSON structure that validates on commit. The validators/validate-tokens.sh script checks token files against the W3C schema requirements, exiting non-zero on missing fields, invalid types, or broken references. This enforces strict token hygiene and prevents drift at the source.

Your Storybook stories use CSF 3 autodocs, so every component ships with an auto-generated props table, typed definitions, and rich MDX documentation. The templates/config/.storybook/preview.ts file sets global parameters for autodocs, ensuring consistent documentation behavior across all components. The templates/components/Button.mdx example shows how to render interactive stories and auto-generate props tables, providing a template your team can replicate for every component.

Automation is key to scaling your design system ^[4]. The scaffold.sh script initializes the directory structure, copies template files, and sets up foundational configuration in seconds. This ensures consistent project layout across teams and reduces onboarding time. The skill.md orchestrator guides you through the end-to-end workflow, from token definition to component documentation and validation. You shift from "fixing the button" to "updating the token," and the rest of the system follows. Documentation is no longer a chore; it's a side effect of the component definition. The AI agent has the canonical knowledge it needs to help you build, maintain, and evolve the system without hallucinating inconsistent patterns.

The File Manifest: What's Inside the Skill

This skill is a multi-file deliverable designed to be dropped into your repo and run. Every file serves a specific purpose in the workflow.

• skill.md — Orchestrator skill that defines the end-to-end workflow for building a scalable design system. References all templates, references, scripts, validators, and examples to guide the agent through token definition, component documentation, and validation.
• references/design-tokens-canonical.md — Canonical knowledge from W3C Design Tokens Community Group. Covers the 3-tier taxonomy (primitives, semantics, aliases), the Format Module 2025.10 JSON structure, and the shift from static to living tokens for cross-tool consistency.
• references/storybook-csf3-canonical.md — Canonical knowledge from Storybook CSF 3 documentation. Covers autodocs configuration via tags, preview.meta/story helpers, MDX documentation blocks (Meta, Story, ArgsTable, Title), and JSDoc best practices for AI context.
• templates/tokens/primitives.json — Production-grade W3C Design Tokens primitive definitions. Contains raw values (colors, spacing, typography) with $type, $value, and description fields, serving as the single source of truth for base design decisions.
• templates/tokens/semantic.json — Production-grade semantic token layer. Maps contextual names (e.g., color-action-primary) to primitive references using the W3C token format, enabling theming and consistent cross-platform styling.
• templates/components/Button.stories.ts — Production-grade Storybook CSF 3 component story. Implements autodocs at component level, hides experimental stories with !autodocs, includes JSDoc summaries for AI parsing, and uses typed StoryObj.
• templates/components/Button.mdx — Production-grade MDX documentation page. Uses Storybook blocks to render interactive stories, auto-generate props tables, and provide rich markdown descriptions aligned with CSF 3 autodocs.
• templates/config/.storybook/preview.ts — Production-grade Storybook preview configuration. Sets global parameters for autodocs, configures DocsPage defaults, and establishes consistent documentation behavior across all components.
• scripts/scaffold.sh — Executable bash script that initializes the design system directory structure, copies template files, and sets up foundational configuration. Ensures consistent project layout across teams.
• validators/validate-tokens.sh — Programmatic validator that checks token JSON files against the W3C schema requirements. Exits non-zero on missing fields, invalid types, or broken references, enforcing strict token hygiene.
• examples/worked-example.md — Step-by-step worked example demonstrating the full workflow: scaffolding, token definition, component development with CSF 3, running validators, and publishing documentation. Serves as a practical reference for cross-team UI consistency.

Ship Consistent UIs Without the Setup Tax

Stop guessing about token hierarchies and component APIs. Upgrade to Pro to install the Building Design System skill and ship a scalable, validated foundation for your UI. Let the AI handle the scaffolding, validation, and documentation while you focus on building features that matter.