# How to Set Up a Development Environment for Nutlope/Hallmark

> Set up a Hallmark development environment quickly. Clone the repo, install Node.js, and run npm run serve for a local demo. Get your Hallmark project running today.

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

---

**Set up a Hallmark development environment by cloning the repository, installing Node.js (no dependencies required), running `npm run serve` to start a local demo server, and optionally copying the skill files to Claude Code, Cursor, or Codex.**

Hallmark is a self-contained design skill for AI-coding assistants that generates high-quality UI with thematic consistency. Whether you want to run the demo site locally or integrate the skill into your AI workflow, the setup process is minimal. This guide walks you through each step using the actual source structure from `Nutlope/hallmark`.

## Clone the Repository

Start by cloning the repository and entering the project directory:

```bash
git clone https://github.com/Nutlope/hallmark.git
cd hallmark

```

The repository contains the skill definition in `skills/hallmark/`, a static demo site in `site/`, and project metadata in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json). No build step or dependency installation is required to run the demo.

## Install Node.js (Minimal Requirements)

Hallmark requires only a Node.js runtime—no `npm install` needed. The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) file contains zero runtime dependencies and only declares a single `serve` script.

Install Node.js 18 LTS or later:

```bash

# Verify your Node version

node --version  # Should be >= 18.0.0

```

As shown in the [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), the project uses a lightweight static server without external packages:

```json
{
  "scripts": {
    "serve": "npx serve@latest site -p 4173"
  },
  "skill": {
    "entry": "skills/hallmark/SKILL.md",
    "references": "skills/hallmark/references/"
  }
}

```

## Run the Demo Server Locally

Start the local development server to view all example pages:

```bash
npm run serve

```

This executes `npx serve@latest site -p 4173`, which serves the `site/` folder on `http://localhost:4173`. The demo includes generated pages like `examples/hum-07` and `examples/cobalt-01` that showcase Hallmark's thematic output.

Navigate to `http://localhost:4173` in your browser. Press **T** to cycle through themes—this behavior is implemented in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

## Add the Skill to Your AI Assistant (Optional)

Hallmark's entry point and reference files are defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) under the `skill` field. Integrate the skill with your preferred AI assistant:

### Claude Code

```bash
mkdir -p ~/.claude/skills/hallmark
cp -r skills/hallmark/* ~/.claude/skills/hallmark/

```

Restart Claude Code, then invoke commands like `hallmark audit` or `hallmark redesign` as documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

### Cursor

```bash
mkdir -p .cursor/rules
cp skills/hallmark/SKILL.md .cursor/rules/hallmark.mdc

```

Cursor loads the rules automatically—no frontmatter required.

### Codex

```bash

# Personal scope

mkdir -p ~/.codex/skills/hallmark
cp -r skills/hallmark/* ~/.codex/skills/hallmark/

# Or project-scoped

mkdir -p .codex/skills/hallmark
cp -r skills/hallmark/* .codex/skills/hallmark/

```

## Explore the Reference Material

The `skills/hallmark/references/` directory contains the design specifications that drive Hallmark's behavior:

- **Macrostructures** – layout patterns and component hierarchies
- **Themes** – color systems, typography scales, and spacing tokens
- **Slop-test rules** – quality gates to prevent generic output
- **Usage verbs** – `audit`, `redesign`, `study` command definitions

These markdown files are read by the skill during its pre-flight scan, which automatically detects existing [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, or token files in your target project.

## Iterate and Test Changes

Edit any source file and refresh your browser to see changes immediately:

```bash

# Example: modify a theme token

echo '{ "primary": "#ff6b6b" }' > site/themes/custom.json

```

The skill's pre-flight scan preserves your project's existing configuration—fonts, color palettes, and spacing scales—before generating new UI. This behavior is defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) under the "0. Pre-flight Scan" section.

## Key Files in the Repository

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Declares skill entry point ([`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)), reference folder, and `serve` script |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core rule-set driving all verbs and design flow |
| `skills/hallmark/references/` | Design specifications: macrostructures, themes, slop-tests |
| `site/` | Static HTML/CSS demo assets |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Demo navigation and theme cycling |

## Summary

- **Clone** `Nutlope/hallmark` to get the skill definition and demo site
- **Install Node.js 18+**—no `npm install` required due to zero runtime dependencies
- **Run `npm run serve`** to start a local server on port 4173
- **Copy skill files** to `~/.claude/skills/`, `.cursor/rules/`, or `~/.codex/skills/` for AI assistant integration
- **Reference files** in `skills/hallmark/references/` control all design behavior and quality gates

## Frequently Asked Questions

### Does Hallmark require npm dependencies to run?

No. Hallmark has zero runtime dependencies. The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) only declares metadata and a `serve` script that uses `npx serve@latest` to launch a static server. You can run the demo immediately after cloning with `npm run serve`.

### How do I update the skill after installing it to Claude Code?

Re-copy the `skills/hallmark/` directory to your Claude Code skills folder whenever you pull updates from the repository. The skill does not auto-update, so manual synchronization ensures you have the latest reference files and rule definitions.

### Can I use Hallmark without running the local server?

Yes. The local server is only needed to preview the demo site. You can copy the skill files directly to your AI assistant and use Hallmark's verbs (`audit`, `redesign`, `study`) without ever starting `npm run serve`.