# How to Contribute New Themes to Hallmark: A Complete 5-Step Guide

> Learn how to contribute new themes to Hallmark with this easy 5-step guide. Follow our detailed instructions to add your custom themes to the Nutlope/hallmark repository.

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

---

**To contribute new themes to Hallmark, you must create a CSS token block in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), add a reference markdown file in `skills/hallmark/references/themes/`, and ensure the theme name is discoverable by the selection algorithm in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).**

Hallmark is an open-source design system that generates visual styles through a curated catalog of themes. If you want to contribute new themes to Hallmark, you need to understand how the repository organizes its token architecture, documentation standards, and skill flow logic. This guide walks through the exact file locations and validation steps required to submit a theme that integrates seamlessly with Hallmark's catalog.

## Understanding the Three-Pillar Architecture

Every Hallmark theme exists in three coordinated locations. The **CSS token definition** lives in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under a `[data-theme="<name>"]` selector, which declares the palette, paper, accent colors, and font stacks. The **theme reference documentation** resides in `skills/hallmark/references/themes/<name>.md`, describing visual language and anti-patterns. Finally, the **theme registration** occurs in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which contains the dispatch logic for the catalog and the diversification rule preventing consecutive builds from using identical themes.

## Step-by-Step Guide to Contributing a New Theme

### 1. Define CSS Tokens in tokens.css

Open [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and add a new `[data-theme="<your-theme>"]` block. Inside this selector, define the required custom properties that Hallmark components consume:

- `--color-paper`: The background paper tone (e.g., `oklch(95% 0.012 80)`)
- `--color-accent`: The primary accent color
- `--color-accent-ink`: The contrast-checked accent color for text
- `--font-display`, `--font-body`, `--font-mono`: Typography stacks
- Theme-specific tokens like `--radius-card` for unique corner treatments

Follow the pattern established by existing themes such as **Hum** or **Cobalt**. Ensure your values use OKLCH color notation for perceptual uniformity.

```css
[data-theme="mytheme"] {
  --color-paper: oklch(95% 0.012 80);
  --color-accent: oklch(55% 0.18 250);
  --color-accent-ink: oklch(95% 0.02 0); /* contrast-checked */
  --font-display: "Instrument Serif", serif;
  --font-body: "Inter", sans-serif;
  --radius-card: 20px;
}

```

### 2. Create Theme Reference Documentation

Create `skills/hallmark/references/themes/<your-theme>.md` to document the visual identity. This file must include a short overview of the palette mood and typography, a strict list of **anti-patterns** (what must never appear), and guidance on how your theme differs from neighbors like **Hum** or **Cobalt**.

Structure your reference file using this outline:

```markdown

# MyTheme

**Palette** – Warm amber primary, cool teal secondary.  
**Paper** – Soft cream `oklch(97% 0.012 95)`.  
**Typography** – Display uses *Instrument Serif*; body uses *Inter*.  

## Anti-patterns

- Never use pure white paper.  
- No serif anywhere except the display face.  
- No square corners on cards; radius must be ≥ 12 px.  

## How MyTheme differs from neighboring themes

- Compared to **Hum**, MyTheme uses a single-accent palette rather than multi-accent.  
- Compared to **Cobalt**, it is a light-theme with no dark band.

```

### 3. Update the Skill Flow Registration

While [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) maintains an implicit catalog of 21 named themes, your theme becomes discoverable once it has both a token block and a reference file. The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file contains the diversification rule that checks [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) to ensure two consecutive builds do not use the same theme unless the brief explicitly signals a repeat.

Ensure your generated CSS includes the required header stamp so the system can track theme usage:

```css
/* Hallmark · macrostructure: bento-grid · tone: playful · theme: mytheme */

```

This stamping logic is defined in the "Stamp the output" section of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

### 4. Add a Preview Example (Optional but Recommended)

Provide a minimal example page under `site/examples/<your-theme>-01/` with a [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) that imports your new theme's token block. This allows reviewers to see the theme in action and validates that your CSS works correctly with the Hallmark component library.

### 5. Validate Against the Slop-Test Suite

Hallmark enforces strict design system constraints through a suite of **58 slop-test gates**. Execute the tests using `npm test` (or the equivalent command) to check for unintended inline colors, missing `--color-accent-ink` definitions, or disallowed typography. Fix any failures before submitting your contribution.

## Key Files and Their Roles

- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)**: Central location for all theme token blocks using the `[data-theme="..."]` selector.
- **`skills/hallmark/references/themes/<theme>.md`**: Human-readable documentation including anti-patterns and visual differentiation.
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**: Core workflow file containing the catalog dispatch, diversification rules, and CSS stamping logic.
- **[`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json)**: Auto-generated log of previous builds used to enforce theme diversification.
- **[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)**: Specification for custom-theme branches when extending beyond the catalog.

## Summary

To successfully contribute new themes to Hallmark, follow these essential steps:

- Define all CSS custom properties in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under a scoped `[data-theme]` selector.
- Document anti-patterns and visual identity in `skills/hallmark/references/themes/<name>.md`.
- Ensure the theme name appears in the generated CSS stamp for diversification tracking.
- Pass the 58-gate slop-test suite to verify compliance with design system constraints.
- Provide an optional preview example in `site/examples/` to demonstrate real-world usage.

## Frequently Asked Questions

### What CSS custom properties are required for a new Hallmark theme?

Every theme must define `--color-paper`, `--color-accent`, and `--color-accent-ink` for the core color system, plus typography variables including `--font-display`, `--font-body`, and `--font-mono`. You should also declare any theme-specific radius or shadow tokens (like `--radius-card`) that differ from the default set.

### Where should I document the anti-patterns for my theme?

Anti-patterns belong in the reference markdown file located at `skills/hallmark/references/themes/<your-theme>.md`. This file must explicitly list what must never appear in the theme, such as forbidden colors or typography combinations, to prevent downstream misuse.

### How does Hallmark prevent the same theme from being used consecutively?

The diversification rule in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) checks [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) to see the previous build's theme. The system automatically rejects selecting the same theme twice in a row unless the brief explicitly signals a repeat, ensuring visual variety across generated outputs.

### What is the slop-test suite and why must my theme pass it?

The slop-test suite consists of 58 validation gates that check for design system violations like unintended inline colors, missing contrast-checked ink colors, or disallowed font stacks. Passing these tests ensures your theme maintains the strict quality standards required for the Hallmark catalog.