# Component-Scope vs. Page-Scope in Hallmark: Detection Signals and Pipeline Differences

> Understand when to use component-scope vs page-scope in Hallmark. Learn detection signals and pipeline differences to optimize your workflow with this crucial Hallmark feature.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-07-21

---

**Hallmark selects component-scope when your brief names a single UI element, stays under 30 words, points to a specific component file, or uses restrictive phrasing like "just the" or "only the"; otherwise it defaults to page-scope, which runs the full macrostructure and enrichment pipeline.**

Hallmark is an AI-powered design skill that generates production-ready UI code from text briefs. Before entering the main generation flow, the system analyzes your prompt to determine whether you need a **component-scope** artifact (a single, state-complete UI element) or a **page-scope** deliverable (a full landing page with navigation, hero sections, and layout architecture). This scope decision, defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), governs which pipeline steps execute, what quality gates apply, and what files get written to disk.

## How Hallmark Detects Component-Scope vs. Page-Scope

Hallmark decides the scope **before** the Design flow begins by scanning the brief for specific signals. If **any** of the following four cues fire, the system switches to component-scope; if **two** or more fire, component-scope is chosen automatically, otherwise the fallback is page-scope.

- **Element name**: The brief explicitly names a single UI element (e.g., "a button", "a card", "a modal").
- **Length**: The brief is short (≤ 30 words) and refers to only one element.
- **Target file**: The user points to a single component file (e.g., [`./Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/./Button.tsx), [`app/components/Card.vue`](https://github.com/Nutlope/hallmark/blob/main/app/components/Card.vue)).
- **User wording**: Phrases such as *"just the X"*, *"only the Y"*, *"this one element"*, or *"a single ___"*.

These rules are codified in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) under the component-scope-signals section.

## What Component-Scope Preserves from the Page Pipeline

Component-scope is not a stripped-down mode; it inherits several critical architectural steps from the full page flow to ensure consistency with your existing codebase.

- **Step 0 – Pre-flight scan**: Reads existing tokens, fonts, framework detection, and micro-interaction stance.
- **Step 1 – Genre detection**: Inherits the project’s genre (editorial, modern-minimal, atmospheric, playful).
- **Step 2.6 – Theme route**: Adopts the existing token system ([`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)) or picks a catalog theme if none exist.
- **2 + 1 font discipline**: Ensures the component uses the project’s type scale.
- **State discipline**: Enforces code generation for **all eight states**: default, hover, focus-visible, active, disabled, loading, error, and success. The checklist lives in [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md).
- **Slop-test subset**: Runs visual, micro-interaction, contrast, accessibility, and typography gates, but skips diversification and layout-safety gates that assume a full page context.

## Pipeline Steps Skipped in Component-Scope

Because a component is a single element rather than a document, Hallmark bypasses several page-specific architectural steps:

- **Step 2 – Macrostructure pick**: Components have no macrostructure (e.g., long-document, split-diptych).
- **Nav & footer archetypes** (N1–N9, Ft1–Ft8): Navigation and footers belong to pages only.
- **Hero polish patterns** (HP1–HP4): No hero section exists for a button or card.
- **Step 4 – Enrichment**: No hero illustrations, demo videos, or abstract backgrounds are generated.
- **Step 5 – Multi-section preview**: Replaced by an 8-state demo wrapper.
- **Project-memory append** ([`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)): Components do not participate in diversification rules that prevent repetitive macrostructures across runs.

Source: [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) § component-scope-skips.

## Outputs: What Each Scope Emits

### Component-Scope Artifacts

Component-scope emits exactly two files:

1. **The component artifact**: A single file respecting the project’s conventions (React, Vue, Svelte, vanilla, Tailwind, etc.). All styling must reference token variables (`var(--color-accent)`) rather than inlining raw colours. The file includes a stamp marking its scope and states:

```css
/* Hallmark · component: <type> · genre: <genre> · theme: <theme>
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */

```

2. **An 8-state demo wrapper**: A tiny standalone page (e.g., [`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.html)) that renders the component in every required state, using helper classes (`.is-hover`, `.is-focus`, etc.) to force pseudo-class styles.

### Page-Scope Artifacts

When none of the component-scope signals fire, Hallmark follows the full page-level pipeline and emits:

- A complete **multi-section preview** (e.g., [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html)) with navigation, hero, and footer.
- **Macrostructure** selection (e.g., long-document, split-diptych).
- **Navigation** and **footer** archetypes (N1‑N9, Ft1‑F8).
- **Hero polish patterns** (HP1‑HP4) and enrichment assets (illustrations, videos).
- An append to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) so future runs can diversify macrostructures and themes.

Source: [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) § page-scope-flow.

## Handling Ambiguous Briefs

If the brief could be interpreted either way (e.g., "design a pricing section"), the skill asks one short question:

> "One pricing card, or the whole pricing page?"

The default answer is **component-scope**, because redirecting a single-artifact output is cheaper than regenerating a full page. This disambiguation logic appears in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) lines 39‑42.

## Code Examples

### Example: Component-Scope Button Generation

**Brief:**

```

Create a button that shows loading and error states.

```

**Detected signals:**
- Element name ("button") → component-scope.
- Length ≤ 30 words.

**Generated files:**

[`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx):

```tsx
export function Button() { 
  return <button className="btn">Click me</button> 
}
/* Hallmark · component: button · genre: editorial · theme: catalog: "Modern"
 * states: default · hover · focus · active · disabled · loading · error · success
 */

```

[`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.html):

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="Button.css">
</head>
<body>
  <div class="demo">
    <button class="btn is-loading">Loading…</button>
    <button class="btn is-error">Error</button>
  </div>
</body>
</html>

```

### Example: Page-Scope Landing Page Generation

**Brief:**

```

Design a landing page for a travel booking service with a hero, navigation bar, and footer.

```

**Detected signals:**
- No single UI element named.
- Length > 30 words, mentions multiple sections → page-scope.

**Generated files:**

[`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html):

```html
<!DOCTYPE html>
<html>
<head>…</head>
<body>
  <nav class="nav-1">…</nav>
  <section class="hero-hp1">…</section>
  <footer class="ft-3">…</footer>
</body>
</html>

```

Additionally, the run appends a record to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json):

```json
{ "run": 1, "macrostructure": "long-document", "theme": "catalog-modern" }

```

## Summary

- **Scope detection** relies on four signals (element name, length ≤ 30 words, target file, restrictive wording); two signals trigger automatic component-scope.
- **Component-scope** preserves pre-flight scans, genre detection, theme routing, and the 8-state discipline, but skips macrostructure, navigation/footer archetypes, and enrichment.
- **Page-scope** runs the full pipeline including macrostructure selection, hero polish patterns (HP1‑HP4), navigation (N1‑N9) and footer (Ft1‑Ft8) archetypes, and appends to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).
- **Ambiguous briefs** default to component-scope after a single clarification question.

## Frequently Asked Questions

### What are the eight required states for component-scope in Hallmark?

According to [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md), every component-scope artifact must emit code for **default, hover, focus-visible, active, disabled, loading, error, and success**. The generated file includes a stamp comment listing these states, and a preview wrapper demonstrates each state using helper classes like `.is-loading` and `.is-error`.

### Does component-scope use the same design tokens as page-scope?

Yes. Component-scope preserves **Step 2.6 – Theme route**, which adopts the existing token system ([`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)) or selects a catalog theme if none exists. Both scopes enforce the **2 + 1 font discipline** to maintain typographic consistency with the broader project.

### Why does component-scope skip the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) update?

Component-scope skips the **project-memory append** because diversification rules (which prevent repetitive macrostructures and themes across runs) only apply to page-scope generations. Single components do not participate in these layout-level diversity checks, as documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) § component-scope-skips.

### How does Hallmark handle a brief that requests "just a navbar"?

The phrase *"just a"* triggers the **user wording** signal for component-scope. Because navigation archetypes (N1‑N9) are reserved for page-scope flows, Hallmark will ask for clarification: *"One navigation component, or a full page with navigation?"* If confirmed as component-scope, it generates a standalone navigation component with the 8-state discipline (including mobile collapsed states) rather than a full landing page.