How to Set Up the Nutlope/Hallmark Project Locally: Step-by-Step Guide

You can set up Nutlope/hallmark by cloning the repository, installing it as a skill with npx skills add nutlope/hallmark, and serving the static site locally on port 4173.

Hallmark is a design skill that helps AI coding assistants generate beautiful, non-default UI patterns. Learning how to set up the Nutlope/hallmark project locally lets you preview its 21 themes, customize the archetype system, or extend the skill for your own workflows. This guide walks through installation, the underlying architecture, and practical development workflows.

Quick Start: Local Setup in 4 Steps

Follow these commands to get Hallmark running on your machine:

Step	Command	Purpose
1	git clone https://github.com/Nutlope/hallmark.git && cd hallmark	Fetch source and enter directory
2	npx skills add nutlope/hallmark	Install Hallmark as a skill for Claude Code, Cursor, and Codex
3	python3 -m http.server --directory site 4173	Launch local demo server
4	Open http://localhost:4173	View the landing page and theme picker

The project requires no build step. You need only Node.js/npm (for the npx command) and Python (for the demo server).

Understanding Hallmark's Architecture

Hallmark differs from typical JavaScript frameworks. According to the Nutlope/hallmark source code, it ships as a self-contained static site with three layers:

Static Assets Layer

The site/ folder contains all HTML, CSS, fonts, and images. The entry point is site/index.html, which hosts the landing page, install instructions, and theme picker UI.

Runtime Controller Layer

site/js/main.js implements a vanilla-JavaScript theme engine. Key functions include:

• applyTheme — switches themes by updating document.documentElement.dataset.theme
• swapArchetypes — swaps hero and footer templates based on the selected theme
• Theme registry (lines 41-65) — defines 21 themes mapping to hero/footer archetypes

Theme persistence uses localStorage under the key hallmark-theme. Keyboard shortcuts T/Shift+T cycle themes, while R triggers random selection.

Skill Descriptor Layer

skills/hallmark/SKILL.md plus the references/ directory form the machine-readable skill definition. The skill field in package.json points to this descriptor, enabling Claude Code, Cursor, and Codex to invoke Hallmark via hallmark <verb> <target>.

Installing Hallmark as a Skill

The npx skills add nutlope/hallmark command automatically installs Hallmark into three harness locations:

AI Assistant	Installation Path
Claude Code	~/.claude/skills/hallmark/
Cursor	.cursor/rules/hallmark.mdc
Codex (personal)	~/.codex/skills/hallmark/
Codex (project)	.codex/skills/hallmark/

No additional configuration is required. The skills package manager handles file placement.

Development Workflow Commands

To extend or debug Hallmark locally, use these patterns:

Start the Demo Server

# Using npm (recommended)

npm run serve

# Or directly with Python

python3 -m http.server --directory site 4173

The serve script is defined in package.json at lines 32-34.

Switch Themes Programmatically

// Browser console: apply Cobalt theme instantly
document.documentElement.dataset.theme = 'cobalt';

// Or use the public API from main.js
applyTheme('cobalt');

Add a Custom Theme

Extend site/js/main.js with new theme definitions:

// 1. Register theme name
THEMES.custom = "Custom";

// 2. Map to archetypes
ARCHETYPES.custom = { hero: "letter", footer: "colophon" };

// 3. Provide copy fixtures
COPY.custom = {
  eyebrow: "My Custom Theme",
  title: HERO_TITLE,
  lede: "A bespoke design crafted just for you."
};

Reload the browser — your theme appears automatically in the picker.

Key Files for Local Development

File	Location	Purpose
README.md	Repository root	Project overview and usage notes
package.json	Root	Skill metadata and npm scripts
site/index.html	site/	Static HTML entry point with theme picker
site/js/main.js	site/js/	Core theme controller and UI logic
skills/hallmark/SKILL.md	skills/hallmark/	AI assistant skill descriptor
skills/hallmark/references/	skills/hallmark/	Reference docs for verbs and components
site/css/*.css	site/css/	Design tokens, base styles, and components

Summary

• Clone with git clone https://github.com/Nutlope/hallmark.git
• Install the skill via npx skills add nutlope/hallmark for Claude Code, Cursor, and Codex
• Serve locally using npm run serve or Python's http.server on port 4173
• Customize by editing site/js/main.js to add themes or modify archetypes
• No build step — changes to site/ files reflect immediately on reload

Frequently Asked Questions

What dependencies does Hallmark require?

Hallmark has zero runtime dependencies. You need Node.js/npm only for the npx skills add command and Python 3 only for the local demo server. The static site runs in any modern browser without bundling or compilation.

Where is the theme state stored?

Theme selection persists in localStorage under the key hallmark-theme. The applyTheme function in site/js/main.js reads this value on page load and restores the last-selected theme automatically.

Can I use Hallmark without installing it as a skill?

Yes. The site/ folder operates as a standalone static website. Clone the repository and serve site/index.html directly — all theme switching and UI functionality works independently of the skill installation.

How do I add support for a new AI assistant?

Create a new harness directory following the pattern in skills/hallmark/. Copy SKILL.md and the references/ folder to your assistant's expected skill location. Update package.json if publishing a fork with modified skill paths.

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