Nutlope/hallmark Best Practices: A Complete Guide to Disciplined UI Generation

Nutlope/hallmark enforces a disciplined, anti-AI-slop design workflow through token-only styling, mandatory diversification rules, and a rigorous 58-point slop-test gate that ensures production-ready UI generation.

Nutlope/hallmark is a design skill for Claude Code, Cursor, and Codex that structures UI generation around architectural safety rails rather than open-ended prompting. Following Nutlope/hallmark best practices ensures every output passes a systematic 8-stage pipeline while avoiding common AI-generated design pitfalls. The workflow centers on declarative tokens, enforced diversification, and a pre-emit self-critique that rejects substandard artifacts before they reach your codebase.

Architectural Overview

The skill architecture consists of four distinct layers that govern how design decisions are made and validated.

Skill entry point — skills/hallmark/SKILL.md declares metadata, available verbs, and safety rails that prevent destructive operations.

Verb implementations — Actionable commands (audit, redesign, study) live in references/verbs/ and trigger specific pipeline branches without bypassing validation gates.

Design pipeline — A rigid 9-step execution flow (0️⃣ Pre-flight scan → 1️⃣ Genre detection → 2️⃣ Macrostructure selection → 2.6 Theme route → 3️⃣ Load visual rules → 4️⃣ Hero enrichment → 5️⃣ Preview → 6️⃣ Build → 7️⃣ Slop-test → 8️⃣ Stamp & log) ensures consistent output quality.

Reference library — Static assets including 21 macrostructures (references/macrostructures/), 20 catalog themes plus custom variants (references/custom-theme.md), and four genre profiles (editorial, modern-minimal, atmospheric, playful) in references/genres/.

Core Design Pipeline

Every hallmark execution follows a strict sequence defined in SKILL.md. Deviating from this flow violates the safety contract.

The pipeline begins with a pre-flight scan that validates file system state and checks .hallmark/log.json for previous macrostructure and theme selections. This enforces the diversification rule—consecutive runs must differ by paper band, display style, or accent hue.

Next, genre detection scopes the token set and voice profile. The four available genres constrain subsequent choices:

• Editorial — High-contrast, classical type pairings
• Modern-minimal — Spacious layouts, restrained color
• Atmospheric — Texture-forward, immersive visuals
• Playful — Bright palettes, organic shapes

Macrostructure selection loads a single file from references/macrostructures/ containing 21 named page-shapes. The system cross-references .hallmark/log.json to prevent repetition.

Theme routing applies the diversification rule, selecting from 20 catalog themes or a custom branch, ensuring visual variety across iterations.

Essential Development Rules

Six core principles govern all hallmark operations according to the source code:

Safety first — The skill never deletes production files without explicit user confirmation. This is enforced at the SKILL.md configuration level.

Token-only styling — All color and font references must use CSS custom properties from site/css/tokens.css. Inline hex codes or font-family declarations trigger immediate rejection.

Example token usage:

/* Correct: Referencing tokens */
.hero-title {
  color: var(--color-accent);
  font-family: var(--font-display);
}

/* Incorrect: Hard-coded values */
.hero-title {
  color: #ff6b6b;
  font-family: 'Inter', sans-serif;
}

Diversification mandate — The system enforces visual variety through .hallmark/log.json, tracking previous macrostructures and themes across sessions.

Pre-emit self-critique — Every artifact receives a six-axis score; any score below 3 triggers an automatic revision pass before file generation.

Responsive hard floor — All builds must pass four required viewport checks: 320 px, 375 px, 414 px, and 768 px. Failure at any breakpoint returns the build to stage 6.

Zero fabrication — Numbers, testimonials, and logos must be real or explicitly marked as placeholders. The 58-point slop-test (defined in references/slop-test.md) validates this gate.

Practical Usage Examples

Installing the Skill

Install the hallmark skill for your AI coding environment:

npx skills add nutlope/hallmark

This registers the skill metadata and verb table with Claude Code, Cursor, or Codex.

Default Design Flow

Execute a full page design without specifying a verb:

hallmark "Design a modern SaaS landing page for a cloud-monitoring tool."

The system automatically:

• Runs the pre-flight scan
• Detects the modern-minimal genre
• Selects an unused macrostructure from references/macrostructures/
• Chooses a catalog theme (e.g., Coral) obeying diversification rules
• Generates a preview summary
• Builds the page, runs the slop-test, and writes a stamp comment at the top of site/css/tokens.css

Auditing Existing Code

Evaluate existing markup against hallmark standards without modifying files:

hallmark audit ./src/pages/index.html

This produces a ranked punch-list of anti-patterns based on the 58-point checklist in references/slop-test.md.

Redesigning Pages

Preserve existing copy and information architecture while swapping visual systems:

hallmark redesign ./src/pages/about.html --mood sleek

This command:

• Retains all text content and routing logic
• Loads a new macrostructure from references/macrostructures/
• Applies a diversified theme from references/custom-theme.md
• Regenerates token assignments in site/css/tokens.css

Studying Design DNA

Extract structural patterns from existing websites:

hallmark study https://example.com

Returns macrostructure classification, type-pairing analysis, and color anchor identification. Optional output to design.md if requested.

Component-Scope Workflow

For single-element targets, the pipeline switches to component-scope:

hallmark redesign ./src/components/Button.tsx

This generates the component file plus an 8-state preview (Button.preview.html) while maintaining token discipline and diversification tracking in .hallmark/log.json.

Key Configuration Files

Understanding the file tree is essential for advanced customization:

Path	Purpose
skills/hallmark/SKILL.md	Skill metadata, safety rails, and verb table
skills/hallmark/references/verbs/audit.md	Audit implementation logic
skills/hallmark/references/verbs/redesign.md	Redesign workflow specifications
skills/hallmark/references/macrostructures.md	21 available page layouts
skills/hallmark/references/slop-test.md	58-point quality gate checklist
skills/hallmark/references/genres/editorial.md	Genre profile specifications
site/css/tokens.css	Central token definitions (required reference)
.hallmark/log.json	Runtime project memory for diversification tracking

Summary

• Nutlope/hallmark implements a rigid 9-step pipeline (0️⃣ through 8️⃣) that prevents AI-generated design slop through systematic validation.
• All styling must reference tokens from site/css/tokens.css—inline values are prohibited by the compiler.
• The diversification rule enforces visual variety by tracking previous selections in .hallmark/log.json and preventing macrostructure or theme repetition.
• Three primary verbs (audit, redesign, study) provide targeted workflows while maintaining safety rails.
• The 58-point slop-test in references/slop-test.md acts as a mandatory quality gate before final output.
• Component-scope workflows generate 8-state previews alongside single-file components for comprehensive testing.

Frequently Asked Questions

How does Nutlope/hallmark prevent repetitive design outputs?

The skill maintains a project memory file at .hallmark/log.json that records previous macrostructure, theme, and enrichment choices. According to the diversification rule specified in SKILL.md, consecutive runs must differ on at least one axis—paper band, display style, or accent hue—ensuring unique visual outcomes across iterations.

What happens if a design fails the slop-test?

Any artifact scoring below 3 on the six-axis self-critique, or failing the 58-point checklist in references/slop-test.md, triggers an automatic revision pass. The system returns to stage 6 (Build) and regenerates the affected components before attempting the slop-test again, preventing low-quality code from reaching your repository.

Can I use Nutlope/hallmark for individual components rather than full pages?

Yes. When the brief targets a single UI element, the pipeline switches to component-scope mode. As documented in SKILL.md under "When the brief is a component, not a page," the system generates the component file plus an 8-state preview HTML file for comprehensive interaction testing while maintaining the same token discipline and diversification rules.

Where are the visual tokens defined and how strict is the token-only rule?

All color and font tokens live in site/css/tokens.css. The token-only rule is absolute—inline hex codes, RGB values, or font-family declarations are prohibited and will cause the build to fail. Every visual property must reference a CSS custom property (e.g., var(--color-accent), var(--font-display)) to ensure consistency and themeability.

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