How the Nutlope Hallmark Architecture Is Structured: A Complete Guide

The Nutlope Hallmark architecture is organized into four distinct layers—metadata, skill definition, reference library, and demo site—that together form a declarative design engine for AI coding assistants.

Hallmark is a design-skill package that integrates with Claude Code, Cursor, and Codex to generate high-quality UI code. Understanding its architecture helps developers customize the skill, debug outputs, or extend its capabilities. This guide breaks down each layer and explains how they interact at runtime.

---

Architecture Overview

The Nutlope Hallmark architecture separates concerns into four layers, each with a specific purpose and core artifacts:

Layer	Purpose	Core Artifacts
Metadata & entry point	Defines the skill for host assistants	package.json
Skill definition	Declares verbs, design flow, and safety rails	skills/hallmark/SKILL.md
Reference library	Stores declarative knowledge and discipline rules	skills/hallmark/references/
Demo site	Showcases outputs and provides visual QA	site/index.html, site/css/, site/_tests/

These layers are bundled by npm and installed via a single npx command.

---

Layer 1: Package Metadata

The package.json file marks Hallmark as an ES module ("type": "module") and declares the skill entry point for AI assistants.

{
  "name": "hallmark",
  "version": "1.1.0",
  "skill": {
    "entry": "skills/hallmark/SKILL.md",
    "references": "skills/hallmark/references",
    "harnesses": ["claude-code","cursor","codex"]
  },
  "scripts": {
    "serve": "python3 -m http.server --directory site 4173"
  }
}

Key fields:

• skill.entry – Points to the main skill definition
• skill.references – Declares the reference library path
• skill.harnesses – Lists supported AI assistants
• scripts.serve – Local server for demo site development

Source: [package.json](https://github.com/Nutlope/hallmark/blob/main/package.json)

---

Layer 2: Skill Definition

skills/hallmark/SKILL.md serves as the single source of truth for Hallmark's public API. It declares:

• Default verb (build) and explicit verbs (audit, redesign, study)
• Design flow: pre-flight scan → macrostructure selection → theme routing → visual rules → enrichment → preview → slop-test
• Safety rails: no file deletions without confirmation, token-only color usage, mandatory 8-state component demos

All procedural steps are implemented by reading reference files from the library. The assistant parses SKILL.md to understand which verb was invoked and which rules to apply.

Source: [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)

---

Layer 3: Reference Library

The skills/hallmark/references/ directory contains declarative knowledge that drives every generation. This token-efficient design loads files only when needed.

Sub-folder	Content
macrostructures/	21 named page patterns (e.g., Marquee Hero, Stat-Led)
themes/	20 catalog themes (e.g., Bloom, Cobalt) plus custom-theme logic
genres/	Four genre files dictating tone and theme clusters
slop-test.md	58-gate quality checklist
anti-patterns.md	Blacklist of forbidden UI patterns
component-cookbook.md	Index of component archetypes and routing tables
*.md files	Discipline-specific rules (typography, color, motion)

On-Demand Loading Example

When generating a landing page, Hallmark might load:

1. references/macrostructures/05-marquee-hero.md for structure
2. references/themes/bloom.md for visual styling
3. references/typography.md for type rules

This selective loading keeps token consumption low and generation deterministic.

Source: references/

---

Layer 4: Demo Site

The site/ folder is a self-contained static site that:

• Provides live previews of every macrostructure and theme (site/_tests/)
• Contains the central CSS token sheet (site/css/tokens.css)
• Hosts HTML/CSS/JS examples for visual debugging

Run the local server with:

npm run serve

# Serves at http://localhost:4173

The demo site also supports Hallmark's self-audit runs, allowing visual verification before code generation.

Source: [site/index.html](https://github.com/Nutlope/hallmark/blob/main/site/index.html)

---

Runtime Execution Flow

Understanding how the Nutlope Hallmark architecture operates at runtime reveals its deterministic design:

1. Installation – npx skills add nutlope/hallmark copies SKILL.md and references/ into the assistant's skill directory
2. Invocation – Assistant reads SKILL.md to parse the verb (hallmark, hallmark audit, etc.)
3. Pre-flight scan – Analyzes package.json, tailwind.config.*, and existing tokens.css to preserve project context
4. Macrostructure & theme selection – Consults macrostructures.md and genre/theme files, respecting diversification rules from .hallmark/log.json
5. Rule loading – Fetches only required reference files for the chosen combination
6. Code generation – Emits HTML, CSS (using token variables), and optional JS with metadata comments
7. Slop-test – Validates against 58 gates; revises if any fail
8. Preview & delivery – Returns concise preview block followed by final assets

Diversification state persists in .hallmark/log.json to enforce variety across runs.

---

Key Files Reference

Path	Role in Architecture
package.json	Skill declaration and installation metadata
skills/hallmark/SKILL.md	Core API: verbs, flow, safety rails
skills/hallmark/references/	Declarative knowledge library
site/css/tokens.css	Central design token sheet
site/_tests/	Visual QA examples
.hallmark/log.json	Generated diversification log

---

Usage Examples

Install and use Hallmark across its three verbs:

# Install the skill

npx skills add nutlope/hallmark

# Default: build new UI from brief

hallmark "design a SaaS landing page for a dev-ops tool"

# Audit existing page for violations

hallmark audit ./public/index.html

# Redesign with mood preservation

hallmark redesign ./src/pages/home.tsx --mood modern-minimal

# Extract design DNA from live URL

hallmark study https://www.usehallmark.com/examples/cobalt-01/

Each command follows the runtime flow above, emitting self-documented files that respect Hallmark's "anti-AI-slop" discipline.

---

Summary

• Four-layer architecture: metadata → skill definition → reference library → demo site
• Declarative design: All rules live in lightweight markdown files loaded on demand
• Token efficiency: Selective reference loading keeps generations fast and deterministic
• Quality gates: 58-check slop-test ensures output meets Hallmark standards
• Extensible structure: Adding new macrostructures or themes requires only new markdown files in references/

---

Frequently Asked Questions

How does Hallmark decide which macrostructure and theme to use?

Hallmark consults references/macrostructures/ and references/themes/ after a pre-flight scan of your project. It checks .hallmark/log.json to avoid recent selections and enforce diversification. The genre file (from references/genres/) further constrains compatible theme clusters.

Can I add custom themes or macrostructures to Hallmark?

Yes. The Nutlope Hallmark architecture treats all design knowledge as declarative markdown. Create a new file in references/macrostructures/ or references/themes/ following the existing format, and Hallmark will include it in the selection pool without code changes.

What happens if a generation fails the slop-test?

Hallmark runs the full 58-gate checklist from references/slop-test.md against every output. If any gate fails, the skill automatically revises the generation and retests. This loop continues until all gates pass or a retry limit is reached, ensuring only validated code reaches the user.

How does Hallmark integrate with different AI assistants?

The package.json skill.harnesses field explicitly lists supported assistants: claude-code, cursor, and codex. During installation, the host assistant reads this metadata and registers SKILL.md as an available tool, enabling the hallmark command within its environment.

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