# Hallmark Best Practices: How to Generate High-Quality HTML+CSS Pages with Nutlope's Design AI

> Discover Hallmark best practices for generating high-quality HTML+CSS pages with Nutlope's Design AI. Leverage core verbs audit, redesign, and study for optimal results.

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

---

**The best practices for using Hallmark center on leveraging its three core verbs (`audit`, `redesign`, `study`), avoiding anti-patterns by letting randomization produce unique fingerprints, and committing generated static assets while never editing HTML directly.**

Hallmark is an open-source **design skill** that generates fully-styled HTML+CSS pages from high-level briefs. According to the Nutlope/hallmark source code, its architecture revolves around **macrostructures**, **themes**, and **enrichment archetypes**—all guarded by a 57-check **slop-test** gate system that eliminates the "AI-generated look."

## Understanding Hallmark's Core Architecture

Before running commands, grasp how Hallmark assembles pages. The system operates on three interconnected layers defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

### Verbs Drive Distinct Workflows

Hallmark exposes three CLI entry points, each serving a specific purpose:

- **`hallmark audit`** – Scores existing code against 57 quality checks (gate 23 in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) references [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md))
- **`hallmark redesign`** – Rebuilds a page from existing copy/IA with a fresh macrostructure+theme combo
- **`hallmark study`** – Extracts design DNA from a live URL and emits a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) spec

Each verb writes to a per-project log at [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to prevent repeat combinations.

### Macrostructures Define Layout Skeletons

Hallmark selects from **21 macrostructures**—including *Long Document*, *Quote-Led*, and *Bento Grid*—documented in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Selection is randomized per run, ensuring no two outputs share the same layout fingerprint.

### Themes Supply Visual Identity

Twenty curated themes (*Linen*, *Cobalt*, *Carnival*) live in `skills/hallmark/references/themes/`. Themes assign color palettes, typography scales, and visual accents. The **Terminal** theme appears in the *Streampipe* recipe as an example of explicit theme selection overriding randomization.

### Enrichment Tiers Add Polish

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

| Tier | Description |
|------|-------------|
| **Tier-A** | Rich SVG art and decorative elements |
| **Tier-B** | Moderate visual enhancement |
| **Tier-C** | Plain typographic layout |

The **slop-test gate system** determines the appropriate tier through 57 quality checks that enforce layout integrity and prevent generic AI aesthetics.

## Installing and Running Hallmark

### Installation

Pull Hallmark into Claude Code, Cursor, or Codex environments with a single command. This copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and all reference assets to the user directory.

```bash
npx skills add nutlope/hallmark

```

Re-run this command to update when new themes or macrostructures release.

### Running Your First Verb

Generate a new landing page from an existing project:

```bash
hallmark redesign .

```

This ingests the target folder, extracts copy and information architecture, picks a random macrostructure+theme combo, and writes a self-contained HTML+CSS site.

### Auditing Existing Code

Surface anti-patterns and accessibility gaps before editing legacy sites:

```bash
hallmark audit ./my-old-site

```

The audit references [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) (gate 23 in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)) to flag problematic patterns.

### Studying Live URLs for Inspiration

Extract portable design specifications from live sites:

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

```

This emits [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)—feed it back into `hallmark redesign` to preserve copy/IA while applying a completely new visual treatment.

## Critical Hallmark Best Practices

### Never Copy Recipes Verbatim

The [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) file contains canonical briefs illustrating expected outputs. Use these as **learning references**, not templates. Each `hallmark` run should produce a *new* design fingerprint. Deliberate randomization is a core feature, not a bug.

### Commit Generated Assets, Never Edit Them Directly

Hallmark outputs pure HTML+CSS—treat results as first-class static assets:

```bash

# Add generated tests to version control

git add site/_tests/*

```

**Never edit generated HTML directly.** Changes overwrite on subsequent runs. Instead, modify the brief or create a **custom theme**.

### Leverage Custom-Theme Mode for Brand Alignment

When catalog themes cannot express your brief, Hallmark falls back to **Custom** mode. Define bespoke palettes, typography, and layouts in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) while retaining full slop-test enforcement.

### Maintain the Per-Project Log

Hallmark stores execution history in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to prevent macrostructure+theme repetition. Preserve this file in version control to maintain design variety across team members.

## Key Files for Deep Dives

| 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 |
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | 21 layout skeletons |
| `skills/hallmark/references/themes/` | 20 curated visual systems |
| [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Bespoke theme authoring guide |
| [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Design pitfalls to avoid |
| [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) | Canonical workflow examples |

## Summary

- **Run `hallmark audit`** before touching existing code to catch anti-patterns early
- **Use `hallmark study`** to extract portable design specs from live URLs
- **Let randomization work**—don't force repeat macrostructure+theme combinations
- **Commit [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)** and generated `site/_tests/*` to version control
- **Edit briefs and custom themes**, never generated HTML directly
- **Re-run `npx skills add nutlope/hallmark`** to receive new themes and macrostructures

## Frequently Asked Questions

### What makes Hallmark different from other AI design tools?

Hallmark's **slop-test gate system** runs 57 quality checks ensuring every output avoids the generic "AI-generated look." The deliberate randomization of macrostructures and themes—tracked via [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)—guarantees unique fingerprints per run, unlike template-driven generators.

### Can I force Hallmark to use a specific theme or layout?

Yes. While Hallmark defaults to random selection, you can reference themes explicitly. The *Streampipe* recipe in [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) demonstrates requesting the **Terminal** theme directly. For complete control, use **Custom** mode defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md).

### Why does Hallmark prevent editing generated HTML?

Direct HTML edits violate Hallmark's reproducible workflow. The tool regenerates files on every verb execution, overwriting manual changes. The correct extension point is the **brief** (input specification) or **custom theme** (visual system), both of which Hallmark merges with its randomization engine while preserving slop-test guarantees.

### How do I update Hallmark when new features release?

Re-run the installation command: `npx skills add nutlope/hallmark`. This pulls the latest [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), macrostructures, themes, and enrichment tiers without modifying your existing project logs or generated assets.