What Is Lock-the-System in Hallmark and How Is design.md Exported?

Hallmark’s lock-the-system flow is an opt-in mechanism that crystallizes the current build’s design tokens, genre, and theme into a portable design.md file, which subsequent builds automatically detect and consume as the single source of truth.

The lock-the-system workflow allows developers to convert ephemeral design decisions made during a Hallmark page build into a version-controlled, reusable system file. Unlike automatic exports, this flow requires explicit user intent and only operates at the page level, ensuring that mature design systems can be locked and shared across multiple pages in a project. According to the Hallmark source code, the entire process is governed by trigger phrases defined in SKILL.md and follows a strict no-overwrite policy when updating existing files.

Understanding the Lock-the-System Flow

When It Runs

The lock-the-system flow is never triggered automatically by Hallmark’s default verb. Instead, it activates only when the user explicitly requests it using specific trigger phrases such as:

• "lock the system"
• "give me a design.md"
• "make this portable"

These triggers are documented in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) under the "Opt-in design.md (lock-the-system flow)" section. Once detected, Hallmark initiates the export sequence immediately after the current build iteration completes.

Scope and Limitations

The flow applies exclusively to page-level builds. Component-level builds are explicitly skipped because a single component lacks the breadth required to represent a complete design system. As noted in the source documentation, attempting to lock the system on a component build will result in no action, preserving the integrity of the design system definition.

How design.md Is Generated and Exported

The Export Process

When the lock-the-system trigger fires, Hallmark performs the following sequence:

1. Loads the portable design system template from [skills/hallmark/references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md)
2. Gathers the in-memory token state from the current build, including CSS variables, genre classifications, and motion settings
3. Writes a design.md file at the project root

The template loaded from design-md.md (lines 47-98) provides the structural scaffolding that ensures consistency across all exported design systems.

The No-Overwrite Policy

If a design.md file already exists at the project root, Hallmark does not overwrite the entire file. Instead, it refreshes only the ## Exports section, preserving any manual amendments made to the System or Tokens sections. This safety mechanism prevents accidental destruction of intentional design tweaks while keeping downstream export formats synchronized.

Export Format and Structure

The exported design.md follows a strict markdown template containing five primary sections:

• System – Defines genre (e.g., editorial), macro-structure (e.g., Long Document), and theme catalog
• Tokens – Canonical CSS variables representing colors, typography, and spacing (sourced from tokens.css)
• CTA voice – The call-to-action tone established during the build
• Motion stance – Animation principles and timing functions
• Exports – Consumption methods for downstream tools such as Tailwind, DTCG, or shadcn/ui

The exact schema and available export options are detailed in [skills/hallmark/references/export-formats.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md).

Consuming the Locked System

After design.md is written, Hallmark’s pre-flight step automatically detects its presence on subsequent runs. When found, the system reads this file first, causing all future design picks—genre, theme, typography, and motion—to defer to the locked specifications rather than generating new ones. This creates a deterministic design pipeline where design.md acts as the rulebook for the entire project.

# 1️⃣ Build a page normally

hallmark build my-page.html

# 2️⃣ Trigger the lock-the-system flow explicitly

> lock the system

# Hallmark writes design.md at project root using the canonical template

# Design — MyProject

Locked design system. Future Hallmark runs read this file first; pages defer
to it. Amend intentionally — the file is the rule.

## System

- Genre · editorial
- Macrostructure · Long Document
- Theme · catalog: Editorial
- Axes · paper-band / display-style / accent-hue

## Tokens (canonical · `tokens.css` is the source of truth)

:root {
  --color-paper:      oklch(<L> <C> <H>);
  --color-ink:        oklch(<L> <C> <H>);
  /* …other variables… */
}

# 3️⃣ Subsequent builds automatically inherit the locked system

hallmark build another-page.html   # All picks now defer to design.md

Summary

• Lock-the-system is an opt-in Hallmark workflow that exports the current build’s design decisions to a portable design.md file.

• The flow triggers only on explicit user commands (e.g., "lock the system") and applies exclusively to page-level builds, not components.

• Hallmark loads the template from skills/hallmark/references/design-md.md and writes the file to the project root, refreshing only the ## Exports section if the file already exists.

• The exported file contains System definitions, canonical Tokens, CTA voice, Motion stance, and Export consumption methods.

• Once present, design.md is automatically detected by Hallmark’s pre-flight step and serves as the authoritative source for all subsequent builds.

Frequently Asked Questions

How do I trigger the lock-the-system flow in Hallmark?

You must explicitly request it using phrases such as "lock the system", "give me a design.md", or "make this portable" after a page build completes. The default Hallmark verb never exports design.md automatically, ensuring that design system creation remains an intentional, user-driven decision.

What happens if I already have a design.md file?

Hallmark implements a no-overwrite policy. If design.md exists, the system refreshes only the ## Exports section to update downstream consumption methods (Tailwind, DTCG, etc.) without touching your manual edits to the System or Tokens sections.

Can I lock the system for a single component?

No. The lock-the-system flow applies only to page-level builds. Component-level builds are too granular to represent a complete design system, so Hallmark skips the export entirely when working at the component scope.

What file does Hallmark read to understand the design.md format?

Hallmark loads the template and rules from skills/hallmark/references/design-md.md (specifically lines 47-98) to ensure the exported file follows the correct structure with sections for System, Tokens, CTA voice, Motion stance, and Exports.

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