# How to Use Hallmark's Default Verb to Build a New UI: A Complete Guide
> Learn to build new UIs with Hallmark's default verb. This guide shows how to generate token-driven interfaces from scratch using the `hallmark` command for a complete UI.
- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-06
---
**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)](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`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, and [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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/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/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/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). This file functions as the **single source of truth** for the entire design system, as specified in [[`export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) present** | Hallmark creates a new design system on-the-fly and writes [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | Each page may use different themes/genres |
| **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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
```bash
# Design a landing page for a SaaS startup
hallmark "SaaS startup landing page: headline, three features, CTA"
```
### Custom Palette Trigger
```bash
# Explicit brand color forces custom theme route
hallmark "Brand X landing page – primary colour #4A90E2, clean modern look"
```
### Inspect Generated Tokens
```bash
# The default verb always produces this file
cat site/css/tokens.css
```
## Typical Output Structure
### Generated HTML ([`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html))
```html
Brand X launches
A clean modern look for fast growth.
```
### Generated Tokens ([`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css))
```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`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) | Page shape catalog | [[`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) |
| [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) |
| [`hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) |
| [`export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) |
| [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | Runtime-generated design system | [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) |
| [`app.css`](https://github.com/Nutlope/hallmark/blob/main/app.css) | Runtime-generated page styles | [`site/css/app.css`](https://github.com/Nutlope/hallmark/blob/main/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/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) ensures maintainable, themeable design systems.
- The default verb **creates systems** when none exist and **respects locked systems** when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) by default, with page-specific styles in [`site/css/app.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/app.css). These paths follow the export format specification in [[`export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) or [`app.css`](https://github.com/Nutlope/hallmark/blob/main/app.css). This comment records the selected genre, macrostructure, theme, and self-critique scores from Step 6 of the design flow.