architecture

Hallmark Backend Architecture Explained: How a Static‑First Skill Runs Without a Server

August 3, 2026 Nutlope/hallmark ↗

Hallmark has no traditional backend—it is a static‑site‑only architecture where all logic runs client‑side, with only a lightweight Python HTTP server for local development.

The Hallmark repository by Nutlope demonstrates a backend‑less approach to building AI‑assisted design tools. Rather than deploying servers, databases, or APIs, Hallmark ships as a collection of static HTML, CSS, and JavaScript files that AI coding assistants consume directly. This article breaks down every component of this architecture using the actual source files.

What "Backend Architecture" Means for Hallmark

In conventional web applications, the backend architecture includes application servers, databases, and API layers. Hallmark inverts this model entirely. According to the Nutlope/hallmark source code, the architecture consists of three distinct parts that all operate without server‑side execution:

  • Static assets pre‑generated for direct browser rendering
  • Skill metadata that informs AI agents how to invoke Hallmark
  • Local development server used only for previewing, not production

Component 1: Static Assets as the Foundation

All user‑facing content lives in the site/ directory as ordinary web files. The browser loads and executes these directly without any intermediate processing.

Asset Type Location Purpose
HTML entry point site/index.html Main landing page with theme configuration
Stylesheets site/css/* Design tokens and component styles
JavaScript site/js/main.js Client‑side interactivity
Examples site/examples/*/index.html Generated design showcases

The site/index.html file exemplifies this static approach:

<!doctype html>
<html lang="en" data-theme="hum">
  <head>
    <link rel="stylesheet" href="css/tokens.css?v=24" />
    <script src="js/main.js"></script>
  </head>
  <body>
    <!-- Content rendered directly by browser -->
  </body>
</html>

There is no templating engine, no server‑side rendering, and no dynamic route handling. The data-theme="hum" attribute on the <html> element is read by client‑side JavaScript in site/js/main.js to switch themes locally.

Component 2: Skill Metadata in package.json

Hallmark's integration with AI coding assistants depends entirely on declarative metadata. The package.json file contains a "skill" section that specifies how agents should load and execute Hallmark:

{
  "name": "hallmark",
  "version": "1.1.0",
  "type": "module",
  "files": ["skills"],
  "skill": {
    "entry": "skills/hallmark/SKILL.md",
    "references": "skills/hallmark/references",
    "harnesses": ["claude-code", "cursor", "codex"]
  }
}

This metadata serves three functions:

  • entry: Points to skills/hallmark/SKILL.md, the Markdown file containing design rules and prompt templates
  • references: Indicates the directory with additional reference materials for the AI
  • harnesses: Declares which AI tools can invoke this skill (Claude Code, Cursor, and Codex)

No runtime code executes when an AI assistant "runs" Hallmark. The assistant reads the Markdown skill definition, applies the design rules, and generates new static files that follow Hallmark's conventions.

Component 3: Local Development Server

The only server‑like component is a development convenience, not a production requirement. As defined in package.json:

{
  "scripts": {
    "serve": "python3 -m http.server --directory site 4173"
  }
}

Running npm run serve executes Python's built‑in HTTP server to serve the site/ directory on port 4173. This server:

  • Has zero custom logic—it only serves static files
  • Is not used in production deployments
  • Can be replaced by any static hosting service (Vercel, Netlify, GitHub Pages)

Client‑Side Logic Implementation

All application behavior runs in the browser. The site/js/main.js file handles interactions like theme selection without server communication:

document.addEventListener('DOMContentLoaded', () => {
  const themeTrigger = document.querySelector('[data-theme-trigger]');
  themeTrigger.addEventListener('click', () => {
    // UI logic only; no server calls
    // Toggles data-theme attribute and updates CSS custom properties
  });
});

Similarly, example pages under site/examples/ contain self‑contained scripts. For instance, site/examples/riso-01/script.js powers presentation slides entirely through DOM manipulation.

How AI Assistants Use This Architecture

When an AI coding assistant invokes Hallmark, the process follows this static‑first flow:

  1. Read: The agent loads skills/hallmark/SKILL.md and parses the design system rules
  2. Apply: Using the rules, the agent generates new HTML, CSS, and JavaScript files
  3. Output: The generated files are written to a location where they can be served statically

The "backend" of this process is the AI assistant's own infrastructure—not Hallmark's. Hallmark merely provides the specification and reference implementations.

Key Architectural Characteristics

  • Zero server dependencies: No Node.js runtime, no database, no API gateway required for production
  • CDN‑deployable: Static files can be cached and distributed globally without application‑layer configuration
  • Version‑controlled design: The SKILL.md file and references/ directory capture the design system in plain text, enabling git‑based versioning and collaboration
  • Harness portability: The same skill definition works across multiple AI tools without code changes

File Reference Summary

File Role in Architecture
package.json Declares skill metadata and development scripts
skills/hallmark/SKILL.md AI‑readable specification for design rule application
site/index.html Static entry point for browser rendering
site/css/tokens.css Centralized design tokens (colors, spacing, typography)
site/js/main.js Client‑side theme switching and UI logic
site/examples/*/index.html Self‑contained generated design demonstrations

Summary

  • Hallmark operates as a static‑only architecture with no production backend services
  • The package.json skill metadata enables AI assistant integration without runtime code
  • A Python HTTP server (python3 -m http.server) provides local previewing only
  • All logic executes client‑side in JavaScript loaded by static HTML files
  • AI assistants consume the Markdown skill definition to generate new static files, not to execute server functions

Frequently Asked Questions

Does Hallmark require a backend server for production?

No. Hallmark ships as static HTML, CSS, and JavaScript files that can be deployed to any static hosting service. The npm run serve command launches a Python HTTP server solely for local development and testing.

How do AI coding assistants "run" Hallmark without a backend API?

AI assistants read the declarative skill definition in skills/hallmark/SKILL.md and apply the embedded design rules to generate new files. There is no API call—just file reading and content generation based on the specification.

What is the purpose of the "harnesses" field in package.json?

The harnesses array declares which AI tools can invoke Hallmark: claude-code, cursor, and codex. This metadata allows compatible agents to discover and load the skill automatically.

Can Hallmark handle dynamic data or user authentication?

Not in its current form. Hallmark is designed for static design system application. Dynamic functionality would require extending the architecture with external services or client‑side integration with serverless APIs.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →