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

To contribute new themes to Hallmark, you must create a CSS token block in 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.

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 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, 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 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.

[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:

# 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 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 file contains the diversification rule that checks /.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:

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

This stamping logic is defined in the "Stamp the output" section of 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 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: 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: Core workflow file containing the catalog dispatch, diversification rules, and CSS stamping logic.
• /.hallmark/log.json: Auto-generated log of previous builds used to enforce theme diversification.
• 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 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 checks /.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.

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