Skip to content

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

CSS

v0.8 polish — Cohort fix · component exports · study gallery

Youssef4b76eb0e3c16
diff --git a/site/_tests/08-cohort-courses/index.html b/site/_tests/08-cohort-courses/index.html
index 282725f..c8bd3d4 100644
--- a/site/_tests/08-cohort-courses/index.html
+++ b/site/_tests/08-cohort-courses/index.html
@@ -25,7 +25,7 @@
<section class="hero">
<p class="hero__eyebrow">Built for educators · not LMS sales teams</p>
<p class="hero__stat">30 <span class="hero__stat-em">—</span> 500</p>
- <h1 class="hero__head">Live courses, the size your <em>roster</em> actually is.</h1>
+ <h1 class="hero__head">Live courses, sized for the <em>class</em> you actually have.</h1>
<p class="hero__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
diff --git a/site/_tests/08-cohort-courses/style.css b/site/_tests/08-cohort-courses/style.css
index 90b723e..baeb9d7 100644
--- a/site/_tests/08-cohort-courses/style.css
+++ b/site/_tests/08-cohort-courses/style.css
@@ -98,7 +98,7 @@ body {
.hero__stat {
font-family: var(--font-display);
- font-size: clamp(6rem, 22vw, 22rem);
+ font-size: clamp(5rem, 14vw, 13rem);
font-weight: 300;
letter-spacing: -0.05em;
line-height: 0.85;
diff --git a/site/css/components.css b/site/css/components.css
index 9ffd8a7..d87ac8b 100644
--- a/site/css/components.css
+++ b/site/css/components.css
@@ -3030,6 +3030,137 @@ html[data-theme="bloom"] body {
[data-theme="riso"] .ex-card__name { text-transform: lowercase; }
+/* — Study gallery card ————————————————————————————————
+ Each card pairs a video-shaped media tile with a structured DNA
+ panel below it. The video uses poster as the static fallback when
+ no <source> is supplied — drop one in to enable playback. The DNA
+ panel renders as an editorial table: mono numeral key, body value,
+ hairline divider per row. Theme-adaptive throughout. */
+.study-card {
+ display: grid;
+ gap: var(--space-md);
+ background: var(--color-paper);
+ border: var(--rule-card, 1px) solid var(--color-rule);
+ border-radius: var(--radius-card, 0);
+ box-shadow: var(--shadow-card, none);
+ overflow: hidden;
+ transition: border-color var(--dur-micro) var(--ease-out);
+}
+
+@media (hover: hover) and (pointer: fine) {
+ .study-card:hover { border-color: var(--color-rule-2); }
+}
+
+.study-card[data-user-content] {
+ border-style: dashed;
+}
+
+.study-card__media {
+ position: relative;
+ aspect-ratio: 16 / 10;
+ background: var(--color-paper-2);
+ border-block-end: var(--rule-card, 1px) solid var(--color-rule);
+ overflow: hidden;
+}
+
+.study-card__video {
+ display: block;
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ object-position: top left;
+ background: var(--color-paper-2);
+}
+
+.study-card__badge {
+ position: absolute;
+ bottom: var(--space-sm);
+ left: var(--space-sm);
+ padding: 0.25rem 0.55rem;
+ font-family: var(--font-label);
+ font-size: 0.625rem;
+ letter-spacing: var(--tracking-label);
+ text-transform: uppercase;
+ color: var(--color-paper);
+ background: color-mix(in oklch, var(--color-ink) 85%, transparent);
+ backdrop-filter: blur(4px);
+ -webkit-backdrop-filter: blur(4px);
+ font-feature-settings: "tnum";
+}
+
+.study-card[data-user-content] .study-card__badge {
+ background: color-mix(in oklch, var(--color-accent) 80%, transparent);
+}
+
+[data-theme="riso"] .study-card__badge,
+[data-theme="brutal"] .study-card__badge,
+[data-theme="manifesto"] .study-card__badge,
+[data-theme="sport"] .study-card__badge { text-transform: uppercase; }
+
+[data-theme="riso"] .study-card__badge { text-transform: lowercase; }
+
+/* DNA panel — structured 10-field key/value table. */
+.study-card__dna {
+ list-style: none;
+ margin: 0;
+ padding: var(--space-md) var(--space-lg) var(--space-lg);
+ display: grid;
+ gap: 0;
+}
+
+.dna__row {
+ display: grid;
+ grid-template-columns: 8.5rem 1fr;
+ gap: var(--space-sm);
+ align-items: baseline;
+ padding-block: var(--space-sm);
+ border-block-end: var(--rule-hair) solid var(--color-rule);
+}
+
+.dna__row:last-child { border-block-end: 0; }
+
+@media (max-width: 36rem) {
+ .dna__row { grid-template-columns: 1fr; gap: 0.15rem; padding-block: var(--space-xs); }
+}
+
+.dna__k {
+ font-family: var(--font-label);
+ font-size: var(--text-xs);
+ letter-spacing: var(--tracking-label);
+ text-transform: uppercase;
+ color: var(--color-muted);
+ font-feature-settings: "tnum";
+}
+
+.dna__v {
+ font-family: var(--font-mono);
+ font-size: 0.8125rem;
+ line-height: 1.45;
+ color: var(--color-ink);
+ letter-spacing: 0;
+}
+
+.study-card[data-user-content] .dna__v {
+ color: var(--color-rule-2);
+}
+
+[data-theme="brutal"] .study-card,
+[data-theme="manifesto"] .study-card { border-width: 2px; }
+
+[data-theme="atelier"] .study-card,
+[data-theme="salon"] .study-card {
+ border: 0;
+ background: transparent;
+ box-shadow: none;
+ border-block-end: var(--rule-hair) solid var(--color-rule);
+ border-radius: 0;
+}
+
+[data-theme="atelier"] .study-card__media,
+[data-theme="salon"] .study-card__media {
+ border-block-end: 0;
+}
+
/* Decision-trail popover — appears after 600ms hover/focus on a tile.
Shows the routing chain Hallmark used to arrive at this output.
Pure CSS — no JS, just transition-delay on the show transition. */
diff --git a/site/css/sections.css b/site/css/sections.css
index 26cb326..00a1dc7 100644
--- a/site/css/sections.css
+++ b/site/css/sections.css
@@ -410,7 +410,53 @@
.step__body { display: grid; gap: var(--space-sm); }
-/* — 05 · FAQ — typographic Q/A ——————————————————————————
+/* — 03 · Study — DNA extraction gallery —————————————————
+ Four tiles. Each pairs a video-shaped media slot (poster image
+ when no <source> is supplied, otherwise an autoplay-muted-loop
+ screen recording) with the structured 10-field DNA panel. The
+ panel is a tabular key/value layout — mono key, body value. */
+.study__intro {
+ margin: 0 0 var(--space-2xl);
+ font-family: var(--font-serif);
+ font-style: italic;
+ font-size: var(--text-md);
+ line-height: var(--lh-snug);
+ color: var(--color-ink-2);
+ max-width: 60ch;
+}
+
+.study__intro code {
+ font-family: var(--font-mono);
+ font-style: normal;
+ font-size: 0.875em;
+ background: var(--color-paper-2);
+ padding: 0.05em 0.35em;
+ border: var(--rule-hair) solid var(--color-rule);
+ color: var(--color-ink);
+}
+
+[data-theme="brutal"] .study__intro,
+[data-theme="manifesto"] .study__intro,
+[data-theme="terminal"] .study__intro,
+[data-theme="sport"] .study__intro,
+[data-theme="almanac"] .study__intro,
+[data-theme="quiet"] .study__intro,
+[data-theme="bloom"] .study__intro {
+ font-family: var(--font-body);
+ font-style: normal;
+}
+
+.study-grid {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: var(--space-2xl) var(--space-xl);
+}
+
+@media (max-width: 60rem) {
+ .study-grid { grid-template-columns: 1fr; gap: var(--space-2xl); }
+}
+
+/* — 06 · FAQ — typographic Q/A ——————————————————————————
Five numbered Q/A pairs in editorial format. Q in display face,
A in body serif. Tighter than a typical FAQ — meant to scan, not
loom. Re-typesets per-theme. */
diff --git a/site/index.html b/site/index.html
index f4c0917..bb3cd96 100644
--- a/site/index.html
+++ b/site/index.html
@@ -297,13 +297,127 @@
</div>
</section>
- <!-- 03 · WITHOUT / WITH — same copy, two design languages, two examples -->
- <section class="section reveal" style="--i:2" aria-labelledby="s3">
+ <!-- 03 · STUDY — what `study` extracts from a design -->
+ <section class="section reveal" style="--i:2" id="study" aria-labelledby="s-study">
<header class="section__head">
<p class="section-label">
- <span class="num">03</span><span class="divider">⁄</span><span>Without / with</span>
+ <span class="num">03</span><span class="divider">⁄</span><span>Study</span>
</p>
- <h2 class="section__title" id="s3">
+ <h2 class="section__title" id="s-study">
+ What Hallmark sees when it reads a design.
+ </h2>
+ </header>
+
+ <p class="study__intro">
+ <code>hallmark study</code> reads a design's structure, not its pixels. Below, four Hallmark-built pages put through the same DNA extraction the verb runs on user-supplied references. Each video is the page in motion; each panel is the structured DNA.
+ </p>
+
+ <div class="study-grid">
+
+ <!-- Tile 01 — Tide -->
+ <article class="study-card">
+ <div class="study-card__media">
+ <video class="study-card__video" autoplay muted loop playsinline
+ poster="_tests/_thumbs/01-tide.png" aria-label="Tide page in motion">
+ <!-- USER: drop <source src="study/01-tide.mp4" type="video/mp4" /> here -->
+ </video>
+ <span class="study-card__badge">01 · Tide</span>
+ </div>
+ <ol class="study-card__dna">
+ <li class="dna__row"><span class="dna__k">Macrostructure</span><span class="dna__v">Letter</span></li>
+ <li class="dna__row"><span class="dna__k">Hero archetype</span><span class="dna__v">H5 Letter · salutation + body + signoff</span></li>
+ <li class="dna__row"><span class="dna__k">Display role</span><span class="dna__v">italic editorial serif</span></li>
+ <li class="dna__row"><span class="dna__k">Body role</span><span class="dna__v">italic editorial serif (same family, smaller weight)</span></li>
+ <li class="dna__row"><span class="dna__k">Label role</span><span class="dna__v">small-caps grotesque</span></li>
+ <li class="dna__row"><span class="dna__k">Paper band</span><span class="dna__v">light · warm cream</span></li>
+ <li class="dna__row"><span class="dna__k">Accent hue</span><span class="dna__v">warm orange · ≤ 3% footprint</span></li>
+ <li class="dna__row"><span class="dna__k">Density</span><span class="dna__v">generous · single-column letter</span></li>
+ <li class="dna__row"><span class="dna__k">Pairing logic</span><span class="dna__v">single family carrying the page; mono labels for register</span></li>
+ <li class="dna__row"><span class="dna__k">Rhythm</span><span class="dna__v">left-biased · varied padding · letter-format intimacy</span></li>
+ </ol>
+ </article>
+
+ <!-- Tile 02 — Tracejam -->
+ <article class="study-card">
+ <div class="study-card__media">
+ <video class="study-card__video" autoplay muted loop playsinline
+ poster="_tests/_thumbs/05-tracejam.png" aria-label="Tracejam page in motion">
+ <!-- USER: drop <source src="study/02-tracejam.mp4" type="video/mp4" /> here -->
+ </video>
+ <span class="study-card__badge">02 · Tracejam</span>
+ </div>
+ <ol class="study-card__dna">
+ <li class="dna__row"><span class="dna__k">Macrostructure</span><span class="dna__v">Workbench</span></li>
+ <li class="dna__row"><span class="dna__k">Hero archetype</span><span class="dna__v">H3 Stat-Led · trace number + sticky panel</span></li>
+ <li class="dna__row"><span class="dna__k">Display role</span><span class="dna__v">soft geometric sans · 600</span></li>
+ <li class="dna__row"><span class="dna__k">Body role</span><span class="dna__v">soft geometric sans · 400</span></li>
+ <li class="dna__row"><span class="dna__k">Label role</span><span class="dna__v">monospace · uppercase</span></li>
+ <li class="dna__row"><span class="dna__k">Paper band</span><span class="dna__v">dark · cool charcoal</span></li>
+ <li class="dna__row"><span class="dna__k">Accent hue</span><span class="dna__v">cyan · phosphor-bright · 8% footprint</span></li>
+ <li class="dna__row"><span class="dna__k">Density</span><span class="dna__v">medium · sticky-panel observability layout</span></li>
+ <li class="dna__row"><span class="dna__k">Pairing logic</span><span class="dna__v">sans display + body, mono labels carry the technical register</span></li>
+ <li class="dna__row"><span class="dna__k">Rhythm</span><span class="dna__v">three-step walkthrough · sticky right panel · medium padding</span></li>
+ </ol>
+ </article>
+
+ <!-- Tile 03 — USER will fill -->
+ <article class="study-card" data-user-content>
+ <div class="study-card__media">
+ <video class="study-card__video" autoplay muted loop playsinline
+ poster="_tests/_thumbs/03-maple.png" aria-label="User study tile 3">
+ <!-- USER: drop <source src="study/03-<your-page>.mp4" type="video/mp4" /> here -->
+ </video>
+ <span class="study-card__badge">03 · Yours</span>
+ </div>
+ <!-- USER CONTENT — replace each "—" with your DNA value. Keep the same shape. -->
+ <ol class="study-card__dna">
+ <li class="dna__row"><span class="dna__k">Macrostructure</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Hero archetype</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Display role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Body role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Label role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Paper band</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Accent hue</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Density</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Pairing logic</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Rhythm</span><span class="dna__v">—</span></li>
+ </ol>
+ </article>
+
+ <!-- Tile 04 — USER will fill -->
+ <article class="study-card" data-user-content>
+ <div class="study-card__media">
+ <video class="study-card__video" autoplay muted loop playsinline
+ poster="_tests/_thumbs/07-foundry.png" aria-label="User study tile 4">
+ <!-- USER: drop <source src="study/04-<your-page>.mp4" type="video/mp4" /> here -->
+ </video>
+ <span class="study-card__badge">04 · Yours</span>
+ </div>
+ <!-- USER CONTENT — replace each "—" with your DNA value. Keep the same shape. -->
+ <ol class="study-card__dna">
+ <li class="dna__row"><span class="dna__k">Macrostructure</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Hero archetype</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Display role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Body role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Label role</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Paper band</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Accent hue</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Density</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Pairing logic</span><span class="dna__v">—</span></li>
+ <li class="dna__row"><span class="dna__k">Rhythm</span><span class="dna__v">—</span></li>
+ </ol>
+ </article>
+
+ </div>
+ </section>
+
+ <!-- 04 · WITHOUT / WITH — same copy, two design languages, four examples -->
+ <section class="section reveal" style="--i:3" aria-labelledby="s4">
+ <header class="section__head">
+ <p class="section-label">
+ <span class="num">04</span><span class="divider">⁄</span><span>Without / with</span>
+ </p>
+ <h2 class="section__title" id="s4">
Same brief. Same words. Two very different pages.
</h2>
</header>
@@ -469,13 +583,13 @@
</div>
</section>
- <!-- 04 · FOUNDATIONS — five plain-English rules -->
- <section class="section reveal" style="--i:3" aria-labelledby="s4">
+ <!-- 05 · FOUNDATIONS — five plain-English rules -->
+ <section class="section reveal" style="--i:4" aria-labelledby="s5-foundations">
<header class="section__head">
<p class="section-label">
- <span class="num">04</span><span class="divider">⁄</span><span>Foundations</span>
+ <span class="num">05</span><span class="divider">⁄</span><span>Foundations</span>
</p>
- <h2 class="section__title" id="s4">
+ <h2 class="section__title" id="s5-foundations">
Five things Hallmark holds the line on — explained without the jargon.
</h2>
</header>
@@ -589,13 +703,13 @@
</div>
</section>
- <!-- 05 · FAQ — six typographic Q/A pairs -->
- <section class="section reveal" style="--i:4" id="faq" aria-labelledby="s5">
+ <!-- 06 · FAQ — five typographic Q/A pairs -->
+ <section class="section reveal" style="--i:5" id="faq" aria-labelledby="s6">
<header class="section__head">
<p class="section-label">
- <span class="num">05</span><span class="divider">⁄</span><span>FAQ</span>
+ <span class="num">06</span><span class="divider">⁄</span><span>FAQ</span>
</p>
- <h2 class="section__title" id="s5">
+ <h2 class="section__title" id="s6">
The questions people actually ask.
</h2>
</header>
@@ -635,13 +749,13 @@
</ol>
</section>
- <!-- 06 · INSTALL — one command, every harness -->
- <section class="section reveal" style="--i:5" id="install" aria-labelledby="s6">
+ <!-- 07 · INSTALL — one command, every harness -->
+ <section class="section reveal" style="--i:6" id="install" aria-labelledby="s7">
<header class="section__head">
<p class="section-label">
- <span class="num">06</span><span class="divider">⁄</span><span>Install</span>
+ <span class="num">07</span><span class="divider">⁄</span><span>Install</span>
</p>
- <h2 class="section__title" id="s6">
+ <h2 class="section__title" id="s7">
One command. Works in every harness.
</h2>
</header>
@@ -690,7 +804,7 @@
</section>
<!-- FOOTER SLOT — archetype swaps per theme -->
- <footer class="slot slot--foot reveal" data-slot="footer" style="--i:6" role="contentinfo" aria-label="Colophon">
+ <footer class="slot slot--foot reveal" data-slot="footer" style="--i:7" role="contentinfo" aria-label="Colophon">
</footer>
</main>
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 6d3284e..2d7a0c6 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -240,6 +240,7 @@ The non-negotiables live in [`references/`](references/). **Be precise about wha
**Load-at-the-end:**
- [`slop-test.md`](references/slop-test.md) — load at Step 7 (the gate-check after build), not earlier.
- [`contract.md`](references/contract.md) — load at handoff time for output-contract + scope rules.
+- [`export-formats.md`](references/export-formats.md) — load at Step 6 only when the project warrants multi-format exports (i.e. has a `design.md`). Single-page builds emit `tokens.css` from the in-memory token state and don't need this file.
**Verb-specific:**
- [`verbs/audit.md`](references/verbs/audit.md), [`verbs/refine.md`](references/verbs/refine.md), [`verbs/redesign.md`](references/verbs/redesign.md) — load only when that verb runs.
@@ -353,6 +354,8 @@ Always:
- Cut motion before adding it. Most pages have too much, not too little. If removing an animation wouldn't lose the user information, remove it.
- **Stamp the output.** The first non-empty line of the produced CSS file (or the top of `<style>` if inline) MUST be a comment of the form: `/* Hallmark · macrostructure: <name> · tone: <tone> · anchor hue: <hue> */`. This stamp is the durable record of what you chose. The next time Hallmark runs in this project, it reads the stamp and picks a *different* macrostructure. **For custom themes**, the stamp also carries the vibe, paper + accent OKLCH values, the chosen display + body fonts, and the three diversification axes — the full multi-line format is in [`custom-theme.md`](references/custom-theme.md) § E.
- **Append to project memory.** After you write the stamp, update (or create) `.hallmark/log.json` at the project root. Append a new entry at the **front** of the array: `{ "date": "<YYYY-MM-DD>", "macrostructure": "<name>", "theme": "<name>", "enrichment": "<E# name or 'none'>", "brief": "<one-line summary>" }`. **Custom entries** also carry `"theme": "custom"` plus `"theme_axes": "<paper-band> / <display-style> / <accent-hue>"` and an optional `"vibe": "<4–8 words>"` — see [`custom-theme.md`](references/custom-theme.md) § F. Trim the file to the last 20 entries (rotate the oldest off). Create `.hallmark/` and the file if they don't exist; respect any existing `.gitignore` (the user may or may not want this committed). This file is what Step 2.5 reads on the next run.
+- **Always emit `tokens.css`.** After writing the page CSS, also write `tokens.css` at the project root containing every `--color-*`, `--font-*`, `--space-*`, `--text-*`, `--ease-*`, `--dur-*`, `--rule-*`, and `--radius-*` token used in the build. The page CSS imports `tokens.css` (or, on framework projects, the project's existing entry-point includes it) — the page CSS must reference tokens by name, never inline raw values. Even single-page builds get a `tokens.css`. This is what makes the design system portable to the next project. Load [`export-formats.md`](references/export-formats.md) at this point only when the project warrants additional formats — see below.
+- **Multi-format exports on `design.md` projects.** If a `design.md` exists at the project root (a system-managed project), append all four export formats — `tokens.css`, Tailwind v4 `@theme`, DTCG `tokens.json`, shadcn/ui CSS variables — into `design.md`'s `## Exports` section. Load [`export-formats.md`](references/export-formats.md) for the canonical mapping from Hallmark tokens to each format. Single-page projects skip this step (they get only `tokens.css`).
### 7. The slop test
diff --git a/skill/references/export-formats.md b/skill/references/export-formats.md
new file mode 100644
index 0000000..82c7759
--- /dev/null
+++ b/skill/references/export-formats.md
@@ -0,0 +1,328 @@
+# Export formats
+
+Loaded by [`SKILL.md`](../SKILL.md) Step 6 when emitting the design system as portable tokens. Defines the four canonical formats Hallmark always writes:
+
+1. **`tokens.css`** — the source of truth. Always emitted alongside the page CSS.
+2. **Tailwind v4 `@theme`** — for projects on Tailwind. Emitted into `design.md`'s Exports section on multi-page projects.
+3. **DTCG `tokens.json`** — for projects using a token pipeline (Style Dictionary, Token Studio, Cobalt). Emitted into `design.md`.
+4. **shadcn/ui CSS variables** — for projects using shadcn/ui's component library. Emitted into `design.md`.
+
+The output rule: `tokens.css` is always written. The other three live inline in `design.md` so the user copies whichever they need into a new project. **No new verb.** This is a side effect of every build.
+
+---
+
+## Token taxonomy — Hallmark's source of truth
+
+Every Hallmark output writes these tokens (or a subset, if the page doesn't use one). The names are the source; every other format is a translation.
+
+| Hallmark token | Type | Example value |
+| --- | --- | --- |
+| `--color-paper` | colour | `oklch(96% 0.018 80)` |
+| `--color-paper-2` | colour | `oklch(94% 0.020 80)` |
+| `--color-paper-3` | colour | `oklch(91% 0.022 80)` |
+| `--color-ink` | colour | `oklch(15% 0.012 80)` |
+| `--color-ink-2` | colour | `oklch(28% 0.014 80)` |
+| `--color-rule` | colour | `oklch(86% 0.018 80)` |
+| `--color-rule-2` | colour | `oklch(72% 0.020 80)` |
+| `--color-muted` | colour | `oklch(50% 0.014 80)` |
+| `--color-neutral` | colour | `oklch(38% 0.012 80)` |
+| `--color-accent` | colour | `oklch(58% 0.16 70)` |
+| `--color-accent-ink` | colour | (text on accent fill, ≥ APCA 7:1) |
+| `--color-focus` | colour | (often = accent at higher chroma) |
+| `--font-display` | font | `"Fraunces", ui-serif, Georgia, serif` |
+| `--font-body` | font | `"Geist", ui-sans-serif, system-ui, sans-serif` |
+| `--font-outlier` | font | `"Geist Mono", ui-monospace, monospace` |
+| `--space-3xs` … `--space-5xl` | length | 4-pt scale: `0.25rem` … `8rem` |
+| `--text-xs` … `--text-display` | length | 1.25 (major-third) ratio scale |
+| `--ease-out` / `--ease-in` / `--ease-in-out` | easing | `cubic-bezier(0.16, 1, 0.3, 1)` etc. |
+| `--dur-micro` / `--dur-short` / `--dur-long` | time | `120ms` / `220ms` / `420ms` |
+| `--rule-hair` / `--rule-fine` | length | `1px` / `2px` |
+| `--radius-card` / `--radius-pill` / `--radius-input` | length | varies per theme |
+| `--shadow-card` | shadow | varies per theme |
+
+If the page introduces *additional* tokens, name them by role and add to `tokens.css`. Don't make up token names downstream that aren't in `tokens.css` — the source of truth is the source of truth.
+
+---
+
+## Format 1 — `tokens.css`
+
+The source. Plain CSS custom properties at `:root`. Every Hallmark page CSS imports this file at the top:
+
+```css
+@import "tokens.css";
+/* page CSS continues — uses var(--color-paper), never raw values */
+```
+
+Or, if the project uses a CSS bundler / framework that doesn't honour bare `@import`, the project's existing entry-point includes `tokens.css` first. The page CSS still references tokens by name, never by raw value.
+
+**Worked example — editorial theme (Specimen-like):**
+
+```css
+:root {
+ --color-paper: oklch(96% 0.018 80);
+ --color-paper-2: oklch(94% 0.020 80);
+ --color-paper-3: oklch(91% 0.022 80);
+ --color-rule: oklch(86% 0.020 78);
+ --color-rule-2: oklch(72% 0.022 78);
+ --color-muted: oklch(50% 0.018 78);
+ --color-neutral: oklch(38% 0.014 76);
+ --color-ink-2: oklch(28% 0.012 75);
+ --color-ink: oklch(15% 0.010 75);
+ --color-accent: oklch(58% 0.16 60);
+ --color-accent-ink: oklch(98% 0.012 75);
+ --color-focus: oklch(58% 0.16 60);
+
+ --font-display: "Fraunces", "Cardo", ui-serif, Georgia, serif;
+ --font-body: "Geist", "Söhne", ui-sans-serif, system-ui, sans-serif;
+ --font-outlier: "Geist Mono", "JetBrains Mono", ui-monospace, monospace;
+
+ --display-weight: 400;
+ --display-style: italic;
+ --tracking-display: -0.02em;
+ --tracking-label: 0.10em;
+
+ --text-xs: 0.75rem;
+ --text-sm: 0.875rem;
+ --text-md: 1.125rem;
+ --text-lg: 1.375rem;
+ --text-xl: 1.75rem;
+ --text-2xl: 2.25rem;
+ --text-display: clamp(3rem, 6vw + 1rem, 6.5rem);
+
+ --space-3xs: 0.25rem;
+ --space-2xs: 0.5rem;
+ --space-xs: 0.75rem;
+ --space-sm: 1rem;
+ --space-md: 1.5rem;
+ --space-lg: 2rem;
+ --space-xl: 3rem;
+ --space-2xl: 4.5rem;
+ --space-3xl: 7rem;
+ --space-4xl: 11rem;
+
+ --rule-hair: 0.5px;
+ --rule-fine: 1px;
+ --radius-card: 0;
+ --radius-pill: 0;
+ --radius-input: 0;
+
+ --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+ --ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+ --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+ --dur-micro: 120ms;
+ --dur-short: 220ms;
+ --dur-long: 420ms;
+}
+```
+
+**Worked example — modern-minimal theme (Quiet-like):**
+
+```css
+:root {
+ --color-paper: oklch(100% 0 0);
+ --color-paper-2: oklch(98.5% 0 0);
+ --color-paper-3: oklch(96% 0 0);
+ --color-rule: oklch(91% 0 0);
+ --color-rule-2: oklch(82% 0 0);
+ --color-muted: oklch(55% 0 0);
+ --color-neutral: oklch(40% 0 0);
+ --color-ink-2: oklch(28% 0 0);
+ --color-ink: oklch(15% 0 0);
+ --color-accent: oklch(15% 0 0);
+ --color-accent-ink: oklch(100% 0 0);
+ --color-focus: oklch(60% 0.10 240);
+
+ --font-display: "Geist", "Inter", ui-sans-serif, system-ui, sans-serif;
+ --font-body: "Geist", "Inter", ui-sans-serif, system-ui, sans-serif;
+ --font-outlier: "Geist Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+ --display-weight: 600;
+ --display-style: normal;
+ --tracking-display: -0.025em;
+
+ --radius-card: 8px;
+ --radius-pill: 999px;
+ --radius-input: 8px;
+}
+```
+
+---
+
+## Format 2 — Tailwind v4 `@theme`
+
+Tailwind v4 reads CSS variables inside `@theme` and generates utilities (`bg-paper`, `text-ink`, etc.) automatically. The translation from Hallmark tokens is direct — same variable names, same OKLCH values:
+
+```css
+@theme {
+ /* Colours */
+ --color-paper: oklch(96% 0.018 80);
+ --color-paper-2: oklch(94% 0.020 80);
+ --color-paper-3: oklch(91% 0.022 80);
+ --color-rule: oklch(86% 0.020 78);
+ --color-rule-2: oklch(72% 0.022 78);
+ --color-muted: oklch(50% 0.018 78);
+ --color-neutral: oklch(38% 0.014 76);
+ --color-ink-2: oklch(28% 0.012 75);
+ --color-ink: oklch(15% 0.010 75);
+ --color-accent: oklch(58% 0.16 60);
+ --color-focus: oklch(58% 0.16 60);
+
+ /* Fonts */
+ --font-display: "Fraunces", "Cardo", ui-serif, Georgia, serif;
+ --font-body: "Geist", ui-sans-serif, system-ui, sans-serif;
+ --font-outlier: "Geist Mono", ui-monospace, monospace;
+
+ /* Spacing — Tailwind reads --spacing-* by default; we keep Hallmark's --space-* names alongside */
+ --spacing-3xs: 0.25rem;
+ --spacing-2xs: 0.5rem;
+ --spacing-xs: 0.75rem;
+ --spacing-sm: 1rem;
+ --spacing-md: 1.5rem;
+ --spacing-lg: 2rem;
+ --spacing-xl: 3rem;
+ --spacing-2xl: 4.5rem;
+
+ /* Type scale — Tailwind reads --text-* */
+ --text-xs: 0.75rem;
+ --text-sm: 0.875rem;
+ --text-md: 1.125rem;
+ --text-lg: 1.375rem;
+ --text-xl: 1.75rem;
+ --text-2xl: 2.25rem;
+
+ /* Radius */
+ --radius-card: 0;
+ --radius-pill: 0;
+ --radius-input: 0;
+
+ /* Easings — Tailwind reads --ease-* */
+ --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+ --ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+ --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+}
+```
+
+Notes:
+- Tailwind v4 expects `--spacing-*` (with `ing`) for the spacing utilities. We mirror Hallmark's `--space-*` to `--spacing-*` so both names work.
+- `--text-*` works as-is (Tailwind v4 picks them up for `text-md` etc.).
+- `--font-*` becomes `font-display` / `font-body` / `font-outlier` utilities.
+- The user's `tailwind.config.{ts,js}` may need `@source` directives but no `theme.extend` — v4 reads `@theme` directly.
+
+---
+
+## Format 3 — DTCG `tokens.json`
+
+W3C Design Tokens Community Group format. For projects using Style Dictionary, Cobalt, or Token Studio. Path-based; OKLCH stays as a string value; `$type` is required.
+
+```json
+{
+ "$schema": "https://design-tokens.github.io/community-group/format/",
+ "color": {
+ "paper": { "$value": "oklch(96% 0.018 80)", "$type": "color" },
+ "paper-2": { "$value": "oklch(94% 0.020 80)", "$type": "color" },
+ "paper-3": { "$value": "oklch(91% 0.022 80)", "$type": "color" },
+ "rule": { "$value": "oklch(86% 0.020 78)", "$type": "color" },
+ "rule-2": { "$value": "oklch(72% 0.022 78)", "$type": "color" },
+ "muted": { "$value": "oklch(50% 0.018 78)", "$type": "color" },
+ "neutral": { "$value": "oklch(38% 0.014 76)", "$type": "color" },
+ "ink-2": { "$value": "oklch(28% 0.012 75)", "$type": "color" },
+ "ink": { "$value": "oklch(15% 0.010 75)", "$type": "color" },
+ "accent": { "$value": "oklch(58% 0.16 60)", "$type": "color" },
+ "focus": { "$value": "oklch(58% 0.16 60)", "$type": "color" }
+ },
+ "font": {
+ "display": { "$value": "Fraunces, Cardo, ui-serif, Georgia, serif", "$type": "fontFamily" },
+ "body": { "$value": "Geist, ui-sans-serif, system-ui, sans-serif", "$type": "fontFamily" },
+ "outlier": { "$value": "Geist Mono, ui-monospace, monospace", "$type": "fontFamily" }
+ },
+ "size": {
+ "text-xs": { "$value": "0.75rem", "$type": "dimension" },
+ "text-sm": { "$value": "0.875rem", "$type": "dimension" },
+ "text-md": { "$value": "1.125rem", "$type": "dimension" },
+ "text-lg": { "$value": "1.375rem", "$type": "dimension" },
+ "text-xl": { "$value": "1.75rem", "$type": "dimension" },
+ "text-2xl": { "$value": "2.25rem", "$type": "dimension" },
+ "text-display": { "$value": "6rem", "$type": "dimension" }
+ },
+ "space": {
+ "3xs": { "$value": "0.25rem", "$type": "dimension" },
+ "2xs": { "$value": "0.5rem", "$type": "dimension" },
+ "xs": { "$value": "0.75rem", "$type": "dimension" },
+ "sm": { "$value": "1rem", "$type": "dimension" },
+ "md": { "$value": "1.5rem", "$type": "dimension" },
+ "lg": { "$value": "2rem", "$type": "dimension" },
+ "xl": { "$value": "3rem", "$type": "dimension" },
+ "2xl": { "$value": "4.5rem", "$type": "dimension" },
+ "3xl": { "$value": "7rem", "$type": "dimension" },
+ "4xl": { "$value": "11rem", "$type": "dimension" }
+ },
+ "duration": {
+ "micro": { "$value": "120ms", "$type": "duration" },
+ "short": { "$value": "220ms", "$type": "duration" },
+ "long": { "$value": "420ms", "$type": "duration" }
+ }
+}
+```
+
+Notes:
+- DTCG accepts `oklch(...)` strings on modern tooling. If the user's pipeline doesn't, convert to hex (lossy — flag this) or to `color(oklch ...)` (CSS Color 4).
+- The `text-display` value uses a fixed `6rem` for portability — the responsive `clamp(...)` belongs in CSS, not in token JSON.
+
+---
+
+## Format 4 — shadcn/ui CSS variables
+
+shadcn/ui's component library reads CSS custom properties with specific names, in a specific shape. The values are **space-separated** triples (no `oklch()` wrapper, no commas) so shadcn can compose them with `oklch(<value> / <alpha>)`.
+
+The translation from Hallmark tokens:
+
+```css
+:root {
+ --background: 96% 0.018 80; /* paper */
+ --foreground: 15% 0.010 75; /* ink */
+
+ --card: 94% 0.020 80; /* paper-2 */
+ --card-foreground: 15% 0.010 75; /* ink */
+
+ --popover: 94% 0.020 80; /* paper-2 */
+ --popover-foreground: 15% 0.010 75; /* ink */
+
+ --primary: 58% 0.16 60; /* accent */
+ --primary-foreground: 98% 0.012 75; /* accent-ink */
+
+ --secondary: 91% 0.022 80; /* paper-3 */
+ --secondary-foreground: 28% 0.012 75; /* ink-2 */
+
+ --muted: 86% 0.020 78; /* rule */
+ --muted-foreground: 50% 0.018 78; /* muted */
+
+ --accent: 58% 0.16 60; /* accent (same as primary in Hallmark) */
+ --accent-foreground: 98% 0.012 75;
+
+ --destructive: 58% 0.20 25; /* warm red, fixed */
+ --destructive-foreground: 98% 0.012 75;
+
+ --border: 86% 0.020 78; /* rule */
+ --input: 86% 0.020 78; /* rule */
+ --ring: 58% 0.16 60; /* focus */
+
+ --radius: 0; /* radius-card; shadcn uses one value */
+}
+```
+
+Then the user's `tailwind.config.ts` (or v4 `@theme`) reads them with `oklch(var(--background))`. Hallmark's accent → shadcn's primary is the canonical mapping; secondary → paper-3.
+
+If the user wants a dark variant, mirror with the dark theme tokens under a `.dark` selector (Hallmark's Midnight / Bloom / Terminal supply the values).
+
+---
+
+## Output rule
+
+When SKILL.md Step 6 emits exports:
+
+1. **Always** write `tokens.css` next to the page CSS (or in the project root for multi-file projects). Format 1.
+2. **On `design.md`-managed projects** (multi-page), embed all four formats inline in `design.md`'s Exports section. The user copies whichever they need.
+3. **On Tailwind projects** (detected at pre-flight), additionally surface the Tailwind `@theme` block in the build output so the user knows where to paste it (typically into `app/globals.css` or the equivalent).
+
+Don't blanket-emit tokens.json or shadcn variables on single-page projects — the user can copy them out of `design.md` if they upgrade to a multi-page system.
diff --git a/skill/references/verbs/redesign.md b/skill/references/verbs/redesign.md
index dd18d7a..4e064fe 100644
--- a/skill/references/verbs/redesign.md
+++ b/skill/references/verbs/redesign.md
@@ -36,7 +36,7 @@ Before redesigning a single file:
Write a single file at the project root: `design.md` (or `DESIGN.md` — match the project's existing case convention). This file is the **one source of truth** every subsequent page redesign reads. Format:
-```markdown
+````markdown
# Design — <Project name>
A locked design system for this app. Every page redesign reads this file before
@@ -107,7 +107,90 @@ tokens (`var(--space-md)`), never raw values.
type, colour, and CTA voice).
- Hero archetype (within the family's allowance).
- Enrichment — only on marketing pages, only Tier-A or Tier-B.
+
+## Exports
+
+Drop-in formats for re-using this design system in other projects.
+See [`export-formats.md`](../export-formats.md) for the canonical mapping.
+
+### tokens.css
+```css
+:root {
+ --color-paper: oklch(<L> <C> <H>);
+ --color-paper-2: oklch(<L> <C> <H>);
+ --color-ink: oklch(<L> <C> <H>);
+ --color-ink-2: oklch(<L> <C> <H>);
+ --color-rule: oklch(<L> <C> <H>);
+ --color-accent: oklch(<L> <C> <H>);
+ --color-accent-ink: oklch(<L> <C> <H>);
+ --color-focus: oklch(<L> <C> <H>);
+
+ --font-display: "<face>", ...;
+ --font-body: "<face>", ...;
+ --font-outlier: "<face>", ...;
+
+ --space-3xs: 0.25rem; --space-2xs: 0.5rem; --space-xs: 0.75rem;
+ --space-sm: 1rem; --space-md: 1.5rem; --space-lg: 2rem;
+ --space-xl: 3rem; --space-2xl: 4.5rem; --space-3xl: 7rem;
+
+ --text-xs: 0.75rem; --text-sm: 0.875rem; --text-md: 1.125rem;
+ --text-lg: 1.375rem; --text-xl: 1.75rem; --text-2xl: 2.25rem;
+
+ --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+ --dur-short: 220ms;
+ --radius-card: <px>; --radius-pill: <px>; --radius-input: <px>;
+}
+```
+
+### Tailwind v4 `@theme`
+```css
+@theme {
+ --color-paper: oklch(<L> <C> <H>);
+ --color-ink: oklch(<L> <C> <H>);
+ --color-accent: oklch(<L> <C> <H>);
+ --font-display: "<face>", sans-serif;
+ --font-body: "<face>", sans-serif;
+ --spacing-md: 1.5rem;
+ --text-md: 1.125rem;
+ --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+ /* mirror the rest of tokens.css with `--spacing-*` for Tailwind's spacing utilities */
+}
+```
+
+### DTCG `tokens.json`
+```json
+{
+ "color": {
+ "paper": { "$value": "oklch(<L> <C> <H>)", "$type": "color" },
+ "ink": { "$value": "oklch(<L> <C> <H>)", "$type": "color" },
+ "accent": { "$value": "oklch(<L> <C> <H>)", "$type": "color" }
+ },
+ "font": {
+ "display": { "$value": "<face>", "$type": "fontFamily" },
+ "body": { "$value": "<face>", "$type": "fontFamily" }
+ },
+ "space": {
+ "md": { "$value": "1.5rem", "$type": "dimension" }
+ }
+}
+```
+
+### shadcn/ui CSS variables
+```css
+:root {
+ --background: <L> <C> <H>; /* paper */
+ --foreground: <L> <C> <H>; /* ink */
+ --primary: <L> <C> <H>; /* accent */
+ --primary-foreground: <L> <C> <H>; /* accent-ink */
+ --muted: <L> <C> <H>; /* rule */
+ --muted-foreground: <L> <C> <H>; /* muted */
+ --border: <L> <C> <H>; /* rule */
+ --input: <L> <C> <H>; /* rule */
+ --ring: <L> <C> <H>; /* focus */
+ --radius: <px>;
+}
```
+````
State the picks aloud in plain text BEFORE writing the file. *"Genre: modern-minimal. Theme: a custom OKLCH palette anchored on your brand teal. Display: Geist 600. Body: Geist 400. Three macrostructure families: Marquee Hero (marketing), Workbench (app), Long Document (content)."* Then ask: *"Want me to proceed with this system across every page, or amend any of it first?"*