A playbook for AI-assisted design systems

TL;DR

When AI agents tackle design system work without grounded references, they pattern-match from training data — and the output looks like it. Sistema is a knowledge base and playbook tool that gives agents access to curated documentation from real design systems, so every generation starts from the same references a senior designer would consult. I built up a knowledge base and a playbook of useful prompts for design system work, then used it to design itself.

When you ask an AI agent to generate a color palette or type scale without any grounding, it produces something that passes every technical test and signals no design intent. Medium-blue primary. Near-white surface with no hue temperature. Border-radius consistent across every component. Type scale differentiated by size alone. The outputs are correct. They're just not designed.

The problem isn't the AI. It's the brief. Without access to real reference material — how Carbon structures its two-tier token architecture, how Material 3 handles elevation, what WCAG 2.2 actually requires for UI components versus body text — the agent defaults to the statistical center of design system patterns it's seen. Safe, generic, forgettable.

This pattern kept surfacing as I was experimenting with AI-assisted design systems work. Every time I started a new design system project with Claude, the first output looked roughly the same. I'd spend most of my time correcting generic defaults rather than making intentional decisions. I was sure that design system foundations were ripe territory for automation — the agent just needed better guidance.

The idea behind Sistema is simple: the reference material is the constraint. Give an agent a brief and ask it to generate color tokens, and it produces plausible output. Give it the same brief after it reads Carbon's two-tier token architecture and Material 3's elevation model, and it produces something specific — with decisions it can justify by reference to how real systems solve the same problem.

Sistema is built around that idea. The knowledge base crawls real design systems and UI libraries — Material Design 3, Carbon, Atlassian, Primer, Ant Design, Radix — and makes them available at stable endpoints agents can fetch. Each play in the playbook embeds that material (i.e. links to the markdown) directly in the prompt, so the agent reads the references before generating.

I didn't write the knowledge base content — it's a curated synthesis. That curation is the feature: knowing which parts of Carbon's color architecture are specific to IBM's brand and which patterns generalize, knowing where the W3C standards and the popular frameworks disagree and why, knowing what questions a designer should be answering at each phase of a token system build.

A play is a structured prompt with fetch instructions baked in. The generate-color-scheme play reads Sistema's color architecture synthesis before producing token files — so the agent sees how Material, Carbon, and Atlassian each solve the same problem before proposing a solution for your project. The result is token output that reflects real design systems knowledge, not statistical averages.

Campaigns compose plays into multi-step sequences with human review gates between phases. The Bootstrap a Design System campaign is the main one: 4 phases, 11 steps, from blank repo to deployed components. It pauses after each phase for approval before advancing — you stay in control of the decisions while the agent handles the generation work.

The cleanest test of whether the tool works is to run it on itself. Late in the build, I ran the Bootstrap campaign on Sistema's own repository. The agent scanned the existing codebase, worked through the establish-context step, generated a visual direction brief, produced a complete DESIGN.md, then generated color, typography, shape, and spacing token files, configured the Style Dictionary v5 pipeline, and applied a design pass across 24 files.

The DESIGN.md it produced became the spec. Sistema's current visual design — the electric blue primary, the three-tier dark mode surface stack, the typography scale — came from human design input meeting Sistema's own playbook and knowledge base. The first end-to-end proof that the campaign works is the product itself.

Sistema is in public beta. Built in roughly seven days of intensive Claude Code sessions, it's a working demonstration of the core hypothesis: grounding AI design work in real reference material produces better output than prompting from a blank slate.

What's been proven: the tooling works, the knowledge base is queryable, the Bootstrap campaign runs end-to-end, and the dogfooding produced a real design system. What hasn't been proven yet: whether it's useful to designers other than me, at what scale the reference material starts to degrade in quality, and which kinds of design system problems benefit most from structured plays versus open-ended prompting. Those are the open questions — and the interesting ones.