How to Lock a Design System into design.md for Portable Handoff with Hallmark

Say "lock the system" to Hallmark and it will capture your current tokens, theme, and voice decisions into a design.md file that future runs defer to automatically.

design.md is Hallmark's opt-in portable design system format. The file is only created when you explicitly trigger the lock-in flow, making your design decisions reusable across pages and projects without drift or re-interpolation.

What Triggers the Lock-In Flow

Hallmark watches for specific trigger phrases to activate Step 6 of its skill flow. According to [skills/hallmark/references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), valid triggers include:

• "lock the system"
• "give me a design.md"
• Equivalent phrases listed in the Triggers section of the design-system reference

When detected, Hallmark executes three operations:

1. Reads the current token state from in-memory tokens.css values
2. Composes a design.md using the strict ~45-line format defined in the reference
3. Writes the file at your project root, respecting existing case convention (design.md or DESIGN.md)

What Gets Locked into design.md

The locked file captures five categorical decisions:

Section	Contents
## System	Genre, macrostructure, theme, and design axes

| ## Tokens | Canonical CSS custom properties from tokens.css |

| ## CTA voice | Button styles, radius, and vertical rhythm rules |

| ## Motion stance | Animation primitives and reduced-motion fallbacks |

| ## Exports | Optional format extensions (Tailwind v4, DTCG, shadcn/ui) |

The token block is treated as canonical—tokens.css remains the source of truth, but design.md creates a portable snapshot.

The Lock Write Operation

If design.md does not exist, Hallmark creates the full file:

# 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)

```css
:root {
  --color-paper:      oklch(98% 0.02 260);
  --color-paper-2:    oklch(95% 0.03 260);
  --color-ink:        oklch(15% 0.05 260);
  --color-ink-2:      oklch(20% 0.04 260);
  --color-rule:       oklch(45% 0.08 260);
  --color-accent:     oklch(55% 0.07 260);
  --color-accent-ink: oklch(10% 0.03 260);
  --color-focus:      oklch(60% 0.09 260);
  --font-display: "Inter", system-ui, sans-serif;
  --font-body:    "Inter", system-ui, sans-serif;
  --font-mono:    "JetBrains Mono", monospace;
}

CTA voice

• Primary · #ff6600 · 8px radius · 16px vertical rhythm
• Secondary · outline · 8px radius

Motion stance

• silent · 1–2 reveal primitives · motion-cut
• Reduced-motion fallback · ≤150ms opacity crossfade.

Exports

tokens.css (in this project) is the source of truth. For Tailwind v4 @theme, DTCG tokens.json, or shadcn/ui CSS variables, ask "extend design.md with Tailwind exports".

If [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) **already exists**, Hallmark preserves the locked system and only refreshes the `## Exports` section, adding a single line stating the system is unchanged.

## How Pre-Flight Reads the Lock

Hallmark's **Step 0 pre-flight scan** ([[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) lines 51–53) checks for [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) existence. When found:

- All subsequent picks defer to the locked system
- The diversification rule **inverts**: new pages must **share** the system instead of diverging
- Genre, theme, typography, spacing, motion, and CTA voice selections are constrained by the lock

This makes [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) the highest-authority input in Hallmark's decision hierarchy.

## CTA Suppression Rules

After default or redesign builds, Hallmark surfaces a lock reminder in the preview block:

> *System portable? Say `lock the system` to extract this build's tokens + voice into a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md).*

This CTA is **suppressed** when:
- The build is component-scoped
- A [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) already exists

## Extending Locked Systems with Export Formats

Once locked, you can append platform-specific exports without regenerating the core file. The [[`export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/export-formats.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) reference documents optional extensions:

| Format | Trigger Phrase |
|--------|---------------|
| Tailwind v4 `@theme` | "extend design.md with Tailwind exports" |
| DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json) | "extend design.md with DTCG exports" |
| shadcn/ui CSS variables | "extend design.md with shadcn exports" |

Hallmark appends these to the `## Exports` section without mutating the locked canonical tokens.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Trigger phrases, format specification, lock behavior |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Skill flow with pre-flight scan (Step 0) and diversification disable |
| [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) | Optional export format specifications |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Canonical token source of truth |

## Summary

- **Speak a trigger phrase** like "lock the system" to initiate the lock-in flow
- Hallmark **writes** [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) with current tokens, theme, and voice decisions
- **Pre-flight detection** causes all future runs to defer to the locked system
- **Existing files are preserved**—only the `## Exports` section refreshes

- **Export formats** can be appended without breaking the canonical lock

## Frequently Asked Questions

### What happens if I say "lock the system" but design.md already exists?

Hallmark does not overwrite your locked system. It preserves the existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) intact and only refreshes the `## Exports` section, adding a line stating that the system is unchanged. This prevents accidental mutation of established design decisions.

### Can I manually edit design.md after locking?

Yes. The file header explicitly states "Amend intentionally—the file is the rule." Manual edits become the new locked baseline. However, since [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) remains the runtime source of truth, keep the CSS custom properties synchronized with your manual `## Tokens` edits to avoid confusion.

### Why does Hallmark require explicit trigger phrases instead of auto-locking?

Auto-locking would capture transient or experimental states as permanent systems. The opt-in design ensures you intentionally commit to a direction. The CTA reminder after builds nudges toward lock-in only when you're satisfied with the result, not during iterative exploration.

### How do I unlock or reset a design system?

Delete or rename [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). Hallmark's pre-flight scan will no longer detect the file, and the diversification rule reverts to default behavior—new pages may diverge rather than share a common system. To establish a new baseline, simply trigger "lock the system" again after your next满意 build.

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