architecture

Hallmark Project Structure Explained: A Deep Dive Into Nutlope's Design Skill Architecture

August 11, 2026 Nutlope/hallmark ↗

Hallmark organizes its codebase into three distinct layers—a core design engine in skills/hallmark/, a runnable demo site in site/, and human-oriented documentation in docs/—enabling installation as a Claude Code, Cursor, or Codex skill while powering the live demo at usehallmark.com.

This guide unpacks the repository structure of Hallmark, an open-source design skill created by Nutlope that generates anti-AI-slop interfaces. Understanding this architecture matters for developers who want to extend the skill, contribute to the design system, or replicate its lazy-loading pattern in their own AI-native tools.

Root-Level Configuration Files

The repository root houses standard project metadata plus skill-specific bootstrappers:

  • README.md – High-level description with live demo link and quick-start notes
  • package.json – Declares the npm package enabling installation via npx skills add nutlope/hallmark
  • vercel.json – Deployment configuration for the Vercel-hosted demo site
  • LICENSE, ROADMAP.md, .gitignore – Standard governance files

These files make Hallmark discoverable and installable as a third-party skill across AI coding environments.

skills/hallmark/ – The Core Design Engine

This directory contains the authoritative skill manifest and all reference material that drives Hallmark's design logic.

SKILL.md: The Execution Contract

skills/hallmark/SKILL.md serves as the single source of truth. It declares:

  • The skill's name, description, and version
  • Procedural verbs (study, brief, audit, generate)
  • Pre-flight scan workflow for project fingerprinting
  • Macrostructure selection logic
  • Theme routing rules
  • The "slop-test" quality gate

The manifest explicitly documents lazy-loading behavior: only needed reference files are read at runtime to preserve token budget.

references/ Directory: The Design Knowledge Base

A dense library of markdown files loaded on demand:

File/Directory Purpose
macrostructures.md Index of 21 named page shapes
macrostructures/*.md Individual macrostructure specifications
themes/*.md Optional theme overrides and definitions
structure.md The six structural axes governing layout decisions
genres/*.md Genre-specific design patterns
anti-patterns.md Detectable quality violations for the audit verb
typography.md, color.md, microinteractions.md Discipline-specific rule sets

The structural axes defined in references/structure.md provide the analytical framework for Hallmark's pre-flight project scan.

site/ – The Runnable Demo and Asset Pipeline

The static site powering usehallmark.com doubles as a visual regression test suite and theme preview environment.

Core Assets

  • index.html – Minimal wrapper loading CSS tokens and a single JavaScript entry point
  • css/tokens.css – Defines 24 thematic token sets (paper, accent, fonts, spacing, radius, shadows) using CSS custom properties and data-theme selectors; the file weighs approximately 2KB
  • css/base.css, css/components.css, css/sections.css – Layout primitives covering reset, grid, typography, and component styling
  • js/main.js – Runtime helper that swaps data-theme on the <html> element for live theme preview

Test and Example Collections

  • _tests/ – Pre-generated pages covering every macrostructure/theme combination, serving dual duty as regression tests and visual documentation
  • examples/ – Hand-crafted pages (e.g., wayfare, garden-01) demonstrating real-content rendering

docs/ – Human-Oriented Knowledge Base

Documentation targets designers and prompt engineers rather than machine consumption:

  • recipes.md – Step-by-step briefs mapping common design scenarios to Hallmark's verb flow
  • study-examples.md – Concrete DNA-extraction scenarios for the hallmark study verb
  • screenshots/ – Visual assets referenced from README.md to showcase outputs

Runtime Artifacts

Hallmark generates a .hallmark/ directory during operation containing:

  • log.json – Rotation history of generation sessions
  • preflight.json – Cached project signals from the initial scan

These files are git-ignored and documented in SKILL.md as ephemeral state, not source.

Practical Code Examples

Installing the Skill

npx skills add nutlope/hallmark

The command pulls package.json metadata and copies SKILL.md plus references/ into the user's skill directory (e.g., ~/.claude/skills/hallmark/).

Hallmark Stamp in Generated Output

/* Hallmark · macrostructure: Bento Grid · theme: Coral */

The engine inserts this header per the SKILL.md specification, enabling later hallmark audit operations to identify the generation context.

Runtime Theme Switching

<html data-theme="coral">
  <!-- page markup -->
</html>

The data-theme attribute selects from the 24 theme blocks in site/css/tokens.css. The demo site's JavaScript toggles this attribute for live preview.

Running a Quality Audit

hallmark audit ./src/index.html

Parses the target file, locates any existing Hallmark stamp, and returns a ranked punch list based on violations cataloged in references/anti-patterns.md.

Summary

  • Hallmark's project structure separates concerns into three layers: the skill engine (skills/hallmark/), the demo site (site/), and documentation (docs/)
  • Lazy-loading architecture in skills/hallmark/references/ preserves token budget while maintaining rich design knowledge
  • SKILL.md functions as both manifest and execution contract, defining verbs, workflows, and quality gates
  • CSS token system in site/css/tokens.css enables 24 theme variations through ~2KB of custom properties
  • Installation via npm (npx skills add) makes the skill portable across Claude Code, Cursor, and Codex environments

Frequently Asked Questions

Where is the main skill logic defined in Hallmark?

The skill logic resides in skills/hallmark/SKILL.md. This file contains the skill manifest (name, version, description) and the full procedural guide covering verbs, pre-flight scanning, macrostructure selection, theme routing, and the slop-test workflow. According to the Nutlope/hallmark source code, SKILL.md is the authoritative document that AI coding environments parse when invoking Hallmark.

How does Hallmark keep token usage low despite its large reference library?

Hallmark implements lazy-loading for reference materials. The SKILL.md manifest instructs the engine to load only the specific files needed for a given operation—such as a single macrostructure definition or theme file—rather than ingesting the entire references/ directory. This architecture is documented in the "load the visual ruleset" section of SKILL.md.

What files control the visual appearance of Hallmark-generated pages?

The 24 theme variations are defined in site/css/tokens.css using CSS custom properties scoped to data-theme selectors. This ~2KB file drives paper colors, accent colors, font stacks, spacing scales, border radii, and shadow definitions. The runtime demo adds js/main.js to swap themes dynamically, while site/css/base.css and site/css/components.css provide structural primitives.

How can I install Hallmark in my AI coding environment?

Run npx skills add nutlope/hallmark. This command, referenced in the repository's package.json, copies SKILL.md and the references/ directory to your local skills folder (typically ~/.claude/skills/hallmark/ for Claude Code). Installation makes the hallmark verb available for study, brief, generate, and audit operations.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →