@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/control-plane/scripts/skills/hallmark/references/typography.md

@@ -0,0 +1,243 @@
+# Typography
+
+Type carries the design. If the type is wrong, nothing else matters.
+
+## Principles
+
+- A page is a pairing, not a single font. Display face + body face, minimum. *Single-font pages are allowed only when the single font IS the design choice* — a true terminal aesthetic is monospace-everywhere on purpose; a Manifesto poster might be one display face on purpose. The default is a pairing.
+- Commit to extremes. Weight 200 next to weight 800 reads as intentional. Weight 400 next to weight 600 reads as a default setting.
+- Size steps should be ratios, not increments. Major third (1.25), perfect fourth (1.333), perfect fifth (1.5), or golden (1.618). Pick one and use it.
+- Line-height changes with size. Tight for display (1.05–1.2), comfortable for body (1.5–1.65).
+- Measure — line length — lives between 45 and 75 characters. Use `max-width: 65ch` as the default.
+
+## The 2+1 rule — three faces is the ceiling
+
+**A page may use at most three distinct font families.** One **display**, one **body**, and an optional **outlier** for a single typographic moment — wordmark, hero stat, pull quote, masthead — where the page wants exactly one note that doesn't sound like the rest. Four families is slop. Two is canonical. Three is the ceiling, used sparingly.
+
+The pattern:
+
+```css
+:root {
+  --font-display:  "Fraunces", ui-serif, Georgia, serif;       /* headings, hero */
+  --font-body:     "Geist", ui-sans-serif, system-ui, sans;    /* prose, UI */
+  --font-outlier:  "Geist Mono", ui-monospace, monospace;      /* wordmark + hero stat ONLY */
+}
+```
+
+The outlier is a *register*, not a third surface. Rules:
+
+- **Outlier appears in ≤ 2 places** on the whole page. Wordmark + hero stat. Or pull quote + masthead. Two slots, not five. If you find yourself reaching for it a third time, you don't have an outlier — you have a third body font, which is slop.
+- **The outlier carries one role.** It tags a specific kind of content (the brand, the headline figure, the manifesto line). Once you know what it tags, every instance of that role uses it. Don't apply it to one button label and not another.
+- **Mono counts as a face.** A page with Fraunces display, Geist body, and Geist Mono in code blocks is using three families. That's fine — code is the outlier role. Don't sneak in a fourth.
+- **Same family at different weights is one family**, not two. Geist 400 + Geist 700 is one font; pairing it with Fraunces is two. Adding Geist Mono on top is three.
+
+Two families is still the right answer for most pages. Three is for SaaS / brand-heavy / editorial-rich pages where the wordmark needs a different register than the body.
+
+## Banned defaults
+
+These fonts are on-distribution for every LLM. Do not reach for them without a deliberate reason:
+
+- **Sans-serif:** Inter, Roboto, Open Sans, Lato, Poppins, Source Sans, Nunito, Montserrat, Raleway, Work Sans, DM Sans, system-ui, Arial, Helvetica.
+- **Serif:** Merriweather, Playfair Display (as body — banned as overused body serif; ok as display in moderation), Lora, Source Serif, Georgia-as-default.
+- **Mono:** Courier New, Consolas-as-default, system mono.
+
+If the user insists on one, do it. Otherwise pick from the allowlist below.
+
+## The font catalog
+
+Three sources, in priority order:
+
+- **Google Fonts** — free, served via CDN, works everywhere. The default source.
+- **Fontshare** (Indian Type Foundry) — free for commercial use, foundry-grade. The "you didn't know these were free" tier. Drop-in via `<link href="https://api.fontshare.com/v2/css?f=...">`.
+- **Foundry-licensed** — Klim, Pangram Pangram, Production Type, Lineto, Colophon. Only when the user has confirmed they're licensed.
+
+### Free display faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Fraunces** | Google | Variable serif, deeply expressive italic, optical-size axis | Editorial, Atelier, brand-heavy |
+| **Newsreader** | Google | Roman serif with optical-size + italic | Editorial, magazine, long-form |
+| **Instrument Serif** | Google | Tight contrast, italic available, smart for short heads | Brand, atelier, intimate editorial |
+| **Cormorant Garamond** | Google | Classical, high contrast, luxury register | Luxury, fashion, fine arts |
+| **EB Garamond** | Google | Honest classical Garamond, body-grade | Editorial body, longform reading |
+| **Cardo** | Google | Scholarly serif, generous x-height | Reference, academic, slow reading |
+| **Source Serif 4** | Google | Modern transitional, big OT family | SaaS marketing with serif tone |
+| **DM Serif Display** | Google | Bracketed serif, high-contrast display | Headlines that need to feel printed |
+| **Bodoni Moda** | Google | Modern Bodoni revival, dramatic | Fashion, editorial, luxury display |
+| **Playfair Display** | Google | Use only as display; banned as body | Marketing display moments — sparingly |
+| **Geist** | Google | Modern grotesque, geometric, 7 weights | Modern minimal, SaaS, dev tools |
+| **Inter Tight** | Google | Tighter Inter — allowed *only* as a body fallback in technical themes; never as display | UI body in restrained themes |
+| **Bricolage Grotesque** | Google | Variable display sans, bold weights, condensable | Brutal, playful, riso-bold |
+| **Space Grotesk** | Google | Geometric grotesque, slightly quirky | Brutalist, technical |
+| **Anton** | Google | Heavy condensed grotesque | Posters, manifestos |
+| **Big Shoulders Display** | Google | Industrial condensed | Sports, manifestos, declarative |
+| **Tomorrow** | Google | Variable optical condensed | Tech, atmospheric, near-future |
+| **Outfit** | Google | Modern geometric (banned as default; use only when *picked* deliberately) | Restrained tech — sparingly |
+| **General Sans** | Fontshare | Modern grotesque, Geist-adjacent | Modern minimal alternative to Geist |
+| **Switzer** | Fontshare | Neutral sans, broad weight range | SaaS body, restrained |
+| **Cabinet Grotesk** | Fontshare | Display grotesque, 9 weights | Editorial display, magazine |
+| **Clash Display** | Fontshare | Ultra-condensed display | Posters, brand moments |
+| **Satoshi** | Fontshare | Playful geometric sans | Playful, consumer |
+| **Sentient** | Fontshare | Variable serif, soft contrast | Soft editorial, atmospheric |
+| **Erode** | Fontshare | Distressed serif, hand-set feel | Riso, tactile-rebellion, brand-y |
+| **Tanker** | Fontshare | Heavy condensed grotesque, pure display | One-word posters, mastheads |
+
+### Free body faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Geist** | Google | The default modern body sans | Modern minimal, SaaS, atmospheric |
+| **The Future** | (in repo) | Hallmark's own body workhorse | Default Hallmark tone |
+| **Newsreader** | Google | Reading serif, optical-size aware | Editorial body, longform |
+| **Source Serif 4** | Google | Body-grade serif | Editorial mid-weight |
+| **EB Garamond** | Google | Classical body | Editorial slow reading |
+| **Spectral** | Google | Slab-ish serif, screen-tuned | Long-form on screen |
+| **Lora** | Google | Calligraphic serif, body-grade | Body — sparingly (over-used) |
+| **Crimson Pro** | Google | Old-style body, generous | Editorial slow body |
+| **IBM Plex Sans** | Google | Engineering sans, broad family | Technical body |
+| **Switzer** | Fontshare | Neutral sans body | SaaS body, restrained |
+| **General Sans** | Fontshare | Geist-adjacent body | Modern minimal body |
+
+### Free mono / outlier faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Geist Mono** | Google | Geist's mono companion | Default Hallmark mono, code, captions |
+| **JetBrains Mono** | Google | Engineering mono, ligatures | Code, terminal, technical |
+| **IBM Plex Mono** | Google | Engineering mono, broad family | Technical body-grade |
+| **Commit Mono** | Google | Tighter mono, modern | Code, modern terminal |
+| **Space Mono** | Google | Quirky, slightly retro | Playful tech, riso |
+
+### Tone-based pairing patterns
+
+Each tone gets two rows: a **free baseline** (Google Fonts / Fontshare; works out of the box) and a **paid upgrade** (foundry licences required; only when the user has confirmed the budget and the licence). The free row is the default. **Never name a paid font in code without confirming the user is licensed** — the demo will fall back to system-default and look broken to the user.
+
+| Tone | Tier | Display | Body | Outlier |
+| --- | --- | --- | --- | --- |
+| **Editorial** | Free | Fraunces · Newsreader · EB Garamond · Instrument Serif · Cabinet Grotesk | IBM Plex Sans · Switzer · Source Serif 4 | JetBrains Mono · Geist Mono · Erode (display moment) |
+| | *Paid* | *Tiempos Headline · Söhne Breit · Reckless Display · Migra · Tobias* | *Söhne · Haffer · Untitled Sans* | *Söhne Mono · GT America Mono* |
+| **Technical** | Free | JetBrains Mono · Geist Mono · Geist (700) · Commit Mono | Geist · IBM Plex Sans · Switzer | Tomorrow · Cabinet Grotesk (wordmark) |
+| | *Paid* | *Berkeley Mono · Söhne Mono · GT Pressura · ABC Diatype Mono* | *Söhne · Untitled Sans · ABC Diatype* | *Berkeley Mono · GT Pressura Mono* |
+| **Brutalist** | Free | Bricolage Grotesque (800) · Anton · Tanker · Big Shoulders Display | Geist · Switzer | Space Grotesk (numerals) · Geist Mono |
+| | *Paid* | *Druk · Monument Extended · NaN Jaune · Migra · ABC Pressura* | *Söhne Breit · GT America* | *GT America Mono* |
+| **Soft** | Free | Geist · Bricolage Grotesque (500) · Sentient · Newsreader | Geist · Crimson Pro · Switzer | Geist Mono · Satoshi (label) |
+| | *Paid* | *Söhne · GT Pressura · Pangaia · Tobias* | *Söhne · Halyard Text · Satoshi* | *Söhne Mono · GT Maru Mono* |
+| **Luxury** | Free | Cormorant Garamond · Fraunces · Cardo · DM Serif Display · Bodoni Moda | EB Garamond · Crimson Pro · Source Serif 4 | (rare; small caps from display family) |
+| | *Paid* | *Canela · Tiempos Headline · GT Super · Domaine Display · Migra* | *Tiempos Text · Suisse Int'l · Domaine Text* | *(rarely used at this tier)* |
+| **Playful** | Free | Bricolage Grotesque · Fraunces (italic) · Satoshi · Newsreader (italic) · Sentient | Geist · Newsreader · Satoshi | Geist Mono · Space Mono |
+| | *Paid* | *Clash Display · Cabinet Grotesk · Migra · Tobias · Pangaia* | *Satoshi · Plus Jakarta Sans · GT Maru* | *Space Mono · GT Maru Mono* |
+| **Austere** | Free | system-ui · Inter Tight (regular) · Geist (400) · Switzer (regular) | system-ui · Geist · Switzer | system-ui mono · Geist Mono |
+| | *Paid* | *ABC Diatype · ABC Monument Grotesk · Söhne (regular) · ABC Pressura* | *ABC Diatype · Söhne* | *ABC Diatype Mono · Söhne Mono* |
+| **Atmospheric** | Free | Geist (600) · Sentient · Tomorrow · Bricolage Grotesque | Geist (400) · Switzer | Geist Mono · JetBrains Mono |
+| | *Paid* | *Söhne · GT Pressura · ABC Diatype* | *Söhne · ABC Diatype* | *Berkeley Mono · Söhne Mono* |
+| **Workshop** *(Hallmark's own theme)* | Free | The Future · Geist · Cabinet Grotesk | The Future · Switzer | The Future Mono · Geist Mono |
+| | *Paid* | *Avenir Next · GT Walsheim* | *Söhne · GT Walsheim* | *Berkeley Mono* |
+
+**The discipline.** Default to the free pairings. They're not consolation prizes; Fraunces, Geist, Bricolage Grotesque, Cabinet Grotesk, Sentient, and JetBrains Mono are first-rate faces in 2026. The paid upgrades exist for two cases: (a) the user has explicitly confirmed they're licensed, or (b) the user is asking for a specific named foundry voice (e.g., "make it look like Klim", "I want Söhne"). Reach for Tier 2 only then; otherwise the free row is the right answer. Treat the free row as canon, the paid row as a *cited* alternative.
+
+## Wordmark / logo typography
+
+The wordmark in the navbar and footer **may use a different display face than the body**. On tone-rich themes (Editorial, Atelier, Specimen) it **should** — collapsing the wordmark into the body family flattens the visual hierarchy and the page reads as un-branded.
+
+```css
+:root {
+  --display:       "Geist", system-ui, sans-serif;     /* body + display */
+  --font-wordmark: "Fraunces", Georgia, serif;         /* logo only */
+}
+.wordmark {
+  font-family: var(--font-wordmark);
+  font-weight: 600;
+  letter-spacing: -0.015em;
+}
+```
+
+Recommended pairings (free baseline first):
+
+- **Geist body → Fraunces wordmark, IBM Plex Mono wordmark, or Bricolage Grotesque (heavy) wordmark**
+- **Fraunces body → Geist Mono wordmark, Inter Tight wordmark**
+- **System-ui body → JetBrains Mono wordmark, Newsreader wordmark**
+- **Inter Tight body → Fraunces wordmark, EB Garamond wordmark**
+
+When to use the same family for both:
+
+- **Editorial · Letter · Manifesto · Long Document** can collapse to a single family because the body voice carries the brand. The wordmark in these contexts is small, grounded, and earns its weight by being typeset rather than decorated.
+
+When to use a contrasting family:
+
+- **Bento Grid · Stat-Led · Workbench · Marquee Hero** — these archetypes lean visually generic (geometric grids, big numbers, browser-frame mockups) and need the wordmark to do the typographic differentiation work the body can't.
+
+**Avoid the same-family collapse on a SaaS page.** A Geist-only page where the wordmark is also Geist 600 reads as un-designed; the wordmark in Fraunces SemiBold over a Geist body costs nothing and adds the one typographic register that says *this is a brand*.
+
+## Scale
+
+Pick a ratio. The default for Hallmark work is **1.25** (major third). Build the scale from a 16px body, then clamp display sizes for responsive.
+
+```css
+:root {
+  --text-xs:   0.64rem;   /* 10.24px */
+  --text-sm:   0.8rem;    /* 12.8px  */
+  --text-base: 1rem;      /* 16px    */
+  --text-md:   1.25rem;   /* 20px    */
+  --text-lg:   1.5625rem; /* 25px    */
+  --text-xl:   1.9531rem; /* 31.25px */
+  --text-2xl:  2.4414rem;
+  --text-3xl:  3.0518rem;
+  --text-4xl:  3.8147rem;
+  --text-display: clamp(2.75rem, 5vw + 1rem, 5.25rem);
+}
+```
+
+**Display max — keep it ≤ 5.5rem (88 px).** Above that, hero headlines crowd themselves on 1280–1440 px viewports and require multi-line wrapping that almost always reads as drama, not gravity. Even on Manifesto / Brutal display-heavy themes, cap at 6rem (96 px). The exception is a single-line, single-word display (e.g. a stat) that occupies ≤ 12 ch — it can grow to 7rem. **Default emit format is `clamp(2.75rem, 5vw + 1rem, 5.25rem)`.**
+
+### Hero headline sizing — match size to copy length
+
+Count characters in the rendered hero `h1`. Pick the cap by bucket — the rule applies on top of any per-theme `--text-display` clamp:
+
+| Headline length | Size cap | Notes |
+| --- | --- | --- |
+| **≤ 20 chars** (e.g. *"Limitless"*, *"Made not generated"*) | full `--text-display`; single-word can grow to 7rem | Display-heavy themes only |
+| **21–50 chars** (the default sweet spot) | `--text-display` | If it wraps past 2 lines at 414 px, step down to `--text-display-s` |
+| **51–90 chars** | cap at `--text-display-s` | Strongly consider splitting into eyebrow + headline |
+| **> 90 chars** | rewrite shorter, or cap at `--text-4xl` with tighter leading | A 100-char headline at display size is the single most reliable AI tell |
+
+**Aggressive-display themes step down one rung when headline > 50 chars.** Brutal, Riso, and Manifesto clamp `--text-display` at 6.5–9rem — that ceiling is for ≤ 50-char statements only. Past 50 chars, route them to `--text-display-s` automatically. **When you write the headline yourself (no user-supplied copy), aim for ≤ 7 words and ≤ 50 chars from the start** — imperative or nominal phrase, never a gerund opener.
+
+Use no more than five sizes on a single page. If you need more hierarchy, use weight and colour, not another size.
+
+## Weights
+
+- Body: one weight (typically 400 or 350). Bold for emphasis only.
+- Headings: a weight that contrasts the body by at least 300 units. If body is 400, headings are 700 or 200 — not 500 or 600.
+- Never synthesise. Load the weight you need; don't rely on `font-weight: bold` against a single-weight file.
+
+## Required features
+
+- `font-display: swap` on every web font.
+- Match fallback metrics with `size-adjust`, `ascent-override`, `descent-override`, `line-gap-override` to prevent CLS.
+- Tabular numbers on any data display: `font-variant-numeric: tabular-nums;`.
+- Oldstyle figures for body copy where the face supports them: `font-variant-numeric: oldstyle-nums;`.
+- Proper typographic punctuation: `" " — … ‘ ’`. Never straight quotes, never `--` or `...`.
+
+## Body text rules
+
+- Minimum 16px. Below 14px is accessibility-hostile.
+- Line-height 1.5–1.65 on body copy, tighter (1.1–1.3) on display. **Floor for all-caps display heads (`text-transform: uppercase` on `.hero__display` / `.section__title` / `h1` / `h2`) is `1.0` — recommended `1.02–1.08`.** Below 1.0 the cap-tops of line N+1 collide with the baseline of line N (no descenders to cushion the gap); the comma + cap-D on a wrapped "PROMPT, / DIFFERENT" fuse into a single glyph blob. Condensed display faces (Anton, Inter Tight 900, Bebas Neue) make this worse. Gate 55 auto-fails the pattern.
+- Measure 45–75 characters (`max-width: 65ch`).
+- Never all-caps body copy. Never justified text without hyphenation. Never letter-spacing above 0.05em on body.
+
+## Headings rules
+
+- Tight tracking on display sizes (`letter-spacing: -0.02em` to `-0.04em` depending on the face).
+- Loose tracking on small caps / labels (`letter-spacing: 0.08em` to `0.14em`, `text-transform: uppercase`, use small caps if the face has them: `font-variant-caps: all-small-caps;`).
+- Skip no levels. `h1` → `h2` → `h3`. Style them visually how you like, but keep semantic order.
+
+## Bans
+
+- No Inter, no Roboto, no Open Sans. No system stack as the *only* stack.
+- No gradient text on headings (`background-clip: text` with a gradient fill).
+- No single-font pages.
+- No all-caps paragraphs.
+- No font-size below 14px for body copy, below 10px anywhere.
+- No hard-synthesised bold or italic.
+- **No more than three font families on a single page.** Display + body + one outlier is the ceiling. Four families = slop. Audit gate.
+- No outlier face used in more than two slots. Wordmark + hero stat is the canonical pair; if you reach for a third slot, drop it back to the body face.

package/control-plane/scripts/skills/hallmark/references/upstream/recipes.md

@@ -0,0 +1,186 @@
+# Recipes — copy-paste prompts that ship Hallmark output
+
+Eight worked briefs you can paste into Claude Code, Cursor, or Codex with the Hallmark skill installed. Each shows the prompt verbatim, the audience/use/tone the skill inferred, the macrostructure + theme + enrichment it picked, and a one-paragraph excerpt of the output. Live page links are included where the test exists in [`site/_tests/`](https://github.com/nutlope/hallmark/tree/main/site/_tests/).
+
+The first recipe is the **canonical try-it prompt** — paste it into a fresh project to verify the skill is installed and discover the flow before reading anything else.
+
+---
+
+## 00 · Try it · Coffeebox
+
+**Prompt** (copy/paste verbatim):
+
+> *"Build me a landing page for Coffeebox — a small-batch coffee subscription. Roast on Sunday, ship on Monday, drink Tuesday. Audience: people who already buy good coffee and want fewer trips to the shop. Tone: warm, hand-set, editorial — like a small café's chalkboard."*
+
+**Inferred trio:** explicit (audience: serious-coffee buyers · use: subscribe · tone: editorial-warm).
+
+**Picks:** Long Document · **Linen** (warm-paper roman-serif) · Tier-B hand-built SVG (a small coffee-bean icon, optional).
+
+**Excerpt of the output:**
+
+> *"Coffeebox · est. 2026 · n.º 12.* The first roast leaves the drum at 6:14 a.m. Sunday. By Monday morning it's in a paper bag in your post box. By Tuesday the kitchen smells like a café. Subscribe, skip a week, change the roast — all from the email. We bake what we baked yesterday. We ship what shipped well. We answer the email ourselves."
+
+**Why this is the canonical try-it:** the brief has explicit context (no design-context-gate friction), an editorial tone (different from any AI-default landing page), and a domain (coffee subscription) that has zero overlap with SaaS/dev-tool clichés. If Hallmark produces *Linen-with-italic-Cormorant-and-warm-paper* for this prompt, the skill is wired correctly.
+
+---
+
+## 01 · Tide · Indie podcast
+
+**Prompt:**
+
+> *"Design a landing page for Tide — an indie podcast about long-form interviews with small-studio designers. Just go ahead, pick the rest yourself."*
+
+**Inferred trio** (the user opted out): audience = designers, design-curious listeners · use = listen + subscribe · tone = quiet editorial.
+
+**Picks:** Letter · **Salon** (warm cream paper, IBM Plex Mono masthead, Cormorant Garamond body, warm-amber caret) · no enrichment (typography only).
+
+**Excerpt:**
+
+> *"Dear listener, Tide is a podcast about how small studios actually work. The bookings, the unsent invoices, the day a senior designer leaves and you sit in the office not knowing what to say to the four people who stayed."* The hero is the salutation. Below: three paragraphs of host-voice, a sign-off, then a single row of "listen where you listen" links — Apple, Spotify, Pocket Casts, Overcast, RSS. No mockups. No demo. The voice carries the brand.
+
+**Live:** [`_tests/01-tide-podcast/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/01-tide-podcast/index.html)
+
+---
+
+## 02 · Streampipe · Open-source CLI
+
+**Prompt:**
+
+> *"Build me a landing page for Streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin. Filter, transform, route. Composes with anything that emits lines. Audience: developers. Use: install + read docs. Tone: technical. Use the Terminal theme."*
+
+**Inferred trio:** explicit. **Theme requested.**
+
+**Picks:** Long Document · **Terminal** (dark phosphor-green, mono everywhere) · Tier-A inline CSS-art terminal blocks (no Lottie, no real video, no sticky pin — embedded inline in the prose).
+
+**Excerpt:**
+
+> *"$ streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin."* Then a paragraph of prose explaining what it does, an inline `<pre>` showing `tail -f access.log | streampipe parse --format nginx --filter 'status >= 500' --out json` with three sample JSON output lines, then a second paragraph (Rust, 1.2 MB binary, no daemon, no buffer). Below: install section (three snippets — brew · cargo · curl), three numbered notes on how it works, a six-row flag table. Pure CSS, no scripts.
+
+**Live:** [`_tests/02-streampipe-cli/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/02-streampipe-cli/index.html)
+
+---
+
+## 03 · Maple Street Bread · Artisan bakery
+
+**Prompt:**
+
+> *"Build a landing page for Maple Street Bread — a small artisan bakery in Lisbon. Sourdough, slow, by hand. We open at seven, thirty loaves, gone by noon, no online orders. Audience: locals. Use: see what we bake, find us. Tone: warm, hand-set."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Catalogue · **Almanac** (warm parchment paper, IM Fell roman-serif display, warm-amber accent) · Tier-A hand-built inline-SVG bread silhouettes (one per item, 96 px, no animation).
+
+**Excerpt:**
+
+> Plate-banner masthead: *"Maple Street Bread · Lisbon · est. 2026 · n.º 47 · sourdough by hand."* Then a centred section: *"Today's bake — Saturday, 6:14 a.m., eight breads, gone by noon."* Below: a 2-column catalogue grid of eight breads (Country sourdough · Baguette tradition · Focaccia rosemary · Boule miche · Rye dark · Brioche feuilletée · Walnut levain · Bola d'óleo). Each row carries a 96-px bread silhouette, the name in IM Fell, a one-line description, and a price (or "sold out"). Visit and hours in a centred almanac panel at the bottom. No CTA — the brief is "see what's available + visit."
+
+**Live:** [`_tests/03-maple-bakery/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/03-maple-bakery/index.html)
+
+---
+
+## 04 · Meridian · Studio manifesto
+
+**Prompt:**
+
+> *"A studio manifesto for Meridian — a small environmental-products design practice in Lisbon. Declarative, no flashy stuff."*
+
+**Inferred trio** (partial): audience = practice peers + clients · use = read it + sign on or move on · tone = declarative editorial.
+
+**Picks:** Quote-Led · **Brutal** (near-black paper, Druk-style condensed display, single yellow strike accent) · no enrichment.
+
+**Excerpt:**
+
+> A single twenty-word pull-quote: *"We make products that don't outlive their use"* — with a yellow strike-through behind "outlive." Attribution beneath: *"— The studio · the position we open with · this is the page."* Below the bleed-yellow rule, four numbered principles (Fewer things, made well · Material is the brief · Repair before replace · Slow is the deliverable), each with one paragraph of body copy. Final § Working rules — five terse operational statements (the shop runs on a four-day week · we answer the email ourselves · etc.). No CTA, no testimonials, no roadmap.
+
+**Live:** [`_tests/04-meridian-manifesto/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/04-meridian-manifesto/index.html)
+
+---
+
+## 05 · Tracejam · SaaS observability
+
+**Prompt:**
+
+> *"Build me a landing page for Tracejam — a tracing/observability tool for distributed systems. Audience: SREs and platform engineers. Use case: try it / contact sales. Tone: technical."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Workbench · **Midnight** (dark cool paper, Geist Mono display, phosphor-cyan accent) · Tier-A pure-CSS sticky trace panel (3-state, swaps on scroll — no clipped browser frame).
+
+**Excerpt:**
+
+> *"Tracejam · v0.4 · For SREs &amp; platform engineers. Distributed tracing that explains itself."* Hero left-aligned with two CTAs (Try it free / Talk to sales). On the right, a sample trace card with five spans — auth.verify, pricing.quote (red, regressed), rates.fx (orange, warning), ledger.write — bars rendered as flex children. Below: a sticky-walkthrough section with three steps (open · find · read), each with a one-paragraph body and a small `$ tracejam ...` command. The right column carries a pinned trace panel with a "REGRESSED" chip and a "WHY" explainer in plain text. Eight integrations strip, three-tier pricing, single-line colophon.
+
+**Live:** [`_tests/05-tracejam-saas/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/05-tracejam-saas/index.html)
+
+---
+
+## 06 · Anya · Personal one-pager
+
+**Prompt:**
+
+> *"Personal site for Anya — software architect in Lisbon. Don't ask, just figure it out."*
+
+**Inferred trio** (the user opted out): audience = engineering hiring managers · use = read who I am, see my work · tone = austere, italic-editorial.
+
+**Picks:** Index-First · **Plain** (pure-white paper #ffffff, Inter Tight display-heavy, deep ink-blue accent) · no enrichment.
+
+**Excerpt:**
+
+> Sticky left sidebar with a numbered TOC: *00 Index · 01 Now · 02 Years · 03 Writing · 04 Reach.* Each section in the right column starts with its own num + label and a clamp-set H2. *"00 · Index"* opens with *"A small, scannable index of who I am and what I do."* — followed by a two-paragraph bio. *"01 · Now"* covers consulting two engagements at a time on payment systems and monolith-to-services migrations. *"02 · Years"* is a tabular work history (Stripe → Monzo → Knot → independent). *"03 · Writing"* lists five linked pieces with date columns. *"04 · Reach"* is a four-cell contact grid (email · GitHub · LinkedIn · Mastodon).
+
+**Live:** [`_tests/06-anya-portfolio/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/06-anya-portfolio/index.html)
+
+---
+
+## 07 · Foundry · Compliance SaaS
+
+**Prompt:**
+
+> *"Build me a landing page for Foundry — SOC 2 and ISO 27001 compliance automation for B2B SaaS. Show: how many companies got compliant, what it costs, who uses it. Audience: founders + CTOs. Tone: technical but trustworthy."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Bento Grid · **Newsprint** (warm-cream paper, Source Serif 4 display, warm-deep-red accent) · Tier-A pure-CSS logo grid (eight wordmark placeholders, mono).
+
+**Excerpt:**
+
+> Newspaper-banner masthead with the wordmark centred. Hero left-bias: *"Compliance, ground out in **days**, not in months."* — the word "days" set in red italic. Right: a pull-quote panel with a CTO testimonial. Below: a 6-tile bento — (1) the "847." anchor stat with a one-line caption, (2) eight customer wordmarks in a 4×2 logo grid, (3) three-tier pricing snippet (Starter $299 · Team $899 popular · Scale custom), (4) a second testimonial pull-quote, (5) a six-row "what's automated" feat-list, (6) a six-question FAQ teaser. Final CTA strip: *"Start the trial. Cancel before the first invoice if it's not ready."* Single-line colophon.
+
+**Live:** [`_tests/07-foundry-compliance/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/07-foundry-compliance/index.html)
+
+---
+
+## 08 · Cohort · Cohort-based courses
+
+**Prompt:**
+
+> *"Build a landing page for Cohort — the platform for cohort-based courses. Run live courses with 30 to 500 students. Built for educators, not LMS sales teams. Audience: course operators + indie creators. Tone: warm, salon-room, editorial."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Stat-Led · **Linen** (warm beige paper, Inter Tight geometric-sans, warm-amber accent) · no enrichment (typography only — the brief's "30–500" range is the visual).
+
+**Excerpt:**
+
+> Centred eyebrow: *"Built for educators · not LMS sales teams."* Hero stat at 22 rem: **"30 — 500"** (with the dash in warm-amber). Headline: *"Live courses, the size your roster actually is."* Sub: *"Cohort runs courses with thirty to five hundred students at once — the size of a real classroom, the size of a real lecture, and a few sizes between. With a date, a roster, and a room."* Below: three supporting stats (186 cohorts run · 93 % finish-rate · 4.7/5 operator NPS). Two operator testimonials side-by-side. Two-tier pricing (First cohort free · Operator $199/mo). Single CTA strip and colophon. No marquee, no card-stack — the brief carried by the typography.
+
+**Live:** [`_tests/08-cohort-courses/`](https://github.com/nutlope/hallmark/blob/main/site/_tests/08-cohort-courses/index.html)
+
+---
+
+## How the recipes are organised
+
+Every recipe shares the same four lines so you can scan a brief and immediately see *which combination Hallmark picks for what*:
+
+1. **Prompt** — verbatim, copy/paste-ready.
+2. **Inferred trio** — what the design-context-gate produces (audience · use · tone). Marked `explicit` if the user provided all three; `the user opted out` if not.
+3. **Picks** — macrostructure · theme · enrichment archetype.
+4. **Excerpt** — one paragraph of the produced copy or layout, so you can verify the output matches the brief without running the skill yet.
+
+When generating something new, look for the closest match in this file and **note what's different** between your brief and the recipe. The macrostructure pick is usually inherited; the theme often shifts (per the diversification rule); enrichment may change tier.
+
+## What the recipes are *not*
+
+- Not templates. Hallmark's whole point is structural variety — duplicating a recipe verbatim is the **Specimen-fall-through** anti-pattern (gate 23 in [`SKILL.md`](../../SKILL.md)).
+- Not fixed picks. Two consecutive runs of recipe 00 (Coffeebox) on the same project should produce *different* macrostructures or themes — the [`.hallmark/log.json`](../../SKILL.md) project memory enforces this.
+- Not exhaustive. The 21 macrostructures × 16 themes × 8 enrichment archetypes = 2,688 distinct fingerprints. The 9 recipes here are a starter set; the next 50 are yours to discover.

package/control-plane/scripts/skills/hallmark/references/upstream/study-examples.md

@@ -0,0 +1,176 @@
+# `hallmark study` — three worked examples
+
+How `study` reads a screenshot the user admires, returns a diagnosis, and (optionally) rebuilds the user's content with the extracted DNA. Each worked example below shows: what the user pasted · what the skill names · what it refuses to do · what it produces.
+
+The whole point of `study`: extract **structural DNA** (macrostructure + archetypes + type-pairing role + colour anchor + rhythm), **never pixels**. If the user wants a 1:1 copy, they want a different tool. Hallmark hands them a diagnosis and lets them keep the bones.
+
+---
+
+## Example A · A Pentagram-style editorial portfolio
+
+**What the user pastes:** a screenshot of a New York studio's portfolio site — large italic-serif name in the top-left margin, numbered project list flowing down the page, generous warm-cream paper, a single warm-orange accent on the active project, a hairline rule between rows. (User says: *"I want my portfolio to feel like this.")*
+
+### Refuse-or-proceed check
+
+Public reference for inspiration → proceed. (Refusal heuristics fire on: paid-template-marketplace listings, copy-protected portfolios. None match.)
+
+### Diagnosis report (what `study` returns first)
+
+> **Macrostructure:** **Specimen** (numbered left-margin labels + huge italic serif + asymmetric spans + typographic-only CTA).
+>
+> **Hero archetype:** H4 Margin-Number Display — the page's only anchor is a vertical column of two-digit indices.
+>
+> **Pitch archetype:** none. The work is the pitch.
+>
+> **Footer archetype:** Ft1 Single-Line Colophon — studio name, year, contact, three links, no nav.
+>
+> **Display family role:** italic editorial serif (high optical size, soft axis, ink-black). **Body family role:** geometric sans (humanist Inter-Tight-or-similar at 350-400 weight). Two free candidates: *Fraunces* italic display + *Geist* body. One paid candidate the user might confirm: *Tiempos Headline* + *Söhne*. The skill names *roles*, not exact font IDs — visual font ID is unreliable.
+>
+> **Surface lightness band:** light (paper L ≈ 96%). Slight warm tint at hue 80 — Pentagram-warm cream, not stark white.
+>
+> **Accent hue band + chroma:** warm-orange ~25-30°, low chroma (≤ 0.13), used at < 5% of viewport. One accent, applied to active state and the one number the brand wants the visitor to remember.
+>
+> **Density verdict:** sparse. ~3-4 macro elements on the first viewport. Generous vertical margin between rows (≥ `--space-3xl`).
+>
+> **Type-pairing role:** italic-display + sans-body — the canonical editorial pairing.
+>
+> **Two anti-patterns the screenshot has** that you should NOT carry over:
+>
+> 1. The hover-state on the number-label uses a slow ease-in-out 800 ms colour fade. Per `microinteractions.md` § The timing canon, hover state should be 150–200 ms. Carry the *idea* (colour-shift on hover); shorten the *duration*.
+> 2. The footer text is set at 11 px with 0.06em tracking — under the 14 px floor for body copy. Bump to 12-13 px on rebuild, keep the tracking.
+
+### Confirmation question
+
+> *"Adopt this DNA wholesale, or change one axis? For example, I could keep the macrostructure (Specimen) but pick a theme that better matches your work — if your tone is more ink-blue and B2B, I'd suggest **Plain** (pure-white paper) instead of the warm-cream **Specimen** theme."*
+
+### What `study` builds when the user says "go"
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Specimen · H4 hero knobs: number-column=margin, alignment=left-bias
+ * theme: Specimen · accent: warm-orange ~3% · enrichment: none
+ * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (free pairing applied)
+ */
+```
+
+Output: the user's actual portfolio entries arranged in a numbered-margin column with italic-Fraunces titles and Geist-body summaries. Hover delays shortened to 200 ms. Footer text bumped to 12 px. The bones come from the screenshot; the words and projects come from the user.
+
+---
+
+## Example B · A Klim-Type-Foundry-leaning specimen
+
+**What the user pastes:** a screenshot of a type-specimen page — full-bleed black paper, single huge geometric-sans display character ("R") tilted -2°, a ruled grid behind it, a footer-band with the typeface name, weight, OpenType features, and a tiny set of glyph callouts. (User says: *"This is the energy I want for our agency rebrand.")*
+
+### Refuse-or-proceed check
+
+Type specimens are typically published references; proceed. (If the screenshot were a paid font foundry's marketing page with an explicit "preview is licensed" watermark, the skill would refuse and ask the user to bring an unconfirmed reference.)
+
+### Diagnosis report
+
+> **Macrostructure:** **Type Specimen** (single character or word centred + ruled grid + footer-band of metadata).
+>
+> **Hero archetype:** H9 Single-Glyph — the entire above-the-fold is one letterform.
+>
+> **Pitch archetype:** none on the first viewport. The page is *the work being specified*. Pitch (if any) lives below the fold as supporting paragraphs.
+>
+> **Footer archetype:** Ft3 Tabular-Specimen — name · weight · OpenType features · designer credit.
+>
+> **Display family role:** geometric-sans-heavy (display-display, weights 800-900). **Body family role:** the same sans at 400 — single-font specimen pages are allowed when the single font *is* the design (per `typography.md`). Free candidate: *Bricolage Grotesque 800*. Paid candidate: *Druk* or *NaN Jaune*. *Refuse to guess the exact paid font ID.*
+>
+> **Surface lightness band:** dark (paper L ≈ 12%). The dark is uniform across the viewport — no gradient.
+>
+> **Accent hue band + chroma:** chromatic-other — single hot-orange callout at ≈ 0.18 chroma, used on **one** OpenType-feature label. Even in a stark specimen, the rule "accent < 5% of viewport" holds.
+>
+> **Density verdict:** ultra-sparse. One element above the fold. Density only increases below.
+>
+> **Type-pairing role:** single-family specimen (single-font is the design). Body and display the same family at different weights.
+>
+> **Two anti-patterns the screenshot has** to NOT carry over:
+>
+> 1. The footer-band uses light-grey text (oklch ~75% lightness) on near-black paper. Contrast ratio ~3.2:1 — fails WCAG AA for body. Bump to oklch ~88% on rebuild.
+> 2. The grid lines behind the glyph are at 1 px solid white at 0.4 opacity. On a 4K display this becomes a sub-pixel that disappears or aliases. Use 1 px solid + colour-mix down to 35% lightness instead — keeps visibility across pixel densities.
+
+### Confirmation question
+
+> *"This DNA is for a specimen page, not a marketing page. If you're rebranding an agency, the glyph hero will be impressive on the first visit and pointless after. Suggested adaptation: Type Specimen as the homepage, then a Long Document or Workbench pattern for the about / case-studies / contact pages. Pick: keep all-Specimen, or hybrid?"*
+
+### What `study` builds (hybrid path)
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Type Specimen · H9 hero knobs: glyph=user-mark, tilt=-2deg, grid=1px-soft
+ * theme: Manifesto · accent: hot-orange ~3% · enrichment: none
+ * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (Bricolage 800 free)
+ */
+```
+
+The homepage emits the agency's mark in 22-rem Bricolage 800, ruled grid behind, single-line metadata footer. The about and case-study pages inherit the dark-paper + geometric-sans tokens but switch to **Workbench** macrostructure (left-margin index + 1fr content). Brand consistency, structural variety.
+
+---
+
+## Example C · A small-studio personal site (Rauno-Freiberg-style)
+
+**What the user pastes:** a screenshot of a personal designer-engineer site — dark-mode paper, a small italic-serif name in the top-left, a single demo embed at the centre (CSS-art clock that ticks), a writing list below. (User says: *"I want my own personal site to feel like this.")*
+
+### Refuse-or-proceed check
+
+An ambiguous source is the edge case here. Per `study.md` § Refusal heuristics: when you can't tell whether the source is the user's own work or someone else's, ask first.
+
+> *"Is this your own work, a public reference for inspiration, or someone else's live site? If it's someone else's live site, I'll extract the DNA at the structural level only — no copy, no demos, no font IDs — and you'll bring your own content. If it's a paid portfolio template, I won't reproduce it."*
+
+User confirms: public reference for inspiration → proceed with DNA extraction only.
+
+### Diagnosis report
+
+> **Macrostructure:** **Long Document** with a centred demo as the hero archetype.
+>
+> **Hero archetype:** H5 Centered-Demo — a single hand-built artefact (CSS art, SVG illustration, declarative animation) sized at ~24 rem, centred on the page, no other hero copy above it.
+>
+> **Pitch archetype:** P3 List-of-Writings — title + date + 1-line summary, in a tabular column.
+>
+> **Footer archetype:** Ft1 Single-Line Colophon.
+>
+> **Display family role:** italic editorial serif. **Body family role:** geometric sans, body weight 400. Free candidate pairing: *Fraunces* italic + *Geist*.
+>
+> **Surface lightness band:** dark (paper L ≈ 16%). Slight cool tint at hue 240. Inks at ~90-95% L, also slight cool.
+>
+> **Accent hue band + chroma:** chromatic-other — green at hue 145, ≈ 0.14 chroma. Used on the active demo's signal element (the ticking dot), nowhere else.
+>
+> **Density verdict:** sparse-medium. Hero demo + ~12-line writing list above the fold.
+>
+> **Type-pairing role:** italic-display-with-sans-body — same as Specimen, just on dark paper.
+>
+> **One anti-pattern the screenshot has** to NOT carry over:
+>
+> 1. The CSS-art clock loops at 1 fps with no `prefers-reduced-motion` fallback. **Always pair declarative animation with a reduced-motion alternative** (`microinteractions.md` § Reduced motion is a first-class state, not an afterthought).
+>
+> One thing the screenshot does *better than most* and you SHOULD carry over:
+>
+> 1. The italic name in the top-left has a baseline at the same y-position as the centred demo's vertical centre — a subtle horizontal-baseline alignment that makes the page feel composed rather than stacked. Carry this; it's invisible until removed.
+
+### Confirmation question
+
+> *"The DNA is portable: dark paper · italic-Fraunces name · centred demo · cool-green accent. Two questions before I build: (1) what's your demo? — I can hand-build it as Tier-A CSS art if you describe it, or you can paste an existing animation. (2) do you have ~5 writings to seed the list, or should I leave a placeholder section?"*
+
+### What `study` builds when the user provides their own demo + writings
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Long Document · H5 hero knobs: demo=centered, size=24rem
+ * theme: Midnight · accent: forest-green ~3% · enrichment: Tier-A custom-craft (user-supplied recipe)
+ * studied: yes · DNA-source: user reference · with reduced-motion fallback
+ */
+```
+
+Output: the user's actual name in italic-Fraunces top-left, their demo (e.g. an ambient breathing-loop) hand-built as CSS art with an explicit `@media (prefers-reduced-motion: reduce)` fallback, their writings tabulated below in Geist body. The bones from the screenshot; the demo and writings from the user. **No pixel-faithful reproduction.**
+
+---
+
+## What `study` doesn't do (worth restating)
+
+1. **Names the font role, not the font ID.** Visual font identification is unreliable. The skill proposes one or two real candidates from the canon and asks the user to confirm.
+2. **Never copies pixels.** The DNA is the macrostructure + archetype + colour-anchor + type-pairing — not the dress.
+3. **Refuses the obvious bad sources.** Paid-template-marketplace listings; copy-protected portfolios without permission.
+4. **Always disclosures the substitutions.** When the screenshot's font is paid (Tiempos / Söhne / Druk) and the user hasn't confirmed a licence, the skill names a free understudy (Fraunces / Inter Tight / Bricolage Grotesque) and *says it's substituting*.
+
+These three examples cover the most common categories of `study` request: an editorial portfolio, a type-specimen statement page, and a small personal site. The protocol is the same for every screenshot — refuse-or-proceed, diagnose, confirm, build. See [`study.md`](../study.md) for the full protocol.