Open Source Project #249: Hallmark — A Design Skill That Refuses to Look AI-Generated, Built on 48 Material Themes and a Browser Linter

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

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
• 💻 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

# 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.

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:

node skills/hallmark/scripts/sloplint.mjs <file-or-dir> --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

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:

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.

/* 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:

node <skill-dir>/scripts/theme.mjs deal --genre <genre> --prompt "<the 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:

node <skill-dir>/scripts/theme.mjs draw --material photo|product|words --job <job> --theme <slug>

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:

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 <slug> 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
• 🌐 Website and all themes: 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

Related

• Together AI (the maker): 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 — curated AI agent and skill tools, each validated in real workflows. No hype, just tools that actually work.

Visit my homepage for more insights and interesting products.