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

> Understand Hallmark's four verbs: default, audit, redesign, and study. Learn how these verbs guide AI to generate, evaluate, refactor, and analyze UI code for handcrafted results.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-04

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) as canonical sources of truth.

**Example invocation:**

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/audit.md).

**Example invocation:**

```bash
hallmark audit ./app/page.tsx

```

**Sample output:**

```markdown

## 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`](https://github.com/Nutlope/hallmark/blob/main/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:**

```bash

# Single page with mood override

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

# Multi-page application-wide redesign

hallmark redesign ./app

```

**Preview output:**

```markdown
**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`](https://github.com/Nutlope/hallmark/blob/main/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:**

```bash

# Image mode

hallmark study ./screenshots/competitor.png

# URL mode

hallmark study https://example.com/product

```

**Sample diagnosis:**

```markdown
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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) | Master skill definition; default flow, genre/theme routing, diversification | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md) | `audit` verb implementation; input handling, output format, stamp checks | [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) |
| [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md) | `redesign` verb implementation; scope detection, non-destructive rules, flows | [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) |
| [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) | `study` verb implementation; image/URL pipelines, DNA extraction, diagnosis | [`skills/hallmark/references/verbs/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md) |
| [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) | Index of 21 named layout patterns used across all verbs | [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) |
| [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | Central token store for color, font, spacing; read/written by verbs | [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.