How Hallmark's Audit Verb Scores Existing Code Against Anti-Patterns

Hallmark's audit verb inspects source files against a curated catalogue of UI anti-patterns and produces a severity-based score, flagging mismatches between stamped metadata and actual markup while applying genre-aware tolerances and design-system validations.

The hallmark audit verb in the Nutlope/hallmark repository is a diagnostic tool purpose-built to detect AI-generated UI patterns. It transforms code review from manual inspection into a structured, machine-readable report that scores how closely your implementation adheres to human-centric design principles.

File-Level Scanning and Stamp Verification

The audit verb begins by reading every file supplied—HTML, CSS, JavaScript, and more—and extracting stamped metadata embedded in comments like /* Hallmark · macrostructure: … */.

Once extracted, the verb performs a structural integrity check: it verifies that the actual markup matches the declared macrostructure. When a mismatch occurs, the verb flags a critical "stamp lies" error at skills/hallmark/references/verbs/audit.md#L14-L15. This ensures that declared intent and implementation remain synchronized, preventing documentation drift.

Anti-Pattern Matching and Severity Scoring

The core scoring mechanism relies on [anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md), a canonical catalogue of named tells that signal AI-generated UI. Each detected match generates a structured finding with four components:

• Tell — the anti-pattern name (e.g., "The purple-gradient hero")
• Where — precise file path and line range
• Severity — critical, major, or minor per the definitions at audit.md#L5-L9
• Fix — a concrete, one-line correction

Findings aggregate by severity, producing a summary line formatted as N critical · M major · K minor at audit.md#L10-L11.

Context-Aware Overrides

The audit verb applies two sophisticated override mechanisms that refine scoring based on project context.

Genre-Aware Audit

When a page's stamp includes a genre: tag, the verb consults genre-specific tolerances defined in slop-test.md. The same visual element can trigger different severities depending on genre context. For example, a radial-gradient background is critical for the "editorial" genre yet permitted for "atmospheric" at audit.md#L16-L17.

Design-System Audit

Projects containing design.md or DESIGN.md activate additional validation. The verb cross-checks every page against locked design-system tokens, themes, and macrostructures. Mismatches surface as "design-system drift" (critical) or "missing system reference" (major) at audit.md#L18-L24.

Running the Audit Verb

Basic invocation scans individual files or entire directories recursively:

# Audit a single page

hallmark audit src/pages/hero.html

# Audit recursively through a directory

hallmark audit src/pages/

# Override genre when stamp is absent

hallmark audit src/pages/hero.html --genre atmospheric

Understanding Audit Output

The verb produces machine-readable findings followed by a final verdict. Example output:

[critical] The purple-gradient hero — src/pages/hero.html:23
  A hero section with a purple-to-blue gradient background.
  → Fix: Pick a single anchor hue; remove the gradient.

[major] Inter-everywhere — src/pages/style.css:45-52
  Inter used for both display and body typefaces.
  → Fix: Pair a distinctive display face with a refined body face.

[minor] Straight quotes — src/pages/about.html:78
  Straight quotation marks appear in copy.
  → Fix: Use curly quotes.

Summary — 1 critical · 1 major · 1 minor
Verdict — reads as AI-generated

The report structure follows the template at audit.md#L3-L11. The verdict categorizes pages into three states: ships as slop (unacceptable), reads as AI-generated (needs revision), or close enough (minor fixes required) at audit.md#L15-L18.

Summary

• The audit verb scores code by matching against [anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) with three severity tiers: critical, major, minor
• Stamp verification catches structural lies by comparing declared metadata against actual markup
• Genre-aware scoring applies contextual tolerances so the same pattern triggers different severities based on aesthetic intent
• Design-system validation enforces consistency against locked design.md specifications
• Output format delivers actionable findings with precise locations and concrete fixes, ending with a clear verdict

Frequently Asked Questions

What files does the hallmark audit verb scan?

The verb processes HTML, CSS, JavaScript, and other source files supplied as arguments. It recursively traverses directories when provided a folder path, extracting stamped metadata and inspecting markup patterns across all recognized file types.

How does the audit verb determine severity levels?

Severity follows explicit definitions in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). Critical indicates patterns that definitively signal AI generation or structural dishonesty. Major reflects significant aesthetic deviations. Minor captures subtle refinements that improve perceived craft.

Can a page pass audit without a genre stamp?

Yes, but genre overrides via --genre flag or inferred defaults may apply less precise tolerances. Explicit genre stamps enable the most accurate scoring because they activate genre-specific rules from slop-test.md.

What happens when design.md is present but violated?

The verb flags critical "design-system drift" for tokens or themes that deviate from the locked specification, or major "missing system reference" when pages fail to reference declared system elements. This ensures organizational consistency across multi-page implementations.

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