# How to Avoid Anti-Patterns When Working with Nutlope/hallmark: A Complete Guide

> Learn how to avoid anti-patterns when working with Nutlope/hallmark. Master pre-flight scans macrostructure rotation theme diversification and the 58-gate slop-test for better UI development.

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

---

**Avoid anti-patterns in Nutlope/hallmark by respecting its pre-flight scan, macrostructure rotation, theme diversification, and the 58-gate slop-test that automatically flags generic AI-generated UI tells.**

Nutlope/hallmark is a design skill that enforces strict discipline to prevent generated UI from falling into recognizable "AI-generated" patterns. To avoid anti-patterns when working with this system, you must follow its architectural contracts including the pre-flight scan, macrostructure selection, and comprehensive slop-testing that governs every output.

## Understanding Hallmark's Anti-Pattern Detection System

The skill operates through a structured pipeline defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Each stage is designed to catch specific categories of anti-patterns before they reach production.

### The Pre-Flight Scan

Before generating any code, Hallmark reads existing project signals from [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), established fonts, palette definitions, motion libraries, and framework choices. This scan, documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) at lines 45-60, determines what design elements to preserve and establishes constraints that prevent generic overrides.

### Macrostructure Selection and Rotation

Hallmark maintains an index of 21 named macrostructures (e.g., *Marquee Hero*, *Stat-Led*) in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Each run must select one macrostructure and record it in a CSS comment stamp. The diversification rules require that this stamp differ from any previous run in the same project, preventing repetitive layout patterns.

### Theme Route Configuration

The system chooses between **catalog** themes (one of 20 named themes) or **custom** palettes when the brief signals bespoke requirements. Themes rotate across three axes: paper-band, display-style, and accent-hue. The custom theme workflow is documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), while individual theme files reside under `references/themes/`.

## Critical Anti-Patterns to Avoid in Hallmark

The master list in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) defines 58 specific gates. Here are the most common violations and their fixes:

### Visual Design Tells

**Purple-gradient heroes** are the single most recognizable AI aesthetic. Hallmark enforces single accent hues and prohibits hero gradients entirely (lines 11-16).

**Inter-everywhere** destroys typographic hierarchy by using one font for both display and body. The system requires pairing distinct display faces with refined body faces (lines 17-22).

**Pure black and pure white** create synthetic-looking flat surfaces. Instead, tint surfaces toward the anchor hue to achieve depth (lines 53-58).

**Gradient headlines** are classic AI tells. Use solid ink and emphasize through weight or underline rather than gradient fills (lines 35-40).

### Layout and Structure Tells

**3-column feature grids** with identical columns and icons scream templated design. Vary column widths, mix card heights, and move icons inline to break the grid (lines 23-28).

**Card-in-card** nesting adds unnecessary visual noise. Maintain a single containment layer per component (lines 29-34).

**Full-viewport centered heroes** represent the default LLM landing page. Size heroes to their content, bias alignment left or right, and add substantial copy (lines 47-52).

### Content and Typography Tells

**Italic headers** indicate AI-generated emphasis. Keep headings roman and use weight, color, or underline for emphasis instead (lines 39-44).

**Invented metrics** erode user trust. Use placeholder dashes (`—`) or request real data from users rather than fabricating statistics (lines 9-15).

### Interaction and Technical Tells

**Hover-only affordances** fail accessibility for touch users. Provide `focus-visible` states for every hover interaction (lines 75-78).

**Lottie shortcuts** introduce heavy runtime overhead for simple motion. Build custom CSS or SVG animations instead (lines 49-56).

**Mid-render token improvisation** breaks design systems. All colors and fonts must reference tokens (`var(--color-accent)`). The system aborts if it detects inline values and requires adding missing tokens to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) first (lines 33-40).

## Enforcement Mechanisms That Prevent Anti-Patterns

Hallmark doesn’t just document anti-patterns—it actively prevents them through automated checks.

### CSS Stamping and Diversification Rules

Every generated CSS file begins with a comment recording the macrostructure, theme, navigation, footer, and slop-test scores. This stamp appears as:

```css
/* Hallmark · macrostructure: Stat-Led · theme: Coral
 * nav: N5 Floating pill · footer: Ft5 Statement
 * pre‑emit critique: P5 H4 E5 S4 R5 V5 */

```

This stamp is read on subsequent runs to enforce diversification rules: macrostructures must change, themes must differ on at least one axis, and nav/footer archetypes must rotate (lines 70-82 in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)).

### Pre-Emit Self-Critique Scoring

Before returning any artifact, Hallmark scores output on six axes: Philosophy, Hierarchy, Execution, Specificity, Restraint, and Variety. Any score below 3 triggers an automatic revision pass (lines 44-48).

### Locked Token System

Once a theme is selected, all color and font references must use tokens. The skill maintains strict token discipline in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and will not proceed with inline values.

### Component-Scope Discipline

For component generation, Hallmark enforces an 8-state demo wrapper and a *State discipline* checklist. Every interactive component must ship code for all required states including loading, error, empty, and success (lines 78-81).

### Responsive Non-Negotiables

The system validates that clickable affordances never wrap to two lines, layouts never use `100vw` widths, and Largest Contentful Paint (LCP) elements are not lazy-loaded (lines 41-49).

## Practical Workflow Examples

Run an audit to identify existing anti-patterns:

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

```

Redesign while preserving the existing token system:

```bash
hallmark redesign ./src/pages/pricing.html --mood modern-minimal

```

Extract design DNA from a live site and build new pages:

```bash
hallmark study https://example.com
hallmark build --from-dna

```

## Summary

- **Respect the pre-flight scan** in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (lines 45-60) to preserve existing project signals and avoid generic overrides.
- **Rotate macrostructures** from the 21 options in [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) and never reuse the same structure consecutively.
- **Follow token discipline** by referencing [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for all colors and fonts, avoiding inline values entirely.
- **Pass the 58-gate slop-test** defined in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) by avoiding purple gradients, Inter-only typography, card-in-card nesting, and invented metrics.
- **Use CSS stamping** to track diversification across runs and ensure nav/footer archetypes from [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) replace generic AI patterns.

## Frequently Asked Questions

### What happens if Hallmark detects an anti-pattern during generation?

Hallmark automatically revises the output before returning it. The pre-emit self-critique scores the code on six axes (Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety), and any score below 3 triggers a revision pass. Additionally, the 58-gate slop-test flags specific tells like purple gradients or hover-only affordances for immediate correction.

### How does Hallmark ensure I don't reuse the same layout repeatedly?

The system enforces diversification rules through CSS comment stamps. Each generation records the macrostructure, theme, and component archetypes used. Subsequent runs must select different macrostructures, vary themes on at least one of three axes (paper-band, display-style, accent-hue), and rotate navigation and footer patterns from the component cookbook.

### Can I use custom colors that aren't in the default theme catalog?

Yes, but you must follow the custom theme workflow documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). When the brief signals a bespoke look, you can define a custom palette, but all colors must still reference tokens in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). The skill prohibits inline color values even in custom themes.

### Where can I find the complete list of anti-patterns to avoid?

The master list resides in [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). This file documents all 58 gates including visual tells (purple gradients, pure black/white), layout patterns (3-column grids, full-viewport heroes), typography issues (italic headers, Inter-everywhere), and technical anti-patterns (Lottie shortcuts, mid-render token improvisation).