$ show google-labs-code/design.md
This repository implements `@google/design.md`, a CLI tool and programmatic library for a design token format called DESIGN.md. The format pairs YAML frontmatter (tokens) with Markdown prose (rationale). The tool provides validation (lint), diffing, multi-format export (Tailwind v3 JSON, Tailwind v4 CSS, DTCG JSON, CSS custom properties), and spec generation. It is published as an npm package and is designed to be consumed by both human designers and AI coding agents. The architecture is a monorepo with a single CLI package (`packages/cli`) that uses `citty` for command routing. The core pipeline parses DESIGN.md files, builds a token model with reference resolution and color parsing, runs 11 lint rules (including WCAG contrast ratio checks), and emits results via stateless handler functions. A separate spec generation pipeline compiles `spec.mdx` with a custom MDX compiler to produce `docs/spec.md`. The codebase is well-tested with unit tests for each component. Key entry points include the CLI binary (`packages/cli/src/index.ts`), the programmatic `lint()` function (`packages/cli/src/linter/index.ts`), and the spec generator (`packages/cli/src/linter/spec-gen/`). External dependencies are minimal: `citty` for CLI, `zod` for validation, `consola` for logging, and `bun` for build/test. The repository also includes three complete example design systems and a set of agent skills for development workflow.
The LLM identified 3 files worth highlighting for reuse:
A self-contained color parser that supports hex, named CSS colors, functional rgb/hsl/hwb/lab/lch/oklab/oklch, and color-mix() with sRGB blending. It handles wide-gamut spaces and provides conversion to sRGB for contrast computation. This module has no internal dependencies and can be extracted as a standalone library for any project needing robust CSS color parsing.
Implements WCAG 2.1 relative luminance and contrast ratio calculation. It is a pure function that takes two color values (as parsed by the color parser) and returns the contrast ratio. The rule is self-contained, well-tested, and can be reused in any accessibility auditing tool or design system validator.
Defines the spec configuration as a TypeScript module derived from a YAML file (`spec-config.yaml`). It serves as the single source of truth for allowed token types, units, sections, and limits. This pattern enables automatic generation of both runtime validation (via Zod schemas) and documentation (via MDX compilation). The approach is reusable for any project that needs to maintain a formal specification with code and docs in sync.