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

> Master Hallmark best practices for generating high-quality HTML from briefs. Learn core verbs, macrostructure selection, and avoid direct HTML editing for optimal results. Unlock efficient web development.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-08-11

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification

The verb system is documented in the [README — Four verbs](https://github.com/Nutlope/hallmark/blob/main/README.md#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`](https://github.com/Nutlope/hallmark/blob/main/.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)](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/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
npx skills add nutlope/hallmark

```

This copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
hallmark redesign .

```

Hallmark ingests the target folder, extracts copy and information architecture, randomly selects macrostructure + theme, and writes a self-contained [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) with embedded CSS.

### Step 3: Iterate with Confidence

Re-run any verb for a fresh design fingerprint. The [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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:

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

```

This emits [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
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)](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)](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:

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

```

The [`site/_tests/`](https://github.com/Nutlope/hallmark/tree/main/site/_tests) folder contains examples of every macrostructure/theme combination for reference.

### Never Edit Generated HTML Directly

Changes to [`index.html`](https://github.com/Nutlope/hallmark/blob/main/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/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`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) file. The slop-test gates still enforce quality guarantees.

Example custom theme invocation:

```bash
hallmark redesign . --theme custom

```

## Critical Anti-Patterns to Avoid

The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core rule-set, all 57 slop-test gates, verb implementations |
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | 21 layout pattern definitions |
| `skills/hallmark/references/themes/` | 20 curated theme implementations |
| [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Custom mode specification format |
| [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Forbidden design patterns (gate 23 reference) |
| [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification. This separates content extraction from generation: you can feed [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) into subsequent `redesign` runs to apply the captured IA to completely new visual treatments.