tutorial

How Hallmark Manages Component-Scope vs Page-Scope Flows: A Complete Guide

August 1, 2026 Nutlope/hallmark ↗

Hallmark automatically detects whether a brief describes a single UI element or a full page, then switches to a trimmed-down Component-Scope flow with strict state-coverage rules, or runs the complete Design flow for page-level output.

The Nutlope/hallmark repository implements a dual-path architecture that fundamentally changes how the AI generates code depending on scope. Understanding this distinction is critical for developers who want predictable, high-quality output—whether they're building reusable UI components or complete landing pages.

How Hallmark Detects Component Scope vs Page Scope

Before any code generation begins, Hallmark performs scope detection based on signals in the brief and target file.

The skill looks for four component-scope signals as defined in skills/hallmark/SKILL.md (lines 64–70):

  • Single-element naming – brief mentions "button," "card," "modal," etc.
  • Brief length – description is ≤ 30 words
  • Target file – points to a single component file
  • Explicit phrasing – user says "just the X"

When two or more signals fire, Hallmark switches to Component-Scope flow. Otherwise, it defaults to the full page-scope Design flow.

What the Component-Scope Flow Keeps from the Page-Scope Design Flow

The Component-Scope flow isn't a rewrite—it's a surgical reduction. According to the source code, these steps remain identical:

Step Behavior
0. Pre-flight scan Reads existing tokens, fonts, framework from the project
1. Genre detection Inherits the project's genre (editorial, modern-minimal, etc.)
2.6. Theme route Uses existing tokens.css / design.md or falls back to catalog
Font & token discipline All color/font references must be token-based

This ensures components stay visually consistent with their parent projects even when generated in isolation.

Steps the Component-Scope Flow Removes (Skips)

The Component-Scope flow explicitly skips six page-level steps, as documented in skills/hallmark/SKILL.md (lines 84–90):

  • Macrostructure pick – components have no macrostructure
  • Nav/footer archetype picks – no navigation or footer scaffolding
  • Hero polish patterns – hero sections are page-only constructs
  • Enrichment step – no hero illustration, demo video, or abstract background
  • Multi-section preview – replaced by an 8-state demo wrapper
  • Project-memory append – no .hallmark/log.json entry, so diversification rules don't apply

These removals keep components lightweight and free of page-specific assumptions.

What the Component-Scope Flow Adds: State Discipline

Where the flow subtracts page structure, it adds rigorous state coverage. The Component-Scope flow mandates three additions:

Strict state discipline – Every interactive component must ship CSS for all eight states: default, hover, focus-visible, active, disabled, loading, error, success. The canonical checklist lives in references/interaction-and-states.md.

Two-file output – Hallmark generates:

Component stamp – A generated comment at the file's start tags it as component-scoped, preventing later page-level diversification from altering it.

Command Examples: Triggering Each Flow

Invoke component-scope automatically


# Target a single component file – Hallmark recognizes component-scope

hallmark redesign ./components/Button.tsx

Result: Hallmark emits Button.tsx and Button.preview.html with the eight states, prefixed with a component-scope comment.

Invoke page-scope (default) flow


# No component signals – Hallmark runs full design flow

hallmark redesign ./pages/landing.html

Result: Full landing-page HTML + CSS with macrostructure, hero, nav, footer, and diversification CTA.

Force component-scope on ambiguous briefs


# Explicitly treat brief as component

hallmark redesign ./src/ui/Card.vue --component

The --component flag disambiguates when signals are unclear.

Inspect the 8-state demo wrapper

<!DOCTYPE html>
<html>
  <head><link rel="stylesheet" href="Card.css"></head>
  <body>
    <!-- Auto-generated demo showing all states -->
    <div class="card-preview"></div>
  </body>
</html>

Open this preview in a browser to verify state styling without writing test pages.

Divergent Outcomes: Component vs Page Artifacts

Flow Emitted Artifacts Diversification Rule
Page-scope (Design flow) Full HTML + CSS page, macrostructure, hero, nav, footer, optional design.md lock-in Pages must differ unless design.md locks the system
Component-scope Single component file + 8-state demo wrapper No diversification; isolated; no .hallmark/log.json entry

This architectural split ensures components remain reusable while pages stay visually distinct across a site.

Key Source Files for Scope Management

File Role
skills/hallmark/SKILL.md Master skill definition; component-scope and page-scope flow descriptions
skills/hallmark/references/interaction-and-states.md Checklist of eight required component states
skills/hallmark/references/design-md.md Portable design system (page-scope only)
skills/hallmark/references/component-cookbook.md Component implementations and best practices
skills/hallmark/references/structure.md Page macrostructures (page-scope only)

Summary

  • Scope detection uses four signals; two or more trigger Component-Scope flow
  • Component-Scope keeps pre-flight, genre, theme, and token discipline from the full Design flow
  • Component-Scope removes macrostructure, nav/footer, hero, enrichment, multi-section preview, and project-memory logging
  • Component-Scope adds mandatory 8-state CSS, two-file output, and component stamps
  • Page-Scope enforces diversification across pages; Component-Scope isolates output for reusability

Frequently Asked Questions

How does Hallmark decide between component-scope and page-scope?

Hallmark evaluates four signals: single-element naming, brief length ≤ 30 words, single-component target file, and explicit "just the X" phrasing. When two or more signals match, it runs Component-Scope flow; otherwise, it defaults to the full page-scope Design flow.

Why does the component flow skip macrostructure and hero steps?

Components are reusable UI pieces, not complete pages. Including macrostructure, navigation, footers, or hero sections would impose page-level assumptions that limit where the component can be dropped. The trimmed-down flow keeps output lightweight and context-agnostic.

What are the eight required component states in Hallmark's component flow?

Every interactive component must implement: default, hover, focus-visible, active, disabled, loading, error, and success. These are enforced via the checklist in references/interaction-and-states.md and visually verified through the auto-generated preview wrapper.

Does component-scope output affect Hallmark's diversification rules?

No. Component runs do not write to .hallmark/log.json, so they bypass the diversification system entirely. Only page-scope outputs are tracked and rotated to ensure visual variety across a site's pages.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →