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

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, 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, 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 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 or 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.
• 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): Components do not participate in diversification rules that prevent repetitive macrostructures across runs.

Source: 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:

/* 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) 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) 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 so future runs can diversify macrostructures and themes.

Source: 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 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:

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:

<!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:

<!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:

{ "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.
• 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, 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 or 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 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 § 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.

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