Sometimes a DESIGN.md Is Not Enough

What DESIGN.md can't tell your coding agent - and how to extract it anyway.

Every AI coding agent today can read a DESIGN.md. Colors, spacing tokens, typography scale, component variants - drop that file into a repo and Claude Code, Codex, Cursor, or Gemini CLI will follow it faithfully. It's become the standard way to hand a coding agent a design system and expect consistent output.

But open the sites that actually make people stop scrolling, and the thing you notice first is never in that file.

It's the way a hero canvas breathes when nothing is happening. The way a row of elements tilts toward your cursor before you've consciously registered it moved. The pacing of a scroll-triggered reveal - not just that it animates, but how it accelerates and settles. None of that lives in a token file. It lives in the running page, and it disappears the moment you only read the

markup.