Sync fork with upstream v0.3.0 (37 commits)

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Change Log
+
+AI-made changes to this fork, with the decisions behind them. Newest first.
+
+## 2026-07-24 — Synced fork with upstream v0.3.0 (branch `sync/upstream-0.3.0`, Claude)
+
+**Ask:** analyze upstream's 37-commit lead, then merge it.
+
+**What changed:** all upstream 0.2.0/0.3.0 work merged — css-vars export, CSS Color
+Module parser (named colors, hwb, lch, color-mix), nested token declarations with
+collision detection, unknown-key / token-like-ignored lint rules, typography
+sub-property warnings, export/lint exit-code fixes, TTY/ENOENT guards, Windows
+`designmd` alias, PHILOSOPHY.md. Fork primitives (ramps, pairs, themes, voice,
+copy, motion, iconography, layout, component states, evals) untouched.
+
+**Why this approach:** union merges where features were additive; fork-wins on the
+model pipeline and shadcn Tailwind output (deliberate fork identity), upstream-wins
+on CLI exit codes, color fallback parsing, and format naming. Color support is the
+union of both engines: the fork's parser (incl. display-p3) first, upstream's
+`parseCssColor` as fallback.
+
+**Considered and rejected:** adopting upstream's `tailwind`→`json-tailwind` alias
+(would silently change fork output — the fork keeps `tailwind` aliased to the
+shadcn-style `css-tailwind` CSS); replacing the fork's color parser wholesale with
+upstream's (would lose display-p3 and the `format`/`raw` round-trip metadata).

README.md

@@ -1,6 +1,20 @@
 # DESIGN.md
 
-A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
+> **About this fork**
+>
+> This is a fork of [google-labs-code/design.md](https://github.com/google-labs-code/design.md). Upstream defines the core DESIGN.md format and a linter; this fork extends both to push DESIGN.md closer to a complete, agent-ready design system spec.
+>
+> **What changed**
+>
+> - **Expanded token vocabulary** — color ramps and semantic pairs as schema primitives, modern color formats (transparent hex, etc.), and richer component property coverage in the linter.
+> - **New token domains** — themes (light/dark), motion, iconography, voice & copy, and a layout system (responsive breakpoints, grid, page templates, layout rules).
+> - **Tailwind v4 output** — generator emits a shadcn-style `:root` + `@theme inline` CSS, with foreground pairs renamed to the `<pair>-foreground` convention and radius lifted into `:root`.
+> - **Evaluation harness** — a sketch eval suite that checks DESIGN.md fidelity across copy, semantic, and vision layers on top of token extraction.
+> - **Docs** — token-storage documentation and a local-clone `bun` CLI workflow in the README.
+>
+> **Why**
+>
+> Upstream DESIGN.md focuses on the format and a linter for it. The goal of this fork is to test whether DESIGN.md can drive *real* agent output end-to-end: enough tokens to describe a full design system (not just color/type/spacing), a generator that produces idiomatic modern CSS, and evals to measure how faithfully an agent reproduces the intended design.
 
 ## The Format
 
@@ -54,7 +68,7 @@ An agent that reads this file will produce a UI with deep ink headlines in Publi
 Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.
 
 ```bash
-npx @google/design.md lint DESIGN.md
+bun run cli lint DESIGN.md
 ```
 
 ```json
@@ -73,7 +87,7 @@ npx @google/design.md lint DESIGN.md
 Compare two versions of a design system to detect token-level and prose regressions:
 
 ```bash
-npx @google/design.md diff DESIGN.md DESIGN-v2.md
+bun run cli diff DESIGN.md DESIGN-v2.md
 ```
 
 ```json
@@ -122,7 +136,7 @@ components:
 
 | Type | Format | Example |
 |:-----|:-------|:--------|
-| Color | Any CSS color (hex, `rgb()`, `oklch()`, named, etc.) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
+| Color | any CSS color: hex, named colors, `rgb()`, `hsl()`, `hwb()`, `oklch()`, `oklab()`, `lab()`, `lch()`, `color(display-p3 …)`, `color-mix()` | `"#1A1C1E"`, `"oklch(70% 0.15 200)"` |
 | 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 example above |
@@ -157,7 +171,7 @@ components:
     backgroundColor: "{colors.tertiary-container}"
 ```
 
-Valid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.
+Valid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`, `gap`, `border`, `outline`, `opacity`, `boxShadow`, `transition`, `backdropFilter`.
 
 Variants (hover, active, pressed) are expressed as separate component entries with a related key name.
 
@@ -175,20 +189,18 @@ Variants (hover, active, pressed) are expressed as separate component entries wi
 
 ### Installation
 
-```bash
-npm install @google/design.md
-```
-
-On **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):
+This fork is not published to npm. Clone the repo and install dependencies with [Bun](https://bun.sh):
 
 ```bash
-npm install "@google/design.md"
+git clone https://github.com/joesteinkamp/design.md.git
+cd design.md
+bun install
 ```
 
-Or run directly (always resolves from the public npm registry):
+Then run the CLI from the repo root via the `cli` script defined in `package.json`:
 
 ```bash
-npx @google/design.md lint DESIGN.md
+bun run cli lint DESIGN.md
 ```
 
 On **Windows/PowerShell**, this direct form can produce no output (or open
@@ -238,24 +250,41 @@ All commands accept a file path or `-` for stdin. Output defaults to JSON.
 Validate a DESIGN.md file for structural correctness.
 
 ```bash
-npx @google/design.md lint DESIGN.md
-npx @google/design.md lint --format json DESIGN.md
-cat DESIGN.md | npx @google/design.md lint -
+bun run cli lint DESIGN.md
+bun run cli lint --format json DESIGN.md
+cat DESIGN.md | bun run cli lint -
+bun run cli lint --fix DESIGN.md   # rewrite the file with auto-fixes applied
 ```
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
 | `--format` | `json` | `json` | Output format |
+| `--fix` | boolean | `false` | Apply auto-fixes (currently: section order) and rewrite the input file |
 
 Exit code `1` if errors are found, `0` otherwise.
 
+### `fix`
+
+Apply auto-fixes to a DESIGN.md file. Today the only fix is reordering sections into the canonical order; more fixes will follow. By default the fixed content is written to stdout, leaving the input file untouched.
+
+```bash
+bun run cli fix DESIGN.md > DESIGN.fixed.md
+bun run cli fix --write DESIGN.md   # rewrite in place
+```
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
+| `--write` | boolean | `false` | Rewrite the input file instead of streaming to stdout |
+| `--format` | `json` \| `text` | `json` | Format for the report when `--write` is used |
+
 ### `diff`
 
 Compare two DESIGN.md files and report token-level changes.
 
 ```bash
-npx @google/design.md diff DESIGN.md DESIGN-v2.md
+bun run cli diff DESIGN.md DESIGN-v2.md
 ```
 
 | Option | Type | Default | Description |
@@ -271,11 +300,14 @@ Exit code `1` if regressions are detected (more errors or warnings in the "after
 Export DESIGN.md tokens to other formats.
 
 ```bash
-npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
-npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
-npx @google/design.md export --format dtcg DESIGN.md > tokens.json
+bun run cli export --format css-tailwind DESIGN.md > theme.css
+bun run cli export --format json-tailwind DESIGN.md > tailwind.theme.json
+bun run cli export --format dtcg DESIGN.md > tokens.json
+bun run cli export --format css-vars DESIGN.md > tokens.css
 ```
 
+The `tailwind` format emits a Tailwind v4 `@theme` stylesheet — Tailwind v4 deprecates `tailwind.config.js` in favor of CSS-first configuration via `@theme { --color-*; --font-*; ... }`. Import the generated file from your app's main stylesheet alongside `@import "tailwindcss";`.
+
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
@@ -295,9 +327,9 @@ Exit code `0` on a successful export (regardless of any lint findings in the sou
 Output the DESIGN.md format specification (useful for injecting spec context into agent prompts).
 
 ```bash
-npx @google/design.md spec
-npx @google/design.md spec --rules
-npx @google/design.md spec --rules-only --format json
+bun run cli spec
+bun run cli spec --rules
+bun run cli spec --rules-only --format json
 ```
 
 | Option | Type | Default | Description |
@@ -340,9 +372,10 @@ console.log(report.designSystem);   // Parsed DesignSystemState
 
 DESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:
 
-- **Tailwind v3 config (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`. `--format tailwind` is a backwards-compatible alias.
-- **Tailwind v4 theme (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`).
-- **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`
+- **Tailwind v4 theme (CSS)** — `bun run cli export --format css-tailwind DESIGN.md` — emits a shadcn-style `:root` + `@theme inline` stylesheet. `--format tailwind` is a backwards-compatible alias.
+- **Tailwind v3 config (JSON)** — `bun run cli export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`.
+- **CSS custom properties** — `bun run cli export --format css-vars DESIGN.md` — emits a plain `:root { --token: value }` stylesheet.
+- **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `bun run cli export --format dtcg DESIGN.md`
 
 ## Status