How to Create Custom Themes in Hallmark When Catalog Themes Don't Fit

TLDR: Hallmark provides a custom-theme protocol that triggers when briefs contain brand-specific colors, unique aesthetic requirements, or structural demands that exceed the 20 built-in catalog themes, allowing you to generate bespoke OKLCH palettes and typography pairings while maintaining design system compliance.

When the 20 predefined catalog themes in Nutlope/hallmark—such as Specimen, Hum, or Lumen—fail to capture a project's unique brand identity, you must create custom themes using the specialized workflow defined in the repository. This protocol ensures that even fully bespoke visual identities adhere to Hallmark's universal accessibility and structural constraints.

Detecting When You Need a Custom Theme

Hallmark's dispatch logic in skills/hallmark/SKILL.md automatically routes to the custom branch only when specific signals appear in the brief. According to skills/hallmark/references/custom-theme.md (lines 20-24), these triggers include:

• An explicit request for a custom theme
• A named brand color or anchor color
• A multi-attribute aesthetic that no catalog theme captures
• An attached color swatch or mood-board
• Structural requests that the macrostructure catalogue cannot satisfy (e.g., "from scratch" or "art-direct it")

The Custom Theme Protocol

The custom-theme workflow orchestrates between skills/hallmark/references/custom-theme.md and skills/hallmark/SKILL.md through a six-stage pipeline. After signal detection, the system collects user confirmation, selects depth, constructs palettes, validates typography, stamps the build, and proceeds with standard compilation.

Step-by-Step: Building a Custom Theme

Signal Detection and User Confirmation

Once Hallmark identifies a custom signal, it prompts the user with a single follow-up question (see custom-theme.md lines 38-44). This collects a brand vibe description (4-8 words) and an optional anchor color to seed the palette generation.

Choosing the Custom Depth

Hallmark offers two custom depths based on structural requirements (sections 50-60 of custom-theme.md):

• Tuned custom: Generates a one-off OKLCH palette and free-font pairing while preserving Hallmark's existing macrostructures.
• Bespoke custom: Redesigns the page's macrostructure from first principles, creating entirely new layout patterns.

Constructing the OKLCH Palette

Follow the recipe in section B of custom-theme.md (lines 83-100) to build accessible color relationships:

1. Anchor accent: Convert the user-provided color to OKLCH and clamp chroma to 0.12-0.20.
2. Paper tone: Derive lightness (L) from the vibe (e.g., bright → L 95-98%). Tint the paper toward the anchor hue with low chroma (0.005-0.020).

Typography Pairing and Slop-Test Gates

Custom themes must pass the same slop-test gates as catalog themes. Reference skills/hallmark/references/typography.md and skills/hallmark/references/anti-patterns.md to select font pairings that respect contrast requirements (see slop-test.md lines 156-158). The custom palette must maintain accessibility standards despite its bespoke nature.

Stamping and Logging

The first non-empty line of generated CSS must contain a comment summarizing the custom run (custom-theme.md lines 71-77). Additionally, the system records an entry in .hallmark/log.json tracking the three diversification axes—paper-band, display-style, and accent-hue—ensuring future runs rotate appropriately (see SKILL.md line 346).

Example: Custom Theme Implementation

Below is a complete custom theme snippet following the protocol, including the required stamp comment and CSS custom properties:

/* Hallmark · route: custom (tuned) · vibe: "archival warmth, hand-set" · paper: oklch(96% 0.008 30) · accent: oklch(13% 0.15 30) · display: Inter Tight · body: Inter */
:root {
  --color-paper: oklch(96% 0.008 30);
  --color-accent: oklch(13% 0.15 30);
  --color-accent-ink: oklch(95% 0.01 30); /* ensures contrast */
  --font-display: "Inter Tight", system-ui, sans-serif;
  --font-body: "Inter", system-ui, sans-serif;
}

/* Example component overrides */
[data-theme="custom"] .hero__title {
  font-family: var(--font-display);
  color: var(--color-accent);
}
[data-theme="custom"] .body-copy {
  font-family: var(--font-body);
  color: var(--color-paper);
}

Summary

• Hallmark routes to custom themes when briefs contain brand colors, unique aesthetics, or structural demands beyond the 20 catalog themes.
• The protocol lives in skills/hallmark/references/custom-theme.md and triggers on five specific signals defined in lines 20-24.
• Choose between tuned custom (new palette, existing macrostructure) or bespoke custom (redesigned macrostructure).
• Build OKLCH palettes by anchoring accent colors and deriving paper tones from the vibe description.
• All custom themes must pass slop-test gates and include a stamp comment in the generated CSS.

Frequently Asked Questions

What triggers the custom theme route in Hallmark?

The custom route activates when a brief contains explicit custom requests, named brand colors, multi-attribute aesthetics, attached mood-boards, or structural demands that catalog themes cannot satisfy (lines 20-24 of custom-theme.md).

What's the difference between tuned and bespoke custom themes?

Tuned custom generates a unique OKLCH palette and font pairing while keeping Hallmark's existing macrostructures, whereas bespoke custom redesigns the page layout from first principles (sections 50-60 of custom-theme.md).

How does Hallmark ensure accessibility in custom themes?

Custom themes must obey the same contrast and accessibility rules as catalog themes, passing the universal slop-test gates defined in skills/hallmark/references/slop-test.md (lines 156-158).

Where are custom themes logged and tracked?

Each custom build receives a stamp comment in the first line of generated CSS (lines 71-77 of custom-theme.md) and an entry in .hallmark/log.json tracking diversification axes to prevent repetition (line 346 of SKILL.md).

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