How to Use the Nutlope Hallmark CLI: Complete Command Guide

Run hallmark with one of four verbs—default (build), audit, redesign, or study—to generate non-generic UIs, score existing code, or extract design DNA from reference sites.

The Hallmark CLI is a specialized tool for AI-assisted workflows that helps you build user interfaces that avoid the "AI-generated" look. Developed by Nutlope, this skill installs via npx and integrates directly with coding assistants like Claude Code, Cursor, and Codex. This guide covers all four CLI verbs, installation paths, and practical workflows based on the actual source code.

Installation and Setup

Install the Hallmark skill using the npx skills command:

npx skills add nutlope/hallmark

Re-running this command updates the skill to the latest version. The CLI binaries are placed in assistant-specific directories depending on your environment:

Assistant	Installation Path
Claude Code	~/.claude/skills/hallmark/
Cursor	.cursor/rules/hallmark.mdc (content from SKILL.md)
Codex (personal)	~/.codex/skills/hallmark/
Codex (project)	.codex/skills/hallmark/

After installation, the hallmark command becomes available in your terminal. The core logic resides in skills/hallmark/SKILL.md, which defines the rule-set for all four verbs.

The Four Hallmark CLI Commands

Default: Build a New UI from Brief

Running hallmark without arguments triggers the default verb, which constructs a complete UI from a design brief in your current directory.

hallmark

This command executes a full pipeline: it selects a macrostructure, applies one of 21 built-in themes, runs 57 slop-test gates to catch generic patterns, and outputs self-contained HTML and CSS files. The resulting page is designed to look intentionally crafted rather than AI-generated.

Audit: Score Code Against Anti-Patterns

The audit verb analyzes existing code without making automatic edits. It identifies Hallmark anti-patterns such as over-reliance on utility classes, unanchored color palettes, or generic component structures.

hallmark audit ./src

Output includes a punch-list of warnings categorized by severity. Common detection patterns include:

• Generic utility class overuse
• Color systems not anchored to OKLCH
• Missing typographic hierarchy
• Predictable layout grids

Use this to assess whether a codebase meets Hallmark's design quality standards before refactoring.

Redesign: Preserve Content, Refresh Visuals

The redesign verb rebuilds the visual layer while preserving information architecture, copy, and brand assets. This is useful when you want a fresh design fingerprint without rewriting content.

hallmark redesign ./src

Hallmark dissolves the existing visual structure, then re-synthesizes the page using its macrostructure library and theme system. The resulting files maintain all original text content but present it through an entirely new design lens.

Study: Extract Design DNA from References

The study verb scrapes reference designs—either live URLs or local screenshots—and extracts their core design parameters.

hallmark study https://www.usehallmark.com/examples/tally/

Hallmark identifies three key elements:

1. Macrostructure – the high-level layout pattern
2. Typography pairing – the font combination and scale system
3. Color anchor – the base color methodology (often OKLCH-based)

Add the --output flag to generate a portable design.md file:

hallmark study https://example.com/page --output design.md

This file can be handed off to other AI tools or used as a reference for subsequent hallmark commands.

Complete Workflow Examples

New Project Bootstrap

# Create project directory with design brief

mkdir my-landing-page && cd my-landing-page
echo "SaaS pricing page for AI code review tool" > brief.txt

# Generate the UI

hallmark

# → index.html, style.css, and assets created

Refactoring an Existing Codebase

# First, assess current state

hallmark audit ./legacy-site

# Review output, then apply redesign

hallmark redesign ./legacy-site

# Verify improvements with second audit

hallmark audit ./legacy-site

Building a Design System from References

# Extract patterns from multiple references

hallmark study https://site1.com --output ref1.md
hallmark study https://site2.com --output ref2.md

# Use extracted DNA to inform new design

hallmark  # uses brief.md combined with learned patterns

Core Architecture and Key Files

Understanding the file structure helps when customizing or debugging:

File	Purpose
skills/hallmark/SKILL.md	Core rule-set defining all four CLI verbs
skills/hallmark/references/	Design references including macrostructures, color palettes, typography systems, and custom theme logic
package.json	Skill manifest with entry point and serve script for demos
site/js/main.js	Reference implementation showing expected output format
docs/recipes.md	Advanced usage patterns and command chaining techniques

The CLI parses your input, consults SKILL.md for behavior definitions, and applies rules from the references/ directory to transform or generate code. All output is generated through this consistent rule pipeline rather than hardcoded templates.

Summary

• Install with npx skills add nutlope/hallmark
• Build new UIs by running hallmark in a directory with a brief
• Audit existing code with hallmark audit <path> to catch anti-patterns
• Redesign while preserving content using hallmark redesign <path>
• Study reference designs via hallmark study <url> to extract portable design DNA

Each command consumes the same rule-set defined in skills/hallmark/SKILL.md, ensuring consistent quality whether you're generating, analyzing, or transforming UI code.

Frequently Asked Questions

How do I update the Hallmark CLI to the latest version?

Re-run the installation command: npx skills add nutlope/hallmark. According to the repository README, this automatically pulls the latest skill version and updates the binaries in your assistant's skill directory without requiring manual file management.

What file format does hallmark study output?

By default, the study verb prints extracted design parameters to your terminal. When you specify --output design.md, it generates a structured Markdown file containing macrostructure, typography pairing, and color anchor details that other AI tools can parse and apply to new designs.

Can I customize the 21 built-in themes?

Yes. The skills/hallmark/references/ directory contains the theme definitions and custom-theme logic. Advanced users can extend or override these references, as documented in docs/recipes.md, to introduce company-specific design systems while maintaining Hallmark's anti-slop testing pipeline.

Why does hallmark audit not auto-fix detected issues?

The audit verb intentionally produces reports without automatic edits. This design choice—implemented in SKILL.md—ensures developers review and understand each anti-pattern before applying changes, preventing superficial fixes that might pass gates without addressing underlying design quality problems.

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