How to Audit UI for AI-Slop Patterns Using the Hallmark Audit Command

The hallmark audit command analyzes HTML files against a curated catalogue of AI-slop anti-patterns to produce a markdown punch-list of violations without ever modifying your source code.

The hallmark audit command serves as the safety-first entry point for the Hallmark CLI (Nutlope/hallmark), offering developers a systematic way to audit UI for AI-slop patterns before they reach production. This read-only operation parses HTML structures, validates Hallmark stamps, and checks against 14 distinct anti-pattern gates to identify gradient-filled heroes, centered-everything layouts, and emoji badges that signal low-quality AI-generated interfaces.

How the Hallmark Audit Pipeline Works

When you invoke hallmark audit <target>, Hallmark executes a six-stage validation pipeline defined in skills/hallmark/references/verbs/audit.md. The process begins by parsing the target HTML and extracting any Hallmark stamp comment (/* Hallmark · macrostructure: … */), then proceeds through the following stages:

1. Extract and Validate Stamps – Compares declared macrostructures (e.g., "Bento Grid") against the actual DOM layout, flagging critical structural findings when the stamp claims do not match the implemented structure
2. Detect Genre Overrides – Applies genre-specific allowances when stamps include declarations like genre: atmospheric, referencing exemption rules from skills/hallmark/references/slop-test.md
3. Run Anti-Pattern Gates – Evaluates 14 binary "tell" checks against the DOM and CSS, including gradient-filled heroes, outline-none inputs, mixed icon libraries, and sparkle emoji badges
4. Cross-Reference Design Files – Validates the page against an optional design.md file in the repository root to ensure alignment with project-wide macro-structure constraints
5. Generate Markdown Report – Emits a structured report (audit-report.md) listing every failure together with actionable fix recommendations
6. Exit Status Handling – Returns exit code 1 if critical findings are detected, enabling CI pipeline integration

The command registers itself as a read-only verb in skills/hallmark/SKILL.md (lines 26-30), with additional documentation at lines 478-481 describing its safety constraints.

Running the Hallmark Audit Command

Basic CLI Usage

To audit a single HTML file for AI-slop patterns:

hallmark audit path/to/index.html

To audit multiple pages using glob patterns:

hallmark audit src/pages/**/*.html

Redirect the output to save the report:

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

Understanding the Audit Output

The generated report follows the structured format defined in skills/hallmark/references/anti-patterns.md. A typical output identifies specific violations and remediation steps:

# hallmark audit src/pages/home.html

> User invocation: "hallmark audit src/pages/home.html"

## Findings

- ✗ **Purple-to-pink gradient hero** → solid surface, single accent
- ✗ **Inter as display + body** → pair distinctive display + body
- ✗ **Centered everything** → bias the layout, break symmetry
- ✗ **Sparkle ✨ emoji as badge** → pick an icon library, or drop it
- ✗ **Gradient pill CTA** → solid fill or outline, single hue

Each finding corresponds to a specific anti-pattern in the Hallmark catalogue and includes a concrete fix recommendation suitable for direct implementation or ticketing systems.

CI/CD Integration

Because hallmark audit exits with a non-zero status code when critical findings are present, it integrates seamlessly into continuous integration workflows. The following GitHub Actions configuration demonstrates automated UI auditing on every pull request:

# .github/workflows/audit.yml

name: UI Slop Audit
on: [push, pull_request]

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

This workflow captures the markdown report as a build artifact while failing the check if AI-slop patterns are detected, preventing low-quality UI from merging into production branches.

Programmatic Usage

You can invoke the audit command programmatically from Node.js applications to process results dynamically and trigger automated remediation workflows:

import { exec } from 'child_process';
import { readFile } from 'fs/promises';

// Run audit on a file and capture the markdown output
exec('hallmark audit ./site/index.html', async (error, stdout) => {
  if (error) {
    console.error('Audit reported issues:');
    console.log(stdout);
    // Parse the markdown for automated remediation or Slack notifications
  } else {
    console.log('No AI-slop patterns found.');
  }
 });

This approach enables you to parse the structured markdown output and integrate findings into notification systems, ticketing APIs, or subsequent hallmark redesign automation.

Key Source Files in the Hallmark Repository

Understanding the following files helps customize and extend the audit behavior:

• skills/hallmark/SKILL.md – Defines the hallmark audit verb registration (lines 26-30) and enforces its read-only constraints (lines 478-481)
• skills/hallmark/references/verbs/audit.md – Contains the authoritative verb specification driving stamp validation, genre detection, and design-file integration logic
• skills/hallmark/references/anti-patterns.md – Enumerates the full catalogue of UI tells that constitute AI-slop, including the 14 binary check definitions and reporting format specifications
• skills/hallmark/references/slop-test.md – Defines genre-specific overrides used when stamps declare atmospheric or other stylistic genres
• site/index.html – Provides the visual demo interface, specifically the <li class="skill-row" data-verb="audit"> block (lines 460-508) that renders audit output in the web UI
• site/css/sections.css – Styles the audit checklist interface through the .audit-check family of selectors
• site/_tests/verbs/audit/audit-report.md – Contains example audit reports generated by the test suite for reference
• design.md (optional) – When present in the repository root, supplies macro-structure constraints that the audit validates against during the cross-reference stage

These files collectively implement the audit pipeline from verb declaration through anti-pattern detection to report rendering.

Summary

• The hallmark audit command provides a read-only safety check for AI-generated HTML, ensuring zero risk to production codebases during analysis
• It validates Hallmark stamp comments against actual DOM structures to detect critical structural mismatches between declared and implemented macrostructures
• The command runs 14 binary anti-pattern gates covering gradient heroes, typography pairing, layout symmetry, and iconography consistency
• Genre-aware auditing allows atmospheric or other specialized styles to pass specific checks via slop-test.md exemptions when properly declared in stamps
• Integration with design.md files enables enforcement of project-wide macro-structure constraints and design system compliance
• Output is a standardized markdown report suitable for PR comments, Jira tickets, or feeding into automated hallmark redesign remediation pipelines

Frequently Asked Questions

What is AI-slop in UI design?

AI-slop refers to visual tropes and low-quality patterns commonly produced by generative AI tools, such as gradient-filled hero sections with purple-to-pink transitions, excessive centering of content, mixing Inter font for both display and body text, and using sparkle emoji (✨) as UI badges. According to the Hallmark source code in skills/hallmark/references/anti-patterns.md, these patterns signal automated design rather than intentional human craft, resulting in generic interfaces that lack distinctive brand character and often fail accessibility standards.

Does hallmark audit modify my HTML files?

No. The skill definition in skills/hallmark/SKILL.md explicitly configures the audit verb as read-only (lines 26-30). The command parses and analyzes HTML structures to detect anti-patterns but never writes changes to disk, making it safe to run against production files, user-provided snippets, or sensitive codebases without risk of accidental corruption or unintended modifications.

How does the audit command detect genre-specific patterns?

When an HTML file contains a Hallmark stamp declaring a specific genre (e.g., genre: atmospheric), the audit loads genre-specific allowances from skills/hallmark/references/slop-test.md. This mechanism allows the system to suppress certain anti-pattern flags for stylistically appropriate contexts—such as permitting gradient effects in atmospheric designs while strictly prohibiting them in standard corporate layouts—ensuring the audit respects intentional stylistic choices.

Can I integrate hallmark audit into my existing CI pipeline?

Yes. The command exits with status code 1 when critical findings are detected, causing CI jobs to fail automatically. You can capture the markdown output as a build artifact, post it to pull request comments via GitHub Actions, or parse the structured findings to trigger Slack notifications. The read-only nature ensures the audit can run safely on every commit without side effects, while the standardized report format facilitates automated ticket creation or feeding into subsequent hallmark redesign runs for remediation.

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