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

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 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). Each stage feeds findings into a severity-ranked report.

1. File Ingestion and Stamp Extraction

The verb receives a file path or glob pattern:

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). 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/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/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 or 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/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/skills/hallmark/references/anti-patterns.md):

[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

hallmark audit src/pages/home.html

Typical output:

[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

hallmark audit src/pages/about.html

With design.md present, output includes system-level checks:

[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 – Core verb specification; defines the seven-stage pipeline, stamp validation logic, and design-system integration points
• 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 – High-level skill definition that maps hallmark audit <target> to the audit implementation
• design.md (project-local, optional) – Design system definition triggering additional validation rules
• 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/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/skills/hallmark/references/slop-test.md)
• Design-system mode activates when 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/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 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/skills/hallmark/references/verbs/audit.md).

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