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

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 and 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. 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. 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, 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:

hallmark audit site/examples/wayfare/index.html

Sample output:

# 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, 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:

# .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:

# 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 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, 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.
• 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 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, 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, 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—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, you can influence scoring through genre-aware overrides. By defining a 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}