# Hallmark Documentation: A Complete Guide to the Design System Reference

> Explore Hallmark documentation within the Nutlope/hallmark repository. Discover comprehensive guides on design system references, macro-structures, themes, genres, and quality gates.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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):

```bash
npx skills add nutlope/hallmark

```

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

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

```

Audit an existing site:

```bash
hallmark audit ./src

```

Redesign a page while preserving copy and IA:

```bash
hallmark redesign ./src/pages/about.tsx

```

Study a live URL and extract its design DNA:

```bash
hallmark study https://example.com

```

Lock the extracted DNA into a portable design file:

```bash
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:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.