# Hallmark Component-Scope vs. Full-Page Design Handling: Complete Guide > Understand Hallmark component-scope vs. full-page design handling. Discover how Hallmark automatically routes UI elements or complete layouts for efficient development. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: deep-dive - Published: 2026-08-05 --- **Hallmark routes every design request into one of two execution paths—component-scope for single UI elements or full-page for complete layouts—based on automated scope detection in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).** The **Hallmark** AI design engine (GitHub: `Nutlope/hallmark`) employs a dual-path architecture that fundamentally changes how it generates code depending on whether you're building a single button or an entire landing page. Understanding this distinction is critical for predictable, high-quality outputs. --- ## How Hallmark Detects Component-Scope vs. Full-Page Scope detection happens in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (lines 60–84) through a lightweight signal-matching system. The engine looks for four specific indicators: - A **single UI element name** (button, card, modal, etc.) - A **brief under 30 words** - A **target file path** pointing to a component file - Explicit phrasing like "just the X" If **two or more signals fire**, Hallmark switches to **component-scope mode** and skips all page-level concerns. Otherwise, it executes the complete **full-page design flow**. --- ## Component-Scope Flow: Focused, State-Rich Component Generation In component-scope mode, Hallmark deliberately omits macrostructure, navigation, and footer handling. The flow runs five concentrated steps: 1. **Pre-flight scan** — reads [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) 2. **Genre detection** — inherits the parent page's genre (modern-minimal, atmospheric, etc.) 3. **Theme route** — catalog or custom, but only at token-level granularity 4. **Eight-state styling** — mandatory CSS for all interactive states 5. **Dual artifact output** — component file plus preview wrapper The eight-state discipline is non-negotiable. Every component must define styles for: **default**, **hover**, **focus-visible**, **active**, **disabled**, **loading**, **error**, and **success**. ### Component-scope stamp format ```css /* Hallmark · component: button · genre: modern-minimal · theme: Coral * states: default · hover · focus · active · disabled · loading · error · success * contrast: pass (46–50) */ ``` This stamp appears at the top of generated files, sourced from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 126–136. ### Preview wrapper generation Hallmark generates a `.preview.html` file that forces each state via helper classes: ```html

Button – 8 states

``` The `.is-*` classes mirror pseudo-states for manual testing, as documented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 95–116. ### Example: Running component-scope ```bash npx hallmark redesign ./src/components/Button.tsx ``` --- ## Full-Page Design Flow: Complete Site Architecture Full-page mode activates for landing pages, dashboards, documentation sites, or any multi-section brief. This path runs eight comprehensive steps: 1. **Pre-flight scan** — same token/framework detection as component-scope 2. **Genre detection** — establishes aesthetic direction 3. **Macrostructure selection** — picks from 21 named macrostructures in [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) 4. **Theme route** — catalog (20 named themes with rotation) or custom bespoke palette 5. **Component archetype selection** — heroes, sections, features, CTAs, nav, footer via [`references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/references/component-cookbook.md) 6. **Optional hero enrichment** — triggered only by image signals in the brief 7. **Slop-test validation** — 58 anti-pattern gates 8. **Diversification enforcement** — guarantees variation from previous runs ### Macrostructure selection The engine loads [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) and selects exactly one structure. Diversification rules force a **different macrostructure** than the previous run, logged in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). ### Component Cookbook routing The [`references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/references/component-cookbook.md) provides one-line indices for 50+ archetypes. The engine loads only needed files—typically 5–7 per page—covering: - **Navigation archetypes** (N1a through N5 floating pill) - **Hero variants** (marquee, split, centered, etc.) - **Section headers and feature grids** - **CTA patterns and footer archetypes** (Ft1–Ft5) ### Theme handling **Catalog route** (default): 20 named themes with automatic rotation. **Custom route** (conditional): entered only when the brief explicitly requests bespoke palettes or provides brand colors. See [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 27–48. ### Example: Running full-page ```bash npx hallmark # brief: "build a SaaS landing page for Tracejam" ``` **Generated stamp:** ```css /* Hallmark · macrostructure: Marquee Hero · theme: Bloom * genre: atmospheric · nav: N5 Floating pill · footer: Ft5 Statement * diversification: different nav (previous N1a), different theme axes (paper-mid vs light) */ ``` --- ## Key Architectural Differences | Aspect | Component-Scope | Full-Page Design | |--------|-----------------|------------------| | **Macrostructure** | Skipped entirely | Selected from 21 options | | **Navigation/Footer** | Omitted | Archetype selection via Cookbook | | **Eight-state CSS** | Mandatory | Per-component, not enforced | | **Slop-test gates** | Subset (no layout safety) | Full 58-gate suite | | **Diversification** | Excluded from [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json) | Macrostructure, theme, nav, footer, archetypes all varied | | **Output artifacts** | 2 files (component + preview) | Full page tree with multiple components | --- ## Diversification and Memory System Hallmark writes a [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) after every full-page run, recording: - Selected macrostructure - Theme and theme axes - Hero enrichment status - Component archetypes used On subsequent runs, the engine **guarantees differences** across four dimensions: - Different macrostructure - Different theme axes - Different nav and footer archetypes - Different component archetypes within the page Component-scope runs **never touch [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json)**. They are intentionally isolated from page-level fingerprinting to allow rapid iteration on individual elements without disrupting site-wide diversification. --- ## Source Code References | File | Purpose | |------|---------| | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Master skill definition; lines 45–58 (full-page flow), lines 60–84 (component-scope flow), lines 95–136 (stamps and eight-state patterns) | | [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | Index of 21 macrostructures for full-page selection | | [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) | 50+ component archetype indices and routing tables | | [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) | Diversification rules, slop-test conventions, stamping standards | --- ## Summary - **Hallmark component-scope** handles single UI elements with mandatory eight-state styling, skips macrostructure/nav/footer, and generates isolated component files with preview wrappers. - **Hallmark full-page design** executes complete site architecture with macrostructure selection, Component Cookbook routing, theme rotation, and 58-gate slop-test validation. - Scope detection relies on signal matching in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md): element names, brief length, file paths, or explicit "just the X" phrasing. - Diversification memory applies only to full-page runs via [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json); component-scope runs remain stateless for rapid iteration. --- ## Frequently Asked Questions ### How does Hallmark decide between component-scope and full-page mode? Hallmark evaluates four signals in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (lines 60–84): single UI element names, briefs under 30 words, target file paths, or explicit "just the X" phrasing. Two or more matching signals trigger component-scope; otherwise, it defaults to full-page design. ### What are the eight mandatory states in Hallmark component-scope? Every component-scope output must define: default, hover, focus-visible, active, disabled, loading, error, and success. These appear in generated CSS and are testable via the [`.preview.html`](https://github.com/Nutlope/hallmark/blob/main/.preview.html) wrapper using helper classes like `.is-hover` and `.is-focus`. ### Why does full-page mode use a log file? The [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) file enables diversification enforcement. Hallmark compares each new run against previous entries to guarantee different macrostructures, theme axes, navigation archetypes, and component selections—preventing repetitive outputs across iterations. ### Can I force full-page mode for a component request? Yes. Deliberately broaden your brief with multiple sections, page types, or layout descriptions. Avoid file paths, single element names, and concise phrasing. The scope detector will default to full-page when component signals fall below the two-signal threshold.