How Hallmark Enforces Token Discipline and Prevents Mid‑Render Improvisation

Hallmark guarantees design consistency by refusing inline color or font declarations once a theme is selected, requiring every visual value to reference a named token defined in tokens.css, then validates this contract through automated post‑emit testing.

The Hallmark project (Nutlope/hallmark) is a code‑generation skill that produces styled web pages. To eliminate the drift caused by ad‑hoc design decisions, the system enforces token discipline through a closed‑loop validation pipeline that treats the token block as the single source of truth.

The Three Mechanisms Behind Token Discipline

Hallmark’s enforcement relies on three tightly‑coupled components defined in the skill’s reference files.

Locked‑Tokens Rule in SKILL.md

At lines 50‑51 of [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the skill defines a hard constraint: once a theme is locked at step 2.6 of the design flow, the system refuses to emit any inline color or font declaration. If a required value does not exist in the token set, the model must define a new custom property (e.g., --color‑accent‑warm) in the token file rather than inserting a raw value like #5b6cff or font‑family: "Some Font".

Slop‑Test Gate 48 Validation

After page generation, the automatic slop‑test executes gate 48, defined at lines 156‑162 of [skills/hallmark/references/slop-test.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). This gate scans the emitted CSS for any raw color or font values. If detected, the build fails immediately, returning a diagnostic that forces the model to lift the value into tokens.css and replace the inline usage with var(--token‑name), ensuring the final artifact contains zero raw values.

Anti‑Pattern Reference Documentation

Human‑readable guidance for both developers and the model resides in skills/hallmark/references/anti‑patterns.md at lines 233‑240. This entry explicitly defines “Mid‑render token improvisation,” explains why it erodes visual cohesion, and prescribes the exact fix: migrate the value to the token block and reference it via CSS custom properties.

How Token Discipline Works in Practice

The enforcement pipeline follows a strict four‑phase workflow:

1. Theme Selection and Locking. At step 2.6 of the design flow, Hallmark locks the chosen theme (catalog or custom). From this point forward, the token block in site/css/tokens.css becomes the immutable source of truth for all visual values.

2. Token Reference. Every CSS rule must consume design values through CSS custom properties. Instead of declaring background‑color: #ff0000, the code emits background‑color: var(--color‑accent), where --color‑accent is defined in the token file.

3. Missing Token Handling. When a rule requires a value absent from the current token set, Hallmark appends a new custom property to tokens.css (e.g., --font‑display: "Instrument Serif", serif) and updates the rule to reference var(--font‑display).

4. Post‑Emit Validation. The slop‑test runs gate 48 against the generated CSS. If any raw hex codes, RGB functions, or inline font families remain, the validation fails, triggering a rewrite that moves the offending values into the token block and updates the references accordingly.

Correct vs. Incorrect Token Usage

Because the token block is the only place where color and font values are permitted, Hallmark‑generated CSS remains portable and consistent across the entire project.

Correct Usage (Token Reference)

/* site/css/tokens.css */
:root {
  --color-accent: oklch(62% 0.12 250);
  --font-display: "Instrument Serif", serif;
}

/* page.css – consumes the tokens */
.hero {
  background-color: var(--color-accent);
  font-family: var(--font-display);
}

Incorrect Usage (Mid‑Render Improvisation)

The following patterns trigger a gate 48 failure because they bypass the token block:

/* ❌ inline values – cause gate 48 failure */
.hero {
  background-color: #5b6cff;          /* raw hex */
  font-family: "Some Font", sans-serif; /* bypasses token block */
}

Fixing Improvisation

To resolve a slop‑test failure, lift the raw value into the token file and reference the custom property:

/* Add the missing token to tokens.css */
:root {
  --color-accent-warm: oklch(70% 0.15 30);
}

/* Update the rule to use the token */
.hero {
  background-color: var(--color-accent-warm);
}

Summary

• Hallmark enforces token discipline by locking the token block at step 2.6 and refusing inline color or font declarations thereafter.
• Gate 48 of the slop‑test programmatically validates that no raw values exist in the final CSS, failing the build if any are found.
• Missing values must be added to site/css/tokens.css (or tokens.css in the project root) as custom properties before they can be referenced.
• Anti‑pattern documentation at skills/hallmark/references/anti‑patterns.md provides the rationale and remediation steps for mid‑render improvisation.
• The result is portable, consistent styling where every visual value originates from a centralized, version‑controlled token file.

Frequently Asked Questions

What happens if the model tries to use a raw hex code in Hallmark?

The slop‑test gate 48 scan detects the raw value (such as #5b6cff or rgb(255, 0, 0)) in the emitted CSS and fails the build. The model receives a diagnostic pointing to the offending line and must refactor the code to define a token in tokens.css and reference it via var(--token‑name).

Where are design tokens stored in a Hallmark project?

Canonical tokens reside in site/css/tokens.css (or a tokens.css file in the project root). This file defines CSS custom properties like --color-accent and --font-display, which serve as the single source of truth for all generated pages.

Can I add new tokens during the generation process?

Yes. If the locked theme lacks a required value, Hallmark adds a new custom property to the token block (e.g., --color-accent-warm) before referencing it in the page CSS. This workflow prevents improvisation while allowing extensibility.

Why does Hallmark call this "mid‑render improvisation"?

The term refers to the anti‑pattern where a model emits raw color or font values in the middle of generating a page rather than using predefined tokens. According to skills/hallmark/references/anti‑patterns.md, this practice erodes design cohesion and creates maintenance debt, which is why the skill explicitly blocks it through the locked‑tokens rule and automated validation.

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