How to Use the `hallmark audit` Command for Design Anti-Pattern Detection

hallmark audit reads HTML/CSS files and returns a ranked punch-list of design anti-patterns without modifying any code.

The hallmark audit command is the safety verb of the Hallmark design skill, implemented in the Nutlope/hallmark repository. Use it to examine existing pages for AI-generated UI tells, theme drift, and structural violations before deciding whether to run hallmark redesign or hallmark refine.

---

How hallmark audit Works

The command performs a seven-step analysis pipeline. Each finding includes the Tell (anti-pattern name), file location, Severity (critical, major, minor), and a one-line Fix.

1. File Ingestion

The verb loads every file you specify via glob patterns or explicit paths. It processes both HTML and CSS files in a single pass.

2. Anti-Pattern Detection

Each finding references a specific tell from skills/hallmark/references/anti-patterns.md. The audit cross-references your code against this master list of AI-generated UI patterns.

3. Severity Grouping

Results are sorted from most to least severe, ending with a summary count:

2 critical · 5 major · 7 minor

4. Structural Fingerprint Check

Pages following Hallmark's default AI template—centered hero, three equal feature cards, CTA, footer—are flagged as critical structural findings. This detects unmodified template output.

5. Stamp-vs-Page Verification

When a file contains a Hallmark CSS comment like:

/* Hallmark · macrostructure: <name> · genre: <genre> */

The command verifies that actual markup matches the declared macrostructure. A mismatch triggers critical: stamp lies.

6. Genre-Aware Audit

If the stamp declares a genre (e.g., genre: atmospheric), the command applies genre-specific overrides from skills/hallmark/references/slop-test.md. Some tells are tolerated in certain genres—what violates "corporate clean" may pass for "brutalist."

7. Design-System Rules (When design.md Exists)

Violation	Severity	Trigger
Theme drift	critical	Mismatched tokens, fonts, or accents vs. design.md
Macrostructure family violation	major	Page uses macrostructure not allowed by design system
Stamp mismatch	critical	CSS claims compliance that code doesn't deliver
Missing stamp	major	Any page in design-system project lacks a stamp

Fallback for Design-System-Less Projects

When no design.md exists, Hallmark applies its diversification rule: pages repeating the same macrostructure or theme as previous Hallmark output receive minor: variety drift.

---

Running hallmark audit

Audit a Single File

hallmark audit site/index.html

Audit Multiple Files

hallmark audit site/**/*.html site/**/*.css

Save Report for Later Use

hallmark audit site/index.html > audit-report.md

The saved report can be pasted into PR comments, attached to tickets, or referenced during hallmark redesign runs.

---

Understanding the Output Format

Raw output follows this structure:

✗ critical: stamp lies – CSS stamp says "macrostructure: Bento Grid" but page is a centered hero.
✗ major: theme drift – page uses #ff33aa where the design system expects #0066ff.
✗ minor: gradient pill CTA – replace with solid fill or outline.
…
2 critical · 3 major · 4 minor

Grouped output (multiple files):

critical (2):
  • stamp lies – site/_tests/audit-example.html
  • structural fingerprint – site/_tests/audit-example.html
major (5):
  • theme drift – site/_tests/audit-example.html
  • …
minor (7):
  • gradient pill CTA – site/_tests/audit-example.html
  • …

---

Key Source Files

Understanding where hallmark audit logic lives helps with debugging and extending the tool:

File	Purpose
skills/hallmark/SKILL.md	Entry point declaring all four verbs: default, audit, redesign, study.
skills/hallmark/references/verbs/audit.md	Complete specification of the audit verb's behavior, grouping rules, and output format.
skills/hallmark/references/anti-patterns.md	Master catalog of AI-generated UI tells the audit detects.
skills/hallmark/references/slop-test.md	57 "slop-test" gates with genre-aware overrides for atmospheric, brutalist, and other genres.
site/_tests/verbs/audit/audit-report.md	Real example output from test runs.

The command reads these reference files at runtime, so the audit stays current with skill updates.

---

Practical Integration Patterns

Pre-Refinement Review

# Check before investing in redesign

hallmark audit src/pages/about.html

# Review critical findings

# Decide: manual fix, or `hallmark redesign`?

CI Integration

# Fail build on critical findings

hallmark audit dist/ --fail-on=critical

Batch Portfolio Audit

# Audit entire site, save for team review

hallmark audit "src/**/*.html" > audits/$(date +%Y-%m-%d)-report.md

---

Summary

• hallmark audit never writes files—it only reports, making it safe for first-pass review.
• Severity levels (critical/major/minor) prioritize what to fix first.
• Stamp verification catches discrepancies between declared and actual macrostructure.
• Genre awareness means the same visual element may pass or fail depending on declared genre.
• Design-system integration adds strict rules when design.md is present; without it, diversification rules apply.
• All logic is reference-file driven from skills/hallmark/references/, not hardcoded.

---

Frequently Asked Questions

What makes a finding "critical" vs. "major" or "minor"?

Critical findings break trust or structure: stamp lies, theme drift in design-system projects, and structural fingerprint (unmodified AI template). Major violations include missing stamps or disallowed macrostructures. Minor flags style tells like gradient pills or generic feature icons that reduce distinctiveness without breaking systems.

Can hallmark audit fix the issues it finds?

No—the audit verb is read-only by design. It outputs a ranked punch-list for human review or input to hallmark redesign/refine. This separation lets you assess scope before committing to automated changes.

How does genre declaration affect results?

The genre field in a Hallmark stamp activates overrides from slop-test.md. For example, genre: atmospheric tolerates soft gradients and blur effects that genre: corporate-clean would flag. Declare your genre accurately to avoid false positives.

What happens if I audit files without Hallmark stamps?

The audit runs in fallback mode: no stamp-mismatch checks, but diversification rules still flag minor: variety drift when pages repeat previous Hallmark macrostructures. Consider adding stamps to enable full verification.

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