Sometimes a DESIGN.md Is Not Enough

Cung Dinh Uy — Thu, 09 Jul 2026 05:24:42 +0000

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.

That gap is what web-reverse-engineer is for.

The layer nobody's filling

The current AI-coding stack has gotten good at two things:

DESIGN.md gives an agent static design direction - palette, type, layout rules.
SKILL.md / Agent Skills give an agent a reusable workflow - a repeatable way of doing a task.
Coding agents (Claude Code, Codex, Cursor, Gemini CLI) handle implementation once they have direction.

What's missing is the step before any of that: actually studying a reference site's runtime behavior - its motion, its interaction logic, its animation timing, and turning that observation into something an agent can build from. Screenshots don't capture motion. A design token file doesn't capture how an SVG eye rotates to track a cursor using real pointer math. That knowledge only exists while the page is running, and most workflows never bother to extract it before code gets written.

web-reverse-engineer is a portable SKILL.md workflow that does exactly that: inspect a public reference, extract the design and motion principles behind it, and hand a coding agent enough structured observation to rebuild an original implementation - not a copy of what it saw.

Not a website copier

That distinction matters enough that it's the first rule of the project, not a footnote.

The workflow never touches proprietary source code, minified bundles, shader strings, stylesheets, or media assets from the reference site. It doesn't reproduce exact layout or exact animation timing. What it does extract is the principle - the class of motion, the interaction pattern, the structural idea - and every line of code in the rebuild is written fresh, in a different brand, different palette, different copy, re-tuned animation velocity.

In short:

Studies runtime behavior, not source code.
Extracts design principles, not assets.
Guides an original implementation, not a duplicate.
Ships as a portable SKILL.md your agent can reuse on the next reference site, not a one-off script.

What it looks like in practice

Three small demos made this concrete:

A reference-inspired dark, whole-page build where ambient canvas motion runs continuously in the background - the kind of animation you only notice because the page feels alive, not because anything is pointing at it.
A light, section-specific rebuild centered on a single micro-interaction: an SVG eye that tracks the cursor, rotating and scaling based on real pointer coordinates. Getting that to feel natural meant working out the interaction math from scratch, not eyeballing a CSS transform.
A light hero built around a Canvas 2D sine-wave animation - procedural motion that has to be derived, not lifted, because there's no source to copy from in the first place.

Each one started as observation - measuring the running page, writing down what it was actually doing - before a single line of the rebuild got written. Look first, build second.

The part an agent still can't certify

Here's the honest part: even with good extraction, there's a step no agent gets to skip past on its own.

The bar for whether a rebuilt animation actually works is simple to state and hard to automate: if a normal person watching for three seconds doesn't notice the motion, the demo failed, regardless of whether the build compiled, lint passed, and the code looked right. "Build passing" and "demo passing" turned out to be two different claims, and only a human can actually confirm the second one. The workflow leans into that instead of pretending otherwise: it captures evidence - screenshots, frame sequences - precisely so a person can make that call, rather than letting an agent self-certify something it fundamentally can't perceive.

That's a small detail, but it's the kind of thing that only shows up once you've actually tried to automate this instead of just writing a spec for it.

Try it

web-reverse-engineer installs as a standard package and drops a portable SKILL.md into your project for your coding agent to use on the next site you want to learn from:

npm install web-reverse-engineer

Live demos, the clean-room notes behind each one, and the skill itself are all in the repo, or see it running live.

If you're already handing your coding agent a DESIGN.md, screenshots, Cursor rules, or a custom skill to carry design context, I'd genuinely like to know what that setup looks like for you. What's the layer you built to cover the gap DESIGN.md leaves open?