{"slug": "sometimes-a-design-md-is-not-enough", "title": "Sometimes a DESIGN.md Is Not Enough", "summary": "A developer created web-reverse-engineer, a portable SKILL.md workflow that extracts design and motion principles from running web pages to guide AI coding agents. The tool captures runtime behavior like animation timing and interaction logic, which static DESIGN.md files miss, and outputs structured observations for agents to rebuild original implementations without copying source code. The project emphasizes that only humans can verify whether rebuilt animations feel right, as build passing does not guarantee demo passing.", "body_md": "What DESIGN.md can't tell your coding agent - and how to extract it anyway.\n\nEvery 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.\n\nBut open the sites that actually make people stop scrolling, and the thing you notice first is never in that file.\n\nIt'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\n\nmarkup.\n\nThat gap is what web-reverse-engineer is for.\n\nThe current AI-coding stack has gotten good at two things:\n\nWhat'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.\n\nweb-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.\n\nThat distinction matters enough that it's the first rule of the project, not a footnote.\n\nThe 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.\n\nIn short:\n\nThree small demos made this concrete:\n\nEach 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.\n\nHere's the honest part: even with good extraction, there's a step no agent gets to skip past on its own.\n\nThe 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.\n\nThat'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.\n\nweb-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:\n\n```\nnpm install web-reverse-engineer\n```\n\nLive demos, the clean-room notes behind each one, and the skill itself are all in the repo, or see it running live.\n\nIf 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?", "url": "https://wpnews.pro/news/sometimes-a-design-md-is-not-enough", "canonical_source": "https://dev.to/uypoko/sometimes-a-designmd-is-not-enough-48l2", "published_at": "2026-07-09 05:24:42+00:00", "updated_at": "2026-07-09 05:42:26.780576+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools", "generative-ai"], "entities": ["web-reverse-engineer", "Claude Code", "Codex", "Cursor", "Gemini CLI"], "alternates": {"html": "https://wpnews.pro/news/sometimes-a-design-md-is-not-enough", "markdown": "https://wpnews.pro/news/sometimes-a-design-md-is-not-enough.md", "text": "https://wpnews.pro/news/sometimes-a-design-md-is-not-enough.txt", "jsonld": "https://wpnews.pro/news/sometimes-a-design-md-is-not-enough.jsonld"}}