# Where to Find Nutlope/hallmark Documentation: Complete Guide to the Design System > Find complete Nutlope/hallmark documentation easily. Access installation, core verbs, safety rails, and design system specifications within the repository's markdown files. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: getting-started - Published: 2026-08-10 --- **The Nutlope/hallmark documentation is distributed across the repository in structured markdown files, with [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) covering installation, [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/themes/lumen.md)), specifying colour bands, display styles, and accent hues. - [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash npx skills add nutlope/hallmark ``` Run the default design flow to generate a new UI: ```bash hallmark ``` This command executes the sequence defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash hallmark audit path/to/project ``` Redesign a project while preserving existing routes and component ownership: ```bash hallmark redesign path/to/project --mood modern-minimal ``` Extract design DNA from a live URL: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and a 58-gate [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) checklist. - Practical implementation examples are available in [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) and [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) for layout patterns, individual markdown files for each theme (e.g., [`themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/themes/lumen.md)), and [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) for UI archetypes. Anti-patterns and quality gates are defined in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/recipes.md)), study examples ([`study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/study-examples.md)), and presentation slides ([`talk-slides.md`](https://github.com/Nutlope/hallmark/blob/main/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.