The design system is now a markdown file

For years, a big part of my job had a very specific shape: a Figma file, open all day, slowly turning into a cathedral. The design system. Every button, every input, every card — a component. Variants for each state. Auto-layout tuned so nothing broke when the text got longer. Tokens for color and spacing and type, named and documented so the whole thing stayed coherent. It was meticulous work, and I loved it. There's a real satisfaction in a system where everything has a place.

I'd spend hours making it right. Not just usable — polished. The kind of file another designer could open and immediately understand. Everything organized, everything maintained, everything mine.

The wall the system never crossed

Here's the part nobody puts on the portfolio: a lot of that care never made it into the product. I'd hand off the pristine system, and somewhere on the other side of the wall it would quietly come apart. The spacing that was exactly 16 became “close enough.” The component I'd built with six carefully considered states shipped with two. The hover I sweated over didn't exist, because there was no line in the design that forced it to.

It wasn't anyone's fault, really. The design system lived in one language — visual, spatial, arranged on a canvas — and the product lived in another. Every handoff was a translation, and translations lose things. I was maintaining a beautiful description of a thing that only half-existed where it actually mattered.

Then the system stopped being a canvas

Now my design system is a markdown file.

Not a Figma library. A text file. A handful of headings and bullet points that describe how things should look and behave — the spacing scale, the color roles, the way a primary button differs from a secondary one, what “quiet” and “loud” mean in this product. Instructions, written in plain language, that the tools I build with can actually read and act on.

The first time I really sat with that, it stopped me. The most visual artifact I made — the one thing that was all shape and color and space — had turned into prose. The visual language became a written one. And somehow it works better.

Why the text version is stronger

It sounds like a downgrade — trading a rich, pixel-perfect canvas for a text file. It isn't. A few things flipped:

The description is the implementation. There's no handoff to lose things in anymore. When the system says buttons use the same spacing scale, that instruction goes straight into the code. The gap between “what I meant” and “what shipped” — the gap I spent my whole career fighting — mostly closed.
Intent survives better as words than as pixels. A rectangle on a canvas shows you a result but not the rule behind it. A sentence — “destructive actions are never the default, and always ask before they act” — carries the reasoning, so it holds up in the fifty screens I never drew.
It's alive. A Figma system decays the moment you stop tending it. A markdown system is small enough to keep true, close enough to the code that drift shows up immediately, and cheap enough to change that I actually keep it honest.

What's really going on

I keep coming back to how strange this is. Design has always been a visual discipline — that's the whole identity of the job. And yet the most leverage I have right now comes from writing the system down in words and letting those words become the product.

I don't think this means the visual craft is going away. Taste still decides which rule is the right rule, and you can only write a good system if you can see the good version in your head first. But the container changed. The design system used to be a thing you looked at. Now it's a thing you read — and, more importantly, a thing the machine reads with you.

Years of building cathedrals in Figma, and it turns out the most durable version of a design system is a text file. The visual language became a written one, and the work is closer to the product than it's ever been.

Same hands draw the screen. Now they mostly write it down.