Skip to content

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

CSS

hallmark study + softer design-context gate

Youssef38526c4b06bc
diff --git a/README.md b/README.md
index 3125279..bab87f9 100644
--- a/README.md
+++ b/README.md
@@ -14,14 +14,15 @@ The differentiator: Hallmark insists on **structural variety**, not just visual
---
-## Four verbs
+## Five verbs
| Verb | What it does |
| --- | --- |
-| *(default)* | Build new UI — passes the design-context gate, picks a structural fingerprint, applies the ruleset, runs the slop test before handing back. |
+| *(default)* | Build new UI — runs the design-context gate (askable, skippable; the skill states what it inferred either way), picks a structural fingerprint, applies the ruleset, runs the slop test before handing back. |
| `hallmark audit <target>` | Score existing code against the named anti-patterns + structural sameness. Returns a punch list. No edits. |
| `hallmark refine <target>` | Polish in place. Smallest possible diff. Preserves structure. |
| `hallmark redesign <target> [--mood <name>]` | Throw out the structure, keep copy + IA + brand, rebuild with a deliberately different structural fingerprint. |
+| `hallmark study <screenshot>` | The user attached a design they admire. Extract the **DNA** — macrostructure, archetypes, type-pairing role, colour anchor — and produce a diagnosis report. Then optionally rebuild *the user's* content using the extracted DNA. **Refuses paid templates and competitor pages. Names font roles, never font IDs. Never copies pixels.** |
---
@@ -39,8 +40,11 @@ The differentiator: Hallmark insists on **structural variety**, not just visual
- [`responsive.md`](skill/references/responsive.md) — mobile-first, content-driven breakpoints, `dvh` not `vh`, safe-area-insets
- [`copy.md`](skill/references/copy.md) — specific verbs, three-part errors, standalone link text, proper typographic punctuation
- [`anti-patterns.md`](skill/references/anti-patterns.md) — 30+ named tells with severity, why they fail, and the fix
+- [`macrostructures.md`](skill/references/macrostructures.md) — the 21 named whole-page shapes; pick one before writing code, stamp it in the CSS comment
+- [`component-cookbook.md`](skill/references/component-cookbook.md) — 33 component archetypes across 7 categories, each with 2–3 within-archetype variation knobs
+- [`study.md`](skill/references/study.md) — vision-extraction protocol for the `hallmark study` verb: refusal heuristics, the structured-fields schema, type-role vocabulary, theme mapping table, worked example, limits
-**Slop test (20 questions)** — every output must answer *no* to all twenty before shipping. Visual (8), structural (2), microinteraction (10).
+**Slop test (29 questions)** — every output must answer *no* to all twenty-nine before shipping. Visual (8), structural (2), microinteraction (10), variety (3), implementation gates (6).
**Site** — [`site/`](site/) is a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. Uses Together AI's "The Future" typeface plus Google Fonts.
@@ -90,7 +94,7 @@ Five skills — [impeccable](https://github.com/pbakaus/impeccable), [kami](http
Distinct choices:
-- **One skill, four verbs.** Not eighteen commands. Use the default; reach for `audit`, `refine`, or `redesign` when you need them.
+- **One skill, five verbs.** Not eighteen commands. Use the default; reach for `audit`, `refine`, `redesign`, or `study` when you need them.
- **Design-context gate.** No audience + use case + tone → no design. The skill asks.
- **Tone as a first-class decision.** "Clean and modern" is rejected. Pick an extreme: editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere.
- **Structural fingerprint.** Every page picks one option from each of six axes. Two consecutive outputs in a session should never share the same fingerprint.
diff --git a/site/index.html b/site/index.html
index 09bc45a..4d6a2c6 100644
--- a/site/index.html
+++ b/site/index.html
@@ -345,13 +345,15 @@
<article class="step">
<span class="step__num">III</span>
<div>
- <h3 class="step__head">Ship, audit, refine, redesign</h3>
- <p class="step__sub">The default verb builds. <code>hallmark audit</code> scores existing code against the tells. <code>hallmark refine</code> polishes in place. <code>hallmark redesign</code> rethinks the structure.</p>
+ <h3 class="step__head">Five verbs: build, audit, refine, redesign, study</h3>
+ <p class="step__sub">The default verb builds. <code>hallmark audit</code> scores existing code against the tells. <code>hallmark refine</code> polishes in place. <code>hallmark redesign</code> rethinks the structure. <code>hallmark study</code> reads a screenshot you admire and extracts its <em>DNA</em> — macrostructure, archetypes, type-pairing role, colour anchor — never the pixels.</p>
</div>
<div class="step__body">
- <pre class="code code--block">$ claude "hallmark audit ./components/hero.tsx"
- → 2 critical · 3 major · 1 minor
- → verdict: reads as AI-generated</pre>
+ <pre class="code code--block">$ claude "hallmark study ./reference.png"
+ → Macrostructure: Split Studio
+ → Hero: H2 Split (6/6, proof column)
+ → Type: italic editorial serif + grotesque
+ → Theme candidate: Studio</pre>
</div>
</article>
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 237e670..0eef154 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -1,7 +1,7 @@
---
name: hallmark
-description: Use this skill when the user asks to design, build, redesign, audit, or refine a UI, web page, landing page, dashboard, component, or interface — or when they ask to make something "feel less AI-generated." Hallmark forces intentional design decisions (typography, color, layout, motion, interaction, structure) and refuses to default to the generic AI-UI template. Trigger phrases include "design a", "build a landing page", "make a dashboard", "redesign this site", "redesign the page", "refine this UI", "audit this design", "this looks AI-generated", "fix the design", "polish this", "give this a different look", and any request that will produce HTML / CSS / JSX / Tailwind output.
-version: 0.2.0
+description: Use this skill when the user asks to design, build, redesign, audit, refine, or study a UI, web page, landing page, dashboard, component, or interface — or when they ask to make something "feel less AI-generated." Hallmark forces intentional design decisions (typography, color, layout, motion, interaction, structure) and refuses to default to the generic AI-UI template. Trigger phrases include "design a", "build a landing page", "make a dashboard", "redesign this site", "redesign the page", "refine this UI", "audit this design", "this looks AI-generated", "fix the design", "polish this", "give this a different look", and any request that will produce HTML / CSS / JSX / Tailwind output. **Also trigger when the user attaches a screenshot of a design they admire** — that is the `hallmark study` verb (extracts design DNA, never pixel-clones).
+version: 0.3.0
---
# Hallmark
@@ -18,7 +18,7 @@ The differentiator: Hallmark insists on **structural variety**, not just visual
## How to use this skill
-Hallmark has one default behaviour and three explicit verbs.
+Hallmark has one default behaviour and four explicit verbs.
| Invocation | What it does |
| --- | --- |
@@ -26,8 +26,9 @@ Hallmark has one default behaviour and three explicit verbs.
| `hallmark audit <target>` | Read the target, score it against the anti-pattern list, return a ranked punch list. **Do not edit.** |
| `hallmark refine <target>` | Apply the ruleset to polish the target in place. Preserve layout structure. **Smallest possible diff.** No redesign. |
| `hallmark redesign <target> [--mood <name>]` | Take the target's content and intent, throw out the structure, and **rebuild it from scratch with a deliberately different structural fingerprint.** New section rhythm, new heading placement, new component voice. Preserve copy, brand, and information architecture; replace everything else. |
+| `hallmark study <screenshot>` | The user pasted or attached an image of a design they admire. Extract the **DNA** — macrostructure, archetypes, type-pairing role, colour anchor — and produce a diagnosis report, then optionally rebuild the user's content using the extracted DNA. **Never copies pixels. Never claims to identify exact fonts. Refuses obvious template-marketplace or competitor-page screenshots.** Load [`references/study.md`](references/study.md) before this verb runs. |
-If the user types anything that does not clearly map to `audit`, `refine`, or `redesign`, treat it as default.
+If the user types anything that does not clearly map to `audit`, `refine`, `redesign`, or `study`, treat it as default. If the user attaches an image without a verb prefix, ask: *"Should I `study` this (extract the DNA), or should I treat it as a reference for a fresh build?"*
---
@@ -35,15 +36,24 @@ If the user types anything that does not clearly map to `audit`, `refine`, or `r
### 1. Design-context gate
-Before writing a single line of code, confirm you have all three:
+Hallmark works best when you know three things before writing code:
1. **Audience.** Who will use this? What do they already know?
2. **Use case.** What single job does this interface do? What is the one action the user should be able to take?
-3. **Tone.** Pick an extreme — *editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere*. "Clean and modern" is not a tone and is not acceptable.
+3. **Tone.** Pick an extreme — *editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere*. "Clean and modern" is not a tone.
-If any of the three is missing, ask for it in one short message. Ask for all missing items at once, not one at a time. Do not guess. Do not infer from the filename, the framework, or surrounding code.
+**Ask once, then commit.** If any of the three is missing, ask for all missing items in **one** short message — not one at a time, not in a follow-up. Offer the user an opt-out at the end of that message: *"or say 'go ahead' and I'll infer from the brief — I'll tell you what I picked."*
-Once you have the three, restate them in one sentence and proceed.
+**If the user opts out** (says "go ahead", "you pick", "skip", "just build it", "don't ask", or simply doesn't engage with the question after one prompt):
+
+- Infer audience, use case, and tone from the brief, the domain, and any visible context (filename, framework, surrounding code is fair game *now* — only because the user delegated).
+- **State the inferences in one sentence at the top of your reply** — *"Going with: audience = X · use = Y · tone = Z. If any of those is wrong, tell me and I'll redirect."*
+- Stamp them in the CSS comment alongside the macrostructure (Step 4 below). The stamp is now the durable record.
+- Pick a **non-default** macrostructure — Specimen-fall-through is still banned, even on inferred briefs.
+
+**Do not skip the inference disclosure.** The opt-out is a courtesy to lazy users, not an excuse for the skill to be opaque. If the user can't see what was inferred, they can't redirect when it's wrong.
+
+Once the three are settled (asked or inferred), restate them in one sentence and proceed.
### 2. Pick a macrostructure FIRST
@@ -77,6 +87,7 @@ The non-negotiables live in [`references/`](references/). Read only what you nee
- [`responsive.md`](references/responsive.md) — mobile-first, content-driven breakpoints, safe areas
- [`copy.md`](references/copy.md) — verbs, labels, error structure, link text
- [`anti-patterns.md`](references/anti-patterns.md) — the named tells you must not emit
+- [`study.md`](references/study.md) — vision-extraction protocol for the `hallmark study` verb (load only when that verb runs)
For most design work you need `macrostructures`, `component-cookbook`, `typography`, `color`, `layout-and-space`, and `anti-patterns`. **Load `microinteractions` whenever the output has *any* interactive element** — buttons, links, inputs, forms, modals, tabs, dropdowns, toasts, drag handles, command palettes, copy buttons, anything with hover/focus/active states. That is most pages.
@@ -208,6 +219,50 @@ Return the redesigned code, plus a short note explaining:
---
+## `hallmark study`
+
+The user has attached or pasted a screenshot of a design they admire. They want to learn from it — its shape, its type, its rhythm — and apply that *DNA* to their own content. They do not want a pixel-faithful copy.
+
+**Critical position:** `study` extracts structure, not pixels. It names the macrostructure, the archetypes, the type-pairing role, the colour anchor, the rhythm. It produces a *diagnosis report* before any code, then offers to rebuild the user's content using the extracted DNA. Pixel-cloning is not a feature.
+
+**Always read [`references/study.md`](references/study.md) before invoking this verb.** That file contains the vision-extraction protocol, the structured-fields schema, the refusal heuristics, and the type-role vocabulary. Do not work from intuition.
+
+### Pipeline
+
+1. **Refuse-or-proceed check.** Before extracting anything, run the refusal heuristics from `study.md`. If the screenshot is clearly a paid template marketplace listing, a competitor's live marketing page, or someone's published portfolio, ask: *"Is this your own work, a public reference for inspiration, or someone else's live site?"* Educational use of public references is fine; copying a competitor's live page is not.
+
+2. **Vision pass.** Read the image into the structured-fields schema in `study.md`. Output ten fields: macrostructure name, hero archetype + variation knobs, pitch archetype + knobs, footer archetype, display family role (never a guessed font name), body family role, surface lightness band (paper L%), accent hue band + chroma, density verdict, type-pairing role.
+
+3. **Diagnosis report.** Return a one-page "this is what you're looking at": names the macrostructure, names the archetypes, points at the type pairing, identifies one or two anti-patterns the screenshot has that the user should *not* carry over. The diagnosis is the deliverable for users who only want to learn.
+
+4. **Confirmation question.** Ask: *"Adopt this DNA wholesale, or change one axis? For example, I could keep the macrostructure but pick a theme that better matches your tone."* Wait for the user's answer before building.
+
+5. **Build.** Pick the closest matching theme from the canon. Stamp the comment with the inferred macrostructure + archetypes + theme. The user's content goes in; the screenshot's content does not.
+
+### Output contract for `study`
+
+When `study` produces code, the macrostructure stamp must include a `studied: yes` flag and the theme picked, e.g.:
+
+```css
+/* Hallmark · macrostructure: Marquee Hero · H1 hero knobs: size=xxl, alignment=left-bias
+ * theme: Studio · accent: forest-green ~3% · studied: yes · DNA-source: user reference
+ */
+```
+
+The stamp signals to future Hallmark runs that this page's structure was extracted, not invented. That matters for the audit verb: a `studied: yes` page should be audited *more* leniently for "Specimen fall-through" (the user explicitly chose this DNA) but *more* strictly for "did you actually use the extracted DNA, or did you drift back to defaults?"
+
+### Limits to spell out to the user
+
+When you return the diagnosis, name the limits explicitly:
+
+- **Fonts:** the skill names a *role* (e.g., "italic editorial serif", "heavy condensed sans", "monospace dev"), not a font ID. It proposes one or two real candidates from the canon and asks the user to confirm. Visual font identification is unreliable; do not pretend otherwise.
+- **Imagery:** the skill never copies the screenshot's photography. It generates structurally-equivalent placeholders or asks for the user's own assets.
+- **Theme drift is allowed.** If the screenshot is a Specimen and the user's content is a SaaS landing page, the skill picks a different theme. The DNA is the macrostructure + archetype + colour-anchor + type-pairing — not the dress.
+
+If `references/study.md` cannot be loaded for any reason, refuse the verb politely and direct the user to `hallmark redesign` with a written description of what they want from the screenshot.
+
+---
+
## Output contract
When producing new work:
diff --git a/skill/references/study.md b/skill/references/study.md
new file mode 100644
index 0000000..cc617a3
--- /dev/null
+++ b/skill/references/study.md
@@ -0,0 +1,274 @@
+# Study — extracting design DNA from a screenshot
+
+This file is loaded when the `hallmark study` verb runs. It defines the protocol for reading a screenshot the user attached, naming what makes it work, and producing a *diagnosis report* the user can accept or amend before any code is built.
+
+**The promise.** `study` extracts the **DNA** of a design — its macrostructure, its component archetypes, its type-pairing role, its colour anchor, its rhythm — and lets the user apply that DNA to their own content. It does not copy pixels. It does not claim to identify exact fonts. It does not output a façade of the source.
+
+**The mental model.** A designer who likes a reference site does not photocopy it. They look at it long enough to say "ah — that's a Marquee Hero with a single column body, italic-editorial display paired with monospace labels, anchored on a desaturated forest green at maybe 3 % footprint, with hairline rules and one orchestrated entrance." Then they go build something *different* with the same skeleton. That sentence is what `study` outputs. The build is what `default` or `redesign` does after.
+
+---
+
+## Refusal — when not to study
+
+Run this check **before** extracting anything. If any of the following is true, refuse politely and offer an alternative.
+
+| If the screenshot is… | Then… |
+| --- | --- |
+| A paid template marketplace listing (ThemeForest, Gumroad templates, Webflow templates, Framer templates, Notion templates) | Refuse. Suggest: "Tell me what you like about it and I'll build with `hallmark default` instead." |
+| A live competitor's marketing page where the user's intent is replication | Refuse. Suggest: "I can extract the structural pattern but won't reproduce a competitor's surface. Would the pattern alone be useful?" |
+| A famous designer's signature work (Pentagram project pages, Klim foundry specimens, Mathieu Triay's portfolio, etc.) being treated as a template | Soft-refuse. Acknowledge the source by name, extract DNA only, and refuse to copy distinctive choices that read as that designer's signature. |
+| Copyrighted artwork, photography, or illustrations as the design's centerpiece | Refuse to reproduce the artwork. The DNA can still be extracted (the *fact* that the page uses one big image as its hero is structural; the specific image is not). |
+| A user's own previous work | Proceed. |
+| A public reference site the user is using for inspiration on their own brand | Proceed. State the source if known. |
+| Anything ambiguous | **Ask once:** *"Is this your own work, a public reference, or someone else's live site? If it's a competitor or a marketplace template, I'll skip the build and just give you the diagnosis."* |
+
+**Never** silently proceed when you suspect the screenshot is a marketplace listing or a competitor. The user must explicitly confirm. The cost of asking is low; the cost of building a knockoff is reputational.
+
+---
+
+## The five-step protocol
+
+Read the screenshot in this order. Each step builds on the previous; do not skip ahead.
+
+### Step 1 — Surface
+
+Before reading any text, look at the page's *colour temperament*.
+
+- **Paper lightness band.** Is the background dark (L < 30 %), light (L > 85 %), or mid (between)? You don't need an exact value — pick a band.
+- **Paper hue.** Does the background tilt warm (yellow/orange/red, hue 30–90), cool (blue/indigo, 220–290), neutral-warm (slight 60–80), neutral-cool (slight 240–270), or chromatic (clearly purple/green/etc.)?
+- **Anchor accent hue.** What single colour appears as accent — links, marks, buttons, small flourishes? Estimate the hue band: warm-red (10–30), orange (40–60), yellow (80–110), green (130–160), teal (180–210), cyan-blue (210–240), indigo (260–290), magenta (300–340), neutral (no chromatic accent — just ink-on-paper).
+- **Accent footprint.** Is the accent a small mark (≤ 5 % of viewport), a recurring underline (5–15 %), or a flood (large blocks, > 15 %)? This dictates how loud the page is.
+- **Distinctive treatments.** Off-register text-shadow (riso), grain overlay, glassmorphism, dark-mode-with-lightness-elevation, paper texture? Note them.
+
+### Step 2 — Type
+
+Read the type *roles*, not the typeface names. You will be wrong if you guess a typeface from a screenshot — even your best guess is unreliable. Name what each face is *doing*.
+
+- **Display role.** What is carrying the headline? Pick from: *italic editorial serif · roman editorial serif · heavy condensed sans · soft geometric sans · expressive variable sans · monospace · pixel · ornamental script*.
+- **Body role.** What is carrying the prose? *roman serif · italic serif · neutral grotesque · soft geometric sans · monospace*.
+- **Label role.** What is carrying eyebrows, captions, micro-labels? *small-caps serif · monospace · uppercase grotesque · italic body · none (no labels visible)*.
+- **Pairing logic.** Same family with weight/italic split, or two different families? If two, what's the contrast — *editorial serif + grotesque body, mono labels* (the modern editorial agency look), or *condensed display + body sans + mono labels* (technical), etc.?
+- **Display weight.** Light (≤ 300), regular (400–500), heavy (700+), extra-bold (800+).
+
+Do not write "this is Söhne" or "this is Inter". Write "this is a neutral grotesque body".
+
+### Step 3 — Structure
+
+Match the page to one of the twenty-one named macrostructures in [`macrostructures.md`](macrostructures.md). Pick the *closest*; if it's between two, name both and say which it leans toward.
+
+For each section visible in the screenshot, also pick an archetype from [`component-cookbook.md`](component-cookbook.md):
+
+- **Hero** → H1–H6 (or F6 for product-led pages).
+- **Pitch / first content block** → F1–F5 (or F6 for catalogue).
+- **Testimonial / proof** (if visible) → T1–T4.
+- **Footer** → Ft1–Ft4.
+
+For each archetype, also pick **variation knobs** from the cookbook's variation-knob table. *"H2 Split Diptych · ratio=7/5 · right-side=proof column · divider=hairline."* The knobs are what distinguishes one Bento from another; capturing them is what makes the diagnosis useful.
+
+### Step 4 — Motion
+
+If the screenshot is static, skip this section but note: *"motion not visible in static capture — assuming default reveals."*
+
+If the screenshot is animated (a GIF, a recorded screen, or the user describes the motion in text):
+
+- **Reveal pattern.** None · fade-up stagger · horizontal sweep · type-unmask · number-tick · typewriter.
+- **Easing voice.** Conservative (ease-out exponential) · physical (slight overshoot, drag-release) · none.
+- **Microinteraction tells.** Bouncy hovers, transition-all, hover-scale on cards, gradient hover sweeps — flag any. These are anti-patterns to *not* carry forward.
+
+### Step 5 — Rhythm
+
+The hardest one. Look at the *density and pacing*:
+
+- **Section padding rhythm.** Equal across sections (templated) or varied (intentional)?
+- **Heading-to-body ratio.** Short heading + long body (editorial) · long heading + short body (declarative) · roughly equal (technical / utilitarian)?
+- **Negative space discipline.** Generous (luxury / atelier / specimen) · medium (modern editorial) · dense (newsprint / catalogue / index)?
+- **Asymmetry.** Centred symmetric (formal, Apple-product-page energy) · left-biased (editorial) · right-biased (rare, atelier-like) · asymmetric grid spans (specimen, bento)?
+
+---
+
+## The structured fields
+
+After the five-step pass, fill out this schema. The diagnosis report is built from it.
+
+```
+{
+ "source": "user-described | public-reference | unknown",
+ "refusal": "ok | refused (paid-template) | refused (competitor) | soft-refusal (signature work)",
+ "macrostructure": "<name from macrostructures.md>",
+ "macrostructure_alt":"<second-closest, if it leans>",
+ "hero": {
+ "archetype": "H1-Marquee | H2-Split | H3-Quote-Led | H4-Stat-Led | H5-Letter | H6-Photographic | F6-Product-grid",
+ "knobs": { "<knob A>": "<value>", "<knob B>": "<value>" }
+ },
+ "pitch": { "archetype": "...", "knobs": { ... } },
+ "footer": { "archetype": "...", "knobs": { ... } },
+ "display_role": "italic editorial serif | heavy condensed sans | ...",
+ "body_role": "neutral grotesque | italic serif | ...",
+ "label_role": "monospace | small-caps serif | uppercase grotesque | none",
+ "pairing_logic": "single family / two families / three families",
+ "paper_band": "dark <30 | mid 30-85 | light >85",
+ "paper_hue": "warm | cool | neutral-warm | neutral-cool | chromatic-<hue>",
+ "accent_hue_band": "warm-red | orange | yellow | green | teal | cyan-blue | indigo | magenta | neutral",
+ "accent_footprint": "small ≤5% | recurring 5-15% | flood >15%",
+ "density": "generous | medium | dense",
+ "asymmetry": "centred | left-biased | right-biased | asymmetric-grid",
+ "treatments": ["riso", "grain-overlay", "glassmorphism", "dark-elevation-lightness", "..."],
+ "reveal": "none | fade-up | sweep | type-unmask | number-tick | typewriter | (not-visible)",
+ "anti_patterns": ["bouncy hover", "transition-all", "..."]
+}
+```
+
+Every field is required (no nulls; if a field is genuinely unknowable from the image, write `"unknown"`). The schema is the contract; the diagnosis report is the human-readable rendering of it.
+
+---
+
+## Theme mapping
+
+After the schema is filled, map the source to one of Hallmark's named themes — but **only as a candidate**. The user may pick a different theme for their build.
+
+| If the schema looks like… | Suggest theme |
+| --- | --- |
+| `display_role: italic editorial serif`, `body_role: neutral grotesque`, `paper_band: light`, `accent: green` | **Studio** |
+| `display_role: roman editorial serif`, `paper_hue: warm`, `density: medium`, `treatments: hairline rules` | **Specimen** |
+| `paper_band: dark`, `accent: indigo`, `display: condensed/heavy` | **Midnight** |
+| `paper_band: dark`, `font: mono throughout`, `treatments: phosphor green or amber` | **Terminal** |
+| `paper_hue: warm-pink`, `treatments: riso / grain / off-register`, `display: heavy lowercase` | **Riso** |
+| `paper_hue: cool-lavender`, `display: soft geometric sans`, `accent: low-chroma indigo` | **Pastel** |
+| `paper_band: light`, `display: heavy black sans`, `accent: red flood` | **Brutal** |
+| `paper_band: dark`, `display: heavy uppercase`, `accent: red flood` | **Manifesto** |
+| `paper_hue: cool`, `density: dense`, `body: 2-3 column justified` | **Newsprint** |
+| `paper_hue: warm`, `density: generous`, `display: ornamental serif`, `dividers: fleuron` | **Salon** |
+| `paper_hue: warm`, `density: medium`, `display: roman serif`, `body: italic serif` | **Linen** |
+| `paper_band: light cool`, `font: mono labels`, `density: dense`, `tabular numbers` | **Almanac** |
+| `display: italic display`, `accent: red`, `tabular numbers`, `motion: horizontal sweep` | **Sport** |
+| `display: ornamental script`, `paper: cream`, `density: medium-generous` | **Garden** |
+| Anything else | **Specimen** *(only if the brief is editorial)* — otherwise propose one of the eight that's closest by *paper hue + display role*, and note the mismatch. |
+
+If two themes are equally close, pick whichever is more *categorically distant* from any previous Hallmark output for this user (read the existing CSS for a `/* Hallmark · macrostructure: ... */` stamp and avoid that theme's family).
+
+---
+
+## The diagnosis report
+
+After the schema and the theme map, produce a one-page report in this shape. Keep it short — about ten sentences. The user reads this *before* approving any code.
+
+```
+You sent me a [macrostructure name].
+
+The hero is an [archetype name] with [knob values]. The pitch below it is
+an [archetype]. The footer is an [archetype].
+
+The type pairing is [display role] with [body role][, labels in <label role>].
+I won't try to identify exact typefaces from a screenshot — fonts to consider:
+[1–2 candidates from the canon].
+
+The surface is [paper band, hue]. The accent is [hue band] used at
+[footprint]. Density reads as [density]; the page is [asymmetry].
+
+Distinctive treatments I noticed: [list, or "none beyond the basics"].
+
+Anti-patterns I'd skip: [list anything from anti-patterns.md visible in
+the screenshot — bouncy hovers, transition-all, three-feature grid, etc.
+If there are none, say so.]
+
+If you adopt this DNA, the closest theme in the canon is [theme name].
+That's a candidate, not a requirement — your content might point elsewhere.
+
+Want me to build with this DNA, or change one axis first?
+```
+
+The last line is the **confirmation question**. Wait for the user before building.
+
+---
+
+## Worked example
+
+**Screenshot:** the user pastes a capture of a fictional "studio.example" page — a beige cream background, a single italic display headline reading *"A studio for the patient."* set in 7rem italic, with a single right-aligned column of three captioned project thumbnails on the right side of the fold, and a 4-column index footer at the bottom with monospace category labels and serif body links.
+
+**Schema** (filled by the model after a vision pass):
+
+```
+{
+ "source": "user-described",
+ "refusal": "ok",
+ "macrostructure": "Split Studio",
+ "macrostructure_alt": null,
+ "hero": {
+ "archetype": "H2-Split",
+ "knobs": { "ratio": "6/6", "right side": "proof column", "divider": "negative space" }
+ },
+ "pitch": null,
+ "footer": {
+ "archetype": "Ft3-Index columns",
+ "knobs": { "columns": "4", "heading style": "monospace", "bullet": "none" }
+ },
+ "display_role": "italic editorial serif",
+ "body_role": "neutral grotesque",
+ "label_role": "monospace",
+ "pairing_logic": "two families",
+ "paper_band": "light >85",
+ "paper_hue": "warm",
+ "accent_hue_band": "neutral",
+ "accent_footprint": "small ≤5%",
+ "density": "generous",
+ "asymmetry": "split-equal",
+ "treatments": [],
+ "reveal": "(not-visible)",
+ "anti_patterns": []
+}
+```
+
+**Diagnosis returned to user:**
+
+> You sent me a Split Studio.
+>
+> The hero is an H2 Split Diptych at a 6/6 ratio — italic display on the left, a column of three captioned projects on the right, divided by negative space rather than a rule. The pitch slot is empty in your capture; I can fill it or leave it. The footer is an Ft3 four-column Index with monospace category headings and roman link rows.
+>
+> The type pairing is italic editorial serif with neutral grotesque body, monospace for labels. I won't guess the exact serif from a screenshot — fonts to consider: **Instrument Serif** (free, 2026's most-used italic display) or **Tobias** (paid). For body and labels: **Geist** + **Geist Mono**.
+>
+> The surface is warm cream, paper L roughly 95 %. The accent is neutral — no chromatic colour beyond ink-on-paper, which is why the page reads composed rather than excited. Density is generous; the page is asymmetric-balanced (split equal but content is right-weighted).
+>
+> Distinctive treatments: none beyond the basics — that's the point. Restraint is the design.
+>
+> Anti-patterns I'd skip: nothing from this screenshot stands out as carry-over risk. The reference is clean.
+>
+> If you adopt this DNA, the closest theme in the canon is **Studio** (Instrument Serif italic display + Geist body + forest-green accent). Note: the screenshot's accent is neutral; Studio uses a small green mark — if you want neutral, I can desaturate the accent in the build.
+>
+> Want me to build with this DNA, or change one axis first?
+
+**If the user says "build it":** the skill picks **Studio**, picks **H2-Split** for the hero, fills the pitch with content from the user's brief (a feature/proof block — F4 Step sequence, say), keeps the Ft3 footer, stamps:
+
+```css
+/* Hallmark · macrostructure: Split Studio · H2 hero knobs: ratio=6/6, right=proof, divider=negative-space
+ * Ft3 footer knobs: cols=4, heading=mono · theme: Studio · accent: neutral (override from default green)
+ * studied: yes · DNA-source: user reference (described as own work)
+ */
+```
+
+**If the user says "change the macrostructure":** offer two alternatives from the same family — say, Bento Grid (modular feature-led) or Long Document (prose-led). Whichever the user picks becomes the new macrostructure; the rest of the DNA carries.
+
+---
+
+## Limits and disclaimers
+
+State these to the user when returning the diagnosis. Do not bury them.
+
+1. **Fonts cannot be identified from screenshots reliably.** Even with What The Font, FontInDetail, or vision-LM guesses, the output is wrong roughly half the time on custom or modified faces. Hallmark names *roles* and proposes 1–2 candidates from its canon. The user owns the final call.
+2. **Imagery is never copied.** The skill's build replaces the screenshot's photography with structurally-equivalent placeholders. If the user wants real assets, they provide them.
+3. **Theme drift is allowed.** The user's content might point to a different theme than the screenshot's surface implies. The DNA is the macrostructure + archetype tuple + colour-anchor band + type-pairing role. The dress (specific typeface, specific accent hex) can change.
+4. **One screenshot, one diagnosis.** Do not let the user paste five screenshots and ask for a "blend". Pick one as the primary reference; the others can inform individual axis choices but the DNA backbone comes from one source. Five blended references is how you produce template-soup.
+5. **No surprise edits.** The diagnosis is for the user to accept. Do not write code in the same turn as the diagnosis. Wait for confirmation.
+
+If any limit is being violated, say so plainly in the diagnosis report — *"I can't reliably identify this typeface; here are two candidates I'm guessing at"* — and let the user redirect.
+
+---
+
+## When `study` should hand off
+
+`study` is the diagnosis verb. It is not for fresh builds and not for refining existing pages.
+
+- If after the diagnosis the user says *"now build me the same kind of page for my brand"*: hand off to the **default** verb with the schema filled in as inferred design-context, and build per the standard flow — but with the studied DNA stamped.
+- If the user says *"now refactor my existing site to match this DNA"*: hand off to **`hallmark redesign`** with the schema attached. Redesign preserves the user's content; study supplied the new shape.
+- If the user only wanted the diagnosis and is satisfied: stop. The diagnosis report is a complete deliverable on its own.
+
+Do not chain verbs without the user's explicit go-ahead. The diagnosis is the contract; the build is a separate decision.