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

> Discover the key differences between component-scope and page-scope flows in Hallmark. Learn how to effectively manage UI elements and full-page designs for optimal architecture.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-08-13

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L84-L86) |
| **Page-scope** | **Selected from index** — Hallmark reads [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) and chooses one (e.g., Marquee Hero, Stat-Led) | [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L64-L66) |

### 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`](https://github.com/Nutlope/hallmark/blob/main/references/component-cookbook.md), are **explicitly page-scope only** — component-scope skips them entirely ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L84-L86).

### 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L101-L115):

```html
<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:

```css
/* 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:

```markdown
**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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L79-L80), documented in [`references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) entry | **None** — no record added ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L89-L90) | **Added** — macrostructure, theme, enrichment logged ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L96-L100) |
| 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — Scope decision logic and step definitions (lines 60-90)
- **[`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md)** — 21 named macrostructures for page-scope
- **[`references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/references/component-cookbook.md)** — Nav/footer archetypes (page-scope only)
- **[`references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/references/interaction-and-states.md)** — 8-state requirements for components
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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.