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

package/control-plane/scripts/skills/hallmark/references/themes/carnival.md

@@ -0,0 +1,301 @@
+# Theme — Carnival
+
+Loud-maximalist editorial. **Duo-tone accent system across six named palette drops** (each its own mood), chunky variable display, decorative ornaments, hard-offset shadows, tinted paper. The loud sibling to Riso / Manifesto / Brutal — but **decorative, not raw**.
+
+Loaded eagerly by SKILL.md Step 3 whenever the catalog pick is `carnival`. The default palette ("Cold Snap") and font stack live in [`site/css/tokens.css`](../upstream/tokens.css) under `[data-theme="carnival"]`; this file carries the **palette drops** (six variants) plus the rules that tokens cannot encode.
+
+## Axes (diversification)
+
+- **Paper band** — light (`L 88–95%`, tinted — varies by drop)
+- **Display style** — **display-heavy** (Big Shoulders Display 800, variable-width axis)
+- **Accent hue** — **per-drop**. Each drop has its own duo-tone hue pair (warm+warm, cool+warm, warm+cool, etc.). The drop name is recorded alongside the theme name in the diversification log so consecutive builds rotate drops, not just themes.
+
+## Palette drops
+
+A drop is a named duo-tone palette that preserves Carnival's structural signature (saturated accent-1 + complementary accent-2 + tinted paper + deep ink) while rotating hue. **Every Carnival build picks one drop.** The catalog of six:
+
+### Drop 01 · Cold Snap *(default)*
+
+Warm + warm. Indie record-label, winter, scrappy. The canonical Carnival.
+
+- `--color-paper: oklch(92% 0.045 50)` — warm pink-cream
+- `--color-paper-2: oklch(88% 0.050 45)`
+- `--color-paper-3: oklch(82% 0.060 40)`
+- `--color-ink: oklch(18% 0.080 20)` — deep aubergine
+- `--color-ink-2: oklch(28% 0.060 25)`
+- `--color-muted: oklch(45% 0.05 30)`
+- `--color-rule: oklch(40% 0.18 25)` — oxblood rules (decorative)
+- `--color-accent: oklch(86% 0.18 95)` — mustard
+- `--color-accent-2: oklch(40% 0.21 25)` — oxblood
+- `--color-accent-ink: oklch(18% 0.080 20)`
+- `--color-focus: oklch(40% 0.21 25)`
+
+**When to pick:** independent music · winter releases · DIY scrappy · the brief mentions cassettes, vinyl, EPs.
+
+### Drop 02 · Citrus Riot
+
+Loud + neon. 90s zine, summer, electric. Lime against magenta — the hardest collision in the catalogue.
+
+- `--color-paper: oklch(94% 0.040 85)` — pale acid cream
+- `--color-paper-2: oklch(90% 0.048 82)`
+- `--color-paper-3: oklch(84% 0.055 80)`
+- `--color-ink: oklch(20% 0.07 145)` — deep forest
+- `--color-ink-2: oklch(32% 0.05 140)`
+- `--color-muted: oklch(48% 0.04 130)`
+- `--color-rule: oklch(28% 0.28 350)` — deep magenta rules
+- `--color-accent: oklch(82% 0.20 130)` — chartreuse-lime
+- `--color-accent-2: oklch(28% 0.28 350)` — deep magenta (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.07 145)`
+- `--color-focus: oklch(28% 0.28 350)`
+
+**When to pick:** zine collectives · summer drops · skate / DIY culture · briefs that want LOUD without referencing music.
+
+### Drop 03 · Diner Sign
+
+Americana. Cream + cherry red + navy. Postwar diner, road trip, neon-and-chrome.
+
+- `--color-paper: oklch(95% 0.035 90)` — bright cream
+- `--color-paper-2: oklch(91% 0.042 88)`
+- `--color-paper-3: oklch(86% 0.050 85)`
+- `--color-ink: oklch(16% 0.04 30)` — black-brown
+- `--color-ink-2: oklch(28% 0.05 30)`
+- `--color-muted: oklch(45% 0.04 35)`
+- `--color-rule: oklch(30% 0.16 250)` — navy rules
+- `--color-accent: oklch(60% 0.22 25)` — cherry red
+- `--color-accent-2: oklch(30% 0.16 250)` — navy
+- `--color-accent-ink: oklch(95% 0.035 90)`
+- `--color-focus: oklch(30% 0.16 250)`
+
+**When to pick:** food + drink · hospitality · vintage Americana · briefs mentioning burgers, milkshakes, motels, roadside.
+
+### Drop 04 · Studio Night
+
+Cool + cool. Dusk warmth, cyan + plum. Late-night booth, blue hour, podcast studio at midnight.
+
+- `--color-paper: oklch(88% 0.05 25)` — warm dusk pink
+- `--color-paper-2: oklch(84% 0.055 22)`
+- `--color-paper-3: oklch(78% 0.06 20)`
+- `--color-ink: oklch(20% 0.05 270)` — deep navy-black
+- `--color-ink-2: oklch(32% 0.045 265)`
+- `--color-muted: oklch(48% 0.04 260)`
+- `--color-rule: oklch(24% 0.18 320)` — deep plum rules
+- `--color-accent: oklch(78% 0.18 220)` — cyan
+- `--color-accent-2: oklch(24% 0.18 320)` — deep plum (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.05 270)`
+- `--color-focus: oklch(24% 0.18 320)`
+
+**When to pick:** late-night radio · podcasts about anything · music + atmosphere · briefs mentioning "late", "after dark", "blue hour", "moonlight".
+
+### Drop 05 · Aqua Park
+
+Cool + warm. Turquoise against coral. Summer pool, motel sign, vacation.
+
+- `--color-paper: oklch(94% 0.040 180)` — pale aqua-cream
+- `--color-paper-2: oklch(90% 0.048 178)`
+- `--color-paper-3: oklch(84% 0.055 175)`
+- `--color-ink: oklch(20% 0.06 200)` — deep teal
+- `--color-ink-2: oklch(32% 0.05 198)`
+- `--color-muted: oklch(48% 0.04 195)`
+- `--color-rule: oklch(36% 0.24 35)` — deep coral rules
+- `--color-accent: oklch(72% 0.16 195)` — turquoise
+- `--color-accent-2: oklch(36% 0.24 35)` — deep coral (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.06 200)`
+- `--color-focus: oklch(36% 0.24 35)`
+
+**When to pick:** summer brands · vacation / hospitality · skate / surf / pool · briefs mentioning summer, beach, motel, sun.
+
+### Drop 06 · Pressroom
+
+Warm + cool. Amber-gold against slate-blue. 1950s journalism, print shop, broadsheet weight.
+
+- `--color-paper: oklch(89% 0.025 65)` — warm slate-cream
+- `--color-paper-2: oklch(85% 0.030 62)`
+- `--color-paper-3: oklch(79% 0.035 58)`
+- `--color-ink: oklch(16% 0.02 60)` — ink-black
+- `--color-ink-2: oklch(28% 0.025 58)`
+- `--color-muted: oklch(45% 0.025 55)`
+- `--color-rule: oklch(34% 0.10 240)` — slate-blue rules
+- `--color-accent: oklch(78% 0.18 75)` — amber-gold
+- `--color-accent-2: oklch(34% 0.10 240)` — slate-blue
+- `--color-accent-ink: oklch(16% 0.02 60)`
+- `--color-focus: oklch(34% 0.10 240)`
+
+**When to pick:** journalism · newsletters · editorial / opinion · briefs mentioning "press", "newspaper", "broadsheet", "subscription".
+
+### Drop rotation rule
+
+The diversification log (`/.hallmark/log.json`) records the drop alongside the theme: `"theme": "carnival", "drop": "studio-night"`. **A new Carnival build picks a drop that hasn't appeared in the last 3 entries.** If only Cold Snap is in the log, any of the other five is valid. If the brief contains a strong drop signal (see "when to pick" above), honour the signal even if it tightens diversification.
+
+### Pick the drop by domain first
+
+Match the brief's **domain** before reaching for the loudest palette:
+
+- food / drink / hospitality / street market → **Diner Sign** (or Cold Snap)
+- independent music / labels / EPs → **Cold Snap** (or Pressroom)
+- late-night / radio / podcast / after-dark → **Studio Night**
+- summer / pool / beach / vacation → **Aqua Park**
+- zine / skate / DIY / deliberately chaotic → **Citrus Riot**
+- journalism / newsletter / editorial → **Pressroom**
+
+Citrus Riot and Aqua Park are the highest-chroma drops — reach for them when the brief genuinely *wants* maximum loudness, not as a default. A food market reads better in Diner Sign than in lime-on-magenta.
+
+### When to construct a custom drop instead
+
+If the brief explicitly names a brand colour that doesn't fit any catalog drop — e.g. *"our brand is teal and beige"* — route to the **custom theme** branch (see `custom-theme.md`) instead of stretching a Carnival drop. Drops are curated, not infinite. Six is the right number for now.
+
+## Reference register
+
+Dropout TV · Fly.io · Stones Throw Records · Third Man Records · Drag City · Moodelier · Kelsey Dake · Bold Monday.
+
+The aesthetic: independent music labels, comedy networks, illustrator portfolios, hot-sauce brands, indie game studios. Things with **character**. Things that print posters as a side hustle. Things that sound loud out loud.
+
+**Patron-saint reference (internal):** *Dropout TV homepage* + *Stones Throw artist pages*. When in doubt about decorative density, ask "would Dropout or Stones Throw run this much density?" If less, add ornaments. If more, you've gone too far.
+
+## Signature moves
+
+The theme's seven tics. A Carnival build should exhibit at least five of them.
+
+1. **Duo-tone accent system.** Sections alternate which accent fills them. Section 1 fills with `--color-accent` (mustard); section 2 fills with `--color-accent-2` (oxblood); section 3 mustard again; etc. One section never shows both — they are *competing*, not blended.
+
+   ```css
+   .section:nth-of-type(odd)  { --section-fill: var(--color-accent); }
+   .section:nth-of-type(even) { --section-fill: var(--color-accent-2); }
+   ```
+
+2. **Decorative ornaments.** Use `✱` (asterisk operator), `❋` (heavy six-petalled), `◆` (black diamond) as bullets, section dividers, and rhythmic spacers. Patterns:
+   - Section dividers: `✱ ✱ ✱ ✱` (repeated 4×, centred)
+   - List bullets: `❋` (replaces • / disc)
+   - Section heading prefixes: `◆ Section Name` (left-aligned, ornament in accent colour)
+
+3. **Layered colour blocks that bleed off the page edge.** Accent fills extend 24px past the page max-width on the left or right, so they read as **posters pinned to the wall**, not as buttons.
+
+   ```css
+   .colour-block { margin-inline: calc(var(--page-gutter) * -1); padding-inline: var(--page-gutter); }
+   ```
+
+4. **Hard-offset drop shadow.** Every card, CTA, and image gets `box-shadow: 4px 4px 0 var(--color-ink)`. No soft shadows ever. The shadow is **flat ink, offset**. This is the single most-recognisable Carnival move.
+
+5. **All-caps headlines with Big Shoulders variable-width, tightly tracked.** `font-variation-settings: "wdth" 110, "wght" 800;`. Track them **tight**, not loose: `letter-spacing: -0.005em` on the hero word, `0.02em` on section heads. The loose `0.04em` look reads as AI-spread and is reserved **only** for the marquee banner (where horizontal spread is the point). Keep line-height tight too: `0.82` for single hero words, `0.92` for multi-line heads. The effect is a marquee poster set by a typographer, not a stretched default.
+
+6. **Halftone pattern fills** in placeholder image regions. Pure CSS, no images:
+
+   ```css
+   .halftone {
+     background-image: radial-gradient(var(--color-ink) 1.5px, transparent 1.5px);
+     background-size: 12px 12px;
+   }
+   ```
+
+   Used wherever the page would otherwise have a photo placeholder.
+
+7. **Marquee scroll** on banner OR footer with decorative dot separators. *"NEW EP ◆ OUT NOW ◆ ON CASSETTE ◆ BLUE VINYL ◆ NEW EP ◆..."* — horizontal scroll, honours `prefers-reduced-motion: reduce` (freeze at static state).
+
+## Layout pitfalls (must avoid)
+
+Carnival's dense visual language has known traps. Read this list **before** writing a card layout — these are mistakes that have happened in earlier builds and shipped looking broken.
+
+1. **Halftone portrait + side-by-side text in a narrow card → text gets covered.** When pairing a halftone "host portrait" / "artist portrait" with a show / artist name in the same card, **never use a 2-column grid where the content column can collapse below 200 px**. On a 3-up `repeat(3, 1fr)` desktop grid, the content column inside each card is ~150–180 px wide and a 5 rem portrait squeezes the title into overlap. The safe patterns:
+   - **Vertical stack** (portrait on top, content below — the portrait sits naturally in the top-left of the card content area because of card padding). This is the default for portrait-paired cards.
+   - **Side-by-side ONLY at 2-up or 1-up grids** where the content column has ≥ 250 px to breathe.
+   - **Sticker corner** — portrait positioned `absolute; top: 0; right: 0` as a small badge, with text content flowing full-width below.
+
+   Concretely: if the card is in a `repeat(3, 1fr)` grid and includes a portrait + title pair, the card must use `display: flex; flex-direction: column;` with the portrait at a fixed `width: 4.5rem; height: 4.5rem;` (not `width: 100%`). Halftone squares **never** overlap typography.
+
+2. **Hard-offset shadow on a card next to a viewport edge → shadow gets clipped.** When a card sits flush against the right edge of the page gutter, its `4px 4px 0` shadow extends past the page max-width. Add `padding-right: max(var(--page-gutter), 8px)` to grids that include shadowed cards near the edge, or set the shell to have ≥ 8 px right margin past the card grid.
+
+3. **Duo-tone fill on a card whose content includes both accents → reads as "blended", not "competing".** A mustard tile must never contain an oxblood badge inside it. Pick one accent per tile. (Signature #1 explicitly says this — but it's worth restating here because it gets violated when adding a sticker or a "NEW" badge.)
+
+4. **Marquee scroll that doesn't repeat its content → gap at end of loop.** The marquee must contain the same scrolling text repeated at least twice (or use `aria-hidden` siblings) so the scroll animation reads as continuous, not as a single string sliding off.
+
+5. **Big Shoulders width axis used without `font-variation-settings` → no width variation.** Setting `font-stretch` on Google's Big Shoulders Display does not work — only `font-variation-settings: "wdth" 110` does. If you see a hero that's supposed to be width-110 but renders at width-100, this is the bug.
+
+6. **Section head detached from, or mis-centred over, its body.** The section head (heading + any lede) sits **tight above** the content it names — about `1.25rem` (`--section-head-gap`) — and **shares that content's alignment**. Don't cap the head at a narrow `max-width` / `ch` and then `margin-inline: auto` it: that strands a centred head over a full-width, left-flush grid (the classic accidental mismatch). Left-flush grid → left-flush head. (See the alignment-coherence note in `layout-and-space.md`.)
+
+7. **Newsletter / CTA button not aligned with the input beside it.** When a button sits next to a form input in one row, they must share the **same height, vertical padding, and border width**, and the row must use `align-items: center` — otherwise the button floats above the input's baseline. If a label is stacked above the input it makes that column taller; centre the row on the *control*, not the column (give the field `align-items: center` or pull the label out of the flex row).
+
+## Macrostructure affinity
+
+**Carnival loves these.**
+
+- **Marquee Hero** — the canonical Carnival opening; large word, scrolling banner under
+- **Type Specimen** — the page IS the type; Big Shoulders Display 96 px+ as content
+- **Manifesto** — short loud declarative statements (works for Carnival's voice too, but louder palette)
+- **Stat-Led** — when the page leads with numbers, Carnival displays them big-and-mustard
+- **Photographic** — image-led with halftone treatments and ornament captions
+- **Bento Grid** (loud variant) — gridded blocks where each tile alternates accent colour
+
+## Macrostructure rejection
+
+**Carnival refuses these.**
+
+- **Long Document** — too quiet; Carnival doesn't sustain over 1500 words
+- **Letter** — too intimate; Carnival never whispers
+- **Quote-Led** — too pensive
+- **Conversational FAQ** — too soft
+- **Workbench** — too technical; Carnival is poster art, not product spec
+
+If the brief would otherwise land in one of these, redirect to Marquee Hero or Manifesto.
+
+## Voice fixtures
+
+Sample lines the Carnival voice should *read like*. Short. Loud. Declarative. Caps on the headlines, not on the body.
+
+- *"FIVE NEW FLAVORS. ALL TOO HOT."*
+- *"WE PRESS RECORDS. THAT'S IT."*
+- *"NEW SEASON. NEW SHOWS. SAME CHAOS."*
+- *"ONE EP. THREE ARTISTS. NO REGRETS."*
+- *"THE GAME IS PIXEL ART. THE GAME IS HARD."*
+
+Body copy is **shorter than other themes**. 1–2 short sentences per paragraph. Paragraphs separated by ornament dividers, not whitespace alone.
+
+**Voice rules:**
+- Headlines: ALL CAPS, ≤ 6 words, period at end (not exclamation — the loudness is in the type, not the punctuation).
+- Body: sentence case, short, present-tense.
+- Numerals over words always (*5* not *five*).
+- Never any of: "experience", "journey", "elevate", "curate", "platform", "ecosystem", "transform". These are SaaS-default AI tells; Carnival is independent, not platformed.
+
+## Anti-patterns (theme-specific)
+
+- **Never soft shadows.** Carnival is hard-offset (`4px 4px 0`) or no shadow. If you find yourself reaching for `0 8px 24px`, redirect.
+- **Never both accents in one block.** Mustard *or* oxblood per section, never blended.
+- **Never sentence-case headlines.** Headlines are ALL CAPS or `font-variant: all-petite-caps`.
+- **Never light-grey text.** Body text is full-ink. Carnival doesn't do "subtle".
+- **Never long paragraphs.** If a paragraph exceeds 3 sentences, break it with an ornament divider or split into two blocks.
+- **Never neutral CTAs.** Every CTA fills with one of the two accent colours.
+- **Never thin rules.** Rules are 2 px solid in oxblood. Hairlines belong to Boutique / Specimen.
+- **Emoji as decoration is allowed when typographic** (✱ ❋ ◆ are typographic ornaments, not emoji). Smiley-face / heart emoji are still banned per universal anti-patterns.
+
+## How Carnival differs from neighbouring themes
+
+| vs | difference |
+|---|---|
+| **Riso** | Riso is risograph print-craft (peach paper, CMYK misregistration on display, cyan + yellow). Carnival is *editorial maximalism* — duo-tone, oxblood-on-pink, decorative ornaments, variable-width type. Different parent tradition. |
+| **Manifesto** | Manifesto is BLACK paper + ALL CAPS red Anton. Carnival is *tinted warm paper* + duo accents + ornaments. Inverted polarity — Manifesto is dark, Carnival is light. |
+| **Brutal** | Brutal is raw graphic-design brutalism (heavy borders, slab type, no ornaments). Carnival is **decorative** — ornaments, layered blocks, variable type, character. |
+| **Sport** | Sport is athletic italic uppercase (Inter Tight italic 700). Carnival is poster-art expressive (Big Shoulders 800 with width axis). Sport feels Nike; Carnival feels Drag City. |
+
+## Test brief expectations
+
+Carnival should be a candidate when the brief mentions:
+
+- *record label · podcast · comedy · indie · zine · poster · illustrator · games · hot sauce · merch · streetwear · cassette · vinyl · cassettes · live show · zine · brand of one*
+- product categories: music · comedy · games · illustration · hot sauce · merch · skateboards · gig posters
+- emotional tone: *loud, fun, scrappy, chaotic, layered, character-led, decorative*
+
+Briefs that say *enterprise / scale / API / B2B / dashboard* never route to Carnival.
+
+## Build hint
+
+When emitting a Carnival page, the first 12 lines of CSS should establish the four most important tells:
+
+```css
+body { background: var(--color-paper); color: var(--color-ink); font-family: var(--font-body); }
+h1, h2 { font-family: var(--font-display); font-weight: 800; font-variation-settings: "wdth" 110; letter-spacing: 0.02em; line-height: 0.92; text-transform: uppercase; } /* hero word goes tighter: letter-spacing: -0.005em; line-height: 0.82 */
+.card, .cta { box-shadow: 4px 4px 0 var(--color-ink); border: 2px solid var(--color-ink); }
+.section:nth-of-type(odd)  { background: var(--color-accent);   color: var(--color-accent-ink); }
+.section:nth-of-type(even) { background: var(--color-accent-2); color: var(--color-paper); }
+.ornament { color: var(--color-accent); }
+.halftone { background-image: radial-gradient(var(--color-ink) 1.5px, transparent 1.5px); background-size: 12px 12px; }
+```
+
+Those rules carry 70 % of the theme's identity. The rest is content fit.

package/control-plane/scripts/skills/hallmark/references/themes/cobalt.md

@@ -0,0 +1,146 @@
+# Theme — Cobalt
+
+Modern-minimal, dev-tool register. The page for an **API, an SDK, a CLI, a docs home, a developer platform** — the GitBook / Firecrawl / Vercel school, executed in **cool cobalt-on-light, not orange**. A calm cool-white ground, ruler-drawn hairlines, exactly ONE electric cobalt signal accent, and **code as the hero**. It reads like good infrastructure: calm, precise, fast.
+
+Loaded eagerly by SKILL.md Step 3 whenever the catalog pick is `cobalt`. The OKLCH palette + font stack live in [`site/css/tokens.css`](../upstream/tokens.css) under `[data-theme="cobalt"]`. Canonical build: [`site/examples/cobalt-01/`](https://github.com/nutlope/hallmark/tree/main/site/examples/cobalt-01) (an API product landing with a request/response hero).
+
+> **Why not orange.** GitBook and Firecrawl both converged on orange-as-signal — but that lane is now crowded, and Hallmark's warm slots are already taken (Lumen brass, Bloom terracotta, Coral coral). Cobalt keeps their *discipline* (cool ground + one signal + code-as-hero + hairlines) and aims the signal at the open electric-blue lane instead. The blue is the differentiator, not a copy.
+
+## Axes (diversification)
+
+- **Paper band** — cool light (`L 98.5%`, hue ~250, very low chroma). An engineered near-white — distinct from Coral's warm grey and from the genre's dark grounds.
+- **Display style** — **grotesk-sans** (Space Grotesk 500/600 — slightly mechanical, tight tracking). Distinct from Geist (Coral) and from every serif/rounded option.
+- **Accent hue** — **electric cobalt** (`oklch(58% 0.20 256)`). High-chroma true blue — reads "API-live," sits clear of Midnight/Lumen's dusky indigos (~250/268). Used as a *signal*, never a flood.
+
+## Reference register
+
+GitBook · Firecrawl · Vercel / Geist · Linear · Mintlify · Stripe docs · Resend · Clerk · Railway · Supabase.
+
+The aesthetic: the developer-product landing and docs home — a cool engineered canvas, one signal accent, **code/terminal/API as the focal element**, hairline structure, a ⌘K-flavoured nav. Never name any of these in the output.
+
+**Patron-saint reference (internal):** *Vercel's blueprint-and-mono restraint* + *Firecrawl's live request-result credibility move*, recoloured cobalt. When in doubt, ask "does this read like an instrument panel, or like a marketing template?" Keep the former.
+
+## Required dependencies
+
+1. **Fonts** — **Space Grotesk** (display, 500/600), **Inter** (body, 400/500), **JetBrains Mono** (code + small UPPERCASE labels). All-sans; no serif anywhere. Google Fonts:
+   ```html
+   <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+   ```
+2. **A small reveal script** — one `IntersectionObserver` adding `.is-in` (fade + ~10px rise, ease-out ~600ms). Plus a one-shot "type-in" of a single line in the hero code demo, then static.
+3. **A working ⌘K command palette** — a small JS overlay that opens on click **and** ⌘K / Ctrl+K (Esc or backdrop closes; Arrow↑/↓ select; type-to-filter), `role="dialog"` / `aria-modal`, focus-managed, reduced-motion safe. The ⌘K in the nav actually works — Cobalt's signature interactive move.
+
+## The signature moves
+
+1. **Cool engineered paper, never `#fff`** — `oklch(98.5% 0.004 250)`. Ink is cool charcoal `oklch(24% 0.02 258)`, never `#000`. Body text sits a notch lighter (`oklch(34% 0.018 257)`).
+
+2. **Hairlines do the work** — 1px `--color-rule` borders define every surface. **No boxed cards, no drop-shadows** beyond a single barely-there `0 1px 2px` lift on the code card. Depth comes from borders, not blur.
+
+3. **One cobalt signal, used sparingly** (< 5% of any viewport) — the eyebrow tick, a link's hover underline, the one primary button, focus rings, the `200 OK` chip, the active nav item. Everything else is ink-on-cool-white.
+
+4. **Code is the hero** — a dark **graphite** card (`oklch(22% 0.016 260)`) with a window bar (3 dots + a filename), syntax tokens (cobalt for methods/keys, light for strings, muted for punctuation), and a status chip. One line types in once, then static. Either a **live API request/response** (POST + JSON `200 OK`) or a **terminal** (install + a clean `PASS` run). Title + lede sit LEFT; the demo sits RIGHT — asymmetric, never centred.
+
+5. **Bordered nav + a working ⌘K palette** — a flush full-width bar, single hairline bottom border, light blur on scroll. Wordmark + 2–3 text links left; a bordered **⌘K** affordance + one solid cobalt button right. The ⌘K **opens a real command palette** (mono search + command rows; click or ⌘K/Ctrl+K; Esc to close) — the page *behaves* like a dev tool, not just looks like one. **Not a floating pill** (softer, and Coral's vocabulary).
+
+6. **Tight technical radii** — 6px on buttons/inputs, 10px on code cards. Not Coral's soft pills, not 0px brutalism — "drawn with a ruler."
+
+7. **Mono labels** — eyebrows, meta, status, kbd hints in JetBrains Mono, UPPERCASE, `0.06em` tracking. The machine-readout voice against the Space Grotesk display.
+
+8. **One dark graphite band per page** — a single full-bleed dark section (a quickstart, a how-it-works, a watch-mode demo) on `oklch(~20% 0.016 260)` with light cool text and the cobalt accent popping. It gives the page a **light → dark → light** rhythm and a showcase moment. The page's *one* dark beat — Cobalt is a light theme *with* a dark band, never a dark theme.
+
+## Motion
+
+Composed and sparse. The one hero type-in (plays once). Section reveals fade + rise. Hover: cobalt underline-grow on nav/links; a 1px border-colour shift to cobalt on the code card / focusable surfaces. **No bounce, no parallax, no autoplay.** Everything gates behind `prefers-reduced-motion: no-preference`; reduced-motion ships static + fully visible.
+
+## Anti-patterns
+
+- **No orange accent** — the crowded GitBook/Firecrawl lane and a collision with Lumen/Bloom/Coral. Cobalt is blue.
+- **No warm paper** — warm grey is Coral's. Cobalt is cool (hue ~250–258).
+- **No pure `#fff` / `#000`.** Cool near-white paper, cool charcoal ink.
+- **No pill / gradient CTAs.** One solid cobalt button at 6px radius + understated typographic links. Name the destination.
+- **No centred-everything hero** (gate 6) — left-biased, title-left / demo-right.
+- **No three-equal-icon-tile feature grid** (gate 3) — vary it (one wide code example + narrower points; asymmetric benchmark figures).
+- **No glassmorphism, no gradient text** (gates), **no aurora/mesh blob, and no background texture/pattern at all** — cool paper + hairlines carry the page; its one dark beat is the graphite band (signature 8), not a background.
+
+## Macrostructure affinity
+
+**Cobalt loves these.**
+
+- **SaaS / API Product** — hero + quick-start code + feature rows + pricing/CTA *(canonical — cobalt-01)*
+- **Dev-tool / CLI** — terminal hero + install + benchmark figures + docs CTA
+- **Docs home** — a calm index with a search-first nav
+- **Workbench** — the technical, tool-first shape
+- **Marquee** — when the hero is one confident code demo
+
+## Macrostructure rejection
+
+**Cobalt refuses these.**
+
+- **Letter** — too intimate; Cobalt is a product, not a note
+- **Manifesto** — too loud; Cobalt is calm infrastructure
+- **Photographic / image-led** — Cobalt leads with code, not imagery
+- **Long Document** — prose-led; route warm-editorial instead
+
+## Voice fixtures
+
+Declarative, technical, specific. Name the X concretely. No hype adjectives.
+
+- *"Turn any website into clean Markdown for LLMs."*
+- *"One API. Every page."*
+- *"From idea to production in an afternoon."*
+- *"Type-safe by default. Fast by design."*
+- *"Built to ship — `200 OK` in under 200 ms."*
+
+Never any of: *seamless, robust, cutting-edge, leverage, synergy, revolutionary, unlock, supercharge*. Never "click here." Name the endpoint, the command, the number.
+
+## How Cobalt differs from neighbouring themes
+
+| vs | difference |
+|---|---|
+| **Coral** (modern-minimal sibling) | Coral is warm-grey paper + warm coral accent + Geist + soft pills + a quiet title/lede hero. Cobalt is cool-white + electric blue + Space Grotesk/JetBrains Mono + tight bordered controls + a live code hero. Same genre, opposite temperature — the rotation walks between them. |
+| **Midnight** (atmospheric) | Both live near hue 250–258, but Midnight is a **dark** canvas (atmospheric, numbered display, typewriter reveals). Cobalt is a **light** engineered canvas (modern-minimal, code hero). Light vs dark settles it instantly. |
+| **Lumen** (atmospheric) | Lumen is a dark (or cool-bone) *apparatus* page with Instrument Serif + an emit/refract focal artefact. Cobalt is light, all-sans, and its focal element is a literal code/API card, not a built light-instrument. |
+| **Aurora** (atmospheric) | Aurora is dark cyan blooms + Sentient serif body. Cobalt is light, hairline-structured, cobalt-on-white — no blooms, no serif. |
+
+## Test brief expectations
+
+Cobalt should be a candidate when the brief mentions:
+
+- *API · SDK · CLI · dev tool · developer platform · docs · documentation · infrastructure · backend · database · observability · webhooks · type-safe · open-source tool · ship · deploy · developer experience · B2B developer*
+- Product categories: *API · developer tool · dev platform · docs site · infra · SaaS-for-engineers*
+- Emotional tone: *precise · engineered · fast · technical · instrument-panel · calm-confident · cool*
+
+Briefs that are warm / consumer / editorial / image-led route elsewhere (Coral for warm SaaS, the editorial themes for content). When the brief is for developers and wants to *show the code*, it's Cobalt.
+
+## Build hint
+
+The first lines of CSS establish Cobalt's anchor moves:
+
+```css
+html, body { overflow-x: clip; }
+body { background: var(--color-paper); color: var(--color-ink-2);
+       font-family: var(--font-body); font-weight: 400; }
+
+/* Reveal — the whole motion engine */
+.reveal { opacity: 0; transform: translateY(10px);
+          transition: opacity .6s cubic-bezier(0.16,1,0.3,1),
+                      transform .6s cubic-bezier(0.16,1,0.3,1); }
+.reveal.is-in { opacity: 1; transform: none; }
+
+/* The code hero — dark graphite card, hairline-framed */
+.code-card { background: var(--color-graphite); border: 1px solid var(--color-rule-2);
+             border-radius: 10px; box-shadow: 0 1px 2px oklch(24% 0.02 258 / 0.05);
+             font-family: var(--font-mono); }
+.code-card .tok-key, .status--ok { color: var(--color-accent); }   /* the one signal */
+.status--ok { font: 500 0.75rem/1 var(--font-mono); letter-spacing: .06em; }
+
+/* Bordered nav + the one cobalt button (6px, never a pill) */
+.nav { border-bottom: 1px solid var(--color-rule); backdrop-filter: blur(8px); }
+.btn--primary { background: var(--color-accent); color: var(--color-accent-ink);
+                border-radius: 6px; }
+
+@media (prefers-reduced-motion: reduce) {
+  .reveal { opacity: 1; transform: none; transition: none; }
+}
+```
+
+Plus the Space Grotesk + Inter + JetBrains Mono link and the small reveal/type-in script. The canonical build to mirror is [`site/examples/cobalt-01/`](https://github.com/nutlope/hallmark/tree/main/site/examples/cobalt-01).

package/control-plane/scripts/skills/hallmark/references/themes/grid.md

@@ -0,0 +1,161 @@
+# Theme - Grid
+
+Swiss neo-grotesque systems design: the object-poster and transit-signage school, executed on a **near-white cool sheet with an exposed 12-column hairline grid, one heavy grotesk, and exactly one signal ink spent entirely on geometry**. Giant lowercase Archivo slams to the left margin, the column rules stay visible behind the content, and every section carries a constructed object: a plate, a figure, a giant numeral, a mark from the kit. It reads like a wayfinding manual a poster designer got hold of: rational, gridded, and unafraid of one loud move per band.
+
+The material, in one line: **a visible column grid, one grotesk, one signal ink, and geometry doing the talking.**
+
+> **The editorial exception.** The editorial cluster is otherwise serif-led (Newsprint, Editorial, Specimen). Grid is its Swiss neo-grotesque slot: no serif anywhere, structure carried by an exposed grid and hairlines, warmth carried by one signal ink. A brief wanting a roman serif or a soft column is a different editorial theme.
+
+## Axes (diversification)
+
+- **Paper band** - **light**, cool near-white (`--color-paper: oklch(99% 0.003 255)`, faintly cool, never `#fff`). Stepped at `paper-2 97.2%` and `paper-3 94.5%`. Ink is cool near-black `--color-ink: oklch(16% 0.010 255)`.
+- **Display style** - **grotesk-heavy** (Archivo **800**, `--display-weight: 800`), run **lowercase** at `--tracking-display: -0.045em`. Heavy plus lowercase is the differentiator against every uppercase-condensed and serif option.
+- **Accent hue** - **the signal ink, exactly one per page**, picked to the brief's temperature:
+  - **signal red** `oklch(55% 0.21 28)` - the default; cultural, editorial, civic.
+  - **ultramarine** `oklch(45% 0.19 264)` - technical, institutional, engineering.
+  - **signal yellow** `oklch(82% 0.17 95)` - industrial, archive, logistics. Yellow is **surface-only**: it floods plates and fills marks, always carrying ink text or sitting beside ink; yellow type on paper never happens at any size.
+
+  Two Grid pages built in the same run must not share the ink. `--color-focus` is the chosen ink (for yellow, focus is ink on a yellow fill).
+
+## Reference register
+
+Vitra, Braun, the Vignelli canon, Museum fur Gestaltung, the Swiss International poster tradition and its object posters. The material to match: the institutional identity manual crossed with the exhibition poster - a modular grid drawn in public, one grotesk, one ink, geometry as the only image. When in doubt, ask whether this reads like a systems manual designed by a poster artist or like a marketing template, and keep the former. Never name any of these in the output.
+
+## Typography
+
+**Archivo only, one family across the whole page** (400/500/600/700/800). Swiss discipline comes from weight, scale, and tracking, not from a second family. `--font-serif` and `--font-mono` resolve to unused fallbacks; do not load them.
+
+- **Display** - Archivo 800, **lowercase**, `clamp(52px, 10.5vw, 136px)`, `letter-spacing: -0.045em`, `line-height: 0.9`. Slammed to the left margin, edge-aligned to the grid.
+- **Body** - Archivo 400, 16px, `line-height: 1.5`.
+- **Label voice** - Archivo uppercase at 12px, weight 600, `letter-spacing: 0.09em`, `--color-muted`. It sets captions, table headers, meta rows, folios, units, and index numbering - the quiet caps counterpoint to the giant lowercase display. It never sits above a heading as a kicker.
+- **The numeral voice** - Archivo 800 numerals at display scale and beyond (`clamp(120px, 22vw, 320px)`), used as objects: a section index numeral set beside or behind the head at 6-10% opacity ink or in the signal ink, cropped by the band edge (`overflow: clip` on the band, the numeral deliberately hanging past it). One per section at most; it is art, not a heading.
+
+## The marks kit
+
+The signal ink and the ink itself are spent on a small vocabulary of constructed geometry. Every mark aligns to the column grid or to type metrics; nothing floats freehand.
+
+- **The period square** - a solid `0.52em` square where a full stop would fall.
+- **The bar** - a `3px` signal rule over a head, cut to a column width, never full-bleed.
+- **The register** - a 1px ink circle with a crosshair through it (print registration), set in a margin column as a folio device.
+- **The quarter-disc** - a solid quarter circle filling one grid cell corner, ink or signal.
+- **The stepped bars** - 3-5 solid rectangles of stepped widths on the column tracks, a data-less bar chart used as texture beside a claim, or a data-ful one beside real numbers.
+- **The dot module** - a cell filled with a dot lattice (`radial-gradient` repeated on an exact grid), ink at low weight, as ground texture inside one figure cell.
+- **The border arrow** - arrows and chevrons drawn entirely from borders and rotated squares, signage style.
+- **The diagonal** - one 45-degree rule crossing a band or a cell, 1px ink or 3px signal, snapped corner to corner on the column tracks.
+- **The cropped numeral** - see the numeral voice above.
+
+Per viewport, marks stay geometric and under 5% painted area; the plate is the one exception.
+
+## The plate
+
+**At most one per page, and every page should want one.** A full-bleed horizontal band flooded solid - the signal ink, or near-black ink - carrying the page's poster moment: an oversized claim, a giant numeral, a figure built from the kit, a specimen line. Text on a red or ultramarine plate is paper; text on a yellow plate is ink; an ink plate may use both paper and the signal. The hairline rails continue across the plate at low opacity (`--color-paper` at 12-18% alpha) so the grid is never interrupted. The plate has zero radius, zero shadow, and butts flush against the rules above and below it. It is a poster inside a manual: one loud move, then back to the sheet.
+
+## Material
+
+- **The exposed 12-column hairline grid is the theme.** A `repeating-linear-gradient` of 1px `--color-rule` lines every `calc(100% / 12)`, painted behind the content, capped to the shell width. The grid is content, not scaffolding to delete, and content rides `repeat(12, minmax(0,1fr))` on top of it.
+- **Every section carries an object.** A section that is only prose has failed this theme. Each band sets at least one constructed thing: a plate, a figure cell, a cropped numeral, a specimen, a diagram, a matrix of ruled cells, stepped bars against real numbers. The object is built from the kit and the grid, never from an image, an emoji, or an icon font.
+- **Asymmetric occupancy.** Running text never spans more than 6 of the 12 columns. The remaining columns carry the section's object or stay empty as designed whitespace - and the occupied side alternates or steps as the page descends, so consecutive sections never share the same silhouette.
+- **Air is structural.** Desktop bands breathe at 120-160px vertical padding minimum; the hero holds most of the first viewport with type occupying less than half of it. Density belongs to tables and indexes; everything else is air and geometry.
+- **Hairlines and ink rules do all the structure; zero cards.** `--radius-card: 0`, `--shadow-card: none`. Faint `--color-rule` hairlines split cells, a 1px-to-2px solid `--color-ink` rule tops a section, and content butts flush against it. No boxes, no float, no drop shadow.
+- **Cells, not tiles.** Where the page needs repeated units, they are equal cells of the same grid divided by `border-inline-start` hairlines, sharing the band's top and bottom rules. The band reads as one ruled object, not as a row of separate objects.
+- **`::selection` is the signal ink on paper** (ink on yellow). The one place the accent floods text.
+
+**Shapes Grid suits** (affinities, never requirements): a numbered index of full-width rows riding the 12 columns with a cropped numeral hanging in the margin; an object-poster plate between two quiet ruled bands; a type or system specimen where the grid is the exhibit; figures set in bordered cells with caps labels beneath; a stepped-bar figure beside three real numbers.
+
+## Motion
+
+Restrained, geometric, grid-snapped. No scroll reveals, no parallax, no autoplay, no blur or fade choreography. What is allowed:
+
+- **Hover micro-states** - a row background shifts to `--color-paper-2` and its title slides 8px; links underline; a bordered surface shifts its border to the signal ink. ~0.18-0.2s ease.
+- **Hover geometry** - a mark answers the pointer with a snapped transform: the quarter-disc rotates 90 degrees, a stepped bar extends one column track, a border arrow translates 8px along its axis. Same 0.18-0.2s, transforms land on grid increments, nothing springs or bounces.
+- **The ticker** - optionally, one thin full-bleed band of label-voice text scrolling at a constant slow rate between two rules, wayfinding-sign style. One per page at most, pausable on hover.
+
+Smooth scroll only, and `prefers-reduced-motion: reduce` kills transitions, the ticker, and `scroll-behavior`.
+
+## Do-nots (this theme's own failure modes)
+
+- **Never hide the grid.** The rails stay visible, including across the plate. Deleting them because they look like scaffolding removes the theme.
+- **Never a prose-only section.** Text plus nothing is the failure this revision exists to kill; every band builds an object from the kit.
+- **Never uppercase display, never a serif, never a mono body.** Grid's display is lowercase Archivo; uppercase-condensed is Manifesto or Brutal, and the second family never arrives.
+- **Never two signal inks on one page.** One ink, chosen once. A red page with a blue chart is a broken page.
+- **Never a dark page, and never a second plate.** One flooded band is a poster moment; two is a striped template, and a full dark ground is Manifesto.
+- **Never a gradient, a wash, or a tint fill** outside `paper-2`/`paper-3`. The ink is solid or absent.
+- **Never a card, a radius, or a drop shadow.** Depth is hairlines, ink rules, and the plate.
+- **Never a centred hero.** Slam left.
+- **Never freehand geometry.** Every mark sits on a column track or a type metric; decoration that ignores the grid is another theme.
+
+## Voice range
+
+Rational, plainspoken, institutional. Name the system, the place, the year concretely. No hype. Never: seamless, robust, cutting-edge, leverage, synergy, revolutionary, unlock, supercharge, elevate, curated, bespoke. Never "click here."
+
+## How Grid differs from its neighbours
+
+| vs | difference |
+|---|---|
+| **Manifesto** | Manifesto is a **dark** ground (`oklch(10% 0.005 60)`), Anton 400 **uppercase** at `--lh-tight: 0.86`, red `#E51A1A`. Grid is a **light** sheet (`oklch(99% 0.003 255)`), Archivo **800 lowercase**; its one plate is a band inside a light page, never the page itself. Same "one ink, type carries it" DNA, opposite value and case. |
+| **Cobalt** | Cobalt is modern-minimal: electric cobalt `oklch(58% 0.20 256)`, Familjen Grotesk plus JetBrains Mono, graphite code surfaces, 6-10px radii. Grid is editorial: a chosen signal ink, single-family Archivo, an exposed 12-column grid, zero radius, no code. Even on ultramarine the difference holds: Grid's blue is a flat poster ink on a ruled sheet, not an interface accent on soft surfaces. |
+| **Brutal** | Both are light near-neutral sheets with red available and zero radius, but Brutal draws with **3px** black rules (`--color-rule: oklch(12%)`) boxing solid inverted blocks in Albert Sans 700 **uppercase**. Grid draws with **1px** hairlines (`--color-rule: oklch(88%)`) painting a **visible column grid**, Archivo 800 **lowercase**, and at most one flooded plate. Marker vs pencil; shout vs quiet with one loud move. |
+
+## When the brief routes here
+
+*identity · brand system · wayfinding · signage · design studio · type specimen · editorial grid · institution · museum · archive · index · directory · systems · modular · Swiss · grotesque · manual · programme · poster*. Categories: design and branding studios, cultural institutions, publishers, specimens and catalogs, portfolio indexes, archives and logistics. Tone: rational, systematic, precise, institutional, disciplined, timeless, calm-authoritative.
+
+Warm, consumer, image-led, or serif-editorial briefs route elsewhere. When the brief wants a visible grid, one grotesk, and one signal ink spent on geometry, it is Grid.
+
+## Build hint
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Archivo:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
+```
+
+```css
+html, body { overflow-x: clip; }
+body { background: var(--color-paper); color: var(--color-ink);
+       font-family: var(--font-body); font-size: 16px; line-height: 1.5; }
+
+/* THE ground: the exposed 12-column hairline grid, painted behind the content */
+.rails {
+  position: absolute; inset: 0; z-index: 0; pointer-events: none;
+  max-width: 1280px; margin-inline: auto;
+  background-image: repeating-linear-gradient(to right,
+    var(--color-rule) 0, var(--color-rule) 1px,
+    transparent 1px, transparent calc(100% / 12));
+}
+
+h1, h2 { font-family: var(--font-display); font-weight: var(--display-weight);
+  font-size: clamp(52px, 10.5vw, 136px); letter-spacing: var(--tracking-display);
+  line-height: 0.9; text-transform: lowercase; }
+
+.period {                              /* the smallest mark in the kit */
+  display: inline-block; width: 0.52em; height: 0.52em;
+  background: var(--color-accent);
+}
+
+.plate {                               /* the one poster moment */
+  background: var(--color-accent); color: var(--color-paper);
+  position: relative; overflow: clip;
+}
+.plate::before {                       /* rails continue across the plate */
+  content: ""; position: absolute; inset: 0; pointer-events: none;
+  background-image: repeating-linear-gradient(to right,
+    color-mix(in oklab, var(--color-paper) 15%, transparent) 0,
+    color-mix(in oklab, var(--color-paper) 15%, transparent) 1px,
+    transparent 1px, transparent calc(100% / 12));
+}
+
+.numeral {                             /* the cropped section numeral */
+  font-weight: 800; font-size: clamp(120px, 22vw, 320px);
+  line-height: 0.8; letter-spacing: -0.05em;
+  color: color-mix(in oklab, var(--color-ink) 8%, transparent);
+  user-select: none;
+}
+
+::selection { background: var(--color-accent); color: var(--color-accent-ink); }
+
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  * { transition-duration: 0.01ms !important; animation: none !important; }
+}
+```
+
+Grid supplies the sheet, the rails, the one grotesk, the marks kit, and one plate. What rides those twelve columns is the brief's business, not the theme's.