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

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, 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
• Component archetypes (components/) – Navs, footers, heroes, and other UI primitives

Non-essential files like 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 contains <template> elements (e.g., <template id="hero-marquee">) cloned by JavaScript at runtime
• CSS – site/css/tokens.css defines custom properties for each theme's paper band, accent hue, and display style
• JavaScript – 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) 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 around line 42:

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

Map it to a genre around line 94:

// In THEME_GENRES
nebula: "atmospheric",

Define the visual tokens in site/css/tokens.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:

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:

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

Finally, register the archetype mapping in the ARCHETYPES object:

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

Adding a New Macro-Structure

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

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

The skill automatically discovers this file through the index in 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 around line 44:

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	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	Static HTML skeleton with <template> elements for runtime cloning
site/css/tokens.css	CSS custom properties defining paper color, accent hue, and font tokens per theme
site/js/main.js	Client-side logic including applyTheme(), swapArchetypes(), and diversification tracking
.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
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), 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 for theme registries, 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, the copy fixture to the COPY object in 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, 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.

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