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

> Discover Hallmark's design.md export format created by the study verb. Learn how this portable design system representation integrates with Tailwind, shadcn/ui, and DTCG.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-07-22

---

**The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), the [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)).

### Example design.md Output from Study

```markdown

# 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`:

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

```

DTCG `tokens.json` (excerpt):

```json
{
  "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):

```css
: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`](https://github.com/Nutlope/hallmark/blob/main/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/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`](https://github.com/Nutlope/hallmark/blob/main/design.md)" or "lock the DNA." This triggers the emission logic defined in [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/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/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/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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.