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

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:

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 and copies the body into .cursor/rules/hallmark.mdc.

Manual Installation

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

# 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). Each produces self-contained index.html + CSS output.

hallmark — Generate New UI

The default verb creates a fresh design from scratch:

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:

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/tree/main/skills/hallmark/references).

hallmark redesign <target> — Rebuild With New Fingerprint

Preserve content while regenerating visuals:

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:

# 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:

// 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:

{
  "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/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, 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)	Core rule-set interpreted by editors	Required for all installations
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)	Bespoke design fallback	Edit for brand alignment
site/_tests/	Visual regression fixtures	Reference for expected output quality
[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 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 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/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.

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