design-dna reads a screenshot, writes a token file, then rebuilds the UI

Why a screenshot has to become a token file first

design-dna exists to turn a request nobody can pin down into a file two machines can read. The framing is blunt about the problem: teams ask an agent to make a build look like some site, and the result changes with the wording of the prompt. This project's answer is to extract visual identity into a structured JSON profile first, then generate from that profile, so the same reference produces the same output twice.

The profile covers three dimensions. Design System holds measurable tokens: colour, typography, spacing, layout, shape, elevation, motion, components. Design Style holds perception: mood, visual language, composition, imagery, interaction feel, brand voice. Visual Effects holds what plain CSS cannot express, listed as Canvas, WebGL, 3D, particles, shaders, scroll-driven motion, cursor effects, SVG animation and glassmorphism.

That third dimension is the one most token pipelines leave out, and it is where a generated page most often looks thin beside its reference. Keeping all three inside one artifact is the point. The JSON can be committed to version control, shared across teams, reused across projects and refined, so a visual decision gets reviewed like a variable instead of re-argued in a chat thread.

The audience is anyone already driving an agent. The compatibility list names Cursor, Claude Code, Codex and GitHub Copilot, plus 39 more agents reachable through the vercel-labs skills CLI.

Structure, Analyze, Generate, and the arrow that leaves the pipeline

The skill is organised as 3 phases. Structure surfaces the full schema and field meanings from `references/schema.md`, so the agent knows what a complete profile looks like before it writes one. Analyze takes screenshots, images or URLs and emits a filled JSON profile. Generate takes that profile plus your content and produces an implementation, defaulting to a self-contained HTML/CSS/JS file, and following `references/generation-guide.md`.

Two structural details matter more than the list itself. First, the phases are not a mandatory chain: each can be used alone, or chained as Analyze then Generate, so a team that already owns a token file never has to run the vision step. Second, the pipeline diagram draws a dashed arrow from the JSON node to a save, reuse and version control node, set apart from the two solid arrows that stand for analysis and generation. Reuse sits deliberately outside the transform, which matches how the artifact is described: something you keep, not something the skill re-derives on every run.

Structure is the odd phase out, because it transforms nothing. It reads the schema and reports it back. For a pure extraction job you can start at Analyze, and no rule states that Structure has to run first.

Installing through the skills CLI, one agent at a time

The prerequisites are a Node.js environment and the ability to run npx commands. That is all, and the quick install is a single line:

npx skills add zanwei/design-dna

The agent-specific form pins the target and the scope. The -a flag selects the agent, -g installs globally, and -y skips the interactive prompt, which is what you want in CI:

# Cursor only, non-interactive, global install
npx skills add zanwei/design-dna -a cursor -g -y

# Claude Code only
npx skills add zanwei/design-dna -a claude-code -g -y

If you would rather read the files before an agent loads them, clone and point the installer at the directory:

git clone https://github.com/zanwei/design-dna.git
npx skills add ./design-dna -y

The same installer enumerates what a package offers:

npx skills add zanwei/design-dna --list

Nothing lands in your package.json. There is no library to import and no runtime dependency to bump: this is a skill directory, loaded as instructions by whichever agent reads it. Your build gains no import that can break, and no hook to inspect when the skill behaves oddly.

Two Node scripts that measure what the model gets wrong

The project carries 2 optional Node scripts that turn colour judgement into arithmetic. The stated reason is specific: LLM colour perception drifts toward familiar palette defaults, and a brand pink like `#ff90e8` gets read as `#ec4899`, a difference the README puts at ΔE ≈ 29.

`measure-colors.mjs` runs deterministic k-means clustering over the actual pixels of an image file and merges anti-aliasing noise perceptually, then prints exact hexes, coverage as `0..1` fractions, background, text and accent roles, and the clustering k it settled on.

`verify.mjs` reads that k back out of the saved file, re-measures a screenshot of the generated page, and reports per-colour ΔE and coverage drift with PASS/FAIL thresholds, handing the agent a signal to correct against instead of asking you to compare two images by eye.

Run both from the root of a local clone, after one install step the prerequisites never mention:

npm install --prefix ./scripts

# Analyze: measure the exact palette from a reference screenshot
node scripts/measure-colors.mjs reference.png > measured-colors.json

# Generate: score the implementation screenshot against the reference
node scripts/verify.mjs implementation.png measured-colors.json

No API keys are required, because the measurement reads pixels you already have instead of calling a model. The skill instructs agents to run both automatically when the references are image files.

Same agent, same hero, two different background colours

The repository's own comparison rebuilds the bun.sh hero twice from one reference with the same agent. The measured rebuild passes with a mean ΔE of 0.87. The perceived rebuild fails with a mean ΔE of 9.54, because the near-black background slid to `#000000` and the brand pink slid to `#ec4899`, the familiar palette default named a few paragraphs earlier. Same process, same model, different colour source.

Read that next to the Analyze phase, which is described as emitting a complete, quantified profile with no empty fields and no guesswork, and a contradiction appears. The schema is complete in the sense that every field is filled, but the values inside those fields are model perception, and the same README puts that perception's error at ΔE ≈ 29 on the exact colour at issue. Completeness of shape is not accuracy of number.

The caption of that comparison claims the measured rebuild reproduces every token while reporting a mean ΔE of 0.87 in the same line, and 0.87 is not zero. What the mean averages over is never stated. A second silence sits right beside it: `verify.mjs` reports PASS/FAIL thresholds, but the threshold values are never printed, so you cannot tell where the bar sits between 0.87 and 9.54, only that these two examples land on opposite sides of it.

URL references never reach the clustering step

Step 1 of the workflow invites you to collect live URLs alongside screenshots, and the Analyze phase counts URLs as valid input. The measurement path does not follow it there. `measure-colors.mjs` takes a file path, its example argument ends in .png, and the skill is told to use both scripts automatically only when references are image files. For a URL, no fetch step, headless screenshot step or conversion into pixels is documented, and the scripts need no API keys precisely because they never leave the filesystem.

So the deterministic guarantee covers the image half of the documented input set. A URL-only workflow stays on the perception path, the same path that slid a near-black background to pure black in the bun.sh example. The remedy offered for thin results is a polish iteration that re-attaches the same URLs or screenshots and asks the agent to audit hierarchy, ornamentation, typographic rhythm, motion and materiality against the reference. That is a prompt, not a measurement, so it produces no number and no PASS or FAIL.

A third gap sits in the same area. `references/schema.md` and `references/generation-guide.md` are named as the schema and the generation rulebook, and they are the only entries under `references/` the README points to, so the field list, the required visual effect vocabulary and the output contract live outside anything the README itself carries.

Prerequisites, clones, and six translations of one skill

The prerequisites list stops at Node.js and npx, yet the deterministic path adds an install step, `npm install --prefix ./scripts`, that has to run from the root of a clone. Two rules for the same 2 files follow from that split. On the manual path you own the clone and invoke the scripts yourself. On the skill path the agent resolves them from the absolute directory containing the loaded `SKILL.md`, which is why you do not need a `scripts/` directory in your project root.

The repository is MIT licensed, publishes no GitHub releases, and its last push was on 2026-08-28, so an upgrade is a fresh install plus a diff rather than a version bump.

The README also ships in 6 languages, with `README.zh-CN.md`, `README.zh-TW.md`, `README.ja.md`, `README.ko.md` and `README.es.md` beside the English one, while the skill itself is a single `SKILL.md` plus a `docs/` folder. The contribution rule asks for `SKILL.md` and the affected files under `references/` to move together when behaviour changes, and says nothing about the translations. A reader working from a translation is reading a file nobody is required to refresh.

Hand-written DNA as the slower, more attributable alternative

Because the phases can run alone, the real alternative is to skip the vision step entirely: write the Design DNA JSON yourself against `references/schema.md`, then use only the Generate phase. Nothing on that path inherits the `#ff90e8` to `#ec4899` drift, because nothing guesses at a hex value.

The difference in approach decides where the error lives. Extraction is fast, and its mistakes stay invisible until a colour happens to matter. Hand-authoring is slow, and every field has a person attached to it, which counts most when the reference site quietly changes its brand pink and your committed file does not. What you lose first is the Visual Effects layer, since Canvas, WebGL, particle and scroll-driven behaviour is exactly what a live reference demonstrates and a hand-written spec omits.

A third option sits between them: run Analyze with image references so the measurement scripts apply, commit the resulting JSON, and treat Generate as a repeatable step over your own content. That is the workflow the save and version control arrow in the pipeline diagram describes.

Editorial conclusion

Adopt design-dna if your team already drives Cursor, Claude Code, Codex or GitHub Copilot and keeps losing hours to subjective handoff notes. Skip it if you need deterministic token output today, because colour error enters at the extraction step and the README never prints the PASS/FAIL values that would catch it. First check: run measure-colors.mjs over one reference you already trust, read the k it records, then decide whether the Visual Effects layer earns its place in a build your team maintains.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. zanwei/design-dna on GitHub