# Where to Find Hallmark Documentation: Complete Guide to the Nutlope Repository

> Find comprehensive Hallmark documentation in the Nutlope/hallmark GitHub repository. Explore the README and detailed specifications for all your Hallmark needs.

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

---

**Hallmark's documentation is stored entirely within the Nutlope/hallmark GitHub repository, with the README as the central entry point and detailed specifications organized under `skills/hallmark/references/`.**

Hallmark is an AI-powered design skill for generating high-quality web pages. Unlike tools with external documentation sites, Hallmark follows a repository-native approach where every design rule, theme definition, and quality gate is version-controlled alongside the code itself.

## Primary Documentation Entry Point

Start with the top-level **README.md**. This file provides:

- Project overview and live demo link (`https://www.usehallmark.com`)
- Installation instructions for npm 9+
- Links to all deeper reference materials
- Quick-start examples for each verb

The README also points to the `_tests/` folder containing self-contained HTML and CSS artifacts for each design brief.

## Core Skill Manifest: SKILL.md

The **SKILL.md** file at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) defines Hallmark's operational contract. It specifies:

- **Four verbs**: `audit`, `redesign`, `study`, and the default build flow
- The complete design flow from prompt to generated output
- How Hallmark selects macro-structures, themes, and enrichments

Every command you run follows the internal flow documented here.

## Design System References

All detailed specifications live in `skills/hallmark/references/`. These files control every aspect of Hallmark's output.

### Macro-Structures Directory

The **macrostructures.md** index lists 21 named macro-structures (layout templates). Individual specifications are stored at:

```bash
skills/hallmark/references/macrostructures/<number-name>.md

```

### Themes Directory

Hallmark includes 20 named themes such as **Brutal**, **Terminal**, and **Bloom**. The themes.md index points to individual definitions at:

```bash
skills/hallmark/references/themes/<theme-name>.md

```

### Genres Directory

Four genre files establish tonal palettes:

- [`editorial.md`](https://github.com/Nutlope/hallmark/blob/main/editorial.md) — structured, authoritative voice
- [`modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/modern-minimal.md) — restrained, essential voice
- [`atmospheric.md`](https://github.com/Nutlope/hallmark/blob/main/atmospheric.md) — sensory, immersive voice
- [`playful.md`](https://github.com/Nutlope/hallmark/blob/main/playful.md) — energetic, inventive voice

### Quality Assurance: slop-test.md

The **slop-test.md** file contains 58 quality gates that Hallmark runs after generating any page. These tests catch common "slop" patterns and enforce design discipline before output is delivered.

## Practical Examples and Recipes

The **recipes.md** file at [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) contains eight worked briefs. Each recipe shows:

- How Hallmark interprets a prompt
- Selected macro-structure, theme, and enrichment
- Final output structure

Browse the `_tests/` folder for the actual generated HTML and CSS artifacts.

## Common Hallmark Commands

Install the skill (requires npm 9+):

```bash
npx skills add nutlope/hallmark

```

Build a new page with the default verb:

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

```

Audit an existing site for quality:

```bash
hallmark audit ./src

```

Redesign a page while preserving copy and information architecture:

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

```

Study a live URL and extract its design DNA:

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

```

Export the extracted DNA to a portable file:

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

```

All commands output a stamp comment recording the chosen configuration:

```css
/* Hallmark · macrostructure: Marquee Hero · theme: Bloom · genre: editorial */

```

## Summary

- **README.md** — Entry point with installation and overview
- **SKILL.md** — Skill manifest defining verbs and design flow
- **references/macrostructures/** — 21 layout templates
- **references/themes/** — 20 visual themes
- **references/genres/** — 4 tonal palettes
- **references/slop-test.md** — 58 quality gates
- **docs/recipes.md** — 8 worked examples with outputs
- **_tests/** — Self-contained HTML/CSS artifacts

## Frequently Asked Questions

### Do I need to visit an external documentation site to use Hallmark?

No. Hallmark documentation lives entirely in the Nutlope/hallmark repository. Clone or browse the repository directly—every specification is version-controlled alongside the code, with the README serving as your starting point.

### What is the difference between macro-structures and themes in Hallmark?

**Macro-structures** define layout organization (21 templates like "Marquee Hero" or "Split Narrative"). **Themes** define visual aesthetics (20 options like "Brutal" or "Bloom"). Hallmark selects both based on your prompt, then combines them with a genre for tone.

### How does Hallmark ensure output quality without human review?

Hallmark runs 58 automated **slop-test gates** documented in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md). These tests catch repetitive patterns, accessibility issues, visual inconsistencies, and other common generation errors before delivering final output.