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

> Learn how to use the hallmark audit command to detect design anti-patterns in your HTML CSS files without code modification. Get a ranked punch-list of issues.

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

---

**`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](https://github.com/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) Exists)

| Violation | Severity | Trigger |
|-----------|----------|---------|
| **Theme drift** | `critical` | Mismatched tokens, fonts, or accents vs. [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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

```bash
hallmark audit site/index.html

```

### Audit Multiple Files

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

```

### Save Report for Later Use

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Entry point declaring all four verbs: `default`, `audit`, `redesign`, `study`. |
| [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Master catalog of AI-generated UI tells the audit detects. |
| [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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

```bash

# Check before investing in redesign

hallmark audit src/pages/about.html

# Review critical findings

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

```

### CI Integration

```bash

# Fail build on critical findings

hallmark audit dist/ --fail-on=critical

```

### Batch Portfolio Audit

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.