# How to Use Hallmark to Generate UI for AI Coding Assistants

> Learn how to use Hallmark to generate stunning, production-ready UIs for your AI coding assistants. Ensure intentional design with Hallmark's anti-slop checklist and diversification rules.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-08

---

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

```bash
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.

```bash
hallmark

```

When invoked, the system reads existing project signals from [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json), selects a diversification-compliant macrostructure from [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/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.

```bash
hallmark audit ./site/index.html

```

The audit references [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md) and [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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.

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file for reuse across projects.

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md), font stacks, motion libraries, and framework choices—and records them in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) (e.g., [`05-workbench.md`](https://github.com/Nutlope/hallmark/blob/main/05-workbench.md)). Diversification rules in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/typography.md), [`color.md`](https://github.com/Nutlope/hallmark/blob/main/color.md), [`layout-and-space.md`](https://github.com/Nutlope/hallmark/blob/main/layout-and-space.md), [`motion.md`](https://github.com/Nutlope/hallmark/blob/main/motion.md), [`copy.md`](https://github.com/Nutlope/hallmark/blob/main/copy.md), and [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md). Component-specific files load only when needed.

**6. Hero Enrichment Decision**

Using [`references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — Core skill definition and verb table
- [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) — 58-gate quality checklist
- [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) — Decision tree for media vs. typography heroes
- [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) — Universal design token definitions (`--color-accent`, `--font-display`)
- [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) — Project memory for diversification enforcement
- [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

### What happens if a build fails the slop-test?

If any of the 58 gates in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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.