How to Audit Existing Code with Hallmark: Detecting AI-Generated Design Patterns

Use hallmark audit <target> 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, 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), 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. 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.

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. 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 (or 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, 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:

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:

hallmark audit site/_tests/**/*.html

CI Integration

Redirect output to a file for continuous integration pipelines or manual review workflows:

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 — Contains the complete specification for the audit verb, including severity rules and genre-aware logic.
• skills/hallmark/references/anti-patterns.md — Catalogs all AI-generated anti-patterns that trigger findings during inspection.
• skills/hallmark/references/slop-test.md — Defines genre-specific overrides and grading thresholds used to classify violations.
• 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 <target>.
• 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 and 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 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 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.

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