Component-Scope vs Page-Scope Design Flows in Hallmark: A Complete Guide

Hallmark automatically routes design briefs to either a component-scope flow for single UI elements or a page-scope flow for full layouts, with the former skipping macrostructure steps and enforcing strict eight-state CSS coverage while the latter builds complete pages with navigation and diversification rules.

The open-source Hallmark design agent (Nutlope/hallmark) distinguishes between generating isolated UI elements and complete web pages through two distinct execution paths. Understanding when and how the system switches between component-scope and page-scope design flows ensures you receive the correct artifacts—whether that is a single button with exhaustive state coverage or a fully diversified landing page.

How Hallmark Detects Component Scope

According to skills/hallmark/SKILL.md (lines 64-70), the skill evaluates specific signals before executing either flow.

Automatic Signal Detection

The component-scope flow triggers when the system detects at least two of the following signals:

• Briefs naming a single element (button, card, modal)
• Descriptions under 30 words
• Target paths pointing to a single component file
• Explicit phrasing like "just the X"

If fewer than two signals fire, Hallmark defaults to the full page-scope design flow.

Manual Override

You can force component-scope execution using the --component flag when auto-detection proves ambiguous.

Steps Shared Across Both Flows

The component-scope flow retains the foundational preprocessing steps from the standard design pipeline:

• Pre-flight scan (Step 0): Reads existing tokens, fonts, and framework settings from the project
• Genre detection (Step 1): Inherits the project's established visual genre (editorial, modern-minimal, etc.)
• Theme routing (Step 2.6): References existing tokens.css or design.md files, or falls back to the theme catalog
• Token discipline: All color and font references must use design tokens regardless of scope

What Component-Scope Removes from the Design Flow

When running in component mode, Hallmark intentionally skips six page-specific steps documented in SKILL.md (lines 84-90):

1. Macrostructure selection – Components exist outside layout grids
2. Navigation archetype picks – No headers or menus required for isolated elements
3. Footer archetype picks – Page boundaries are irrelevant for single components
4. Hero polish patterns – Hero treatments apply only to full-page compositions
5. Enrichment steps – No hero illustrations, demo videos, or abstract backgrounds
6. Multi-section previews – Replaced by the 8-state demo wrapper
7. Project-memory append – Component runs do not write to .hallmark/log.json, bypassing diversification rules that rotate macrostructures across pages

Unique Requirements of Component-Scope Flow

Eight-State CSS Coverage

Unlike page-scope flows, component-scope mandates CSS for all eight interaction states defined in references/interaction-and-states.md: default, hover, focus-visible, active, disabled, loading, error, and success.

Dual-File Output Structure

Every component-scope run generates two files:

• The component file itself (e.g., Button.tsx)
• An 8-state demo wrapper (Button.preview.html or .tsx) rendering the component in every state for visual verification

Component Stamp Protection

Generated files begin with a comment tagging them as component-scoped. This stamp prevents the diversification engine from treating the file as a page that must differ from previous generations.

Output Comparison and Diversification Rules

Flow	Emitted Artifacts	Diversification Behavior
Page-scope	Full HTML/CSS page with macrostructure, hero, nav, and footer; optional design.md lock-in	Pages must differ unless locked by design.md
Component-scope	Single component file + 8-state demo wrapper	No diversification; isolated from .hallmark/log.json entries

Practical CLI Examples

Invoke component-scope via auto-detection by targeting a component file:

hallmark redesign ./components/Button.tsx

Run the full page-scope flow on a full page:

hallmark redesign ./pages/landing.html

Force component-scope manually when the brief is ambiguous:

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

Verify all eight states using the generated preview file:

<!-- Open Button.preview.html in browser -->
<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="Button.css">
  </head>
  <body>
    <div id="root"></div>
    <!-- Renders: default, hover, focus-visible, active, disabled, loading, error, success -->
  </body>
</html>

Summary

• Hallmark's SKILL.md routes briefs to component-scope when detecting two or more single-element signals or when using the --component flag
• Component-scope preserves token discipline and genre detection but removes macrostructure, navigation, and hero generation steps
• The component flow enforces eight-state CSS coverage and emits a dedicated preview file for state verification
• Unlike page-scope, component runs skip .hallmark/log.json entries and diversification rules, keeping outputs lightweight and reusable across projects

Frequently Asked Questions

How does Hallmark decide between component and page scope automatically?

The system evaluates four signals defined in skills/hallmark/SKILL.md (lines 64-70): briefs describing single UI elements, descriptions under 30 words, target paths pointing to component files, and explicit phrasing like "just the button". When two signals trigger simultaneously, Hallmark switches to component-scope; otherwise, it executes the full page-scope design flow.

Why does component-scope require eight different states?

According to references/interaction-and-states.md, interactive components must ship with complete CSS for default, hover, focus-visible, active, disabled, loading, error, and success states. This ensures the component is production-ready and accessible regardless of where it is dropped into a codebase, preventing missing hover or focus styles that often plague design systems.

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

Yes, but you must manually invoke the page-scope flow on a new target file. The component stamp in the generated file prevents automatic diversification, so running hallmark redesign on a page path separately generates the surrounding macrostructure, navigation, and hero elements without conflicting with the existing component.

What happens to the project memory when I generate components?

Component-scope runs intentionally skip writing to .hallmark/log.json (as documented in SKILL.md lines 84-90). This isolation prevents component generations from triggering diversification rules that would force subsequent pages to look different, maintaining a consistent design system while allowing unlimited reuse of the generated elements.

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