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

> Discover the Hallmark design.md lock file and learn how it enforces design consistency across all pages, inverting the diversification rule.

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

---

**[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) Lock File?

The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file (also accepted as [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), the lock-the-system flow is a **conscious, irreversible step** that signals design completion.

### What [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.json), shadcn/ui CSS variables |

The **Exports** section enables downstream consumption by other tools and projects, making [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (step 0):

```js
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) § Theme-diversification rule, prevents "same-old-theme" drift and ensures visual variety across standalone pages.

### How [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) Inverts the Rule

When a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) lock file is present, the diversification rule is **completely inverted**:

| Aspect | Without [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) | With [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (line 153) and reinforced in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) Structure

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

```markdown

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md):

- **Without [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)**: Audit flags minor variety drifts as suggestions
- **With [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)**: Any deviation from the locked spec is reported as **critical design-system drift**

This elevates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) from documentation to **enforceable contract**.

## Key Source Files

The following files in `Nutlope/hallmark` define the complete [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) behavior:

- [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) — Lock file format specification and lock-the-system flow
- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — Core detection logic, diversification inversion, and workflow steps
- [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) — Multi-page flow that creates/updates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)
- [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) — Drift detection against locked specifications

## Summary

- **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)
- **The diversification rule inverts** from "pages must differ" to "pages must match" when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) requires conscious user intent to freeze the design.

### Can I edit [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) work with multi-page projects?

Absolutely. The multi-page redesign flow in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (line 260) specifically leverages [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) to coordinate a single design system across many pages, ensuring consistency that would otherwise require manual coordination.