Design Dna Skill for Claude

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 <style>", "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)

• 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.
• 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.
• 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.
• Ratios, not values. "The headline is 96px" is nearly worthless. "The headline is 8x the body, never under 6x" is the identity.
• Coverage, not just colour. The same three hex codes at 60/30/10 and at 90/8/2 are two unrelated designs.
• Percentages, not pixels, in everything spatial. One spec has to drive a 1080x1350 carousel and a 1920x1080 slide with no rewrite.
• 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.
• One skill per style. Never merge two identities into one spec. The average of two good designs is a bad design.
• 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:

• The reference image, attached and named first
• soul.one_line
• The weird move, alone, unmissable
• The 3-9 signature moves, as ratios
• The bans, as absolutes
• Palette and type: roles and coverage only, never a full ramp
• Archetype names and when to use each
• 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

• 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.
• 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.
• Build. For web, hand the build to ../nextjs/SKILL.md and the words to ../marketing/SKILL.md; the identity stays here.
• Run the self-check, name each test and its result, repair and re-run on any failure.
• 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.