# What Are the Key Components of the Hallmark Project?

> Explore the key components of the Hallmark project: Skill Definition, Reference Library, and Site Assets. Understand how these layers enforce anti-AI-slop standards via a 58-gate validation pipeline.

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

---

**The Hallmark project is organized into three distinct architectural layers—the Skill Definition interface, the Reference Library of curated design rules, and the Site Assets test suite—that collectively enforce anti-AI-slop standards through a 58-gate validation pipeline.**

Hallmark is an open-source design skill from the Nutlope/hallmark repository that generates anti-AI-slop web pages and components. Understanding the key components of the Hallmark project reveals how it maintains strict design discipline while keeping token usage low through selective rule loading and comprehensive post-build verification.

## The Three-Layer Architecture

### Layer 1: Skill Definition (SKILL.md)

The entry point resides at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which declares the skill name, version, and available verbs. This file defines four primary operations—`default`, `audit`, `redesign`, and `study`—and documents the safety rails that prevent destructive edits to existing codebases. The Skill Definition acts as the contract between the user and the AI, specifying exactly how Hallmark may be invoked and what constraints govern its behavior.

### Layer 2: Reference Library

The Reference Library contains curated design intelligence loaded on demand to minimize token consumption. Core files include:

- **Verb documentation** ([`references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/audit.md), [`references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/redesign.md), [`references/verbs/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/study.md))—specific implementation flows for each command
- **Genre definitions** (`references/genres/*.md` such as [`editorial.md`](https://github.com/Nutlope/hallmark/blob/main/editorial.md))—tone and theme cluster guidelines
- **Macrostructure index** ([`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md))—catalog of 21 layout patterns
- **Individual macrostructures** (`references/macrostructures/<NN-slug>.md`)—detailed specifications for specific layouts
- **Theme files** (`references/themes/*.md`)—definitions for 20 named themes plus custom configurations
- **Component archetypes** (`references/components/*.md` such as [`N5-floating-pill.md`](https://github.com/Nutlope/hallmark/blob/main/N5-floating-pill.md))—nav, footer, and hero patterns
- **Universal discipline files** ([`typography.md`](https://github.com/Nutlope/hallmark/blob/main/typography.md), [`color.md`](https://github.com/Nutlope/hallmark/blob/main/color.md), [`layout-and-space.md`](https://github.com/Nutlope/hallmark/blob/main/layout-and-space.md), [`motion.md`](https://github.com/Nutlope/hallmark/blob/main/motion.md), [`copy.md`](https://github.com/Nutlope/hallmark/blob/main/copy.md))
- **Anti-patterns** ([`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md))—rules for scoring existing code
- **Slop-test** ([`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md))—the 58-gate quality validation suite

### Layer 3: Site Assets and Test Suite

The concrete implementation layer lives in `site/` and provides both demonstration and regression testing:

- [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)—main entry point
- [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)—central token sheet (colors, fonts, spacing) shared across all generated pages
- [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css)—component-level CSS for buttons, cards, and navs
- [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)—minimal JavaScript loader
- `site/_tests/<theme>/index.html`—pre-rendered examples for every theme and macrostructure serving as documentation and test artifacts
- [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)—diversification log tracking previous builds to ensure varied outputs
- [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json)—cached scan results for fast re-runs

## The Hallmark Execution Pipeline

### Pre-flight Scanning and Caching

Before generating code, Hallmark executes a pre-flight scan that reads the project's [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, and existing design tokens. This preserves the current palette, font stack, and spacing scale, with results cached in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) to enable fast subsequent runs.

### Verb Dispatch and Routing

Based on the user command—`hallmark`, `hallmark audit`, `hallmark redesign`, or `hallmark study`—the system loads the corresponding verb documentation from `references/verbs/*.md` and executes the specific flow. The **audit** verb scores files against anti-patterns without modifying code, while **redesign** refactors existing components and **study** extracts design DNA.

### Selective Rule Loading

To maintain token efficiency, Hallmark loads only necessary reference files:

1. The specific genre file (e.g., [`references/genres/modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/references/genres/modern-minimal.md))
2. The selected macrostructure file (e.g., [`references/macrostructures/05-workbench.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/05-workbench.md))
3. Required component archetype files for nav and footer patterns
4. Universal discipline files covering typography, color, layout, motion, copy, and anti-patterns

### Macrostructure and Theme Selection

Hallmark reads the macrostructure index and selects a layout that differs from recent runs (tracked in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)). It then routes to either the catalog of 20 named themes or a custom theme configuration, populating the chosen values into [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).

### The 58-Gate Slop-Test Validation

After emitting HTML/CSS, Hallmark runs the slop-test defined in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md). If any of the 58 gates fail, the skill automatically revises the output until compliance is achieved. Successful builds receive a signature comment:

```css
/* Hallmark · macrostructure: Marquee Hero · theme: Bloom · pre‑emit critique: P5 H4 E5 S4 R5 V5 */

```

## Working with Hallmark: Code Examples

### Installing the Skill

```bash
npx skills add nutlope/hallmark

```

### Running the Default Design Flow

```bash
hallmark

```

Hallmark prompts for audience, use-case, and tone, then emits a preview:

```markdown
**Hallmark · v1.1.0**

- **Macrostructure** · Marquee Hero
- **Theme** · Bloom (light paper · cool accent)
- **Enrichment** · none (typography only)
- **Sections** · Hero · Logos · Stats · Features · CTA · Footer
- **Motion** · none — typography only
- **Slop test** · 58 / 58 ✓
- **Diversification** · differs from previous on accent hue

```

### Auditing Existing Components

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

```

### Generated Component Preview

Hallmark automatically generates 8-state demo wrappers for component validation:

```html
<div class="preview">
  <button class="btn is-hover">Hover</button>
  <button class="btn is-focus">Focus</button>
  <button class="btn is-active">Active</button>
  <button class="btn" disabled>Disabled</button>
  <button class="btn loading">Loading</button>
  <button class="btn error">Error</button>
  <button class="btn success">Success</button>
</div>

```

## Summary

- **Three-layer architecture** separates the Skill Definition interface, Reference Library, and Site Assets to maintain clean boundaries between invocation logic, design rules, and generated output.
- **58-gate slop-test** ensures all emitted code meets anti-AI-slop standards through automated validation and revision cycles defined in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md).
- **Selective file loading** minimizes token usage by loading only necessary genre, macrostructure, and component files for each specific request.
- **Pre-flight scanning** preserves existing project configurations by caching [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) and Tailwind settings in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json).
- **Diversification tracking** via [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) ensures consecutive runs produce varied macrostructures and themes rather than repetitive outputs.

## Frequently Asked Questions

### What is the purpose of the 58-gate slop-test in Hallmark?

The slop-test, defined in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md), serves as a post-emit validation suite that checks generated code against 58 specific quality gates covering typography, spacing, color usage, and anti-patterns. If any gate fails, Hallmark automatically revises the output until compliance is achieved, ensuring all emitted code meets strict anti-AI-slop standards before delivery.

### How does Hallmark prevent destructive edits to existing projects?

The Skill Definition layer in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) implements safety rails that restrict destructive operations. During the pre-flight scan, Hallmark reads existing [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) and `tailwind.config.*` files to preserve current palettes and spacing scales, caching results in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) to prevent overwriting existing design tokens or configurations.

### What are the four available verbs in the Hallmark skill?

Hallmark provides four distinct verbs: **default** (generates new designs), **audit** (scores existing files against [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md) without modifying code), **redesign** (refactors existing components), and **study** (extracts design DNA from existing implementations). Each verb loads specific documentation from `references/verbs/*.md` to guide its execution flow.

### Where are design tokens stored in the Hallmark project?

Central design tokens—including colors, fonts, and spacing scales—live in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). This stylesheet is referenced by all generated pages and is populated during the theme selection phase, supporting both the 20 named themes and custom theme configurations defined in `references/themes/*.md`.