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

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) 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:

npx skills add nutlope/hallmark

Once installation completes, the hallmark command is available on your $PATH. The skill manifest at 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, 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), and interpolates your brief with component archetypes (hero, navigation, footer).

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

The command outputs a self-contained folder containing index.html, tokens.css, and a 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 without modifying the source. Hallmark parses the target page, extracts its tokens and layout, then runs 57 validation gates.

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 lines 32-35, this flow respects a "no deletion" safety rail, asking for confirmation before structural changes.

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 file for reuse.

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

To persist the extracted DNA for future builds:

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). 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 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).

Practical Code Examples

Study and lock a competitor's design system:

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

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

Generate with specific mood override:

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) – 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) – 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) – Global CSS token definitions that constrain all generated output.
• 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) – 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 and the archetype definitions in site/js/main.js to ensure consistent, anti-slop output.
• The API surface is governed by 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, 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.

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 file that you can use as a specification for subsequent hallmark builds.

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