Nutlope/hallmark Architecture: A Technical Breakdown of the Design Skill System

The Nutlope/hallmark architecture implements a serverless, markdown-driven design skill that enables AI coding assistants to generate anti-slop UI through structured verbs, reference libraries, and a token-based static frontend.

The Nutlope/hallmark repository operates as a design skill for AI coding assistants like Claude, Cursor, and Codex, requiring no backend server or runtime API to function. Unlike traditional web frameworks, this architecture relies entirely on static files, markdown specifications, and CSS custom properties to enforce design discipline across four distinct execution verbs. Examining the Nutlope/hallmark architecture reveals how AI-native developer tools can embed complex design systems through structured data rather than application logic.

Skill Metadata and Configuration

The foundation of the Nutlope/hallmark architecture resides in package.json, which declares the package as module-type and exposes a skill block that host platforms read to instantiate the skill:

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

The entry field points to the Markdown implementing the skill verbs, while references designates the knowledge base directory. The harnesses array defines which AI assistants can invoke Hallmark: claude-code, cursor, and codex. The serve script launches a Python HTTP server on port 4173 to host the static demonstration site locally.

Core Skill Definition Layer

skills/hallmark/SKILL.md serves as the execution engine, defining four distinct verbs that control the AI behavior:

• default: Initiates the full design flow for comprehensive UI generation
• audit: Runs the six-axis slop-test against existing code
• redesign: Applies Hallmark principles to refactor existing components
• study: Analyzes design patterns without emitting code

The skill implements a pre-flight scan that inspects target projects for existing fonts, color palettes, motion libraries, and spacing scales. Following the scan, the design flow executes a step-by-step selection process: choosing a genre (editorial, modern-minimal, atmospheric, or playful), selecting a theme, determining macrostructure, applying hero polish, and assigning component archetypes. A component-scope flow provides a streamlined path when the brief targets a single UI element rather than a full page.

Reference Library Structure

The skills/hallmark/references directory functions as a curated knowledge base that SKILL.md consults at runtime via relative path links. Key reference files include:

• structure.md: Defines macro-structure patterns and diversification rules to prevent repetitive layouts
• custom-theme.md: Contains logic for selecting between catalog themes and generating custom OKLCH palettes
• slop-test.md: Implements six-axis self-critique gates that block invented metrics, italic headings, and other anti-patterns
• anti-patterns.md: Maintains a blacklist of prohibited UI patterns including fake browser chrome and artificial scarcity timers
• genres/*.md: Four genre families that control voice, color, and typography presets

This tight coupling ensures that any output adheres to Hallmark's "anti-AI-slop" design principles by grounding generation in predetermined rules rather than model hallucination.

Static Frontend Implementation

The site/ directory contains a self-contained static website demonstrating the skill output. Three core files define the frontend architecture:

• site/index.html: Root entry that loads the token system and renders theme examples
• site/css/base.css: Implements the CSS custom property token system
• site/js/main.js: Powers the theme picker and archetype mapping logic

Token-Based CSS Architecture

site/css/base.css enforces a token-based styling system using CSS custom properties to eliminate hard-coded values:

/* Theme transitions using locked tokens */
html, body, .nav, .opening__title, .opening__sub, .section__title,
.spec__name, .spec__rule, .tell, .tell__viz, .tell__meta,
.tell__name, .tell__why, .step__head, .step__sub,
.install__body, .foot, .code, .swatch, .section__head,
.vs, .vs__col, .vs__caption, hr.rule, .themer, .themer__btn {
  transition:
    background-color var(--dur-short) var(--ease-out),
    color var(--dur-short) var(--ease-out),
    border-color var(--dur-short) var(--ease-out);
}

All visual elements reference tokens like --color-accent, --color-paper, --font-display, and --space-2, ensuring consistent application of the design system.

Theme and Archetype Engine

site/js/main.js implements a registry of 20 named themes mapped to structural archetypes:

const THEMES = { hum:"Hum", specimen:"Specimen", /* ... 18 more ... */ };
const ARCHETYPES = {
  specimen:{hero:"marquee",footer:"colophon"},
  garden:{hero:"letter",footer:"colophon"},
  /* ... additional mappings ... */
};
const THEME_GENRES = {
  specimen:"editorial", 
  coral:"modern-minimal",
  bloom:"atmospheric", 
  hum:"playful"
};

Each theme maps to a hero archetype and footer archetype, guaranteeing structural variety across generations. The genre association determines which slop-test gates apply during the audit phase. The JavaScript handles theme persistence via localStorage and implements hover-play video behaviors, maintaining a fully client-side architecture.

Development and Deployment Workflow

The Nutlope/hallmark architecture requires no build step or compilation. Running npm run serve executes the Python HTTP server command defined in package.json, serving the static site/ directory on port 4173. This design-first, code-light approach eliminates bundling complexity and ensures the skill remains portable across different host environments.

Summary

• The Nutlope/hallmark architecture is a pure-data skill with no server-side runtime, relying on markdown specifications and static assets
• package.json declares skill metadata including entry points, reference paths, and supported AI harnesses (claude-code, cursor, codex)
• SKILL.md defines four execution verbs (default, audit, redesign, study) and implements pre-flight scanning with structured design flows
• The references/ directory provides a knowledge base of anti-patterns, genre definitions, and slop-test criteria
• site/css/base.css enforces a token-based design system through CSS custom properties
• site/js/main.js manages 20 themes, archetype mappings, and genre associations to ensure structural variety
• The entire system deploys via a simple Python HTTP server without build steps

Frequently Asked Questions

What distinguishes Nutlope/hallmark from traditional web frameworks?

Traditional frameworks rely on runtime logic, server-side rendering, or complex build pipelines. The Nutlope/hallmark architecture operates as a static skill definition that AI assistants read and execute, producing output through predetermined markdown rules and reference libraries rather than application code. This serverless approach requires no backend infrastructure while enforcing strict design discipline through the token system and slop-test gates.

How does the theme system prevent repetitive designs?

The architecture in site/js/main.js defines 20 distinct themes mapped to specific hero and footer archetypes, ensuring that each generation produces unique structural combinations. The genre system (editorial, modern-minimal, atmospheric, playful) further diversifies output by applying different color, typography, and voice presets. The ARCHETYPES object guarantees that selecting the "specimen" theme produces a marquee hero and colophon footer, while "garden" selects a letter hero, preventing layout homogenization.

What are the supported execution verbs in the Hallmark skill?

The skill exposes four verbs defined in skills/hallmark/SKILL.md: default (full design flow with pre-flight scanning), audit (six-axis slop-test critique of existing code), redesign (refactoring existing components to meet Hallmark standards), and study (analysis mode without code emission). Each verb follows the same reference-backed architecture but targets different stages of the development lifecycle.

How does the slop-test mechanism maintain design quality?

The references/slop-test.md file defines six axes of self-critique that the skill applies before emitting code. These gates specifically target AI generation failures including invented metrics, inappropriate italic headings, mismatched spacing scales, and other "anti-slop" violations. By consulting this reference library during the execution of the audit verb or the pre-flight phase of the default verb, the system ensures output adheres to human design standards rather than model hallucinations.

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