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

> Discover how Hallmark's component-scope flow distills page-scope design by removing macrostructure and navigation, focusing on isolated, two-file packages with 8-state CSS coverage.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-07-19

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) / [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) lock-in | Pages must differ (diversify) unless [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) locks the system; writes to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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:

```bash

# Hallmark recognises component-scope automatically via signals

hallmark redesign ./components/Button.tsx

```

This 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) containing the eight states, prefixed with a component-scope comment.

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

```bash

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

```bash

# Explicit component flag for disambiguation

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

```

Verify state coverage using the generated preview:

```html
<!-- 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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) with state definitions in [`references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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.