How to Customize Hallmark Behavior: 9 Ways to Control the Design Engine

You customize Hallmark by editing its declarative source files—SKILL.md, tokens.css, macrostructure archetypes, and genre rules—or by using CLI flags like --mood and --custom to override behavior at runtime.

Hallmark is a deterministic, rule-based design skill that generates UI through a structured pipeline. Unlike open-ended AI generation, it relies on a catalog system of themes, macrostructures, and component archetypes defined in the Nutlope/hallmark repository. Customizing its behavior means tweaking these declarative layers or using verb-level flags to bypass catalog rotation.

Skill Definition Layer (SKILL.md)

The root behavior contract lives in skills/hallmark/SKILL.md. This file declares the four verbs (audit, redesign, study, and the default Design flow) and enforces safety rails that prevent destructive edits.

Key customization points:

• Verb table (lines 19‑28): Add new verbs or modify existing contracts.
• Safety rails (lines 32‑38): Adjust the threshold for file deletion warnings.
• Diversification rules (lines 68‑73): Change how many previous macrostructures are excluded from selection (default is last three runs).

Note: The SKILL file is intended to stay stable because downstream tools (Claude, Cursor, Codex) depend on its exact shape. Edit with caution.

Visual Tokens and Themes (site/css/tokens.css)

All visual styling flows from site/css/tokens.css. Each theme sits inside a [data-theme="…"] CSS block defining:

• Paper color: --color-paper (background hue band)
• Accent color: --color-accent (primary brand color)
• Typography: --font-display, --font-body
• Component shape: Border radius, weight, and shadows under "PER‑THEME COMPONENT SHAPE"

To add a custom theme:

1. Copy an existing [data-theme="..."] block in tokens.css and rename it (e.g., [data-theme="my-theme"]).
2. Modify the OKLCH values for your palette.
3. Create skills/hallmark/references/themes/my-theme.md describing the archetype.
4. Reference it via --mood my-theme in CLI commands.

Page Structure and Layouts (Macrostructures)

Hallmark selects from 21 page macrostructures stored in skills/hallmark/references/macrostructures/. Files like 05-workbench.md define the page skeleton, while skills/hallmark/references/components/ contains nav and footer archetypes (e.g., N5-floating-pill.md, Ft5-statement.md).

Customization workflow:

• Create a new markdown file following the existing format in references/macrostructures/.
• Reference its slug in the "Pick a macrostructure FIRST" section of SKILL.md (lines 64‑66).
• The diversification engine (lines 96‑112) automatically avoids reusing the last three selected macrostructures unless overridden.

Genre and Tone Control

Four genre files reside under skills/hallmark/references/genres/: "editorial", "modern-minimal", "atmospheric", and "playful". The genre auto-detects from brief keywords (see "Genre — pick before themes", lines 30‑36 in SKILL.md) and scopes both the theme cluster and copy-voice rules.

To add a new genre:

1. Create references/genres/retro.md (or your chosen name).
2. Add trigger keywords to the detection logic in SKILL.md (lines 30‑36).
3. Define associated theme clusters in the genre file.

CLI Verb Flags

Runtime behavior changes through verb-specific flags parsed in references/verbs/:

• hallmark audit <target>: Scores existing code against the 58-gate slop-test without editing files.
• hallmark redesign <target> --mood <name>: Forces a specific theme while allowing macrostructure diversification (parsed in references/verbs/redesign.md).
• hallmark study <url>: Extracts design DNA from a competitor for later use with --use-dna.

Extension point: Add flags like --no-enrichment by editing the corresponding verb reference file (e.g., references/verbs/redesign.md).

Project Memory and Diversification (.hallmark/log.json)

After each run, Hallmark writes an entry to .hallmark/log.json containing the selected macrostructure, theme, enrichment, and brief. The next run reads the last 3‑5 entries to enforce diversification (see SKILL.md lines 96‑112).

Customization strategies:

• Reset history: Delete .hallmark/log.json to clear diversification constraints for experiments.
• Manual override: Edit the JSON directly to force specific combinations on the next run.

Locked Design Systems (design.md)

When a design.md file exists at the project root, Hallmark treats it as the single source of truth for genre, theme, and palette choices. This bypasses catalog rotation entirely (see SKILL.md lines 85‑89).

Lock workflow:

hallmark redesign ./src/pages/landing.tsx --lock

This generates design.md at the repository root. Edit this file directly to freeze a custom typography scale or color system across all future generations.

Component Enrichment Rules

Hero enrichment (video backgrounds, CSS art, illustrations) is governed by references/hero-enrichment.md. Hallmark only activates enrichment tiers when the brief signals intent (see "Decide on hero enrichment", lines 93‑98 in SKILL.md).

To customize:

1. Define a new tier archetype (e.g., E6-3d-model) in references/hero-enrichment.md.
2. Reference it in the enrichment decision step within SKILL.md.

Quality Gates (references/slop-test.md)

Every generated artifact passes through a 58-gate "slop-test" defined in references/slop-test.md. Scores are stamped at the top of each file (lines 46‑48).

Adjustment warning: You can modify gate thresholds in slop-test.md, but this changes the quality guarantees for all downstream generations.

Practical Code Examples

Force a specific theme during redesign

hallmark redesign ./src/pages/home.tsx --mood bloom

This loads the Bloom theme from tokens.css while re-picking the macrostructure according to diversification rules.

Audit without editing

hallmark audit ./src/components/Button.tsx

Returns a ranked punch-list of anti-patterns (e.g., invented metrics, inline colors) without modifying the source file.

Study competitor DNA then apply

hallmark study https://example.com/hero
hallmark redesign ./src/pages/new.tsx --use-dna

The --use-dna flag (defined in references/verbs/redesign.md) skips catalog rotation and adopts the extracted design system.

Add a bespoke custom theme

hallmark redesign ./src/pages/landing.tsx --custom

The --custom flag prompts for a vibe description and anchor color, then constructs an OKLCH palette on the fly, writing the new theme to tokens.css and references/themes/.

Summary

• Skill definition: Edit skills/hallmark/SKILL.md to change verbs, safety rails, and diversification logic.
• Themes: Modify site/css/tokens.css and add entries to references/themes/.
• Structures: Create new macrostructure files in references/macrostructures/ and genre files in references/genres/.
• Runtime control: Use --mood, --custom, --use-dna, and --lock flags to bypass catalog rotation.
• Persistence: Use .hallmark/log.json to track history or design.md to freeze design systems project-wide.
• Quality: Adjust references/slop-test.md gates to change quality thresholds (with caution).

Frequently Asked Questions

How do I lock a theme so Hallmark uses it for every generation?

Create a design.md file at your project root. You can generate one automatically by running hallmark redesign <target> --lock, then editing the file to specify your preferred genre, theme, and tokens. When design.md exists, Hallmark skips catalog rotation and uses these values as the single source of truth.

What is the diversification rule in Hallmark?

The diversification rule prevents repetitive designs by excluding the last three used macrostructures and themes from selection. Hallmark reads .hallmark/log.json (which stores the last 3‑5 runs) and filters these from the candidate pool. Delete this log file to reset the history and allow previously used structures again.

How do I add a completely custom theme to Hallmark?

Copy an existing theme block in site/css/tokens.css and rename it (e.g., [data-theme="brand"]). Adjust the OKLCH values for paper and accent colors, plus font families. Then create skills/hallmark/references/themes/brand.md describing the archetype. Invoke it with hallmark redesign <target> --mood brand or use --custom for dynamic palette generation.

What is the difference between audit and redesign verbs?

hallmark audit performs read-only analysis, scoring the target file against the 58-gate slop-test and outputting a punch-list of anti-patterns without modifying code. hallmark redesign generates new code, applying macrostructure, theme, and component archetype transformations while optionally accepting flags like --mood or --lock to constrain the output.

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