DESIGN.md Skill — Design System Validation & Management

> Validate, diff, and export DESIGN.md files for consistent design systems across projects.

Overview

DESIGN.md is a format specification (by Google Labs) for describing a visual identity to coding agents. It combines:

• YAML front matter — Machine-readable design tokens
• Markdown body — Human-readable design rationale

Installation

The skill uses @google/design.md npm package:

npm install -g @google/design.md

Commands

1. Lint — Validate DESIGN.md

npx @google/design.md lint DESIGN.md

Checks:

• Token references resolve (broken-ref → error)
• WCAG contrast ratios (contrast-ratio → warning)
• Missing primary colors (missing-primary → warning)
• Section order (section-order → warning)

Output: JSON with findings

2. Diff — Compare Versions

npx @google/design.md diff DESIGN.md DESIGN-v2.md

Detects:

• Added/removed/modified tokens
• Regressions between versions

3. Export — Convert to Other Formats

npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

4. Spec — View Format Specification

npx @google/design.md spec
npx @google/design.md spec --rules

Quick Start

1. Read existing DESIGN.md in project
2. Run lint to validate structure
3. Run export to generate Tailwind config
4. Update components based on findings

Usage in Coding

When working on UI components:

# Before editing a component, lint current state
npx @google/design.md lint design-md/markiosi/DESIGN.md

# After changes, diff to check for regressions
npx @google/design.md diff design-md/markiosi/DESIGN.md design-md/markiosi/DESIGN.md.new

# Export updated tokens
npx @google/design.md export --format tailwind design-md/markiosi/DESIGN.md > tailwind.tokens.json

Workflow Integration

1. Before making UI changes:
• Read project's DESIGN.md
• Run lint to understand current design state

1. After UI changes:
• Update DESIGN.md tokens accordingly
• Run diff to detect regressions
• Run lint to validate WCAG compliance

1. For new components:
• Check DESIGN.md for existing component patterns
• Define new components in DESIGN.md first
• Use token references ({colors.primary}) over hardcoded values

Resources

• Spec: https://github.com/google-labs-code/design.md
• Stitch Tool: https://stitch.withgoogle.com/
• Design Tokens Format: https://www.designtokens.org/