deep-dive

What Defines a Hallmark Theme: Paper Band, Display Style, and Accent Hue Explained

August 7, 2026 Nutlope/hallmark ↗

A Hallmark theme is defined by three orthogonal dimensions—paper band (background lightness and hue), display style (hero/footer archetype and genre voice), and accent hue (chromatic highlight color)—that work together to create a complete visual and narrative system.

A Hallmark theme is a runtime-swappable package of design rules that transforms the entire page aesthetic. Each theme combines three independent variables stored in the theme registry at site/js/main.js and documented in reference files under skills/hallmark/references/themes/. Understanding how these dimensions interact lets you predict exactly how any theme will render.

Paper Band: Background Lightness and Hue

The paper band controls the foundational warmth and value of the page. It uses CSS custom properties to define layered background tones:

--color-paper – primary background
--color-paper-2 – secondary surface
--color-paper-3 – tertiary depth

These values use oklch() color space for perceptual uniformity. For example, the Hum theme uses oklch(97% 0.012 95) for its warm, light paper base. You can find these definitions in theme-specific markdown files like skills/hallmark/references/themes/hum.md.

The paper band creates the atmospheric "temperature" of the theme—warm tones (yellow-orange hues around 60-100°) feel inviting, while cool tones (blue hues around 220-260°) feel clinical or professional.

The display style determines structural layout and narrative tone through two coordinated systems.

Archetypes (Structural Components)

As implemented in site/js/main.js, the ARCHETYPES object maps each theme to its hero and footer components:

// site/js/main.js lines 71-92
ARCHETYPES = {
  hum:    { hero: "hum",     footer: "colophon" },
  cobalt: { hero: "marquee", footer: "minimal" },
  grid:   { hero: "letter",  footer: "stack" },
  // ...
}

Genre Voice (Narrative Tone)

The parallel THEME_GENRES object (lines 95-126) assigns each theme a genre that drives copy fixtures—eyebrow labels, ledes, quotes, and overall editorial stance:

Editorial – authoritative, magazine-style prose
Modern-minimal – sparse, direct statements
Atmospheric – evocative, scene-setting language
Playful – conversational, surprising rhythms

Switching themes simultaneously swaps both structure and voice, ensuring visual and verbal consistency.

Accent Hue: The Chromatic Signature

The accent hue provides the clickable, highlightable, interactive color that punctuates each theme. Like paper values, these reside in theme markdown files as --color-accent, --color-accent-2, and extended palettes.

The Cobalt theme demonstrates a cool accent strategy: oklch(80% 0.17 250) places its primary action color in the cyan-blue range. By contrast, Hum clusters multiple accents around 95° (pear-yellow) for layered warmth.

Accent hue operates orthogonally to paper band—both use oklch() but serve different functions: paper provides the stage, accent provides the spotlight.

How Theme Switching Works at Runtime

When a visitor selects a theme via the banner UI, the script executes a coordinated four-step sequence:

Store – Sets data-theme attribute on <html> element
Structure – Calls swapArchetypes(theme) to inject hero/footer components from ARCHETYPES
Label – Updates visible UI with human-readable name (THEMES[theme]) and genre (THEME_GENRES[theme])
Render – CSS custom properties automatically apply via scoped stylesheets

// Trigger a complete theme change
document.documentElement.dataset.theme = 'hum';

// Script automatically:
//   → Applies ARCHETYPES['hum'] (hero: "hum", footer: "colophon")
//   → Sets THEME_GENRES['hum'] genre voice ("playful")
//   → Pulls CSS variables from skills/hallmark/references/themes/hum.md

The button wiring that enables this lives in site/js/main.js, where each theme dot connects to applyTheme(btn.dataset.themeBtn).

Key Implementation Files

File	Purpose
`site/js/main.js`	Central registry: `THEMES`, `ARCHETYPES`, `THEME_GENRES`; handles `applyTheme()` and `swapArchetypes()`
`skills/hallmark/references/themes/*.md`	Per-theme documentation with concrete `oklch()` values for paper and accent dimensions
`site/css/theme.css`	Consumes custom properties to render hairline rules, grid overlays, and genre-specific treatments

Summary

Hallmark theme means a deterministic combination of three independent dimensions: paper band, display style, and accent hue.
Paper band uses oklch() CSS custom properties (--color-paper series) to control background warmth and lightness.
Display style pairs structural archetypes (hero/footer components from ARCHETYPES) with narrative genres (voice from THEME_GENRES).
Accent hue provides the interactive color signature through theme-scoped variables like --color-accent.
Runtime switching updates all three dimensions atomically via data-theme and swapArchetypes().

Frequently Asked Questions

How do I create a new Hallmark theme?

Define three components: add your theme to THEMES, ARCHETYPES, and THEME_GENRES in site/js/main.js (lines 65-126); create a markdown file under skills/hallmark/references/themes/ documenting your oklch() paper and accent values; and build corresponding hero/footer components that consume your CSS custom properties.

Can I use a warm paper band with a cool accent hue?

Yes—the three dimensions are orthogonal by design. The paper band (background warmth) and accent hue (interactive color) operate independently. For example, you could combine Hum's warm paper (oklch(97% 0.012 95)) with Cobalt's cool accent (oklch(80% 0.17 250)) by defining a new theme entry that references each.

Where does the genre voice actually change the text?

The THEME_GENRES mapping in site/js/main.js drives copy fixtures—eyebrow, lede, quote placement, and overall prose rhythm. The specific text strings aren't hardcoded; rather, the genre signals which copy patterns to apply from your content source, ensuring voice consistency with visual presentation.

Why `oklch()` instead of HSL or RGB?

The Hallmark codebase uses oklch() (Oklab color space with chroma and hue) because it provides perceptual uniformity—changing the hue value produces a predictable visual shift without unexpected saturation or lightness jumps that plague HSL. This matters when themes need reliable, systematic color relationships.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how Nutlope/hallmark works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →