# How Hallmark's Build, Audit, Redesign, and Study Verbs Work: A Complete Guide

> Master Hallmark's build, audit, redesign, and study verbs. This guide reveals how this design automation pipeline analyzes, rewrites, and extracts design DNA from your code. Unlock efficient design workflows today.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Hallmark's four core verbs—`build`, `audit`, `redesign`, and `study`—form a complete design-automation pipeline that analyzes existing code, rewrites visual systems, and extracts design DNA from external references.**

Hallmark is an open-source design-automation system by Nutlope that enforces structured, version-controlled design decisions through explicit command verbs. While the user-facing CLI exposes four primary verbs, the source implementation in `skills/hallmark/references/verbs/` defines three core workflows: `audit`, `redesign`, and `study`. The `build` verb operates as the generation counterpart to `study`, using extracted or locked design DNA to produce new implementations.

## The Audit Verb: Detecting Drift and Anti-Patterns

The `audit` verb in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) analyzes existing pages and reports structural drift, anti-patterns, and design-system mismatches.

### Core Execution Flow

`audit` follows a three-phase protocol:

1. **File ingestion** — reads target file(s) from the specified path
2. **Finding emission** — for each issue, outputs **Tell** (description), **Where** (location), **Severity** (critical/warning/note), and **Fix** (remediation)
3. **Aggregation** — groups findings by severity and appends a final count

### Key Validation Rules

- **AI-template macrostructure detection** — flags AI-generated template macrostructures as *critical* severity
- **Stamp verification** — validates the `/* Hallmark · macrostructure: … */` comment against actual page structure
- **Genre-aware checks** — applies contextual rules based on page genre
- **Design-system audit** — when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists, validates theme, macrostructure family, and stamp consistency
- **Diversification rule** — uses similarity analysis (or its inversion) to distinguish intentional patterns from "slop"

```bash

# Audit a single page

hallmark audit ./src/pages/about/page.tsx

# Audit multiple files

hallmark audit ./src/pages/**/*.tsx

```

## The Redesign Verb: Non-Destructive Visual Rewrites

The `redesign` verb in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) rewrites a page's visual and interaction layer while preserving content and route structure.

### Scope Detection: Single-Page vs. Multi-Page

`redesign` automatically detects scope and branches accordingly:

- **Single-page flow** — classic redesign with direct macrostructure selection
- **Multi-page flow** — system-level redesign that generates a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) first

### Multi-Page Design System Generation

For multi-page projects, `redesign` creates a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file that becomes the single source of truth. Subsequent page redesigns must obey its:

- Design tokens
- Typography scale
- Spacing system
- Motion presets
- Micro-interaction patterns

### Implementation Rules

- **Non-destructive implementation rule** — never deletes existing routes or components without explicit approval
- **Stamping requirement** — each output page receives a `/* Hallmark · genre: … · macrostructure: … · design-system: … */` comment for drift detection

```bash

# Redesign single page with mood directive

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

# Redesign entire app (generates design.md, then processes all pages)

hallmark redesign ./src/app --mood modern

```

### Stamp Mismatch Detection

Future `audit` runs compare actual page structure against stamped metadata. A mismatch triggers critical findings, enabling continuous drift detection across the codebase.

## The Study Verb: Extracting Design DNA

The `study` verb in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) extracts structured design intelligence from reference screenshots or live URLs through a rigorous protocol.

### Source Mode Detection

`study` automatically determines input type:

- **URL mode** — fetches HTML and same-origin CSS via HTTPS, ignores scripts
- **Image mode** — analyzes static screenshot, infers structure visually

### Five-Step Extraction Protocol

The verb runs a systematic analysis across five layers:

| Step | Focus | Output |
|------|-------|--------|
| Surface | Color, texture, materiality | Exact `oklch`/hex values (URL) or color bands (image) |
| Type | Typography scale, hierarchy, roles | Font names (URL) or type roles (image) |
| Structure | Layout macrostructure, grid, containment | Macrostructure classification |
| Motion | Animation patterns, transition physics | Easing, duration, stagger values |
| Rhythm | Pacing, density, visual cadence | Spacing scale, component frequency |

Results populate a strict JSON schema that maps to catalog themes.

### Safety and Refusal Layers

- **Auto-refuse** — paid-template URLs
- **Soft-refuse** — copyrighted designer work (requires clarification)
- **Ambiguity check** — requests clarification on uncertain sources

### Remote URL Security

`study` enforces multiple safeguards before fetching:

- HTTPS-only protocol
- Private IP blocking
- Redirect prohibition
- Non-web scheme rejection

### Fallback Handling

**Junk-or-blocked detection** identifies login walls, SPA shells, or unusable pages and automatically falls back to screenshot-based analysis.

### Post-Diagnosis Actions

After extraction completes, `study` offers three paths:

1. **Build with DNA** — immediately use extracted patterns for generation
2. **Lock to design.md** — persist DNA to portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (requires explicit attestation for URL sources; automatic for images)
3. **Stop** — review report without action

```bash

# Study live site (URL mode)

hallmark study https://example.com/landing

# Study screenshot (image mode)

hallmark study /path/to/screenshot.png

```

## The Build Verb: Generating from Design DNA

While not documented in the reference verbs directory, `build` functions as the **generation counterpart to `study`**.

`build` consumes:

- Output from `study` (immediate DNA)
- Locked [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files
- Catalog themes and macrostructure libraries

It produces implementation-ready code stamped with provenance metadata, maintaining the same non-destructive guarantees as `redesign`.

## Runtime Integration: CSS Stamp Interpretation

The [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) file provides runtime support that interprets Hallmark's CSS stamps and applies the active design system in the browser. This ensures that stamped pages render correctly regardless of how they were generated.

## Summary

- **`audit`** — analyzes existing code for drift and anti-patterns, with stamp verification and genre-aware rules defined in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md)
- **`redesign`** — non-destructively rewrites visual systems, with automatic scope detection and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) generation for multi-page projects per [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md)
- **`study`** — extracts design DNA from URLs or images through a five-step protocol with comprehensive safety checks, as specified in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)
- **`build`** — generates new implementations from extracted or locked design DNA, completing the pipeline

All verbs maintain explicit, version-controlled design decisions through mandatory stamping, enabling continuous drift detection and reversible transformations.

## Frequently Asked Questions

### What happens if a page's stamp doesn't match its actual structure?

Hallmark's `audit` verb flags this as a *critical* finding. The `/* Hallmark · macrostructure: … */` stamp is compared against detected structure, and mismatches indicate manual edits or drift from the design system. This enables teams to catch unauthorized changes before they propagate.

### Can I use `study` on any website without restrictions?

No. `study` implements multiple refusal layers: it auto-rejects paid-template URLs, soft-refuses recognizable copyrighted designer work, and requires explicit user attestation before emitting [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) from URL sources. Private IPs, non-HTTPS schemes, and redirects are blocked at the network layer.

### What's the difference between `redesign` with and without a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file?

Without [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), `redesign` operates in single-page mode, selecting macrostructures and visual treatments per-page. With [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (either pre-existing or generated via multi-page scope detection), all pages must obey the locked tokens, typography, spacing, and motion settings—ensuring systemic consistency across the entire application.

### How does `study` handle modern JavaScript-heavy sites?

`study` fetches only HTML and same-origin CSS, ignoring all scripts. If the fetched result is a login wall, SPA shell, or otherwise content-free (detected via junk-or-blocked analysis), it automatically falls back to screenshot-based extraction. For SPAs, this typically means capturing the initial shell state rather than the hydrated application.