What Documentation Is Available for Nutlope/hallmark? Complete Guide to Skills and References

The Nutlope/hallmark repository provides comprehensive documentation spanning installation guides, skill specifications in SKILL.md, a detailed design system reference library under skills/hallmark/references/, worked recipes in docs/recipes.md, and live study examples.

The Hallmark project is a Claude Code skill that generates production-ready UI through structured design systems. Understanding what documentation is available for Nutlope/hallmark helps developers and designers leverage its full capabilities, from basic installation to advanced DNA extraction workflows. The documentation is deliberately split into human-readable markdown guides and machine-readable reference files that the skill itself loads during execution.

Getting Started and Installation

The entry point for Hallmark documentation lives in README.md, which covers supported runtimes (Claude Code, Cursor, Codex) and the installation command.

Install the skill globally using:

npx skills add nutlope/hallmark

The README also links to the live demo at usehallmark.com, where you can browse fully rendered example outputs from the site/_tests/ directory.

Core Skill Specification

The skills/hallmark/SKILL.md file serves as the authoritative source for how the skill operates. It defines the verb list (audit, redesign, study), safety rails, and the default design flow that executes when you run the hallmark command.

According to this specification, invoking the default verb triggers a five-step process:

1. Run a pre-flight scan (fonts, palette, framework)
2. Ask three design-context questions (audience, use-case, tone)
3. Pick a macrostructure and theme (respecting diversification rules)
4. Emit a preview block
5. Generate final output

The SKILL.md file also documents command-line flags and environment constraints that govern how Hallmark interacts with your codebase.

Design System Reference Library

The skills/hallmark/references/ directory contains the machine-readable knowledge base that Hallmark consults during execution. These files define the 20 named themes, 21 macrostructures, component archetypes, typography rules, and colour systems.

Themes and Macrostructures

Individual theme definitions reside in skills/hallmark/references/themes/*.md. For example, skills/hallmark/references/themes/lumen.md defines the Lumen theme's colour bands, display styles, and accent hues.

The complete index of page-shape choices is documented in skills/hallmark/references/macrostructures.md, which enumerates all 21 macrostructures available for UI generation.

Anti-Patterns and Quality Gates

skills/hallmark/references/anti-patterns.md lists prohibited patterns (such as invented metrics or italic headers) that the skill avoids during generation.

For post-generation validation, skills/hallmark/references/slop-test.md provides a 58-gate quality checklist that filters out low-quality outputs before they reach your working directory.

The skills/hallmark/references/component-cookbook.md catalogs standard component archetypes—including navigation patterns, footer layouts, and hero sections—that Hallmark assembles into complete pages.

Practical Examples and Recipes

The docs/recipes.md file contains eight copy-and-paste briefs demonstrating how Hallmark interprets prompts, selects macrostructures, and generates output. Each recipe includes:

• The input prompt
• The inferred audience/use-case/tone trio
• The selected theme and macrostructure
• Excerpts from the generated output

These worked examples illustrate the decision-making process between the initial prompt and final HTML/CSS generation.

Study Workflows and DNA Extraction

For the hallmark study verb, docs/study-examples.md provides sample DNA extractions from existing designs. This documentation shows how Hallmark parses HTML/CSS from live URLs to extract macrostructure, theme, type-pairing, and colour anchors.

To study an existing site:

hallmark study https://example.com

The command outputs a diagnosis report mapping the detected design patterns to Hallmark's internal reference system.

Advanced Usage Patterns

Auditing Existing Codebases

The audit verb documentation in SKILL.md explains how to score existing projects against the anti-pattern list without modifying files:

hallmark audit path/to/project

This returns a punch-list of issues based on the rules defined in skills/hallmark/references/anti-patterns.md.

Redesigning with Preserved Structure

To refresh visual layers while keeping routes and component ownership intact:

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

The --mood flag references specific theme definitions in the references directory, allowing targeted visual refreshes without structural changes.

Additional Resources

Beyond the core documentation, the repository includes:

• docs/talk-slides.md: Presentation-style overview of the skill's architecture and philosophy
• ROADMAP.md: Planned features, theme expansions, and future macrostructures
• site/examples/tally/app.js: Source code examples showing JavaScript implementations used in generated pages
• site/_tests/*: Fully rendered HTML and CSS outputs for every example page, serving as regression tests and visual references

Summary

The documentation for Nutlope/hallmark constitutes a complete, searchable knowledge base covering:

• Installation and setup via README.md and the npx skills add command
• Skill mechanics detailed in skills/hallmark/SKILL.md with verb definitions and safety rails
• Design system rules including 20 themes and 21 macrostructures under skills/hallmark/references/
• Quality standards enforced through anti-patterns.md and slop-test.md
• Practical recipes in docs/recipes.md showing real-world prompt-to-output workflows
• DNA extraction methodology documented in docs/study-examples.md
• Live examples hosted at usehallmark.com with source code in site/examples/*/

Frequently Asked Questions

Where is the Hallmark skill definition documented?

The complete skill definition—including verb tables, design flows, and safety rails—is documented in skills/hallmark/SKILL.md. This file specifies how the skill behaves when you invoke hallmark, hallmark audit, or hallmark study.

What design system references does Hallmark use?

Hallmark references 20 predefined themes (stored in skills/hallmark/references/themes/*.md) and 21 macrostructures (indexed in skills/hallmark/references/macrostructures.md). These files define the colour palettes, typography pairings, and page layouts the skill can generate.

How do I see examples of Hallmark-generated output?

Worked examples live in docs/recipes.md, while fully rendered HTML outputs are stored in site/_tests/*. The live demo at usehallmark.com showcases these examples in a browser, and the site/examples/tally/app.js file provides JavaScript implementations used in generated pages.

What quality checks does Hallmark perform?

The skill consults skills/hallmark/references/slop-test.md, which defines a 58-gate post-generation checklist. It also references skills/hallmark/references/anti-patterns.md to avoid prohibited design patterns like invented metrics or italic headers.

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