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

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 (or 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, 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 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, 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 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 or 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:

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:

hallmark build

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

lock the system

3. Verify the output. Hallmark creates two artifacts:
   • tokens.css alongside your built assets (always generated)
   • design.md at the repository root (generated only upon opt-in)

File Structure and Location

The generated 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 during the build process. This file contains your raw design tokens in CSS custom property format. When you opt-in to design.md, the content of tokens.css is embedded within the Exports section.

The Four Export Formats in design.md

As defined in skills/hallmark/references/export-formats.md, the Exports section of design.md contains four distinct blocks:

1. Raw CSS – The tokens.css content inline
2. Tailwind v4 @theme block – Ready for Tailwind CSS v4 configuration
3. DTCG 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:

## 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 exists, Hallmark's behavior changes fundamentally for future runs.

Pre-Flight Scan Inversion

According to skills/hallmark/SKILL.md §0, Hallmark performs a pre-flight scan that detects the presence of 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. 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. Without this section, Hallmark enforces strict adherence to the exported token definitions.

Summary

• Opt-in required: Hallmark only writes design.md when you explicitly trigger "lock the system" or equivalent phrases.
• Non-destructive updates: Existing 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, skills/hallmark/references/export-formats.md, and skills/hallmark/SKILL.md.
• System enforcement: Once exported, future builds read 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 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 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 during builds, but no 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.

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 is always written to disk, while the comprehensive export formats (Tailwind, DTCG, shadcn/ui) are only serialized into design.md upon triggering the lock-the-system flow.

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