# Hallmark Theme-Diversification Rule: Paper Band, Display Style, and Accent Hue Explained

> Learn Hallmark's theme diversification rule. Discover how unique paper bands, display styles, and accent hues ensure distinct theme pairings for your projects.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-04

---

**Hallmark's theme-diversification rule requires each theme to combine a unique paper-band display style with a distinct accent hue, ensuring no two themes share the same pairing.**

The `Nutlope/hallmark` repository implements a systematic approach to visual theming that separates structural presentation from color identity. This article breaks down exactly how the paper-band display style and accent hue work together to create visually distinct themes while maintaining architectural consistency.

## What Is Hallmark's Theme-Diversification Rule?

Hallmark's **theme-diversification rule** is a design constraint enforced across the entire theme catalog. It operates on two independent properties that together guarantee visual uniqueness:

- **Paper-band display style** — The decorative band that appears across the top of each themed page (e.g., `solid`, `striped`, `dotted`)
- **Accent hue** — The primary interactive color drawn from Hallmark's curated palette (e.g., `indigo`, `teal`, `amber`)

The rule states that **the combination of `bandStyle` + `accentHue` must be unique for every theme** in the `THEMES` registry. This creates a multiplicative design space: multiple band styles multiplied by multiple accent hues yield many distinct visual identities without requiring entirely separate component architectures.

## Where the Rule Is Defined: [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)

The core theme registry lives in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). Each theme entry declares its `bandStyle` and `accentHue` as required fields:

```javascript
// site/js/main.js — THEMES object with diversification fields
const THEMES = {
  // … existing themes …
  sunrise: {
    title: "Sunrise",
    bandStyle: "striped",      // paper-band display style
    accentHue: "amber",        // accent hue — must be unique combo
    // other theme-specific properties …
  },
  ocean: {
    title: "Ocean",
    bandStyle: "solid",
    accentHue: "teal",
  },
  midnight: {
    title: "Midnight",
    bandStyle: "dotted",
    accentHue: "indigo",
  },
};

```

The `swapArchetypes` function reads these values at runtime and applies them as data attributes to the document body, which CSS then targets for styling:

```javascript
// site/js/main.js — swapArchetypes applies the visual tokens
function swapArchetypes(theme) {
  const { bandStyle, accentHue } = THEMES[theme];
  document.body.dataset.bandStyle = bandStyle;   // e.g., "striped"
  document.body.dataset.accentHue = accentHue;   // e.g., "amber"
  // … remaining archetype swaps …
}

```

## How Paper-Band Display Styles Work

The **paper-band display style** controls the visual treatment of the decorative header band. Implemented in [`site/css/theme.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/theme.css), each style maps to a CSS class via the `data-band-style` attribute:

```css
/* site/css/theme.css — paper-band style variations */
[data-band-style="solid"] .paper-band {
  background: var(--band-color);
  border: none;
}

[data-band-style="striped"] .paper-band {
  background: repeating-linear-gradient(
    45deg,
    var(--band-color),
    var(--band-color) 10px,
    transparent 10px,
    transparent 20px
  );
}

[data-band-style="dotted"] .paper-band {
  background-image: radial-gradient(var(--band-color) 2px, transparent 2px);
  background-size: 10px 10px;
}

```

Available `bandStyle` values in the current implementation include:
- `solid` — uniform fill
- `striped` — diagonal repeating pattern
- `dotted` — radial dot pattern

## How Accent Hues Are Applied

The **accent hue** drives interactive element colors. Like band styles, accent hues are applied via data attributes and mapped to CSS custom properties:

```css
/* site/css/theme.css — accent hue palette */
[data-accent-hue="amber"] {
  --accent-color: #f59e0b;
  --accent-hover: #d97706;
}

[data-accent-hue="teal"] {
  --accent-color: #14b8a6;
  --accent-hover: #0d9488;
}

[data-accent-hue="indigo"] {
  --accent-color: #6366f1;
  --accent-hover: #4f46e5;
}

```

These custom properties are consumed by button, link, and focus-state rules throughout the component library.

## Build-Time Enforcement in [`build/check-themes.js`](https://github.com/Nutlope/hallmark/blob/main/build/check-themes.js)

The diversification rule isn't merely conventional—it's **enforced programmatically**. The [`build/check-themes.js`](https://github.com/Nutlope/hallmark/blob/main/build/check-themes.js) script validates the `THEMES` object before any build completes:

```javascript
// build/check-themes.js — uniqueness validation
function validateThemeDiversification(themes) {
  const combos = new Set();
  
  for (const [key, theme] of Object.entries(themes)) {
    const combo = `${theme.bandStyle}:${theme.accentHue}`;
    
    if (combos.has(combo)) {
      throw new Error(
        `Theme-diversification violation: "${key}" shares ` +
        `bandStyle="${theme.bandStyle}" and accentHue="${theme.accentHue}" ` +
        `with another theme. Each combination must be unique.`
      );
    }
    
    combos.add(combo);
  }
  
  console.log(`✓ ${combos.size} themes validated — all bandStyle+accentHue combinations unique`);
}

```

This prevents accidental duplication during theme development and maintains the integrity of Hallmark's visual catalog.

## Complete Example: Theme Declaration and Application

Here's a full workflow from theme definition to rendered output:

```javascript
// 1. Define a new theme with unique combination
THEMES.forest = {
  title: "Forest",
  bandStyle: "solid",        // note: "solid" used here, but with unique accent
  accentHue: "emerald",      // unique combo: solid + emerald
};

// 2. User selects theme — swapArchetypes called
swapArchetypes("forest");

// 3. HTML reflects the data attributes
<body data-band-style="solid" data-accent-hue="emerald">
  <header class="paper-band"></header>
  <button class="accent-button">Action</button>
</body>

// 4. CSS renders distinct visual identity
//    - Solid green band at top
//    - Emerald buttons and links

```

## Key Files in the Theme-Diversification System

| File | Purpose |
|------|---------|
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Theme registry (`THEMES`), runtime application via `swapArchetypes` |
| [`build/check-themes.js`](https://github.com/Nutlope/hallmark/blob/main/build/check-themes.js) | Build-time validation ensuring unique `bandStyle` + `accentHue` pairs |
| [`site/css/theme.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/theme.css) | Visual mappings for paper-band styles and accent hues |
| `site/examples/*/index.html` | Live demonstrations of each theme combination |

## Summary

- Hallmark's **theme-diversification rule** mandates that each theme possess a unique pairing of **paper-band display style** and **accent hue**
- The rule is implemented through the `THEMES` object in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), applied via `swapArchetypes`, and enforced by [`build/check-themes.js`](https://github.com/Nutlope/hallmark/blob/main/build/check-themes.js)
- **Paper-band styles** (`solid`, `striped`, `dotted`) control the header band's visual pattern
- **Accent hues** provide interactive color identity through CSS custom properties
- This architecture enables dozens of distinct visual themes from a single, maintainable component codebase

## Frequently Asked Questions

### What happens if two themes share the same band style and accent hue?

The build fails. The `validateThemeDiversification` function in [`build/check-themes.js`](https://github.com/Nutlope/hallmark/blob/main/build/check-themes.js) throws an error with a descriptive message identifying the conflicting themes and their duplicate combination.

### Can I add new paper-band display styles?

Yes. Add a new `bandStyle` value to a theme definition, then create corresponding CSS rules in [`site/css/theme.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/theme.css) targeting `[data-band-style="your-new-style"]`. The validation script accepts any string value—no hardcoded list restricts creativity.

### How many unique theme combinations are possible?

With **3 band styles** and **6 accent hues** in the current palette, you get **18 guaranteed-unique combinations**. Expanding either dimension multiplies the design space; the validation script scales linearly with theme count.

### Where is the accent hue used beyond buttons and links?

Accent hues propagate to focus rings, selection highlights, progress indicators, and active states throughout the component system—all controlled by the CSS custom properties defined in [`theme.css`](https://github.com/Nutlope/hallmark/blob/main/theme.css).