# How Hallmark Handles Designing Individual UI Components: The Component Archetype System > Discover how Hallmark designs UI components using a reusable archetype system in markdown, rendering static HTML with CSS custom properties and genre-aware macrostructure. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-07-27 --- **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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md). This approach lets the `hallmark redesign ` 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`](https://github.com/Nutlope/hallmark/blob/main/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 `, 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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) injects the generated assets into the page, while [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) file (or a generated [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css)) exposes design tokens as CSS custom properties on `:root`: ```css :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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/components/h1-marquee.md), [`skills/hallmark/references/components/c2-inline-form-as-cta.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/components/h1-marquee.md): ```html

Your bold statement here

``` ### C2 · Inline Form as CTA Defined in [`skills/hallmark/references/components/c2-inline-form-as-cta.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/components/c2-inline-form-as-cta.md): ```html
``` ### N5 · Floating Pill Navigation Defined in [`skills/hallmark/references/components/n5-floating-pill.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/components/n5-floating-pill.md): ```html ``` 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md), creating a declarative, language-agnostic catalogue. - The `hallmark redesign ` 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) (or [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) file generated from [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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 ` 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`](https://github.com/Nutlope/hallmark/blob/main/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.