Nutlope/hallmark Repository Structure Overview: Architecture and Implementation Guide

The Nutlope/hallmark repository is a static, theme-driven showcase site that generates 20 distinct visual themes across 21 macro-structures using a client-side JavaScript engine with no build step.

Hallmark serves as a design-skill framework for Claude Code, Cursor, and Codex, demonstrating how to build landing pages that vary in both visual style and structural layout. The entire application runs client-side without a compilation step, persisting user preferences in localStorage and supporting URL-based theme overrides.

Core Architecture Components

The repository follows a modular architecture centered around dynamic template injection and runtime theme resolution.

HTML Skeleton

The entry point site/index.html provides the foundational markup containing <slot> placeholders for hero and footer content, plus a banner UI for theme controls. This skeleton remains constant while JavaScript populates it dynamically at runtime.

Theme Registry

In site/js/main.js, the THEMES object defines the catalog of 20 available themes, while ARCHETYPES maps each theme to structural configurations (hero type + footer type). The THEME_GENRES object applies genre overlays, and the COPY object stores per-theme text strings including eyebrow text, ledes, and quotes.

Archetype Swapping System

The swapArchetypes() function in site/js/main.js (lines 74-96) handles structural variation by cloning elements from <template> fragments (such as #hero-marquee or #footer-colophon) into the DOM slots. This function interpolates {{key}} placeholders using the selected theme's COPY values, ensuring each theme generates a distinct page skeleton rather than simple color swaps.

Template Library

Raw component templates reside in site/_tests/ as Markdown files (e.g., components/h1-marquee.md). These 57+ component "cookbook" entries provide the markup that swapArchetypes() clones and injects into the active document.

How Themes and Archetypes Work

The theme application follows a deterministic resolution chain:

1. Initial Selection – On page load, the script checks for a ?theme= query parameter, falls back to localStorage (hallmark-theme), or defaults to the hum theme.
2. applyTheme(theme) – Updates document.documentElement.dataset.theme, persists the choice to localStorage, and triggers swapArchetypes(theme).
3. Structural Rebuild – swapArchetypes() looks up ARCHETYPES[theme] to determine the hero and footer types, retrieves the corresponding <template> elements, interpolates copy values, and injects the result into data-slot="hero" and data-slot="footer" containers.
4. UI Synchronization – The banner updates to display the current theme name, genre classification, and ordinal position among the 20 available themes.

Key Implementation Details

Stateful UI and Persistence

The interactive banner controls (theme picker, shuffle button, T-key tooltip, and Easter-egg overlay) are wired in site/js/main.js (lines 120-250). User interactions trigger localStorage updates for hallmark-theme and hallmark-t-tooltip-seen, enabling progressive enhancement and session persistence.

Data-Driven Copy System

Each theme maintains its own voice through the COPY object definitions (lines 31-121 in main.js). These objects contain standardized fields—eyebrow, title, lede, quote—that interpolate() merges into template placeholders, guaranteeing thematic consistency while allowing textual variation.

GitHub Star Badge Integration

A lightweight async routine fetches the repository's star count from the GitHub API with TTL-based caching in localStorage. This pattern (implemented in main.js lines 80-88) demonstrates non-blocking data fetching with automatic cache invalidation after one hour.

Practical Code Examples

Selecting a Theme Programmatically

import { applyTheme } from "./site/js/main.js";

// Switch to the "cobalt" theme
applyTheme("cobalt");

See the applyTheme implementation at lines 54-66 in site/js/main.js.

Adding a New Theme

// Extend the registry in site/js/main.js
THEMES.bonsai = "Bonsai";
ARCHETYPES.bonsai = { hero: "marquee", footer: "colophon" };
THEME_GENRES.bonsai = "playful";

COPY.bonsai = {
  eyebrow: "Bonsai Theme",
  title: HERO_TITLE,
  lede: "A fresh, nature-inspired design with tight spacing and organic colour accents.",
  // ...additional copy fields
};

After registry updates, access the theme via the banner dropdown or ?theme=bonsai.

Using the Copy-to-Clipboard Helper

<pre data-copy-source>
  <code data-copy-text>npm install hallmark</code>
  <button data-copy-btn>Copy</button>
</pre>

The attachCopyButtons() function auto-initializes at load, binding click handlers that copy text to the clipboard and flash a "copied" state. Implementation details are available in site/js/main.js lines 100-110.

Fetching the GitHub Star Count

fetch(`https://api.github.com/repos/nutlope/hallmark`, {
  headers: { Accept: "application/vnd.github+json" }
})
  .then(r => r.ok ? r.json() : null)
  .then(d => {
    if (d) document.querySelector("[data-star-count]").textContent = d.stargazers_count;
  });

The production implementation caches results for one hour in localStorage to minimize API calls.

Summary

• No build step required – All logic runs client-side via vanilla JavaScript in site/js/main.js.
• Template-driven architecture – swapArchetypes() rebuilds page structure by cloning <template> fragments from site/_tests/ instead of merely toggling CSS classes.
• Triple-tier theme resolution – URL query parameters override localStorage, which overrides the default hum theme.
• Data decoupling – Visual themes, structural archetypes, and copy content are stored in separate registry objects (THEMES, ARCHETYPES, COPY) enabling combinatorial variety.
• Skill integration – The skills/hallmark/ directory contains the Claude Code/Cursor/Codex skill definition and reference library for design patterns.

Frequently Asked Questions

How does the Nutlope/hallmark repository handle theme persistence?

The repository stores the active theme in localStorage under the key hallmark-theme. On initial load, applyTheme() checks for a URL query parameter ?theme= first, then falls back to the stored value, and finally defaults to the hum theme if neither exists.

What is the difference between a theme and an archetype in this codebase?

A theme defines the visual styling (colors, typography, spacing) and copy content, while an archetype defines the structural layout (hero type and footer type). The ARCHETYPES object in main.js maps each theme to specific hero and footer templates, enabling 420 possible combinations (20 themes × 21 macro-structures).

Where are the component templates stored in the Nutlope/hallmark repository?

Component templates reside in site/_tests/ as Markdown files (e.g., components/h1-marquee.md). These fragments are referenced as <template> elements in the DOM and cloned by swapArchetypes() when switching themes.

Can I use the Hallmark skill with Claude Code or Cursor without the web interface?

Yes. The skills/hallmark/SKILL.md file defines the skill configuration for AI coding assistants, while the skills/hallmark/references/ directory contains markdown guides for macrostructures, genres, and component patterns. Install via npx skills add nutlope/hallmark to integrate the design rules into your editor.

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