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

> Install and run the Hallmark AI design skill with these easy build instructions. Use npx to add the skill and npm to serve generated HTML locally.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/README.md)【1†L94-L99】:

```bash
npx skills add nutlope/hallmark

```

This copies three critical components into your assistant:
- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json)【1†L32-L35】:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md) to catch inconsistencies.

7. **Final emit** — Writes [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), optional [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), and the complete HTML page to `site/`.

The "Load the visual ruleset" subsection of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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:

```js
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`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Contains sole npm script (`serve`)【1†L32-L35】 |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) | Output specifications for [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) and HTML |
| `site/` | Destination folder for all generated artifacts |
| `site/_tests/` | Reference builds demonstrating valid outputs【2†L71-L73】 |
| [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) | Human‑readable design brief templates |
| [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)【2†L21-L28】.
- **Output generation** follows a strict seven‑stage pipeline ending in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) for design tokens, optional [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) for documentation, and the final HTML page. The [`references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/references/export-formats.md) file specifies these formats precisely.