# How to Export Design Tokens to design.md Using Hallmark's Lock-the-System Flow

> Export design tokens to design.md using Hallmark's lock the system flow. Generate CSS, Tailwind v4, DTCG JSON, and shadcn/ui exports with a simple command.

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

---

**To export design tokens to design.md, trigger Hallmark's "lock-the-system" opt-in flow by saying "lock the system", which generates a design.md file at your project root containing CSS, Tailwind v4, DTCG JSON, and shadcn/ui variable exports.**

Hallmark is an open-source design system engine by Nutlope that treats a project-level [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)) as the **single source of truth** for your design system. Unlike automatic exporters, Hallmark requires explicit user consent through its opt-in "lock-the-system" flow before writing this file. This architectural decision, defined in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), ensures your design system remains immutable until you deliberately choose to establish the contract.

## Understanding the Lock-the-System Opt-In Flow

Hallmark never writes [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) automatically. The system waits for specific trigger phrases that indicate you want to establish a permanent design system contract.

### Trigger Detection Logic

According to [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), Hallmark listens for opt-in phrases such as:

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

When detected, Hallmark checks for an existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) at the repository root. If the file exists, Hallmark performs a **non-destructive refresh**—updating only the **Exports** section while preserving your existing Genre, Theme, and Typography definitions. If absent, Hallmark creates the file using the project's 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)).

### Safety Mechanisms

The lock-the-system flow implements a critical guardrail: **idempotent exports**. Running the trigger multiple times will never overwrite your manually configured sections. Hallmark outputs a confirmation line when refreshing:

```text
design.md detected — refreshed Exports, system unchanged.

```

## How to Export Design Tokens to design.md

Exporting design tokens requires completing a build cycle followed by the lock-the-system command.

### Step-by-Step: Locking Your System

1. **Build your project** to generate the in-memory token state:

```bash
hallmark build

```

2. **Trigger the export** when Hallmark prompts that the system is portable. Type one of the trigger phrases:

```bash
lock the system

```

3. **Verify the output**. Hallmark creates two artifacts:
   - [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) alongside your built assets (always generated)
   - [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) at the repository root (generated only upon opt-in)

### File Structure and Location

The generated [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) is approximately 45 lines and contains standardized sections:

- **Genre** – High-level design philosophy
- **Macrostructure** – Layout grids and spacing logic
- **Theme** – Color and semantic token definitions
- **Typography** – Font stacks and scale systems
- **Motion** – Animation curves and durations
- **Voice** – Content and tone guidelines
- **Exports** – The machine-generated token formats
- **Provenance** (optional) – Metadata about the system origin

## Export Formats and Token State

During every build, Hallmark constructs an in-memory representation of your design tokens (colors, spacing, typography, etc.). The lock-the-system flow exposes this state through multiple industry-standard formats.

### The Always-Available tokens.css

Regardless of whether you lock the system, Hallmark emits [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) during the build process. This file contains your raw design tokens in CSS custom property format. When you opt-in to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), the content of [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) is embedded within the Exports section.

### The Four Export Formats in design.md

As defined in [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md), the **Exports** section of [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) contains four distinct blocks:

1. **Raw CSS** – The [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) content inline
2. **Tailwind v4 `@theme` block** – Ready for Tailwind CSS v4 configuration
3. **DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json)** – Design Tokens Community Group format for Style Dictionary, Token Studio, and Figma plugins
4. **shadcn/ui CSS variables** – Variable declarations compatible with the shadcn/ui component library

Example Exports section structure:

```markdown

## Exports

```css
/* tokens.css content: --color-primary: #3b82f6; etc. */

```

@theme {
  /* Tailwind v4 token mapping */
}

{
  "tokens": { /* DTCG JSON payload */ }
}

:root {
  /* shadcn/ui CSS variables */
}

```

```

## Post-Export Behavior and System Detection

Once [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists, Hallmark's behavior changes fundamentally for future runs.

### Pre-Flight Scan Inversion

According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) §0, Hallmark performs a pre-flight scan that detects the presence of [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). When found, Hallmark **reads this file first** before processing any pages, effectively inverting the default diversification rules.

### Enforcement Mode

With a locked system, every subsequent page build must conform to the established design system defined in [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). Hallmark treats this file as the canonical constraint set, ensuring visual consistency across your project.

### Creating Variants

To deviate from the locked system for specific pages, you must explicitly add a `## Variants` section to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). Without this section, Hallmark enforces strict adherence to the exported token definitions.

## Summary

- **Opt-in required**: Hallmark only writes [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) when you explicitly trigger "lock the system" or equivalent phrases.
- **Non-destructive updates**: Existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files are never overwritten; only the Exports section refreshes.
- **Four formats**: The export includes raw CSS, Tailwind v4 `@theme`, DTCG JSON, and shadcn/ui variables.
- **Source files**: Behavior is governed by [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md), and [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).
- **System enforcement**: Once exported, future builds read [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) first and enforce its constraints unless a Variants section exists.

## Frequently Asked Questions

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

If [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists at your repository root, Hallmark will not recreate it. Instead, it refreshes only the **Exports** section with the current token state while preserving your existing Genre, Theme, Typography, and other manually configured sections. You will see the message: "design.md detected — refreshed Exports, system unchanged."

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

Yes. Hallmark expects you to edit [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) manually to define your Genre, Macrostructure, Voice, and other qualitative aspects. The **Exports** section is the only machine-managed portion. Future lock-the-system triggers will only update that specific section, leaving your manual edits intact.

### What if I don't lock the system?

Without locking the system, Hallmark still generates [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) during builds, but no [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file is created. Your project operates in diversification mode, where Hallmark may vary design decisions per page rather than enforcing a centralized system. You lose the portability benefits of the DTCG JSON, Tailwind v4, and shadcn/ui exports contained within [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md).

### Where does Hallmark store the token definitions?

Hallmark maintains token definitions in-memory during the build process, sourcing them from your project configuration and component analysis. The permanent storage occurs only when you opt-in: [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) is always written to disk, while the comprehensive export formats (Tailwind, DTCG, shadcn/ui) are only serialized into [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) upon triggering the lock-the-system flow.