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

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 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 exists, validates theme, macrostructure family, and stamp consistency
• Diversification rule — uses similarity analysis (or its inversion) to distinguish intentional patterns from "slop"

# 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 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 first

Multi-Page Design System Generation

For multi-page projects, redesign creates a 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

# 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 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 (requires explicit attestation for URL sources; automatic for images)
3. Stop — review report without action

# 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 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 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
• redesign — non-destructively rewrites visual systems, with automatic scope detection and design.md generation for multi-page projects per 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
• 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 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 file?

Without design.md, redesign operates in single-page mode, selecting macrostructures and visual treatments per-page. With 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.

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