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

> Discover how Hallmark's audit verb scores code against UI anti-patterns. It inspects source files, flags mismatches, and applies genre-aware tolerances for accurate validation.

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

---

**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](https://github.com/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`](https://github.com/Nutlope/hallmark/blob/main/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/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md#L16-L17).

### Design-System Audit

Projects containing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md#L18-L24).

## Running the Audit Verb

Basic invocation scans individual files or entire directories recursively:

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md#L15-L18).

## Summary

- The `audit` verb scores code by matching against [[`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) 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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md).

### What happens when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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.