What Is the Hallmark `design.md` Lock File and How Does It Invert the Diversification Rule?

design.md is an opt‑in, portable design‑system file that Hallmark generates when a user explicitly "locks" their design, forcing all subsequent pages to share a consistent system rather than vary across iterations.

In the Hallmark code repository (Nutlope/hallmark), the design.md lock file serves as a critical architectural mechanism for transitioning from exploratory design to enforced consistency. This article explains the lock file's structure, creation flow, and how it fundamentally reverses Hallmark's default behavior regarding theme diversification.

What Is the design.md Lock File?

The design.md file (also accepted as DESIGN.md) is a human-readable, version-controllable design specification that captures a complete design language in one place. Unlike automatic configuration files, it is created only through explicit user intent.

When Hallmark Creates the Lock File

Hallmark writes design.md only when the user triggers a "lock the system" intent. Common trigger phrases include:

• "lock the system"
• "give me a design.md"
• "export this as a design.md"

The default Hallmark verb never creates this file automatically. This mirrors how professional design teams freeze a style guide after completing iterative exploration.

As documented in skills/hallmark/SKILL.md and skills/hallmark/references/design-md.md, the lock-the-system flow is a conscious, irreversible step that signals design completion.

What design.md Contains

The lock file records the full design language in a stable, portable format:

Section	Contents
Palette	Paper backgrounds, accent hues, neutrals, semantic colors
Typography	Display and body font families, weights, scales
Motion	Easing curves, duration scales, transition patterns
Component choices	Button styles, card variants, input treatments
Exports	Tailwind @theme, DTCG tokens.json, shadcn/ui CSS variables

The Exports section enables downstream consumption by other tools and projects, making design.md a true cross-platform design contract.

How Hallmark Detects and Uses the Lock File

On every run, Hallmark performs a pre-flight scan defined in SKILL.md (step 0):

// Pseudo-logic matching the implementation in SKILL.md
if (fs.existsSync('design.md') || fs.existsSync('DESIGN.md')) {
  const design = parseDesignMD();        // Extract palette, typography, motion
  applyDesignSystem(design);             // All design picks defer to this spec
  enforceConsistency(design);            // Skip diversification, require sameness
} else {
  // Standard flow: catalog/custom dispatch with forced variation
  pickThemeViaDiversification();
}

When design.md is detected, Hallmark reads it as the single source of truth and bypasses the usual catalog/theme dispatch entirely.

Understanding the Diversification Rule

To grasp how design.md inverts behavior, you must first understand Hallmark's baseline diversification rule.

The Normal Flow: Enforced Variation

In standard operation, Hallmark enforces a diversification rule that requires two consecutive pages to differ on at least one of three axes:

1. Paper-band — background value and warmth
2. Display-style — typographic personality (geometric, humanist, etc.)
3. Accent-hue — primary color family

This rule, defined in SKILL.md § Theme-diversification rule, prevents "same-old-theme" drift and ensures visual variety across standalone pages.

How design.md Inverts the Rule

When a design.md lock file is present, the diversification rule is completely inverted:

Aspect	Without design.md	With design.md
Goal	Maximize variation	Enforce consistency
Constraint	Pages must differ	Pages must match
Check	Diversification validation	Consistency enforcement
Deviation handling	Encouraged if rule satisfied	Flagged as critical drift

As stated in SKILL.md (line 153) and reinforced in skills/hallmark/references/verbs/redesign.md (line 260), the locked system requires every page to conform to the recorded design language rather than explore alternatives.

Practical Example: Minimal design.md Structure

Here is the skeleton generated by the lock-the-system flow:

# design.md — opt-in portable design system

## Palette

paper: #f5f5f5
accent: #ff6f61

## Typography

display: "Atelier", 700
body: "Inter", 400

## Motion

ease: cubic-bezier(0.4, 0, 0.2, 1)

## Exports

### Tailwind @theme

@theme {
  --color-paper: #f5f5f5;
  --color-accent: #ff6f61;
}

### tokens.json

{
  "color": { "paper": "#f5f5f5", "accent": "#ff6f61" },
  "font": { "display": "Atelier", "body": "Inter" }
}

This format is fully specified in skills/hallmark/references/design-md.md § Format.

Auditing Against a Locked System

The hallmark audit verb also respects the inversion. Per skills/hallmark/references/verbs/audit.md:

• Without design.md: Audit flags minor variety drifts as suggestions
• With design.md: Any deviation from the locked spec is reported as critical design-system drift

This elevates design.md from documentation to enforceable contract.

Key Source Files

The following files in Nutlope/hallmark define the complete design.md behavior:

• skills/hallmark/references/design-md.md — Lock file format specification and lock-the-system flow
• skills/hallmark/SKILL.md — Core detection logic, diversification inversion, and workflow steps
• skills/hallmark/references/verbs/redesign.md — Multi-page flow that creates/updates design.md
• skills/hallmark/references/verbs/audit.md — Drift detection against locked specifications

Summary

• design.md is an opt-in, explicit lock file that captures a complete design system in portable, human-readable format
• Creation requires user intent — no automatic generation; triggered by "lock the system" or similar phrases
• Detection occurs at step 0 of every Hallmark run via pre-flight scan in SKILL.md
• The diversification rule inverts from "pages must differ" to "pages must match" when design.md is present
• Consistency enforcement replaces variation exploration, ensuring unified design across all pages
• Audit severity escalates — deviations become critical drifts rather than suggestions

Frequently Asked Questions

How do I create a design.md file in Hallmark?

Request it explicitly with phrases like "lock the system" or "export this as a design.md". Hallmark never generates this file automatically; the lock-the-system flow in skills/hallmark/references/design-md.md requires conscious user intent to freeze the design.

Can I edit design.md manually after locking?

Yes. The file is human-readable markdown designed for version control. However, manual edits change the enforced specification — subsequent Hallmark runs will apply your modifications and flag any existing pages that no longer match as design-system drift.

What happens if I delete design.md?

Hallmark reverts to the standard diversification flow. The next run will perform catalog/custom theme dispatch with enforced variation across pages. Deleting the file effectively unlocks the system and resumes exploratory design mode.

Does design.md work with multi-page projects?

Absolutely. The multi-page redesign flow in skills/hallmark/references/verbs/redesign.md (line 260) specifically leverages design.md to coordinate a single design system across many pages, ensuring consistency that would otherwise require manual coordination.

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