# How the Nutlope Hallmark Architecture Is Structured: A Complete Guide

> Discover the Nutlope Hallmark architecture structure. Explore its four layers: metadata, skill definition, reference library, and demo site, forming a declarative design engine.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-08-03

---

**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`](https://github.com/Nutlope/hallmark/blob/main/package.json) |
| Skill definition | Declares verbs, design flow, and safety rails | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) file marks Hallmark as an **ES module** (`"type": "module"`) and declares the skill entry point for AI assistants.

```json
{
  "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)](https://github.com/Nutlope/hallmark/blob/main/package.json)

---

## Layer 2: Skill Definition

[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) to understand which verb was invoked and which rules to apply.

Source: [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) | 58-gate quality checklist |
| [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) | Blacklist of forbidden UI patterns |
| [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/05-marquee-hero.md) for structure
2. [`references/themes/bloom.md`](https://github.com/Nutlope/hallmark/blob/main/references/themes/bloom.md) for visual styling
3. [`references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/references/typography.md) for type rules

This selective loading keeps token consumption low and generation deterministic.

Source: [`references/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css))
- Hosts HTML/CSS/JS examples for visual debugging

Run the local server with:

```bash
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)](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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and `references/` into the assistant's skill directory
2. **Invocation** – Assistant reads [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) to parse the verb (`hallmark`, `hallmark audit`, etc.)
3. **Pre-flight scan** – Analyzes [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, and existing [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) to preserve project context
4. **Macrostructure & theme selection** – Consults [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) and genre/theme files, respecting diversification rules from [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to enforce variety across runs.

---

## Key Files Reference

| Path | Role in Architecture |
|------|----------------------|
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Skill declaration and installation metadata |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core API: verbs, flow, safety rails |
| `skills/hallmark/references/` | Declarative knowledge library |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Central design token sheet |
| `site/_tests/` | Visual QA examples |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) | Generated diversification log |

---

## Usage Examples

Install and use Hallmark across its three verbs:

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) as an available tool, enabling the `hallmark` command within its environment.