Design DNA - one beautiful design into a permanent skill

A design loop finds you one beautiful thing. This turns that one thing into a skill you keep forever, so you can make more of it, in any format, without the look drifting.

Not only about "designs". The subject is anything that got built: a website, a landing page, a poster, a motion graphic, a carousel, a deck. Same system, same file, same tests. The format is an output, not the subject.

The problem this solves

Nobody wrote down why the winner was beautiful. Next time you ask for "the same style" you get something close, then something a bit off, then something generic. Every rule you do not write down, the model has to guess, and it does not guess randomly: it guesses the average of everything it has ever seen. That average is what people call slop. Slop is the sound of an unwritten rule.

Two modes

You say	Mode	What happens
"codify this", "turn this into a skill", here is the winner	CAPTURE	Run the seven steps below. Output: a new style skill folder.
"build X in ", "another one like the last", /<slug>	REUSE	Load that style's PROMPT.md only, build, then run its self-check before returning.

If a dna.json already exists for the style named, you are in REUSE. Never re-derive a style that has a record.

To find out which records exist — in either scope, without guessing at paths — run npx @ericrisco/rsc doctor --json and read designStartingPoint. A record it reports as unreadable is not a record you can reuse: say what is missing, do not use half of one.

Hard rules (these are the skill)

1. A specification that cannot fail is not a specification. If every rule you wrote is one a bad output could still satisfy, you wrote a mood board.
2. Compile, do not paste. Two files, always. dna.json is the record, any size, and it never enters a prompt. PROMPT.md is the payload, hard cap 2KB, and it is the only thing that does.
3. Always attach the reference image. Highest-leverage move available and close to free: image conditioning runs on its own pathway, so it does not eat the attention your words are competing for.
4. Ratios, not values. "The headline is 96px" is nearly worthless. "The headline is 8x the body, never under 6x" is the identity.
5. Coverage, not just colour. The same three hex codes at 60/30/10 and at 90/8/2 are two unrelated designs.
6. Percentages, not pixels, in everything spatial. One spec has to drive a 1080x1350 carousel and a 1920x1080 slide with no rewrite.
7. When output looks generic, add a ban, not a rule. A positive instruction is one weak vote against a landslide; "never centre the hero" deletes the landslide from the options. Bans should outnumber positive style rules.
8. One skill per style. Never merge two identities into one spec. The average of two good designs is a bad design.
9. Reproduce the system, never the marks. Real logos, wordmarks, licensed photographs and proprietary typefaces go in meta.not_copied with a named substitute.
10. Step 5 is not optional. A spec that has never been used to rebuild its own source has never been tested.

CAPTURE - the seven steps

Run PROMPT.md as written. It is the operative artefact and it is self-contained; this section is the map, not a second copy of it.

Step	Name	Non-negotiable output
1	Observe	Flat inventory of literal measurements. Sampled hexes, coverage estimates, type counts, largest-to-smallest ratio, margins as percentages, texture, and what is absent. No judgements: interpreting here is how you end up specifying a design that is not the one in front of you.
2	Debate	Loop A argues exhaustive, Loop B argues nine moves and a wall of refusals, then adjudicate each property with one question: if I changed this value, would it stop looking like the reference? Yes is load-bearing, no is trivia, and trivia dilutes attention. Resolve it by splitting documents, not by compromising.
3	Codify	dna.json against design-dna.schema.json. Descriptive colour names ("dusty plum", never "accent-500": image and video models cannot read token names). Every family gets a fallback.
4	Tests that can fail	8 to 12, binary and measurable, each marked auto or human.
5	Reconstruct and diff	Close the reference. Rebuild it from dna.json alone. Put them side by side and list every difference: each one is a field the spec forgot. Fold them in, record them in reconstruction.gaps_found, go again. Expect two or three passes, and expect the gaps to be things you were sure were obvious.
6	Emit the skill	The folder below.
7	Declare uncertainty	Every value inferred rather than measured, and every rule under 70% confidence, into meta.confidence_notes. That is where the style drifts first.

What gets emitted

~/.claude/skills/<slug>/
  SKILL.md          how to use this style, and when not to
  PROMPT.md         the 2KB payload. THIS is what enters a context window
  dna.json          the full record. NEVER pasted into a prompt
  design-dna.schema.json -> validated against the parent copy
  reference/        the original, kept forever
  example/          one worked output, the canonical proof
  scripts/check.py  the auto tests, exits non-zero on failure

The record is the harness's design identity

The folder above makes the style reusable. Writing the record into the harness is what makes it this project's identity rather than a loose folder in a global directory:

• Write the record as an article under 02-DOCS/wiki/brand/, beside the brand study, and link it from 02-DOCS/wiki/index.md and the root CLAUDE.md ## Brand & voice section — the same convention design follows, and the same place marketing, presentations, brand-voice and content-engine already read.
• It does not replace the brand study. The study is the judgement and the direction — why this identity, what it refuses. The record is the measurable contract that can fail a test. They share only a few fields; each carries what the other cannot.
• One harness, one design identity. If a second appears, name the conflict. The average of two good designs is a bad design.
• A style captured before this convention still works from its folder. To bring it into the harness, write its record as the article above; nothing needs re-deriving.

rsc doctor reports whether this harness has an identity, so the rule is not just prose.

Scaffold from templates/ and validate before you claim it works:

python3 ~/.claude/skills/design-dna/scripts/emit.py <slug>            # scaffold + validate
python3 ~/.claude/skills/<slug>/scripts/check.py <output-file>        # run the auto tests

PROMPT.md ordering is fixed

Attention is strongest at the two ends and weakest in the middle, so the order is a mechanism, not a style choice:

1. The reference image, attached and named first
2. soul.one_line
3. The weird move, alone, unmissable
4. The 3-9 signature moves, as ratios
5. The bans, as absolutes
6. Palette and type: roles and coverage only, never a full ramp
7. Archetype names and when to use each
8. The self-check, last

Nothing else. If it does not change what the output looks like from three metres away, it belongs in dna.json. To add a tenth signature you must delete one.

Last line of every PROMPT.md, verbatim:

Before returning any output, run every test in the self-check. Name each test and its result. If any fails, repair the output and run them again. Never return output with a failing test and a note explaining it away.

REUSE - building with a captured style

1. Load only that style's PROMPT.md. Attach reference/. Do not read dna.json into context; read it only to answer a specific measured question or to regenerate the payload.
2. Pick an archetype by name before writing anything. Structure first: unnamed layouts are why piece 8 does not sit beside piece 1 as a set.
3. Build. For web, hand the build to ../nextjs/SKILL.md and the words to ../marketing/SKILL.md; the identity stays here.
4. Run the self-check, name each test and its result, repair and re-run on any failure.
5. If output drifts, do not add a rule. Consult the table below.

When it goes wrong

What you see	Cause	Fix
Matches every value, still looks generic	Signature moves missing, or too many	Cut to 3-9, rewrite each as a ratio
Drifts back to the stock AI look	Not enough bans	Bans should outnumber positive style rules
Piece 1 and piece 8 do not match	No named layouts	Add archetypes
The accent reads as a theme, not an accent	No coverage percentages	Add them
Works on a slide, breaks on a carousel	Pixel values in the spacing	Convert to percentages
Obeys some rules, ignores others, differently each run	Payload over the cap	Cut to 2KB
Your best rule keeps getting ignored	It is buried in the middle	Move it to the top or the bottom
Fine, but forgettable	No weird move	Find the one break in the system
Spec feels complete, output is wrong	You skipped Step 5	Rebuild the original from the spec. Compare.

Styles captured so far

Style	Reads as	Weird move
../cold-press/SKILL.md	newsprint editorial, serif at 8x, one vermilion	section numeral clipped by the right edge
../night-shift/SKILL.md	near-black instrument panel, one phosphor green	status ribbon severed mid-word by the right edge
../soft-optics/SKILL.md	warm paper, lowercase display at 6x, one olive	display line crossing a tinted plate's bottom edge

Each is a finished skill: reference, dna.json, a capped payload, a worked proof, and tests that exit non-zero. Never merge two of them: the average of two good designs is a bad design.

Hand-offs

• No winner yet, no reference to measure -> ../design-loop/SKILL.md first: it takes a real reference and converges on a piece that beats it. Come back with the winner. Capturing an average of several candidates produces the average, which is the thing you are trying to escape.
• The words on the page -> ../marketing/SKILL.md. voice in dna.json constrains them; it does not write them.
• The build -> ../nextjs/SKILL.md (App Router, React 19) or ../react/SKILL.md (Vite SPA).
• SDD gate. Capturing a style writes a skill, not product code, so it needs no spec. The moment its output becomes a new feature or a non-trivial behaviour change in a real app, ../specify/SKILL.md runs first.

Files

File	What it is
PROMPT.md	The standalone prompt. Paste anywhere, attach the design, done.
design-dna.schema.json	Every field of dna.json, explained.
scripts/emit.py	Scaffolds and validates an emitted style skill.
templates/	SKILL.md, PROMPT.md and check.py skeletons for the emitted skill.
references/method.md	The full method and the research each decision traces to. Read once, not per run.

Why any of this works is not opinion: lost-in-the-middle recovery, instruction-compliance decay under constraint count, style being formally the correlation between features rather than the features, and decoupled image cross-attention. The citations are in references/method.md.