How Hallmark Handles Designing Individual UI Components: The Component Archetype System

Hallmark treats every UI element as a reusable component archetype defined in a markdown-driven cookbook, then renders them into static HTML using CSS custom properties and genre-aware macrostructure matching.

Hallmark is an open-source design engine that solves the problem of designing individual UI components through a declarative, language-agnostic system. Instead of generating one-off markup, it organizes every interface piece into a catalog of archetypes stored in skills/hallmark/references/component-cookbook.md. This approach lets the hallmark redesign <target> CLI command assemble complete pages from modular, token-styled building blocks.

The Component Cookbook: Designing Individual UI Components as Archetypes

At the center of Hallmark's approach is the Component Cookbook (skills/hallmark/references/component-cookbook.md). This file enumerates more than 50 reusable archetypes grouped by semantic role:

• Hero sections – H1 through H9
• Feature blocks – F1 through F6
• Navigation styles – N1 through N13
• Footers – Ft1 through Ft8
• Tiny UI pieces – chips and links (C1 through C4, T1 through T4)

Each entry acts as a contract. It tells the build engine exactly which component to pull when the macrostructure calls for a specific pattern.

Anatomy of an Archetype Entry

Every archetype in the cookbook contains four elements:

1. A concise purpose – guidelines on when to use the component and what it replaces.
2. A "don't confuse with" note – a visual-semantic boundary check to prevent misuse.
3. A minimal markup sketch – plain HTML that describes the required DOM structure.
4. Variation knobs – lightweight CSS custom property overrides (for example, --space, --color, --radius) that let the same archetype adapt to different genres or brand tokens.

Because the definitions live in pure markdown, they remain language-agnostic. Any front-end stack—plain HTML, React, Vue, or Svelte—can consume them.

From Markdown to Static HTML: The Build Pipeline

When you invoke the CLI with hallmark redesign <target>, the Hallmark engine reads the target page's macrostructure. It then maps that structure to specific archetypes:

• Selects a navigation archetype from the cookbook's routing table (N1–N13).
• Selects a footer archetype (Ft1–Ft8).
• Pulls the required component archetypes for each content section (for example, an H1·Marquee hero, an F1·Bento grid feature block, or a C2·Inline form as CTA).

The engine renders these selections into static HTML and CSS files. The runtime glue in site/js/main.js injects the generated assets into the page, while site/index.html serves as the standard entry point for Hallmark-generated output.

Genre-Aware Selection

The macrostructure carries a genre tag—such as playful, modern-minimal, editorial, or atmospheric. This genre determines which navigation and footer archetypes are appropriate, preventing the "AI-default" sameness that plagues template-driven tools. As implemented in Nutlope/hallmark, this genre signal filters the archetype pool before any markup is generated.

Token-Driven Styling and Variation Knobs

Hallmark enforces a strict separation of concerns: markup lives in the component markdown files, layout decisions are driven by macrostructure files, and styling lives in token files. The skills/hallmark/references/design-md.md file (or a generated tokens.css) exposes design tokens as CSS custom properties on :root:

:root {
  --color-primary: #0f172a;
  --space-md: 1rem;
  --radius-sm: 0.375rem;
}

Individual components reference these tokens in their class definitions. Because the markup in skills/hallmark/references/components/h1-marquee.md, skills/hallmark/references/components/c2-inline-form-as-cta.md, and other archetype files uses these variables, a global theme change requires editing only the token file—never the component markdown.

Extensible Overrides

Each archetype exposes variation knobs through inline-ready CSS custom properties. Designers can tweak spacing, color, or sizing by passing overrides directly in the HTML style attribute. This avoids forking the core component definition.

Framework Integration and Optional Adapters

Although Hallmark's archetypes are pure markdown and HTML, the repository provides optional adapters for popular UI libraries such as shadcn/ui. The token names in skills/hallmark/references/design-md.md map to the library's expected CSS variable shapes, ensuring seamless integration when you do adopt a component framework.

Practical Examples for Designing Individual UI Components

The following snippets show how archetypes translate into rendered HTML. Each class name corresponds to its markdown definition file, and the inline style attribute demonstrates variation knobs.

H1 · Marquee Hero Component

Defined in skills/hallmark/references/components/h1-marquee.md:

<!-- Hallmark component: H1 · Marquee -->
<section class="h1-marquee" style="--space: var(--space-xl); --color-bg: var(--color-primary);">
  <h1 class="marquee-title">Your bold statement here</h1>
</section>

C2 · Inline Form as CTA

Defined in skills/hallmark/references/components/c2-inline-form-as-cta.md:

<!-- Hallmark component: C2 · Inline form as CTA -->
<form class="c2-inline-form" action="/subscribe" method="POST"
      style="--color-border: var(--color-accent); --space: var(--space-sm);">
  <label for="email">Stay updated</label>
  <input type="email" name="email" id="email" placeholder="you@example.com" required />
  <button type="submit">Submit →</button>
</form>

N5 · Floating Pill Navigation

Defined in skills/hallmark/references/components/n5-floating-pill.md:

<nav class="n5-floating-pill" style="--color-bg: var(--color-surface); --blur: 8px;">
  <a href="/" class="logo">Studio</a>
  <a href="/features">Features</a>
  <a href="/contact" class="cta">Contact</a>
</nav>

In each example, the inline style attribute overrides the default token values without altering the underlying archetype file.

Summary

• Hallmark stores all UI patterns as component archetypes inside skills/hallmark/references/component-cookbook.md, creating a declarative, language-agnostic catalogue.
• The hallmark redesign <target> CLI reads page macrostructure, matches it to archetypes by genre, and generates static HTML/CSS.
• Variation knobs—CSS custom property overrides—let designers customize spacing, color, and radius without forking component markdown.
• A token-driven layer in skills/hallmark/references/design-md.md (or tokens.css) centralizes theming so components remain consistent across a site.
• Optional adapters bridge Hallmark's token system to libraries like shadcn/ui for teams that want framework-specific components.

Frequently Asked Questions

How does Hallmark define individual UI components?

Hallmark defines individual UI components as archetypes inside a markdown-based Component Cookbook. Each archetype lives in a file such as skills/hallmark/references/components/h1-marquee.md and contains a purpose statement, a markup sketch, and variation knobs. This structure keeps components declarative and language-agnostic.

Can I customize a Hallmark component without editing its source markdown?

Yes. Every archetype exposes variation knobs through CSS custom properties such as --space, --color-bg, and --radius. You can override these values in the HTML style attribute or in the global tokens.css file generated from skills/hallmark/references/design-md.md. This lets you tweak a component's appearance without forking the underlying markdown definition.

What file does Hallmark use to store the master list of components?

The master list resides in skills/hallmark/references/component-cookbook.md. This file catalogs more than 50 archetypes—including hero sections, navigation bars, footers, and micro-elements—and maps them to the codes the build engine uses during the hallmark redesign <target> command.

Is Hallmark limited to plain HTML, or does it work with React and other frameworks?

Hallmark is framework-agnostic because its archetypes are pure markdown and HTML. However, the repository also provides optional adapters for libraries like shadcn/ui. The design tokens in skills/hallmark/references/design-md.md map to framework-specific CSS variable shapes, so you can consume Hallmark components in React, Vue, Svelte, or vanilla HTML.

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