# When to Use Component-Scope vs Page-Scope in Hallmark: Detection Signals and Pipeline Differences

> Learn when to use component-scope vs page-scope in Hallmark. Understand detection signals and pipeline differences to choose automatically.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-07-13

---

**Hallmark determines whether to use component-scope (single UI element) or page-scope (full page) before entering the Design flow by scanning for four specific signals in the brief, automatically selecting component-scope when two or more signals fire.**

Hallmark, an AI-powered design generation tool from the `Nutlope/hallmark` repository, bifurcates its generation pipeline based on scope detection logic defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Understanding when Hallmark switches to component-scope versus maintaining the full page-scope pipeline is critical for predicting output artifacts and structuring effective design briefs.

## How Hallmark Detects Scope: The Four Signals

Hallmark evaluates every brief against four scope-detection signals. If **two or more** signals fire, the system automatically switches to component-scope; otherwise, it defaults to page-scope.

### Signal 1: Element Name

The brief explicitly names a single UI element such as "a button", "a card", or "a modal".

### Signal 2: Brief Length

The request contains **≤ 30 words** and references only one element.

### Signal 3: 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)).

### Signal 4: User Wording

Phrases like "just the X", "only the Y", "this one element", or "a single ___" explicitly narrow scope.

## What Component-Scope Preserves from the Page Pipeline

When operating in component-scope, Hallmark maintains several critical steps from the full page pipeline while omitting page-specific architecture.

### Pre-Flight and Genre Detection

Component-scope retains **Step 0 – Pre-flight scan**, which reads existing tokens, fonts, framework, and micro-interaction stance. It also keeps **Step 1 – Genre detection**, inheriting the project's genre (editorial, modern-minimal, atmospheric, playful).

### Theme and Typography Discipline

The component adopts **Step 2.6 – Theme route**, using existing token systems ([`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)) or selecting a catalog theme if none exist. It enforces the **2 + 1 font discipline**, ensuring the component uses the project's established type scale.

### State Discipline Requirements

Unlike page-scope, component-scope **must** emit code for **all 8 states**: default, hover, focus-visible, active, disabled, loading, error, and success. This checklist is enforced according to [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md).

### Reduced Slop-Testing

Component-scope runs visual, micro-interaction, contrast, a11y, and typography gates, but **skips** diversification and layout-safety gates that assume full-page context, as documented in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md).

## Steps Excluded in Component-Scope Mode

Component-scope explicitly bypasses several steps that only apply to full-page generation:

- **Step 2 – Macrostructure pick**: Components have no macrostructure.
- **Nav & footer archetypes** (N1–N9, Ft1–Ft8): Navigation and footers belong to pages only.
- **Hero polish patterns** (HP1–HP4): No hero section exists for isolated elements.
- **Step 4 – Enrichment**: No hero illustrations, demo videos, or abstract backgrounds.
- **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.

Additionally, the custom theme branch defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) is only available in page-scope.

## Component-Scope Output Artifacts

When Hallmark selects component-scope, it emits exactly two artifacts respecting the project's conventions (React, Vue, Svelte, vanilla, Tailwind, etc.).

### The Component File

A single file where all styling references token variables (`var(--color-accent)`) rather than raw values. The file includes a scope stamp:

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

```

### The 8-State Demo Wrapper

A standalone preview file (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.

## The Full Page-Scope Pipeline

When fewer than two component-scope signals fire, Hallmark executes the complete page-level pipeline defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md):

1. Selects a **macrostructure** (e.g., long-document, split-diptych).
2. Chooses **nav** and **footer** archetypes (N1‑N9, Ft1‑Ft8).
3. Applies **hero polish patterns** (HP1‑HP4) and **enrichment** (illustrations, videos).
4. Generates a **multi-section preview** with full-page layout.
5. Appends a record to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) for diversification tracking.

## Handling Ambiguous Briefs

If a brief could be interpreted either way (e.g., "design a pricing section"), Hallmark asks: *"One pricing card, or the whole pricing page?"* The default resolution is **component-scope**, as redirecting a single-artifact output is cheaper than generating an unnecessary full page.

## Practical Examples

### Example 1: Component-Scope Detection

**Brief:** "Create a button that shows loading and error states."

**Analysis:**
- Element name ("button") detected.
- Length ≤ 30 words.

**Result:** Component-scope selected. Generates [`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) with all 8 states.

```tsx
// Button.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
 * contrast: pass (46–50)
 */

```

```html
<!-- Button.preview.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 2: Page-Scope Detection

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

**Analysis:**
- No single element named.
- Length > 30 words, multiple sections mentioned.

**Result:** Page-scope selected. Generates [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) with nav, hero, footer, and updates [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).

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

```

## Summary

- Hallmark evaluates **four scope-detection signals** (element name, length ≤ 30 words, target file, restrictive wording) before entering the Design flow.
- **Two or more signals** trigger automatic component-scope; otherwise, Hallmark defaults to page-scope.
- Component-scope preserves **pre-flight scans**, **genre detection**, **theme routes**, and **8-state discipline**, but skips macrostructure selection, navigation/footer archetypes, and project-memory logging.
- Component-scope emits a **single component file** with token-based styling and an **8-state demo wrapper**, while page-scope generates **full-page layouts** with [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) tracking.
- Ambiguous briefs default to component-scope after user clarification.

## Frequently Asked Questions

### How does Hallmark decide between component-scope and page-scope?

Hallmark scans the brief for four signals: explicit element naming, brief length under 30 words, single component file targets, and restrictive phrasing like "just the" or "only the." If two or more signals fire, component-scope is selected automatically; otherwise, Hallmark falls back to page-scope.

### What are the 8 required states for component-scope outputs?

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 handle: **default**, **hover**, **focus-visible**, **active**, **disabled**, **loading**, **error**, and **success**. The generated code includes a stamp confirming these states and a demo wrapper visualizing each one.

### Why doesn't component-scope generate a [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) file?

Component-scope intentionally skips the **project-memory append** step because isolated components do not participate in diversification rules. Only page-scope writes to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to track macrostructures and themes for future generation variety.

### Can I force Hallmark to use page-scope for a single element?

If your brief is ambiguous, Hallmark asks for clarification ("One pricing card, or the whole pricing page?"). To ensure page-scope, include multiple sections, navigation requirements, or explicit page-level terminology in your brief, ensuring fewer than two component-scope signals fire.