# How to Configure Hallmark: Complete Installation and Setup Guide

> Easily configure Hallmark with our complete installation guide. Install the nutlope/hallmark skill and deploy definition files to enforce design standards across your codebase.

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

---

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

```bash
npx skills add nutlope/hallmark

```

This command, documented in the repository's [`README.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/README.md) (lines 100-105). The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) – identifies installed font packages
- `tailwind.config.{js,ts}` – extracts current Tailwind theme configuration
- [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) capturing theme data for future audits (lines 40-48 of [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json) for reuse across components.

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

### Example: Running a Custom Design Pass

```bash

# 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

```bash
hallmark audit ./src

# Returns JSON report of anti-pattern scores and violations

```

### Example: Studying External Designs

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and `references/` to tool-specific directories (`~/.claude/skills/hallmark/`, `.cursor/rules/`, or `~/.codex/skills/hallmark/`)
- **Detect** existing assets (`tailwind.config`, [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json), [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) in your working directory.

### How does Hallmark detect my existing design system?

During pre-flight, Hallmark scans for [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) (fonts), `tailwind.config.{js,ts}` (themes), [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json) (DTCG tokens), and existing HTML/CSS files. This detection logic in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.