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

The best practices for writing Hallmark skills require strict adherence to the SKILL.md manifest, mandatory CSS token discipline, rigorous anti-pattern detection through the 58-gate slop-test, and systematic diversification tracking via 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, 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 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 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) 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.

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 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.

Finally, the slop-test runs 58 gates after the build, checking against the blacklist in 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.

/* 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 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 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. 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

hallmark audit ./src/pages/about.html

This command reads 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

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

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, and proceeds with the standard flow.

Component-Scope Implementation

hallmark redesign ./src/components/Button.tsx

This generates two files: Button.tsx containing the component with token-referenced colors, and Button.preview.html showing a vertical stack of all eight interaction states with labels.

Summary

• Respect the manifest: Never modify 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; inline values are prohibited.
• Pass the slop-test: Validate all output against the 58 gates defined in anti-patterns.md before presenting previews.
• Track diversification: Read and update .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 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. 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 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.

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