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

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. 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, 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 or 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.

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.

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): Components do not participate in diversification rules.

Additionally, the custom theme branch defined in 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:

/* 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) 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:

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 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 and Button.preview.html with all 8 states.

// 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)
 */

<!-- 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 with nav, hero, footer, and updates .hallmark/log.json.

<!-- 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 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}