Hallmark design.md Export Format: How the Study Verb Creates Portable Design Systems

The design.md export format is a canonical, portable representation of a design system that the Hallmark study verb emits when you "lock the DNA," containing standardized sections for tokens, motion, and exports compatible with Tailwind, shadcn/ui, and DTCG pipelines.

The design.md file serves as the single source of truth in the Nutlope/hallmark repository. When using the study verb to analyze images or URLs, Hallmark can export a tight, approximately 45-line specification that captures the extracted design DNA in a format readable by future Hallmark runs and external AI tools like Cursor or Bolt.

What Is the Hallmark design.md Export Format?

According to [skills/hallmark/references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), the design.md format is a markdown-based contract that Hallmark treats as the rule for all subsequent builds. The file uses a strict section hierarchy to ensure portability across projects.

Required Sections in the design.md Specification

Every design.md file emitted by the study verb contains six mandatory sections:

• # Design — <Project name> – The H1 header identifies the system and establishes the file as the canonical reference.

• ## System – Declares high-level choices including genre (e.g., editorial), macrostructure (e.g., long-document), theme catalog, and design axes.

• ## Tokens – Houses canonical CSS custom properties in a :root block, serving as the source of truth for all visual values.

• ## CTA voice – Defines primary and secondary button styling using the format <fill colour> · <radius> · <padding rhythm>.

• ## Motion stance – Specifies motion primitives (e.g., "silent · 1–2 reveal primitives · motion-cut") and reduced-motion fallbacks.

• ## Exports – Provides inline snippets for alternative token pipelines including Tailwind v4 @theme, DTCG tokens.json, and shadcn/ui CSS variables.

How the Study Verb Generates design.md

The study verb in Hallmark operates as a design system extraction tool. When you run hallmark study against an image or URL, it first diagnoses the DNA—macrostructure, typography, color, and motion patterns.

As documented in [skills/hallmark/references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), the export only occurs when you explicitly request it with phrases like "give me a design.md" or "lock the DNA." This opt-in behavior mirrors real-world design hand-off workflows and triggers Step 6 in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

The emission process applies the same refusal layer that protects third-party sites, ensuring ethical extraction before writing the file to your project root using the repository's case convention (design.md or DESIGN.md).

Example design.md Output from Study

# Design — Example-Site

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: Example-Site
- Axes · paper-band / display-style / accent-hue

## Tokens (canonical · `tokens.css` is the source of truth)

```css
:root {
  --color-paper:      oklch(96% 0.018 80);
  --color-ink:        oklch(15% 0.012 80);
  --color-accent:     oklch(58% 0.16 70);
  --font-display:     "Fraunces", ui-serif, Georgia, serif;
  --font-body:        "Geist", ui-sans-serif, system-ui, sans-serif;

  --ease-out:        cubic-bezier(0.16, 1, 0.3, 1);
  --dur-fast:        180ms;
  --radius-card:     4px;
}

CTA voice

• Primary · #ff6b6b · 4px · 1rem 1.5rem
• Secondary · outline · 4px

Motion stance

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

Exports

tokens.css (in this project) is the source of truth.
Tailwind v4 @theme:

@theme {
  --color-paper: oklch(96% 0.018 80);
  --color-ink:   oklch(15% 0.012 80);
}

DTCG tokens.json (excerpt):

{
  "color": {
    "paper": "oklch(96% 0.018 80)",
    "ink":   "oklch(15% 0.012 80)"
  },
  "font": {
    "display": "\"Fraunces\", ui-serif, Georgia, serif"
  }
}

shadcn/ui CSS vars (excerpt):

:root {
  --primary:   var(--color-accent);
  --radius:    var(--radius-card);
}

## Portability and Cross-Tool Compatibility

The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) format is explicitly designed as a **portable design-system spec**. Because the file is self-contained—with all tokens defined in the `## Tokens` block and multiple export formats in the `## Exports` section—you can copy it into any new codebase.

As detailed in [[`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md), the format supports four canonical payloads:

1. **[`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css)** – The source-of-truth CSS custom properties (always written).
2. **Tailwind v4 `@theme`** – Native CSS-first theme configuration.
3. **DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json)** – Design Tokens Community Group specification for Style Dictionary.
4. **shadcn/ui CSS vars** – Compatible with the popular React component library.

Future Hallmark runs automatically detect and read [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) first, making the system reusable across projects without re-running the `study` verb. This portability extends to multi-page redesigns orchestrated through [[`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md).

### Using design.md in a New Project

```bash

# Copy the design.md file to your new project root

cp /path/to/studied/design.md ./design.md

# Hallmark now reads the locked system on every run

hallmark default  # All picks defer to the portable spec

Summary

• The design.md export format is a tight, approximately 45-line markdown specification that serves as the canonical representation of a Hallmark design system.
• The study verb emits this file only when explicitly requested ("lock the DNA"), extracting visual DNA from images or URLs and formatting it according to [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).
• The format includes six required sections: Design header, System, Tokens, CTA voice, Motion stance, and Exports.
• Portability is achieved through self-contained CSS custom properties and optional export formats compatible with Tailwind v4, DTCG/Style Dictionary, and shadcn/ui.
• The file is written to the project root and becomes the single source of truth for all subsequent Hallmark runs and compatible AI tools.

Frequently Asked Questions

What triggers the design.md export in Hallmark's study verb?

The export is opt-in, not automatic. After running hallmark study on an image or URL, you must explicitly request the file using phrases like "give me a design.md" or "lock the DNA." This triggers the emission logic defined in [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) and Step 6 of [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

Is the design.md format compatible with Tailwind CSS v4?

Yes. The ## Exports section optionally includes a Tailwind v4 @theme block that maps the canonical CSS custom properties to Tailwind's CSS-first configuration format. This allows you to import the studied design system directly into a Tailwind v4 project without additional transformation steps.

Can I use a Hallmark design.md file with shadcn/ui?

Yes. The format explicitly supports shadcn/ui CSS variables in the ## Exports section, mapping Hallmark tokens like --color-accent to shadcn's --primary and --radius variables. This compatibility is documented in [export-formats.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md).

Where does Hallmark write the design.md file?

Hallmark writes the file to the project root, respecting the repository's case convention (either design.md or DESIGN.md). Once present, any future Hallmark command—including default and redesign verbs—reads this file first to enforce the locked design system across all subsequent operations.

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