# Hallmark Project Structure Explained: A Deep Dive Into Nutlope's Design Skill Architecture > Explore Hallmark's project structure with its three core layers: skills, site, and docs. Install Hallmark as a Claude Code, Cursor, or Codex skill and power usehallmark.com. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-08-11 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) | Index of 21 named page shapes | | `macrostructures/*.md` | Individual macrostructure specifications | | `themes/*.md` | Optional theme overrides and definitions | | [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md) | The six structural axes governing layout decisions | | `genres/*.md` | Genre-specific design patterns | | [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) | Detectable quality violations for the audit verb | | [`typography.md`](https://github.com/Nutlope/hallmark/blob/main/typography.md), [`color.md`](https://github.com/Nutlope/hallmark/blob/main/color.md), [`microinteractions.md`](https://github.com/Nutlope/hallmark/blob/main/microinteractions.md) | Discipline-specific rule sets | The structural axes defined in [`references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/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 `` 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`](https://github.com/Nutlope/hallmark/blob/main/log.json) – Rotation history of generation sessions - [`preflight.json`](https://github.com/Nutlope/hallmark/blob/main/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 ```bash npx skills add nutlope/hallmark ``` The command pulls [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) metadata and copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) plus `references/` into the user's skill directory (e.g., `~/.claude/skills/hallmark/`). ### Hallmark Stamp in Generated Output ```css /* 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 ``` The `data-theme` attribute selects from the 24 theme blocks in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). The demo site's JavaScript toggles this attribute for live preview. ### Running a Quality Audit ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/js/main.js) to swap themes dynamically, while [`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css) and [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json), copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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.