# How the Hallmark `audit` Verb Works: A Complete Guide to Detecting AI-Generated Design Issues

> Discover how the Hallmark audit verb works to detect AI-generated design issues. Learn about its seven-stage pipeline for anti-pattern and rule checking without modifying HTML.

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

---

**The `hallmark audit` verb analyzes HTML files without modifying them, surfacing "AI-generated slop" and design issues through a seven-stage pipeline that checks anti-patterns, macrostructure stamps, genre rules, and optional design-system constraints.**

The `hallmark audit` verb is the safety-check step in the Hallmark toolchain that evaluates one or more HTML files before you decide whether to `refine` or `redesign` a page. According to the [Nutlope/hallmark](https://github.com/Nutlope/hallmark) source code, it functions as a read-only linter specialized for detecting visual clichés, structural laziness, and design-system violations in AI-generated landing pages.

## How `hallmark audit` Processes Files

The audit follows a strict pipeline defined in [[`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). Each stage feeds findings into a severity-ranked report.

### 1. File Ingestion and Stamp Extraction

The verb receives a file path or glob pattern:

```bash
hallmark audit index.html
hallmark audit src/pages/*.html

```

For each target file, the audit engine:

- Loads the HTML content
- Extracts any **Hallmark stamp comments** (`/* Hallmark · macrostructure: … */`)
- Captures the declared macrostructure name and optional `genre:` tags

Stamps serve as both documentation and validation hooks for subsequent checks.

### 2. Anti-Pattern Detection

The core of `hallmark audit` is the anti-pattern detector defined in [[`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). For every line in the file, the engine tests against a curated rulebook:

| Severity | Trigger | Example Tell |
|----------|---------|--------------|
| **critical** | Structural failures, outright slop | Purple-gradient hero, generic three-card feature grid |
| **major** | Significant design degradation | Inter font used everywhere, missing stamps |
| **minor** | Polish issues | Straight quotes, inconsistent spacing |

Each match produces:

- **Tell name** – the named anti-pattern identifier
- **Location** – `file:line` for precise navigation
- **Severity** – `critical`, `major`, or `minor`
- **One-line rationale** – why this pattern signals poor quality
- **One-line fix** – actionable remediation guidance

### 3. Structural Fingerprint Check

The audit specifically targets a common AI template pattern. As implemented in the early section of [[`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the engine checks for:

- Centered full-viewport hero section
- Three equal-width feature cards
- Generic CTA block
- Footer with minimal variation
- **No asymmetry or intentional tension**

Pages matching this fingerprint are flagged with a **critical structural finding**, regardless of other quality signals.

### 4. Stamp-vs-Page Validation

When a stamp declares `macrostructure: <name>`, the audit verifies that the actual DOM matches that macrostructure definition. A mismatch—where the stamp "lies" about the page structure—is reported as **critical**. This prevents documentation drift and enforces honest metadata.

### 5. Genre-Aware Overrides

If the stamp includes a `genre:` tag (e.g., `genre: atmospheric`), the audit loads genre-specific exceptions from [[`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). For example:

- **Atmospheric genre**: Radial-gradient backgrounds permitted
- **Brutalist genre**: Intentional clash of type scales allowed
- **Editorial genre**: Asymmetric layouts expected, not penalized

These overrides prevent false positives when a page's aesthetic choices are deliberate rather than lazy.

### 6. Design-System Audit (Conditional)

When [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md) exists at the project root, `hallmark audit` activates four additional checks:

1. **Theme drift** – Hardcoded values (`#5b6cff`) that bypass design tokens
2. **Macrostructure family violation** – Using a macrostructure not permitted by the system's allowed families
3. **Stamp mismatch** – Stamps claiming design-system compliance that the page violates
4. **Missing stamp** – Pages without stamps flagged as **major** in system-managed projects

This design-system integration is documented in the *design.md audit* section of [[`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md).

### 7. Reporting and Verdict

Findings are grouped by severity and formatted per the specification in [[`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md):

```text
[severity] Tell name — file:line
  why it's a tell (one line)
  → fix (one line)

```

The report concludes with a summary line (`N critical · M major · K minor`) and a verdict such as **"ships as slop"** or **"passes"**.

## Running `hallmark audit`: Examples

### Basic Single-File Audit

```bash
hallmark audit src/pages/home.html

```

Typical output:

```text
[critical] The purple-gradient hero — src/pages/home.html:12
  A hero section with a purple-to-blue gradient background.
  → Pick a single anchor hue; no gradient on heroes.

[major] Inter-everywhere — src/pages/home.html:27
  Inter used as both display and body font.
  → Pair a distinctive display face with a refined body face.

[minor] Straight quotes — src/pages/home.html:45
  Uses straight quotes in body copy.
  → Replace with curly quotes.

Summary — 1 critical · 1 major · 1 minor
Verdict — ships as slop

```

### Design-System Project Audit

```bash
hallmark audit src/pages/about.html

```

With [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) present, output includes system-level checks:

```text
[critical] Theme drift — src/pages/about.html:8
  Token "#5b6cff" used directly instead of a design token.
  → Replace with var(--color-accent) or add a new token.

[major] Missing stamp — src/pages/about.html:1
  No Hallmark macrostructure stamp found in a design-managed project.
  → Add a stamp that matches the macrostructure you intend to use.

Summary — 1 critical · 1 major · 0 minor
Verdict — ships as slop

```

## Key Source Files

Understanding these files deepens your ability to interpret and extend `hallmark audit`:

- **[`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md)** – Core verb specification; defines the seven-stage pipeline, stamp validation logic, and design-system integration points
- **[`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md)** – Rulebook of named anti-patterns with severities, rationales, and fixes; referenced directly by the audit engine
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – High-level skill definition that maps `hallmark audit <target>` to the audit implementation
- **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)** (project-local, optional) – Design system definition triggering additional validation rules
- **[`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)** – Genre-specific override definitions for context-aware detection

## Summary

- **`hallmark audit`** is a **read-only analysis tool** that never modifies source files
- The verb executes a **seven-stage pipeline**: file ingestion, anti-pattern detection, structural fingerprinting, stamp validation, genre overrides, design-system checks, and formatted reporting
- **Anti-patterns** are sourced from [[`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) and assigned **critical/major/minor** severities
- **Stamps** (`/* Hallmark · macrostructure: … */`) enable both documentation and automated validation of page structure
- **Genre tags** load context-aware exceptions from [[`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)
- **Design-system mode** activates when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists, adding token-drift and macrostructure-family validations

## Frequently Asked Questions

### What makes `hallmark audit` different from standard HTML validators?

Standard validators check syntax, accessibility, and SEO metadata. `hallmark audit` evaluates **aesthetic and structural quality signals** specific to AI-generated content—detecting visual clichés like gradient heroes, generic three-card layouts, and font monotony that conventional tools ignore. The source code in [[`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) explicitly targets "AI-generated slop" patterns rather than markup correctness.

### Can `hallmark audit` fix the issues it finds?

No. The verb is **strictly read-only** by design. It produces a severity-ranked punch-list that guides your next decision: use `hallmark refine` for targeted fixes or `hallmark redesign` for structural overhaul. This separation of concerns ensures you review findings before any automated changes occur.

### How does the design-system integration work?

When [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists at your project root, the audit loads token definitions and permitted macrostructure families from that file. It then checks each audited page for **theme drift** (hardcoded values), **family violations** (unauthorized layouts), **stamp mismatches** (false compliance claims), and **missing stamps** (undocumented pages). All four checks are defined in the *design.md audit* section of [[`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md).