Component-Scope vs Page-Scope Flows in Hallmark: Architecture Differences Explained

Hallmark's component-scope flow runs when briefs describe single UI elements, while page-scope flow handles full-page designs with macrostructure, navigation, and diversification rules.

Both flows share initial pre-flight and genre detection steps, but diverge significantly in structure, output format, and state requirements. Understanding this distinction helps you predict which pipeline Hallmark will activate for your design brief.

---

How Hallmark Decides Which Flow to Run

Hallmark selects the scope before any design work begins. The decision hinges on scope signals detected in your brief.

According to SKILL.md (lines 64-70), component-scope triggers when any of these signals fire:

• A single UI element name (e.g., "button", "card")
• Brief description of ≤30 words
• Target file identified as a component
• Explicit phrasing like "just the X" or "only the Y"

Page-scope runs only when none of these signals fire and the brief describes a full page with multiple sections.

---

Shared Pipeline: Steps 0-2.6

Both scopes execute identical early-phase logic found in SKILL.md (lines 73-78):

• Step 0 (Pre-flight scan): Validates inputs, checks project context
• Step 1 (Genre detection): Inherits the project's established genre
• Step 2.6 (Theme route): Selects from catalog or custom themes

Theme selection diverges subtly: page-scope must obey diversification rules (different macrostructure/theme from recent builds), while component-scope diversification applies only to the component token itself.

---

Critical Divergences: What Each Flow Actually Does

Macrostructure Selection

Scope	Behavior	Source
Component-scope	Skipped entirely — components have no macrostructure structure	SKILL.md
Page-scope	Selected from index — Hallmark reads references/macrostructures.md and chooses one (e.g., Marquee Hero, Stat-Led)	SKILL.md

Navigation and Footer Archetypes

Page-scope flows pick from nav archetypes N1a-N13 and footer archetypes Ft1-Ft8, recording selections in the output stamp. These archetypes, defined in references/component-cookbook.md, are explicitly page-scope only — component-scope skips them entirely (SKILL.md.

Hero Enrichment

Hero polishing patterns (HP1-HP4) — including illustration injection, demo video embedding, and other enhancements — only run in page-scope. Component-scope bypasses hero enrichment per SKILL.md (lines 86-87).

---

Output Format: 8-State Demo vs Multi-Section Preview

Component-Scope Output

Generates an 8-state demo wrapper showing every interactive state in isolation (SKILL.md:

<div class="demo-wrapper">
  <div class="state">default       <button class="btn">Click me</button></div>
  <div class="state">hover         <button class="btn is-hover">Click me</button></div>
  <div class="state">focus         <button class="btn is-focus">Click me</button></div>
  <div class="state">active        <button class="btn is-active">Click me</button></div>
  <div class="state">disabled      <button class="btn" disabled>Click me</button></div>
  <div class="state">loading       <button class="btn" data-state="loading">⌛ Working…</button></div>
  <div class="state">error         <button class="btn" data-state="error">⚠ Try again</button></div>
  <div class="state">success       <button class="btn" data-state="success">✓ Saved</button></div>
</div>

The component stamp appears at the file's top:

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

Page-Scope Output

Generates a multi-section preview showing the complete page layout:

**Hallmark · v1.1.0**

- **Macrostructure** · Stat-Led
- **Theme** · Plain (#fff paper · cool greys · ink-blue accent)
- **Enrichment** · none (typography only)
- **Sections** · Hero · Logos · Stats · Features · Testimonials · Pricing · FAQ · CTA · Footer
- **Motion** · counter · pricing-lift · pulse-once
- **Slop test** · 58 / 58 ✓
- **Diversification** · differs from Newsprint on display style + accent hue

---

State Discipline Requirements

Component-scope enforces strict 8-state compliance for every interactive element (SKILL.md, documented in references/interaction-and-states.md):

• default
• hover
• focus
• active
• disabled
• loading
• error
• success

Page-scope applies state discipline selectively — only where individual elements require it, not universally across all components.

---

Project Memory and Diversification

Aspect	Component-Scope	Page-Scope
.hallmark/log.json entry	None — no record added (SKILL.md	Added — macrostructure, theme, enrichment logged (SKILL.md
Diversification rules	Do not apply	Enforced for future builds

This ensures page-scope designs evolve across iterations while component-scope outputs remain lightweight and repeatable.

---

Key Source Files

These files govern scope behavior in the Hallmark repository:

• skills/hallmark/SKILL.md — Scope decision logic and step definitions (lines 60-90)
• references/macrostructures.md — 21 named macrostructures for page-scope
• references/component-cookbook.md — Nav/footer archetypes (page-scope only)
• references/interaction-and-states.md — 8-state requirements for components
• site/css/tokens.css — Theme tokens referenced by both scopes

---

Summary

• Component-scope activates for single-element briefs with specific trigger signals, skips macrostructure/nav/footer selection, enforces 8-state demos, and avoids log pollution
• Page-scope handles full-page requests, runs complete macrostructure selection, applies diversification rules, and maintains project memory
• Both scopes share pre-flight, genre detection, and theme routing through Step 2.6
• State discipline is universal and strict in component-scope, selective and contextual in page-scope

---

Frequently Asked Questions

How does Hallmark detect which scope to use?

Hallmark scans your brief for component-scope signals before any design processing: single element names, briefs under 30 words, component file targets, or explicit "just the X" phrasing. If any signal matches, component-scope runs. Otherwise, page-scope activates for full-page descriptions.

Can I force page-scope even for a single component request?

No direct override exists in the current architecture per SKILL.md. The scope decision is signal-driven and automatic. To trigger page-scope, structure your brief to describe multiple sections or a complete page layout without component-scope trigger phrases.

Why does component-scope skip project memory logging?

Component-scope outputs are designed as lightweight, reusable assets rather than evolutionary design iterations. Skipping .hallmark/log.json entries prevents component work from affecting diversification rules for future page-scope builds, keeping the design space open for full-page variations.

Do both scopes access the same theme tokens?

Yes — both read from site/css/tokens.css. However, component-scope must reference existing tokens rather than create new ones, ensuring component outputs remain consistent with the project's established design system.

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