Design.md

design.md is a design system specification format and toolchain that defines a visual identity through structured, machine-readable design tokens embedded in a human-readable Markdown document. It combines exact token values with prose explanations of design intent, enabling coding agents to consistently apply brand styles across a project while keeping the rationale accessible to human designers.

The project provides a linter that validates design specification files for structural correctness, broken token references, and WCAG color contrast compliance, outputting structured findings. It also includes a diff tool that compares two design specification files and reports token-level additions, removals, and modifications to detect visual regressions. Design tokens can be exported to Tailwind CSS configuration files (v3 JSON or v4 CSS theme blocks) and to the W3C Design Tokens Community Group JSON format for cross-tool interoperability.

The specification format itself defines design tokens with typed values, descriptions, and rationale in a YAML frontmatter block, with support for cross-token reference resolution to ensure consistency. The toolchain covers the full lifecycle of design token management—storing, validating, diffing, and exporting—to maintain a single source of truth for colors, typography, and spacing.

Features

Structured Token Specifications - Defines a structured specification format for design tokens with typed values, descriptions, and rationale in YAML frontmatter.

Visual Identity Descriptions - Combines machine-readable design tokens with human-readable rationale so coding agents understand both exact values and design intent.

Design Token Exporters - Converts design tokens into Tailwind CSS configuration files and W3C DTCG JSON format for cross-tool interoperability.

Design Specification Validations - Lints a DESIGN.md file for structural correctness, broken token references, and WCAG contrast compliance.

Design Token Management - Stores, validates, and diffs design tokens to maintain a single source of truth for colors, typography, and spacing.

Design Specification Validators - Validates DESIGN.md files against a schema for required fields, token types, and structural correctness.

Design Intent Wrappers - Wraps design token definitions in prose sections that explain design intent and usage guidelines for human readers.

Design Specification Differs - Compares two design specification files and reports token-level changes to detect visual regressions.

Design Token Diff Detections - Ships a diff tool that compares two design specification files and reports token-level changes to detect visual regressions.

WCAG Contrast Checkers - Checks color token pairs against WCAG contrast ratio thresholds and reports failures with structured findings.

Token Configuration Exports - Converts design tokens into Tailwind CSS configuration files for v3 JSON or v4 CSS theme blocks.

Design Token Aliasing - Resolves cross-token references within the specification to ensure consistency and detect broken links.

Design Token Interoperability - Exports design tokens to the W3C Design Tokens Community Group JSON format for cross-tool interoperability.

Exporters - Converts design tokens into Tailwind CSS configs and W3C DTCG JSON for cross-platform use.

Multi-Format Exporters - Converts design tokens into Tailwind CSS configuration files and W3C DTCG JSON format for cross-tool interoperability.

Specifications - Defines a machine-readable specification format for design tokens with typed values and rationale.

Token-Level Diffing - Compares two design specification files and reports token-level additions, removals, and modifications to detect regressions.

Token-Level Version Diffing - Compares two design specification files to detect token-level additions, removals, and modifications for regression checking.

Agent-Oriented Specifications - Defines a visual identity with structured tokens and rationale so coding agents can consistently apply brand styles across a project.

Agent-Targeted Formats - Provides a structured format for describing visual identity to coding agents using design tokens and human-readable rationale.

Design Specification Linters - Validates design specification files for structural correctness and WCAG contrast compliance.

google-labs-codedesign.md

Features

Star history