How to Use Hallmark's Default Verb to Build a New UI: A Complete Guide

The default verb is Hallmark's entry point for generating fresh UIs from scratch—simply run hallmark with a brief to trigger the deterministic Design flow that produces a complete, token-driven interface.

Hallmark's default verb serves as the primary mechanism for creating new user interfaces without pre-existing design systems. When you invoke Hallmark without specifying a verb qualifier—such as asking it to "design a landing page" or just running the base command—the system automatically follows the Design flow (default) defined in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). This flow enforces Hallmark's anti-AI-slop discipline through a rigorous, sequenced process that transforms a textual brief into production-ready code.

How the Default Design Flow Works

The default verb executes eight deterministic steps. Each step references specific source files in the Hallmark repository to ensure consistent, high-quality output.

Step 0: Pre-Flight Scan

Hallmark first inspects your existing project structure. It reads package.json, tailwind.config.*, and tokens.css to detect any established design system, font stack, color palette, motion libraries, and framework. This scan prevents collision with existing work and enables intelligent inheritance.

Step 1: Genre Detection

From your brief, Hallmark extracts a genre that shapes the entire design's tone and structure. The four supported genres are:

• editorial — journalism-inspired, text-forward layouts
• modern-minimal — clean, spacious, precision-driven
• atmospheric — immersive, mood-heavy experiences
• playful — energetic, unconventional, bold

This genre influences copy style, macro-structure choices, and visual weight distribution according to [SKILL.md lines 62-67](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

Step 2.6: Theme Route Selection

By default, Hallmark selects from 20 catalog themes (e.g., Lumen, Hum, Cobalt) and rotates them across invocations to prevent repetitive output. The theme route only switches to custom when your brief explicitly signals a brand-specific palette or color requirement.

Step 2: Macrostructure Pick

Hallmark chooses a page-level macrostructure that defines the overall shape: hero → feature-grid → CTA → footer, or alternative compositions. The complete catalog resides in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md).

Step 3: Component Archetype Assignment

The selected macrostructure implies specific navigation and footer archetypes:

• Navigation: N1a through N13 variants
• Footer: Ft1 through Ft8 variants

These routing tables are documented in [component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md).

Step 4: Hero Enrichment Decision

Hallmark determines whether the hero section should be typography-only or include imagery/illustration based on rules in [hero-enrichment.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md). This decision balances narrative clarity against visual density.

Step 5: Token Emission

All color and font values export as CSS custom properties to site/css/tokens.css. This file functions as the single source of truth for the entire design system, as specified in [export-formats.md lines 14-19](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md).

Step 6: Pre-Emit Self-Critique

Before returning output, Hallmark scores the design on six axes: Philosophy, Hierarchy, Execution, Specificity, Restraint, and Variety. This stamp appears in generated files for traceability ([SKILL.md lines 46-47](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)).

Design System Behavior: Created vs. Locked

The default verb handles design systems differently based on input context:

Scenario	Behavior	Diversification Rule
No design.md present	Hallmark creates a new design system on-the-fly and writes tokens.css	Each page may use different themes/genres
design.md already exists	Hallmark treats the system as locked; only adds new page macrostructure	Pages share the same system (inverted diversification)

This behavior is documented in [SKILL.md lines 53-55](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). The locked mode ensures brand consistency across multi-page builds.

Practical Invocation Examples

Basic Default Build

# Design a landing page for a SaaS startup

hallmark "SaaS startup landing page: headline, three features, CTA"

Custom Palette Trigger

# Explicit brand color forces custom theme route

hallmark "Brand X landing page – primary colour #4A90E2, clean modern look"

Inspect Generated Tokens

# The default verb always produces this file

cat site/css/tokens.css

Typical Output Structure

Generated HTML (index.html)

<!DOCTYPE html>
<html lang="en" data-theme="hum">
<head>
  <link rel="stylesheet" href="/site/css/tokens.css">
  <link rel="stylesheet" href="/site/css/app.css">
</head>
<body>
  <header class="hero">
    <h1 class="hero__display">Brand X <em class="verb">launches</em></h1>
    <p class="hero__lede">A clean modern look for fast growth.</p>
  </header>
  <!-- Feature grid, CTA, Footer follow -->
</body>
</html>

Generated Tokens (site/css/tokens.css)

:root {
  --color-background: oklch(99% 0.01 260);
  --color-foreground: oklch(15% 0.12 260);
  --color-accent: oklch(65% 0.20 210);
  --font-display: var(--font-geist-display);
  --font-body: var(--font-geist);
  /* Additional tokens... */
}

/* Hallmark diagnostic stamp */
/* Hallmark · genre: modern-minimal · macrostructure: Bento Grid · theme: hum */

The diagnostic comment at the bottom enables auditing and reproducibility across multiple Hallmark runs.

Key Source Files for the Default Verb

File	Purpose	Location
SKILL.md	Core default verb definition and complete design flow	[skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)
macrostructures.md	Page shape catalog	[skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)
component-cookbook.md	Navigation and footer archetype tables	[skills/hallmark/references/component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md)
hero-enrichment.md	Hero visual strategy rules	[skills/hallmark/references/hero-enrichment.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md)
export-formats.md	Token file specification	[skills/hallmark/references/export-formats.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md)
tokens.css	Runtime-generated design system	site/css/tokens.css
app.css	Runtime-generated page styles	site/css/app.css

Summary

• The default verb activates when you run hallmark without qualifiers, triggering the Design flow from [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).
• Eight deterministic steps enforce anti-slop discipline: pre-flight scan, genre detection, theme selection, macrostructure pick, archetype assignment, hero enrichment, token emission, and self-critique.
• Token-driven output in site/css/tokens.css ensures maintainable, themeable design systems.
• The default verb creates systems when none exist and respects locked systems when design.md is present.
• All decision logic is transparent and auditable through source file references and diagnostic stamps.

Frequently Asked Questions

What happens if I run hallmark with no arguments?

Hallmark prompts for a brief or exits with usage guidance. The default verb requires at minimum a textual description of the desired UI to proceed through the design flow.

Can I force a specific theme instead of the default rotation?

Yes—include explicit color requirements or theme names in your brief. Phrases like "using Cobalt theme" or "primary color #FF5733" trigger the custom theme route, bypassing the catalog rotation described in [SKILL.md lines 38-39](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

Where does Hallmark store the generated design system?

All tokens write to site/css/tokens.css by default, with page-specific styles in site/css/app.css. These paths follow the export format specification in [export-formats.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md).

How can I verify which decisions Hallmark made for my build?

Check the diagnostic stamp at the bottom of tokens.css or app.css. This comment records the selected genre, macrostructure, theme, and self-critique scores from Step 6 of the design flow.

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