# Main Features of the Nutlope Hallmark Project: Anti-AI-Slop Design Pipeline

> Discover Hallmark project features: token-first styling, 21 macrostructure variations, and a 58-gate slop-test. Ensure AI generates hand-crafted interfaces, not generic templates.

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

---

**Hallmark is a design skill library that enforces token-first styling, 21 macrostructure variations, and a 58-gate "slop-test" to ensure AI coding assistants generate hand-crafted looking interfaces rather than generic templates.**

The Nutlope/hallmark repository provides a rule-driven design system for AI coding assistants including Claude Code, Cursor, and Codex. It transforms generic AI-generated UI into distinctive, professionally designed components through strict design disciplines enforced at every stage of the generation pipeline.

## Four Entry Verbs for Design Workflows

Hallmark operates through four distinct command verbs defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), each targeting a specific phase of the design lifecycle:

- **build** – The default verb that runs the full design flow, executing a pre-flight scan, selecting a macrostructure, and emitting a complete HTML/CSS page.
- **audit** – Scores existing UI against anti-patterns without making edits, generating a ranked punch-list of violations. Detailed specifications live in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md).
- **redesign** – Revamps an existing page while preserving copy, routes, and branding, as documented in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md).
- **study** – Extracts the "DNA" (macrostructure, type-pairing, colour anchor) from a screenshot or live URL, optionally emitting a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file.

Install the skill via npm and run the default build:

```bash
npx skills add nutlope/hallmark
hallmark build ./my-app

```

## Pre-Flight Scan and System Detection

Before any design work begins, Hallmark executes a **pre-flight scan** that detects existing fonts, palettes, motion libraries, spacing scales, and framework conventions (Next.js, Astro, Vue, Svelte, or vanilla). This scan preserves the project's existing design system rather than clobbering it with generic defaults.

The scan logic is defined in Section 0 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), ensuring that subsequent theme application respects the target repository's architectural constraints.

## Macrostructure Selection and Diversification Rules

Hallmark selects from **21 named macrostructures** (e.g., *Marquee Hero*, *Stat-Led*) recorded in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Each selection is stamped into the generated CSS for traceability.

To prevent template fatigue, **diversification rules** mandate that consecutive runs must differ on at least one axis: macrostructure, theme (paper-band, display-style, accent-hue), nav archetype, or footer archetype. This ensures visual variety across multiple generations.

## Theme Routing and Token-First Architecture

The system supports two theme branches:

- **Catalog themes** – One of 20 predefined themes selected by default.
- **Custom themes** – A bespoke OKLCH palette paired with free-font selection when the brief signals unique brand requirements, as implemented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md).

All styling adheres to **token-first discipline** defined in Discipline 3 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md). Colors and fonts are referenced exclusively through CSS custom properties (e.g., `var(--color-accent)`). Inline color values are forbidden; new values must be added as named tokens in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). This creates a portable, maintainable design system that survives framework migrations.

## Responsive and Typography Non-Negotiables

Hallmark enforces strict responsive validation at 320px, 375px, 414px, and 768px breakpoints as specified in Discipline 5 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and detailed in [`skills/hallmark/references/responsive.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/responsive.md). The rules prohibit horizontal scroll, multi-line clickable text, and rigid grid tracks.

**Typography purity** rules, documented in Discipline 6 and [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md), forbid italicized headings. Emphasis must be expressed via weight, color, or underline rather than font-style variations.

## The Slop-Test Quality Gate

After code generation, Hallmark subjects output to a **58-gate automated checklist** defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). The gates score philosophy, hierarchy, execution, specificity, restraint, and variety. Any output scoring below 3 on any gate triggers an automatic revision pass, ensuring that "AI slop"—generic gradients, centered text monotony, and invented metrics—never reaches production.

## Component-Scope Development

For single-element briefs (buttons, cards, modals), Hallmark emits the component file plus an **8-state demo wrapper** that validates hover, active, focus, disabled, loading, error, success, and empty states. This workflow is detailed in Sections 0-2 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

Run a component-level redesign with a mood flag:

```bash
hallmark redesign ./components/Button.tsx --mood modern-minimal

```

This produces [`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx) (or the framework-appropriate equivalent) alongside [`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.html), demonstrating all interaction states while respecting the genre constraints defined in [`skills/hallmark/references/genres/modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/genres/modern-minimal.md).

## Study and Audit Commands

Extract design patterns from existing sites or validate current implementations:

```bash

# Audit existing UI for anti-patterns

hallmark audit ./src/pages/landing.html

# Study a live URL to extract design DNA

hallmark study https://example.com

```

The `study` verb analyzes macrostructure, type-pairing, and color anchors, enabling Hallmark to replicate or riff on existing design languages without direct copying.

## Summary

The Nutlope/hallmark project delivers a comprehensive design skill architecture that eliminates AI-generated visual sameness through:

- **Four specialized verbs** (`build`, `audit`, `redesign`, `study`) targeting different design phases.
- **21 macrostructures** with enforced diversification rules to prevent template repetition.
- **Token-first CSS architecture** using [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) to ban inline values and ensure design system portability.
- **58-gate slop-test** quality assurance that automatically rejects low-quality outputs.
- **Component-scope generation** with 8-state validation for interactive elements.
- **Pre-flight detection** that preserves existing project conventions.

## Frequently Asked Questions

### What makes Hallmark different from other AI design tools?

Hallmark is not a generator but a **discipline layer** that sits between AI assistants and code output. According to the [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) source, it enforces 58 specific quality gates and token-first architecture that generic AI coding assistants typically ignore. The system is designed to detect and prevent "AI slop"—visual patterns like generic gradients, centered text walls, and invented metrics—through automated validation rather than manual prompting.

### How does Hallmark ensure designs don't look repetitive?

The diversification rule set in Sections 2-2.6 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) mandates that consecutive runs must differ on at least one axis: macrostructure, theme, navigation archetype, or footer archetype. Additionally, the system maintains a catalog of 21 distinct macrostructures ranging from *Marquee Hero* to *Stat-Led*, ensuring that the AI cannot fall back on the same centered-hero layout repeatedly.

### Can Hallmark work with existing design systems?

Yes. The pre-flight scan defined in Section 0 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) detects existing fonts, color palettes, motion libraries, and framework choices (Next.js, Astro, Vue, Svelte, or vanilla) before generating any code. This allows Hallmark to extend existing design systems rather than overwriting them, producing output that respects the project's established architectural patterns.

### What is the "slop-test" and how strict is it?

The slop-test is a 58-gate automated validation defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) that scores generated code on philosophy, hierarchy, execution, specificity, restraint, and variety. Any output scoring below 3 on any gate triggers an automatic revision. This strict threshold ensures that only hand-crafted quality designs pass the pipeline, effectively filtering out generic AI-generated UI patterns.