# How to Audit Existing Code with Hallmark: Detecting AI-Generated Design Patterns > Audit existing code with Hallmark to detect AI-generated design patterns, structural drift, and compliance issues in HTML/CSS. Get categorized findings and actionable fixes. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-16 --- **Use `hallmark audit ` to scan HTML and CSS files for AI-generated anti-patterns, structural drift, and compliance violations, receiving categorized findings with severity levels and concrete fixes.** Hallmark is an open-source tool from the `Nutlope/hallmark` repository that helps developers identify AI-generated design artifacts in existing codebases. When you audit existing code with Hallmark, the tool inspects your HTML and CSS against a curated catalog of anti-patterns and structural fingerprints, producing actionable reports that distinguish between critical violations, major tells, and minor taste issues. ## Understanding the Hallmark Audit Command The `audit` verb in Hallmark evaluates one or more HTML and CSS pages to determine how well they follow the tool’s anti-pattern rules and structural "fingerprint" requirements. According to the specification in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the command reads each target file and groups findings into three severity tiers: - **Critical** — Violations that register as "slop" and would be rejected outright, such as using the default AI template or stamp declarations that do not match the actual layout. - **Major** — Clear indicators of AI-generated design, including missing asymmetry, incorrect genre-specific cues, or absent stamps in design-system projects. - **Minor** — Small taste issues such as token drift on system-less projects or repetitive macrostructures across multiple pages. Each finding includes four components: the **Tell** (named anti-pattern from [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md)), the **Where** (file path and line range), the **Severity**, and a **Fix** (one-line concrete correction). ## What Hallmark Checks During an Audit ### Anti-Pattern Detection Hallmark matches pages against a catalog of known AI-generated cues defined in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). These include visual clichés like centered hero sections, three equal-width feature cards, and generic placeholder copy that signal automated design generation. ### Structural Fingerprint Verification The tool verifies that your page does not unintentionally fallback to the default AI template. If Hallmark detects template drift, it raises a **critical** structural finding labeled `template-drift` according to the validation logic in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). ### Stamp Verification When your CSS contains a Hallmark stamp comment (`/* Hallmark · macrostructure: … */`), the audit cross-references this declaration against the rendered layout. A mismatch between the claimed macrostructure and the actual implementation triggers a **critical** `stamp lies` finding. ### Genre-Aware Validation Hallmark applies genre-specific rules documented in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). For example, a radial-gradient background registers as a **critical** tell for the *editorial* genre but remains permissible for *atmospheric* designs. These contextual overrides prevent false positives when auditing diverse project types. ### Design-System Compliance When a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)) file exists in your project root, Hallmark enforces strict adherence to the system’s theme, token, and macrostructure choices. Violations such as *design-system drift* or *missing system reference* are flagged as **critical** or **major** respectively, ensuring consistency across large codebases. ### Variety Drift Detection On projects without a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), Hallmark monitors for excessive homogeneity. When many pages share identical macrostructures or themes, the tool issues **minor** findings to encourage visual diversity and prevent the "same-page syndrome" common in AI-generated sites. ## Running a Hallmark Audit ### Single File Inspection Target a specific HTML file to receive immediate feedback on that page’s design integrity: ```bash hallmark audit site/_tests/03-maple-bakery/index.html ``` ### Batch Auditing Audit entire directories or test suites using glob patterns to evaluate consistency across your project: ```bash hallmark audit site/_tests/**/*.html ``` ### CI Integration Redirect output to a file for continuous integration pipelines or manual review workflows: ```bash hallmark audit site/_tests/**/*.html > audit-report.txt ``` The command outputs a concise report to stdout, concluding with a summary in the format `2 critical · 5 major · 3 minor` that quantifies your codebase’s design health. ## Interpreting Audit Results Each finding in the audit report provides actionable intelligence: 1. **Tell** — References the specific anti-pattern name from the catalog. 2. **Where** — Pinpoints the exact file path and line range requiring attention. 3. **Severity** — Indicates the urgency level (critical, major, or minor). 4. **Fix** — Offers a concrete, one-line correction to resolve the issue. The final summary line aggregates all findings by severity, allowing you to track technical debt and prioritize remediation efforts. ## Configuration and Key Files Hallmark’s audit behavior is governed by several reference files: - **[`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md)** — Contains the complete specification for the audit verb, including severity rules and genre-aware logic. - **[`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md)** — Catalogs all AI-generated anti-patterns that trigger findings during inspection. - **[`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)** — Defines genre-specific overrides and grading thresholds used to classify violations. - **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)** — Optional project-level design system definition; when present, audit validates compliance with its tokens, fonts, and macrostructure families. - **`site/_tests/…/*.html`** — Example pages that demonstrate expected audit behavior; the stamp comment inside each CSS file provides the source of macrostructure metadata. ## Summary - **Hallmark’s `audit` verb** inspects HTML and CSS for AI-generated patterns using `hallmark audit `. - **Severity levels** categorize findings as critical (rejection-worthy), major (clear AI tells), or minor (taste issues). - **Six verification layers** check anti-patterns, structural fingerprints, stamp validity, genre rules, design-system compliance, and variety drift. - **Key files** including [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) configure audit behavior and compliance rules. - **CI-ready output** supports batch processing and file redirection for automated testing pipelines. ## Frequently Asked Questions ### What does the "stamp lies" finding mean? The **stamp lies** finding indicates a **critical** mismatch between your CSS stamp comment (`/* Hallmark · macrostructure: … */`) and the actual rendered layout. When you audit existing code with Hallmark, the tool verifies that the macrostructure claimed in the stamp matches the visual implementation; if they differ, Hallmark flags this as template drift requiring immediate correction. ### Can I audit multiple files at once? Yes. Hallmark supports glob patterns and directory traversal for batch auditing. Run `hallmark audit site/_tests/**/*.html` to evaluate all HTML files in a test suite simultaneously, or use shell wildcards to target specific directories. The command aggregates findings across all targets and provides a unified severity summary. ### How does Hallmark handle projects without a design system? When no [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file exists, Hallmark operates in "variety mode," encouraging design diversity across pages. Instead of enforcing strict system compliance, the tool issues **minor** findings when it detects repetitive macrostructures or token drift across multiple files, prompting you to introduce intentional variation rather than accidental uniformity. ### What makes a finding "critical" versus "major"? **Critical** findings in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) represent violations that would be rejected as "slop," including default template usage or stamp mismatches. **Major** findings identify clear AI-generated tells such as missing asymmetry or incorrect genre cues, while **minor** findings address subtle taste issues like token inconsistencies on non-system projects.