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

> Learn how to audit UI for AI-slop patterns using the hallmark audit command. Analyze HTML files against anti-patterns to generate a markdown punch-list of violations without altering source code.

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

---

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

```bash
hallmark audit path/to/index.html

```

To audit multiple pages using glob patterns:

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

```

Redirect the output to save the report:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). A typical output identifies specific violations and remediation steps:

```text

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

```yaml

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

```javascript
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)** – Defines genre-specific overrides used when stamps declare atmospheric or other stylistic genres
- **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/sections.css)** – Styles the audit checklist interface through the `.audit-check` family of selectors
- **[`site/_tests/verbs/audit/audit-report.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/audit/audit-report.md)** – Contains example audit reports generated by the test suite for reference
- **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) exemptions when properly declared in stamps
- Integration with **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.