## 1. Project Overview & Quickstart (Nutlope/hallmark) ## File: README.md # Hallmark **A design skill for Claude Code, Cursor, and Codex that refuses to look AI-generated.** [Live demo →](https://www.usehallmark.com)  ·  twenty-one themes  ·  four verbs  ·  press `T` to cycle. Made by Together AI. Hallmark picks a macrostructure for the brief, dresses it in one of twenty-one themes, runs fifty-seven slop-test gates plus a pre-emit self-critique, and refuses the on-distribution defaults every LLM was trained into. Two pages by Hallmark for two different briefs feel like different sites, not colour-swaps of the same template. --- ## Four verbs | Verb | What it does | | --- | --- | | *(default)* | Build new UI. Picks a macrostructure, applies the rule-set, runs the slop test before handing back. | | `hallmark audit ` | Score existing code against the anti-patterns. Punch list, no edits. | | `hallmark redesign ` | Throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint. | | `hallmark study ` | Extract the **DNA** from a design you admire: macrostructure, type-pairing, colour anchor. Refuses pixel-clones and paid templates. Optionally emits a portable `design.md` for handoff to other AI tools. | --- ## Different briefs, different shapes Each generated from a different brief. The skill picks the theme, structure, and craft to fit each one, not from a template. | [](https://www.usehallmark.com/examples/hum-07/) | [](https://www.usehallmark.com/examples/cobalt-01/) | [](https://www.usehallmark.com/examples/carnival-01/) | [](https://www.usehallmark.com/examples/lumen-01/) | | --- | --- | --- | --- | | **Bubble**Sourdough app · Hum | **Distil**Extraction API · Cobalt | **Cold Snap**Record label · Carnival | **Cinder**AI tool · Lumen | | [](https://www.usehallmark.com/examples/custom-03/) | [](https://www.usehallmark.com/examples/garden-01/) | [](https://www.usehallmark.com/examples/riso-01/) | [](https://www.usehallmark.com/examples/press-01/) | | **Ferns & Fathom**Tea menu · Custom | **Hollowback Apiary**Honey farm · Garden | **Off-Register**Print fair · Riso | **Press Quaternary**Type studio · Custom | | [](https://www.usehallmark.com/examples/tally/) | [](https://www.usehallmark.com/examples/wayfare/) | [](https://www.usehallmark.com/examples/najm/) | [](https://www.usehallmark.com/examples/hyperlane/) | | **Tally**SaaS · modern-minimal | **Wayfare**Travel · atmospheric | **NAJM**Fashion brand | **Hyperlane**Dev infrastructure | Each page is self-contained HTML + CSS, stamped with its macrostructure in the CSS comment. Browse the full set at [usehallmark.com](https://www.usehallmark.com) or under [`site/_tests/`](site/_tests/). --- ## Custom NEW When a brief carries creative intent that no catalog theme fits, Hallmark switches to **Custom** and designs the page from scratch: a made-to-measure palette, type, and layout. Same 57 slop-test gates, no template underneath. | [](https://www.usehallmark.com/examples/custom-02/) | [](https://www.usehallmark.com/examples/custom-04/) | | --- | --- | | **The Cascadia Nightjar**Sleeper-train ticket · Custom | **The Mend Assembly**Repair-café broadsheet · Custom | It stays a quiet branch; vanilla briefs never see it. The protocol lives in [`custom-theme.md`](skills/hallmark/references/custom-theme.md). --- ## Install ``` npx skills add nutlope/hallmark ``` Re-run any time to update. Or copy [`SKILL.md`](skills/hallmark/SKILL.md) + [`references/`](skills/hallmark/references/) into: - **Claude Code**: `~/.claude/skills/hallmark/` - **Cursor**: `.cursor/rules/hallmark.mdc` (body of `SKILL.md`, no frontmatter) - **Codex**: `~/.codex/skills/hallmark/` (personal) or `.codex/skills/hallmark/` (project-scoped) The rule-set lives in [`SKILL.md`](skills/hallmark/SKILL.md) and [`references/`](skills/hallmark/references/). Worked examples in [`docs/recipes.md`](docs/recipes.md) and [`docs/study-examples.md`](docs/study-examples.md). --- ## Licence MIT. Use it, fork it, ship it. --- ## File: docs/recipes.md # Recipes — copy-paste prompts that ship Hallmark output Eight worked briefs you can paste into Claude Code, Cursor, or Codex with the Hallmark skill installed. Each shows the prompt verbatim, the audience/use/tone the skill inferred, the macrostructure + theme + enrichment it picked, and a one-paragraph excerpt of the output. Live page links are included where the test exists in [`site/_tests/`](../../site/_tests/). The first recipe is the **canonical try-it prompt** — paste it into a fresh project to verify the skill is installed and discover the flow before reading anything else. --- ## 00 · Try it · Coffeebox **Prompt** (copy/paste verbatim): > *"Build me a landing page for Coffeebox — a small-batch coffee subscription. Roast on Sunday, ship on Monday, drink Tuesday. Audience: people who already buy good coffee and want fewer trips to the shop. Tone: warm, hand-set, editorial — like a small café's chalkboard."* **Inferred trio:** explicit (audience: serious-coffee buyers · use: subscribe · tone: editorial-warm). **Picks:** Long Document · **Linen** (warm-paper roman-serif) · Tier-B hand-built SVG (a small coffee-bean icon, optional). **Excerpt of the output:** > *"Coffeebox · est. 2026 · n.º 12.* The first roast leaves the drum at 6:14 a.m. Sunday. By Monday morning it's in a paper bag in your post box. By Tuesday the kitchen smells like a café. Subscribe, skip a week, change the roast — all from the email. We bake what we baked yesterday. We ship what shipped well. We answer the email ourselves." **Why this is the canonical try-it:** the brief has explicit context (no design-context-gate friction), an editorial tone (different from any AI-default landing page), and a domain (coffee subscription) that has zero overlap with SaaS/dev-tool clichés. If Hallmark produces *Linen-with-italic-Cormorant-and-warm-paper* for this prompt, the skill is wired correctly. --- ## 01 · Tide · Indie podcast **Prompt:** > *"Design a landing page for Tide — an indie podcast about long-form interviews with small-studio designers. Just go ahead, pick the rest yourself."* **Inferred trio** (the user opted out): audience = designers, design-curious listeners · use = listen + subscribe · tone = quiet editorial. **Picks:** Letter · **Salon** (warm cream paper, IBM Plex Mono masthead, Cormorant Garamond body, warm-amber caret) · no enrichment (typography only). **Excerpt:** > *"Dear listener, Tide is a podcast about how small studios actually work. The bookings, the unsent invoices, the day a senior designer leaves and you sit in the office not knowing what to say to the four people who stayed."* The hero is the salutation. Below: three paragraphs of host-voice, a sign-off, then a single row of "listen where you listen" links — Apple, Spotify, Pocket Casts, Overcast, RSS. No mockups. No demo. The voice carries the brand. **Live:** [`_tests/01-tide-podcast/`](../../site/_tests/01-tide-podcast/index.html) --- ## 02 · Streampipe · Open-source CLI **Prompt:** > *"Build me a landing page for Streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin. Filter, transform, route. Composes with anything that emits lines. Audience: developers. Use: install + read docs. Tone: technical. Use the Terminal theme."* **Inferred trio:** explicit. **Theme requested.** **Picks:** Long Document · **Terminal** (dark phosphor-green, mono everywhere) · Tier-A inline CSS-art terminal blocks (no Lottie, no real video, no sticky pin — embedded inline in the prose). **Excerpt:** > *"$ streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin."* Then a paragraph of prose explaining what it does, an inline `` showing `tail -f access.log | streampipe parse --format nginx --filter 'status >= 500' --out json` with three sample JSON output lines, then a second paragraph (Rust, 1.2 MB binary, no daemon, no buffer). Below: install section (three snippets — brew · cargo · curl), three numbered notes on how it works, a six-row flag table. Pure CSS, no scripts. **Live:** [`_tests/02-streampipe-cli/`](../../site/_tests/02-streampipe-cli/index.html) --- ## 03 · Maple Street Bread · Artisan bakery **Prompt:** > *"Build a landing page for Maple Street Bread — a small artisan bakery in Lisbon. Sourdough, slow, by hand. We open at seven, thirty loaves, gone by noon, no online orders. Audience: locals. Use: see what we bake, find us. Tone: warm, hand-set."* **Inferred trio:** explicit. **Picks:** Catalogue · **Almanac** (warm parchment paper, IM Fell roman-serif display, warm-amber accent) · Tier-A hand-built inline-SVG bread silhouettes (one per item, 96 px, no animation). **Excerpt:** > Plate-banner masthead: *"Maple Street Bread · Lisbon · est. 2026 · n.º 47 · sourdough by hand."* Then a centred section: *"Today's bake — Saturday, 6:14 a.m., eight breads, gone by noon."* Below: a 2-column catalogue grid of eight breads (Country sourdough · Baguette tradition · Focaccia rosemary · Boule miche · Rye dark · Brioche feuilletée · Walnut levain · Bola d'óleo). Each row carries a 96-px bread silhouette, the name in IM Fell, a one-line description, and a price (or "sold out"). Visit and hours in a centred almanac panel at the bottom. No CTA — the brief is "see what's available + visit." **Live:** [`_tests/03-maple-bakery/`](../../site/_tests/03-maple-bakery/index.html) --- ## 04 · Meridian · Studio manifesto **Prompt:** > *"A studio manifesto for Meridian — a small environmental-products design practice in Lisbon. Declarative, no flashy stuff."* **Inferred trio** (partial): audience = practice peers + clients · use = read it + sign on or move on · tone = declarative editorial. **Picks:** Quote-Led · **Brutal** (near-black paper, Druk-style condensed display, single yellow strike accent) · no enrichment. **Excerpt:** > A single twenty-word pull-quote: *"We make products that don't outlive their use"* — with a yellow strike-through behind "outlive." Attribution beneath: *"— The studio · the position we open with · this is the page."* Below the bleed-yellow rule, four numbered principles (Fewer things, made well · Material is the brief · Repair before replace · Slow is the deliverable), each with one paragraph of body copy. Final § Working rules — five terse operational statements (the shop runs on a four-day week · we answer the email ourselves · etc.). No CTA, no testimonials, no roadmap. **Live:** [`_tests/04-meridian-manifesto/`](../../site/_tests/04-meridian-manifesto/index.html) --- ## 05 · Tracejam · SaaS observability **Prompt:** > *"Build me a landing page for Tracejam — a tracing/observability tool for distributed systems. Audience: SREs and platform engineers. Use case: try it / contact sales. Tone: technical."* **Inferred trio:** explicit. **Picks:** Workbench · **Midnight** (dark cool paper, Geist Mono display, phosphor-cyan accent) · Tier-A pure-CSS sticky trace panel (3-state, swaps on scroll — no clipped browser frame). **Excerpt:** > *"Tracejam · v0.4 · For SREs & platform engineers. Distributed tracing that explains itself."* Hero left-aligned with two CTAs (Try it free / Talk to sales). On the right, a sample trace card with five spans — auth.verify, pricing.quote (red, regressed), rates.fx (orange, warning), ledger.write — bars rendered as flex children. Below: a sticky-walkthrough section with three steps (open · find · read), each with a one-paragraph body and a small `$ tracejam ...` command. The right column carries a pinned trace panel with a "REGRESSED" chip and a "WHY" explainer in plain text. Eight integrations strip, three-tier pricing, single-line colophon. **Live:** [`_tests/05-tracejam-saas/`](../../site/_tests/05-tracejam-saas/index.html) --- ## 06 · Anya · Personal one-pager **Prompt:** > *"Personal site for Anya — software architect in Lisbon. Don't ask, just figure it out."* **Inferred trio** (the user opted out): audience = engineering hiring managers · use = read who I am, see my work · tone = austere, italic-editorial. **Picks:** Index-First · **Plain** (pure-white paper #ffffff, Inter Tight display-heavy, deep ink-blue accent) · no enrichment. **Excerpt:** > Sticky left sidebar with a numbered TOC: *00 Index · 01 Now · 02 Years · 03 Writing · 04 Reach.* Each section in the right column starts with its own num + label and a clamp-set H2. *"00 · Index"* opens with *"A small, scannable index of who I am and what I do."* — followed by a two-paragraph bio. *"01 · Now"* covers consulting two engagements at a time on payment systems and monolith-to-services migrations. *"02 · Years"* is a tabular work history (Stripe → Monzo → Knot → independent). *"03 · Writing"* lists five linked pieces with date columns. *"04 · Reach"* is a four-cell contact grid (email · GitHub · LinkedIn · Mastodon). **Live:** [`_tests/06-anya-portfolio/`](../../site/_tests/06-anya-portfolio/index.html) --- ## 07 · Foundry · Compliance SaaS **Prompt:** > *"Build me a landing page for Foundry — SOC 2 and ISO 27001 compliance automation for B2B SaaS. Show: how many companies got compliant, what it costs, who uses it. Audience: founders + CTOs. Tone: technical but trustworthy."* **Inferred trio:** explicit. **Picks:** Bento Grid · **Newsprint** (warm-cream paper, Source Serif 4 display, warm-deep-red accent) · Tier-A pure-CSS logo grid (eight wordmark placeholders, mono). **Excerpt:** > Newspaper-banner masthead with the wordmark centred. Hero left-bias: *"Compliance, ground out in **days**, not in months."* — the word "days" set in red italic. Right: a pull-quote panel with a CTO testimonial. Below: a 6-tile bento — (1) the "847." anchor stat with a one-line caption, (2) eight customer wordmarks in a 4×2 logo grid, (3) three-tier pricing snippet (Starter $299 · Team $899 popular · Scale custom), (4) a second testimonial pull-quote, (5) a six-row "what's automated" feat-list, (6) a six-question FAQ teaser. Final CTA strip: *"Start the trial. Cancel before the first invoice if it's not ready."* Single-line colophon. **Live:** [`_tests/07-foundry-compliance/`](../../site/_tests/07-foundry-compliance/index.html) --- ## 08 · Cohort · Cohort-based courses **Prompt:** > *"Build a landing page for Cohort — the platform for cohort-based courses. Run live courses with 30 to 500 students. Built for educators, not LMS sales teams. Audience: course operators + indie creators. Tone: warm, salon-room, editorial."* **Inferred trio:** explicit. **Picks:** Stat-Led · **Linen** (warm beige paper, Inter Tight geometric-sans, warm-amber accent) · no enrichment (typography only — the brief's "30–500" range is the visual). **Excerpt:** > Centred eyebrow: *"Built for educators · not LMS sales teams."* Hero stat at 22 rem: **"30 — 500"** (with the dash in warm-amber). Headline: *"Live courses, the size your roster actually is."* Sub: *"Cohort runs courses with thirty to five hundred students at once — the size of a real classroom, the size of a real lecture, and a few sizes between. With a date, a roster, and a room."* Below: three supporting stats (186 cohorts run · 93 % finish-rate · 4.7/5 operator NPS). Two operator testimonials side-by-side. Two-tier pricing (First cohort free · Operator $199/mo). Single CTA strip and colophon. No marquee, no card-stack — the brief carried by the typography. **Live:** [`_tests/08-cohort-courses/`](../../site/_tests/08-cohort-courses/index.html) --- ## How the recipes are organised Every recipe shares the same four lines so you can scan a brief and immediately see *which combination Hallmark picks for what*: 1. **Prompt** — verbatim, copy/paste-ready. 2. **Inferred trio** — what the design-context-gate produces (audience · use · tone). Marked `explicit` if the user provided all three; `the user opted out` if not. 3. **Picks** — macrostructure · theme · enrichment archetype. 4. **Excerpt** — one paragraph of the produced copy or layout, so you can verify the output matches the brief without running the skill yet. When generating something new, look for the closest match in this file and **note what's different** between your brief and the recipe. The macrostructure pick is usually inherited; the theme often shifts (per the diversification rule); enrichment may change tier. ## What the recipes are *not* - Not templates. Hallmark's whole point is structural variety — duplicating a recipe verbatim is the **Specimen-fall-through** anti-pattern (gate 23 in [`SKILL.md`](../SKILL.md)). - Not fixed picks. Two consecutive runs of recipe 00 (Coffeebox) on the same project should produce *different* macrostructures or themes — the [`.hallmark/log.json`](../SKILL.md) project memory enforces this. - Not exhaustive. The 21 macrostructures × 16 themes × 8 enrichment archetypes = 2,688 distinct fingerprints. The 9 recipes here are a starter set; the next 50 are yours to discover. --- ## File: docs/study-examples.md # `hallmark study` — three worked examples How `study` reads a screenshot the user admires, returns a diagnosis, and (optionally) rebuilds the user's content with the extracted DNA. Each worked example below shows: what the user pasted · what the skill names · what it refuses to do · what it produces. The whole point of `study`: extract **structural DNA** (macrostructure + archetypes + type-pairing role + colour anchor + rhythm), **never pixels**. If the user wants a 1:1 copy, they want a different tool. Hallmark hands them a diagnosis and lets them keep the bones. --- ## Example A · A Pentagram-style editorial portfolio **What the user pastes:** a screenshot of a New York studio's portfolio site — large italic-serif name in the top-left margin, numbered project list flowing down the page, generous warm-cream paper, a single warm-orange accent on the active project, a hairline rule between rows. (User says: *"I want my portfolio to feel like this.")* ### Refuse-or-proceed check Public reference for inspiration → proceed. (Refusal heuristics fire on: paid-template-marketplace listings, copy-protected portfolios. None match.) ### Diagnosis report (what `study` returns first) > **Macrostructure:** **Specimen** (numbered left-margin labels + huge italic serif + asymmetric spans + typographic-only CTA). > > **Hero archetype:** H4 Margin-Number Display — the page's only anchor is a vertical column of two-digit indices. > > **Pitch archetype:** none. The work is the pitch. > > **Footer archetype:** Ft1 Single-Line Colophon — studio name, year, contact, three links, no nav. > > **Display family role:** italic editorial serif (high optical size, soft axis, ink-black). **Body family role:** geometric sans (humanist Inter-Tight-or-similar at 350-400 weight). Two free candidates: *Fraunces* italic display + *Geist* body. One paid candidate the user might confirm: *Tiempos Headline* + *Söhne*. The skill names *roles*, not exact font IDs — visual font ID is unreliable. > > **Surface lightness band:** light (paper L ≈ 96%). Slight warm tint at hue 80 — Pentagram-warm cream, not stark white. > > **Accent hue band + chroma:** warm-orange ~25-30°, low chroma (≤ 0.13), used at < 5% of viewport. One accent, applied to active state and the one number the brand wants the visitor to remember. > > **Density verdict:** sparse. ~3-4 macro elements on the first viewport. Generous vertical margin between rows (≥ `--space-3xl`). > > **Type-pairing role:** italic-display + sans-body — the canonical editorial pairing. > > **Two anti-patterns the screenshot has** that you should NOT carry over: > > 1. The hover-state on the number-label uses a slow ease-in-out 800 ms colour fade. Per `microinteractions.md` § The timing canon, hover state should be 150–200 ms. Carry the *idea* (colour-shift on hover); shorten the *duration*. > 2. The footer text is set at 11 px with 0.06em tracking — under the 14 px floor for body copy. Bump to 12-13 px on rebuild, keep the tracking. ### Confirmation question > *"Adopt this DNA wholesale, or change one axis? For example, I could keep the macrostructure (Specimen) but pick a theme that better matches your work — if your tone is more ink-blue and B2B, I'd suggest **Plain** (pure-white paper) instead of the warm-cream **Specimen** theme."* ### What `study` builds when the user says "go" Macrostructure stamp: ```css /* Hallmark · macrostructure: Specimen · H4 hero knobs: number-column=margin, alignment=left-bias * theme: Specimen · accent: warm-orange ~3% · enrichment: none * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (free pairing applied) */ ``` Output: the user's actual portfolio entries arranged in a numbered-margin column with italic-Fraunces titles and Geist-body summaries. Hover delays shortened to 200 ms. Footer text bumped to 12 px. The bones come from the screenshot; the words and projects come from the user. --- ## Example B · A Klim-Type-Foundry-leaning specimen **What the user pastes:** a screenshot of a type-specimen page — full-bleed black paper, single huge geometric-sans display character ("R") tilted -2°, a ruled grid behind it, a footer-band with the typeface name, weight, OpenType features, and a tiny set of glyph callouts. (User says: *"This is the energy I want for our agency rebrand.")* ### Refuse-or-proceed check Type specimens are typically published references; proceed. (If the screenshot were a paid font foundry's marketing page with an explicit "preview is licensed" watermark, the skill would refuse and ask the user to bring an unconfirmed reference.) ### Diagnosis report > **Macrostructure:** **Type Specimen** (single character or word centred + ruled grid + footer-band of metadata). > > **Hero archetype:** H9 Single-Glyph — the entire above-the-fold is one letterform. > > **Pitch archetype:** none on the first viewport. The page is *the work being specified*. Pitch (if any) lives below the fold as supporting paragraphs. > > **Footer archetype:** Ft3 Tabular-Specimen — name · weight · OpenType features · designer credit. > > **Display family role:** geometric-sans-heavy (display-display, weights 800-900). **Body family role:** the same sans at 400 — single-font specimen pages are allowed when the single font *is* the design (per `typography.md`). Free candidate: *Bricolage Grotesque 800*. Paid candidate: *Druk* or *NaN Jaune*. *Refuse to guess the exact paid font ID.* > > **Surface lightness band:** dark (paper L ≈ 12%). The dark is uniform across the viewport — no gradient. > > **Accent hue band + chroma:** chromatic-other — single hot-orange callout at ≈ 0.18 chroma, used on **one** OpenType-feature label. Even in a stark specimen, the rule "accent < 5% of viewport" holds. > > **Density verdict:** ultra-sparse. One element above the fold. Density only increases below. > > **Type-pairing role:** single-family specimen (single-font is the design). Body and display the same family at different weights. > > **Two anti-patterns the screenshot has** to NOT carry over: > > 1. The footer-band uses light-grey text (oklch ~75% lightness) on near-black paper. Contrast ratio ~3.2:1 — fails WCAG AA for body. Bump to oklch ~88% on rebuild. > 2. The grid lines behind the glyph are at 1 px solid white at 0.4 opacity. On a 4K display this becomes a sub-pixel that disappears or aliases. Use 1 px solid + colour-mix down to 35% lightness instead — keeps visibility across pixel densities. ### Confirmation question > *"This DNA is for a specimen page, not a marketing page. If you're rebranding an agency, the glyph hero will be impressive on the first visit and pointless after. Suggested adaptation: Type Specimen as the homepage, then a Long Document or Workbench pattern for the about / case-studies / contact pages. Pick: keep all-Specimen, or hybrid?"* ### What `study` builds (hybrid path) Macrostructure stamp: ```css /* Hallmark · macrostructure: Type Specimen · H9 hero knobs: glyph=user-mark, tilt=-2deg, grid=1px-soft * theme: Manifesto · accent: hot-orange ~3% · enrichment: none * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (Bricolage 800 free) */ ``` The homepage emits the agency's mark in 22-rem Bricolage 800, ruled grid behind, single-line metadata footer. The about and case-study pages inherit the dark-paper + geometric-sans tokens but switch to **Workbench** macrostructure (left-margin index + 1fr content). Brand consistency, structural variety. --- ## Example C · A small-studio personal site (Rauno-Freiberg-style) **What the user pastes:** a screenshot of a personal designer-engineer site — dark-mode paper, a small italic-serif name in the top-left, a single demo embed at the centre (CSS-art clock that ticks), a writing list below. (User says: *"I want my own personal site to feel like this.")* ### Refuse-or-proceed check An ambiguous source is the edge case here. Per `study.md` § Refusal heuristics: when you can't tell whether the source is the user's own work or someone else's, ask first. > *"Is this your own work, a public reference for inspiration, or someone else's live site? If it's someone else's live site, I'll extract the DNA at the structural level only — no copy, no demos, no font IDs — and you'll bring your own content. If it's a paid portfolio template, I won't reproduce it."* User confirms: public reference for inspiration → proceed with DNA extraction only. ### Diagnosis report > **Macrostructure:** **Long Document** with a centred demo as the hero archetype. > > **Hero archetype:** H5 Centered-Demo — a single hand-built artefact (CSS art, SVG illustration, declarative animation) sized at ~24 rem, centred on the page, no other hero copy above it. > > **Pitch archetype:** P3 List-of-Writings — title + date + 1-line summary, in a tabular column. > > **Footer archetype:** Ft1 Single-Line Colophon. > > **Display family role:** italic editorial serif. **Body family role:** geometric sans, body weight 400. Free candidate pairing: *Fraunces* italic + *Geist*. > > **Surface lightness band:** dark (paper L ≈ 16%). Slight cool tint at hue 240. Inks at ~90-95% L, also slight cool. > > **Accent hue band + chroma:** chromatic-other — green at hue 145, ≈ 0.14 chroma. Used on the active demo's signal element (the ticking dot), nowhere else. > > **Density verdict:** sparse-medium. Hero demo + ~12-line writing list above the fold. > > **Type-pairing role:** italic-display-with-sans-body — same as Specimen, just on dark paper. > > **One anti-pattern the screenshot has** to NOT carry over: > > 1. The CSS-art clock loops at 1 fps with no `prefers-reduced-motion` fallback. **Always pair declarative animation with a reduced-motion alternative** (`microinteractions.md` § Reduced motion is a first-class state, not an afterthought). > > One thing the screenshot does *better than most* and you SHOULD carry over: > > 1. The italic name in the top-left has a baseline at the same y-position as the centred demo's vertical centre — a subtle horizontal-baseline alignment that makes the page feel composed rather than stacked. Carry this; it's invisible until removed. ### Confirmation question > *"The DNA is portable: dark paper · italic-Fraunces name · centred demo · cool-green accent. Two questions before I build: (1) what's your demo? — I can hand-build it as Tier-A CSS art if you describe it, or you can paste an existing animation. (2) do you have ~5 writings to seed the list, or should I leave a placeholder section?"* ### What `study` builds when the user provides their own demo + writings Macrostructure stamp: ```css /* Hallmark · macrostructure: Long Document · H5 hero knobs: demo=centered, size=24rem * theme: Midnight · accent: forest-green ~3% · enrichment: Tier-A custom-craft (user-supplied recipe) * studied: yes · DNA-source: user reference · with reduced-motion fallback */ ``` Output: the user's actual name in italic-Fraunces top-left, their demo (e.g. an ambient breathing-loop) hand-built as CSS art with an explicit `@media (prefers-reduced-motion: reduce)` fallback, their writings tabulated below in Geist body. The bones from the screenshot; the demo and writings from the user. **No pixel-faithful reproduction.** --- ## What `study` doesn't do (worth restating) 1. **Names the font role, not the font ID.** Visual font identification is unreliable. The skill proposes one or two real candidates from the canon and asks the user to confirm. 2. **Never copies pixels.** The DNA is the macrostructure + archetype + colour-anchor + type-pairing — not the dress. 3. **Refuses the obvious bad sources.** Paid-template-marketplace listings; copy-protected portfolios without permission. 4. **Always disclosures the substitutions.** When the screenshot's font is paid (Tiempos / Söhne / Druk) and the user hasn't confirmed a licence, the skill names a free understudy (Fraunces / Inter Tight / Bricolage Grotesque) and *says it's substituting*. These three examples cover the most common categories of `study` request: an editorial portfolio, a type-specimen statement page, and a small personal site. The protocol is the same for every screenshot — refuse-or-proceed, diagnose, confirm, build. See [`study.md`](study.md) for the full protocol. --- ## File: docs/talk-slides.md # Stop letting your agents ship ugly UIs. How to build well-designed UIs with AI agents. Hassan El Mghari · Together AI · AI Engineer World's Fair · 2026 --- > **About this deck** — this is a general playbook for any AI engineer, not a product pitch. Hallmark is mentioned once, on slide 15, as one open-source example our team built. The seven fixes apply to v0, Lovable, Bolt, Cursor, Claude Code, or any agent you're building yourself. > > **Visual style** — dark slate `#0b1117`, off-white ink `#e6edf3`, GitHub-cool-blue accent `#58a6ff`. Inter for type, Roboto Mono for code. Every slide chrome-free: no eyebrow labels, no decorative hairlines. Footer is the Together AI logo bottom-left and a page number bottom-right. > > **Cadence** — 17 slides, 18 minutes. ~60 seconds per slide. Section opener (S05) is a 10-second beat. S08 (wireframes), S11 (eight states), S13 (system prompt) want a moment. --- ## 01 · Cover # Stop letting your agents ship ugly UIs. *How to build well-designed UIs with AI agents.* — Hassan El Mghari · Together AI · AI Engineer World's Fair · 2026 *Speaker: I'm Hassan, I lead DX at Together AI. Most of you have built an AI app this year and watched it ship a UI you'd never put on your portfolio. This talk is about why that happens, and seven concrete things that fix it — for any agent you use.* --- ## 02 · The problem # Here's what your agent ships today. *(Visual: the real DevForge screenshot — a generated developer-conference landing page. Purple-cyan gradient on the headline, centered hero, four-column stat row, Inter on Inter.)* > Vanilla prompt. Same shape every time. *Speaker: I gave the same prompt to a dozen agents — "build me a landing page for a developer conference, dark theme, in Brooklyn." This is roughly what every one of them returned. Different models, different stacks, same page.* --- ## 03 · The promise # It could ship this instead. *(Visual: the Hyperlane screenshot — same brief, rebuilt. Big sans-serif headline with an italic-serif accent, asymmetric layout, single warm accent, monospace meta.)* > Same brief. One missing layer added. *Speaker: Same brief. Same agent. The difference is the layer between the prompt and the output. We'll spend the rest of the talk on that layer.* --- ## 04 · Why # Models ship the mean of their training set. *Every SaaS site since 2019 trained on the same shape. Without external steering, the agent regresses to it.* > Every part of this is fixable with prompting and a small amount of structure. *Speaker: This isn't a model failure. Claude can render anything you describe. It's that "make me a landing page" maps to a region of the manifold where every SaaS site since 2019 lives. The good news: every fix from here is something you can do today, with any agent.* --- ## 05 · Section opener # Seven things that fix it. *Tool-agnostic. Works with v0, Lovable, Bolt, Cursor, Claude Code, or your own agent.* *Speaker: Each one of these closes a class of slop. Each one works today.* --- ## 06 · Fix 01 — Use a real component library # Use a real component library. shadcn/ui is the lingua franca of generated UI. Every major AI tool is trained on it. Linear, Vercel and Stripe ship it. Adopt it and your agent's output gets 80% better on day one. ```bash $ npx shadcn@latest add button card dialog input table ``` → *drop the components in. Now every AI generation composes from a real system, not from invented primitives.* *Speaker: This is the cheapest, highest-leverage move. Most AI engineers know about shadcn/ui. Fewer actually adopt it. v0 ships it natively. Cursor reads it. Claude Code reads it. The model has seen millions of examples of these components — it knows how to compose them.* --- ## 07 · Fix 02 — Pin a design system # Pin a design system. A single file at the root the agent reads on every render. One palette, one type pairing, one scale. No mid-render improvisation. ```css /* DESIGN.md or app/globals.css — Tailwind v4 @theme block */ @theme { --color-paper: oklch(0.13 0.01 250); /* one surface, not five */ --color-ink: oklch(0.93 0.01 250); /* one ink */ --color-accent: oklch(0.65 0.18 250); /* one accent, under 5% */ --font-display: "Inter Tight", sans-serif; --font-body: "Inter", sans-serif; --space-1: 0.25rem; /* 4-pt scale */ --ease-out: cubic-bezier(.2,0,0,1); } ``` *Speaker: Tailwind v4 made this easier than it used to be. One `@theme` block, OKLCH for color, semantic names. Drop a `DESIGN.md` next to it that describes the brand in plain English — what the brand sounds like, what it isn't. The agent reads both on every run.* --- ## 08 · Fix 03 — Ask for a shape # Ask for a shape, not a list of features. *Stop saying "hero with three features." Say marquee. bento. long-document. stat-led.* *(Visual: four abstract wireframes drawn in Figma showing each shape.)* - **MARQUEE** · one editorial idea, biased left - **LONG DOCUMENT** · reads like a letter, no marketing chrome - **BENTO** · many entries, irregular grid - **STAT-LED** · product is the headline; numbers carry it *Speaker: This is the move that breaks the "every page looks like a SaaS landing" attractor. Don't enumerate features. Pick a category of page. The same way Linear's home and Stripe's home don't share a shape — they share a category.* --- ## 09 · Fix 04 — Show a reference # Paste a screenshot. Don't describe it. AI sees more than it reads. A reference image carries more taste than a paragraph of adjectives. ``` → pick a real site you admire. → ask the agent to extract the structure, not copy the pixels. → name the role of the type ("italic editorial serif"), not the font. ``` *(Visual right: a real screenshot of calendly.com — the reference you'd actually paste.)* > example · pasted calendly.com to the agent *Speaker: Designers have always done this — "make it feel like this." Until recently your agent had no equivalent. Now it does. Don't describe taste. Show it. And ask the model to extract structure, not pixels — what you want is the rhythm, not a knock-off.* --- ## 10 · Fix 05 — Ban the tells # Tell it what you DON'T want. *Constraints beat instructions. Put these in your system prompt:* - ✕ Purple → blue gradient hero - ✕ Inter / Roboto as display AND body - ✕ Three equal columns with icon-above-heading - ✕ `min-height: 100vh`, everything centered - ✕ Cards inside cards (no semantic reason) - ✕ `background-clip` text gradients on headlines - ✕ Pure `#000` or pure `#fff` as a surface - ✕ Invented metrics, testimonials, or logos *Speaker: Counterintuitive but true: telling the model what NOT to do is stronger than describing what you want. These eight tells are the fingerprints of AI-generated UI. Ban them and the model has to reach somewhere else.* --- ## 11 · Fix 06 — Eight states # Every interactive element ships eight states. *If the agent emits two, your UI ships broken.* *(Visual: eight actual buttons in a 4-by-2 grid, each visibly in a different state — default, hover, focus-visible, active, disabled, loading, error, success.)* | state | what makes it different | | --- | --- | | `default` | the resting style | | `hover` | one shade lighter | | `:focus-visible` | a 2px accent ring, instant (no fade-in) | | `:active` | inverted ink, accent fill | | `disabled` | 50% opacity, no pointer | | `loading` | `· · · working` | | `error` | red border, ⚠ retry | | `success` | green border, ✓ saved | *Speaker: This is the single fastest "real or vibes" test you can run on AI output. Tab into the page. Disable a field. Make something load. If three of the eight states are unstyled, the agent shipped a screenshot, not a component.* --- ## 12 · Fix 07 — Critique before emit # Make the agent grade its own work — first. *One line in the system prompt forces a critical pass before output. Two passes is normal.* - **DISTINCTIVENESS** · does this look like THIS brief — or any brief - **HIERARCHY** · can a reader tell first / second / third in 2 seconds - **EXECUTION** · are the details right (rules, spacing, focus rings) - **RESTRAINT** · cut what doesn't earn its place Score each 1–5. Anything below 3 → revision pass. *Speaker: The trick isn't the rubric — it's forcing the model to look at its own output critically before it returns. Two passes is normal. Three passes means the brief is too vague.* --- ## 13 · The whole playbook # You can fit the whole playbook in one paragraph. ```md # system_prompt.md You are a designer, not a templater. Before you write code: 1. use shadcn/ui — never re-invent a primitive that already exists. 2. read DESIGN.md for tokens. Use only those. 3. pick ONE page shape (marquee, long-document, bento, stat-led, manifesto, catalogue). 4. ban: purple-cyan gradients, Inter on Inter, 3-col icon grids, 100vh centered hero, card-in-card, background-clip text, pure #000 / #fff, invented metrics. 5. ship 8 states for every interactive element. 6. score Distinctiveness · Hierarchy · Execution · Restraint on 1–5. anything <3 triggers a revision pass. ``` *Speaker: That's it. Seven lines. Drop this in any agent's system prompt — Cursor `.mdc`, Claude Code skill, v0 project instructions. Feel the difference on the next render.* --- ## 14 · Tools # Pick your weapon. *Same seven fixes. Different surfaces.* | | | | | --- | --- | --- | | **v0** | shadcn / Tailwind playground | best UI quality out of the box | | **Lovable** | full-stack chat-and-build | edit visually, ship live | | **Bolt** | fast prototyping in StackBlitz | speed | | **Cursor** | in-IDE assistant | lives in your editor | | **Claude Code** | agent loop · file-aware · skills | longest-context coder | *Speaker: All of these can do beautiful work if you put the seven fixes in. Pick the one that matches your stack.* --- ## 15 · Hallmark — one example our team open-sourced # Hallmark. *One example our team open-sourced.* A Claude Code skill that bakes all seven fixes in. → `github.com/nutlope/hallmark` *(Visual: the Hallmark OG image — "The best landing pages built with AI" with three real example pages baked in.)* *Speaker: We packaged the seven fixes into a Claude Code skill for ourselves at Together AI, then open-sourced it. It's one approach — there are others (Anthropic's frontend-design skill, Taste, Impeccable, others). The principle is the same: stop letting the agent invent the rules. Hand it a system.* --- ## 16 · The big idea # Design taste is a layer in the agent stack. ``` MODELS TOOLS MEMORY RAG EVALS TASTE ← here ORCHESTRATION ``` *If you don't put it in the stack, the model picks the mean.* *Speaker: We treat eval as a first-class layer because we know models will optimize for the wrong thing without it. Taste is the same — not a polish step you add at the end. A layer. Same stack you already build with. New row.* --- ## 17 · Thanks # Thanks. ``` github.com/nutlope/hallmark together.ai ``` `@nutlope` `@YoussefXLM` *(Visual right: a real QR code linking to the Hallmark repo.)* > scan to install *Speaker: Thanks. The skill is open today. I'd love to see what you build with it — and what fixes you'd add to your own agent's stack.* --- # Designer / production notes **Chrome — kept minimal on purpose** - No eyebrow labels at the top of slides. - No decorative hairlines, dividers, or accent rules. - Footer is two elements only: the Together AI logo bottom-left (32×32), and the slide number bottom-right. - Functional rectangles (code-block surfaces, button shapes on S11, axis cards on S12) are kept — they carry content. **Palette — locked** - BG `#0b1117` (deep slate) - Surface `#161b22` (code blocks, cards) - Ink primary `#e6edf3` - Ink secondary `#7d8590` - Accent `#58a6ff` (GitHub cool blue — links, key labels, accent fills) - Alert `#f85149` (only on Fix 05 ban list and Fix 06 error button) - Success `#3fb950` (only on Fix 06 success button) **Type** - Display: Inter (Black / Bold weights at huge sizes) - Body: Inter Regular / Light - Code & mono labels: Roboto Mono **Pacing** 17 slides for an 18-minute slot ≈ 60 seconds per slide. The section opener (S05) is a 10-second beat. The system-prompt slide (S13) wants a moment for Hassan to read it out loud. The Hallmark slide (S15) is intentionally quiet — read the label, don't dwell. **If running long** In order: S04 (Why — can fold into S02 narration), S16 (the stack diagram — can be one sentence after S15). Never drop S05, S08, S09, S11. **If running short** Add a live demo after S09. Paste a screenshot of a designed site, run the agent, show the output. 90 seconds max. **The markdown deliverable** This file (`docs/talk-slides.md`) is the canonical copy. If the Figma file gets reorganized, this stays authoritative. --- # Sources - ["shadcn/ui March 2026 Update: CLI v4, AI Agent Skills and Design System Presets"](https://medium.com/@nakranirakesh/shadcn-ui-march-2026-update-cli-v4-ai-agent-skills-and-design-system-presets-d30cf200b0e9) - ["AI-First UIs: Why shadcn/ui's Model is Leading the Pack" — Refine](https://refine.dev/blog/shadcn-blog/) - ["Design Systems for the Vibe-Coding Era" — Anna Arteeva, Design Systems Collective](https://www.designsystemscollective.com/design-systems-for-the-vibe-coding-era-42282e1affef) - [Anthropic — "Improving frontend design through Skills"](https://claude.com/blog/improving-frontend-design-through-skills) - ["v0 by Vercel — Complete Guide 2026"](https://www.nxcode.io/resources/news/v0-by-vercel-complete-guide-2026) - ["The Vibe-Coder's Prompting Guide" — Anna Arteeva, Medium](https://annaarteeva.medium.com/the-vibe-coders-prompting-guide-e04ba0295a18) - ["Choosing your AI prototyping stack: Lovable, v0, Bolt, Replit, Cursor, Magic Patterns" — Anna Arteeva, Medium](https://annaarteeva.medium.com/choosing-your-ai-prototyping-stack-lovable-v0-bolt-replit-cursor-magic-patterns-compared-9a5194f163e9) - [AI Engineer World's Fair 2026 — Jun 29 – Jul 2](https://www.ai.engineer/worldsfair) - [Hassan El Mghari · DX at Together AI](https://www.nutlope.com/) --- ## File: site/_tests/custom/README.md # Custom worked examples Three landing pages produced by the **custom** theme route — the new opt-in branch added to Hallmark in v0.6.x. Custom is the route for one-off custom palettes + font pairings tuned to a single brand. **Catalog** (the 16 named themes) is the default; custom fires only when the brief signals creative or unique intent. These three pages are the worked examples written into [`references/custom-theme.md`](../../../skills/hallmark/references/custom-theme.md) § G — rendered as actual HTML so the palette + pairing can be inspected visually. | # | Brand | Vibe | Anchor | Macrostructure | Axes | | --- | --- | --- | --- | --- | --- | | 01 | **Coffeebox** — small-batch coffee subscription | "archival warmth, hand-set, no varnish" | terracotta | Long Document | light / italic-serif / chromatic-terracotta | | 02 | **Loop** — payment-rail observability for fintechs | "industrial precision, cool, technical" | sea-blue | Workbench | dark / mono / cool | | 03 | **Mossroot** — herbal apothecary in Porto | "moss, lichen, soft pink, herbal" | (skipped — derived) | Catalogue | light / roman-serif / chromatic-other (dusty-pink) | Each folder holds: - **`index.html`** — the rendered page - **`style.css`** — custom palette + pairing as inline `:root` tokens, with the custom stamp at the top ## What custom unlocks The 16 named themes can't carry every brand. Coffeebox is closest to **Atelier** but warmer + more terracotta-led; Loop is closest to **Midnight** but mono-everywhere and sea-blue not phosphor-cyan; Mossroot has no catalog match (moss-tinted paper with dusty-pink accent isn't in the catalogue). Without custom, all three pages would compromise on the brand voice. With custom, the palette + pairing are tuned to the specific vibe — and every existing rule (OKLCH bands, accent footprint, font ban list, slop test) carries forward unchanged. The freedom is the combination, not the rules. ## What guards prevent over-invention 1. **The opt-in is opt-in.** Custom fires only when the user signals creative/unique intent in their prompt (named brand colour, multi-attribute aesthetic that doesn't match a catalog theme name, explicit "make it custom"). Default route is catalog — no behavioural change for vanilla briefs. 2. **One question only.** The skill asks vibe (4–8 words) + optional anchor colour. Anything more is over-asking. 3. **Every existing rule applies.** color.md OKLCH bands, typography.md pairing catalogue, anti-patterns.md ban list, the 38 slop-test gates — same gates fire as on catalog themes. 4. **The Step 5 preview surfaces the palette + pairing.** Before any code is emitted, the user sees the OKLCH values and the chosen fonts in plain text. They can redirect early. 5. **Diversification is theme-route-blind.** Each custom run records its three axis values (paper-band / display-style / accent-hue) in `.hallmark/log.json`. The next run rotates against them the same way it does against catalog themes. See [`references/custom-theme.md`](../../../skills/hallmark/references/custom-theme.md) for the full protocol. --- ## File: site/_tests/verbs/README.md # Hallmark verbs — worked examples Each verb demonstrated on a tiny, realistic input. Folders contain the input, the verb's output, and a one-page note explaining what fired and why. | Verb | Folder | Input | What the verb does | | --- | --- | --- | --- | | `audit` | [`audit/`](audit/) | An AI-templated landing fragment | Read it, score against the anti-pattern list, return a ranked punch list. **Does not edit.** | | `redesign` | [`redesign/`](redesign/) | A page with the AI structural template (centered hero · 3 cards · CTA · footer) | Throw out the structure, rebuild with a different fingerprint. **Preserves copy + IA.** | | `study` | [`study/`](study/) | A described screenshot of a Pentagram-style portfolio | Extract DNA — macrostructure, archetypes, type-pairing role, accent — return a diagnosis report, then rebuild user content with that DNA. **Never copies pixels.** | Each folder holds: - **`input.html`** (or `input-description.md` for `study`) — what the user paste / attach. - **`output.*`** — what the verb produces. For `audit` and `study`, this is a Markdown report. For `redesign`, this is a finished `index.html` + `style.css`. - **`notes.md`** — one page explaining what fired, what reference files loaded, and what the durable artifact is. The three verb tests together exercise every load path in the skill that the default-flow tests don't. --- ## File: site/_tests/README.md # Hallmark — generation tests Eight landing pages produced by exercising the Hallmark skill across contrasting briefs. The point: see what comes out *without* hand-holding the AI on theme, structure, or enrichment. Each test deliberately tests a different scenario. The current generation reflects **v0.6.0** of the skill — pre-flight scan, project-memory rotation, and the upfront preview block all firing. Each `brief.md` walks through Steps 0 → 6 of the design flow so the discipline is visible. | # | Brief | Context given | Theme requested | What the skill picked | | --- | --- | --- | --- | --- | | 01 | Indie podcast `Tide`, no detail | **Skipped** ("you pick") | none | Letter + Salon + no enrichment | | 02 | Open-source CLI `Streampipe` for stream parsing | Full (devs / install + docs / technical) | **Terminal** (requested) | Long Document + Terminal + Tier-A inline CSS-art terminal | | 03 | Artisan bakery `Maple Street Bread` | Full (locals / browse + visit / warm hand-set) | none | Catalogue + Almanac + Tier-A hand-built SVG bread silhouettes | | 04 | Manifesto for an environmental studio `Meridian` | Partial ("declarative, no flashy stuff") | none (implied) | Quote-Led + Brutal + no enrichment · single-line polemic with strike accent | | 05 | SaaS observability tool `Tracejam` | Full (SREs / try-or-talk-to-sales / technical) | none | Workbench + Midnight + Tier-A sticky trace panel | | 06 | Personal one-pager for `Anya` (software architect) | **Skipped** ("don't ask, just figure it out") | none | Index-First + Plain + no enrichment | | 07 | SOC2 / ISO27001 compliance SaaS `Foundry` | Full (founders + CTOs / try-or-talk-to-sales / technical-but-trustworthy) | none | Bento Grid + Newsprint + Tier-A logo grid · 6-tile bento on warm-cream paper | | 08 | Cohort-based courses platform `Cohort` | Full (educators / run-courses / warm-salon-room) | none | Stat-Led + Linen + no enrichment · the brief's "30–500" range as the typographic hero | Each folder contains: - **`brief.md`** — the verbatim prompt + the new design flow (Step 0 Pre-flight, Step 1 Context, Step 2.5 Rotation, Step 5 Preview, Step 6 Stamp) - **`index.html`** — the rendered page (self-contained, no shared assets) - **`style.css`** — the page's tokens + components, with the Hallmark stamp at the top Open any one with `open site/_tests//index.html` or browse via the local dev server at `http://localhost:8765/_tests//`. **Eight distinct fingerprints across eight prompts.** No macro repeats. No theme repeats. Every adjacent pair differs from its neighbour on at least one of: macrostructure / display style / accent hue / paper band — the v0.6.0 rotation rule firing. ## What this exercise was for Stress-testing the skill on briefs that range from "complete spec" to "you figure it out, I'm lazy". Specifically watching for: 1. Does the skill default to the same shape twice across the six tests? → No two should share a macrostructure or hero archetype. 2. Does the skill enrich every page even when it shouldn't? → Tests 01, 04, 06 should be typography-only. 3. When the user skips the design-context gate, does the skill state its inferences in one sentence at the top? → Yes, see brief.md headers. 4. Does the skill bend toward "Built for the modern team" voice when copy is left to it? → Each brief has its own voice; no template-soup. Findings and a priority list of skill improvements are at the bottom of this file, after the six test cases. --- ## Findings — what worked, what didn't, what to fix ### What worked 1. **Six different briefs produced six structurally different pages.** No two share a macrostructure, hero archetype, or footer voice. The page-shape variety the skill is built around held up under the test. 2. **Three of six tests ship with no enrichment.** The skill correctly resisted the urge to add a Lottie / illustration / mockup to the podcast (typography-only is right for voice), the manifesto (a manifesto is not a marketing page), and the personal portfolio (restraint is the credibility signal). This is the test the *previous* anti-slop generation failed. 3. **The two tests that reach for hand-built CSS art (Tracejam flame chart, bakery loaf) produced custom DOM — not Lottie.** The skill picked Tier-A or Tier-B from the enrichment hierarchy without asking, and the result feels designed, not pulled. 4. **The skipped-context flow worked twice (01 podcast, 06 architect).** Both pages open with an inferred-context disclosure sentence at the top of `brief.md`, which is the documented pattern. The skill states what it inferred. 5. **Type pairing held across all six.** No two tests share a font stack. Newsreader (1, 3), Geist Mono (2, 5), Inter Tight (4), Fraunces (6) each carry one page; pairing logic is theme-driven so this fell out naturally. 6. **The clipped-edge mockup (test 5) was hand-built CSS, not a video file.** The skill resisted the temptation to ship "embed a Loom" — the trace waterfall is pure CSS bars on a percentage grid. ### Friction points I hit while generating - **The "domain → trio" table covers most cases but not all.** The bakery is in the table; the manifesto is in the table; the personal portfolio is in the table. The SaaS tracing tool is *implicitly* in the table under "platform / tool / infra". The podcast is in the table. **But:** I had to combine "SaaS marketing" + "developer tool" mentally to land on Bento Grid for Tracejam — the skill could be more explicit about *which* of the three suggested macrostructures wins for a given sub-domain. (E.g., "platform/tool" → Workbench or Bento; pick Workbench when the brief says docs/walkthrough, pick Bento when the brief says try-or-talk-to-sales.) - **Theme picking is still by feel.** The skill has a strong rule that "the next theme can't be Specimen if the last one was Specimen" — but no rule like *"the next theme should be categorically different on at least one of: paper-band, display-style, accent-hue."* I avoided repeating themes here by deliberate intuition; a documented rule would help future runs. - **Copy generation bent toward "Built for the modern team" twice — and I had to course-correct.** Tracejam's first draft headline was *"Trace what matters."* — a near-template; I rewrote it to *"Distributed tracing that explains itself."* which is more specific. **The skill needs example copy fixtures per macrostructure** (Tier 3 in the existing roadmap) — without them, the model bends toward LLM-distribution copy. - **The `hero-enrichment.md` decision protocol is text-only — no concrete worked examples per domain.** I had to imagine what Tracejam's "Demo Video Clipped-Edge" looks like vs. "Mockup Split"; an in-file example for each enrichment archetype on a real page would speed this up. - **Within-archetype variation knobs work in theory but I leaned on the same defaults.** The two pages with footer-index (Tracejam, none of the others ended up there) and footer-inline (the podcast, the bakery, the architect) all converge on the same shape. A future run on the *same* footer archetype should pick *different* knobs — but the rule lives in the cookbook, not in muscle memory. - **Free fonts only got me so far.** The bakery wanted Tiempos Headline (paid, Klim); I substituted Newsreader. The Studio theme on Anya's portfolio wanted Tobias (paid); Fraunces is a strong understudy but not the same. The skill should explicitly call out free-vs-paid trade-offs with two-tier candidates per pairing. ### Improvement list — priority order This is the punch list. Do these and the skill goes from "good" to "as good as a human-curated design.md gets in 2026". #### Tier 1 — Real holes (next session) 1. **Per-archetype example copy fixtures.** For each of the 21 macrostructures, ship 2–3 example *opening-line copy fragments* in `references/macrostructures.md`. The model imitates them instead of bending to LLM distribution. Highest single payoff for output quality. Currently roadmap Tier 3. 2. **Sub-domain refinement for the trio table.** Split "platform / tool / infra / dashboard / developer" into two rows: *docs/walkthrough* → Workbench / Long Doc; *try-or-talk-to-sales* → Bento / Stat-Led / Workbench. Same for "personal" (one-pager Letter vs. multi-page Long Doc). 3. **A documented theme-diversification rule.** *"Across consecutive Hallmark outputs in this user's session/project, no two themes should share more than one of: paper-band, display-style, accent-hue."* Currently the rule is "don't repeat Specimen", which is tighter on one tail than it should be. 4. **Free-vs-paid font trade-off in `typography.md`.** Each tone gets two pairings: "free baseline" and "paid upgrade if the user can pay". The bakery example would say: "Free: Newsreader + Geist + Geist Mono. Paid upgrade: Tiempos Headline + Söhne + Söhne Mono." 5. **Worked examples in `hero-enrichment.md` per archetype.** A 5-line "what this looks like for X brief" under each E1–E8. Right now the descriptions are abstract; concrete worked examples accelerate generation. #### Tier 2 — Quality polish 6. **A "different knobs" check in the slop test.** Question 34: *"If I used the same archetype as a previous Hallmark output (e.g., footer-inline twice), did I pick at least one different variation knob?"* Catches the template-soup-within-an-archetype risk this exercise surfaced. 7. **More illustration recipes in `custom-craft.md`.** The bakery loaf was the only worked example. Add one for: a workflow diagram, a mascot, a small architectural diagram, a botanical accent. Each in 30–60 lines. The bakery loaf I generated above had room to be sharper — the recipes should show what *good* looks like at this scale. 8. **A `references/copy.md` extension with non-LLM voice samples.** Three voices per tone (editorial / brutalist / soft / technical / luxury / playful / austere) with 5 example sentences each. Borrow from real sites (Klim, Linear, Apple, Tufte, Rauno, Frieze) — credit them, don't copy. 9. **Mobile breakpoint discipline per archetype.** I caught this on test 5 (Tracejam): the clipped-edge mockup needed a 60rem media query to collapse to stacked. The cookbook entries should say *"on viewports below X, this archetype collapses to Y"* so it's automatic. 10. **An in-skill check: did I write `aria-label` on every visual-only SVG?** I caught it manually for the bakery loaf and the trace waterfall, but a slop-test gate would make it automatic. #### Tier 3 — Long bet 11. **Project-level memory beyond the CSS stamp.** Right now the skill reads the *latest* stamp in the project. A `.hallmark/log.json` per-project file (history of macrostructures + themes + briefs) would let the diversification rules see further back. 12. **A "study + remix" combined verb.** `hallmark study + redesign` in one — extract DNA from a screenshot, then rebuild the user's content with that DNA. Today the user has to chain `study` then `redesign`; one verb would be tighter. 13. **A real example gallery on the landing page.** These six tests should be linked from the main `site/index.html` as a "Generated by Hallmark" gallery, with one-line captions. Marketing the skill via the skill's outputs. 14. **Auto-generated Open Graph cards per page.** Each test ships its own meta description, but the OG image is missing. A small Hallmark utility that generates an OG image per page from the macrostructure stamp + headline would close the loop. ### What this means for the skill Hallmark is *good*. The structural variety position holds — six briefs, six different pages, no template repetition. The enrichment hierarchy works — three of six pages correctly choose to ship nothing visual, and the three that do enrich pick the right tier (custom-built, not Lottie). The remaining gap is **copy voice** and **theme-pick discipline**. The slop test catches *visual* tells well; it doesn't yet catch *prose* tells (like "Built for the modern team" headlines). And the diversification rules are tight on one axis (no Specimen fall-through) but loose on the rest. Tier 1 of this list is the next session's work. --- ## v0.5.0 — Tier 1, 2, and most of Tier 3 — DONE Items 1–11 and 13 from the improvement list above shipped in commit `b61f1ef`. Specifically: - ✅ **#1 Per-archetype copy fixtures** in `macrostructures.md` — 21 archetypes × 2–3 sample opening lines. - ✅ **#2 Sub-domain refinement** of the trio table in `structure.md`. - ✅ **#3 Theme-diversification rule** in `SKILL.md` — paper-band, display-style, accent-hue. - ✅ **#4 Free-vs-paid font trade-off** in `typography.md` — every tone has both rows. - ✅ **#5 Worked examples per enrichment archetype** in `hero-enrichment.md`. - ✅ **#6 Different-knobs slop-test gate** (gate 34). - ✅ **#7 Four illustration recipes** in `custom-craft.md`. - ✅ **#8 Non-LLM voice samples** in `copy.md` — 7 tones × 3 patterns × 5 samples. - ✅ **#9 Mobile-collapse discipline** in `component-cookbook.md`. - ✅ **#10 aria-label slop-test gate** (gate 35). - ✅ **#11 Project memory** `.hallmark/log.json`. - ✅ **#13 Example gallery** on the landing page (text-only at the time). - 🟡 **#12 study + redesign combined verb** — deferred. - 🟡 **#14 auto-generated OG cards** — deferred. --- ## v0.6.0 — Tracejam fixes + SaaS expansion + visual gallery ### What shipped 1. **Tracejam (test 05) defects fixed.** Horizontal scroll suppressed via `html/body { overflow-x: clip }`. Navbar items vertically centered with `align-items: center` and `line-height: 1`. Wordmark switched from Geist (body family) to Fraunces (`--font-wordmark`). Hero highlight raised from baseline to mid-x-height — the band now reads as a highlighter mark, not a fat underline. Browser-frame chrome dots got `aria-hidden="true"`. 2. **Three new slop-test gates** (now 38 total). Gate 36: no horizontal scroll on any viewport 320–1920 px. Gate 37: decorative effects on text must be visually verified to sit at x-height, not baseline. Gate 38: interactive bars must declare `align-items: center` + `line-height: 1`. 3. **Default-on microinteractions rule** in `microinteractions.md`. For Bento Grid, Stat-Led, Workbench, Marquee Hero, and Conversational FAQ archetypes, the skill now ships 2–3 small purposeful microinteractions automatically — number reveal on stats, pricing card lift, marquee scroll, stagger reveal — without the user asking. Default-off archetypes (Editorial, Manifesto, Letter, Quote-Led, Long Document) stay still. 4. **SaaS page sequence** in `macrostructures.md`. Hero → social proof → features → testimonials → pricing → FAQ → CTA → footer — when the macrostructure is SaaS-typical and the brief is B2B SaaS marketing. 5. **Wordmark guidance** in `typography.md`. The wordmark may (and on Bento / Stat-Led / Workbench / Marquee Hero, *should*) use a different display face than the body. Free pairings listed. 6. **Page-edge clipping discipline** in `layout-and-space.md`. Always pair clipped-edge enrichment with `html/body { overflow-x: clip }`. Use `clip` not `hidden` to preserve sticky positioning. 7. **Meridian Manifesto (test 04) extended** from 7 sections to 11. New sections: § What we refuse (anti-list with strikethrough), § Working rules (numbered operational principles), § The practice (3-paragraph narrative with drop-cap), § What we read (annotated bibliography). Voice consistent with the original manifesto; no testimonials, no pricing, no CTA. 8. **Two new SaaS-focused tests** demonstrating the new rules end-to-end: - **Test 07 — Foundry** (Stat-Led + Plain pure-white). Hero is one giant number ("847" — animated counter from 0). 9 sections including testimonials, real pricing tiers, FAQ. Pricing card hover-lift + recommended-tier pulse-once. **Theme deliberately departs from the warm-paper run** (Specimen, Atelier, Newsprint, Salon, Linen, Studio all sit in the cream-to-pink band) — Foundry is pure #ffffff, near-neutral cool greys, deep ink-blue accent, display-heavy Inter Tight + Bricolage Grotesque wordmark. Stark Klim-Type-Foundry-leaning B2B serious. - **Test 08 — Cohort** (Marquee Hero + Salon). Continuous-scroll marquee of course titles. Alternating-side feature rows with hand-built CSS visualisations. Stagger-reveal on testimonials. 9. **Real visual thumbnails on the example gallery.** `site/_tests/_thumbs/*.png` — eight 1024×640 PNG screenshots, one per test. Gallery cards now show a real preview above the text. Cards inherit theme tokens (radius, rule, shadow) so switching the landing page's theme reskins the card frames around the screenshots. 10. **README updates.** Slop-test count 35 → 38. New default-on microinteractions and SaaS-recipe bullets in "What's distinct." ### Skipped from this round - **#12 study + redesign combined verb** — still deferred. Single-shot screenshot-to-rebuilt-page workflow. - **#14 auto-generated OG cards** — still deferred. Needs Node + Puppeteer utility. ### What this round means for the skill The structural variety position holds across **eight** tests now, not six. The skill shipped its first two long-form pages (Foundry and Cohort) with proper SaaS structure — testimonials with role + company, real pricing, conversational FAQ — and they read distinctly per macrostructure, not just look distinct. The microinteractions are appropriate (counter, lift, marquee) and bounded to three primitives per page. The Tracejam regressions are gated against in three new slop-test questions. --- ## v0.6.0 — second pass · re-generated under the new disclosure layers The eight tests above are a re-generation of the original prompts under v0.6.0's three new disclosure layers — pre-flight scan (Step 0), project memory rotation (Step 2.5), and the upfront preview block (Step 5). They were produced as a single rotating session, so each pick takes the previous picks into account and the diversification rule fires across all eight. **Outcome:** every macrostructure unique, every theme unique, every pick measurably different from the original generation. The pre-flight + rotation + preview discipline is documented inside each `brief.md` so the user can read the skill's reasoning before scrolling to the page. The previous picks (which had Quote-Led/Atelier · Workbench/Terminal · Long Document/Linen · Manifesto/Manifesto · Bento Grid/Pastel · Long Document/Studio · Stat-Led/Plain · Marquee Hero/Salon) are preserved in the git history of this folder. ### Verb tests `_tests/verbs/` carries one worked example per verb (`audit`, `refine`, `redesign`, `study`) — see [`verbs/README.md`](verbs/README.md). These are not part of the gallery; they sit alongside as reference material for what each verb produces on a tiny realistic input. ## 2. Official Technical Reference & Guides (Nutlope/docs) # Mintlify Starter Kit Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including - Guide pages - Navigation - Customizations - API Reference pages - Use of popular components ### Development Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview the documentation changes locally. To install, use the following command ``` npm i mint ``` Run the following command at the root of your documentation (where docs.json is) ``` mint dev ``` ### Publishing Changes Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard. #### Troubleshooting - If the dev environment isn't running - Run `mint update` to ensure you have the most recent version of the CLI. - Page loads as a 404 - Make sure you are running in a folder with `docs.json`