Hallmark Build Instructions: How to Install and Run the Design Skill

Hallmark is an AI design skill rather than a traditional build system—you install it via npx skills add nutlope/hallmark, optionally run npm run serve to preview generated HTML locally, and invoke design verbs like hallmark, audit, or redesign through your AI assistant.

This guide covers the complete hallmark build instructions from the Nutlope/hallmark repository. Unlike conventional UI libraries that bundle JavaScript, Hallmark operates as a deterministic, rule‑based design pipeline that produces static HTML + CSS pages through AI assistants such as Claude Code, Cursor, and Codex.

---

Installation: Adding Hallmark to Your AI Assistant

The first step in any hallmark build workflow is installing the skill into your assistant's registry.

Use the official command from README.md【1†L94-L99】:

npx skills add nutlope/hallmark

This copies three critical components into your assistant:

• skills/hallmark/SKILL.md — the core skill definition and verb taxonomy
• skills/hallmark/references/ — all rule files (macrostructures, themes, slop‑test gates)
• Export format specifications in references/export-formats.md

The skill is now ready to receive commands. No npm install inside the repo is required unless you want to run the local preview server.

---

Local Preview Server: The Only npm Script

Hallmark's only official build‑related command is serve, defined in package.json【1†L32-L35】:

npm run serve

This launches a Python HTTP server on port 4173 that hosts the site/ directory. The skill writes all generated output—tokens.css, markdown summaries, and final HTML pages—to this folder.

Access your builds at:

http://localhost:4173

The site/_tests/ folder contains 21+ pre‑generated example builds you can browse for reference【2†L71-L73】.

---

Running Hallmark: The Verb Interface

All design work happens through verbs defined in SKILL.md【2†L21-L28】. These are not CLI binaries but natural‑language commands interpreted by your AI assistant.

Core Verbs

Verb	Purpose	Example invocation
default (implicit)	Generate a fresh landing page from scratch	hallmark
audit	Review an existing HTML file against Hallmark standards	hallmark audit ./site/index.html
redesign	Preserve copy/IA while applying new macrostructure and theme	hallmark redesign ./site/index.html --mood editorial
study	Extract "design DNA" from a live URL	hallmark study https://example.com

Each verb triggers a deterministic sequence documented in SKILL.md【2†L45-L63】.

---

The Default Design Flow (Step‑by‑Step)

When you run hallmark without arguments, the skill executes a seven‑stage pipeline hardcoded in SKILL.md【2†L48-L81】:

1. Pre‑flight scan — Detects existing tokens, frameworks, and color palettes in your project context.

2. Macrostructure selection — Chooses from 21 named layouts (e.g., Marquee Hero, Split Hero, Editorial List). Full index lives in references/macrostructures.md.

3. Theme routing — Either applies one of 20 built‑in catalog themes or generates a custom palette respecting diversification rules. Theme definitions are in references/themes/.

4. Hero enrichment — Optionally injects media, SVG art, or Lottie animations per references/hero-enrichment.md.

5. Preview emit — Outputs a markdown summary: macrostructure name, theme, planned sections, and motion decisions.

6. Slop‑test — Runs 58 quality gates defined in references/slop-test.md to catch inconsistencies.

7. Final emit — Writes tokens.css, optional design.md, and the complete HTML page to site/.

The "Load the visual ruleset" subsection of SKILL.md【2†L48-L81】 enumerates every file loaded at each stage.

---

Programmatic Integration (Advanced)

Since Hallmark is skill‑based rather than package‑based, embedding it in Node requires copying the skill files into your assistant's rule directory:

const fs = require('fs');
const path = require('path');

// Example: integrate with Cursor's rules system
fs.cpSync(
  path.resolve('skills/hallmark'),
  path.resolve('.cursor/rules/hallmark'),
  { recursive: true }
);

// The assistant now recognizes hallmark verbs and references

No webpack, Vite, or bundler configuration exists—the skill logic executes entirely within the AI assistant's context window.

---

File Structure for Build Reference

Understanding these paths clarifies how hallmark build instructions operate:

Path	Role in Build Process
package.json	Contains sole npm script (serve)【1†L32-L35】
skills/hallmark/SKILL.md	Entry point: verb taxonomy and design flow【2†L21-L28】
skills/hallmark/references/	All deterministic rules (macrostructures, themes, slop‑test)
skills/hallmark/references/export-formats.md	Output specifications for tokens.css and HTML
site/	Destination folder for all generated artifacts
site/_tests/	Reference builds demonstrating valid outputs【2†L71-L73】
docs/recipes.md	Human‑readable design brief templates
docs/study-examples.md	Sample DNA‑extraction scenarios

---

Summary

• Hallmark has no traditional build step—it is a design skill installed via npx skills add nutlope/hallmark.
• Local preview requires only npm run serve (port 4173) to host the site/ directory【1†L32-L35】.
• Design execution uses verbs (hallmark, audit, redesign, study) processed by AI assistants per SKILL.md【2†L21-L28】.
• Output generation follows a strict seven‑stage pipeline ending in tokens.css + HTML written to site/【2†L45-L63】.
• Quality assurance is built‑in through the 58‑gate slop‑test in references/slop-test.md.

---

Frequently Asked Questions

How do I compile Hallmark into a JavaScript bundle?

You don't. Hallmark is not a bundlable library. According to the Nutlope/hallmark source code, it is a "design skill" consisting of markdown rule files that AI assistants interpret directly. There is no entry point for webpack, Vite, or Rollup.

What does npm run serve actually do?

It runs a Python HTTP server from package.json【1†L32-L35】 that serves the site/ directory on localhost:4173. This is purely for previewing the static HTML + CSS that Hallmark generates—not for building the skill itself.

Can I use Hallmark without Claude Code, Cursor, or Codex?

No. The skill requires an AI assistant with a skill registry that can parse SKILL.md and load the references/ rule files. The deterministic design logic lives in the assistant's context, not in executable code you can run standalone.

Where are the actual build artifacts created?

All output lands in the site/ folder: tokens.css for design tokens, optional design.md for documentation, and the final HTML page. The references/export-formats.md file specifies these formats precisely.

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