Skip to content

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

CSS

Macrostructure layer — fix the default-attractor problem

Youssef34701de82989
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 8ea5dd6..0be0952 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -45,18 +45,21 @@ If any of the three is missing, ask for it in one short message. Ask for all mis
Once you have the three, restate them in one sentence and proceed.
-### 2. Pick a structural fingerprint
+### 2. Pick a macrostructure FIRST
-Before loading the visual ruleset, decide the **structural fingerprint** of this page along these axes (one decision each — see [`references/structure.md`](references/structure.md) for the full catalogue):
+Before loading any visual ruleset, **pick one of the twenty-one named macrostructures in [`references/macrostructures.md`](references/macrostructures.md).** Each macrostructure is a complete page-shape — heading placement, body composition, divider language, button voice, image treatment, reveal — bundled as a single named choice. Picking one named macrostructure is faster and more varied than choosing six independent axes from scratch.
-- **Section-heading placement.** Left margin / hanging / centered / bottom-aligned / overlapping image / sticky / numbered display / inline.
-- **Body composition.** Single column / two-column asymmetric / multi-column justified / marginalia / three-column equal / full-bleed with reset / asymmetric spans.
-- **Divider language.** Hairline rule / ornament / negative space / bleed-color block.
-- **Button voice.** Outlined / unstyled link / oversized solid / typographic-only.
-- **Image treatment.** Full-bleed / tightly cropped / inline / margin-aligned / none.
-- **Reveal pattern.** Fade-up stagger / horizontal sweep / type-unmask / number-tick / typewriter / none.
+**Diversification rule (mandatory).** Before you pick:
-Pick a *combination*. The combination is the page's voice. Two combinations should never be identical across pages you build for the same user. If a previous page in this session used left-margin labels with hairline dividers, this one should not.
+1. Look in the target codebase for an existing `/* Hallmark · macrostructure: <name> · ... */` stamp at the top of any CSS file. If you find one, your pick must be a *different* macrostructure.
+2. If you have produced any other Hallmark output for this user in this session, your pick must be a different macrostructure than the last one.
+3. **The Specimen macrostructure (numbered left-margin labels + huge serif + asymmetric spans + typographic CTA) is no longer a default.** Reach for it only when the brief is explicitly editorial, foundry-adjacent, or the user has named it.
+
+**State your pick.** Before writing any code, say "Macrostructure: <name>." in plain text. This is a deliberate accountability step — picking on the page (not in your head) prevents the default-attractor sameness that kept the skill emitting Specimen output.
+
+If the brief is genuinely vague (no theme, no tone), do **not** default. Offer the user three macrostructures from *categorically different* groups (e.g. one grid-led like Bento, one document-led like Long Document, one poster-led like Manifesto). Three concrete choices, not seven abstract tones.
+
+The macrostructure picks five of the six structural axes for you; you only need to pick the reveal yourself. The deeper axis catalogue is still in [`references/structure.md`](references/structure.md) when you need to deviate from the macrostructure's defaults.
### 3. Load the visual ruleset
@@ -65,7 +68,9 @@ The non-negotiables live in [`references/`](references/). Read only what you nee
- [`typography.md`](references/typography.md) — fonts, scale, pairing, weights, measure
- [`color.md`](references/color.md) — OKLCH, palette construction, accent discipline, dark mode
- [`layout-and-space.md`](references/layout-and-space.md) — 4pt scale, grid-breaks, asymmetry, depth
-- [`structure.md`](references/structure.md) — heading patterns, body composition, dividers, component voice, reveal style
+- [`macrostructures.md`](references/macrostructures.md) — twenty-one named whole-page shapes (Bento Grid, Long Document, Marquee Hero, Stat-Led, Workbench, etc.); pick one before writing code
+- [`component-cookbook.md`](references/component-cookbook.md) — thirty-two component archetypes (six hero shapes, five section-head shapes, five feature blocks, four CTA shapes, four testimonials, four footers, four navigations) you can compose into any macrostructure
+- [`structure.md`](references/structure.md) — the six primitive axes underlying the macrostructures, for when you need to deviate
- [`motion.md`](references/motion.md) — durations, easings, what to animate, reduced-motion
- [`microinteractions.md`](references/microinteractions.md) — per-interaction recipes (button press, focus, modal, toast, optimistic update, command palette, drag, copy-to-clipboard, search-as-you-type) and the named microinteraction tells
- [`interaction-and-states.md`](references/interaction-and-states.md) — the eight states, focus, hit-targets, forms
@@ -73,7 +78,7 @@ The non-negotiables live in [`references/`](references/). Read only what you nee
- [`copy.md`](references/copy.md) — verbs, labels, error structure, link text
- [`anti-patterns.md`](references/anti-patterns.md) — the named tells you must not emit
-For most design work you need `typography`, `color`, `layout-and-space`, `structure`, and `anti-patterns`. **Load `microinteractions` whenever the output has *any* interactive element** — buttons, links, inputs, forms, modals, tabs, dropdowns, toasts, drag handles, command palettes, copy buttons, anything with hover/focus/active states. That is most pages.
+For most design work you need `macrostructures`, `component-cookbook`, `typography`, `color`, `layout-and-space`, and `anti-patterns`. **Load `microinteractions` whenever the output has *any* interactive element** — buttons, links, inputs, forms, modals, tabs, dropdowns, toasts, drag handles, command palettes, copy buttons, anything with hover/focus/active states. That is most pages.
### 4. Build
@@ -91,10 +96,11 @@ Always:
- Include `:focus-visible` with a visible ring at ≥3:1 contrast. **Never animate the ring's appearance** — it must show instantly on focus.
- For each interaction in the output (button, input, modal, toast, drag, copy, etc.), apply the recipe in [`microinteractions.md`](references/microinteractions.md). Pick *silent success* over celebratory toasts. Pick *optimistic update + Undo* over confirmation dialogs. Pick *delay 800ms* on hover tooltips and *0ms* on focus tooltips.
- 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.
### 5. The slop test
-Before handing back, run the output through these twenty questions. Every answer must be **no**.
+Before handing back, run the output through these twenty-three questions. Every answer must be **no**.
**Visual:**
@@ -125,6 +131,12 @@ Before handing back, run the output through these twenty questions. Every answer
19. Is auto-rotating content (carousel, banner, stats) lacking pause-on-hover-and-focus? (WCAG 2.2.2.)
20. Is there a placeholder name "Jane Doe / John Smith" or a startup cliché (Acme, Nexus, Seamless, Unleash)?
+**Variety:**
+
+21. Is the `/* Hallmark · macrostructure: <name> · ... */` stamp missing from the top of the CSS? (It must be present.)
+22. Is the macrostructure I picked the same as a previous Hallmark output's stamp in this project? (Read the file system; if a stamp exists, mine must differ.)
+23. Did I default to the **Specimen** macrostructure (numbered left-margin labels + huge serif + asymmetric spans + typographic-only CTA) when the brief did not explicitly call for editorial / foundry / specimen energy? (Specimen fall-through is banned.)
+
If any answer is yes, fix it. Do not ship slop.
---
diff --git a/skill/references/anti-patterns.md b/skill/references/anti-patterns.md
index 67e0a3d..2c72836 100644
--- a/skill/references/anti-patterns.md
+++ b/skill/references/anti-patterns.md
@@ -56,6 +56,22 @@ A card with a thick coloured border on one edge (usually left, 4–6px, purple o
**Fix.** Tint toward your anchor hue. See [`color.md`](color.md).
+### Default-attractor sameness
+
+Two consecutive Hallmark outputs in the same project use the same macrostructure. The first emitted left-margin numbered labels + huge serif + asymmetric spans (Specimen); the second did exactly the same. The page looks redesigned only because copy changed.
+
+**Why it fails.** Hallmark's whole point is that two pages for two briefs feel like *different sites*, not colour-swaps of one template. Repeating a macrostructure across outputs is the structural fingerprint of templating, which is the AI tell Hallmark exists to defeat.
+
+**Fix.** Before writing code, look in the project's CSS for a `/* Hallmark · macrostructure: <name> · ... */` stamp. If one exists, your pick must be a different macrostructure — categorically different where possible (a serif-led editorial macrostructure paired with a sans-led grid one, not two editorial variants). See [`macrostructures.md`](macrostructures.md) for the twenty-one named choices.
+
+### Specimen fall-through
+
+Producing the Specimen macrostructure (numbered left-margin labels like `01 — HELLO.` + huge serif display + asymmetric spans + hairline rules + typographic-only CTA + sometimes a hand-drawn SVG accent) when the brief did not explicitly request editorial / foundry / specimen energy. This is the single most-repeated Hallmark output, and it's the reason the skill felt like it had one shape.
+
+**Why it fails.** Specimen is a beautiful pattern when the brief is editorial. Applied to a SaaS pricing page, a developer tool, an e-commerce site, or a personal app, it looks like the AI defaulted — because it did.
+
+**Fix.** The Specimen macrostructure is one of twenty-one in [`macrostructures.md`](macrostructures.md), not a default. If the brief is vague, pick from the first ten in that file (Bento Grid, Long Document, Marquee Hero, Stat-Led, Workbench, Conversational FAQ, Manifesto, Photographic, Quote-Led, then Specimen). Reach for Specimen only when the brief explicitly says "editorial", "specimen sheet", "type foundry", or names the Specimen theme.
+
---
## Major (looks AI-generated)
diff --git a/skill/references/component-cookbook.md b/skill/references/component-cookbook.md
new file mode 100644
index 0000000..0dc2918
--- /dev/null
+++ b/skill/references/component-cookbook.md
@@ -0,0 +1,488 @@
+# Component cookbook
+
+Thirty-two component archetypes you can compose into any macrostructure. Every entry: a *shape*, a one-line "use when", a one-line "don't confuse with", and a short structural sketch (DOM + minimal CSS). Pick from this file when you're building a section and don't know which shape to reach for.
+
+The same macrostructure (e.g., Bento Grid) can be built from many different combinations of these archetypes. The macrostructure picks the *page shape*; this file picks the *components inside it*.
+
+**Diversification rule:** within a single page, no two sections should use the same archetype. A Bento Grid might pair *Bento feature block* with *Inline form CTA* with *Logo wall (hairline)*. The next page Hallmark builds should pick different archetypes from the same categories.
+
+---
+
+## Heroes
+
+### H1 · Marquee
+A single statement fills the fold. No subhead, no CTA in view.
+*Use when:* the brand or person *is* the message.
+*Don't confuse with:* H4 Stat-Led (which is a number, not a statement).
+
+```html
+<section class="hero-marquee">
+ <h1 class="display-xxl">A statement.</h1>
+</section>
+```
+```css
+.hero-marquee { min-height: 80dvh; display: grid; align-content: end; padding: 0 var(--page-gutter) var(--space-2xl); }
+.display-xxl { font-size: clamp(4rem, 12vw, 12rem); line-height: 0.92; }
+```
+
+### H2 · Split Diptych
+Headline + lede on one side, image or product capture on the other. 6/6 or 7/5 columns.
+*Use when:* you can pair every claim with a visual proof.
+*Don't confuse with:* H6 Photographic (which puts the image full-bleed, not paired).
+
+```html
+<section class="hero-split">
+ <div><h1>…</h1><p>…</p><a class="cta-outline">…</a></div>
+ <figure><img src="" /></figure>
+</section>
+```
+```css
+.hero-split { display: grid; grid-template-columns: 7fr 5fr; gap: var(--space-2xl); align-items: center; }
+@media (max-width: 56rem) { .hero-split { grid-template-columns: 1fr; } }
+```
+
+### H3 · Quote-Led
+A pull-quote with attribution is the hero. Your headline is borrowed credibility.
+*Use when:* you have a real testimonial that earns the front page.
+*Don't confuse with:* T3 Single huge quote (which lives mid-page, not in the hero slot).
+
+```html
+<section class="hero-quote">
+ <blockquote class="display-italic">"…"</blockquote>
+ <p class="attribution">— Name, Role, Company</p>
+</section>
+```
+
+### H4 · Stat-Led
+A giant number or metric is the hero. A small qualifier line below.
+*Use when:* you have one defensible, externally-verifiable number.
+*Don't confuse with:* T4 Numbered stat strip (which is several stats in a row, not one focal).
+
+```html
+<section class="hero-stat">
+ <p class="figure tnum">99.97<span class="unit">%</span></p>
+ <p class="qualifier">…</p>
+</section>
+```
+```css
+.figure { font-size: clamp(6rem, 18vw, 16rem); font-variant-numeric: tabular-nums; line-height: 0.85; }
+```
+
+### H5 · Letter Hero
+First-person opening — "Dear reader,". No buttons in fold. Reads as personal correspondence.
+*Use when:* the founder's voice is the brand.
+*Don't confuse with:* H1 Marquee (which is impersonal declaration).
+
+```html
+<section class="hero-letter">
+ <p class="salutation"><em>Dear reader,</em></p>
+ <p class="lede">…</p>
+</section>
+```
+
+### H6 · Photographic Fold
+Single full-bleed image fills the viewport. Caption sits in a corner.
+*Use when:* you have real photography that earns full-bleed.
+*Don't confuse with:* H2 Split (which pairs image with text in a grid).
+
+```html
+<section class="hero-photo">
+ <img class="bleed" src="" alt="" />
+ <p class="caption">Spring, 2026.</p>
+</section>
+```
+```css
+.hero-photo { position: relative; height: 80dvh; }
+.hero-photo .bleed { width: 100%; height: 100%; object-fit: cover; }
+.hero-photo .caption { position: absolute; bottom: var(--space-md); right: var(--space-md); }
+```
+
+---
+
+## Section heads
+
+### S1 · Left-margin numbered
+A narrow left column holds `01 — LABEL.`; the wide right column holds the heading and content.
+*Use when:* the page is editorial / specimen.
+*Don't confuse with:* S5 Bottom-anchored (which puts the label *under* the section).
+
+```html
+<header class="head-margin">
+ <p class="num-label">01 — Foundations</p>
+ <h2>…</h2>
+</header>
+```
+```css
+.head-margin { display: grid; grid-template-columns: 10rem 1fr; gap: var(--space-xl); align-items: baseline; }
+```
+
+### S2 · Hanging
+Heading floats above the section in negative space; no border, no rule.
+*Use when:* the content has a quiet, room-to-breathe energy.
+*Don't confuse with:* S3 Sticky-pinned (which moves with scroll).
+
+```html
+<header class="head-hang">
+ <h2>…</h2>
+</header>
+```
+```css
+.head-hang { padding-block: var(--space-3xl) var(--space-xl); }
+```
+
+### S3 · Sticky pinned
+Heading remains in viewport while content scrolls beneath. Orientation aid.
+*Use when:* the section is dense and the user benefits from always seeing where they are.
+*Don't confuse with:* S1 Left-margin (which doesn't move).
+
+```html
+<header class="head-sticky">
+ <p class="num-label">02</p>
+ <h2>…</h2>
+</header>
+```
+```css
+.head-sticky { position: sticky; top: 0; background: var(--color-paper); padding-block: var(--space-sm); border-bottom: 1px solid var(--color-ink); z-index: 10; }
+```
+
+### S4 · Inline (no break)
+The heading is a small caps phrase that emerges *inside* the body flow; no spatial break.
+*Use when:* the page is prose-led; reading should be continuous.
+*Don't confuse with:* S2 Hanging (which separates with negative space).
+
+```html
+<p>… <span class="head-inline">A small heading.</span> …</p>
+```
+```css
+.head-inline { font-variant-caps: all-small-caps; letter-spacing: 0.06em; font-weight: 500; }
+```
+
+### S5 · Bottom-anchored
+The label or heading sits *below* the section's content. Inverts hierarchy.
+*Use when:* the content is the primary act and the label is a footer to it.
+*Don't confuse with:* S1 Left-margin (which leads with the label).
+
+```html
+<section>
+ <div class="content">…</div>
+ <p class="num-label">— end of 02</p>
+</section>
+```
+
+---
+
+## Feature blocks
+
+### F1 · Bento grid
+Asymmetric grid of 8–15 tiles in mixed spans (1×1, 2×1, 1×2, 2×2). Visual rhythm via size.
+*Use when:* multiple equally-valid entry points; SaaS feature page.
+*Don't confuse with:* F2 Sticky-scroll (which stacks vertically with sticky pacing).
+
+```html
+<section class="bento">
+ <article class="cell span-2x2">…</article>
+ <article class="cell span-1x1">…</article>
+ <article class="cell span-2x1">…</article>
+</section>
+```
+```css
+.bento { display: grid; grid-template-columns: repeat(4, 1fr); grid-auto-rows: 12rem; gap: var(--space-md); }
+.span-2x2 { grid-column: span 2; grid-row: span 2; }
+.span-2x1 { grid-column: span 2; }
+.span-1x2 { grid-row: span 2; }
+@media (max-width: 56rem) { .bento { grid-template-columns: repeat(2, 1fr); } }
+```
+
+### F2 · Sticky-scroll stack
+Sticky left pane, scrolling right pane that cycles through related screenshots.
+*Use when:* feature has multiple sub-states worth showing in sequence.
+*Don't confuse with:* F4 Step sequence (which is linearly numbered, not synced).
+
+```html
+<section class="sticky-stack">
+ <div class="pane-sticky"><h3>…</h3><p>…</p></div>
+ <div class="pane-scroll">
+ <figure>1</figure><figure>2</figure><figure>3</figure>
+ </div>
+</section>
+```
+```css
+.sticky-stack { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-2xl); }
+.pane-sticky { position: sticky; top: var(--space-xl); align-self: start; }
+```
+
+### F3 · Tabular spec sheet
+Each row is a feature; columns hold name, value, footnote. Hairline rules between rows. Tabular numerics.
+*Use when:* features compare quantitatively.
+*Don't confuse with:* F1 Bento (which is non-tabular and visually rhythmic).
+
+```html
+<table class="spec-sheet tnum">
+ <tr><th>Latency</th><td>p99 &lt; 50 ms</td><td class="muted">measured externally</td></tr>
+ <tr>…</tr>
+</table>
+```
+
+### F4 · Step sequence
+Numbered stages (`1.0 → 2.0 → 3.0`) flow vertically. Each stage has a heading, a paragraph, sometimes a small visual.
+*Use when:* the product is a workflow, not a single moment.
+*Don't confuse with:* F2 Sticky-scroll (which doesn't number stages).
+
+```html
+<ol class="steps">
+ <li><span class="stage">1.0</span><h3>Intake.</h3><p>…</p></li>
+ <li><span class="stage">2.0</span><h3>Plan.</h3><p>…</p></li>
+</ol>
+```
+
+### F5 · Annotated screenshot
+A product capture sits centre-stage with arrows or short labels pointing to UI details.
+*Use when:* the product UI itself is the explanation.
+*Don't confuse with:* F2 Sticky-scroll (which uses multiple screenshots in sequence).
+
+```html
+<figure class="annotated">
+ <img src="" />
+ <span class="callout" style="--x:60%; --y:30%;">→ assigns automatically.</span>
+</figure>
+```
+
+---
+
+## CTAs / signups
+
+### C1 · Outlined chip
+A bordered, transparent button with a typographic verb ("Save changes").
+*Use when:* the page has one primary action; you want it visible but quiet.
+*Don't confuse with:* C2 Oversized solid (which is statement-loud).
+
+```html
+<a class="cta-outline">Open your studio →</a>
+```
+```css
+.cta-outline { display: inline-flex; align-items: center; gap: 0.4em; padding: 0.7rem 1.2rem; border: 1px solid var(--color-ink); min-height: 44px; }
+```
+
+### C2 · Inline form-as-CTA
+The CTA *is* the form — a single email input with a "Submit →" beside it. No separate landing for sign-up.
+*Use when:* the action is collecting an email.
+*Don't confuse with:* C1 Outlined chip (which navigates, not submits).
+
+```html
+<form class="cta-form">
+ <label for="email" class="visually-hidden">Email</label>
+ <input id="email" type="email" placeholder="[email protected]" />
+ <button type="submit">Send →</button>
+</form>
+```
+```css
+.cta-form { display: grid; grid-template-columns: 1fr auto; border-bottom: 1px solid var(--color-ink); }
+.cta-form input { background: none; border: 0; padding: 0.7rem 0; min-height: 44px; }
+```
+
+### C3 · Typographic link
+Just a word, an arrow, and a 1-px underline. No box, no fill.
+*Use when:* the page is editorial / Long Document; CTAs should not shout.
+*Don't confuse with:* C1 Outlined chip (which is bordered).
+
+```html
+<a class="link">Read the case study →</a>
+```
+
+### C4 · Sticky bottom bar
+A horizontal bar pinned to the viewport bottom, holding a CTA + a brief reassurance line.
+*Use when:* the page is long and the CTA needs to be reachable always.
+*Don't confuse with:* anything in the fold; this is a *persistent* element, not a hero CTA.
+
+```html
+<aside class="cta-sticky">
+ <span>Try it free for 14 days.</span>
+ <a class="cta-outline">Start →</a>
+</aside>
+```
+```css
+.cta-sticky { position: fixed; left: 0; right: 0; bottom: 0; padding: var(--space-sm) var(--space-md); background: var(--color-paper); border-top: 1px solid var(--color-rule); display: flex; justify-content: space-between; align-items: center; }
+```
+
+---
+
+## Testimonials / proof
+
+### T1 · Pull-quote with marginalia
+A quote sits in the wide column; the attribution and source link float in the narrow margin column.
+*Use when:* the page already has a marginalia rhythm (Tufte-leaning, editorial).
+*Don't confuse with:* T3 Single huge quote (which is centered and dominates).
+
+```html
+<aside class="proof-margin">
+ <blockquote class="serif-italic">"…"</blockquote>
+ <p class="attribution muted">— Name<br />Role, Company</p>
+</aside>
+```
+
+### T2 · Logo wall (hairline)
+A row of customer logos, monochromatic, separated by hairline rules. No card boxes, no shadows.
+*Use when:* you have recognisable customers and want to surface them quietly.
+*Don't confuse with:* the AI-default 6-logo box grid; this version refuses card boxes.
+
+```html
+<section class="logo-wall">
+ <ul>
+ <li><img src="" /></li>
+ <li><img src="" /></li>
+ <li><img src="" /></li>
+ </ul>
+</section>
+```
+```css
+.logo-wall ul { display: grid; grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr)); gap: 0; }
+.logo-wall li { padding: var(--space-md); border-right: 1px solid var(--color-rule); display: grid; place-items: center; }
+.logo-wall img { filter: grayscale(1); opacity: 0.7; }
+```
+
+### T3 · Single huge quote
+One quote, set big, centered, taking a whole section. No supporting text, no attribution boxes — attribution is a small caps line beneath.
+*Use when:* one quote is so good it earns the room.
+*Don't confuse with:* T1 Margin pull-quote (which is the *side* mate, not the *room*).
+
+```html
+<section class="proof-room">
+ <blockquote class="display-italic">"…"</blockquote>
+ <p class="attribution"><span class="caps">— Name, Company</span></p>
+</section>
+```
+
+### T4 · Numbered stat strip
+A horizontal strip of 3–5 stats (count + qualifier) running across one row. Tabular nums.
+*Use when:* you have multiple complementary metrics that work together.
+*Don't confuse with:* H4 Stat-led hero (which is one focal number, not several).
+
+```html
+<section class="stat-strip tnum">
+ <div><b>2.4M</b><span>users</span></div>
+ <div><b>99.97%</b><span>uptime</span></div>
+ <div><b>14</b><span>regions</span></div>
+</section>
+```
+
+---
+
+## Footers
+
+### Ft1 · Mast-headed
+A wordmark and tagline anchor a single horizontal band. Two or three small links beside, address or licence below.
+*Use when:* the page has heavy content; the footer should be quiet and singular.
+*Don't confuse with:* Ft2 Inline-rule (which is even more reduced).
+
+```html
+<footer class="foot-mast">
+ <p class="wordmark">Studio Name</p>
+ <p class="tagline muted">Designs that don't look generated.</p>
+ <p class="links muted">Imprint · Privacy · Contact</p>
+</footer>
+```
+
+### Ft2 · Inline-rule single line
+A single horizontal line of credits, address, copyright. Hairline rule above. No columns.
+*Use when:* the page is editorial and the footer is afterthought.
+*Don't confuse with:* Ft4 Dense typographic (which packs more in).
+
+```html
+<footer class="foot-line">
+ <p>© 2026 · 137 Marlow Street · MIT licensed</p>
+</footer>
+```
+
+### Ft3 · Index-style category list
+Three or four short columns, each headed by a category in small caps, holding 4–6 links each.
+*Use when:* the page is a hub or a documentation root.
+*Don't confuse with:* Ft4 Dense typographic (which is one big block, not columns).
+
+```html
+<footer class="foot-index">
+ <div><p class="caps">Product</p><ul>…</ul></div>
+ <div><p class="caps">Company</p><ul>…</ul></div>
+ <div><p class="caps">Resources</p><ul>…</ul></div>
+</footer>
+```
+
+### Ft4 · Dense typographic
+One large block of text — credits, references, licence, address — in a small monospace font, fully justified or ragged-right. Editorial colophon energy.
+*Use when:* the brand is editorial and a colophon-style sign-off fits.
+*Don't confuse with:* Ft3 Index (which navigates).
+
+```html
+<footer class="foot-dense mono">
+ <p>Hallmark v0.2.0. Built with The Future, Fraunces, IBM Plex Mono. MIT licensed. Powered by Together AI. 137 Marlow Street, 2026.</p>
+</footer>
+```
+
+---
+
+## Navigation
+
+### N1 · Wordmark + 2 links
+Top-of-page bar: wordmark on the left, two text links on the right ("Pricing" / "Sign in"). No logo image, no menu icon.
+*Use when:* the page has very few destinations.
+*Don't confuse with:* N3 Side-rail (which is vertical).
+
+```html
+<nav class="nav-min">
+ <a class="wordmark">Studio</a>
+ <ul><li><a>Pricing</a></li><li><a>Sign in</a></li></ul>
+</nav>
+```
+
+### N2 · Floating chip
+A small fixed chip in a corner — wordmark + a single action ("Try it"). Doesn't sit in document flow.
+*Use when:* the page is fold-heavy and traditional nav would fight the content.
+*Don't confuse with:* C4 Sticky bottom bar (which is full-width).
+
+```html
+<aside class="nav-chip">
+ <a class="wordmark">Studio</a>
+ <a class="cta-outline">Try →</a>
+</aside>
+```
+```css
+.nav-chip { position: fixed; top: var(--space-md); right: var(--space-md); display: inline-flex; gap: var(--space-md); padding: 0.5rem 0.75rem; background: var(--color-paper); border: 1px solid var(--color-rule); }
+```
+
+### N3 · Side-rail
+A thin vertical strip on the left edge — wordmark rotated, plus 2–3 dot-indicators for sections. Editorial / portfolio energy.
+*Use when:* the page is long and section-numbered.
+*Don't confuse with:* N1 Top wordmark (which is horizontal).
+
+```html
+<nav class="nav-rail">
+ <p class="wordmark vertical">Studio</p>
+ <ul class="dots"><li></li><li></li><li></li></ul>
+</nav>
+```
+```css
+.nav-rail { position: fixed; left: 0; top: 0; bottom: 0; width: 3rem; padding: var(--space-md); writing-mode: vertical-rl; }
+```
+
+### N4 · Hidden behind ⌘K
+No visible nav. The user opens a command palette via `⌘K` to get anywhere. Designed for keyboard-first audiences.
+*Use when:* the page is for technical users who expect this affordance.
+*Don't confuse with:* N2 Floating chip (which is visible always).
+
+```html
+<button class="kbd-hint">⌘ K</button>
+<dialog class="palette">…</dialog>
+```
+
+---
+
+## Picking from this file
+
+When building a section:
+
+1. Identify the section's role (hero / section-head / feature / CTA / testimonial / footer / navigation).
+2. Glance at the archetypes in that category.
+3. Pick the one whose "Use when" fits the brief.
+4. Make sure no two sections in the same page use the same archetype.
+5. If the macrostructure suggests a default (e.g., Bento Grid → F1 Bento), use it; if it doesn't suggest, vary deliberately.
+
+The goal is composed variety — within a page, sections feel different from each other; across pages Hallmark builds, sections feel different from the last.
diff --git a/skill/references/macrostructures.md b/skill/references/macrostructures.md
new file mode 100644
index 0000000..5dffa3a
--- /dev/null
+++ b/skill/references/macrostructures.md
@@ -0,0 +1,519 @@
+# Macrostructures
+
+Twenty-one named landing-page shapes. **Pick one before you write code.** Each is a complete fingerprint — heading placement, body composition, divider language, button voice, image treatment, reveal pattern — bundled as a single named choice. Picking a macrostructure is faster, less error-prone, and *categorically more varied* than choosing six independent axes from `structure.md`.
+
+The Specimen macrostructure (left-margin numbered labels + huge serif + asymmetric spans + typographic CTA) is one of these twenty-one. **It is no longer a default.** Reach for it only when the brief is explicitly editorial, foundry-adjacent, or the user has named it.
+
+## Diversification rule (mandatory)
+
+Before picking, check the target codebase for a `/* Hallmark · macrostructure: <name> · ... */` comment in any existing CSS file. If you find one, **your pick must be a different macrostructure.** No two consecutive Hallmark outputs in the same project share a macrostructure.
+
+When the brief is vague (no theme, no tone), pick from the *first ten* below before reaching for anything in 11–21. The first ten are deliberately the strongest non-Specimen shapes; they cover ~80% of briefs.
+
+---
+
+## 01 · Bento Grid
+
+Modular blocks of varying sizes laid out as an irregular grid. Each block is a feature, a quote, an image, a stat. Visual rhythm comes from size variation, not card uniformity.
+
+- **Heading:** centered display in a fixed-height hero (not full viewport).
+- **Body:** asymmetric grid — 8–15 blocks of mixed spans (1×1, 2×1, 1×2, 2×2).
+- **Divider:** consistent 12–24 px gap; no rules; the grid itself is the rhythm.
+- **Button:** outlined chip on the hero; tile-internal CTAs as typographic links.
+- **Image:** tightly cropped inside individual blocks; never full-bleed.
+- **Reveal:** none, or a subtle one-shot fade on grid-tile entry.
+
+Reach for it when the brief is "many small things to show", a feature page, a SaaS landing, or anywhere users have multiple equally-valid entry points.
+
+Avoid when the message is a single hero idea — Bento spreads attention; one-idea pages need Marquee or Stat-Led.
+
+Reference: Apple in-page sections, Framer feature pages, Tailwind UI templates.
+
+```html
+<header class="hero-fixed">…</header>
+<section class="bento">
+ <article class="cell span-2x2">…</article> <!-- hero feature -->
+ <article class="cell span-1x1">…</article>
+ <article class="cell span-2x1">…</article> <!-- wide stat -->
+ <article class="cell span-1x2">…</article> <!-- tall image -->
+ <article class="cell span-1x1">…</article>
+ <article class="cell span-1x1">…</article>
+</section>
+```
+
+---
+
+## 02 · Long Document
+
+Reads like a memo, a letter, or a journal entry. No marketing structure. Continuous prose with inline section heads. The page is *literature* about the product.
+
+- **Heading:** inline with body — section heads emerge from the paragraph flow as small caps or bold short phrases.
+- **Body:** single column, generous line-height (1.65+), measure 60–65ch.
+- **Divider:** negative space; the gap is the divider; occasionally a centered ornament for emphasis.
+- **Button:** typographic link inside a paragraph, not a separate block.
+- **Image:** inline, sized to text measure; never full-bleed.
+- **Reveal:** none. The page is just *there*.
+
+Reach for it for case studies, founder posts, mission pages, products whose sale is *philosophical*. The brief is "tell a story", not "list features".
+
+Avoid when there's a single decisive action to take — Long Document hides CTAs, which is wrong for transactional pages.
+
+Reference: Frank Chimero's site, destroytoday.com, long-form Substack essays in product disguise.
+
+```html
+<article class="prose">
+ <p class="lede">…</p>
+ <p>…</p>
+ <h2 class="inline">A small heading.</h2>
+ <p>…</p>
+ <blockquote>…</blockquote>
+ <p>… <a href="">read more →</a> …</p>
+</article>
+```
+
+---
+
+## 03 · Marquee Hero
+
+The hero IS the page above the fold. A single bold statement or visual fills the viewport. No subhead, no CTA in fold. Below the fold the page becomes something else (a list, a grid, prose).
+
+- **Heading:** display fills the fold — 8–14 vw type, hugging the viewport edges.
+- **Body:** below-fold becomes a list of work or a single content block; the hero doesn't continue.
+- **Divider:** a thick rule between hero and below-fold, OR a hard colour change.
+- **Button:** none in fold; first CTA arrives below.
+- **Image:** none in fold (typography is the visual), OR a single full-bleed photograph as the fold *background*.
+- **Reveal:** the fold is static; below-fold may sweep in horizontally.
+
+Reach for it when the brand or person *is* the message — designer/director portfolios, indie products with a single declarative voice, any "this is who we are" page.
+
+Avoid for products whose value requires explanation in seconds. Marquee makes the user scroll before they understand.
+
+Reference: 14islands.com, destroytoday.com, many design studio homepages.
+
+```html
+<section class="marquee">
+ <h1 class="display-xxl">A statement.</h1>
+</section>
+<hr class="rule-thick" />
+<section class="below-fold">…</section>
+```
+
+---
+
+## 04 · Stat-Led
+
+The hero is a giant number — a metric, a count, a percentage. Everything that follows supports or qualifies it. Data is the narrative.
+
+- **Heading:** numeric display (8–12 rem), tabular figures, small qualifier line below.
+- **Body:** sections each anchored by a supporting stat or chart.
+- **Divider:** hairline rules between stat blocks; tabular-nums everywhere.
+- **Button:** outlined chip aligned beneath the qualifier.
+- **Image:** charts and small data-viz; no photography.
+- **Reveal:** number-tick on the hero figure — counter from 0 to target over ~500 ms.
+
+Reach for it when the brief is "we have proof in numbers" — enterprise/B2B, fundraising platforms, climate or impact pages.
+
+Avoid for products without a defensible single metric. A fake big number is worse than no number.
+
+Reference: Ahrefs, Stripe Sessions stat blocks, climate-impact dashboards, venture firm portfolio pages.
+
+```html
+<section class="stat-hero">
+ <div class="figure tnum">99.97<span class="unit">%</span></div>
+ <p class="qualifier">uptime across 2026, measured externally.</p>
+ <a class="cta-outline">Read the report →</a>
+</section>
+<section class="supporting-stats">…</section>
+```
+
+---
+
+## 05 · Workbench
+
+Product screenshots in frames are the primary content. The page is a guided tour of the app in use. Less marketing copy, more "here's what you do with it."
+
+- **Heading:** small, functional — workbench pages don't shout.
+- **Body:** sequence of screenshot blocks, each with a short caption and an inline annotation arrow.
+- **Divider:** the screenshot frame *is* the divider; sections separate by gap and frame.
+- **Button:** sticky-bottom CTA bar after the third screenshot ("Try it →"), once context is built.
+- **Image:** central — browser/device frames around real product captures, with annotation arrows.
+- **Reveal:** type-unmask on captions; screenshots load instantly.
+
+Reach for it for SaaS, developer tools, IDE extensions — anywhere seeing the product in motion is the sale.
+
+Avoid when the product is conceptual or services-led. Workbench needs a UI to show.
+
+Reference: Linear.app, Vercel, Raycast, Arc Browser.
+
+```html
+<header class="lite">…</header>
+<section class="screenshot-frame">
+ <figure><img src="step-1.png" /><figcaption>Open a project.</figcaption></figure>
+</section>
+<section class="screenshot-frame">…</section>
+<aside class="sticky-cta">Try it free →</aside>
+```
+
+---
+
+## 06 · Conversational FAQ
+
+Bold questions, brief answers. The page reads like an honest interview with the product. Often each Q/A is a collapsible accordion.
+
+- **Heading:** each section *is* a question — a short, direct phrase ending in `?`.
+- **Body:** answer in 2–4 short paragraphs immediately below the question.
+- **Divider:** thin rule between Q/A pairs, or zero rule and a paper-colour swap.
+- **Button:** typographic link inside answers ("Read the full policy →"); one outlined CTA at the foot.
+- **Image:** sparse — maybe one diagram per long answer; mostly text.
+- **Reveal:** none on load; accordion expand uses 200 ms `--ease-out` on `grid-template-rows: 0fr → 1fr`.
+
+Reach for it near pricing, for products that meet skepticism, for educational/regulated industries.
+
+Avoid as the *primary* page. FAQ usually pairs with another macrostructure that opens the page.
+
+Reference: many SaaS pricing pages, Casper, Substack help pages.
+
+```html
+<section class="faq">
+ <details>
+ <summary><h2>How long does setup take?</h2></summary>
+ <div class="answer">…</div>
+ </details>
+ <details>…</details>
+</section>
+```
+
+---
+
+## 07 · Manifesto
+
+Polemical large type. Declaration energy. The page tells the reader what to believe before it tells them what to buy. Often political-poster aesthetic.
+
+- **Heading:** all-caps display tilted slightly (`-2°` to `-4°`), or stacked colour-block highlights on the verb.
+- **Body:** short paragraphs each holding one assertion, large enough to read across the room.
+- **Divider:** bleed-colour blocks between sections; no hairlines.
+- **Button:** oversized solid block, accent colour, set far below the fold.
+- **Image:** none, or a single high-contrast B&W photograph used as a section bleed.
+- **Reveal:** horizontal sweep on section entry.
+
+Reach for it for brand repositioning announcements, mission-led indie products, design-studio beliefs pages.
+
+Avoid for transactional pages. Manifesto sells *agreement*, not action.
+
+Reference: Linear's positioning pages, agency rebrand sites, political campaign landing pages.
+
+```html
+<section class="manifesto bleed-ink">
+ <h1 class="caps display-xxl">WE BELIEVE <em class="block-accent">DESIGN</em> IS SLOW.</h1>
+</section>
+<section class="bleed-paper">
+ <p class="claim">It costs less than the rework you'll do without it.</p>
+</section>
+```
+
+---
+
+## 08 · Photographic
+
+A single huge image dominates each fold. Text is small annotation, not headline. The design says *look* before it says *read*.
+
+- **Heading:** small caption near a corner of the image; never centered display.
+- **Body:** full-bleed image bands alternating with narrow text bands.
+- **Divider:** the image edge IS the divider; no rules.
+- **Button:** typographic link tucked under the caption.
+- **Image:** the whole point — full-bleed, edge to edge, often a single photo per fold.
+- **Reveal:** no spatial motion; let the photographs do the work.
+
+Reach for it for fashion, hospitality, photography portfolios, lifestyle e-commerce, any brand whose product is a *feeling*.
+
+Avoid without real photography. AI-generated stock undoes the macrostructure.
+
+Reference: Aimé Leon Dore, Mr Porter editorial, Stüssy lookbooks.
+
+```html
+<section class="photo-fold">
+ <img class="bleed" src="hero.jpg" />
+ <p class="caption">Spring, 2026.</p>
+</section>
+<section class="text-fold">
+ <p class="lede">…</p>
+</section>
+<section class="photo-fold">…</section>
+```
+
+---
+
+## 09 · Quote-Led
+
+The hero is a pull-quote with attribution. The headline is borrowed credibility, not the brand's voice. The page leads with social proof.
+
+- **Heading:** italic display setting a customer's quote (36–60 px), with attribution below in small caps.
+- **Body:** continues with additional testimonials, case studies, or a quiet feature list.
+- **Divider:** centered quote-mark glyph or an em-rule between testimonials.
+- **Button:** typographic link beneath the attribution ("Read the full case study →").
+- **Image:** small avatar or company logo by the attribution; otherwise none.
+- **Reveal:** none in fold; below-fold may stagger.
+
+Reach for it for B2B products with strong customer voices, agency case-study pages, fundraising sites, anywhere "people like me use this" is the unlock.
+
+Avoid for new products without real testimonials. Fake quotes destroy trust on inspection.
+
+Reference: many B2B SaaS landings, agency homepages, university development pages.
+
+```html
+<section class="quote-hero">
+ <blockquote class="display-italic">"…"</blockquote>
+ <p class="attribution">— Name, Title, Company</p>
+ <a class="link">Read the case →</a>
+</section>
+<section class="more-quotes">…</section>
+```
+
+---
+
+## 10 · Specimen *(no longer the default)*
+
+Numbered left-margin labels, huge serif display, asymmetric column spans, hairline rules, typographic-only CTA, generous whitespace. Editorial / type-foundry energy.
+
+- **Heading:** left-margin number + label (`01 — HELLO.`) beside a large serif phrase.
+- **Body:** asymmetric spans — narrow label column / wide content column.
+- **Divider:** hairline rules between sections.
+- **Button:** typographic link with arrow ("Open your studio →"); no box, no fill.
+- **Image:** none, or a hand-drawn SVG accent in the wide left margin.
+- **Reveal:** fade-up stagger on first load.
+
+Reach for it ONLY when the brief is explicitly editorial, type-foundry, journal, or "specimen sheet". Otherwise pick something else.
+
+**Banned as a default.** If the brief is vague and you've defaulted here, restart.
+
+Reference: type foundry homepages (Klim, Pangram Pangram, Production Type), some editorial portfolios.
+
+```html
+<header class="specimen">
+ <p class="num-label">01 — HELLO.</p>
+ <h1 class="serif-xxl">A quiet <em>instrument.</em></h1>
+ <p class="lede narrow">…</p>
+ <a class="link">Open your studio →</a>
+</header>
+```
+
+---
+
+## 11 · Catalogue
+
+Uniform grid of variations of the same thing — typefaces, colour palettes, product SKUs. The page is a visual index of inventory.
+
+- **Heading:** brand mark + tagline only; no big display.
+- **Body:** grid of identical-sized cards (3–5 per row), each one variant of the core product.
+- **Divider:** hairline rules between rows; sometimes a category label band.
+- **Button:** card-internal link to detail page; no global CTA.
+- **Image:** specimen thumbnail per card, or a swatch.
+- **Reveal:** none.
+
+Reach for it for foundries, palette generators, font shops, colour systems, capsule collections.
+
+Avoid for narrative brands. Catalogue treats every item as equal — wrong for products with hierarchy.
+
+Reference: Klim Type Foundry, Pangram Pangram, Coolors palettes.
+
+---
+
+## 12 · Letter
+
+First-person, written, intimate. Opens with a greeting ("Dear friend,"). No buttons in the fold. Reads as a personal note from the founder.
+
+- **Heading:** salutation in serif italic ("Dear reader,"), 1.5–2× body size.
+- **Body:** prose, single column, narrow measure (50ch), as if typed.
+- **Divider:** paragraph spacing only, occasional `* * *` separator.
+- **Button:** sign-off link at the foot ("p.s. join us if you'd like →").
+- **Image:** maybe one signature scan, or a quiet inline photograph.
+- **Reveal:** none.
+
+Reach for it for personal brands, indie founder announcements, sabbatical or pivot pages, donation appeals.
+
+Avoid for transactional commerce. Letter is intimate; commerce is functional.
+
+Reference: Frank Chimero's site, founder farewell posts, indie newsletter front pages.
+
+---
+
+## 13 · Index-First
+
+The page IS a list of links. No hero image, no narrative flow. Pure navigation as design.
+
+- **Heading:** one short paragraph at the top introducing the index, no display type.
+- **Body:** vertical list of categorised links; sometimes a sidebar of filters.
+- **Divider:** hairline rules between rows; or zero rules with paper-colour bands.
+- **Button:** the links themselves are the buttons.
+- **Image:** none, or tiny favicons by each entry.
+- **Reveal:** none.
+
+Reach for it for documentation hubs, knowledge bases, archive front pages, design system entries, link-in-bio pages with substance.
+
+Avoid for marketing pages. Index-First is for browsing audiences; selling needs structure.
+
+Reference: Are.na's homepage feel, archive sites, documentation indices.
+
+---
+
+## 14 · Narrative Workflow
+
+Numbered stages tell the story of how the user uses the product over time. Each section is a phase (1.0 → 2.0 → 3.0 → 4.0). The page is a process timeline.
+
+- **Heading:** large numbered stage labels (`1.0 INTAKE`, `2.0 PLAN`).
+- **Body:** each stage has a short explanation and a small product visual.
+- **Divider:** thick numbered rule between stages.
+- **Button:** stage-internal links; one global "Start at stage 1 →" at the foot.
+- **Image:** small product capture per stage, often annotated.
+- **Reveal:** sweep horizontal as stages enter the viewport.
+
+Reach for it for products with explicit workflows — project management, design-to-dev pipelines, writing tools.
+
+Avoid for tools that work in *one* moment. Narrative Workflow needs a real sequence.
+
+Reference: Linear's how-it-works pages, some Figma marketing pages.
+
+---
+
+## 15 · Split Studio
+
+Diptych. Every major content block divides the screen — text on one side, proof on the other. The pairing alternates direction down the page.
+
+- **Heading:** half-screen wide; the other half holds a screenshot or a quote.
+- **Body:** alternating left-text/right-image and right-text/left-image modules.
+- **Divider:** a clear gutter between halves; no rules.
+- **Button:** outlined chip below the text half.
+- **Image:** anchored to the opposite half from the text in each row.
+- **Reveal:** opposite halves cross-fade in slightly staggered.
+
+Reach for it for SaaS feature pages, dev tools that pair explanation with code, anything where every claim wants a visual proof.
+
+Avoid for narrative or photographic brands. Split halves the attention; some pages need single focus.
+
+Reference: Vercel feature pages, Stripe Sessions program pages, many dev-tool homepages.
+
+---
+
+## 16 · Feature Stack
+
+Sticky left pane (label / description) + scroll-synced right pane (screenshots cycling through related details). Cinematic pacing.
+
+- **Heading:** held inside the sticky pane; persists while content cycles beside it.
+- **Body:** two columns — left sticky, right scrolling; the right pane plays through 3–6 detail screens per section.
+- **Divider:** section bands; the sticky pane re-anchors per section.
+- **Button:** in the sticky pane, set when the user reaches the section's detail count.
+- **Image:** the scrolling-right column is mostly imagery.
+- **Reveal:** none of the spatial-fade kind; the sticky/scroll IS the motion.
+
+Reach for it for premium products, complex feature stories, anything where you want to control pacing as the user scrolls.
+
+Avoid on mobile-first audiences without strong fallback. Sticky+scroll-sync is rough on small screens.
+
+Reference: Apple product pages, some Stripe Sessions pages, Read.cv onboarding.
+
+---
+
+## 17 · Type Specimen
+
+The typeface IS the design. Foundry homepage or design-system marketing where a custom typeface is the brand's proof.
+
+- **Heading:** the typeface set at multiple sizes, demonstrating what it does.
+- **Body:** progressive demonstration — display size, body size, italic, language coverage, OpenType features.
+- **Divider:** centred caption labels between specimens.
+- **Button:** outlined "Buy" or "Use it" at the foot.
+- **Image:** none — typography is the imagery.
+- **Reveal:** type-unmask on first paint of each specimen block.
+
+Reach for it for type foundries, design systems where a custom face is the differentiator, font product pages.
+
+Avoid when the brand uses an off-the-shelf face. Type Specimen needs something distinctive to celebrate.
+
+Reference: Klim Type Foundry, Pangram Pangram, Geist Pixel announcement pages.
+
+---
+
+## 18 · Portfolio Grid
+
+Filterable cards of projects. Studio or designer homepages where the work is the product.
+
+- **Heading:** short tagline above the grid; no display.
+- **Body:** responsive grid of project cards, all same size or with subtle size variation.
+- **Divider:** filter bar above the grid; no internal rules.
+- **Button:** card-internal "View case study"; no global CTA.
+- **Image:** thumbnail per card.
+- **Reveal:** card-fade on filter change.
+
+Reach for it for design studios, agencies, photographer portfolios, any creative business where work is the pitch.
+
+Avoid for products. Portfolio Grid is service-business shape.
+
+Reference: Pentagram, 14islands, Locomotive, Bureau Borsche.
+
+---
+
+## 19 · Map / Diagram
+
+A single large spatial diagram organises the page — flowchart, floor plan, network graph, system map. Information is laid out *spatially*, not linearly.
+
+- **Heading:** a small orientation phrase above or beside the map.
+- **Body:** the map itself; nodes and edges; a legend somewhere.
+- **Divider:** the diagram has no internal sections — it's one composition.
+- **Button:** node-internal links; one outlined CTA below the map.
+- **Image:** the map IS the image; SVG with interactive hovers.
+- **Reveal:** node-by-node ink-on as the user enters viewport (cap to 5 nodes).
+
+Reach for it for system overviews, ecosystem maps, process diagrams, organisation charts.
+
+Avoid as a substitute for narrative. Some stories shouldn't be read spatially.
+
+Reference: process visualisation sites, ecosystem maps, knowledge-graph products.
+
+---
+
+## 20 · Ecosystem Index
+
+Multiple discovery surfaces — featured / latest / by category / by people. The platform's value is emergence and browsing, not declaration.
+
+- **Heading:** brief positioning paragraph; no display.
+- **Body:** several horizontal rails or grids — each surfacing a different cut of the platform's content.
+- **Divider:** rail-titled bands.
+- **Button:** "See more →" at each rail's edge; rarely a global CTA.
+- **Image:** thumbnails everywhere; the page is dense imagery.
+- **Reveal:** none.
+
+Reach for it for community platforms, content marketplaces, design-asset stores, any UGC/curated catalogue front page.
+
+Avoid for single-product pages. Ecosystem needs multiple things to surface.
+
+Reference: Are.na, Figma Community, Behance.
+
+---
+
+## 21 · Component Playground
+
+Interactive code-and-preview blocks are the page's primary content. Each block previews a thing and shows how to copy-paste it.
+
+- **Heading:** category labels (`Buttons`, `Forms`, `Cards`, `Layouts`).
+- **Body:** alternating preview-and-code blocks, often with a tab to switch frameworks.
+- **Divider:** category bands; horizontal rules between examples.
+- **Button:** "Copy" button on every code block (silent success).
+- **Image:** none — the previews ARE the imagery.
+- **Reveal:** none.
+
+Reach for it for design systems, component libraries, code-snippet sites, framework documentation.
+
+Avoid for marketing pages. Playground is utility, not pitch.
+
+Reference: shadcn/ui, Tailwind UI, Once UI, MUI demos, Framer Motion examples.
+
+---
+
+## How to pick
+
+1. **Read the brief.** Note any words that strongly signal one macrostructure ("data heavy", "tell a story", "a list of links", "many small features", "personal note").
+2. **Check the codebase** for an existing `/* Hallmark · macrostructure: <name> · ... */` stamp. If found, exclude that name from your choices.
+3. **Match brief energy to a macrostructure** using the "Reach for it" lines. Most briefs match 2–4 of these patterns; pick the one that's most categorically distant from any past output for this user.
+4. **State your pick** in plain text *before* writing code: "Macrostructure: Bento Grid." Then write the code, opening the CSS with the required stamp.
+5. If genuinely torn, offer the user three choices from *different categories* (e.g. Bento + Long Document + Manifesto) and let them pick.
+
+The goal is not novelty for its own sake. The goal is that two pages Hallmark builds for two different briefs *look like different sites, not different colour-swaps of the same template*.
diff --git a/skill/references/structure.md b/skill/references/structure.md
index 5e4f423..73f576b 100644
--- a/skill/references/structure.md
+++ b/skill/references/structure.md
@@ -2,7 +2,9 @@
Most AI-generated UIs are visually distinct but structurally identical: hero → three features → CTA → footer. Same heading positions, same column counts, same component vocabulary. **Structural sameness is the AI fingerprint, not visual sameness.** Hallmark's job is to break it.
-This file catalogues the axes of structural variety. Pick one option from each axis to form a *structural fingerprint*. Two pages should never share the same fingerprint.
+This file catalogues the **primitive axes** of structural variety. For most builds you should NOT compose a fingerprint axis-by-axis from this file — instead pick a named whole-page shape from [`macrostructures.md`](macrostructures.md), which is faster and prevents default-attractor sameness. Use this file when you need to deviate from a macrostructure's defaults on one or two axes, or when you're auditing an existing page and need vocabulary for what you see.
+
+The axes below are still the building blocks. Pick one option from each to form a *structural fingerprint*. Two pages should never share the same fingerprint.
## The six axes
@@ -87,22 +89,24 @@ Two rules govern choices:
## Theme-suggested fingerprints
-Each Hallmark theme has a default structural fingerprint. Use them as starting points, deviate when the brief demands.
+Each Hallmark theme has a default structural fingerprint. Use them as starting points only when the brief specifies a theme. **For most builds, pick a macrostructure from [`macrostructures.md`](macrostructures.md) instead** — themes describe *visual surface*, macrostructures describe *page shape*; the latter drives variety more.
+
+The table below is alphabetical by theme to neutralise any "first row = default" attractor. No theme is the default.
| Theme | Heading | Body | Divider | Button | Image | Reveal |
| --- | --- | --- | --- | --- | --- | --- |
-| Specimen | Left-margin | Asymmetric spans | Hairline | Outlined | None | Fade-up |
-| Midnight | Numbered display | Single column | Hairline | Typographic-only | None | Typewriter |
+| Almanac | Sticky | Three-column equal | Hairline | Outlined | Inline | Number-tick |
+| Atelier | Centered | Single column | Negative space | Typographic-only | Tightly cropped | Type-unmask |
| Brutal | Overlapping image | Full-bleed reset | Bleed-colour | Oversized solid | Full-bleed | Horizontal sweep |
| Garden | Hanging | Marginalia | Negative space | Unstyled link | Margin-aligned | None |
-| Atelier | Centered | Single column | Negative space | Typographic-only | Tightly cropped | Type-unmask |
-| Newsprint | Bottom-aligned | Multi-column justified | Double rule | Outlined | Inline | None |
-| Terminal | Inline (with `>` prompt) | Single column | Negative space | Typographic-only `[ go ]` | None | Typewriter |
+| Linen | Hanging | Two-column asymmetric | Negative space | Unstyled link | Margin-aligned | Fade-up |
| Manifesto | Overlapping image | Full-bleed reset | Bleed-colour | Oversized solid | Full-bleed | Horizontal sweep |
+| Midnight | Numbered display | Single column | Hairline | Typographic-only | None | Typewriter |
+| Newsprint | Bottom-aligned | Multi-column justified | Double rule | Outlined | Inline | None |
| Salon | Centered | Single column narrow | Ornament (fleuron) | Outlined | Tightly cropped | None |
-| Linen | Hanging | Two-column asymmetric | Negative space | Unstyled link | Margin-aligned | Fade-up |
-| Almanac | Sticky | Three-column equal | Hairline | Outlined | Inline | Number-tick |
+| Specimen | Left-margin | Asymmetric spans | Hairline | Outlined | None | Fade-up |
| Sport | Numbered display | Asymmetric spans | Bleed-colour | Oversized solid | Full-bleed | Horizontal sweep |
+| Terminal | Inline (with `>` prompt) | Single column | Negative space | Typographic-only `[ go ]` | None | Typewriter |
## Anti-patterns of structural sameness
@@ -116,10 +120,12 @@ Reject these structural fingerprints. They are the AI-template fingerprint.
## When you don't know
-If the brief doesn't suggest a fingerprint and the user hasn't picked a theme, ask:
+If the brief doesn't suggest a fingerprint and the user hasn't picked a theme, **do not default**. Offer the user three named macrostructures from *categorically different* groups, and let them pick. For example:
-> One word for the *feeling* of this page — editorial, brutalist, soft, technical, luxury, austere, playful?
+- **Bento Grid** — modular, feature-led, many entry points.
+- **Long Document** — prose-led, one continuous narrative, no marketing structure.
+- **Manifesto** — declarative large type, one belief per fold, polemical.
-Their answer maps to a theme; the theme maps to a fingerprint. Proceed.
+Three concrete page-shapes beat seven abstract tones. If the user shrugs and says "you pick", roll a die: pick whichever of the three is most *categorically distant* from any previous Hallmark output for this user (read the existing CSS for a `/* Hallmark · macrostructure: ... */` stamp and avoid that family).
-If they answer "modern", "clean", or "professional", say so isn't a feeling and ask again.
+If the user answers a vague tone word ("modern", "clean", "professional"), that is not a feeling. Re-ask with the three concrete macrostructures above.