# How to Use `hallmark audit` to Score UI Against Anti-Patterns

> Score UI against anti-patterns using `hallmark audit` CLI from Nutlope/hallmark. Detect AI design tells in your HTML and get a ranked markdown report without altering source files.

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

---

**To score a UI against anti-patterns, run `hallmark audit <target-file>` from the Nutlope/hallmark CLI, which reads your HTML and outputs a ranked markdown report of detected AI-generated design "tells" without modifying any source files.**

The `hallmark audit` command is a read-only analysis tool in the Hallmark design-system CLI that evaluates HTML files against a canonical library of UI anti-patterns. As implemented in the Nutlope/hallmark repository, this verb scans your markup for AI-generated design "tells" and structural issues, producing a severity-ranked punch-list you can use to guide manual fixes or automated redesigns.

## How the Scoring Algorithm Works

The `hallmark audit` verb follows a five-step pipeline defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). Each step transforms the input HTML into a structured report without altering the source.

### Step 1: Load the Anti-Pattern Library

Hallmark ships with a definitive reference list located at [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). This file contains the catalog of UI patterns considered AI-generated or undesirable, including **Invented metrics**, **Re-drawn chrome**, and **Italic headers**. The audit verb loads this library into memory before parsing your target file.

### Step 2: Parse the Target HTML

The verb reads the supplied HTML (or screenshot-derived markup) using a DOM walker. This step is purely observational; no changes are written to disk. The parser extracts structural elements, class names, and visual attributes required for pattern matching.

### Step 3: Execute Pattern Matching and Slop-Tests

Hallmark evaluates each DOM element against the anti-pattern catalog. Simultaneously, it runs the **58 "slop-test" gates** documented in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). These structural checks catch deeper architectural issues such as **mid-render token improvisation** and **eyebrow-plus-heading** misuse that surface-level pattern matching might miss.

### Step 4: Rank Findings by Severity

Detected issues are classified into three severity tiers: **critical**, **major**, and **minor**. The algorithm sorts all findings into a punch-list format, prioritizing structural anti-patterns that affect user experience over cosmetic inconsistencies.

### Step 5: Generate the Markdown Report

The verb outputs a concise markdown report to stdout. As shown in [`site/_tests/verbs/audit/audit-report.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/audit/audit-report.md), the report format includes the anti-pattern name, a brief explanation, and a recommended fix. No files are written during this process unless you explicitly redirect the output.

## Running Your First Audit

### Basic CLI Usage

Run the audit against any HTML file in your project:

```bash
hallmark audit site/examples/wayfare/index.html

```

**Sample output:**

```markdown

# hallmark audit site/examples/wayfare/index.html

## Findings (ranked)

1. ✗ Gradient hero
   → Use a solid surface or a single accent colour.
2. ✗ Inter as display + body
   → Pair a distinctive display font with a body font.
3. ✗ Centered everything
   → Bias the layout and break symmetry.
4. ✗ Emoji badge
   → Pick an icon library or remove the emoji.
5. ✗ Gradient pill CTA
   → Use a solid fill or outline with a single hue.

```

The report links directly to the anti-pattern definitions in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md), allowing you to understand the rationale behind each recommendation.

### CI/CD Integration

Because `hallmark audit` is read-only and returns a markdown artifact, it integrates cleanly into GitHub Actions workflows:

```yaml

# .github/workflows/audit.yml

name: UI Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Hallmark audit
        run: |
          hallmark audit site/index.html > audit-report.md
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: audit-report
          path: audit-report.md

```

Reviewers can view the uploaded markdown directly in the GitHub UI to verify that new commits do not introduce AI-generated design patterns.

## Acting on Audit Results

The `hallmark audit` output serves two primary workflows: **refinement** or **redesign**.

**Refinement** is appropriate when the audit reveals isolated cosmetic issues. You manually fix the listed anti-patterns while preserving the page's macro-structure.

**Redesign** is recommended when the audit detects fundamental structural problems. You can feed the audit report into the redesign verb using the `--notes` flag:

```bash

# Generate the audit report

hallmark audit src/pages/home.html > audit.md

# Redesign while respecting the flagged anti-patterns

hallmark redesign src/pages/home.html --notes audit.md

```

The `--notes` flag ensures the `redesign` verb considers the existing anti-patterns, preventing the new design from repeating the same mistakes.

### Genre-Aware Scoring

If your project contains a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file or `genre` specification in the project root, `hallmark audit` applies genre-aware overrides during scoring. This feature, documented in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), adjusts the severity of certain anti-patterns based on your specific design system's conventions.

## Summary

- **`hallmark audit`** is a read-only CLI verb in Nutlope/hallmark that scores HTML against [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md).
- The scoring process includes **58 slop-test gates** for structural validation and ranks findings by severity (critical, major, minor).
- Output is a markdown punch-list suitable for manual review, CI artifacts, or feeding into `hallmark redesign` via the `--notes` flag.
- The tool respects **genre-aware** configurations from [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) and never modifies source files.
- Use it to detect AI-generated "tells" like gradient heroes, emoji badges, and typography misuse before they reach production.

## Frequently Asked Questions

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

The verb primarily targets HTML files. According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), it parses standard HTML markup or screenshot-derived markup representations. While the core focus is HTML, the DOM walker can process any markup format that resolves to a parseable document structure.

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

No. The audit verb is strictly read-only. As specified in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), it parses the target without making edits, outputting results to stdout. This makes it safe to run repeatedly on production code or in CI pipelines without risk of accidental modifications.

### How does Hallmark determine the severity of anti-patterns?

Severity is assigned based on the structural impact of the pattern. Critical issues—such as those detected by the slop-test gates in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)—indicate fundamental architectural problems. Major and minor tiers correspond to user-facing inconsistencies and cosmetic deviations, respectively. The ranking algorithm ensures structural fixes are prioritized over aesthetic adjustments.

### Can I customize the anti-pattern rules for my project?

Yes. While Hallmark provides a canonical list in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md), you can influence scoring through **genre-aware** overrides. By defining a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or `genre` specification in your project root, you instruct the audit verb to adjust severity weights or ignore specific patterns that align with your established design system conventions.