Design Dna

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

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.

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

Styles captured so far

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

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.