How Hallmark Differentiates Component-Scope vs Page-Scope Design Flows
Hallmark routes each design request through either a lightweight component-scope pipeline or a full page-scope pipeline by detecting component-scope signals in the brief and branching accordingly.
The open-source design automation tool Nutlope/hallmark implements this dual-flow architecture in its core skill specification. Understanding how Hallmark distinguishes between these two scopes helps developers predict which design steps will execute and what artifacts they'll receive.
The Design-Context Gate: Detecting Component-Scope
Hallmark's routing decision begins at the Design-context gate defined in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 60-70). The system evaluates four signals—any two of which trigger component-scope:
| Signal | Trigger Example |
|---|---|
| Single UI element named | "a button", "an avatar", "a dropdown" |
| Brief ≤ 30 words focused on one element | "Create a rounded chip" |
| Target file is a single component | ./components/Button.vue, Button.tsx |
| Explicit scope cue from user | "just the X", "only the Y" |
If fewer than two signals fire, Hallmark defaults to page-scope—the full design flow for landing pages and complete UIs.
This detection mechanism ensures that brief, element-focused requests skip the architectural overhead required for multi-section layouts.
What Component-Scope Retains from the Page Pipeline
The component-scope flow preserves only generic pre-flight steps that remain useful when building isolated elements (lines 73-81):
- Step 0 – Pre-flight scan: Reads existing tokens, fonts, and framework detection
- Step 1 – Genre detection: Inherits the project's established genre
- Step 2.6 – Theme route: Uses project tokens or catalog/custom themes
- 2 + 1 Font discipline: Same constraint system as page-scope builds
- State discipline (stricter): Must emit all 8 UI states (default, hover, focus, active, disabled, loading, error, success)
- Slop test (subset): Visual and micro-interaction checks only, without diversification gates
These retained steps ensure component-scope outputs remain consistent with the parent project's design system while avoiding page-specific complexity.
Steps Deliberately Skipped in Component-Scope
Component-scope builds explicitly omit every step assuming full-page context (lines 84-90):
| Skipped Step | Rationale |
|---|---|
| Macrostructure pick (Step 2) | Components have no page-level layout structure |
| Nav & footer archetypes (N1a-N13, Ft1-Ft8) | Single elements don't need site navigation or footers |
| Hero enrichment patterns (HP1-HP4) | Hero sections apply to pages only |
| Step 4 – Enrichment | No hero illustration, demo video, or background assets |
| Step 5 – Multi-section preview | Replaced by 8-state demo wrapper |
| Project-memory append | No entry in .hallmark/log.json; diversification rules don't apply |
This selective pruning reduces execution time and eliminates irrelevant decisions for component-level work.
Artifacts Emitted by Component-Scope
Hallmark produces two artifacts for component-scope requests (lines 93-100):
- The component file — follows host project conventions (React, Vue, Svelte, Tailwind) and references tokens via
var(--token) - An 8-state preview wrapper — HTML/TSX page rendering all required UI states for developer sanity-checking; not production code
The component file carries a mandatory stamp comment (lines 27-34) that marks scope and requirements:
/* Hallmark · component: button · genre: modern-minimal · theme: Coral
* states: default · hover · focus · active · disabled · loading · error · success
* contrast: pass (46–50)
*/
.btn {
background: var(--color-accent);
color: var(--color-on-accent);
}
The component: prefix in this stamp enables future Hallmark runs to recognize the file's scope and bypass page-level diversification rules.
8-State Demo Wrapper Example
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="button.css">
<style>
.demo { margin: 1rem 0; }
.demo button { display: block; width: 100%; }
</style>
</head>
<body>
<div class="demo"><button class="btn">default</button></div>
<div class="demo"><button class="btn is-hover">hover</button></div>
<div class="demo"><button class="btn is-focus">focus</button></div>
<div class="demo"><button class="btn is-active">active</button></div>
<div class="demo"><button class="btn" disabled>disabled</button></div>
<div class="demo"><button class="btn loading">loading</button></div>
<div class="demo"><button class="btn error">error</button></div>
<div class="demo"><button class="btn success">success</button></div>
</body>
</html>
Page-Scope Flow for Contrast
When component-scope signals are absent, Hallmark executes the full page-scope design flow starting at line 145:
- Macrostructure selection (Step 2)
- Nav/footer archetype picks (Step 2.5)
- Hero enrichment (Step 4)
- Multi-section preview (Step 5)
- Diversification logging (
.hallmark/log.json)
This page-scope pipeline builds complete landing pages or app UIs with architectural diversity tracking, while component-scope remains focused on single-element fidelity across interaction states.
Key Implementation Files
| File | Purpose |
|---|---|
[skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
Central specification for both flows: signal detection, retained/skipped steps, stamp format |
[skills/hallmark/references/component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) |
Component archetypes index; documents component: prefix semantics |
[skills/hallmark/references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) |
Opt-in design.md flow; notes CTA and page-level actions skipped for component-scope |
[site/css/tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) |
Token definitions; component-scope files must use var(--token) |
.hallmark/log.json (runtime) |
Diversification history for page-scope; not updated for component-scope builds |
Summary
- Component-scope detection requires two of four signals from the Design-context gate in
SKILL.md - Retained steps focus on tokens, genre, theme, and strict 8-state discipline
- Skipped steps include all page architecture, navigation, hero enrichment, and diversification logging
- Output artifacts are the component file plus an 8-state preview wrapper
- Stamp comments with
component:prefix enable scope-aware future processing - Page-scope remains the default full pipeline for multi-section UI design
Frequently Asked Questions
How does Hallmark decide between component-scope and page-scope?
Hallmark evaluates four signals in the Design-context gate: single UI element named, brief length ≤30 words focused on one element, target file being a single component, or explicit user cue like "just the X". If two or more signals match, component-scope executes; otherwise page-scope runs.
What are the 8 UI states required for component-scope builds?
According to SKILL.md lines 79-80, component-scope files must implement: default, hover, focus, active, disabled, loading, error, and success. These are enforced through stricter state discipline than page-scope builds require.
Why doesn't component-scope update .hallmark/log.json?
Component-scope builds deliberately skip project-memory append operations (line 84-90). This prevents diversification rules from applying to isolated components, keeping their lifecycle lightweight and avoiding inappropriate macrostructure rotation or nav/footer diversification.
Can a component-scope file later become part of a page-scope build?
Yes. The stamp comment's component: prefix marks the file's origin scope, but the component itself can be imported into any page-scope design. Future Hallmark runs recognize the prefix and avoid applying page-level constraints to that specific file while still including it in broader compositions.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →