Hallmark Four Verbs Explained: Default, Audit, Redesign, and Study

The four Hallmark verbs are: (default) for building new UIs from scratch, audit for scoring files against anti-patterns, redesign for visual refreshes that preserve implementation, and study for extracting design DNA from screenshots or URLs.

Hallmark is an open-source CLI tool for AI-assisted UI generation maintained in Nutlope/hallmark. Each verb represents a distinct workflow for working with web interfaces—whether you're starting fresh, evaluating existing code, refreshing a design, or learning from references you admire. This guide breaks down each of the four Hallmark verbs, their specific functions, and when to apply them based on the source implementation.

The Default Verb: Build New UIs From Scratch

Running Hallmark without an explicit verb triggers the default build workflow. This is the primary entry point for greenfield UI generation.

When you execute hallmark <target>, the tool:

• Selects a macrostructure suited to your content
• Applies your chosen theme
• Runs the full slop-test suite to catch AI-generation issues
• Returns a generated page without modifying any existing files

This verb is purely additive—it never overwrites your codebase. According to the README (lines 17–25), this is the designed behavior for rapid prototyping and standalone page generation.

# Generate a fresh hero section

hallmark ./hero.tsx

# Build an entire landing page

hallmark ./src/pages/pricing.tsx

Audit Verb: Score Code Without Editing

The hallmark audit verb performs read-only analysis of existing files. It evaluates code against Hallmark's anti-pattern database and returns a categorized punch-list without touching your source.

The audit workflow, documented in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), classifies findings into:

• Critical — Blocking issues that break accessibility or UX
• Major — Significant deviations from best practices
• Minor — Polish and refinement opportunities

# Audit a single component

hallmark audit ./src/components/Hero.tsx

# Audit multiple pages

hallmark audit ./src/pages/*.tsx

Use this verb for code reviews, legacy codebase assessments, or pre-deployment checks where you need visibility without side effects.

Redesign Verb: Refresh Visuals While Preserving Code

The hallmark redesign verb enables controlled visual evolution. It accepts existing content—copy, information architecture, and branding—and generates updated visual structure, rhythm, and component voice.

Key characteristics from [skills/hallmark/references/verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md):

• Preserves underlying implementation unless explicitly overridden
• Supports optional --mood flag for directional styling
• Maintains content integrity while shifting aesthetic presentation

# Redesign with default mood detection

hallmark redesign ./src/pages/about.tsx

# Explicitly specify a luxury aesthetic

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

# Apply minimal/clean treatment

hallmark redesign ./src/pages/pricing.tsx --mood minimal

This verb solves the "refresh without rebuild" scenario—ideal for brand updates, seasonal campaigns, or A/B testing visual directions.

Study Verb: Extract Design DNA From References

The hallmark study verb reverse-engineers design intelligence from sources you want to learn from. It operates on either live URLs or local screenshot files, producing a structured analysis of what makes the reference effective.

Per [skills/hallmark/references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), the extraction includes:

• Macrostructure and layout patterns
• Type pairing and typographic hierarchy
• Color anchoring and palette logic

Hallmark's study protocol explicitly rejects pixel-perfect clones and paid template listings—it extracts principles, not reproductions. Optionally emits a portable design.md for use in downstream AI workflows.

# Study a live website

hallmark study https://linear.app

# Analyze a local screenshot

hallmark study ./screenshots/linear-landing.png

# Generate portable design spec

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

Comparison: When to Use Each Hallmark Verb

Verb	Input	Output	Modifies Source?	Best For
(default)	Target path	New UI files	No	Greenfield development, rapid prototyping
audit	Existing files	Issue report	No	Code review, quality gates, slop detection
redesign	Existing files + optional mood	Updated UI	User-controlled	Brand refreshes, visual A/B tests
study	URL or screenshot	Design DNA analysis	No	Competitive analysis, inspiration workflows

Summary

• Default verb (hallmark <target>) builds new UIs with full slop-testing, never touching existing files
• Audit verb (hallmark audit <target>) scores code against anti-patterns in read-only mode
• Redesign verb (hallmark redesign <target>) refreshes visuals while preserving implementation, with optional mood targeting
• Study verb (hallmark study <URL\|screenshot>) extracts design DNA from references for principle-based learning

Each verb maps to specific reference documentation in skills/hallmark/references/verbs/ and skills/hallmark/references/study.md, making the implementation transparent and extensible.

Frequently Asked Questions

What happens if I run Hallmark without specifying a verb?

The default verb executes automatically. This triggers a complete UI build from scratch using the target path you provide. The tool selects appropriate macrostructure, applies themes, runs slop detection, and emits freshly generated files without modifying anything in your existing codebase.

Does Hallmark audit modify my source files?

No. The audit verb is explicitly read-only. It analyzes supplied files against the anti-pattern database and returns a categorized report of critical, major, and minor issues. As documented in skills/hallmark/references/verbs/audit.md, editing source files is outside this verb's scope.

How does redesign differ from the default build verb?

Redesign preserves your existing implementation while refreshing visual presentation. It takes your current content—copy, IA, and branding—and generates updated structure, rhythm, and component voice. The default build, by contrast, creates entirely new UIs without reference to existing files. Use redesign for controlled evolution; use default for greenfield creation.

Can I use Hallmark to clone websites I admire?

No. The study verb explicitly rejects pixel-clones and paid-template listings. It extracts design DNA—macrostructure, type-pairing, color logic—rather than reproducing visuals. This produces a portable design.md specification you can apply to your own original work, not a copy of the reference.

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