What Are the Key Components of the Hallmark Project?

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, 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, references/verbs/redesign.md, references/verbs/study.md)—specific implementation flows for each command
• Genre definitions (references/genres/*.md such as editorial.md)—tone and theme cluster guidelines
• Macrostructure index (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)—nav, footer, and hero patterns
• Universal discipline files (typography.md, color.md, layout-and-space.md, motion.md, copy.md)
• Anti-patterns (references/anti-patterns.md)—rules for scoring existing code
• Slop-test (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—main entry point
• site/css/tokens.css—central token sheet (colors, fonts, spacing) shared across all generated pages
• site/css/components.css—component-level CSS for buttons, cards, and navs
• 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—diversification log tracking previous builds to ensure varied outputs
• .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, tailwind.config.*, and existing design tokens. This preserves the current palette, font stack, and spacing scale, with results cached in .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)
2. The selected macrostructure file (e.g., 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). 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.

The 58-Gate Slop-Test Validation

After emitting HTML/CSS, Hallmark runs the slop-test defined in 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:

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

Working with Hallmark: Code Examples

Installing the Skill

npx skills add nutlope/hallmark

Running the Default Design Flow

hallmark

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

**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

hallmark audit ./src/components/Button.tsx

Generated Component Preview

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

<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.
• 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 and Tailwind settings in .hallmark/preflight.json.
• Diversification tracking via .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, 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 implements safety rails that restrict destructive operations. During the pre-flight scan, Hallmark reads existing package.json and tailwind.config.* files to preserve current palettes and spacing scales, caching results in .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 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. 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.

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