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

> Set up the Nutlope/hallmark project locally by cloning the repo, installing it as a skill, and serving the static site. Follow our step-by-step guide to get started quickly.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), which hosts the landing page, install instructions, and theme picker UI.

### Runtime Controller Layer

[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) plus the `references/` directory form the machine-readable skill definition. The `skill` field in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/package.json) at lines 32-34.

### Switch Themes Programmatically

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) with new theme definitions:

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Repository root | Project overview and usage notes |
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Root | Skill metadata and npm scripts |
| [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | `site/` | Static HTML entry point with theme picker |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | `site/js/` | Core theme controller and UI logic |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and the `references/` folder to your assistant's expected skill location. Update [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) if publishing a fork with modified skill paths.