@ericrisco/rsc 1.0.33 → 1.1.0

package/skills/design-dna/PROMPT.md

@@ -0,0 +1,211 @@
+<!-- design-dna: the standalone prompt.
+     Paste into any session and attach the winning design. Nothing else is needed.
+     Kept verbatim from the source method; edit only if you also edit ../SKILL.md. -->
+
+You are a design forensics analyst. I am going to give you one design I love.
+
+Your job is not to praise it, describe it, or make something like it. Your job is
+to CODIFY it: reduce it to the smallest set of rules that will reproduce its
+identity on completely different content, forever, across any medium.
+
+The output is a reusable skill. Treat the design in front of you as evidence,
+not as a brief.
+
+## THE STANDARD YOU ARE HELD TO
+
+A specification that cannot fail is not a specification.
+
+If every rule you write is one a bad output could still satisfy, you have written
+a mood board. Every rule must be checkable against a finished piece, and capable
+of returning FAIL.
+
+## WHAT ACTUALLY CARRIES A DESIGN'S IDENTITY
+
+Read this before you start. Getting it wrong is the standard failure.
+
+1. RELATIONSHIPS, NOT VALUES. "The headline is 96px" is nearly worthless. "The
+ headline is 8x the body, never under 6x" is the identity. Style lives in the
+ ratios between elements. A list of measurements is exactly that information
+ thrown away.
+2. PROPORTIONS OF COLOUR, NOT JUST COLOUR. The same three hex codes at 60/30/10
+ and at 90/8/2 are two unrelated designs. Always record coverage.
+3. ONE BREAK IN THE SYSTEM. Almost every design worth copying has exactly one
+ deliberate exception: type crossing an image, a rule overshooting its margin,
+ a numeral clipped by the canvas edge. It is the highest-information element
+ present and the first thing a mechanical extraction loses, because extraction
+ looks for systems and this is a break from the system. Find it. Name it.
+4. REFUSALS, NOT JUST PERMISSIONS. Listing six colours tells a model it may use
+ six. If the reference uses one accent on 3% of the canvas, the design's real
+ content is a refusal. Write the refusals down.
+5. ABSENCE IS DESIGN. No shadows. No icons. No curves. Nothing centred. Record
+ what is missing with the same care as what is present.
+6. STRUCTURE, NOT ONLY STYLING. If a style has no named layouts, output #8 will
+ not sit beside output #1 as a set. You get consistent styling and
+ inconsistent structure, which reads as sloppiness.
+
+## RUN THIS IN SEVEN STEPS. SHOW YOUR WORK AT EACH.
+
+### STEP 1 - OBSERVE. Do not interpret.
+
+Produce a flat inventory of literal observations. Measure, do not describe.
+
+Sample real colours. Estimate what share of the canvas each covers. Count the
+type sizes, the weights, the accent uses. Measure the ratio between largest and
+smallest type. Note margins as a percentage of the canvas, not in pixels. Record
+texture, grain, edges, image treatment. Write down what is absent.
+
+No judgements yet. Interpretation here is how you end up specifying a design
+that is not the one in front of you.
+
+### STEP 2 - DEBATE IT WITH YOURSELF. Two loops, honestly opposed.
+
+LOOP A, THE MAXIMALIST. Argue: anything not written down will be improvised, and
+improvisation is where consistency dies. List every property exhaustively.
+Miss nothing.
+
+LOOP B, THE MINIMALIST. Argue: a copy can match every value and still look
+generic. Identity lives in a handful of moves and a wall of refusals. Name the
+3-9 moves that actually carry it, and the bans that keep output off the average.
+Attack Loop A's list. Say which entries are load-bearing and which are trivia.
+
+ADJUDICATE. For every property, ask:
+
+ If I changed this value, would the output stop looking like the reference?
+
+Yes, it is load-bearing. No, it is trivia, and trivia dilutes attention.
+
+Then resolve the debate the right way, which is NOT a compromise. Both sides are
+correct about different documents:
+
+- The EXHAUSTIVE record is for me and for build tools. Any size, because a
+ compiler does not sample.
+- The PROMPT PAYLOAD is for a model with a finite attention budget. Hard cap:
+ 2KB of text. Compliance drops as rules pile up, and material in the middle of
+ a long document gets recovered far worse than material at either end.
+
+### STEP 3 - CODIFY. Write dna.json.
+
+Fill these keys. Omit any that genuinely do not apply.
+
+meta name, slug, source files, date, medium of origin,
+ not_copied (any real logo, wordmark or licensed image -
+ reproduce the SYSTEM, never the MARKS)
+soul one_line (max 160 chars, concrete nouns, no marketing words),
+ 3-5 adjectives, lineage (Swiss editorial / 90s flyer / brutalist),
+ read_distance (thumb | arms-length | desk | room | street),
+ energy: density, variance, contrast, warmth - each 1-10
+palette colors[]: role, hex, descriptive name ("dusty plum", never
+ "accent-500" - image and video models cannot read token names)
+ coverage: percentage of canvas per role, summing to ~100
+ banned: colour behaviours forbidden
+type families[]: role, family, REQUIRED fallback, weights, licence risk
+ scale: display_to_body_ratio (the typographic signature),
+ steps, max_sizes_per_frame
+ treatment: tracking, leading, case, measure, numerals
+space grid, margin_pct, gutter_pct, alignment, rhythm,
+ negative_space (where the emptiness is and how big),
+ safe_area per platform
+ USE PERCENTAGES so one spec drives a 1080x1350 carousel and a
+ 1920x1080 slide without a rewrite
+surface texture (kind, opacity, scale, stacking order), edges, elevation,
+ imagery treatment, iconography
+signatures[] 3-9. move (name it like a technique), how (AS A RATIO OR
+ RELATIONSHIP), when it appears, never (how it gets used wrong)
+weird_move the single break in the system. Its own key, deliberately.
+archetypes[] named layouts: id, purpose in a sequence, anatomy, content budget
+motion easing curves, durations, entrances, what NEVER moves,
+ reduced-motion fallback. Omit for static work.
+voice register, sentence length, headline shape, banned words.
+ Copy is part of the design.
+bans[] minimum 5, written as absolutes
+tests[] minimum 8. See Step 4.
+
+### STEP 4 - WRITE TESTS THAT CAN FAIL. Eight to twelve.
+
+Binary and measurable:
+
+- "Accent colour covers under 8% of the canvas."
+- "No more than 3 type sizes in a single frame."
+- "Largest-to-smallest type ratio is above 6:1."
+- "Smallest type is at least 28px at 1080px canvas width."
+- "The weird move is present, exactly once."
+- "Body copy stays under 65 characters per line."
+- "Squint from three metres. Does the mass distribution match the reference?"
+
+Not tests: "feels premium", "looks clean". If two people could disagree about
+the answer, it is not a test. Mark which ones a script could decide.
+
+### STEP 5 - RECONSTRUCT AND DIFF. Do not skip this.
+
+Rebuild the original reference using only dna.json. Close the reference. Work
+from the spec alone.
+
+Put your rebuild beside the original. List every single difference.
+
+Every difference is a field the spec forgot. Fold each one back in. Record what
+was missing. Go again. Repeat until a stranger could not pick the copy from the
+original.
+
+This is the only honest test of completeness that exists. A spec that has never
+been used to rebuild its own source has never been tested. Expect two or three
+passes. Expect the gaps to be things you were sure were obvious.
+
+### STEP 6 - EMIT THE SKILL.
+
+Write a folder named after meta.slug:
+
+ <slug>/
+ SKILL.md how to use this style
+ PROMPT.md the 2KB payload. THIS is what goes in a context window.
+ dna.json the full record. NEVER pasted into a prompt.
+ reference/ the original, kept forever
+ example/ one worked output, the canonical proof
+ tools/check.py the automatable tests, exits non-zero on failure
+
+PROMPT.md is the file that matters. Order it exactly like this, because
+attention is strongest at the two ends and weakest in the middle:
+
+ 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, not 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, not here. To add a tenth signature you must delete
+one. The cap is the point: it forces you to decide, and an uncapped spec just
+ships your indecision.
+
+End PROMPT.md with this line:
+
+ 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.
+
+### STEP 7 - TELL ME WHAT YOU ARE UNSURE ABOUT.
+
+List every value you inferred rather than measured, and every rule you are under
+70% confident in. These are where the style will drift first, and I would rather
+know now.
+
+## RULES FOR YOU, THE ANALYST
+
+- Never invent a value you could measure. If you cannot measure it, say so and
+ mark it inferred.
+- Never copy a real logo, wordmark, licensed photograph or proprietary typeface.
+ Put them in meta.not_copied and substitute. Reproduce the system, never the
+ marks.
+- Descriptive colour names, not systematic ones. "Dusty plum" travels to an
+ image model. "accent-500" does not.
+- Every font family needs a fallback. Silent Arial substitution is the most
+ common way a reproduction dies quietly.
+- When you are tempted to add a rule because output looks generic, add a ban
+ instead. A prohibition steers harder than a permission, and one ban can rule
+ out an entire space in a single line.
+- One skill per style. Never merge two identities into one spec. The average of
+ two good designs is a bad design.
+
+Begin at Step 1. Show your work.

package/skills/design-dna/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: design-dna
+description: "Use when a design has won and its look must survive: codify it into a permanent style skill with measured ratios, bans and tests that can fail, then build new pieces in that exact look. Fires on 'turn this into a skill', 'keep the same style', 'my output drifted'. NOT finding the winner (that is `design-loop`), NOT the words (that is `marketing`)."
+tags: [design, style, dna, codify, skill-factory, consistency]
+recommends: [design-loop, design, nextjs, marketing]
+origin: risco
+---
+
+# 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.
+
+## 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`.

package/skills/design-dna/design-dna.schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Design DNA",
+  "description": "The exhaustive record of one visual identity. Written for you and for build tools, never pasted into a prompt. The prompt payload is compiled from this file into PROMPT.md under a 2KB cap.",
+  "type": "object",
+  "required": ["meta", "soul", "palette", "type", "space", "signatures", "weird_move", "bans", "tests", "reconstruction"],
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "type": "object",
+      "description": "Provenance. What this is, where it came from, and what must never be reproduced.",
+      "required": ["name", "slug", "source", "captured", "not_copied", "medium_of_origin"],
+      "properties": {
+        "name": { "type": "string", "description": "Human name of the style, e.g. 'Cold Press Editorial'." },
+        "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "kebab-case. Becomes the emitted skill folder name and its slash command." },
+        "source": { "type": "array", "items": { "type": "string" }, "description": "Paths or URLs of the reference artefacts this was measured from." },
+        "captured": { "type": "string", "description": "ISO date the capture was made. Styles age; a dated record tells you when to re-measure." },
+        "not_copied": { "type": "array", "items": { "type": "string" }, "description": "Real logos, wordmarks, licensed photographs, proprietary typefaces. Reproduce the SYSTEM, never the MARKS. Name the substitute used for each." },
+        "medium_of_origin": { "type": "string", "description": "What the reference actually was: website, poster, carousel, deck, motion graphic. The format is an output, not the subject." },
+        "confidence_notes": { "type": "array", "items": { "type": "string" }, "description": "Step 7 output: every value inferred rather than measured, and every rule under 70% confidence. This is where the style drifts first." }
+      }
+    },
+    "soul": {
+      "type": "object",
+      "description": "The compression key. Read this alone and you are most of the way there.",
+      "required": ["one_line", "adjectives", "lineage", "read_distance", "energy"],
+      "properties": {
+        "one_line": { "type": "string", "maxLength": 160, "description": "Max 160 chars. Concrete nouns only. No marketing words, no 'premium', no 'clean'." },
+        "adjectives": { "type": "array", "minItems": 3, "maxItems": 5, "items": { "type": "string" } },
+        "lineage": { "type": "string", "description": "The family tree: Swiss editorial, 90s rave flyer, brutalist web, Memphis, ECM sleeve." },
+        "read_distance": { "enum": ["thumb", "arms-length", "desk", "room", "street"], "description": "How far away it is read from. This sets the minimum type size, so it is a functional field, not a poetic one." },
+        "energy": {
+          "type": "object",
+          "description": "Each 1-10. A fingerprint that catches drift no single value does.",
+          "required": ["density", "variance", "contrast", "warmth"],
+          "properties": {
+            "density": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How much of the canvas is occupied." },
+            "variance": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How much elements differ from each other. Low = systematic, high = collaged." },
+            "contrast": { "type": "integer", "minimum": 1, "maximum": 10 },
+            "warmth": { "type": "integer", "minimum": 1, "maximum": 10 }
+          }
+        }
+      }
+    },
+    "palette": {
+      "type": "object",
+      "description": "Colour AND its proportions. The same three hex codes at 60/30/10 and at 90/8/2 are two unrelated designs.",
+      "required": ["colors", "coverage", "banned"],
+      "properties": {
+        "colors": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "required": ["role", "hex", "name"],
+            "properties": {
+              "role": { "type": "string", "description": "ground, ink, accent, secondary, hairline." },
+              "hex": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Sampled, never guessed." },
+              "name": { "type": "string", "description": "Descriptive, not systematic. 'dusty plum' travels to an image model; 'accent-500' does not." }
+            }
+          }
+        },
+        "coverage": { "type": "object", "description": "Percentage of canvas per role, summing to roughly 100. The most-skipped and most-decisive field in the whole document.", "additionalProperties": { "type": "number" } },
+        "mode": { "type": "string", "description": "light, dark, or duotone-on-stock." },
+        "banned": { "type": "array", "items": { "type": "string" }, "description": "Colour behaviours forbidden: gradients, two accents in one frame, pure #000000." }
+      }
+    },
+    "type": {
+      "type": "object",
+      "description": "Families, and above all the ratio between them. 8-to-1 and 2-to-1 are different designs with identical fonts.",
+      "required": ["families", "scale", "treatment"],
+      "properties": {
+        "families": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["role", "family", "fallback"],
+            "properties": {
+              "role": { "enum": ["display", "body", "mono", "caption", "ui"] },
+              "family": { "type": "string" },
+              "fallback": { "type": "string", "description": "REQUIRED. Silent Arial substitution is the most common way a reproduction dies quietly." },
+              "weights": { "type": "array", "items": { "type": "integer" } },
+              "licence_risk": { "type": "string", "description": "free / webfont-ok / proprietary-substitute-needed." }
+            }
+          }
+        },
+        "scale": {
+          "type": "object",
+          "required": ["display_to_body_ratio", "max_sizes_per_frame"],
+          "properties": {
+            "display_to_body_ratio": { "type": "number", "description": "The typographic signature. Record it as a floor too ('8x, never under 6x')." },
+            "ratio_floor": { "type": "number" },
+            "steps": { "type": "array", "items": { "type": "number" }, "description": "Relative steps, not pixels." },
+            "max_sizes_per_frame": { "type": "integer", "description": "Usually 2 or 3. A testable ceiling." }
+          }
+        },
+        "treatment": {
+          "type": "object",
+          "properties": {
+            "display_tracking": { "type": "string", "description": "e.g. '-0.03em'." },
+            "body_leading": { "type": "string", "description": "As a multiple of size." },
+            "case": { "type": "string" },
+            "measure": { "type": "string", "description": "Characters per line. Under 65 for body is the usual bound." },
+            "numerals": { "type": "string", "description": "lining / oldstyle / tabular." }
+          }
+        }
+      }
+    },
+    "space": {
+      "type": "object",
+      "description": "USE PERCENTAGES. One spec must drive a 1080x1350 carousel and a 1920x1080 slide without a rewrite. Pixel values here are the reason a spec works on a slide and breaks on a carousel.",
+      "required": ["grid", "margin_pct", "alignment", "negative_space"],
+      "properties": {
+        "grid": { "type": "string" },
+        "margin_pct": { "type": "number" },
+        "gutter_pct": { "type": "number" },
+        "alignment": { "type": "string", "description": "Where things line up, and what is deliberately never centred." },
+        "rhythm": { "type": "string", "description": "The spacing progression, e.g. 'x1.5 geometric off a 8px base'." },
+        "negative_space": { "type": "string", "description": "Where the emptiness is and how big. Emptiness is a placed element, not leftover." },
+        "safe_area": { "type": "object", "description": "Per platform, in percentages.", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "description": "What the thing is physically made of.",
+      "properties": {
+        "texture": { "type": "object", "properties": { "kind": { "type": "string" }, "opacity": { "type": "number" }, "scale": { "type": "string" }, "stacking_order": { "type": "string" } } },
+        "edges": { "type": "string", "description": "Radii, hairline weights, whether anything bleeds off canvas." },
+        "elevation": { "type": "string", "description": "Often the honest answer is 'none'. Record the absence." },
+        "imagery": { "type": "string", "description": "Treatment: duotone, grain, crop discipline, subject distance." },
+        "iconography": { "type": "string", "description": "Or the absence of it." }
+      }
+    },
+    "signatures": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 9,
+      "description": "The payload. Carry these and nothing else and it is still recognisable. To add a tenth you must delete one; the cap forces a decision instead of shipping indecision.",
+      "items": {
+        "type": "object",
+        "required": ["move", "how", "when", "never"],
+        "properties": {
+          "move": { "type": "string", "description": "Name it like a technique, so it can be referred to in one word." },
+          "how": { "type": "string", "description": "AS A RATIO OR RELATIONSHIP. Style is formally the correlation between features, not the features." },
+          "when": { "type": "string", "description": "Where in a piece or a sequence it appears." },
+          "never": { "type": "string", "description": "How it gets used wrong. The failure mode, written down." }
+        }
+      }
+    },
+    "weird_move": {
+      "type": "object",
+      "description": "The single deliberate break in the system. Its own key, deliberately, so it can never get buried in the middle of a document. Highest-information element present and the first thing a mechanical extraction loses.",
+      "required": ["what", "how", "why"],
+      "properties": {
+        "what": { "type": "string" },
+        "how": { "type": "string", "description": "Reproducible instruction, as a relationship." },
+        "why": { "type": "string" },
+        "frequency": { "type": "string", "default": "exactly once per piece" }
+      }
+    },
+    "archetypes": {
+      "type": "array",
+      "description": "Named layouts. Without these you get consistent styling and inconsistent structure, which reads as sloppiness: output #8 will not sit beside output #1 as a set.",
+      "items": {
+        "type": "object",
+        "required": ["id", "purpose", "anatomy"],
+        "properties": {
+          "id": { "type": "string" },
+          "purpose": { "type": "string", "description": "Its job in a sequence: opener, proof, quote, closer." },
+          "anatomy": { "type": "string", "description": "Slot-by-slot structure in percentages." },
+          "content_shape": { "type": "string", "description": "The content budget: max words per slot." }
+        }
+      }
+    },
+    "motion": {
+      "type": "object",
+      "description": "Omit entirely for static work. Restraint is a signature too, which is why never_moves is required when this key exists.",
+      "required": ["never_moves"],
+      "properties": {
+        "easing": { "type": "string" },
+        "durations": { "type": "object", "additionalProperties": { "type": "string" } },
+        "entrances": { "type": "string" },
+        "never_moves": { "type": "array", "items": { "type": "string" } },
+        "reduced_motion": { "type": "string", "description": "The prefers-reduced-motion fallback. Not optional in shipped work." }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "description": "Copy is part of the design. Right layout, wrong sentence, broken look.",
+      "properties": {
+        "register": { "type": "string" },
+        "sentence_length": { "type": "string" },
+        "headline_shape": { "type": "string" },
+        "banned_words": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "bans": {
+      "type": "array",
+      "minItems": 5,
+      "items": { "type": "string" },
+      "description": "Written as absolutes, starting with 'Never'. A positive instruction has to out-vote the training average; a ban deletes the landslide from the options. One ban can rule out an entire space in one line. Bans should outnumber positive style rules."
+    },
+    "tests": {
+      "type": "array",
+      "minItems": 8,
+      "description": "8 to 12. Binary and measurable. If two people could disagree about the answer, it is not a test. A spec with no failing test is a mood board with better formatting.",
+      "items": {
+        "type": "object",
+        "required": ["id", "check", "fail_looks_like", "auto"],
+        "properties": {
+          "id": { "type": "string" },
+          "check": { "type": "string", "description": "Stated so the answer is yes or no, or a number against a bound." },
+          "fail_looks_like": { "type": "string" },
+          "auto": { "type": "boolean", "description": "True if a script could decide it. Those go into tools/check.py." }
+        }
+      }
+    },
+    "reconstruction": {
+      "type": "object",
+      "description": "Step 5. A spec that has never been used to rebuild its own source has never been tested at all.",
+      "required": ["attempted", "gaps_found", "passes"],
+      "properties": {
+        "attempted": { "type": "boolean" },
+        "passes": { "type": "integer", "description": "Expect 2 or 3." },
+        "gaps_found": { "type": "array", "items": { "type": "string" }, "description": "Every difference found between rebuild and original, and the field added to close it. Expect these to be things you were sure were obvious." },
+        "stranger_test": { "type": "string", "description": "Whether a stranger could still pick the copy from the original, and how you checked." }
+      }
+    }
+  }
+}