Where to Find Nutlope/hallmark Documentation: Complete Guide to the Design System

The Nutlope/hallmark documentation is distributed across the repository in structured markdown files, with README.md covering installation, SKILL.md defining core verbs and safety rails, and the skills/hallmark/references/ directory containing detailed design system specifications.

The Nutlope/hallmark repository ships a self-contained documentation suite that explains how the design system skill works, how to invoke it, and how its visual language is organized. Whether you are installing the tool for the first time or extending its capabilities, the documentation splits cleanly into human-readable guides and machine-readable reference files that the skill loads during execution.

Core Documentation Entry Points

README.md – Installation and Overview

Located at the repository root, README.md provides the high-level overview and installation instructions. It includes the command to add the skill to supported runtimes like Claude Code, Cursor, and Codex, plus links to the live demo at https://www.usehallmark.com.

SKILL.md – Skill Definition and Verbs

The file skills/hallmark/SKILL.md serves as the primary specification document. It contains the full description of the Hallmark skill, including the verb list (audit, redesign, study), safety rails, and the default design flow. This file specifies the five-step generation process, from pre-flight font scans to the final preview block emission.

Design System Reference Library

Themes and Macrostructures

The skills/hallmark/references/ directory houses the complete design system taxonomy used by the skill. Key reference files include:

• skills/hallmark/references/macrostructures.md – Index of the 21 macrostructures (page-shape choices) available for layout selection.
• skills/hallmark/references/themes/*.md – Individual definitions for 20 named themes (e.g., themes/lumen.md), specifying colour bands, display styles, and accent hues.
• skills/hallmark/references/component-cookbook.md – Catalog of component archetypes covering navs, footers, and hero parts.

Quality Assurance References

Documentation for maintaining output quality includes strict guardrails:

• skills/hallmark/references/anti-patterns.md – List of prohibited patterns such as invented metrics, italic headers, and other visual slop.
• skills/hallmark/references/slop-test.md – A 58-gate post-emit quality checklist that the skill uses to validate generated output.

Practical Examples and Usage Guides

Recipes and Worked Examples

The docs/recipes.md file provides eight copy-and-paste briefs demonstrating how Hallmark interprets prompts, infers the design trio (audience, use-case, tone), selects macrostructures, and generates pages. Each recipe includes the final output excerpts and links to live test pages.

Study Examples and DNA Extraction

For the hallmark study workflow, docs/study-examples.md contains sample DNA extractions from existing designs. These examples show how the skill parses HTML/CSS to extract macrostructure, theme, type-pairing, and colour anchors, then outputs a diagnosis report.

Installation and CLI Usage

Install the skill using the Node Package Executor:

npx skills add nutlope/hallmark

Run the default design flow to generate a new UI:

hallmark

This command executes the sequence defined in SKILL.md: it runs a pre-flight scan (checking fonts, palette, and framework), asks three design-context questions (audience, use-case, tone), picks a macrostructure and theme respecting diversification rules, and emits a preview block.

Audit an existing project against anti-patterns without modifying files:

hallmark audit path/to/project

Redesign a project while preserving existing routes and component ownership:

hallmark redesign path/to/project --mood modern-minimal

Extract design DNA from a live URL:

hallmark study https://example.com

The study verb fetches the page, parses the HTML/CSS, and outputs a diagnosis report referencing the macrostructure and theme definitions in skills/hallmark/references/.

Live Demo and Test Outputs

The repository maintains a publicly hosted site at https://www.usehallmark.com that showcases every generated page. Fully rendered HTML and CSS outputs for testing are stored in site/_tests/, providing concrete examples of the skill's emission format.

Summary

• The Nutlope/hallmark documentation is split between human-readable guides (README.md, docs/) and machine-readable specifications (skills/hallmark/references/).
• Core skill logic, verb definitions, and safety rails are defined in skills/hallmark/SKILL.md.
• The design system includes 21 macrostructures, 20 themes, and a component cookbook documented under skills/hallmark/references/.
• Quality assurance relies on anti-patterns.md and a 58-gate slop-test.md checklist.
• Practical implementation examples are available in docs/recipes.md and docs/study-examples.md.

Frequently Asked Questions

Where is the main skill definition located in Nutlope/hallmark?

The primary skill specification is located at skills/hallmark/SKILL.md. This file defines the available verbs (audit, redesign, study), safety rails, and the default design flow including the pre-flight scan and preview generation steps described in the Design Flow (Default) section.

What design system references are available in the Hallmark documentation?

The documentation includes 20 named themes and 21 macrostructures documented under skills/hallmark/references/. Specific files include macrostructures.md for layout patterns, individual markdown files for each theme (e.g., themes/lumen.md), and component-cookbook.md for UI archetypes. Anti-patterns and quality gates are defined in anti-patterns.md and slop-test.md.

How do I install and run the Hallmark skill?

Install the skill using npx skills add nutlope/hallmark. Once installed, invoke the default design flow by running hallmark in your terminal, or use specific verbs like hallmark audit path/to/project or hallmark study https://example.com for targeted operations.

What is the difference between the docs/ and skills/hallmark/references/ directories?

The docs/ directory contains human-readable guides such as worked recipes (recipes.md), study examples (study-examples.md), and presentation slides (talk-slides.md). The skills/hallmark/references/ directory contains machine-readable specifications that the Hallmark skill loads during execution to enforce design rules, validate against anti-patterns, and apply the 58-gate slop test.

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