How Hallmark Macrostructure Variation Knobs Work: Bento Tiles, Spans, and Accent Controls

Hallmark’s macrostructure variation knobs let you adjust visual rhythm—such as tile spans, accent colors, and block counts—without changing the underlying layout pattern, by baking CSS classes and custom properties into the generated HTML.

The open-source Hallmark project (Nutlope/hallmark) generates marketing pages using predefined macrostructures—high-level layout patterns like Bento Grid, Stat-Led, or Quote-Led. Within each macrostructure, variation knobs serve as tunable parameters that modify density, emphasis, and animation. These knobs are defined in the repository’s reference files and applied at generation time, producing distinct visual outputs from a single structural template.

What Are Hallmark Macrostructure Variation Knobs?

Macrostructure variation knobs are declarative controls that alter the rendered output of a Hallmark page without changing its core layout family. According to the source code in skills/hallmark/SKILL.md, these knobs map brief requirements—such as "many features" or "high contrast"—to specific HTML class injections and CSS variable assignments.

When the Hallmark CLI processes a brief, it selects a macrostructure, then adjusts the knobs to match intent. The knobs are baked into the generated HTML/CSS; they are not runtime parameters that users manually tweak in the browser.

Core Variation Knobs Explained

Tile Spans (Bento Grid)

The tile spans knob controls the width and height of individual grid cells in a Bento Grid layout. Valid span values include 1x1, 2x1, 1x2, and 2x2, creating irregular, eye-catching patterns instead of uniform grids.

In skills/hallmark/references/macrostructures/01-bento-grid.md, these spans are implemented via CSS utility classes. HTML elements receive classes like span-2x2 or span-1x1, which the layout CSS reads to size cells using grid-area declarations.

<article class="cell span-2x2">…</article>
<article class="cell span-2x1 accent">…</article>

Accent Color

The accent knob applies a highlight hue to selected blocks, such as a call-to-action tile or featured image. This adds contrast and draws focus while maintaining the macrostructure’s rhythm.

The macrostructure adds a CSS custom property (e.g., --accent) that receives one of twenty palette colors. Blocks opt-in via a class such as accent or a data attribute. The runtime script in site/js/main.js injects the chosen value into the CSS variable.

.cell.accent { background:var(--accent); }

Number of Blocks

This knob determines how many items the grid contains, typically ranging from 8 to 15 blocks. Higher values increase visual density, while fewer blocks create a sparser, more minimalist feel.

The Hallmark generator populates the <section class="bento"> container with a variable-length loop, respecting the brief’s "many small things" cue or similar density indicators.

Reveal Effects and Divider Gaps

Reveal effects control entry animations for tiles (none, fade-in, or slide), applied via classes like reveal-fade. Divider gaps manage horizontal and vertical spacing between tiles (12–24px), defined as CSS variables on the .bento container.

.bento { display:grid; gap:var(--gap, 16px); }
.reveal-fade { animation: fadeIn 0.4s ease-out; }

How Knobs Are Applied in the Code

The transformation from brief to rendered page occurs through a pipeline defined in the codebase. The generator reads the macrostructure spec, applies the knob values, and outputs concrete HTML with mapped CSS classes.

Here is a complete example showing multiple knobs active simultaneously:

<header class="hero-fixed">…</header>

<section class="bento">
  <article class="cell span-2x2">…</article>
  <article class="cell span-1x1">…</article>
  <article class="cell span-2x1 accent">…</article>
  <article class="cell span-1x2 reveal-fade">…</article>
</section>

/* Span helpers */
.span-1x1 { grid-area: span 1 / span 1; }
.span-2x1 { grid-area: span 1 / span 2; }
.span-1x2 { grid-area: span 2 / span 1; }
.span-2x2 { grid-area: span 2 / span 2; }

/* Accent and gap variables */
.cell.accent { background:var(--accent); }
.bento { gap:var(--gap, 16px); }

Key Implementation Files

Understanding the knob system requires examining these specific source files:

• skills/hallmark/references/macrostructures/01-bento-grid.md – Defines the Bento Grid structure and enumerates available knobs including spans, accent, block count, and reveal effects.
• skills/hallmark/SKILL.md – The master rule-set that maps macrostructures to HTML/CSS templates and exposes variation knobs to the Hallmark CLI.
• site/js/main.js – Runtime script that injects the chosen macrostructure and applies knob values such as --accent and --gap.
• site/_tests/verbs/redesign/output.html – Example output demonstrating macrostructure comments with knob settings (e.g., "macrostructure: Workbench · knobs: pinned=right, content=feature-card").

Summary

• Hallmark macrostructure variation knobs tune visual output without changing the core layout pattern.
• Tile spans use classes like span-2x2 to create irregular Bento Grid layouts.
• Accent colors inject via CSS custom properties (--accent) controlled by opt-in classes.
• Block counts, reveal effects, and gap spacing are adjusted at generation time based on brief requirements.
• Knobs are defined in reference Markdown files and applied by the CLI, baking the final values into static HTML/CSS.

Frequently Asked Questions

How do tile spans affect the Bento Grid layout?

Tile spans determine the grid footprint of each cell using CSS grid-area values. Classes like span-2x1 or span-2x2 create asymmetric patterns that break uniform grid monotony, allowing featured content to occupy larger visual areas while standard content fills single units.

Can I change the accent color after the page is generated?

No. The accent color is baked into the generated CSS at build time via the --accent custom property. While you could override it manually in the browser, the Hallmark system treats knobs as generation-time parameters, not runtime user preferences.

What is the difference between a macrostructure and a variation knob?

A macrostructure is the high-level layout family (e.g., Bento Grid, Stat-Led) that defines the overall page architecture. A variation knob is a tunable parameter within that structure—such as span size or accent application—that modifies visual rhythm without altering the underlying structural framework.

Where are the knob definitions stored in the repository?

Knob definitions are stored in skills/hallmark/references/macrostructures/01-bento-grid.md for the Bento layout and orchestrated through skills/hallmark/SKILL.md, which maps these definitions to the CLI generation logic and HTML templates.

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