## Introduction > Making AI-generated pages look human-made is less about what to add and more about what to refuse. This is **article 249** in the "One Open Source Project a Day" series. Today's project is **Hallmark** (Nutlope/hallmark). You've seen the page: a small all-caps "eyebrow" above every heading, one word in a headline painted with a gradient, cards inside cards, an email sign-up band at the bottom, and a form that says thanks without sending anything. These aren't one model's quirks. They're the defaults almost every coding assistant falls into when left unconstrained. Hallmark's position is clear: **it is a skill that makes the UIs a coding assistant generates look made, not generated.** It doesn't teach the model taste. It writes the tells of machine-made pages down as rules, then checks for them with tools. ### What You'll Learn - What problem Hallmark solves, and why it chooses constraints over prompt polishing - The design of the Floor / Reflex / Finish tiers - The "deal" mechanism: 48 themes, pick one of three, and a log that keeps consecutive builds from converging - How sloplint inspects pages in a real browser, and what the fresh-context review adds - How the redesign and audit verbs avoid losing content and wiring - Where it fits and where it doesn't ### Prerequisites - You've used a coding assistant such as Claude Code, Codex or Cursor and know what a skill is - Basic HTML and CSS; familiarity with `:focus-visible` and `prefers-reduced-motion` helps - Interest in putting quality gates on AI output --- ## Project Background ### Overview Hallmark is a design skill for Claude Code, Codex CLI, Cursor and OpenCode. The README sums it up: it holds a hard floor and then gets out of the way; deals three themes from a catalog of 48 materials; builds the page around what the visitor came to do; lints the result in a real browser against the tells of machine-made pages; and a fresh-context reviewer gets the last word. The tells it checks for include: - An eyebrow above every heading - Tracked-capital labels - One coloured word in a headline - A page of empty frames, or nothing but photographs - A hero that misses its screen - An email sign-up at the end of every page - A form that says thanks without sending anything ### Author and Team - Made by Together AI (the README says "Made by Together AI") - Repo owner: Nutlope, i.e. Hassan El Mghari, with about 8.8k GitHub followers and 111 public repos - Created: 2026-04-27; currently v2.0.0 - Website: [usehallmark.com](https://www.usehallmark.com) ### Project Data As of GitHub on 2026-10-27; treat as a snapshot: - ⭐ GitHub Stars: ~37,900 - 🍴 Forks: ~1,970 - 📦 Version: v2.0.0 (as stamped in SKILL.md) - 📄 License: MIT (photos in the library keep their own licences) - 🌐 Website: [usehallmark.com](https://www.usehallmark.com) - 💻 Languages: CSS, HTML, JavaScript, Python, TypeScript (the CSS/HTML mass comes largely from the site and test fixtures) --- ## Main Features ### What It Does In one page build Hallmark does four things: 1. **Pre-flight**: reads the project's fonts, palette, framework and any locked `design.md`, and asks once for the material it needs 2. **Deal**: offers three themes from 48 and picks one, then deals the page's anatomy from its job 3. **Hero first**: builds only the nav and hero, renders it, and has it reviewed cold before the rest exists 4. **Sweep**: `sloplint --render` checks the page at eight widths, then a subagent reviews it with fresh eyes The output is self-contained HTML and CSS, stamped in its first CSS comment with the decisions it took. ### Use Cases 1. **A new landing or marketing page from scratch** - Give a one-line prompt; the assistant deals and builds instead of reaching for a generic template 2. **A health check on an existing page** - `/hallmark audit ./index.html` reports only and changes nothing 3. **Redesign that keeps content and wiring** - `/hallmark redesign ./src/app` keeps the content and the wiring and changes the system and layout 4. **A quality gate for a team's UI output** - Run `sloplint` standalone on any page or directory, or wire it into an edit-time hook 5. **A custom look** - Say custom and Hallmark drops the themes, keeping only the floor and the gates, to find the one idea only this client has ### Quick Start ```bash # Install for every project (leave off -g to install into the current one) npx skills add nutlope/hallmark -g # One harness only npx skills add nutlope/hallmark -g --agent claude-code ``` Needs Node 18 or later. The browser checks (`sloplint --render`, screenshots) also need `npm i -g puppeteer-core` and Chrome; without them the static checks still run. | Harness | Lands in | Invoke | | --- | --- | --- | | Claude Code | `~/.claude/skills/hallmark` | `/hallmark ` or describe a new build | | Codex CLI | `~/.agents/skills/hallmark` | `$hallmark ` | | Cursor | finds the copies above | `/hallmark ` | | OpenCode | finds the copies above | `/hallmark ` | Or as a Claude Code plugin: ``` /plugin marketplace add nutlope/hallmark /plugin install hallmark@hallmark ``` If it does not fire on its own, name it: *use hallmark to build ...*. To lint any page by itself: ```bash node skills/hallmark/scripts/sloplint.mjs --render ``` ### Core Features 1. **48 material themes** - Each is a material (paper, type, colour, surfaces, its own components and texture) with a picture of a finished page, in one file of at most 8 KB 2. **Pages built from the job** - A booking page books, a shop sells, a newsletter subscribes: the action sits where the category puts it, and the page ends on it 3. **Real product screenshots** - Point it at a URL, a dev server or an app and it captures the screenshots itself instead of drawing a fake product window 4. **755 openly licensed photos** - Picked per subject and credited on the page, from Wikimedia Commons; no Unsplash, Pexels or other sites whose terms bar AI tools from picking images 5. **Redesign and audit** - The first rebuilds while keeping content and wiring; the second only reports 6. **Three tiers of rules** - Floor never ships, Reflex can be waived on the record, Finish never blocks ### Advantages | Aspect | Hallmark | Asking an assistant directly | Generic frontend template | |:---|:---|:---|:---| | Convergence | Deal plus log keeps consecutive builds apart | Model defaults repeat | Everyone shares one look | | Quality checks | Measures contrast, focus rings and the fold in a browser | Eyeballing or after-the-fact feedback | None | | Honesty of content | No invented metrics, quotes or logos | Often invents them | Placeholder copy | | Redesign safety | Records every link and field first; a loss fails the redesign | Easy to drop wiring | Not applicable | **Why look at it?** - It breaks the subjective "is this well designed?" into concrete rules a machine can check - The rules are tiered: it admits not every rule should bind equally, while keeping a floor that never bends - For any skill author who wants quality gates on AI output, it is a complete reference implementation --- ## Deep Dive ### Three Tiers: Floor, Reflex, Finish This is the project's skeleton. In `gates.md` every gate carries a **tier**, which says whether you may disagree with it: | Tier | Meaning | Handling | |---|---|---| | **Floor** | No admired page breaks it on purpose (correctness, access, honesty, the bans), or it is a house rule where Hallmark is stricter than the field | Never waivable; a `FAIL` means nothing ships | | **Reflex** | A default a language model falls into | May be waived on the record with a real reason; past three waivers sloplint notes a house style, which belongs in a `design.md` | | **Finish** | Craft detail invisible at arm's length | Reported and answered, never blocking | | **Ledger** | Bookkeeping about repetition | Reports at `NOTE`, never counts toward the verdict | The Floor has 16 rules, for example: - Every colour and font goes through a token declared at `:root`; no literal colour or `font-family` past the token block - Never `transition: all`; never animate `width`, `height`, `top` or `left` - Never one italic word inside a roman heading - Every interactive element has `:focus-visible`, appearing instantly - Every animation has a `prefers-reduced-motion: reduce` fallback, and content is visible with scripting off - **Never an invented metric, testimonial, logo wall or case-study count** - **Never an eyebrow, and never a label in tracked capitals** - Never middle-dot-joined meta strings, arrows glued to link text, or decorative status dots - Never a purple-to-blue gradient, a card inside a card, an emoji as an icon, or a hand-drawn browser or OS window - About 80 words on any one screen; the hero's text is the headline, one sentence and its actions A few are explicitly marked house rules: the eyebrow (54), the screen budget (58), template punctuation (63) and tracked capitals (67). The idea is that these are the most reliable signs of machine-made pages, so Hallmark is stricter than the field. A waiver goes in the CSS stamp with three fields: the gate, the guard evidence, the reason. ```css /* Hallmark · waive 47b · one frame, a real terminal capture inside · the terminal is the product being sold */ ``` A waiver naming a Floor gate is rejected and the gate fires. **sloplint re-derives the guard**, so a build that cannot state its guard usually finds it does not hold. One more detail: retired gate numbers (5, 13, 14, 21 and others) are never reused, so an older stamp still reads. ### The Deal: A Log That Prevents Convergence How do you keep consecutive builds from looking alike? Hallmark deals: ```bash node /scripts/theme.mjs deal --genre --prompt "" [--log .hallmark/log.json] ``` It offers three themes from 48 that fit the prompt and clear the recent log. The assistant looks at the three pictures, picks the one whose material can carry the prompt (motion, photographs, code), and says why. Once a theme is picked, `draw` runs: ```bash node /scripts/theme.mjs draw --material photo|product|words --job --theme ``` It deals the page's shape, the hero posture, the nav, the footer, the first section, where the action sits, two compositions to leave out, and what the hero leads with. The README puts the design in one line: **a theme is a material, not a plan.** It never says what a page contains or in what order, so two prompts in one theme make two different pages. There is also a "mirror test": would a neighbouring prompt in the same category get this exact combination? If yes, change one decision and say which. Every build writes `.hallmark/log.json` with fields such as `shape`, `theme`, `hero`, `nav`, `footer`, `photos`, `signature`, `waived` and `fingerprint`, which the next deal reads and avoids. ### What a Theme Looks Like Take Dusk (money software for bank reconciliation). A theme file starts with metadata: ```yaml name: Dusk slug: dusk genre: modern-minimal paper: dark 17.5 268 display: grotesk-sans Wix Madefor Display accent: cool 274 posture: committed keywords: treasury, banking, fintech, payments, reconciliation, ledger, ... ``` `keywords` is what the deal matches against the prompt. The body describes the material: "money software at the calm end of the day", with a real photograph of land at dusk behind the hero, the head set dark on its palest part, and the product beside it in smoked glass with a lit top edge. Below, the page turns to slate and light surfaces become bone wells. Then come the full tokens (in `oklch`) and three dials: two Dusk pages in one run must differ on at least two of them. All 48 themes follow a similar format, from `almanac`, `arcade` and `atelier` to `terminal`, `vellum` and `werkstatt`. ### The Build: Hero First, Then the Rest `SKILL.md` splits the flow into 7 steps. Key constraints: - **Ask once**: material, audience, use, tone. "Clean and modern" is not a tone; pick an extreme (editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere) - **Facts are never inferred**: a number, quote or logo not given is absent; a picture not given is a stand-in from the library - **Hero first**: write the nav and hero only, run `sloplint --stage hero`, get a fresh-context review, and only then build the sections - **One idea per screen, set big**: headline of seven words or fewer, one sentence of twelve words or fewer, six to nine sections, 450 visible words at most, photographs at most a third of the page below the hero - **Start from the scaffold**: `theme.mjs scaffold ` writes `tokens.css` and `base.css`; the assistant writes only the page - **Existing stylesheets are append-only**: imports go right after the last `@import`; reuse the project's token names The "signature" idea is a good one: each page needs the one thing a visitor would remember, the prompt's strongest real thing shown at its best (the photograph that is the place, the product doing its one job), shown on the first screen and named in the Picks block and the stamp. ### Review: sloplint Plus a Fresh Context Verification has two layers. **sloplint** is a zero-dependency script (`sloplint.mjs` is about 230 KB, the render tier `sloplint-render.mjs` about 99 KB) that reads HTML, CSS, framework components and Tailwind classes. With `--render` it measures in a real browser: - The fold at three widths - Contrast against the pixels behind the text - Focus rings found by tabbing - Section rhythm and the share of the page in photographs - Heads crowding what precedes them - Text cramped against its box or painted under another element Each gate reports as `FAIL`, `REFLEX`, `WAIVED`, `WARN`, `ANSWERED` or `NOTE`. The second layer is the **fresh-context review**: a subagent that did not watch the build reads only the review prompt and the finished page, and returns a first word (`recapture`, `rebuild`, `fix` or `ship`). SKILL.md says the reviewer reads its prompt and "you never open `review-*.md`", so the builder can't write to the rubric. The builder reports the outcome on the last row of the Picks block, for example `Floor 0 FAIL · Reflex 2 (1 waived: 47b) · finish-review: subagent, 3 resolved`. The docs include the line: **a fabricated pass is itself slop.** ### Redesign: Record First, Rebuild, Fail if Anything Is Lost Redesign is the most safety-engineered part. Hallmark only touches an existing design when you name it: ``` /hallmark redesign ./src/app /hallmark audit ./index.html ``` A full redesign keeps the content and the wiring and changes the system and layout; say *keep the layout* for a restyle or *polish* for only the tells. Mechanically: - `sloplint --before` records every link, field, handler and heading first - `sloplint --kept` compares afterwards and **fails the redesign** if one went missing - The handoff is a side-by-side before and after SKILL.md also says that in an existing project you name the files you will touch first, and never delete a route or a component tree without a file-level plan the user approved. ### Honesty About Images Hallmark is restrained about images: - User pictures first, then screenshots of the real product (`scripts/capture.mjs`), then the product built at full fidelity only when it can't be reached, and finally library photographs - The photo library `photos.json` (about 450 KB) lists photographs hosted on Wikimedia Commons and **holds no image files**; each keeps its own licence (CC0, public domain, CC BY or CC BY-SA) and is credited in the footer - Banned: stock-site URLs, drawn illustrations, empty washes, rows of counting marks, invented figures ### Evaluation: The eval Directory The `eval/` directory holds an evaluation harness: `briefs.json` (test briefs), `run-matrix.py`, `judge.py`, `score.mjs`, `report.mjs` and `index.html`, for generating pages across models and harnesses, screenshotting, scoring and reporting. The ROADMAP also admits that "run the same brief and redesign through Claude Code, `codex exec` and OpenCode and assert each reaches 0 FAIL" is still on the Now list. ### Worth Noting in the Roadmap The ROADMAP lists the author's own judgment: - **Cream or off-white paper, pill-shaped buttons, near-black with one acid accent and the hairline broadsheet now read as generated looks.** Custom runs already treat them as spent; the catalog needs a decision on whether to keep them as deliberate materials dealt only on their keywords, or re-paper and re-shape those themes - Future work includes theme-aware motion tokens, multi-page coherence (lock the brand axes, vary the page-voice axes), a brand-first flow, the edit-time hook on by default, and deeper app-screen checks That shows the author chasing the drift of "AI slop" itself: today's anti-pattern can become tomorrow's pattern. --- ## Scope and Limits - **For new builds, or by name**: SKILL.md says never use it on an existing design unless the user names Hallmark; any other change should be done in the project's own system - **Strongly opinionated**: many strict rules, such as no eyebrows and no tracked capitals; if your brand relies on those, lock your system in a `design.md`, and Floor rules cannot be waived - **Browser checks need extra dependencies**: `puppeteer-core` and Chrome; without them only the static checks run - **Cross-harness conformance is still being verified**: it is on the ROADMAP's Now list - **Cost**: pre-flight, hero-first, two reviews and several sloplint render passes mean a build is not cheap; the ROADMAP has a "measure a build" task, and SKILL.md offers a fast mode for quick, rough or prototype work - **Photo library limits**: sourced from Wikimedia Commons, so subjects and styles are limited, and each photo must be credited on the page --- ## Links and Resources ### Official - 🌟 **GitHub**: [https://github.com/Nutlope/hallmark](https://github.com/Nutlope/hallmark) - 🌐 **Website and all themes**: [https://www.usehallmark.com](https://www.usehallmark.com) - 📚 **Rules**: `skills/hallmark/references/gates.md` in the repo - 🗺️ **Roadmap**: `ROADMAP.md` in the repo - 🐛 **Issues**: [https://github.com/Nutlope/hallmark/issues](https://github.com/Nutlope/hallmark/issues) ### Related - Together AI (the maker): [together.ai](https://www.together.ai) - Evaluation suite: `eval/README.md` in the repo --- ## Summary and Outlook ### Key Takeaways 1. **Constraints beat prompt polishing**: breaking "AI slop" into rules you can check one by one, then checking them with tools, is far more reliable than telling the model to "have taste" 2. **Three tiers of rules**: Floor never bends, Reflex can be waived on the record, Finish only reports; a hard floor without rigidity 3. **Dealing prevents convergence**: 48 themes plus a log keep consecutive builds apart, and "a theme is a material, not a plan" 4. **Two-layer verification**: sloplint measures in a real browser, then a fresh-context reviewer judges, and the builder never sees the rubric 5. **Redesign provably loses nothing**: every link and field is recorded first, and losing one fails the run ### Who It's For - Developers and indie makers who often ask AI to generate landing pages and product sites and are tired of samey results - Skill authors who want quality gates on their own skills and could borrow the "tiered rules, machine checks, independent review" structure - Frontend engineers, who can use sloplint on its own as a page-quality checker ### Suggestions Start with `/hallmark audit` on an existing page to see what it flags and get a feel for the strictness; then run a small build end to end and read the Picks block at the end. If you have brand guidelines, lock the system in a `design.md` first. --- *Explore [PrimeSkills](https://primeskills.store) — curated AI agent and skill tools, each validated in real workflows. No hype, just tools that actually work.* *Visit my [homepage](https://home.wonlab.top/en) for more insights and interesting products.*

DeepSeek Harness Series (04): Agent Loop — How a Conversation Turn Actually Runs