Hallmark Documentation: A Complete Guide to the Design System Reference

Hallmark's documentation lives entirely within the Nutlope/hallmark repository, with the README serving as the central entry point and the skills/hallmark/references/ directory containing exhaustive specifications for macro-structures, themes, genres, and quality gates.

Hallmark is an open-source AI design skill that generates high-quality landing pages through structured design rules. Unlike traditional frameworks with external documentation sites, Hallmark documentation is embedded directly in the repository, creating a self-contained reference system that governs every output. This approach ensures that the design system specifications, verb behaviors, and quality controls remain version-locked with the codebase itself.

Central Documentation Entry Points

The documentation hierarchy begins with two critical files at different levels of the repository.

README.md Overview

The top-level README.md provides the high-level map of the project. It contains the live demo link (https://www.usehallmark.com), installation instructions for npm versions greater than 9, and navigation pointers to the deeper reference material. This file serves as the primary onboarding document for developers installing the skill for the first time.

SKILL.md Manifest

Located at skills/hallmark/SKILL.md, this file functions as the skill's contract and central manifest. It defines the four core verbs that control Hallmark's behavior:

• audit – Analyzes existing codebases for design quality
• redesign – Rebuilds pages while preserving existing copy and information architecture
• study – Extracts design DNA from live URLs and converts it into portable design files
• Default (build) – Generates new pages from brief descriptions

The manifest also outlines the complete design flow that Hallmark follows for every output, ensuring consistent execution across all verbs.

Design System Specifications in references/

The skills/hallmark/references/ directory houses the granular design rules that Hallmark applies during generation. These files constitute the actual design system engine.

Macro-Structure Definitions

The macrostructures.md file serves as an index of the 21 named macro-structures available in the system. Individual specifications for each layout pattern reside in references/macrostructures/<num-name>.md, providing detailed structural logic for compositions ranging from hero sections to complex content grids.

Theme Catalog

Hallmark includes 20 distinct visual themes, catalogued in references/themes.md. Each theme—such as Brutal, Terminal, or Bloom—has its own dedicated file at references/themes/<theme>.md containing specific color logic, typography rules, and component styling parameters.

Genre Specifications

The tonal palette of generated pages is controlled by four genre files located in references/genres/:

• editorial.md – Formal, content-heavy presentation
• modern-minimal.md – Clean, whitespace-focused aesthetics
• atmospheric.md – Mood-driven, immersive layouts
• playful.md – Casual, dynamic visual treatments

Each genre file defines the voice, pacing, and stylistic boundaries that inform the AI's layout decisions.

Quality Assurance Documentation

Hallmark implements rigorous quality controls through slop-test.md, located at skills/hallmark/references/slop-test.md. This file contains the exhaustive list of 58 slop-test gates that Hallmark runs after generating a page. These automated checks catch common AI-generated web design flaws, ensuring output quality before the final HTML and CSS are written.

Practical Examples and Recipes

Beyond technical specifications, the Hallmark documentation includes concrete implementation examples.

recipes.md

The docs/recipes.md file contains eight worked briefs that demonstrate how Hallmark interprets natural language prompts, selects appropriate macro-structures and themes, applies genre treatments, and produces final outputs. These examples show the complete reasoning chain from input to generated HTML.

Test Artefacts

The _tests/ folder contains self-contained HTML and CSS artefacts for each brief, providing inspectable reference implementations that correspond to the recipes. Developers can study these files to understand how the abstract rules in references/ manifest in actual browser-rendered code.

CLI Usage Examples

All documentation references the same internal flow defined in SKILL.md. The following commands demonstrate how to interact with the documented verbs:

Install the skill (requires npm > 9):

npx skills add nutlope/hallmark

Run Hallmark with the default verb to build a new page:

hallmark "Build a landing page for CoffeeBox – a small-batch coffee subscription."

Audit an existing site:

hallmark audit ./src

Redesign a page while preserving copy and IA:

hallmark redesign ./src/pages/about.tsx

Study a live URL and extract its design DNA:

hallmark study https://example.com

Lock the extracted DNA into a portable design file:

hallmark study https://example.com --output design.md

Every command generates output that includes a stamp comment recording the chosen macro-structure, theme, genre, and enrichment. For example:

/* Hallmark · macrostructure: Marquee Hero · theme: Bloom … */

Summary

• Hallmark documentation is repository-native, with no external documentation site required.
• The README.md provides installation and overview, while SKILL.md defines the four core verbs and design flow.
• Design specifications live in skills/hallmark/references/, including 21 macro-structures, 20 themes, and 4 genres.
• slop-test.md enforces quality through 58 automated validation gates.
• recipes.md and the _tests/ folder provide eight worked examples with inspectable HTML/CSS outputs.
• All outputs carry a stamp comment tracking the applied design system choices.

Frequently Asked Questions

Where is the Hallmark documentation hosted?

Hallmark documentation is hosted entirely within the Nutlope/hallmark GitHub repository. There is no separate documentation website; instead, the README, SKILL.md, and the skills/hallmark/references/ directory contain all specifications, making the documentation version-locked with the code.

What are the four verbs defined in Hallmark's SKILL.md?

According to the source code in skills/hallmark/SKILL.md, the four verbs are: audit for analyzing existing codebases, redesign for rebuilding pages while preserving content, study for extracting design DNA from URLs, and the default build verb for generating new pages from brief descriptions.

How does Hallmark ensure design quality in generated outputs?

Hallmark runs 58 automated checks defined in skills/hallmark/references/slop-test.md after generating each page. These slop-test gates catch common AI design flaws before finalizing the HTML and CSS, ensuring the output meets the standards defined in the macro-structure and theme specifications.

Can I see examples of Hallmark's generated code?

Yes. The repository includes docs/recipes.md with eight worked briefs showing prompt-to-output workflows, and the _tests/ folder contains self-contained HTML and CSS artefacts for each brief. Additionally, the live demo at https://www.usehallmark.com showcases the complete set of generated examples.

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