How Hallmark's Component-Scope Flow Differs from Page-Scope Design Flow

Hallmark's component-scope flow strips away macrostructure, navigation, and hero logic from the full page-scope design flow while enforcing strict 8-state CSS coverage and emitting a two-file package isolated from project diversification rules.

Hallmark (Nutlope/hallmark) is an AI-powered design skill that generates UI code with contextual awareness. Understanding how its component-scope flow differs from the page-scope design flow is essential for developers generating reusable UI elements versus complete landing pages. While both flows share token discipline and genre detection, they diverge sharply on state requirements, output structure, and diversification rules.

Scope Detection and Flow Selection

Hallmark selects the component-scope flow early by scanning for specific signals in the user brief. According to skills/hallmark/SKILL.md (lines 64-70), the skill looks for:

• Single element names (button, card, modal, etc.)
• Brief descriptions of ≤30 words
• Target files that resolve to a single component
• Explicit phrasing like "just the X"

When at least two of these signals fire, Hallmark switches to the component-scope flow. Otherwise, it executes the full page-scope design flow.

Foundations Retained from Page-Scope Design

The component-scope flow preserves critical design system checks from the page-scope flow to maintain visual consistency:

• Pre-flight scan (Step 0): Reads existing tokens.css, detects fonts, and identifies the framework
• Genre detection (Step 1): Inherits the project's established genre (editorial, modern-minimal, etc.)
• Theme route (Step 2.6): Uses existing tokens.css / design.md or falls back to the catalog
• Token discipline: All color and font references must remain token-based, identical to page-scope requirements

Steps Removed in Component-Scope Flow

The component flow aggressively trims page-specific scaffolding that would bloat a single UI element. As documented in skills/hallmark/SKILL.md (lines 84-90), the following steps are skipped entirely:

• Macrostructure selection: Components have no macrostructure (no reference to references/structure.md)
• Navigation and footer archetypes: No nav or footer generation
• Hero polish patterns: Hero section logic is page-only
• Enrichment step: Excludes hero illustrations, demo videos, and abstract backgrounds
• Multi-section preview: Replaced by an 8-state demo wrapper
• Project-memory append: Component runs do not write to .hallmark/log.json, preventing diversification rules from rotating macrostructures across the project

State Discipline and Component-Specific Additions

Where the component flow removes page scaffolding, it adds strict requirements for interactive completeness. The flow enforces rules found in references/interaction-and-states.md:

Mandatory 8-State Coverage: Every interactive component must ship CSS for all eight states: default, hover, focus-visible, active, disabled, loading, error, and success.

Two-File Output Pattern: Hallmark generates the component file plus an 8-state demo wrapper (ComponentName.preview.html or .tsx). This wrapper renders the component in every state side-by-side for immediate visual verification without requiring manual test pages.

Component Stamp: Generated files begin with a comment tagging them as component-scoped, preventing later page-level diversification attempts from treating them as extractable content.

Output Artefacts and Diversification Rules

The architectural split creates fundamentally different outputs and project integration behaviors:

Flow	Emitted Artefacts	Diversification Behavior
Page-scope	Full HTML + CSS page with macrostructure, hero, nav, footer; optional design.md lock-in	Pages must differ (diversify) unless design.md locks the system; writes to .hallmark/log.json
Component-scope	Single component file + 8-state demo wrapper	No diversification rules applied; isolated from project memory and log rotation

Practical Usage Examples

Invoke the component-scope flow by targeting a single component file:

# Hallmark recognises component-scope automatically via signals

hallmark redesign ./components/Button.tsx

This emits Button.tsx and Button.preview.html containing the eight states, prefixed with a component-scope comment.

For full page generation, target a page file without component signals:

# Runs the full page-scope design flow

hallmark redesign ./pages/landing.html

This produces complete landing-page HTML + CSS, selects a macrostructure, and adds diversification CTAs.

Force component-scope on ambiguous briefs:

# Explicit component flag for disambiguation

hallmark redesign ./src/ui/Card.vue --component

Verify state coverage using the generated preview:

<!-- ComponentName.preview.html renders all states automatically -->
<!DOCTYPE html>
<html>
  <head><link rel="stylesheet" href="Card.css"></head>
  <body>
    <div class="state-demo">
      <div class="card--default"></div>
      <div class="card--hover"></div>
      <div class="card--disabled"></div>
      <!-- ... remaining states ... -->
    </div>
  </body>
</html>

Summary

• Component-scope flow targets single UI elements, skipping macrostructure, navigation, and hero logic while enforcing 8-state CSS coverage
• Page-scope flow builds complete sites with diversification rules that rotate macrostructures across pages
• Component runs produce a two-file package (component + preview) and do not write to .hallmark/log.json
• Both flows share token discipline, genre detection, and theme routing, but diverge on state requirements and project memory
• Source configuration lives in skills/hallmark/SKILL.md with state definitions in references/interaction-and-states.md

Frequently Asked Questions

What triggers Hallmark to use component-scope instead of page-scope?

Hallmark selects component-scope when it detects at least two specific signals in the brief: naming a single UI element (like "button" or "card"), a description under 30 words, a target path pointing to a single component file, or explicit phrasing like "just the login modal". If fewer than two signals fire, the full page-scope design flow executes.

Why does component-scope skip the project memory append?

Component-scope runs intentionally skip writing to .hallmark/log.json to keep reusable UI elements isolated from diversification rules. Page-scope flow uses this log to ensure consecutive pages have distinct macrostructures, but components must remain portable and undiversified to maintain consistency when dropped into any page.

How does the 8-state requirement work in practice?

Every interactive component generated via component-scope must include CSS for eight specific states defined in references/interaction-and-states.md: default, hover, focus-visible, active, disabled, loading, error, and success. Hallmark validates this coverage during generation and provides a preview wrapper that renders all states side-by-side for visual verification before integration.

Can I convert a page-scope output into a component-scope file later?

While you can extract components from generated pages manually, Hallmark treats them as distinct architectural modes. A component stamp comment placed in component-scope files prevents the skill from later applying page-level diversification rules. To regenerate existing code as a component, run hallmark redesign targeting the specific component file path to trigger component-scope detection.

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