Hallmark's Four Verbs Explained: `default`, `audit`, `redesign`, and `study`

Hallmark uses four verbs—default, audit, redesign, and study—to govern how AI assistants generate, evaluate, refactor, and analyze UI code, ensuring handcrafted output instead of templated slop.

Hallmark is an AI design skill that enforces anti-slop discipline on generated frontend code. Rather than producing generic Tailwind defaults, it routes every design request through one of four intentional verbs, each defined in dedicated reference files under skills/hallmark/references/verbs/. This article breaks down how each verb works, when to use it, and what happens under the hood according to the Hallmark source code.

---

default: Generate New UI From Scratch

The default verb is Hallmark's implicit starting point—triggered whenever a user asks to design, build, or create something without specifying another verb. It produces brand-new pages or components through a rigorous seven-step pipeline documented in SKILL.md.

Core workflow

1. Pre-flight scan – detects existing fonts, color palette, motion libraries, and framework
2. Genre detection – selects from editorial, modern-minimal, atmospheric, or playful
3. Macrostructure pick – chooses a named layout from macrostructures.md (e.g., Marquee Hero, Bento Grid)
4. Theme route – defaults to the catalog of 20 named themes (Bloom, Coral, etc.); custom themes only when explicitly briefed
5. Enrichment decision – typically typographic-only; richer hero enrichment requires explicit request
6. Preview block – emits a markdown summary of macrostructure, theme, sections, motion, and diversification strategy
7. Slop-test – runs 58 gate checks; failures are auto-fixed before code emission

The default verb never deletes files and treats existing design.md or tokens.css as canonical sources of truth.

Example invocation:

hallmark design "Create a landing page for a SaaS analytics tool"

---

audit: Lint Existing Code Without Modifying It

The audit verb performs read-only analysis of target files, extracting design elements and returning a ranked punch-list of anti-patterns. It is strictly non-destructive—no files are ever modified.

Input and output format

• Input: One or more file paths (pages, components, CSS files)
• Output: Plain-text list grouped by severity with four fields per finding:
  • Tell – named anti-pattern (e.g., Eyebrow-left header-right)
  • Where – file path and line range
  • Severity – critical, major, or minor
  • Fix – one-line concrete correction

The audit also enforces stamp-vs-page consistency: a file stamped macrostructure: Bento Grid must actually follow that shape. Genre-specific overrides are respected per audit.md.

Example invocation:

hallmark audit ./app/page.tsx

Sample output:

## Critical (2)

- Eyebrow-left header-right on ./app/page.tsx L42-L45
- Default three-equal-card grid on ./components/Features.tsx L12-L20

## Major (1)

- Italic header on ./components/Header.tsx L3

## Minor (0)

---

redesign: Restructure Visual Layers In-Place

The redesign verb performs non-destructive refactoring of existing pages or applications. It preserves routes, copy intent, brand colors, fonts, and information architecture while replacing the visual fingerprint.

Single-page vs. multi-page flows

Mode	Behavior
Single-page	Replaces macrostructure, component voice, reveal pattern, and visual rhythm for one target file
Multi-page	Creates or updates a design.md system-wide guide; subsequent pages share theme, accent, and typography, varying only in macrostructure

The redesign verb never deletes routes or component directories unless the user explicitly authorizes it. It respects audit findings—pages that drift from their own stamp trigger critical findings.

Example invocations:

# Single page with mood override

hallmark redesign ./app/about/page.tsx --mood luxurious

# Multi-page application-wide redesign

hallmark redesign ./app

Preview output:

**Hallmark · v1.1.0**

- Macrostructure · Stat-Led
- Theme · Paper: light, Accent: cool-blue
- Enrichment · none (typography only)
- Sections · Hero · Stats · Features · CTA · Footer
- Motion · fade-up · scale-pulse
- Diversification · differs from previous on accent hue

---

study: Extract DNA From Screenshots or URLs

The study verb reverse-engineers design DNA from external sources—either screenshots (image mode) or live URLs (URL mode). It produces a structured diagnosis that users can act on in three ways.

Extraction pipeline (five steps)

1. Surface – paper lightness, hue, accent footprint, distinctive treatments
2. Type – roles (display, body, label) and exact faces when in URL mode
3. Structure – matches to named macrostructure and selects archetypes for hero, nav, footer
4. Motion – discovers motion libraries, reveal patterns, and anti-patterns
5. Rhythm – density, asymmetry, spacing (screenshots only; URL mode marks as unknown)

Three possible outcomes

After the diagnosis, the user chooses:

1. Build – hand off extracted DNA to default for new implementation
2. Lock – save DNA to portable design.md for reuse
3. Stop – read the report and take no further action

Safeguards: study refuses paid-template marketplaces and validates that URL-mode inputs are public https:// pages (no IP literals, no private hosts, no disallowed schemes).

Example invocations:

# Image mode

hallmark study ./screenshots/competitor.png

# URL mode

hallmark study https://example.com/product

Sample diagnosis:

I read https://example.com/product.

The page is a **Marquee Hero**. The hero is an **H1-Marquee** with ratio=7/5.
Nav is **N5 Floating-pill**; footer is **Ft5 Statement**.

The page loads **Inter** for display and **Geist** for body. Roles: display = neutral grotesque, body = neutral grotesque.

The paper is `oklch(96% 0.01 90)` – a light warm band. The accent is `#c0392b` – warm-red, small ≤ 5 % footprint.

Motion: the page uses **framer-motion**; reveal pattern is **fade-up**.

Rhythm — density and asymmetry — I can't judge from the HTML alone. If those matter, send a screenshot as well.

Want me to build with this DNA, or change one axis first?

---

Key Reference Files

File	Purpose	Location
SKILL.md	Master skill definition; default flow, genre/theme routing, diversification	skills/hallmark/SKILL.md
audit.md	audit verb implementation; input handling, output format, stamp checks	skills/hallmark/references/verbs/audit.md
redesign.md	redesign verb implementation; scope detection, non-destructive rules, flows	skills/hallmark/references/verbs/redesign.md
study.md	study verb implementation; image/URL pipelines, DNA extraction, diagnosis	skills/hallmark/references/verbs/study.md
macrostructures.md	Index of 21 named layout patterns used across all verbs	skills/hallmark/references/macrostructures.md
tokens.css	Central token store for color, font, spacing; read/written by verbs	site/css/tokens.css

---

Summary

• default –implicitly triggered when building new UI; runs 58 slop-tests before emitting code
• audit – read-only linting that produces ranked anti-pattern punch-lists without file modification
• redesign – non-destructive refactoring that replaces visual fingerprint while preserving IA and brand assets
• study – DNA extraction from screenshots or URLs, producing actionable diagnoses with three exit paths

Hallmark's four verbs create a complete design lifecycle: generate, evaluate, refactor, and learn. Each verb is intentionally constrained—no deletions without authorization, no modifications during audit, no rhythm analysis from URLs—to keep AI-assisted UI development predictable and high-quality.

---

Frequently Asked Questions

How do I know which Hallmark verb to use?

Use default for new designs, audit to evaluate existing code without changes, redesign to refactor visuals while preserving structure, and study to learn from external references. The verbs are mutually exclusive in a single request—combine them sequentially rather than simultaneously.

Can audit fix the problems it finds?

No. audit is strictly read-only. To fix issues, run redesign on the audited files or manually address the critical/major/minor findings. The audit output includes a one-line fix suggestion for each finding to streamline manual correction.

What happens if study can't access a URL?

study validates URLs before fetching: it requires public https:// schemes, rejects IP literals and private hosts, and refuses known paid-template marketplaces. If validation fails, the verb exits with an explanation and prompts for an alternative input (screenshot or different URL).

Does redesign preserve my React components?

Yes, with caveats. redesign preserves routes, copy intent, information architecture, and brand tokens defined in tokens.css. It replaces macrostructure, visual rhythm, and component voice—so the shape of components changes, but their existence and hierarchy remain unless you explicitly authorize deletion.

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