# Nutlope/hallmark Repository Structure Overview: Architecture and Implementation Guide

> Explore the Nutlope/hallmark repository structure. Discover how this static, theme-driven site generates 20 visual themes with a client-side JavaScript engine and no build step for efficient implementation.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-07-14

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/main.js) lines 80-88) demonstrates non-blocking data fetching with automatic cache invalidation after one hour.

## Practical Code Examples

### Selecting a Theme Programmatically

```javascript
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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).*

### Adding a New Theme

```javascript
// 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

```html
<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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) lines 100-110.

### Fetching the GitHub Star Count

```javascript
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.