Hallmark Best Practices: A Complete Guide to Generating High-Quality HTML Pages from Briefs

Use the three core verbs (audit, redesign, study), let Hallmark randomly select macrostructures and themes, and never edit generated HTML directly.

Hallmark is an open-source design skill from Nutlope/hallmark that transforms high-level briefs into fully-styled HTML + CSS pages. Its architecture centers on verbs, macrostructures, themes, and slop-test gates—a 57-check quality system that prevents generic AI-generated looks. This guide covers the exact workflow, recommended practices, and anti-patterns to avoid based on the source code in skills/hallmark/SKILL.md.

Understanding Hallmark's Core Architecture

Hallmark generates pages through four interconnected systems. Knowing how they interact is essential for effective use.

Verbs: The Three Entry Points

Hallmark exposes three CLI verbs in bin/hallmark.js. Each triggers a distinct workflow:

• hallmark audit <target> — Scores existing code for anti-patterns, accessibility gaps, and semantic markup issues
• hallmark redesign <target> — Rebuilds a page from extracted copy/IA using a fresh macrostructure + theme combination
• hallmark study <url> — Extracts design DNA from a live URL and emits a portable design.md specification

The verb system is documented in the README — Four verbs section.

Macrostructures: The Layout Foundation

Hallmark selects from 21 macrostructures that define page architecture. Options include Long Document, Quote-Led, Bento Grid, and Feature Cascade. The selection is randomized per run, with .hallmark/log.json preventing repeat combinations for the same project.

These structures live in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md).

Themes: Visual Identity Systems

Twenty curated themes supply color palettes, typography, and accents. Examples include Linen, Cobalt, Carnival, and Terminal (used in the Streampipe recipe). Like macrostructures, themes are randomly assigned unless explicitly requested via custom-theme mode.

Browse all themes in the references/themes/ folder.

Enrichment Archetypes and Slop-Test Gates

After macrostructure and theme selection, Hallmark applies an enrichment tier:

Tier	Description
Tier A	Rich SVG art, layered backgrounds, advanced effects
Tier B	Moderate visual enhancement with balanced whitespace
Tier C	Clean typographic layout, minimal decoration

The slop-test gate system (57 quality checks in SKILL.md) selects the appropriate tier while guaranteeing layout integrity and blocking AI-generated visual clichés.

Installation and Basic Workflow

Step 1: Install Hallmark

Pull the skill into Claude Code, Cursor, or Codex environments:

npx skills add nutlope/hallmark

This copies SKILL.md, all reference assets, and verb binaries to your environment. Re-run this command to update when new themes or macrostructures release.

Step 2: Execute Your First Verb

Generate a new landing page from an existing project:

hallmark redesign .

Hallmark ingests the target folder, extracts copy and information architecture, randomly selects macrostructure + theme, and writes a self-contained index.html with embedded CSS.

Step 3: Iterate with Confidence

Re-run any verb for a fresh design fingerprint. The .hallmark/log.json prevents macrostructure/theme repetition within the same project.

Step 4: Extract Design DNA with study

Bootstrap from inspiration sites without copying verbatim:

hallmark study https://www.usehallmark.com/examples/tally/

This emits design.md—a portable specification you can feed into hallmark redesign for completely new styling while preserving original copy and IA.

Essential Hallmark Best Practices

Always Run audit Before Editing Legacy Code

Surface anti-patterns and accessibility issues upfront:

hallmark audit ./my-old-site

The audit verb checks against 57 gates including semantic HTML structure, color contrast, and animation performance. Results reference specific anti-pattern IDs from [skills/hallmark/references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md).

Leverage the Recipe Collection

The [docs/recipes.md](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) file contains canonical briefs that demonstrate complete workflows. Study these before creating custom briefs—they show expected output structure and brief formatting.

Commit Generated Sites as Static Assets

Hallmark outputs pure HTML + CSS with no build step. Treat results as first-class static assets:

git add site/_tests/*
git commit -m "Add Hallmark-generated landing page variants"

The site/_tests/ folder contains examples of every macrostructure/theme combination for reference.

Never Edit Generated HTML Directly

Changes to index.html will be overwritten on the next verb execution. Instead:

• Modify the brief content in your source files
• Adjust styling through [custom-theme.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)
• Re-run hallmark redesign to regenerate

Use Custom-Theme Mode for Brand-Specific Looks

When catalog themes cannot express your brief, Hallmark falls back to Custom mode. Define bespoke palettes, typography, and layout rules in a custom-theme.md file. The slop-test gates still enforce quality guarantees.

Example custom theme invocation:

hallmark redesign . --theme custom

Critical Anti-Patterns to Avoid

The SKILL.md file defines specific anti-patterns (gate 23). Hallmark actively prevents these, but understanding them improves brief quality:

• Copying recipes verbatim — Each run should produce a unique fingerprint; reuse brief structure, not exact output
• Forcing specific macrostructures — Random selection ensures design diversity; override only when IA strictly requires a particular layout
• Ignoring enrichment tier boundaries — Don't manually bump tiers; let slop-test gates determine appropriate visual complexity
• Hand-editing generated CSS — Breaks reproducibility; use custom-theme mode instead

Key Source Files Reference

File	Purpose
skills/hallmark/SKILL.md	Core rule-set, all 57 slop-test gates, verb implementations
skills/hallmark/references/macrostructures.md	21 layout pattern definitions
skills/hallmark/references/themes/	20 curated theme implementations
skills/hallmark/references/custom-theme.md	Custom mode specification format
skills/hallmark/references/anti-patterns.md	Forbidden design patterns (gate 23 reference)
docs/recipes.md	Workflow demonstrations and brief templates
site/_tests/	Generated output examples for every combination

Summary

• Install once with npx skills add nutlope/hallmark, then update regularly
• Master three verbs: audit for quality checks, redesign for fresh pages, study for design DNA extraction
• Trust randomization: Macrostructure and theme selection produces unique, non-repeating outputs per project
• Respect the slop-test gates: All 57 quality checks run automatically; don't circumvent them
• Use custom-theme mode for brand-specific looks while maintaining quality guarantees
• Never edit generated HTML: Modify briefs or themes, then regenerate

Frequently Asked Questions

What makes Hallmark different from other AI site generators?

Hallmark enforces 57 slop-test gates that block generic AI visual patterns. Unlike tools that produce identical-looking outputs, Hallmark randomizes macrostructure and theme selection per run, with .hallmark/log.json preventing repetition. The result is genuinely unique pages from the same brief.

How do I prevent Hallmark from repeating the same design?

Hallmark automatically prevents this. The .hallmark/log.json file tracks used macrostructure/theme combinations per project. To force a fresh look, simply re-run hallmark redesign .—the system will select an unused combination if available, or cycle through the full 420+ possible pairings.

Can I use Hallmark with my existing brand colors and fonts?

Yes, via custom-theme mode. Create a custom-theme.md file specifying your palette, typography, and layout preferences, then run hallmark redesign . --theme custom. All 57 slop-test gates still apply, ensuring quality output with your brand identity.

Why does hallmark study output a markdown file instead of HTML?

The study verb extracts design DNA—macrostructure, theme characteristics, and typographic patterns—into a portable design.md specification. This separates content extraction from generation: you can feed design.md into subsequent redesign runs to apply the captured IA to completely new visual treatments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}