Hallmark Page Scope vs Component Scope: When to Use Each Design Flow

Use page scope for full-page designs with multiple sections, navigation, and footers; use component scope for isolated UI elements like buttons, cards, or modals, which triggers a streamlined workflow that skips macrostructure selection and diversification logging.

The open-source Hallmark design system by Nutlope automatically determines whether a request requires a comprehensive page layout or a targeted component refinement. Understanding when Hallmark activates page scope versus component scope ensures you receive the correct artifacts—whether that's a complete landing page with diversification tracking or a single element with an 8-state preview wrapper.

How Hallmark Detects Scope Automatically

Hallmark decides early in the workflow which path to take based on explicit signals in the design brief. According to the source code in skills/hallmark/SKILL.md (lines 64-70), the system scans for indicators that distinguish a full-page request from a component-level task.

Component Scope Signals

Component scope triggers when the brief meets specific criteria:

• Names a single UI element (button, card, modal, input, etc.)
• Contains 30 words or fewer
• Points to a single component file
• Explicitly limits scope with phrases like "just the X"

When these signals fire, Hallmark immediately routes to the component flow. If the brief is ambiguous, Hallmark asks a single clarifying question such as "One pricing card, or the whole pricing page?" (lines 141-142).

Page Scope Default

When no component signals are detected—such as when the brief describes a full page, multi-section layout, or requests a new app or landing page—Hallmark defaults to page scope. This activates the complete design apparatus without skipping steps.

What Runs in Page Scope Versus Component Scope

The two workflows share common preliminary steps but diverge significantly in execution depth.

The Common Preliminaries

Both scopes begin with:

• Pre-flight scan
• Genre detection
• Theme routing
• Font discipline

Page Scope Execution

Page scope retains every step of the full design flow:

• Macrostructure selection
• Navigation and footer archetype identification
• Hero enrichment patterns (HP1-HP4)
• Multi-section preview generation
• Diversification log entry in .hallmark/log.json

Component Scope Shortcuts

Component scope explicitly skips major page-level steps (lines 73-90):

• Macrostructure pick – Irrelevant since a single element has no macrostructure (lines 84-85)
• Nav and footer archetype selection – No page chrome exists (lines 85-86)
• Hero polish patterns – HP1-HP4 are skipped (lines 86-87)
• Enrichment step – No hero illustrations or demo videos (lines 87-88)
• Multi-section preview block – Replaced by an 8-state demo wrapper (lines 88-89)
• Project-memory append – Components do not participate in diversification; no .hallmark/log.json entry is created (lines 89-90)

Output Artifacts and Structure

The scope decision determines what files Hallmark generates and how it tracks design history.

Page Scope Deliverables

Page scope produces a complete page structure including:

• Full macrostructure with hero, sections, navigation, and footer
• Diversification tracking entry in .hallmark/log.json to ensure future builds differ from recent macrostructures, themes, and enrichment archetypes

Component Scope Deliverables

Component scope generates exactly two files (lines 92-104):

1. The component itself (e.g., Button.tsx)
2. An 8-state preview wrapper (Button.preview.html) demonstrating every required state (default, hover, focus, active, disabled, loading, error, success)

The CSS stamp uses the component: prefix to prevent later page-level diversification conflicts (lines 130-133).

Practical Examples

Component Scope Trigger

A brief like:

Design a primary button for our SaaS dashboard.

Hallmark detects component signals (named element, short length) and produces token-based styling with the 8-state wrapper:

/* Hallmark · component: button · genre: modern-minimal · theme: Coral
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */
.button { … }

<!-- Button.preview.html -->
<div class="button is-hover">Click me</div>
<div class="button is-focus">Click me</div>
<!-- ... all 8 states -->

Page Scope Trigger

A brief like:

Create a landing page for our new AI-powered analytics platform.
Include a hero, feature grid, pricing table, and footer.

No component signals fire, so Hallmark executes the full flow, selecting macrostructure, nav/footer archetypes, hero enrichment, and logging the build to prevent repetitive diversification.

Summary

• Use page scope when designing full-page layouts with multiple sections, navigation, footers, or hero elements that require macrostructure selection and diversification tracking.
• Use component scope for isolated UI elements (buttons, inputs, cards, modals) where the brief names a single element or stays under 30 words.
• Page scope generates complete layouts with .hallmark/log.json entries; component scope produces isolated files with 8-state preview wrappers and no diversification logging.
• Hallmark detects scope automatically via signals in skills/hallmark/SKILL.md but will ask clarifying questions when briefs are ambiguous.

Frequently Asked Questions

How does Hallmark decide between page and component scope?

Hallmark analyzes the brief for specific signals defined in skills/hallmark/SKILL.md (lines 64-70). If the text names a single UI element, contains 30 or fewer words, points to one component file, or explicitly limits the request ("just the button"), it triggers component scope. Otherwise, it defaults to page scope.

Can I force Hallmark to use component scope for a complex request?

If the brief is ambiguous, Hallmark asks a single clarifying question such as "One pricing card, or the whole pricing page?" (lines 141-142). You should explicitly state "just the [component]" or keep the brief under 30 words targeting a single element to ensure component scope activation.

Why doesn't component scope create a diversification log entry?

Component builds intentionally skip the .hallmark/log.json append (lines 89-90) because isolated UI elements do not participate in the diversification system. This prevents individual buttons or cards from affecting the macrostructure diversity tracking used for full-page designs.

What is the 8-state preview wrapper in component scope?

Instead of a multi-section page preview, component scope generates an 8-state preview wrapper (e.g., Button.preview.html) that demonstrates every required state of the component: default, hover, focus, active, disabled, loading, error, and success (lines 92-104). This replaces the full-page preview block used in page scope.

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