# How to Use the Hallmark API: A Complete Guide to the Anti-Slop Design CLI

> Master the Hallmark API with this guide. Learn to generate, audit, and redesign UI pages using the anti-slop design CLI for a robust design system.

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

---

**Install the Hallmark skill with `npx skills add nutlope/hallmark`, then invoke the `hallmark` binary with one of four verbs—generate (default), audit, redesign, or study—to build, validate, or analyze UI pages against a strict design system.**

Hallmark is an AI-assisted design skill that generates production-ready HTML and CSS through a command-line interface. If you are researching how to use the Hallmark API, the entry points are defined in the skill manifest at [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and executed through the `hallmark` binary. The API processes natural-language briefs, existing files, or live URLs through four distinct workflows that enforce a 57-gate anti-pattern validation system.

## Installing the Hallmark API

The Hallmark API is distributed as an **npm-compatible skill** rather than a traditional package. Installation registers the CLI binary and copies the skill definition to your local AI assistant environment (Claude Code, Cursor, or Codex).

Run the following command in your project root:

```bash
npx skills add nutlope/hallmark

```

Once installation completes, the `hallmark` command is available on your `$PATH`. The skill manifest at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) declares the supported verbs, version constraints, and safety rails that govern all subsequent operations.

## The Four Core CLI Commands

The Hallmark API exposes four primary verbs, each targeting a different stage of the design lifecycle.

### Generate a New Page (Default)

Running `hallmark` without a verb triggers the **default design flow**, which builds a new page from a text brief. This flow performs a pre-flight scan of your existing project files ([`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, etc.), selects a genre and catalog theme from the `THEMES` object in [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), and interpolates your brief with component archetypes (hero, navigation, footer).

```bash
echo "Build a SaaS landing page for a data-visualisation tool." | hallmark

```

The command outputs a self-contained folder containing [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html), [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), and a [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) describing the chosen macrostructure and enrichment.

### Audit Existing Pages

The **audit** verb scores an existing HTML file against the anti-pattern checklist defined in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md) without modifying the source. Hallmark parses the target page, extracts its tokens and layout, then runs 57 validation gates.

```bash
hallmark audit ./src/pages/home.html

```

Output appears as a ranked punch-list of violations, such as:

```

Hallmark · audit report
✗ 12 – Invented metric “10× faster”
✗ 23 – Italic header detected
✓ All other 56 gates passed

```

### Redesign with Content Preservation

The **redesign** verb re-styles an existing page while locking its content and information architecture. According to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 32-35, this flow respects a "no deletion" safety rail, asking for confirmation before structural changes.

```bash
hallmark redesign ./src/pages/home.html --mood modern-minimal

```

The engine replaces only the visual layer—tokens, themes, and macrostructure—and outputs a new version of the file.

### Study Design DNA from URLs

The **study** verb extracts the design "DNA" from a live URL or screenshot. If the target is a URL, Hallmark fetches the page via WebFetch to read exact font and color values. The result is a portable **DNA report** (macrostructure, archetype, palette, typography) that can be locked into a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file for reuse.

```bash
hallmark study https://www.usehallmark.com/examples/hum-07/

```

To persist the extracted DNA for future builds:

```bash
hallmark study https://example.com > design.md

```

## How the API Processes Your Requests

When you invoke a verb, the host runtime parses your command and forwards control to the Hallmark engine implemented in [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). The processing pipeline follows these stages:

1. **Pre-flight Scan** – Reads existing project configurations to preserve your current design system.
2. **Genre & Theme Selection** – Maps your brief to one of four genres (editorial, modern-minimal, atmospheric, playful) and selects a catalog theme (e.g., `Hum`, `Midnight`, `Cobalt`) from the `ARCHETYPES` object.
3. **Macrostructure Assembly** – Clones HTML templates for the selected page shape and injects copy fixtures from the `COPY` object.
4. **Slop-Test Validation** – Runs the 57-gate validation against [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md) to ensure no anti-patterns exist before final output.

All flows ultimately produce HTML and CSS that reference the global token system defined in [[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).

## Practical Code Examples

**Study and lock a competitor's design system:**

```bash

# Extract DNA and save to file

hallmark study https://example.com > design.md

# Use the locked DNA in a new build

hallmark --design-spec ./design.md

```

**Batch audit multiple pages:**

```bash
for file in ./src/pages/*.html; do
  hallmark audit "$file"
done

```

**Generate with specific mood override:**

```bash
echo "Marketing site for coffee subscription" | hallmark --theme Midnight

```

## Key Files in the Repository

Understanding the Hallmark API requires familiarity with these source files:

- **[[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – The canonical skill manifest declaring verbs, safety rails, and flow specifications.
- **[[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** – Core engine logic for theme selection, archetype swapping, and copy interpolation.
- **[[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** – Global CSS token definitions that constrain all generated output.
- **[`references/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references)** – Design system library containing macrostructures, component recipes, and the anti-pattern checklist.
- **[[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)** – Worked examples for extending the skill or debugging complex flows.

## Summary

- Install the Hallmark CLI once via `npx skills add nutlope/hallmark` to enable the four core verbs.
- Use the **default** verb to generate new pages from text briefs, the **audit** verb to validate existing HTML against 57 anti-pattern gates, the **redesign** verb to swap visual layers while preserving content, and the **study** verb to extract portable design DNA from live URLs.
- All commands reference the strict token system in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and the archetype definitions in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) to ensure consistent, anti-slop output.
- The API surface is governed by [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which defines safety rails such as the "no deletion" rule for redesign operations.

## Frequently Asked Questions

### What is the Hallmark API used for?

The Hallmark API is a CLI tool for generating, auditing, and redesigning UI pages according to a strict anti-slop design system. It enables developers and AI coding assistants to produce HTML and CSS that pass a comprehensive 57-gate validation checklist, ensuring consistent typography, spacing, and component architecture across projects.

### How do I install the Hallmark CLI tool?

You install Hallmark using the `npx skills add nutlope/hallmark` command, which registers the `hallmark` binary with your local AI assistant environment (such as Claude Code, Cursor, or Codex). This command pulls the repository, copies the skill definition from [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), and makes the four core verbs available on your system `$PATH`.

### What is the difference between the audit and redesign commands?

The **audit** command analyzes an existing HTML file and outputs a violation report without modifying the source, checking against anti-patterns like invented metrics or italic headers. The **redesign** command actually writes a new version of the file, replacing the visual layer (themes, tokens, and macrostructure) while preserving the original content and information architecture, per the safety rails in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

### Can Hallmark analyze websites without changing them?

Yes. The **study** verb fetches a live URL via WebFetch or accepts a local image, then extracts the design DNA—including macrostructure, archetype, color palette, and typography—without altering the remote source. This generates a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file that you can use as a specification for subsequent `hallmark` builds.