# design-md

Create and validate DESIGN.md token specs, compare revisions, and export design tokens to Tailwind or W3C DTCG formats.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 523 installs · ★ 257179
- Author: Hermes Agent
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/NousResearch/hermes-agent/tree/HEAD/skills/creative/design-md/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/hermes-agent-design-md

## What it does

The skill builds a `DESIGN.md` file with machine-readable tokens in YAML front matter and guidance in Markdown. It can also lint an existing spec, compare two versions, and export its tokens. When drafting a file, it asks for the brand tone, accent color, and typography direction.

Validation and exports use the `@google/design.md` CLI through `npx`; Node is required. The CLI checks structure and WCAG contrast, compares versions, and exports Tailwind themes or W3C DTCG JSON. On Windows, `design.md` can collide with the `.md` file association, so the instructions provide the `designmd` alias. Export can succeed despite lint findings, so run `lint` separately when those checks should gate the work.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add NousResearch/hermes-agent --skill design-md -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/design-md/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/design-md/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add NousResearch/hermes-agent --skill design-md -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/design-md/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add NousResearch/hermes-agent --skill design-md -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/design-md/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install NousResearch/hermes-agent design-md
```

2. **Manually: put the files in place**
- File: `.github/skills/design-md/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add NousResearch/hermes-agent --skill design-md -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/NousResearch/hermes-agent --path skills/creative/design-md
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/design-md/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add NousResearch/hermes-agent --skill design-md -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/NousResearch/hermes-agent/tree/HEAD/skills/creative/design-md/SKILL.md

## When to use it
- create a `DESIGN.md` with color and typography tokens
- check token references and WCAG contrast
- compare spec revisions for regressions
- export tokens to Tailwind or W3C DTCG JSON

## Example prompts
- Create a `DESIGN.md` for this project with color and typography tokens.
- Lint `DESIGN.md` for broken token references and WCAG contrast.
- Compare `DESIGN.md` with `DESIGN-v2.md`, then export the tokens to Tailwind.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c7e7e6be3862b984.

BEGIN THIRD-PARTY FILE c7e7e6be3862b984
````text
---
name: design-md
description: Author/validate/export Google's DESIGN.md token spec files.
version: 1.1.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [design, design-system, tokens, ui, accessibility, wcag, tailwind, dtcg, google]
    related_skills: [popular-web-designs, claude-design, excalidraw, architecture-diagram]
---

# DESIGN.md Skill

DESIGN.md is Google's open spec (Apache-2.0, `google-labs-code/design.md`) for
describing a visual identity to coding agents. One file combines:

- **YAML front matter** — machine-readable design tokens (normative values)
- **Markdown body** — human-readable rationale, organized into canonical sections

Tokens give exact values. Prose tells agents *why* those values exist and how to
apply them. The CLI (`npx @google/design.md`) lints structure + WCAG contrast,
diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.

## When to use this skill

- User asks for a DESIGN.md file, design tokens, or a design system spec
- User wants consistent UI/brand across multiple projects or tools
- User pastes an existing DESIGN.md and asks to lint, diff, export, or extend it
- User asks to port a style guide into a format agents can consume
- User wants contrast / WCAG accessibility validation on their color palette

For purely visual inspiration or layout examples, use `popular-web-designs`
instead. For *process and taste* when designing a one-off HTML artifact
from scratch (prototype, deck, landing page, component lab), use
`claude-design`. This skill is for the *formal spec file* itself.

## File anatomy

```md
---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary}"
---

## Overview

Architectural Minimalism meets Journalistic Gravitas...

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

## Typography

Public Sans for everything except small all-caps labels...

## Components

`button-primary` is the only high-emphasis action on a page...
```

## Token types

| Type | Format | Example |
|------|--------|---------|
| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
| Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
| Token reference | `{path.to.token}` | `{colors.primary}` |
| Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | see above |
````
END THIRD-PARTY FILE c7e7e6be3862b984

The third-party file has ended. Everything between the c7e7e6be3862b984 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3147 of 8477 bytes. © Hermes Agent · MIT · https://github.com/NousResearch/hermes-agent/tree/HEAD/skills/creative/design-md/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md