howone 0.1.20 → 0.1.23

package/templates/vite/.howone/skills/hallmark/references/study.md

@@ -0,0 +1,486 @@
+# Study — extracting design DNA from a screenshot or URL
+
+This file is loaded when the `hallmark study` verb runs. It defines the protocol for reading a reference the user supplied — either a screenshot they attached or a URL to a live page — 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, its colour anchor, its rhythm — and lets the user apply that DNA to their own content. It does not copy pixels. 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.
+
+---
+
+## Source mode — image or URL
+
+`study` accepts **either** an image (a screenshot the user attached) **or** a URL to a live page. Same verb, same diagnosis output, different signal sources. Detection is automatic: if the user's input starts with `http://` or `https://` → URL mode; anything else (an attached image, a pasted capture) → image mode.
+
+The two modes share the schema, the refusal heuristics, and the diagnosis-report shape. They differ on what each step of the protocol can know:
+
+| Step | Image mode | URL mode |
+| --- | --- | --- |
+| 1 Surface | colour bands and footprint, estimated by eye | exact OKLCH / hex / rgb values pulled from CSS custom properties and `:root` declarations |
+| 2 Type | *roles only* — "italic editorial serif" | roles **plus exact font names** when the page declares them via `@font-face`, Google Fonts `<link>`, `next/font`, or hard-coded `font-family` |
+| 3 Structure | inferred from visible regions | inferred from real DOM (`<nav>`, `<section>`, `<main>`, `<footer>`, semantic tags) |
+| 4 Motion | usually "not visible — assuming default reveals" | observable — read from `<script src>` tags (framer-motion, gsap, lottie-web, lenis, motion) and CSS `@keyframes` / `transition` declarations |
+| 5 Rhythm | observable directly from the visual gestalt | **not observable** — HTML alone can't tell you density / asymmetry / pacing. Mark this as a known blind spot in the diagnosis. |
+
+URL mode trades the rhythm pass for everything else getting more accurate. If rhythm is what the user wants extracted, they should attach a screenshot instead — or alongside the URL, but Hallmark still defaults to one source at a time (see the "One screenshot, one diagnosis" rule in § Limits).
+
+### URL mode — fetch pipeline
+
+When the input is a URL:
+
+1. **URL refusal check.** Run the URL refuse list in § Refusal **before fetching anything**. Auto-refuse on a domain match. Marketplaces and template demos don't get a WebFetch call at all.
+2. **Fetch.** Use the WebFetch tool on the URL. Ask for the rendered HTML plus any linked stylesheets referenced via `<link rel="stylesheet">`. If WebFetch can only return one consolidated response, ask for "the full HTML source plus the contents of any `<style>` blocks and `:root` token declarations."
+3. **Junk-or-blocked check.** Decide if the fetch was useful using the heuristics in § Junk-or-blocked detection below. If the page is auth-walled, an empty SPA shell, or otherwise un-readable, fall back to asking the user for a screenshot. Do not silently degrade.
+4. **Extract.** Run the five-step protocol against the HTML / CSS payload. Every step except Rhythm produces concrete values; Rhythm is marked `unknown (URL mode)` in the schema and called out as a blind spot in the diagnosis.
+5. **Schema + diagnosis.** Fill the schema (URL-mode fields noted inline in § The structured fields). Emit the diagnosis using the URL-mode template variant in § The diagnosis report.
+
+### Junk-or-blocked detection
+
+After WebFetch returns, decide if the payload is usable. Any one of these signals triggers the screenshot fallback:
+
+| Signal | What it means |
+| --- | --- |
+| HTML contains `<input type="password">` or `<form action="/login">` *and* total visible text < 500 chars | Auth wall — the page didn't render past the login |
+| `<body>` text content < 200 chars *and* the page has a `<div id="root">`, `<div id="__next">`, `<div id="app">`, or similar SPA mount node | Client-rendered SPA — WebFetch only saw the JS shell |
+| HTTP status was non-2xx, or WebFetch returned an error | The URL didn't resolve / blocked the request |
+| No `<link rel="stylesheet">`, no `<style>` blocks, no inline `style=` attributes | The page has no usable styling signal — typically a robots-blocked or CDN-blocked response |
+| The fetched HTML is < 1 KB total | The origin returned a minimal stub, not the real page |
+
+**Fallback message** (use this verbatim, swap the bracketed reason):
+
+> *I tried to read this URL but [the page is behind a login / it's a client-rendered SPA and only the JS shell came back / the URL didn't respond / there's no styling signal in the response]. Could you paste a screenshot instead? `study` works equally well from images — URL mode just needs the page to render server-side.*
+
+A half-blind diagnosis is worse than asking once. If type, colour, AND structure can't all be extracted, fall back.
+
+---
+
+## 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.
+
+### URL refuse list (auto-refuse on domain match)
+
+In URL mode, run this **before** WebFetch fires — don't even fetch the page. If the URL matches any pattern, refuse and offer the redirect.
+
+| If the URL host / path is… | Then… |
+| --- | --- |
+| `themeforest.net/*`, `templatemonster.com/*`, `themely.com/*` (paid template marketplaces) | Refuse. *"This looks like a template marketplace listing. I won't study it. Tell me what about it you like and I'll build with `hallmark default` instead."* |
+| `framer.com/templates/*`, `*.framer.website` (Framer marketplace + template demos), `webflow.com/templates/*` (Webflow templates) | Refuse same as above — these are the marketplace ecosystem by another name. |
+| `gumroad.com/*` where the page is selling a UI kit or template (heuristic: `og:type=product` plus *template*, *UI kit*, *starter*, *bundle* in the title) | Refuse. |
+| `dribbble.com/shots/*`, `behance.net/gallery/*` (designer presentation work) | Soft-refuse. *"These are individual designers' presentation pieces — I'll extract DNA only, not reproduce signature choices. If a specific designer's voice resonates, tell me what about it does."* |
+| Any URL the user discloses as a direct competitor | Refuse the build. *"I'll extract the structural pattern but won't reproduce a competitor's surface. Would the pattern alone be useful?"* |
+| Anything ambiguous (an unfamiliar agency page, a personal portfolio, an unknown SaaS) | **Ask once:** *"Is this your own site, a public reference you admire, or a competitor? If competitor or marketplace, I'll skip the build and give you the diagnosis only."* |
+
+The image-mode refusal rules above still apply by analogy in URL mode — if the page reads as signature work from a known designer, soft-refuse the same way.
+
+---
+
+## The five-step protocol
+
+Read the source in this order. Each step builds on the previous; do not skip ahead. In image mode, "read" means a vision pass on the attached capture. In URL mode, "read" means parsing the WebFetch'd HTML plus any inlined or linked CSS. Where the two modes differ, the step calls it out explicitly.
+
+### 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)?
+- **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.
+
+**URL mode override.** Pull paper and accent values directly from the fetched CSS. Look for `:root` blocks, `--color-*` / `--bg-*` / `--accent-*` / `--brand-*` custom properties, and the `background-color` / `color` declared on `body`, `main`, and primary buttons / links. Record both the band (for the schema's `paper_band` / `accent_hue_band` fields) **and** the exact value (record it in the schema's `paper_value` / `accent_value` fields — these only exist in URL mode). If the page uses Tailwind, look at the `bg-*` / `text-*` utility classes on `<body>` and primary actions and map them back to the theme.
+
+### Step 2 — Type
+
+Read the type *roles*. In image mode, you do not name typefaces — you'll be wrong about half the time. In URL mode, you **do** name typefaces — the page tells you.
+
+Pick the role each face is playing:
+
+- **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+).
+
+**Image mode rule.** Do not write "this is Söhne" or "this is Inter". Write "this is a neutral grotesque body" and propose 1–2 candidates from the canon in the diagnosis.
+
+**URL mode override.** Read the actual font declarations. The sources, in order of reliability:
+
+1. `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=…">` — names the Google Fonts loaded. Authoritative.
+2. `@font-face { font-family: "…"; src: url(…) }` in CSS — names self-hosted faces. Authoritative.
+3. `next/font` imports in the HTML's preloaded fonts (`<link rel="preload" as="font" href="/_next/static/media/…woff2">` with a `data-font-family` hint, or referenced in inlined `<style>`). Reliable.
+4. Hard-coded `font-family: "Geist", system-ui, sans-serif` declarations on `body`, `h1`, etc. Authoritative for what's *intended*, even if the font isn't actually loaded.
+
+When URL mode names a face, still record the role (the role is what travels into the rebuilt page), and record the name as a side fact. The schema gets both: `display_role: "neutral grotesque"` AND `display_face: "Inter"`. The diagnosis report can then say *"the page loads Inter Tight for display and Inter for body — both neutral grotesques."*
+
+### 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 source, 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.
+
+**URL mode override.** Read the DOM directly. Count `<section>` / `<article>` / `<main>` blocks. Inspect the first one for hero-archetype tells (is there a single `<h1>` + `<p>` + `<a class="…btn…">` → H1 Marquee; is there a `grid-cols-2` wrapper around the hero → H2 Split; is there an `<img>` with `object-cover` filling the hero → H6 Photographic). Inspect the `<nav>` for its archetype (count links; check for a logo + 4–5 inline links + button-right → N1 Standard; floating `position: fixed` with rounded-full → N5 Floating pill). Inspect the `<footer>` for its archetype (4 column grid + social row → Ft3 Index; one big statement line → Ft5; minimal copyright row → Ft1). The DOM is concrete — use it.
+
+### Step 4 — Motion
+
+**Image mode.** 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), record the reveal / easing / microinteraction tells described below.
+
+**URL mode override.** Motion is observable from the page's scripts and CSS. Read these signals:
+
+- `<script src="…framer-motion…">`, `<script src="…gsap…">`, `<script src="…lottie-web…">`, `<script src="…lenis…">`, `<script src="…motion@…">` → record the motion library in use.
+- CSS `@keyframes` blocks → name them (e.g. `fade-up`, `marquee`, `reveal`), and note which selectors apply them.
+- CSS `transition: all …` declarations → flag as the *transition-all* anti-pattern.
+- CSS `transform: scale(1.05)` on `:hover` → flag as the hover-scale anti-pattern.
+- `<script>` blocks referencing `IntersectionObserver` with class toggles → record as scroll-triggered reveal.
+
+Then categorise:
+
+- **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)?
+
+**URL mode override.** Rhythm is the one step URL mode can't carry. HTML can tell you a section has `padding: 8rem 0` but not whether the *visual rhythm* of that 8rem reads generous or templated next to its neighbours — that's a gestalt judgement. Record what the CSS literally declares (padding values, gap values, grid-template-columns ratios) as raw facts, mark the four rhythm axes above as `unknown (URL mode)` in the schema, and call this out as a blind spot in the diagnosis: *"I read this from the page's HTML, not a screenshot — I can name the macrostructure, the type, the colour, and the motion, but I can't tell you whether the rhythm reads generous or templated. If that matters, send a screenshot too."*
+
+---
+
+## The structured fields
+
+After the five-step pass, fill out this schema. The diagnosis report is built from it.
+
+```
+{
+  "source_mode":       "image | url",
+  "source_url":        "<the URL if source_mode=url, else null>",
+  "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": { ... } },
+  "nav":               { "archetype": "N1 | N2 | … | N9", "knobs": { ... } },
+  "footer":            { "archetype": "Ft1 | Ft2 | … | Ft8", "knobs": { ... } },
+  "display_role":      "italic editorial serif | heavy condensed sans | ...",
+  "display_face":      "<exact font name in URL mode, else null>",
+  "body_role":         "neutral grotesque | italic serif | ...",
+  "body_face":         "<exact font name in URL mode, else null>",
+  "label_role":        "monospace | small-caps serif | uppercase grotesque | none",
+  "label_face":        "<exact font name in URL mode, else null>",
+  "pairing_logic":     "single family / two families / three families",
+  "paper_band":        "dark <30 | mid 30-85 | light >85",
+  "paper_value":       "<exact oklch/hex/rgb in URL mode, else null>",
+  "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_value":      "<exact oklch/hex/rgb in URL mode, else null>",
+  "accent_footprint":  "small ≤5% | recurring 5-15% | flood >15%",
+  "density":           "generous | medium | dense | unknown (URL mode)",
+  "asymmetry":         "centred | left-biased | right-biased | asymmetric-grid | unknown (URL mode)",
+  "treatments":        ["riso", "grain-overlay", "glassmorphism", "dark-elevation-lightness", "..."],
+  "reveal":            "none | fade-up | sweep | type-unmask | number-tick | typewriter | (not-visible)",
+  "motion_library":    "<framer-motion | gsap | lottie | lenis | motion | none — only set in URL mode>",
+  "anti_patterns":     ["bouncy hover", "transition-all", "..."]
+}
+```
+
+Every field is required (no nulls except where the schema explicitly notes a mode-conditional field; if a field is genuinely unknowable, write `"unknown"`). The `*_face`, `*_value`, and `motion_library` fields are mode-conditional — they carry exact values in URL mode and `null` in image mode. `density` and `asymmetry` carry `unknown (URL mode)` when source_mode is `url`. 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_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.
+
+### Image-mode template
+
+```
+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 say **build it**, I'll use the extracted DNA as the system — the
+paper, accent, type roles, macrostructure, and nav/footer above become
+the build's tokens. Catalog themes are suspended for that build. If
+you'd rather pivot to a catalog cousin afterwards, the closest is
+[theme name] — just say *"use [theme name] instead"*.
+
+Want me to build with this DNA, or change one axis first?
+
+Or — say `lock the DNA` (or `give me a design.md`) if you want a portable
+`design.md` of this DNA that you can hand to another AI tool. Opt-in,
+never auto.
+```
+
+### URL-mode template
+
+```
+I read [URL].
+
+The page is a [macrostructure name]. The hero is an [archetype name] with
+[knob values]. Nav is [N-archetype]; footer is [Ft-archetype].
+
+The page loads [display_face] for display and [body_face] for body[, with
+<label_face> for labels]. Roles: [display role] + [body role][ + <label role>].
+
+The paper is [exact value, e.g. oklch(96% 0.01 90)] — a [paper band, hue].
+The accent is [exact value, e.g. #c0392b] — a [hue band] used at
+[footprint estimated from how many places it appears in the CSS].
+
+Motion: the page uses [motion_library or "no motion library"]; reveal pattern
+is [reveal]. Anti-patterns I noticed in the CSS / scripts: [list, e.g.
+transition-all on .card, hover-scale on buttons — or "none"].
+
+Rhythm — density and asymmetry — I can't judge from the HTML alone. If
+those matter, send a screenshot as well and I'll add a rhythm pass.
+
+If you say **build it**, I'll use the extracted DNA as the system — the
+paper, accent, type roles, macrostructure, and nav/footer above become
+the build's tokens. Catalog themes are suspended for that build. If
+you'd rather pivot to a catalog cousin afterwards, the closest is
+[theme name] — just say *"use [theme name] instead"*.
+
+Want me to build with this DNA, or change one axis first?
+
+Or — say `lock the DNA` (or `give me a design.md`) if you want a portable
+`design.md` of this DNA. URL-mode emission asks you to confirm the source
+is yours or a public reference for your own brand before writing — that
+extra friction is intentional.
+```
+
+The "Want me to build" line is the **confirmation question** for code generation. The "lock the DNA" line is the **emission CTA** for portable design system output. Both are opt-in; wait for the user before doing either. See § Emitting a `design.md` from `study` below for the emission flow.
+
+---
+
+## 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 say **build it**, I'll use this DNA as the system — warm cream paper, neutral ink-on-paper accent, italic editorial serif + neutral grotesque + monospace, Split Studio macrostructure, H2 hero + Ft3 footer. Catalog themes are suspended for the build. If you'd rather pivot to a catalog cousin after, the closest is **Studio** (Instrument Serif + Geist + small green accent) — just say *"use Studio instead"*.
+>
+> Want me to build with this DNA, or change one axis first?
+
+**If the user says "build it":** the skill builds with the **studied DNA as the system, not a catalog theme**. Paper, accent, type roles, macrostructure, and archetypes from the diagnosis become the tokens directly. Catalog rotation is suspended for this build (see SKILL.md § 2.6 Condition 0). The stamp records `theme: studied-DNA` with the source URL or image tag plus the actual OKLCH/font values inline:
+
+```css
+/* Hallmark · macrostructure: Split Studio · H2 hero knobs: ratio=6/6, right=proof, divider=negative-space
+ * Ft3 footer knobs: cols=4, heading=mono
+ * theme: studied-DNA (source: image) · paper oklch(95% 0.012 80) · accent neutral (ink-on-paper)
+ * display: italic editorial serif (Instrument Serif candidate) · body: neutral grotesque (Geist candidate) · label: mono (Geist Mono)
+ * studied: yes · DNA-source: user reference (described as own work)
+ */
+```
+
+**If the user instead says "build it with Studio":** the DNA hands the macrostructure + archetypes to the build but the catalog theme **Studio** supplies the tokens (Instrument Serif + Geist + forest-green accent). This is the pivot path — explicit only.
+
+**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.** In image mode, Hallmark names *roles* and proposes 1–2 candidates from its canon — visual font ID is wrong half the time on custom or modified faces. In **URL mode** the rule flips: the page's `@font-face`, Google Fonts `<link>`, and `next/font` declarations name the typefaces authoritatively, and the diagnosis can name them. The role still travels into the rebuilt page (Hallmark may pick a different specific face from the canon for the user's content); the original name is recorded as a side fact.
+2. **Imagery is never copied.** The skill's build replaces the source'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 source'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 — even when URL mode named the exact dress.
+4. **One source, one diagnosis.** Do not let the user paste five screenshots OR five URLs 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. **URL mode has a known rhythm blind spot.** HTML alone can't tell you whether the visual rhythm reads generous or templated. Always call this out in URL-mode diagnoses, and offer the user the option to send a screenshot alongside if rhythm matters.
+6. **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.
+
+---
+
+## Emitting a `design.md` from `study`
+
+After the diagnosis, the user has a third option alongside "build with this DNA" and "stop here": **emit a portable `design.md`** that captures the DNA as a system other AI tools (Cursor, v0, Bolt, future Hallmark runs) can read directly. This is the same `design.md` format produced by the default verb's "lock the system" flow — but seeded from the studied DNA rather than from a build the user iterated on.
+
+### Trigger phrases
+
+Fire ONLY when the user says one of these *after* a diagnosis:
+
+- *"lock the DNA"* / *"lock this DNA"*
+- *"give me a design.md"* / *"write a design.md"* / *"export this as a design.md"*
+- *"make this portable"* / *"make the DNA portable"*
+
+If the user just confirms the diagnosis without naming emission, **do not emit**. The CTA in the diagnosis surfaces the option; the trigger phrase confirms intent.
+
+### The emission-refusal layer (tighter than diagnosis refusal)
+
+Diagnosis refusal asks: *"can I read this without crossing the line into cloning a competitor or copying a paid template?"* The answer is usually yes — reading is cheap and educational.
+
+Emission refusal asks: *"can I package this DNA as a portable system the user (or any AI tool the user hands the file to) will then use as their own design language?"* That's meaningfully more extractive than a diagnosis. The user already has the diagnosis; the file is a separate, durable artifact that travels.
+
+The two refusal layers do not match. A reference can clear the diagnosis bar and still fail the emission bar.
+
+**Image mode — emission is allowed by default.** The user owns the screenshot they attached. They can be trusted to have rights to extract from it (their own work, a personal moodboard, a public reference they have permission to learn from). Emit without asking.
+
+**URL mode — emission requires explicit attestation.** Before writing the file, ask one short question and wait for the answer:
+
+> *Before I write the file — `design.md` emission packages this DNA as a portable spec other AI tools can use, which is more extractive than a diagnosis. Is this URL:*
+>
+> *(a) your own site*
+> *(b) a public reference for your own brand (you have permission to learn from it)*
+> *(c) something else (a competitor, a designer you admire, a stranger's site you stumbled on)*
+>
+> *Reply (a), (b), or (c).*
+
+Then dispatch on the answer:
+
+| Answer | Action |
+| --- | --- |
+| (a) "my own site" | Emit. Note in the file's `## Provenance` block: *"Extracted from `<URL>` — user-owned source, <date>."* |
+| (b) "public reference for own brand" | Emit, but include a `## Provenance` block: *"Extracted from `<URL>` as a public reference for the user's brand on <date>. The DNA is structural; specific tokens may need to be regenerated to match the user's brand identity rather than the source's."* |
+| (c) "something else" | **Refuse.** *"I won't emit a `design.md` from a third-party site I'm not authorised to extract from. The diagnosis is yours — that's a learning tool. The portable spec needs a source you can attest authorship of, or a public reference for your own brand. If you want a design.md anyway, take a screenshot of your own moodboard or your own existing site, and I'll study that instead."* |
+
+If the user has already disclosed source attribution earlier in the conversation (e.g., during the initial "is this your own work / public reference / competitor" check, they answered "my own site"), do not re-ask — carry that attestation forward. The ask is only needed when status is unknown.
+
+The image-mode refusal table at the top of this file still applies in both modes. A source that already failed the diagnosis refusal (paid template, declared competitor, soft-refused signature work) is auto-refused at emission — do not re-ask.
+
+### What gets written
+
+Use the format defined in [`design-md.md`](design-md.md) § Format, with these `study`-mode adjustments:
+
+1. **Source mode informs token values.** URL mode populates the `## Tokens` block with exact OKLCH / hex values from the source's CSS, and the `## System` block with the exact fonts named in `@font-face` / Google Fonts / `next/font`. Image mode populates the same blocks with the schema's bands rendered into best-guess OKLCH (centre of band) and 1–2 candidate font names from the canon — flag these as estimated.
+2. **Add a `## Provenance` block.** Inserted between `## System` and `## Tokens`. Carries: the source mode, the URL (URL mode only) or "image (user-attached)" (image mode), the date of extraction, the attestation answer if any, and a one-line note about confidence:
+   - URL mode: *"Tokens are exact (extracted from source CSS). Fonts are exact (extracted from source font declarations). Rhythm is unknown — HTML alone can't judge density."*
+   - Image mode: *"Tokens are estimated from source-image colour bands. Fonts are role-based with named candidates from the Hallmark canon. Rhythm is from a vision pass on the source."*
+3. **Add a `## Notes` block** at the end with the anti-patterns the diagnosis flagged as "do NOT carry over." Future Hallmark runs reading the file should see these as part of the system's identity.
+4. **The stamp at the top of the file** carries `studied: yes` and `DNA-source: <mode>` plus the URL or "image" tag, mirroring the macrostructure stamp pattern.
+
+### After the file is written
+
+Same post-emission behaviour as the default verb's lock-the-system flow (per [`design-md.md`](design-md.md) § After the file is written):
+
+- Subsequent Hallmark runs read `design.md` first; diversification inverts to consistency.
+- If the user genuinely needs a different system for a future page, amend `design.md` with a `## Variants` section.
+- One-line confirmation back to the user: *"design.md written. The system is now locked to the extracted DNA. Future runs will defer to it."*
+
+---
+
+## When `study` should hand off
+
+`study` is the diagnosis verb. It is not for fresh builds and not for refining existing pages. After the diagnosis, the user has three options — and `study` itself stops after any one of them:
+
+- If 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 says *"lock the DNA"* / *"give me a design.md"*: emit the file per § Emitting a `design.md` from `study` above. The emitted file becomes the new system; subsequent runs defer to it.
+- 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 or emit files without the user's explicit go-ahead. The diagnosis is the contract; the build and the file are separate decisions.