# Hallmark Component-Scope vs Page-Scope Flow: When to Use Each Approach
> Understand Hallmark's component-scope vs page-scope flow. Learn when to use each approach for building with this powerful UI generation tool. Optimize your development workflow today.
- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: tutorial
- Published: 2026-07-24
---
**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx))
2. An **8-state demo wrapper** ([`ComponentName.preview.html`](https://github.com/Nutlope/hallmark/blob/main/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:
```bash
hallmark redesign ./components/Button.tsx
```
Result: Hallmark emits [`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx) and [`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/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:
```bash
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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).
### Verifying State Coverage
Open the generated preview file to inspect all states side-by-side:
```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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).
- Scope detection relies on signals like brief length, target file type, and explicit user phrasing defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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.