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

> Lock your design system into design.md with Hallmark for portable handoff. Capture tokens, themes, and voice decisions for automatic future deference. Streamline your workflow today.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Say "lock the system" to Hallmark and it will capture your current tokens, theme, and voice decisions into a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file that future runs defer to automatically.**

[`design.md`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) values
2. **Composes** a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) remains the source of truth, but [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) creates a portable snapshot.

## The Lock Write Operation

If [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) does **not** exist, Hallmark creates the full file:

```markdown

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