# Best Practices for Writing Hallmark Skills in Nutlope/hallmark: A Complete Developer Guide

> Master Hallmark skills in Nutlope/hallmark with best practices. Learn manifest adherence, CSS token discipline, anti-pattern detection, and diversification tracking for superior AI designs.

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

---

**The best practices for writing Hallmark skills require strict adherence to the [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifest, mandatory CSS token discipline, rigorous anti-pattern detection through the 58-gate slop-test, and systematic diversification tracking via [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json) to prevent repetitive AI-generated designs.**

The Nutlope/hallmark repository provides a self-contained design engine that eliminates AI-generated "slop" through disciplined architectural patterns. Following the best practices for writing skills ensures that every Hallmark skill invocation produces unique, token-compliant, and production-ready designs while maintaining strict separation between component-scope and page-scope implementations.

## Mastering the Skill Manifest and Core Verbs

The foundation of every Hallmark skill resides in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which serves as the single source of truth for the skill's contract and execution model.

### Understanding the SKILL.md Structure

The manifest file declares the skill name, description, and version metadata. It also documents the **verb table** that the harness (Claude-Code, Cursor, or Codex) uses to invoke specific behaviors. Never edit the metadata fields—`name`, `description`, or `version`—unless you are explicitly bumping the version number. When adding new verbs, extend the verb table and provide a matching reference file under `references/verbs/`.

### The Three Explicit Verbs

Hallmark operates through three primary commands defined in the skill manifest:

- **audit**: Inspects existing code against the anti-patterns blacklist and returns a ranked punch-list of violations.
- **redesign**: Executes the full 7-step design pipeline while enforcing diversification rules.
- **study**: Analyzes existing implementations to inform design decisions without generating new code.

## The 7-Step Design Flow Pipeline

The default verb runs a strict pipeline defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) under "Design flow (default)". Each step must emit a clear human-readable banner before proceeding.

### Step 1: Pre-flight Scan

Before any design work begins, the skill inspects the existing codebase for fonts, palette definitions, motion libraries, spacing systems, and framework detection. It writes these findings to a [`preflight.json`](https://github.com/Nutlope/hallmark/blob/main/preflight.json) cache file. You must preserve existing tokens, palettes, and spacing values, only adding new ones when explicitly required. If the user asks to ignore the existing project, skip the scan and announce this decision.

### Step 2-4: Audience Definition, Genre Detection, and Macrostructure Selection

First, establish the audience, use-case, and tone. Then select from four static genre files located in the references folder: `editorial`, `modern-minimal`, `atmospheric`, or `playful`. If no genre signal is present in the brief, default to **editorial**.

Next, select a macrostructure from the 21 named options under `references/macrostructures/`. Always read the slim index ([`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)) first, then load only the chosen macrostructure file. The selection must differ from the macrostructure stamped on any existing Hallmark file or from the last entry in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).

### Step 5-7: Theme Routing, Enrichment, and Slop-Testing

**Theme routing** offers two paths: **catalog** (20 named themes with genre-specific clusters) or **custom** (tuned palette plus font pairing). Only trigger the custom route upon explicit user signals such as brand colors or "custom palette" requests. Otherwise, silently pick a catalog theme that differs on at least one axis (paper band, display style, or accent hue).

**Hero enrichment** only loads [`hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/hero-enrichment.md) when the brief explicitly requests imagery or demo videos. If no imagery signal is detected, emit a typography-only hero using the placeholder strategy defined in [`assets.md`](https://github.com/Nutlope/hallmark/blob/main/assets.md).

Finally, the **slop-test** runs 58 gates after the build, checking against the blacklist in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md). The build must pass all gates before presenting the preview.

## Token Discipline and Component Architecture

### CSS Token Requirements

After locking a theme, every color and font must be referenced via CSS tokens. Inline values are strictly forbidden.

```css
/* Correct: Token-referenced values */
background-color: var(--color-accent);
font-family: var(--font-display);

/* Forbidden: Inline values */
background-color: #c0392b;
font-family: 'Inter', sans-serif;

```

When you need a new token, add it to the central token block at [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) first, then reference it in your implementation.

### Component-Scope vs Page-Scope

When the brief targets a single UI element rather than a full page, the flow switches to component-scope mode. This emits two files: the component implementation and an 8-state preview wrapper. You must follow the stricter state checklist: **default**, **hover**, **focus**, **active**, **disabled**, **loading**, **error**, and **success**.

## Anti-Patterns and Quality Assurance

### The 58-Gate Slop-Test

The file [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) enumerates critical "tells" such as purple-gradient heroes and three-column grids. Treat this list as a blacklist; never emit a flagged pattern. After code generation, run the slop-test automatically and fix any failures before presenting the preview.

### Diversification Rules

Consecutive Hallmark runs must differ in macrostructure, theme axes, nav archetype, and footer archetype. The system tracks prior builds in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). Before picking new parameters, read the log and announce the rotation decision to the user, for example: "Last macrostructure was Bento Grid → picking Marquee Hero."

## Practical Implementation Examples

### Auditing an Existing Page

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

```

This command reads [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and returns a ranked punch-list:

```

[critical] Purple-gradient hero — src/pages/about.html:12
  Why: recognized AI tell.
  → Fix: use a single accent hue and a solid hero background.

```

### Running the Default Design Flow

```bash
hallmark design ./src

```

This executes the full 7-step pipeline: Pre-flight scan, audience/use-case/tone definition, genre selection, macrostructure choice, theme routing, enrichment, preview generation, and slop-testing.

### Redesigning with Custom Theme Signals

```bash
hallmark redesign ./src --mood playful

```

When Hallmark detects the custom-theme signal, it asks: "Do you want a tuned palette (anchor = #c0392b) or a fully bespoke design?" After confirmation, it builds an OKLCH palette, updates [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), and proceeds with the standard flow.

### Component-Scope Implementation

```bash
hallmark redesign ./src/components/Button.tsx

```

This generates two files: [`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx) containing the component with token-referenced colors, and [`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.html) showing a vertical stack of all eight interaction states with labels.

## Summary

- **Respect the manifest**: Never modify [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) metadata without version bumping, and extend verbs only through the proper reference file structure.
- **Enforce token discipline**: Reference all colors and fonts via CSS variables defined in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css); inline values are prohibited.
- **Pass the slop-test**: Validate all output against the 58 gates defined in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) before presenting previews.
- **Track diversification**: Read and update [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to ensure consecutive runs differ in macrostructure, theme, and archetype selections.
- **Scope appropriately**: Use component-scope mode (with 8-state checklists) for single UI elements, and page-scope (7-step pipeline) for full layouts.

## Frequently Asked Questions

### What happens if the slop-test detects an anti-pattern?

The build forces a revision before any code is presented to the user. Hallmark will reference the specific gate failure from [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and require you to fix the violation, such as replacing a purple-gradient hero with a solid background using a single accent hue.

### How does Hallmark prevent repetitive designs across multiple runs?

The system implements mandatory diversification rules tracked in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). Before selecting parameters, Hallmark reads the log to ensure the new macrostructure, theme axes, nav archetype, and footer archetype differ from previous entries. It announces these rotation decisions to maintain visual variety.

### Can I use custom colors that aren't in the default token set?

Yes, but you must follow token discipline. Add the new color to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) first, then reference it via `var(--your-new-token)`. Never use inline hex values or raw font names in the final output, even when building custom palettes from OKLCH color spaces.

### What is the difference between the catalog and custom theme routes?

The **catalog** route selects from 20 pre-defined themes organized by genre-specific clusters, choosing options that differ on at least one axis from previous runs. The **custom** route builds a tuned palette and font pairing from scratch, but only triggers when the brief contains explicit signals like brand colors or "custom palette" requests, often requiring a short follow-up confirmation from the user.