deep-dive

Hallmark Component-Scope vs. Full-Page Design Handling: Complete Guide

August 5, 2026 Nutlope/hallmark ↗

Hallmark routes every design request into one of two execution paths—component-scope for single UI elements or full-page for complete layouts—based on automated scope detection in SKILL.md.

The Hallmark AI design engine (GitHub: Nutlope/hallmark) employs a dual-path architecture that fundamentally changes how it generates code depending on whether you're building a single button or an entire landing page. Understanding this distinction is critical for predictable, high-quality outputs.

How Hallmark Detects Component-Scope vs. Full-Page

Scope detection happens in SKILL.md (lines 60–84) through a lightweight signal-matching system. The engine looks for four specific indicators:

  • A single UI element name (button, card, modal, etc.)
  • A brief under 30 words
  • A target file path pointing to a component file
  • Explicit phrasing like "just the X"

If two or more signals fire, Hallmark switches to component-scope mode and skips all page-level concerns. Otherwise, it executes the complete full-page design flow.

Component-Scope Flow: Focused, State-Rich Component Generation

In component-scope mode, Hallmark deliberately omits macrostructure, navigation, and footer handling. The flow runs five concentrated steps:

  1. Pre-flight scan — reads package.json, tailwind.config.*, tokens.css, and design.md
  2. Genre detection — inherits the parent page's genre (modern-minimal, atmospheric, etc.)
  3. Theme route — catalog or custom, but only at token-level granularity
  4. Eight-state styling — mandatory CSS for all interactive states
  5. Dual artifact output — component file plus preview wrapper

The eight-state discipline is non-negotiable. Every component must define styles for: default, hover, focus-visible, active, disabled, loading, error, and success.

Component-scope stamp format

/* Hallmark · component: button · genre: modern-minimal · theme: Coral
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */

This stamp appears at the top of generated files, sourced from SKILL.md lines 126–136.

Preview wrapper generation

Hallmark generates a <Component>.preview.html file that forces each state via helper classes:

<!doctype html>
<html lang="en">
<head>
  <link rel="stylesheet" href="button.css">
</head>
<body>
  <h2>Button – 8 states</h2>

  <button class="btn">default</button>
  <button class="btn is-hover">hover</button>
  <button class="btn is-focus">focus</button>
  <button class="btn is-active">active</button>
  <button class="btn" disabled>disabled</button>
  <button class="btn" data-state="loading">loading</button>
  <button class="btn" data-state="error">error</button>
  <button class="btn" data-state="success">success</button>
</body>
</html>

The .is-* classes mirror pseudo-states for manual testing, as documented in SKILL.md lines 95–116.

Example: Running component-scope

npx hallmark redesign ./src/components/Button.tsx

Full-Page Design Flow: Complete Site Architecture

Full-page mode activates for landing pages, dashboards, documentation sites, or any multi-section brief. This path runs eight comprehensive steps:

  1. Pre-flight scan — same token/framework detection as component-scope
  2. Genre detection — establishes aesthetic direction
  3. Macrostructure selection — picks from 21 named macrostructures in references/macrostructures.md
  4. Theme route — catalog (20 named themes with rotation) or custom bespoke palette
  5. Component archetype selection — heroes, sections, features, CTAs, nav, footer via references/component-cookbook.md
  6. Optional hero enrichment — triggered only by image signals in the brief
  7. Slop-test validation — 58 anti-pattern gates
  8. Diversification enforcement — guarantees variation from previous runs

Macrostructure selection

The engine loads references/macrostructures.md and selects exactly one structure. Diversification rules force a different macrostructure than the previous run, logged in .hallmark/log.json.

Component Cookbook routing

The references/component-cookbook.md provides one-line indices for 50+ archetypes. The engine loads only needed files—typically 5–7 per page—covering:

  • Navigation archetypes (N1a through N5 floating pill)
  • Hero variants (marquee, split, centered, etc.)
  • Section headers and feature grids
  • CTA patterns and footer archetypes (Ft1–Ft5)

Theme handling

Catalog route (default): 20 named themes with automatic rotation.
Custom route (conditional): entered only when the brief explicitly requests bespoke palettes or provides brand colors. See SKILL.md lines 27–48.

Example: Running full-page

npx hallmark

# brief: "build a SaaS landing page for Tracejam"

Generated stamp:

/* Hallmark · macrostructure: Marquee Hero · theme: Bloom
 * genre: atmospheric · nav: N5 Floating pill · footer: Ft5 Statement
 * diversification: different nav (previous N1a), different theme axes (paper-mid vs light)
 */

Key Architectural Differences

Aspect Component-Scope Full-Page Design
Macrostructure Skipped entirely Selected from 21 options
Navigation/Footer Omitted Archetype selection via Cookbook
Eight-state CSS Mandatory Per-component, not enforced
Slop-test gates Subset (no layout safety) Full 58-gate suite
Diversification Excluded from log.json Macrostructure, theme, nav, footer, archetypes all varied
Output artifacts 2 files (component + preview) Full page tree with multiple components

Diversification and Memory System

Hallmark writes a .hallmark/log.json after every full-page run, recording:

  • Selected macrostructure
  • Theme and theme axes
  • Hero enrichment status
  • Component archetypes used

On subsequent runs, the engine guarantees differences across four dimensions:

  • Different macrostructure
  • Different theme axes
  • Different nav and footer archetypes
  • Different component archetypes within the page

Component-scope runs never touch log.json. They are intentionally isolated from page-level fingerprinting to allow rapid iteration on individual elements without disrupting site-wide diversification.

Source Code References

File Purpose
skills/hallmark/SKILL.md Master skill definition; lines 45–58 (full-page flow), lines 60–84 (component-scope flow), lines 95–136 (stamps and eight-state patterns)
skills/hallmark/references/macrostructures.md Index of 21 macrostructures for full-page selection
skills/hallmark/references/component-cookbook.md 50+ component archetype indices and routing tables
skills/hallmark/references/structure.md Diversification rules, slop-test conventions, stamping standards

Summary

  • Hallmark component-scope handles single UI elements with mandatory eight-state styling, skips macrostructure/nav/footer, and generates isolated component files with preview wrappers.
  • Hallmark full-page design executes complete site architecture with macrostructure selection, Component Cookbook routing, theme rotation, and 58-gate slop-test validation.
  • Scope detection relies on signal matching in SKILL.md: element names, brief length, file paths, or explicit "just the X" phrasing.
  • Diversification memory applies only to full-page runs via .hallmark/log.json; component-scope runs remain stateless for rapid iteration.

Frequently Asked Questions

How does Hallmark decide between component-scope and full-page mode?

Hallmark evaluates four signals in SKILL.md (lines 60–84): single UI element names, briefs under 30 words, target file paths, or explicit "just the X" phrasing. Two or more matching signals trigger component-scope; otherwise, it defaults to full-page design.

What are the eight mandatory states in Hallmark component-scope?

Every component-scope output must define: default, hover, focus-visible, active, disabled, loading, error, and success. These appear in generated CSS and are testable via the .preview.html wrapper using helper classes like .is-hover and .is-focus.

Why does full-page mode use a log file?

The .hallmark/log.json file enables diversification enforcement. Hallmark compares each new run against previous entries to guarantee different macrostructures, theme axes, navigation archetypes, and component selections—preventing repetitive outputs across iterations.

Can I force full-page mode for a component request?

Yes. Deliberately broaden your brief with multiple sections, page types, or layout descriptions. Avoid file paths, single element names, and concise phrasing. The scope detector will default to full-page when component signals fall below the two-signal threshold.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →