How to Configure Hallmark: Complete Installation and Setup Guide

Install Hallmark with npx skills add nutlope/hallmark, deploy the skill definition files to your AI tool's specific directory, and execute CLI verbs like audit or redesign to enforce design standards across your codebase.

Hallmark is an open-source design skill for AI coding assistants that enforces typographic discipline and structural consistency across Claude Code, Cursor, and Codex. Configuring Hallmark requires installing the skill package, placing reference files in tool-specific locations, and optionally connecting existing design assets. This guide covers the complete configuration process using the actual implementation from the Nutlope/hallmark repository.

1. Install the Hallmark Skill

Run the one-line installation command to download the latest version:

npx skills add nutlope/hallmark

This command, documented in the repository's README.md (lines 94-99), registers Hallmark in your environment and pulls the skill definition files.

2. Deploy Skill Definition Files to Your AI Tool

After installation, copy SKILL.md and the entire references/ directory to the location required by your specific AI tool.

Claude Code Configuration

Create the skills directory and copy the files:

mkdir -p ~/.claude/skills/hallmark
cp skills/hallmark/SKILL.md ~/.claude/skills/hallmark/
cp -r skills/hallmark/references ~/.claude/skills/hallmark/

Cursor Configuration

Place the body of SKILL.md (excluding frontmatter) at .cursor/rules/hallmark.mdc in your project root.

Codex Configuration

Copy to either ~/.codex/skills/hallmark/ for personal use or .codex/skills/hallmark/ for project-scoped installation.

These instructions are detailed in README.md (lines 100-105). The SKILL.md file contains the core rule-set and pre-flight detection logic, while the references/ directory holds the theme catalogue and custom theme protocols.

3. Configure Project-Specific Assets (Optional)

Hallmark automatically detects existing design systems by scanning for specific files in your project root:

• package.json – identifies installed font packages
• tailwind.config.{js,ts} – extracts current Tailwind theme configuration
• tokens.json or DTCG-style design token files – imports colour palettes
• Existing HTML/CSS files – preserves current typography and colour values

As implemented in skills/hallmark/SKILL.md (lines 149-155), Hallmark does not overwrite detected assets without explicit prompting. If you want to force a fully custom theme instead of using the 20 built-in catalog themes, trigger the custom workflow described below.

4. Select a Theme Route: Catalog vs. Custom

Hallmark decides between default catalog themes and custom generation based on signals defined in skills/hallmark/references/custom-theme.md (lines 18-25).

Catalog route (default): Activated when no custom signals are detected. Hallmark silently proceeds with one of 20 pre-defined themes.

Custom route triggers:

• Explicit ask – user types "custom", "tailored", or "bespoke"
• Named brand colour – provides a hex or OKLCH anchor value
• Multi-attribute vibe – uses three or more descriptive adjectives that don't map to catalog themes
• Brand-mood reference – attaches a colour swatch or moodboard
• Singular structural vision – specifies a unique layout not covered by catalog macrostructures

When any signal fires, Hallmark asks a single follow-up question: "Custom needs one input – describe the brand's vibe in 4–8 words … (optional anchor colour)."

5. Using Hallmark CLI Verbs

Hallmark provides four primary operations defined in the Four verbs table of README.md (lines 17-24):

Verb	Purpose	Example
hallmark	Build new UI from scratch using chosen theme	hallmark
hallmark audit <target>	Score existing code against anti-patterns without making changes	hallmark audit src/
hallmark redesign <target>	Keep copy/IA/brand but rebuild UI with different fingerprint	hallmark redesign src/
hallmark study <screenshot|URL>	Extract design DNA (macrostructure, typography, colour) from existing site	hallmark study https://example.com

6. Custom Theme Workflow

When custom signals are detected, Hallmark executes the protocol defined in skills/hallmark/references/custom-theme.md:

1. Capture vibe and anchor – Provide 4–8 word description plus optional hex code (e.g., "archival warmth, hand-set, no varnish" + #c0392b)
2. Generate OKLCH palette – Built following §B Palette construction guidelines
3. Select font pairing – Determined per §C Font pairing protocols
4. Insert stamp comment – Records theme metadata at the top of generated stylesheets:

/* Hallmark · macrostructure: Long Document …
 * theme: custom · vibe: "archival warmth, hand-set, no varnish"
 * paper: oklch(94% 0.020 65) · accent: oklch(58% 0.16 35)
 * display: Fraunces italic · body: Source Serif 4
 * axes: light / italic-serif / chromatic-terracotta
 * studied: no · context: explicit · v0.8.0 */

5. Log entry – Writes to .hallmark/log.json capturing theme data for future audits (lines 40-48 of custom-theme.md).

7. Advanced Configuration: Tailwind and Design Tokens

For Tailwind v4 projects, Hallmark expects @theme tokens exposed directly (avoiding theme.extend). Custom palettes can be exported to your project's tokens.css or tokens.json for reuse across components.

If no Tailwind configuration exists, Hallmark generates a minimal tailwind.config.ts that reads inline :root variables via @theme. This guidance appears in skills/hallmark/references/export-formats.md (lines 210-314).

Example: Running a Custom Design Pass

# Default catalog build

hallmark

# Custom redesign with signal detection

hallmark redesign ./my-project

# When prompted for vibe: "archival warmth, hand-set, no varnish" #c0392b

Example: Auditing Existing Code

hallmark audit ./src

# Returns JSON report of anti-pattern scores and violations

Example: Studying External Designs

hallmark study https://www.usehallmark.com/examples/cobalt-01/

# Generates design.md with macrostructure, typography, and colour DNA

Summary

• Install Hallmark via npx skills add nutlope/hallmark
• Deploy SKILL.md and references/ to tool-specific directories (~/.claude/skills/hallmark/, .cursor/rules/, or ~/.codex/skills/hallmark/)
• Detect existing assets (tailwind.config, tokens.json, package.json) automatically without overwriting
• Trigger custom themes using signals (explicit ask, brand colours, multi-attribute vibes) defined in skills/hallmark/references/custom-theme.md
• Execute four CLI verbs: hallmark, audit, redesign, and study
• Stamp generated code with metadata comments and log to .hallmark/log.json for audit trails

Frequently Asked Questions

Where does Hallmark store its configuration files?

Hallmark stores skill definitions in tool-specific directories: ~/.claude/skills/hallmark/ for Claude Code, .cursor/rules/hallmark.mdc for Cursor, and ~/.codex/skills/hallmark/ for Codex. Project-specific outputs like logs and stamps are written to .hallmark/log.json in your working directory.

How does Hallmark detect my existing design system?

During pre-flight, Hallmark scans for package.json (fonts), tailwind.config.{js,ts} (themes), tokens.json (DTCG tokens), and existing HTML/CSS files. This detection logic in skills/hallmark/SKILL.md (lines 149-155) ensures Hallmark respects existing variables and does not overwrite assets without prompting.

Can I force Hallmark to use a custom theme instead of the catalog?

Yes. Hallmark switches to custom mode when it detects specific signals: explicit requests for "custom" or "tailored" work, provided hex/OKLCH brand colours, three or more descriptive adjectives, attached moodboards, or unique layout requirements. When triggered, it asks for a 4-8 word vibe description and optional anchor colour, then builds an OKLCH palette per skills/hallmark/references/custom-theme.md.

What is the difference between hallmark audit and hallmark redesign?

hallmark audit analyzes existing code against anti-patterns and returns a JSON report without modifying files, while hallmark redesign preserves your copy, information architecture, and brand but rebuilds the UI implementation using a different theme fingerprint or custom palette.

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