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

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.

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 references 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 spec

Each verb writes to a per-project log at .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. 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 and all reference assets to the user directory.

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:

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:

hallmark audit ./my-old-site

The audit references skills/hallmark/references/anti-patterns.md (gate 23 in SKILL.md) to flag problematic patterns.

Studying Live URLs for Inspiration

Extract portable design specifications from live sites:

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

This emits 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 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:

# 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 while retaining full slop-test enforcement.

Maintain the Per-Project Log

Hallmark stores execution history in .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	Core rule-set, all 57 slop-test gates
skills/hallmark/references/macrostructures.md	21 layout skeletons
skills/hallmark/references/themes/	20 curated visual systems
skills/hallmark/references/custom-theme.md	Bespoke theme authoring guide
skills/hallmark/references/anti-patterns.md	Design pitfalls to avoid
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 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—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 demonstrates requesting the Terminal theme directly. For complete control, use Custom mode defined in 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, macrostructures, themes, and enrichment tiers without modifying your existing project logs or generated assets.

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