# What Defines a Hallmark Theme: Paper Band, Display Style, and Accent Hue Explained > Learn what defines a Hallmark theme: explore paper band, display style, and accent hue. Understand how these elements create a cohesive visual and narrative system. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: deep-dive - Published: 2026-08-07 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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. ## Display Style: Hero, Footer, and Genre Voice The **display style** determines structural layout and narrative tone through two coordinated systems. ### Archetypes (Structural Components) As implemented in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), the `ARCHETYPES` object maps each theme to its hero and footer components: ```javascript // 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: 1. **Store** – Sets `data-theme` attribute on `` element 2. **Structure** – Calls `swapArchetypes(theme)` to inject hero/footer components from `ARCHETYPES` 3. **Label** – Updates visible UI with human-readable name (`THEMES[theme]`) and genre (`THEME_GENRES[theme]`) 4. **Render** – CSS custom properties automatically apply via scoped stylesheets ```javascript // 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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), where each theme dot connects to `applyTheme(btn.dataset.themeBtn)`. ## Key Implementation Files | File | Purpose | |------|---------| | [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.