Design.md: A format spec for describing a visual identity to coding agents

Interestingly I have gone the opposite direction and decided that design does not belong in long lived artifacts or docs.

I went down quite a rabbit hole experimenting with what I call “specsmaxxing” (wrote about it too, see my post history).

My first reaction is that everything I see defined here in DESIGN.md is already codified in my actual themes configs, or component files.

I understand what they want to achieve, as LLMs almost never get design right on the first shot, and very often they ship something that is functionally to-spec but still visually unshippable.

The thing is, you can hand-implement a feature exactly as defined in the most well-prepared design briefs and mocks, and still find something worth changing as soon as you play with the working version. You might not appreciate how fluid layout and styles and themes can be, until you try speccing them out (and later finding yourself updating the spec to chase the product). IMO trying to codify design rigidly and prescriptively in docs is going to slow you down more than it’s worth.

Maybe there is more value for teams trying to align design across dozens or hundreds of products though?

When it comes to acceptance criteria though I am fully on-board. We need to be writing requirements down and tracking them atomically through implementation and QA, and maintain them in long lived feature requirements docs. Yaml is great for this. I built some tools that help me do that in a very productive way already.

But how is DESIGN.md to play nicely with eg Figma Design Tokens, or tailwind.config.js? Is it to become the source-of-truth, or simply point to those--in which case how, besides deterministic validation, does it differ from AGENTS.md? Scope? If the future of agentic coding is the orchestration of discrete, focused sub-agents, I expect something like DESIGN.md to show up as .agents/designer/SOUL.md.

Very useful. Stealing it.