# How the `hallmark audit` Command Scores Code Against AI Anti-Patterns

> Discover how the hallmark audit command identifies AI-generated UI anti-patterns in HTML CSS and JavaScript. Get a severity-weighted report with actionable fixes.

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

---

**The `hallmark audit` command inspects HTML, CSS, and JavaScript files against a canonical catalogue of AI-generated UI anti-patterns, producing a severity-weighted report that identifies "tells" and recommends concrete fixes.**

The `hallmark audit` verb in [Nutlope/hallmark](https://github.com/Nutlope/hallmark) is a read-only diagnostic tool designed to detect whether frontend code exhibits the visual signatures of AI-generated design. It performs static analysis against a curated rule set and outputs structured findings grouped by severity. This guide explains exactly how the scoring mechanism works, from rule loading through final verdict generation.

---

## Loading the Anti-Pattern Rule Set

Every audit begins by loading the canonical anti-pattern catalogue from [[`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). Each entry in this file defines a named pattern with three severity tiers:

- **Critical** — Definite slop indicators that the report flags as "ships as slop." Examples include purple-gradient heroes and full-viewport centered heroes.
- **Major** — Strong AI-generated visual signatures. Examples include `bounce`/`ease-elastic` animations, centered-everything layouts, and italic headers.
- **Minor** — Subtle taste issues that accumulate. Examples include straight quotes instead of curly quotes and `z-index: 9999` values.

The severity classification directly weights the final audit score. A single critical finding triggers an automatic "ships as slop" verdict regardless of other results.

---

## Scanning Target Files for Pattern Matches

The audit accepts any file or directory path as its target:

```bash

# Audit an entire directory

hallmark audit ./src/pages

# Audit a single file

hallmark audit ./src/components/hero.css

```

For each file encountered, the verb applies pattern matching across HTML, CSS, and JavaScript content. The matching logic checks for exact pattern definitions from the anti-patterns catalogue—no fuzzy inference, only documented tells.

---

## Generating Structured Findings

Every detected match produces a finding record with four mandatory fields, as specified 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):

| Field | Description |
|-------|-------------|
| **Tell** | The anti-pattern name from the catalogue |
| **Where** | File path and line range (e.g., `src/pages/index.html:45-47`) |
| **Severity** | `critical`, `major`, or `minor` |
| **Fix** | One-line actionable recommendation from the "Fix" paragraph |

Here is a representative audit output showing all three severity levels:

```text
[critical] The purple-gradient hero — src/pages/home.html:52-54
  why it reads as AI-generated
  → pick a single anchor hue; no gradient hero

[major] Inter-everywhere — src/styles/global.css:8-10
  why it reads as AI-generated
  → pair a distinctive display face with a refined body face

[minor] Straight quotes — src/components/quote.html:23
  why it reads as AI-generated
  → use curly quotes

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

```

---

## Structural Fingerprint Checks

Beyond style tells, the `hallmark audit` command evaluates architectural consistency through three additional checks defined in lines 14-24 of [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md):

### Stamp-vs-Page Verification

The audit validates that `/* Hallmark · macrostructure: <name> … */` comments match the actual page shape. Mismatched structural declarations generate findings even when visual anti-patterns are absent.

### Genre-Aware Scoring

The same visual element receives different severity weights depending on declared genre. A radial-gradient background is **critical** for *editorial* pages but **allowed** for *atmospheric* layouts. This prevents false positives when unconventional aesthetics are intentional.

### [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) Drift Detection

If a project contains a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file, the audit cross-references:

- Theme consistency against declared design tokens
- Macrostructure family violations
- Missing or mismatched stamp declarations

These checks catch deviations from self-documented design systems.

---

## Grouping and Final Scoring

All findings are aggregated by severity before output. The final report format is strictly prescribed in [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md):

```

Summary — N critical · M major · K minor
Verdict — [ships as slop | needs work | clean]

```

The verdict logic follows the hierarchy:

- Any **critical** finding → "ships as slop"
- Only **major** and/or **minor** findings → "needs work"
- No findings → "clean"

---

## Summary

- **The `hallmark audit` command** loads anti-patterns from [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) with severity tiers of critical, major, and minor.
- **Pattern matching** scans user-supplied files for exact matches against the catalogue, generating structured findings with tell names, locations, severities, and fixes.
- **Structural checks** validate `Hallmark` stamp comments, apply genre-specific overrides, and detect [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) drift.
- **Final scoring** groups findings by severity and produces a verdict: "ships as slop," "needs work," or "clean."
- **The command never modifies files** — it is purely diagnostic.

---

## Frequently Asked Questions

### What file types does `hallmark audit` analyze?

The command processes HTML, CSS, and JavaScript files. It performs static text analysis against pattern definitions, so any file containing code in these languages is valid input, including templated files like `.jsx` or `.vue` if they include recognizable CSS or HTML structures.

### Where are the anti-pattern definitions stored?

All rules live 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). This file contains the complete catalogue with severity classifications, descriptions explaining why each pattern reads as AI-generated, and the one-line fix recommendations that appear in audit output.

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

No. According to the verb definition 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), the audit command is strictly read-only. For automated remediation, you would use the `hallmark redesign` verb instead.

### How does genre affect the audit score?

Genre declarations modify severity weights for specific patterns. For example, a radial-gradient hero background is classified as **critical** for *editorial* genre pages but permitted without penalty for *atmospheric* pages. This contextual scoring prevents penalizing intentional aesthetic choices that match declared genre conventions.