design.md or a design skill? Where your brand guidance should live

Vercel recently wrote about design.md, a single public file that any agent can load so that generated pages come out looking like Vercel. It’s a genuinely good read, and the eval loop behind it (fixed scenarios, blind comparisons, corrections encoded as rules) is the most rigorous public write-up of design guidance for agents I’ve seen.

It’s also worth being precise about which problem it solves, because it’s probably not yours.

---

Two different rooms

Vercel already had in-repo guidance: a skill called product-design that lives in each repository next to the components it describes. Their post is clear about why it works: an agent reading it is surrounded by real components and shipped examples of the things it describes.

design.md exists for everything that happens outside those repositories. Reports, proposals, one-off pages built in v0 or a Slack bot, tools that can’t see the codebase at all. Out there, the agent has no components to look at, so Vercel distilled the visual language into one public file and paired it with a public stylesheet, then spent two hundred eval runs making the words survive without the code.

So the honest summary is: in-repo guidance first, and design.md as the export format for rooms the repo can’t reach.

---

Inside the repo, proximity wins

If the work happens in your codebase, the in-repo skill is the stronger tool, and Vercel’s own findings explain why. Their first attempt at design.md was porting the in-repo skill to a public prompt, and it failed: every model interpreted the prose differently, because the prose had lost the code that grounded it.

That grounding is the whole trick. A skill that says “use the Button component’s lg variant” sits next to a real Button with a real lg variant the agent can open. Nothing needs to survive translation into brand-speak, because the referent is right there. This is why every Lexington theme ships a design skill extracted from that theme’s actual code rather than a style guide written about it: descriptions drift, extractions can be checked.

The eval discipline from Vercel’s post transfers, though, and it’s the part I’d steal for any project: keep the corrections you find yourself repeating, encode each one as something observable (“evidence tables use the full available width”), and prefer a constraint the agent can check over an adjective it has to interpret.

---

One more consideration: public means public

design.md works because it’s one URL anyone can load. That’s the right shape for Vercel: their brand guidance getting used widely costs them nothing and spreads the brand.

If your design system is the product, the calculus flips. Publishing a distilled, agent-ready description of a theme’s typography, tokens, and composition at a public URL is publishing the theme’s recipe. For Lexington that would mean anyone can point v0 at the file and generate look-alikes without ever buying the theme whose look it describes. The in-repo skill has the opposite property: it ships with the purchase, next to the code it describes, to the people it’s for.

So the placement question has a business answer as well as a technical one. Public file for guidance you want the world to use; in-repo skill for guidance that’s part of what you sell.

---

The short version

• Work happens in the codebase? In-repo skill. Proximity to real components beats any amount of prose, and Vercel’s own experiments back that up.
• Artifacts get made outside the codebase, in tools that can’t read files? That’s the design.md problem. Expect to invest in evals; the file only got good because they measured it.
• Either way, write constraints, not vibes. “Never use a raw Tailwind palette color, only tokens from colors.css” changes agent output. “Keep it minimal” does not.

I wrote about how the per-theme design skills are built in the design skill that keeps AI pages on-brand, and the full extraction method is chapter 2 of Making Your Codebase AI-Ready.