Design system as a markdown

Product development is evolving at a faster pace than I could imagine. As a designer, the focus is moving away from the process. It’s now more about iteration and experimentation. You move back and forth between design and code. It's about how fast you can prototype, get to customers, and get feedback. Every designer is evolving into a generalist over time. Everyone is building.

LLMs work great when they have enough context. While designing, Figma's MCP acts as a perfect design context. LLMs can see your artifact in a structured format (of course, you have to name your layers and auto-layout). Without that, LLMs will create colors, fonts, and spacing that almost match your brand. But they may look messy. That's where design systems come in.

Design systems have been the source of truth for product teams and now it's time to provide that context to LLMs. The best way to do it is to have it as a markdown file. If you have been following the AI news, you already know how everything is a markdown file and how useful they are. At Citrix, I created markdown files for designers and PMs. They use them to develop prototypes. We saw a ~10x improvement in output quality with our prototypes. To be honest, we do not have an enriched design system, but here's what worked (we use Claude Code):

I wrote two markdown (.md) files that work together: claude.md and design.md. claude.md holds the token rules. It opens with a hard instruction that reads design.md before writing any UI code. Then it defines a three-layer token architecture:

• Primitives (Layer 1)

  Raw values like --color-teal-700 or --font-size-m. I instructed to never use this directly.

• Semantics (Layer 2)

  Contextual tokens like var(--color-content-brand). I instructed to always use these; they handle light and dark mode automatically.

• Components (Layer 3)

  Unique overrides for complex components, created using only Layer 2 tokens.

The golden rule: No hardcoded values. No hex codes. No pixel values for spacing. No raw font sizes. Anything that is a visual value, has a token for it.

/* Wrong */
background: #FFFFFF;
padding: 16px;
border-radius: 8px;
 
/* Right */
background: var(--color-surface-l1);
padding: var(--space-16);
border-radius: var(--border-radius-m);

design.md holds our components. It lists every component in our code library with imports and intended use. Before building anything custom, the LLM checks this list. If our library has it, it uses it. It only reaches for custom tokens when the library has nothing close.

You need your design tokens configured to do this. If you don't have them set up yet, take a screenshot of your variables in Figma, send it to any AI, and ask it to create a .json file for your primitives and semantics.

For components, I got help from our engineering team to add the component library as a dependency.

You don't need a perfect system to try this. You can start with a single design.md or claude.md and keep the instructions plain. Export whatever tokens you have. Write a short list of usage rules – what layer to use, what's forbidden, and what to check before building custom components. Add a component reference even if it's incomplete.

Design systems were always meant to scale decisions. Markdown extends that to AI.