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

> Master Nutlope/hallmark best practices for disciplined UI generation. Learn token-only styling diversification rules and slop-tests for production-ready designs.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) configuration level.

**Token-only styling** — All color and font references must use CSS custom properties from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). Inline hex codes or font-family declarations trigger immediate rejection.

Example token usage:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md)) validates this gate.

## Practical Usage Examples

### Installing the Skill

Install the hallmark skill for your AI coding environment:

```bash
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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)

### Auditing Existing Code

Evaluate existing markup against hallmark standards without modifying files:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md).

### Redesigning Pages

Preserve existing copy and information architecture while swapping visual systems:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md)
- Regenerates token assignments in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)

### Studying Design DNA

Extract structural patterns from existing websites:

```bash
hallmark study https://example.com

```

Returns macrostructure classification, type-pairing analysis, and color anchor identification. Optional output to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) if requested.

### Component-Scope Workflow

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

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

```

This generates the component file plus an 8-state preview ([`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.html)) while maintaining token discipline and diversification tracking in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).

## Key Configuration Files

Understanding the file tree is essential for advanced customization:

| Path | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Skill metadata, safety rails, and verb table |
| [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) | Audit implementation logic |
| [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) | Redesign workflow specifications |
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | 21 available page layouts |
| [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) | 58-point quality gate checklist |
| [`skills/hallmark/references/genres/editorial.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/genres/editorial.md) | Genre profile specifications |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Central token definitions (required reference) |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) that records previous macrostructure, theme, and enrichment choices. According to the diversification rule specified in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.