# How to Contribute to the Hallmark AI Project: A Complete Developer Guide

> Contribute to the Hallmark AI project by adding themes, UI components, or tooling. Explore the Nutlope/hallmark repo and enhance this AI tool today.

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

---

**You can contribute to the Hallmark AI project by adding new themes or macro-structures to the reference library, extending the demo site's UI components, or improving tooling—each requiring targeted edits to files in `skills/hallmark/references/` or the `site/` directory.**

Hallmark is a design skill for Claude Code, Cursor, and Codex that injects disciplined UI-generation rules into AI-assisted development. Contributing to this open-source project involves working within one of three architectural pillars: the **skill definition**, the **reference library**, or the **demo site**. Whether you are implementing a new visual theme with custom CSS tokens or refining the 57-gate slop-test validation, your changes will follow the repository's lazy-load strategy and diversification rules.

## Understanding the Hallmark Architecture

The repository is organized around three distinct pillars that handle different aspects of the design skill.

### The Skill Definition Layer

At the root of the skill sits [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), a front-matter-less markdown file that host platforms read to discover the skill's name, version, and entry point. This file defines three core verbs—`audit`, `redesign`, and `study`—and points to the `references/` directory where all rule-sets live. According to the source code, the skill metadata and high-level workflow description reside in the first five lines of this file.

### The Reference Library

The `skills/hallmark/references/` directory contains a curated library of markdown files encoding macro-structures, themes, genres, anti-patterns, and the slop-test gates. The skill employs a **lazy-load** strategy: it only reads the minimal files required for a given run. The hierarchy loads in this order:

- **Genres** (`genres/`) – High-level voice definitions (editorial, modern-minimal, atmospheric, playful)
- **Themes** (`themes/`) – 20 catalog themes mapped to genres via the `THEME_GENRES` object
- **Macro-structures** (`macrostructures/`) – 21 named page shapes loaded from [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)
- **Component archetypes** (`components/`) – Navs, footers, heroes, and other UI primitives

Non-essential files like [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) are imported only after HTML/CSS output generation to minimize token usage.

### The Demo Site

The `site/` directory contains a static HTML/CSS/JS showcase demonstrating every theme and macro-structure combination. Key implementation details include:

- **HTML** – [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) contains `<template>` elements (e.g., `<template id="hero-marquee">`) cloned by JavaScript at runtime
- **CSS** – [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) defines custom properties for each theme's paper band, accent hue, and display style
- **JavaScript** – [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) handles theme cycling, archetype swapping via `swapArchetypes()`, and keyboard shortcuts (`t` for next theme, `r` for random)

The site also enforces **diversification rules**: new builds must select a macro-structure different from the last three entries (tracked in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)) and a theme differing on at least one of three axes (paper band, display style, accent hue).

## Contribution Pathways

When you contribute to the Hallmark AI project, you typically focus on one of these three areas:

- **Add or refine references** – Create new macro-structures, themes, or genres under `skills/hallmark/references/`
- **Extend the demo site** – Add UI components, accessibility fixes, or visual polish to `site/`
- **Improve tooling** – Enhance scripts, documentation, or CI configuration

## Step-by-Step Implementation Guides

### Adding a New Theme

To add a theme like "nebula," you must update the JavaScript registry, CSS tokens, and optionally create HTML templates.

First, register the theme in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) around line 42:

```javascript
// Add to the THEMES map
nebula: "Nebula",

```

Map it to a genre around line 94:

```javascript
// In THEME_GENRES
nebula: "atmospheric",

```

Define the visual tokens in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css):

```css
[data-theme="nebula"] {
  --color-paper: oklch(15% 0.04 210);
  --color-accent: oklch(60% 0.18 210);
  --font-display: "Inter", system-ui;
  --font-body: "Inter", system-ui;
}

```

Add copy fixtures inside the `COPY` object in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js):

```javascript
nebula: {
  eyebrow: "Cosmic UI",
  title: HERO_TITLE,
  lede: "A dark‑skin theme for data‑intensive dashboards. Cool cyan accent, deep‑space paper.",
},

```

Optionally create a hero template in [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html):

```html
<template id="hero-nebula">
  <section class="hero">
    <h1>{{title}}</h1>
    <p>{{lede}}</p>
  </section>
</template>

```

Finally, register the archetype mapping in the `ARCHETYPES` object:

```javascript
nebula: { hero: "nebula", footer: "colophon" },

```

### Adding a New Macro-Structure

Create a markdown file in `references/macrostructures/` following the naming convention:

```markdown
---
macrostructure: Grid Carousel
---
/* Hallmark · macrostructure: Grid Carousel */

```

The skill automatically discovers this file through the index in [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) when the macro-structure is selected during a build.

### Updating Site Interactions

To extend the copy-to-clipboard logic for new element types (e.g., `<code>` blocks), modify the `attachCopyButtons` function in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) around line 44:

```javascript
function attachCopyButtons(scope = document) {
  // Existing logic …
  const codeSources = scope.querySelectorAll("code[data-copy-source]:not([data-copy-bound])");
  codeSources.forEach(source => {
    source.dataset.copyBound = "true";
    source.addEventListener("click", () => copyFromSource(source));
  });
}

```

## Critical Files for Contributors

| Path | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core skill metadata, entry point, and workflow description |
| `skills/hallmark/references/` | Library of markdown files for genres, themes, macro-structures, and the 57-gate slop-test |
| [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Static HTML skeleton with `<template>` elements for runtime cloning |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | CSS custom properties defining paper color, accent hue, and font tokens per theme |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Client-side logic including `applyTheme()`, `swapArchetypes()`, and diversification tracking |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) | Runtime log tracking previous macro-structures and themes for diversification rules |

## Local Development Workflow

1. Fork the repository and clone your fork locally
2. Create a feature branch: `git checkout -b feat/your-feature`
3. Make your changes to the relevant pillar (references, site, or tooling)
4. Run the demo locally using `npm run serve` (uses a simple Python HTTP server)
5. Verify diversification by cycling themes and ensuring your changes respect the slop-test rules in [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md)
6. Commit your changes and open a Pull Request with clear descriptions and screenshots

## Summary

- Hallmark consists of three pillars: the **skill definition** ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)), the **reference library** (`references/`), and the **demo site** (`site/`)
- The skill uses a **lazy-load** strategy to minimize token usage, loading only required reference files per run
- Contributions typically involve editing [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) for theme registries, [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for visual tokens, or `skills/hallmark/references/` for structural rules
- The **57-gate slop-test** and **diversification rules** (macro-structure and theme-axis variety) enforce quality and variety across builds
- No build step is required; the site runs as static HTML/CSS/JS served directly from the `site/` directory

## Frequently Asked Questions

### Do I need to run a build step to test changes?

No. The Hallmark demo site is pure HTML, CSS, and JavaScript. Running `npm run serve` simply starts a static file server. You can view your changes immediately by refreshing the browser after editing files in `site/` or `skills/hallmark/references/`.

### Where are the automated tests located?

The repository currently relies on manual visual tests located under `site/_tests/`. There is no automated test harness, so adding simple validation scripts or visual regression tests is a welcome contribution for future developers.

### Can I submit a new theme without creating a custom hero template?

Yes. If your theme reuses an existing hero archetype, you only need to add the token block to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), the copy fixture to the `COPY` object in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), and map it in the `THEMES` and `THEME_GENRES` registries. The existing template will render with your new theme's tokens.

### How does Hallmark prevent "invented metrics" in generated UI?

The slop-test gate 48, defined in [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md), specifically rejects hard-coded numerical values. Instead, the skill requires using placeholders (`—`) or labeled grey blocks to indicate spacing and sizing, ensuring the generated code follows disciplined token-based design rather than arbitrary pixel values.