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

> Learn how to customize Hallmark behavior by editing source files or using CLI flags. Control the design engine and tailor your experience with these 9 methods.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-26

---

**You customize Hallmark by editing its declarative source files—[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md))

The root behavior contract lives in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css))

All visual styling flows from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/05-workbench.md) define the page skeleton, while `skills/hallmark/references/components/` contains nav and footer archetypes (e.g., [`N5-floating-pill.md`](https://github.com/Nutlope/hallmark/blob/main/N5-floating-pill.md), [`Ft5-statement.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)) and scopes both the theme cluster and copy-voice rules.

To add a new genre:

1. Create [`references/genres/retro.md`](https://github.com/Nutlope/hallmark/blob/main/references/genres/retro.md) (or your chosen name).
2. Add trigger keywords to the detection logic in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/redesign.md)).

## Project Memory and Diversification ([`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json))

After each run, Hallmark writes an entry to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 96‑112).

**Customization strategies:**

- **Reset history**: Delete [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/design.md))

When a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) lines 85‑89).

**Lock workflow:**

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

```

This generates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)).

To customize:

1. Define a new tier archetype (e.g., `E6-3d-model`) in [`references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/references/hero-enrichment.md).
2. Reference it in the enrichment decision step within [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

## Quality Gates ([`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md))

Every generated artifact passes through a 58-gate "slop-test" defined in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md), but this changes the quality guarantees for all downstream generations.

## Practical Code Examples

### Force a specific theme during redesign

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

```

This loads the **Bloom** theme from [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) while re-picking the macrostructure according to diversification rules.

### Audit without editing

```bash
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

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

```

The `--use-dna` flag (defined in [`references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/redesign.md)) skips catalog rotation and adopts the extracted design system.

### Add a bespoke custom theme

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) and `references/themes/`.

## Summary

- **Skill definition**: Edit [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) to change verbs, safety rails, and diversification logic.
- **Themes**: Modify [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to track history or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) to freeze design systems project-wide.
- **Quality**: Adjust [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.