# How to Integrate Nutlope/Hallmark into an Existing Project: Complete Setup Guide

> Easily integrate Nutlope/hallmark into your project using npx skills add. Generate, audit, or redesign HTML pages with zero runtime dependencies. Get the complete setup guide now.

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

---

**Use `npx skills add nutlope/hallmark` to install Hallmark into Claude Code, Cursor, or Codex, then run `hallmark` verbs to generate, audit, or redesign fully-styled HTML pages with zero runtime dependencies.**

**Hallmark** is a design skill that integrates with AI-powered code editors to generate production-ready HTML and CSS. Unlike traditional design systems, it operates entirely at build-time—producing static assets that slot into any existing project without adding runtime overhead. This guide walks through exactly how to integrate Nutlope/hallmark into your workflow, with specific paths, commands, and automation patterns drawn from the source code.

---

## Installation Methods

### Automated Installation (Recommended)

The fastest way to integrate Hallmark is the official installer:

```bash
npx skills add nutlope/hallmark

```

This command detects your editor and drops files into the correct location:

| Editor | Installation Path |
|--------|-------------------|
| **Claude Code** | `~/.claude/skills/hallmark/` |
| **Cursor** | `.cursor/rules/hallmark.mdc` |
| **Codex** | `~/.codex/skills/hallmark/` (global) or `.codex/skills/hallmark/` (project-scoped) |

For Cursor specifically, the installer strips frontmatter from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and copies the body into `.cursor/rules/hallmark.mdc`.

### Manual Installation

If you need full control over file placement, copy directly from the repository:

```bash

# Clone the repository

git clone https://github.com/Nutlope/hallmark.git

# Claude Code: copy to global skills directory

cp -r hallmark/skills/hallmark/* ~/.claude/skills/hallmark/

# Codex: project-scoped installation

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

# Cursor: manually create rule file

cat hallmark/skills/hallmark/SKILL.md | tail -n +2 > .cursor/rules/hallmark.mdc

```

The manual approach is useful when integrating Hallmark into containerized development environments or CI/CD pipelines where `npx` may not be available.

---

## Core Verbs and Usage Patterns

Hallmark exposes four primary verbs through its rule-set in [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Each produces self-contained [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) + CSS output.

### `hallmark` — Generate New UI

The default verb creates a fresh design from scratch:

```bash
hallmark

```

Hallmark selects a **macrostructure** (layout template), applies one of 21 built-in **themes** (color palettes and type pairings), then runs a 57-criteria **slop-test** to catch AI-generated visual artifacts.

### `hallmark audit <target>` — Score Existing Code

Evaluate an existing project against Hallmark's quality gates:

```bash
hallmark audit ./my-existing-site

```

This parses the target's HTML/CSS and reports violations of typographic balance, spacing consistency, and anti-patterns documented in [[`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md)](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references).

### `hallmark redesign <target>` — Rebuild With New Fingerprint

Preserve content while regenerating visuals:

```bash
hallmark redesign ./my-existing-site

```

Useful for A/B testing different themes or refreshing stale designs without rewriting copy.

### `hallmark study <source>` — Extract Design DNA

Capture aesthetic patterns from external sources:

```bash

# From screenshot

hallmark study ./reference-design.png

# From live URL

hallmark study https://example.com/landing-page

```

Study outputs feed into the custom theme pipeline when no built-in theme matches.

---

## Automating Hallmark in Build Pipelines

Since Hallmark produces static files, you can wire it into any build process. Below is a Node.js script that generates designs and moves them into a Next.js `public/` folder:

```javascript
// scripts/generate-design.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const OUTPUT_DIR = path.resolve('public/generated');

// Ensure output directory exists
fs.mkdirSync(OUTPUT_DIR, { recursive: true });

// Run Hallmark verb
const verb = process.argv[2] || 'hallmark';
execSync(verb, { stdio: 'inherit' });

// Move generated assets
['index.html', 'styles.css'].forEach(file => {
  if (fs.existsSync(file)) {
    fs.renameSync(file, path.join(OUTPUT_DIR, file));
    console.log(`📦 Moved ${file} → ${OUTPUT_DIR}/`);
  }
});

console.log('✅ Hallmark integration complete');

```

Add to [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json):

```json
{
  "scripts": {
    "design:new": "node scripts/generate-design.js",
    "design:audit": "node scripts/generate-design.js 'hallmark audit ./src'",
    "build": "npm run design:new && next build"
  }
}

```

For CI environments, pin the skill version by committing `.codex/skills/hallmark/` to your repository rather than relying on global installation.

---

## Customizing Themes and Macrostructures

When built-in themes don't match your brand, Hallmark falls back to [[`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). Edit this file to specify:

- **Color primitives**: primary, secondary, surface, text
- **Type stack**: font families, scale ratios, line heights
- **Spacing system**: base unit, density (compact/default/loose)
- **Corner radius**: rectangular, subtle, or fully rounded

After modifying [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md), any Hallmark verb incorporates your changes automatically. The slop-test still runs, ensuring custom designs avoid common AI-generation artifacts.

---

## Key Source Files for Integration Reference

| Path | Purpose | Integration Relevance |
|------|---------|----------------------|
| [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core rule-set interpreted by editors | Required for all installations |
| [`skills/hallmark/references/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references) | Themes, macrostructures, component recipes | Extend or customize here |
| [[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Bespoke design fallback | Edit for brand alignment |
| [`site/_tests/`](https://github.com/Nutlope/hallmark/tree/main/site/_tests) | Visual regression fixtures | Reference for expected output quality |
| [[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)](https://github.com/Nutlope/hallmark/blob/main/package.json) | npm metadata | Enables `npx skills add` |

All paths are relative to repository root. When installing manually, preserve the `skills/hallmark/` directory structure—relative imports in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) depend on it.

---

## Editor-Specific Integration Notes

### Claude Code

Claude Code loads skills from `~/.claude/skills/`. After installation, invoke Hallmark by typing natural language: *"Use Hallmark to generate a landing page"* or *"Run hallmark audit on ./src"*. The skill parses your intent and executes the appropriate verb.

### Cursor

Cursor treats `hallmark.mdc` as a rule file. It triggers contextually—type "Create a design for..." and Cursor applies Hallmark's macrostructure selection and theme logic without explicit command invocation.

### Codex

Codex supports both global (`~/.codex/skills/`) and project-scoped (`.codex/skills/`) installation. Use project-scoped for team consistency—commit the `hallmark/` folder to version control so all contributors share identical rule-sets.

---

## Summary

- **Install Hallmark** via `npx skills add nutlope/hallmark` or manual copy to editor-specific paths
- **Execute verbs** (`hallmark`, `audit`, `redesign`, `study`) to generate or evaluate static HTML/CSS
- **Automate integration** with Node.js scripts that move output into your project's asset pipeline
- **Customize visuals** through [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md) when built-in themes are insufficient
- **Control versions** by committing skill files to your repository for reproducible builds

Hallmark's zero-runtime architecture means integration adds no bundle size or production dependencies—only rendered static assets.

---

## Frequently Asked Questions

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

No. Hallmark is implemented as a **skill**—a rule-set that AI editors interpret—not a standalone CLI tool. The `npx skills add` command fetches files for editor consumption; there is no independent `hallmark` binary. To use Hallmark outside supported editors, you would need to manually execute the logic in [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) yourself.

### Does Hallmark work with React, Vue, or other frameworks?

Hallmark outputs **vanilla HTML and CSS**, not framework components. Integrate by generating static files and serving them directly, or by embedding the HTML in framework pages via `dangerouslySetInnerHTML` or equivalent. For component-based workflows, run `hallmark study` on Hallmark output to extract design tokens, then manually replicate layouts in your framework.

### How do I downgrade or pin Hallmark to a specific version?

The `npx skills add` installer pulls latest by default. To pin: clone the repository at a specific tag (`git checkout v1.2.3`) and manually copy `skills/hallmark/` to your editor path. Commit this folder to your project repository for reproducible installations across environments.

### What happens if a design fails the slop-test?

Hallmark regenerates the failing aspects automatically—rerunning macrostructure selection, theme application, or both until all 57 quality criteria pass. You do not need to manually intervene; the loop is internal to the skill's execution logic in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).