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

> Understand component-scope vs page-scope design flows in Hallmark. Learn how Hallmark routes briefs for single UI elements or full layouts, optimizing your design process.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/Button.tsx))
- An **8-state demo wrapper** ([`Button.preview.html`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) lock-in | Pages must differ unless locked by [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) |
| **Component-scope** | Single component file + 8-state demo wrapper | No diversification; isolated from [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) entries |

## Practical CLI Examples

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

```bash
hallmark redesign ./components/Button.tsx

```

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

```bash
hallmark redesign ./pages/landing.html

```

Force component-scope manually when the brief is ambiguous:

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

```

Verify all eight states using the generated preview file:

```html
<!-- 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) (as documented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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.