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

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

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:

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

Genres Directory

Four genre files establish tonal palettes:

• editorial.md — structured, authoritative voice
• modern-minimal.md — restrained, essential voice
• atmospheric.md — sensory, immersive voice
• 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 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+):

npx skills add nutlope/hallmark

Build a new page with the default verb:

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

Audit an existing site for quality:

hallmark audit ./src

Redesign a page while preserving copy and information architecture:

hallmark redesign ./src/pages/about.tsx

Study a live URL and extract its design DNA:

hallmark study https://example.com

Export the extracted DNA to a portable file:

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

All commands output a stamp comment recording the chosen configuration:

/* 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. These tests catch repetitive patterns, accessibility issues, visual inconsistencies, and other common generation errors before delivering final output.

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