How to Use Hallmark to Generate UI for AI Coding Assistants

Hallmark is a design skill that AI coding assistants invoke to build production-ready interfaces that look intentionally crafted rather than AI-generated, enforced through a 58-gate anti-slop checklist and strict diversification rules.

Hallmark transforms how Claude Code, Cursor, and Codex approach UI generation by treating design as a disciplined craft rather than a creative guess. Located in the Nutlope/hallmark repository, this skill system forces assistants to follow architectural rigor—from pre-flight scans to post-build slop-testing—ensuring every output avoids the visual clichés typical of AI-generated code. The entire workflow is defined in skills/hallmark/SKILL.md and operates through four primary verbs that guide the assistant from concept to production-ready HTML or React components.

Installing Hallmark for Claude Code, Cursor, and Codex

To enable Hallmark in your AI coding assistant environment, install it as a skill using the package manager.

npx skills add nutlope/hallmark

Once installed, the assistant recognizes the hallmark command family and automatically loads the reference files located in skills/hallmark/references/. These files contain the macrostructure definitions, theme catalogs, and anti-pattern rules that constrain the generation process.

The Four Core Verbs

Hallmark exposes four distinct operations, each serving a different point in the development lifecycle. The assistant selects the appropriate verb based on your request.

Default (Generate Fresh UI)

The root hallmark verb builds a new interface from a brief. This triggers the full 9-step architectural flow: pre-flight scan, genre detection, macrostructure selection, theme routing, and the 58-gate slop-test validation.

hallmark

When invoked, the system reads existing project signals from .hallmark/preflight.json, selects a diversification-compliant macrostructure from references/macrostructures.md, and applies a catalog theme (such as Hum, Cobalt, or Bloom) or custom OKLCH palette. The final output includes a stamped comment containing the macrostructure name, genre, theme, and slop-test scores.

Audit (Score Existing Code)

Use hallmark audit to evaluate existing markup against the anti-pattern list without modifying files. This command runs the slop-test gates against the target and returns a report highlighting invented metrics, chrome leakage, or typographic violations.

hallmark audit ./site/index.html

The audit references references/anti-patterns.md and references/slop-test.md to score the input against 58 specific design discipline gates.

Redesign (Visual Refresh)

The hallmark redesign verb preserves information architecture, copy, and brand identity while rebuilding the visual layer. It accepts an optional --mood flag to force a specific genre.

hallmark redesign ./components/Button.tsx --mood modern-minimal

This command is ideal for refactoring legacy components to meet Hallmark's token-driven standards without rewriting business logic.

Study (Extract Design DNA)

The hallmark study verb analyzes screenshots or live URLs to extract structural and stylistic DNA—macrostructure type, color anchors, font pairings, and spacing scales. It can optionally emit a portable design.md file for reuse across projects.

hallmark study https://www.usehallmark.com/examples/hum-07/

After extraction, subsequent hallmark default runs automatically adopt the studied DNA, ensuring visual continuity with the analyzed reference.

The 9-Step Architectural Flow

Every default Hallmark invocation follows a rigid sequence documented in skills/hallmark/SKILL.md. This pipeline ensures diversification and prevents the repetitive layouts common in AI-generated UI.

1. Pre-flight Scan

The assistant reads existing project signals—design.md, font stacks, motion libraries, and framework choices—and records them in .hallmark/preflight.json. This prevents visual discontinuity with established codebases.

2. Genre Detection

Based on brief signals, the system selects one of four genres defined in references/genres/: editorial, modern-minimal, atmospheric, or playful. Each genre file contains specific voice and styling constraints.

3. Macrostructure Pick

Hallmark selects a named macrostructure from the slim index in references/macrostructures.md (e.g., 05-workbench.md). Diversification rules in .hallmark/log.json force the selection to differ from recent runs, ensuring structural variety across iterations.

4. Theme Route

The system chooses between three theme paths:

• Catalog: One of 21 predefined themes (e.g., Bloom, Hum)
• Custom: A tuned OKLCH palette and free-font pairing for bespoke requests
• Studied-DNA: The palette and structure extracted via hallmark study

The theme must differ on at least one of three axes (paper band, display style, accent hue) from the previous project entry.

5. Load Visual Ruleset

The assistant eagerly loads the selected genre file, theme specification, and universal references: typography.md, color.md, layout-and-space.md, motion.md, copy.md, and anti-patterns.md. Component-specific files load only when needed.

6. Hero Enrichment Decision

Using references/hero-enrichment.md, the system determines whether the design requires hero illustrations, video backgrounds, or CSS art. If no enrichment signals are present, it defaults to typography-only hero sections.

7. Preview Summary

Before generating code, Hallmark emits a markdown preview listing the selected macrostructure, theme, enrichment strategy, sections, motion language, and diversification notes. This allows for human review of the design direction.

8. Build and Slop-Test

The assistant generates HTML/CSS or framework-specific components, then runs the 58-gate slop-test defined in references/slop-test.md. Any gate scoring below 3 triggers an automatic revision pass. Successful builds receive a stamped comment containing the design parameters and slop scores.

9. Project Memory Update

The system writes the new macrostructure and theme choices to .hallmark/log.json, enforcing diversification constraints on subsequent invocations.

Understanding the Slop-Test Gates

The slop-test is Hallmark's quality enforcement mechanism. Located in references/slop-test.md, it contains 58 specific anti-patterns that distinguish "made" design from "AI-generated slop." Gates include prohibitions on italic headers, fabricated metrics (e.g., "trusted by 10,000+ teams"), fake browser chrome, and undifferentiated card grids.

Each gate scores from 1 to 5. If any gate falls below 3, the build fails and the assistant must revise. This ensures outputs never leak the telltale signs of LLM generation, such as generic testimonials or placeholder-influenced layouts.

Key Reference Files in the Hallmark Repository

The following files constitute the Hallmark design engine and are referenced by the assistant during each invocation:

• skills/hallmark/SKILL.md — Core skill definition and verb table
• skills/hallmark/references/slop-test.md — 58-gate quality checklist
• skills/hallmark/references/macrostructures.md — Index of 21 structural layouts
• skills/hallmark/references/macrostructures/XX-<name>.md — Individual macrostructure specifications (e.g., 05-workbench.md)
• skills/hallmark/references/themes/<theme>.md — Catalog theme definitions
• skills/hallmark/references/genres/<genre>.md — Editorial, modern-minimal, atmospheric, and playful genre rules
• skills/hallmark/references/hero-enrichment.md — Decision tree for media vs. typography heroes
• site/css/tokens.css — Universal design token definitions (--color-accent, --font-display)
• .hallmark/log.json — Project memory for diversification enforcement
• design.md — Optional portable design system file generated by study or redesign verbs

Summary

• Hallmark is a design skill activated in AI assistants via npx skills add nutlope/hallmark, not a CLI tool for manual use.
• The system operates through four verbs: hallmark (build), hallmark audit (score), hallmark redesign (refresh), and hallmark study (extract).
• Every build passes through a 9-step architectural flow including genre detection, macrostructure diversification, and theme routing.
• The 58-gate slop-test automatically rejects outputs containing AI-typical anti-patterns like fabricated metrics or undifferentiated card grids.
• Reference files in skills/hallmark/references/ enforce strict design disciplines, while .hallmark/log.json ensures structural variety across multiple generations.

Frequently Asked Questions

Which AI coding assistants support Hallmark?

Hallmark is compatible with Claude Code, Cursor, and Codex. Any assistant that supports the "skills" architecture and can read markdown reference files from the repository can invoke the hallmark verb family. The skill is installed via npx skills add nutlope/hallmark and loads its rules from skills/hallmark/SKILL.md.

What happens if a build fails the slop-test?

If any of the 58 gates in references/slop-test.md scores below 3, the assistant must automatically trigger a revision pass. The system does not emit code that fails the slop-test. Instead, it re-evaluates the macrostructure, theme, or component implementation until all gates pass, ensuring the final output meets the anti-slop design discipline.

Can I force Hallmark to use a specific layout or color scheme?

Yes. Use hallmark study <URL> or hallmark study <screenshot> to extract design DNA into a design.md file, which subsequent hallmark invocations will automatically adopt. Alternatively, use hallmark redesign <target> --mood <genre> to constrain the genre while refreshing the visual layer, or provide a detailed brief requesting a custom OKLCH palette to trigger the Custom theme route.

How does Hallmark prevent repetitive designs?

The system enforces diversification through .hallmark/log.json, which records recent macrostructure and theme selections. The rules require each new build to differ from the last on at least one axis—macrostructure, paper band, display style, or accent hue. This prevents the "same AI layout" problem that occurs when models default to their training distribution.

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