# What Are the Four Main Verbs in Hallmark? Complete Command Reference

> Discover the four main Hallmark verbs: build, audit, redesign, and study. Optimize your design process with this essential command reference for Nutlope/hallmark.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: api-reference
- Published: 2026-07-27

---

**Hallmark operates through four primary commands: the default build pipeline (invoked without a verb), `audit` for read-only safety analysis, `redesign` for restructuring visual layers, and `study` for extracting design DNA from screenshots or URLs.**

Hallmark is an AI-powered design workflow tool maintained in the `Nutlope/hallmark` repository that converts natural language briefs into structured web interfaces. Mastering the four main verbs in Hallmark unlocks its complete public API, enabling you to generate pages, validate code quality, refactor designs, and analyze reference materials.

## The Four Primary Hallmark Commands

According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), Hallmark exposes one default behavior and three explicit verbs. Together, these constitute the entire command surface of the tool.

### Default Build (Implicit Verb)

When you invoke Hallmark without specifying a verb, it executes the standard build pipeline. This command generates a complete page using your current design system without altering existing files or configurations.

The default behavior is triggered by `hallmark <brief>` or explicitly via `hallmark build`. It serves as the primary creation mechanism, interpreting your brief through the lens of established tokens, components, and macro-structures defined in your `.hallmark/` directory.

### hallmark audit

The `audit` verb performs a read-only safety check against anti-pattern lists. As specified in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), this command analyzes a target page, scores it against quality heuristics, and returns a ranked punch-list of issues without writing any files.

Use this command when you need to validate existing markup before refactoring or to establish a baseline quality score for legacy pages. Because it never modifies disk state, `audit` is safe to run in CI pipelines or against production snapshots.

### hallmark redesign

The `redesign` verb restructures the visual and interaction layers of a page or entire application. Defined in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md), this command preserves your existing copy, routes, and component ownership while applying new macro-structures, themes, or mood profiles.

When you run `hallmark redesign`, the tool updates [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) and may emit new token files or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specifications reflecting the transformed architecture. This is the appropriate command for brand refreshes, layout migrations, or thematic overhauls that maintain content parity.

### hallmark study

The `study` verb extracts the "DNA" from external references. As documented in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), this command accepts either a local screenshot path or a live URL, analyzes the macrostructure, archetypes, type-pairing, and color anchors, and produces a diagnosis report.

You can optionally pipe the output directly into a default build or emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file for manual refinement. The `study` command enables rapid cloning of design systems from reference materials without manual specification writing.

## Practical Command Examples

All commands assume execution from the project root containing the `.hallmark/` configuration directory.

```bash

# 1. Default build (no verb specified)

hallmark build "a landing page for a small-batch honey farm"

# 2. Audit a page for anti-patterns (read-only)

hallmark audit src/pages/about.html

# 3. Redesign with a specific mood

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

# 4. Study a reference image

hallmark study ./reference.png

# 5. Study a live URL and lock the DNA

hallmark study https://example.com

```

The `audit` verb operates exclusively in read-only mode, while `redesign` and `study` may create or update [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), or token files as part of their execution flow.

## Key Implementation Files

The following source files define the behavior and protocols for each verb:

- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — Central specification listing the default behavior and three explicit verbs
- [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) — Scoring rules and output format for safety checks
- [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) — Multi-page flow handling and mood parameter specifications
- [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) — Source-mode detection and DNA extraction protocols

## Summary

- **Default (no verb)**: Generates pages using the current design system without file modifications
- **`hallmark audit`**: Read-only safety analysis that scores pages against anti-patterns and returns ranked issue lists
- **`hallmark redesign`**: Restructures visual and interaction layers while preserving content and ownership
- **`hallmark study`**: Extracts design DNA from screenshots or URLs to create portable specifications or direct builds

## Frequently Asked Questions

### What is the difference between the default Hallmark command and hallmark redesign?

The default command creates new pages from natural language briefs using your existing design system without altering current files. The `redesign` verb modifies existing pages or applications, preserving your copy and routes while applying new visual structures or themes. Use the default for greenfield generation and `redesign` for architectural migrations.

### Does hallmark audit modify my source files?

No. According to the implementation in [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the `audit` verb is strictly read-only. It analyzes your markup, scores it against anti-pattern lists, and outputs a diagnostic report, but it never writes to disk. This makes it safe for production validation and continuous integration workflows.

### Can hallmark study analyze both images and live websites?

Yes. The `study` command accepts two input modes as defined in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md): local image files (such as PNG or JPG screenshots) or live URLs. In both cases, it extracts the design DNA including macrostructure, typography, and color systems, then optionally emits a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file or feeds directly into the build pipeline.

### When should I use hallmark study versus the default build command?

Use `hallmark study` when you have a visual reference (screenshot or website) that you want to reverse-engineer into a design system. Use the default build command when you have a text brief or conceptual description and want Hallmark to generate a new page from scratch using your existing design tokens.