Hallmark Component-Scope vs Page-Scope Flow: When to Use Each Approach

Component-scope flow generates single UI elements with strict 8-state coverage and skips macrostructure decisions, while page-scope flow builds complete websites with navigation, heroes, and diversification rules.

The Hallmark CLI tool uses two distinct design flows depending on whether you are building a reusable UI component or an entire page. Understanding the component-scope vs page-scope flow distinction ensures you trigger the correct generation mode and receive the appropriate artifacts for your use case. According to the source code in skills/hallmark/SKILL.md, the skill automatically detects scope based on input signals before executing a trimmed-down component workflow or the full page design flow.

How Hallmark Detects Scope Automatically

Hallmark decides early whether your brief describes a single UI element or a full page by scanning for specific component-scope signals.

The skill checks for indicators such as:

• A brief naming a single element (button, card, modal, etc.)
• Descriptions under 30 words
• Target paths pointing to single component files
• Explicit phrasing like "just the X"

When two or more signals fire, Hallmark switches to component-scope mode. Otherwise, it defaults to the page-scope (Design) flow. This detection logic is defined in skills/hallmark/SKILL.md between lines 64 and 70.

What the Component Flow Keeps From Page-Scope

The component-scope flow is not a complete rewrite—it inherits several critical steps from the full page design flow to maintain consistency with your existing design system.

According to the source in skills/hallmark/SKILL.md, the component flow retains:

• Pre-flight scan (Step 0): Reads existing tokens, fonts, and framework detection exactly as page-scope does
• Genre detection (Step 1): Inherits the project's genre (editorial, modern-minimal, etc.)
• Theme route (Step 2.6): Uses existing tokens.css or design.md files, or falls back to the catalog
• Font and token discipline: All color and font references must remain token-based, identical to page-scope requirements

Critical Steps the Component Flow Skips

The component-scope flow deliberately removes page-level scaffolding that would bloat a reusable component. As documented in skills/hallmark/SKILL.md (lines 84-90), the following steps are skipped:

• Macrostructure selection – Components have no macrostructure
• Navigation and footer archetypes – No nav or footer generation
• Hero polish patterns – Hero sections are page-only constructs
• Enrichment step – No hero illustrations, demo videos, or abstract backgrounds
• Multi-section preview – Replaced by an 8-state demo wrapper
• Project-memory append – Component runs do not write to .hallmark/log.json, bypassing diversification rules that rotate macrostructures across pages

Added Requirements in Component-Scope Flow

While removing page scaffolding, the component flow adds strict requirements for state completeness and output structure.

Strict 8-State Discipline

Every interactive component must ship CSS for all eight states: default, hover, focus-visible, active, disabled, loading, error, and success. The checklist is enforced via references/interaction-and-states.md in the Hallmark skills directory.

Two-File Output Pattern

Component-scope generation produces:

1. The component file itself (e.g., Button.tsx)
2. An 8-state demo wrapper (ComponentName.preview.html or .tsx) that renders the component in every state for immediate visual verification

Component Stamp Header

Generated component files begin with a comment tagging them as component-scoped. This prevents later page-level diversification rules from incorrectly applying macrostructure rotation to the file.

Practical Examples: Invoking Each Flow

Triggering Component-Scope Automatically

Targeting a single component file signals Hallmark to use the component flow:

hallmark redesign ./components/Button.tsx

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

Running Full Page-Scope Flow

Targeting a page directory or HTML file triggers the complete design flow:

hallmark redesign ./pages/landing.html

Result: Hallmark produces a full landing page HTML with macrostructure, hero, navigation, footer, and adds a diversification entry to .hallmark/log.json.

Verifying State Coverage

Open the generated preview file to inspect all states side-by-side:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="Card.css">
  </head>
  <body>
    <!-- Renders card in default, hover, focus, active, disabled, loading, error, and success states -->
    <div class="card-preview"></div>
  </body>
</html>

Summary

• Component-scope flow targets reusable UI pieces, enforces 8-state CSS coverage, emits a component file plus preview wrapper, and skips macrostructure, navigation, and hero steps.
• Page-scope flow builds complete sites with macrostructure variety, navigation/footer scaffolding, and diversification rules stored in .hallmark/log.json.
• Scope detection relies on signals like brief length, target file type, and explicit user phrasing defined in skills/hallmark/SKILL.md.
• Component files receive a component stamp comment to prevent page-level design system conflicts.

Frequently Asked Questions

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

Hallmark analyzes your brief for component-scope signals such as single-element naming (button, card, modal), descriptions under 30 words, or explicit phrasing like "just the X". When two or more signals are detected, it chooses the component flow; otherwise it defaults to page-scope as defined in skills/hallmark/SKILL.md.

Why does the component flow skip macrostructure selection?

Components are intended as portable, reusable elements that can be dropped into any existing codebase. Macrostructure decisions (page layout grids, section ordering) apply only to full-page compositions, so the component flow skips these steps to avoid generating unnecessary scaffolding, as noted in the scope documentation.

What are the eight required component states?

According to references/interaction-and-states.md, every interactive component must handle: default, hover, focus-visible, active, disabled, loading, error, and success. The component-scope flow enforces this via a checklist and generates a preview file demonstrating all states.

Does component-scope generation affect the project memory log?

No. Component-scope runs deliberately do not append entries to .hallmark/log.json. This isolation prevents diversification rules—designed to ensure page variety across a site—from incorrectly rotating macrostructures or themes when generating individual components.

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