Problem:

Design systems are documented for humans (Figma, Storybook, style guides), but engineers increasingly build with AI coding agents that never open those tools — they read files. Without a machine-readable layer, agents hallucinate token names (bg-primary instead of color.bg.primary), duplicate near-identical tokens, and pick the wrong component for the context (e.g., a raw-styled banner instead of AlertBanner with the correct role=alert) — because the judgment behind the system (why Dialog vs Sheet, why danger variant here not there) was never written down anywhere an agent could reach. All the small decisions a designer usually makes without thinking about it just isn’t there for an AI to find.

Solution:

I am trying to explore a small set of files that basically explain the design system to the AI, in a language it can actually use. Not just "here are our colors," but the reasoning behind things — like "use a Dialog when someone needs to make a decision before moving on, but not for stuff that doesn't block them, use a Sheet instead." It's organized so the AI only pulls in the info it needs for the task at hand, instead of drowning in every rule at once. End result: when someone prompts an AI to build something, it already knows how our system works — same as if a designer had reviewed it.