# How Hallmark Differentiates Component-Scope vs Page-Scope Design Flows

> Discover how Hallmark intelligently distinguishes component-scope from page-scope design flows. Learn about its efficient pipeline routing and signal detection for optimal performance.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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](https://github.com/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)](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`](https://github.com/Nutlope/hallmark/blob/main/./components/Button.vue), [`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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):

1. **The component file** — follows host project conventions (React, Vue, Svelte, Tailwind) and references tokens via `var(--token)`
2. **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:

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

```html
<!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`](https://github.com/Nutlope/hallmark/blob/main/.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)](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)](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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Opt-in [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Token definitions; component-scope files must use `var(--token)` |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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.