Series
AI-Ready Design Systems
Stateless AI sessions need stateful documentation. This series walks through rebuilding a design system as the source of truth that AI coding tools and the people working alongside them both read from, every session.
Articles in this series 7
How we structure design systems to be read by AI
Static styleguides drift, and AI coding sessions make that drift loud. The structure we settled on for AI-ready design systems, and why each piece in it earned its place.
The five-tier structure of an AI-ready design system
A five-tier structure and a spec format that let an AI tool read your whole design system in one pass: foundations, tokens, atoms, molecules, organisms.
Audit before you scaffold: meeting projects where they are
Most design systems aren't greenfield. The read-only audit step that saves a week of cleanup before you scaffold into an existing codebase.
Wiring design tokens through Tailwind v4 (Nuxt and Next)
How to wire design tokens through Tailwind v4 with tokens.css and @theme in Nuxt and Next, why @import fails, and how to verify the served CSS with curl.
Writing component specs an AI can actually use
How to write component specs an AI can use without re-reading the code: the format, the four-things quality bar, and good versus vague examples.
When the design system and the code disagree
Reconciling two drifting token sources surfaced a WCAG contrast bug. How to choose which truth wins when your design system and code disagree.
Turning a one-project pattern into a reusable Claude Code skill
How we packaged a one-project design-system pattern into a reusable Claude Code skill that audits, plans, confirms, and scaffolds any frontend codebase.