The Four Hallmark Commands: Complete CLI Verb Reference

The four Hallmark commands are the default build (invoked without a verb), audit, redesign, and study.

Hallmark is a design-system CLI tool that structures its entire workflow around four primary verbs. According to the source code in the Nutlope/hallmark repository, these commands—defined in skills/hallmark/SKILL.md and verb-specific reference files—constitute the complete public API for generating pages, analyzing anti-patterns, and extracting design DNA.

The Four Hallmark Verbs Explained

Hallmark operates around one default behavior and three explicit verbs, each serving distinct functions in the design workflow.

1. Default Build (Implicit Verb)

The default command runs the standard build pipeline when no verb is specified. As documented in skills/hallmark/SKILL.md, this generates a page using the current design system without altering any existing files. It is invoked by running hallmark <brief> or explicitly with hallmark build <brief>.

2. audit

The audit verb performs a read-only safety check on target pages. According to skills/hallmark/references/verbs/audit.md, it analyzes the target against anti-pattern lists, scores the results, and returns a ranked punch-list for the user. This command never writes files, making it safe for inspection workflows.

3. redesign

The redesign verb restructures the visual and interaction layers of a page or entire application. As specified in skills/hallmark/references/verbs/redesign.md, it preserves copy, routes, and component ownership while applying new macro-structures or themes. Unlike audit, this verb may create or update .hallmark/log.json, token files, or other configuration assets.

4. study

The study verb extracts design "DNA"—including macrostructure, archetypes, type-pairing, and colour anchors—from screenshots or live URLs. According to skills/hallmark/references/study.md, it produces a diagnosis report and optionally emits a portable design.md file or hands results off to the default build for immediate implementation.

How to Use Hallmark Commands

All commands are run from the project root where the .hallmark/ directory lives. Below are practical examples for each verb:

# 1. Default build (no verb)

hallmark build "a landing page for a small-batch honey farm"

# 2. Audit a page (read-only safety check)

hallmark audit src/pages/about.html

# 3. Redesign a page or whole app

hallmark redesign src/pages/home.tsx --mood luxury

# 4. Study a reference (screenshot or URL) and optionally lock the DNA

hallmark study ./reference.png          # image mode

hallmark study https://example.com      # URL mode

The audit verb operates in read-only mode, while redesign and study may modify project files as part of their workflow.

Source Files Defining the Verb API

The implementation and specifications for these commands are maintained in the following files:

• skills/hallmark/SKILL.md — Central specification listing the default behavior and three explicit verbs
• skills/hallmark/references/verbs/audit.md — Implementation notes for the audit verb, including scoring rules and output format
• skills/hallmark/references/verbs/redesign.md — Specification for the redesign verb, covering multi-page flows and mood handling
• skills/hallmark/references/study.md — Protocol for the study verb, describing source-mode detection and DNA extraction

Summary

• Hallmark provides four primary commands: the default build, audit, redesign, and study.
• The default build generates pages without altering files and runs when no verb is specified.
• The audit verb performs read-only safety checks against anti-patterns.
• The redesign verb restructures visual layers while preserving content and routes.
• The study verb extracts design DNA from references and produces diagnostic reports.

Frequently Asked Questions

What is the difference between audit and study in Hallmark?

The audit verb evaluates existing pages against anti-pattern lists to identify issues, while the study verb analyzes external references (screenshots or URLs) to extract design DNA and archetypes. audit is read-only and never writes files, whereas study may generate design.md or other output files.

Does the default Hallmark command modify existing files?

No. According to skills/hallmark/SKILL.md, the default build behavior generates pages using the current design system without altering any existing files in the project. It operates as a pure generation command that respects the existing project state.

Can I run Hallmark without specifying a verb?

Yes. Running hallmark <brief> invokes the default build behavior. You can also use the explicit form hallmark build <brief> for the same result. This implicit verb triggers the build pipeline immediately without requiring explicit command typing.

What files does the redesign verb update?

The redesign verb may create or update .hallmark/log.json, design.md, or token files as part of its flow, according to the specification in skills/hallmark/references/verbs/redesign.md. These updates track the transformation history and design token changes applied during the restructuring process.

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