# How Hallmark Code Generation Works: Client-Side Theme Assembly

> Discover how Hallmark generates landing pages client-side using theme registries archetype maps copy fixtures and a lightweight runtime engine for dynamic content.

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

---

**Hallmark generates landing pages entirely in the browser by combining declarative data structures—theme registries, archetype maps, and copy fixtures—with a lightweight runtime engine that clones HTML templates and interpolates dynamic content.**

Hallmark is an open-source project by **Nutlope** that demonstrates AI-driven page generation without server-side rendering. Unlike traditional static site generators that rely on build-time compilation, Hallmark code generation happens dynamically in the client through a sophisticated templating system that assembles pre-written component fragments based on user-selected themes.

## Declarative Data Structures Driving Generation

The Hallmark code generation system rests on three core data structures defined in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). These dictionaries map themes to structural components and textual content, enabling the runtime to construct distinct page layouts without hardcoding HTML.

### Theme Registry (`THEMES`)

The **`THEMES`** object enumerates all available themes, providing both human-readable names and lookup keys. Located at line 41 in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), this registry acts as the entry point for theme selection, translating user choices into archetype and copy lookups.

### Archetype Map (`ARCHETYPES`)

The **`ARCHETYPES`** object (line 70 in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)) maps each theme to a tuple of concrete component archetypes that fill specific page slots—such as `hero` and `footer`. This mapping drives structural variety, ensuring that switching themes changes the page layout, not just color schemes.

### Copy Fixtures (`COPY`)

The **`COPY`** object (line 35 in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)) holds per-theme textual content including eyebrow text, ledes, and CTA labels. While the hero title remains locked across themes for consistency, all other copy is theme-specific, allowing each generated page to maintain distinct voice and messaging.

## Template Slots and the Runtime Engine

Hallmark’s generation pipeline relies on static `<template>` elements embedded in [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) and a minimal JavaScript runtime that orchestrates DOM manipulation.

### HTML Template Slots

Each archetype corresponds to a `<template>` element in the HTML—such as `hero-marquee` or `footer-colophon`. These templates contain the pre-written markup for specific structural components. The runtime clones these templates rather than generating markup from scratch, ensuring valid, semantic HTML output.

### Core Runtime Functions

Three functions in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) handle the actual code generation:

**`interpolate(node, copy)`** – Walks a DOM subtree using `document.createTreeWalker`, replacing `{{key}}` placeholders with values from the copy object. This function performs the text substitution that personalizes generic templates with theme-specific content.

**`swapArchetypes(theme)`** – Retrieves the archetype tuple for the selected theme from `ARCHETYPES`, clones the matching `<template>` elements, runs `interpolate` on them to inject copy, and replaces the contents of designated DOM slots (e.g., `[data-slot="hero"]`).

**`applyTheme(theme)`** – The primary entry point that updates the document’s `data-theme` attribute, persists the selection to `localStorage` under the key `hallmark-theme`, triggers a view transition when `document.startViewTransition` is available, and invokes `swapArchetypes` to refresh the page structure.

## The Hallmark Code Generation Pipeline

When a user selects a theme—via the sticky banner, the "T" keyboard shortcut, or random shuffle—the following deterministic pipeline executes:

1. **Theme Activation** – `applyTheme(theme)` receives the chosen key and initiates the transition sequence.

2. **View Transition** – If the browser supports the View Transition API, Hallmark wraps the DOM update in `document.startViewTransition()`, creating smooth visual morphing between the old and new page structures.

3. **Archetype Swapping** – `swapArchetypes(theme)` looks up the archetype tuple (`ARCHETYPES[theme]`) and corresponding copy (`COPY[theme]`). It locates the appropriate `<template>` elements by ID (e.g., `hero-${tuple.hero}`), clones their content, and runs `interpolate` to replace placeholders like `{{eyebrow}}` or `{{lede}}` with actual text.

4. **Persistence and UI Sync** – The selected theme is stored in `localStorage`, and the banner UI updates to reflect the new theme name, genre, and ordinal, ensuring deterministic regeneration on future visits.

```javascript
// Programmatically switch to the "garden" theme
applyTheme('garden');   // → updates data-theme, swaps archetypes, persists to localStorage

```

```javascript
// How the runtime populates a hero slot
function swapArchetypes(theme) {
  const tuple = ARCHETYPES[theme] || ARCHETYPES.specimen;
  const copy  = COPY[theme] || COPY.specimen;

  const heroTpl = document.getElementById(`hero-${tuple.hero}`);
  const fragment = heroTpl.content.cloneNode(true);
  interpolate(fragment, copy);          // injects {{eyebrow}}, {{lede}}, etc.
  document.querySelector('[data-slot="hero"]').replaceChildren(fragment);
}

```

```javascript
// Placeholder interpolation implementation
function interpolate(node, copy) {
  const walker = document.createTreeWalker(node, NodeFilter.SHOW_TEXT);
  while (walker.nextNode()) {
    walker.currentNode.nodeValue = walker.currentNode.nodeValue.replace(
      /\{\{(\w+)\}\}/g,
      (_, key) => copy[key] ?? ''
    );
  }
}

```

## Client-Side Architecture Benefits

Hallmark’s approach to code generation eliminates the need for server-side build tools or external dependencies. As evidenced by [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), the project relies solely on standard browser APIs.

**Instant Theme Switching** – Because generation occurs client-side, theme changes happen in milliseconds without network requests or page reloads.

**Structural Variety** – Unlike CSS-only theme systems, Hallmark’s archetype mapping allows entirely different HTML structures per theme, enabling genuine layout diversity rather than superficial color swaps.

**Offline Capability** – With all templates and logic bundled in static assets, the generation system functions entirely offline after initial load, storing user preferences in `localStorage` for deterministic restoration.

## Summary

- Hallmark code generation operates entirely in the browser through a client-side templating system defined in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).
- Three declarative data structures—**`THEMES`**, **`ARCHETYPES`**, and **`COPY`**—control which components render and what content they display.
- The runtime engine uses **`interpolate`**, **`swapArchetypes`**, and **`applyTheme`** to clone HTML templates and inject dynamic content.
- Placeholder syntax (`{{key}}`) within `<template>` elements enables text substitution without innerHTML risks.
- Theme selections persist in **`localStorage`** under the key `hallmark-theme`, ensuring consistent regeneration across sessions.
- The View Transition API provides smooth visual transitions when swapping between structurally distinct themes.

## Frequently Asked Questions

### Does Hallmark use server-side rendering for code generation?

No. Hallmark generates all content client-side using JavaScript. The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) reveals no server-side dependencies, and the generation logic in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) executes entirely within the browser, cloning `<template>` elements and manipulating the DOM directly.

### How does Hallmark handle dynamic content interpolation?

Hallmark uses the **`interpolate(node, copy)`** function to perform text substitution. This function creates a TreeWalker to traverse text nodes within a cloned template, replacing placeholder patterns like `{{eyebrow}}` or `{{lede}}` with values from the `COPY` object corresponding to the active theme.

### Where are the theme definitions and component structures stored?

Theme mappings reside in **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)**, which exports the `THEMES`, `ARCHETYPES`, and `COPY` objects. The actual HTML structures for each archetype (such as `hero-marquee` or `footer-colophon`) are defined as `<template>` elements within **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)**, while design documentation lives in [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) and `skills/hallmark/references/genres/*.md`.

### Can Hallmark's code generation system work without an internet connection?

Yes. Once the initial assets load, Hallmark operates entirely offline. All templates, archetype definitions, and generation logic are bundled with the application. User theme preferences are stored in **`localStorage`**, allowing the page to regenerate consistently even without network connectivity.