# How Hallmark Manages Component-Scope vs Page-Scope Flows: A Complete Guide

> Learn how Hallmark manages component-scope vs page-scope flows. Discover its automatic detection and optimized state-coverage rules for efficient UI element or full page design.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: tutorial
- Published: 2026-08-01

---

**Hallmark automatically detects whether a brief describes a single UI element or a full page, then switches to a trimmed-down Component-Scope flow with strict state-coverage rules, or runs the complete Design flow for page-level output.**

The Nutlope/hallmark repository implements a dual-path architecture that fundamentally changes how the AI generates code depending on scope. Understanding this distinction is critical for developers who want predictable, high-quality output—whether they're building reusable UI components or complete landing pages.

## How Hallmark Detects Component Scope vs Page Scope

Before any code generation begins, Hallmark performs **scope detection** based on signals in the brief and target file.

The skill looks for four component-scope signals as defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 64–70):

- **Single-element naming** – brief mentions "button," "card," "modal," etc.
- **Brief length** – description is ≤ 30 words
- **Target file** – points to a single component file
- **Explicit phrasing** – user says "just the X"

When **two or more signals fire**, Hallmark switches to Component-Scope flow. Otherwise, it defaults to the full page-scope Design flow.

## What the Component-Scope Flow Keeps from the Page-Scope Design Flow

The Component-Scope flow isn't a rewrite—it's a surgical reduction. According to the source code, these steps remain identical:

| Step | Behavior |
|------|----------|
| **0. Pre-flight scan** | Reads existing tokens, fonts, framework from the project |
| **1. Genre detection** | Inherits the project's genre (editorial, modern-minimal, etc.) |
| **2.6. Theme route** | Uses existing [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) / [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or falls back to catalog |
| **Font & token discipline** | All color/font references must be token-based |

This ensures components stay visually consistent with their parent projects even when generated in isolation.

## Steps the Component-Scope Flow Removes (Skips)

The Component-Scope flow explicitly skips six page-level steps, as documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 84–90):

- **Macrostructure pick** – components have no macrostructure
- **Nav/footer archetype picks** – no navigation or footer scaffolding
- **Hero polish patterns** – hero sections are page-only constructs
- **Enrichment step** – no hero illustration, demo video, or abstract background
- **Multi-section preview** – replaced by an 8-state demo wrapper
- **Project-memory append** – no [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) entry, so diversification rules don't apply

These removals keep components lightweight and free of page-specific assumptions.

## What the Component-Scope Flow Adds: State Discipline

Where the flow subtracts page structure, it adds **rigorous state coverage**. The Component-Scope flow mandates three additions:

**Strict state discipline** – Every interactive component must ship CSS for all **eight states**: default, hover, focus-visible, active, disabled, loading, error, success. The canonical checklist lives in [`references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/references/interaction-and-states.md).

**Two-file output** – Hallmark generates:
  - The component file itself ([`Button.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx), [`Card.vue`](https://github.com/Nutlope/hallmark/blob/main/Card.vue), etc.)
  - An **8-state demo wrapper** ([`ComponentName.preview.html`](https://github.com/Nutlope/hallmark/blob/main/ComponentName.preview.html) or `.tsx`) for visual verification

**Component stamp** – A generated comment at the file's start tags it as component-scoped, preventing later page-level diversification from altering it.

## Command Examples: Triggering Each Flow

### Invoke component-scope automatically

```bash

# Target a single component file – Hallmark recognizes component-scope

hallmark redesign ./components/Button.tsx

```

**Result:** Hallmark emits [`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 the eight states, prefixed with a component-scope comment.

### Invoke page-scope (default) flow

```bash

# No component signals – Hallmark runs full design flow

hallmark redesign ./pages/landing.html

```

**Result:** Full landing-page HTML + CSS with macrostructure, hero, nav, footer, and diversification CTA.

### Force component-scope on ambiguous briefs

```bash

# Explicitly treat brief as component

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

```

The `--component` flag disambiguates when signals are unclear.

### Inspect the 8-state demo wrapper

```html
<!DOCTYPE html>
<html>
  <head><link rel="stylesheet" href="Card.css"></head>
  <body>
    <!-- Auto-generated demo showing all states -->
    <div class="card-preview"></div>
  </body>
</html>

```

Open this preview in a browser to verify state styling without writing test pages.

## Divergent Outcomes: Component vs Page Artifacts

| Flow | Emitted Artifacts | Diversification Rule |
|------|-------------------|----------------------|
| **Page-scope (Design flow)** | Full HTML + CSS page, macrostructure, hero, nav, footer, optional [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) lock-in | Pages must differ unless [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) locks the system |
| **Component-scope** | Single component file + 8-state demo wrapper | No diversification; isolated; no [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) entry |

This architectural split ensures components remain reusable while pages stay visually distinct across a site.

## Key Source Files for Scope Management

| File | Role |
|------|------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Master skill definition; component-scope and page-scope flow descriptions |
| [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md) | Checklist of eight required component states |
| [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Portable design system (page-scope only) |
| [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) | Component implementations and best practices |
| [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) | Page macrostructures (page-scope only) |

## Summary

- **Scope detection** uses four signals; two or more trigger Component-Scope flow
- **Component-Scope keeps** pre-flight, genre, theme, and token discipline from the full Design flow
- **Component-Scope removes** macrostructure, nav/footer, hero, enrichment, multi-section preview, and project-memory logging
- **Component-Scope adds** mandatory 8-state CSS, two-file output, and component stamps
- **Page-Scope enforces diversification** across pages; **Component-Scope isolates output** for reusability

## Frequently Asked Questions

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

Hallmark evaluates four signals: single-element naming, brief length ≤ 30 words, single-component target file, and explicit "just the X" phrasing. When two or more signals match, it runs Component-Scope flow; otherwise, it defaults to the full page-scope Design flow.

### Why does the component flow skip macrostructure and hero steps?

Components are reusable UI pieces, not complete pages. Including macrostructure, navigation, footers, or hero sections would impose page-level assumptions that limit where the component can be dropped. The trimmed-down flow keeps output lightweight and context-agnostic.

### What are the eight required component states in Hallmark's component flow?

Every interactive component must implement: default, hover, focus-visible, active, disabled, loading, error, and success. These are enforced via the checklist in [`references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/references/interaction-and-states.md) and visually verified through the auto-generated preview wrapper.

### Does component-scope output affect Hallmark's diversification rules?

No. Component runs do not write to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), so they bypass the diversification system entirely. Only page-scope outputs are tracked and rotated to ensure visual variety across a site's pages.