# What Does the `hallmark audit` Command Do? A Complete Guide to Anti-Pattern Detection

> Learn what the hallmark audit command does. Detect AI-generated UI anti-patterns and structural violations with this read-only analysis. Get a severity-graded report to guide redesign decisions.

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

---

**The `hallmark audit <target>` command performs a read-only analysis of HTML/CSS files to detect AI-generated UI anti-patterns, structural violations, and "stamp lies," producing a severity-graded report that helps developers decide whether to run a redesign.**

The `hallmark audit` command is one of three explicit verbs defined in the Hallmark design skill for identifying "slop" in web interfaces. According to the [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) specification, this command evaluates source files against an anti-pattern catalogue and structural rules without ever modifying the original code.

## How the hallmark audit Command Works

### Target File Ingestion

When invoked with `hallmark audit <target>`, the tool loads the specified HTML, CSS, or directory contents. The command recursively walks directories specified as targets, auditing every file containing Hallmark-relevant markup to build a comprehensive analysis scope.

### Anti-Pattern Detection Against the Catalogue

The audit scans for named "tells" defined in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). These include visual signatures like the **purple-gradient hero**, **3-column feature grids**, and **mixed icon libraries**. Each detected anti-pattern receives a severity classification of **critical**, **major**, or **minor** based on its correlation with AI-generated templates.

### Structural Fingerprint Verification

Beyond surface patterns, the audit verifies macro-structure guidelines defined in the Hallmark specification. If a page uses a centered-hero-only template—a common AI-template shape—the tool flags this as a **critical structural finding** regardless of visual polish.

### Stamp-vs-Page Validation

When source files contain a Hallmark stamp (`/* Hallmark · macrostructure: … */`), the audit performs validation checks to ensure the actual markup matches the claimed macrostructure. Mismatches between declared structure and implemented code are flagged as **stamp lies**, indicating the developer documentation has drifted from reality.

### Genre-Aware Tolerance Rules

The audit respects genre declarations within stamps (such as `genre: atmospheric`). When specified, the tool applies tolerance rules from [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md), allowing certain patterns like gradients in atmospheric contexts while maintaining strict rules for other genres. This implements the **58-gate slop-test** logic specified in the reference documentation.

### Design System Drift Detection

If the project root contains a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md) file, the audit performs additional checks against the locked design system. It validates token usage, font pairings, and macrostructure compliance, flagging any drift from the established design specifications as critical findings.

## Understanding the Audit Report Format

The command outputs findings grouped by severity with structured metadata. Each entry includes the anti-pattern name, file location (e.g., `index.html:23`), severity level, explanation ("why"), and a one-line fix suggestion.

The report concludes with a quantitative summary line (`3 critical · 5 major · 12 minor`) and a final verdict such as *"ships as slop"* or an equivalent status indicating whether the code meets Hallmark quality standards.

## Practical Usage Examples

Basic single-file audit:

```bash
hallmark audit index.html

```

Recursive directory audit:

```bash
hallmark audit src/

```

Sample output structure:

```text
critical   The purple‑gradient hero — index.html:23
  why: gradient background on hero is a known AI tell
  → fix: use a single anchor hue, no gradient

major      Inter‑everywhere — styles.css:45
  why: same font used for display and body
  → fix: pair a distinctive display face with a refined body face

minor      Straight quotes — components/quotes.html:12
  why: typographic typo
  → fix: replace with curly quotes

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

```

## Summary

- The `hallmark audit` command is a **read-only safety check** that never modifies source files, unlike the `redesign` or `study` verbs.
- It evaluates code against the **anti-pattern catalogue** in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) and the **58-gate slop-test** rules in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md).
- The tool detects **structural violations**, **stamp lies** (documentation drift), and **design system drift** against [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specifications.
- Findings are classified into three severity levels: **critical**, **major**, and **minor**.
- Output includes actionable fix suggestions and a final verdict determining if the code "ships as slop."

## Frequently Asked Questions

### Does `hallmark audit` modify my source files?

No. According to [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the audit verb is explicitly designed as a read-only operation. It analyzes and reports findings without writing changes to disk, serving as a decision-making tool to determine whether you should proceed with `hallmark redesign` or other modification commands.

### What is the difference between critical, major, and minor findings?

**Critical** findings indicate severe AI-template signatures or structural violations (like purple-gradient heroes or centered-hero-only layouts). **Major** findings represent significant design system drift or anti-patterns that degrade user experience. **Minor** findings are typographic or stylistic issues (like straight quotes instead of curly) that don't indicate AI generation but should be fixed for polish.

### How does the audit handle different design genres?

When a Hallmark stamp declares a genre (e.g., `genre: atmospheric`), the audit applies genre-specific tolerance rules from [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). For example, gradients that would be flagged as critical AI-tells in a corporate genre might be permitted in atmospheric contexts, demonstrating the tool's contextual awareness of legitimate design variations.

### What happens if my Hallmark stamp doesn't match my actual code?

The audit performs **stamp validation** by comparing the declared macrostructure in your stamp comment against the actual DOM structure. If mismatches are detected, the tool flags these as "stamp lies" in the report, helping maintain documentation accuracy and preventing drift between claimed architecture and implementation.