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

> Learn how Hallmark's macrostructure variation knobs adjust visual rhythm using Bento tiles spans and accent controls without altering the layout pattern. Get started today.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.

```html
<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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) injects the chosen value into the CSS variable.

```css
.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.

```css
.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:

```html
<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>

```

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md) for the Bento layout and orchestrated through [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which maps these definitions to the CLI generation logic and HTML templates.