From 4287ad133151b3a0d262c48af92299a0abc48194 Mon Sep 17 00:00:00 2001
From: David East <deast@google.com>
Date: Tue, 2 Jun 2026 05:23:44 +0000
Subject: [PATCH] docs: update color spec to document all supported CSS color
 formats

The linter already supports oklch, oklab, lab, lch, rgb, hsl, hwb,
named colors, color-mix, and 8-digit hex alpha. But the spec, README,
and error messages all said only hex was accepted. This was blocking
adoption for teams using modern CSS color spaces (Issue #53).

Update the Color type definition in the spec, the token types table in
the README, the spec.mdx source, and the linter error message to
reflect the full range of supported formats.

Closes #53
---
 README.md                                 |  2 +-
 docs/spec.md                              | 12 +++++++++++-
 packages/cli/src/linter/model/handler.ts  |  2 +-
 packages/cli/src/linter/spec-gen/spec.mdx | 12 +++++++++++-
 4 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3cea273..c9f6f79 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ components:
 
 | Type | Format | Example |
 |:-----|:-------|:--------|
-| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
+| Color | Any CSS color (hex, `rgb()`, `oklch()`, named, etc.) | `"#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 example above |
diff --git a/docs/spec.md b/docs/spec.md
index 874f300..41b6d08 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -59,7 +59,17 @@ components:
 
 The `<scale-level>` placeholder represents a named level in a sizing or spacing scale. Common level names include `xs`, `sm`, `md`, `lg`, `xl`, and `full`. Any descriptive string key is valid.
 
-**Color**: A color value must start with "#" followed by a hex color code in the SRGB color space.
+**Color**: A color value is any valid CSS color string. Supported formats include:
+
+* Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+* Named colors: `red`, `cornflowerblue`, `transparent`
+* Functional: `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`
+* Wide-gamut: `oklch()`, `oklab()`, `lch()`, `lab()`
+* Mixing: `color-mix(in srgb, ...)`
+
+All color values are internally converted to sRGB for WCAG contrast checking. The original format is preserved for display and export.
+
+Hex notation (`#RRGGBB`) remains the recommended default for simplicity and broad tooling support.
 
 - `fontFamily` (string)
 - `fontSize` (Dimension)
diff --git a/packages/cli/src/linter/model/handler.ts b/packages/cli/src/linter/model/handler.ts
index 8cfd71c..cfb1f87 100644
--- a/packages/cli/src/linter/model/handler.ts
+++ b/packages/cli/src/linter/model/handler.ts
@@ -60,7 +60,7 @@ export class ModelHandler implements ModelSpec {
             findings.push({
               severity: 'error',
               path: `colors.${name}`,
-              message: `'${raw}' is not a valid color. Expected a hex color code (e.g., #ffffff).`,
+              message: `'${raw}' is not a valid color. Expected a CSS color value (e.g., #ffffff, rgb(0 0 0), oklch(0.5 0.2 240)).`,
             });
             // Store as-is for fallback
             symbolTable.set(`colors.${name}`, raw);
diff --git a/packages/cli/src/linter/spec-gen/spec.mdx b/packages/cli/src/linter/spec-gen/spec.mdx
index 92cb358..44064d5 100644
--- a/packages/cli/src/linter/spec-gen/spec.mdx
+++ b/packages/cli/src/linter/spec-gen/spec.mdx
@@ -43,7 +43,17 @@ components:
 
 The `<scale-level>` placeholder represents a named level in a sizing or spacing scale. Common level names include `xs`, `sm`, `md`, `lg`, `xl`, and `full`. Any descriptive string key is valid.
 
-**Color**: A color value must start with "#" followed by a hex color code in the SRGB color space.
+**Color**: A color value is any valid CSS color string. Supported formats include:
+
+- Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+- Named colors: `red`, `cornflowerblue`, `transparent`
+- Functional: `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`
+- Wide-gamut: `oklch()`, `oklab()`, `lch()`, `lab()`
+- Mixing: `color-mix(in srgb, ...)`
+
+All color values are internally converted to sRGB for WCAG contrast checking. The original format is preserved for display and export.
+
+Hex notation (`#RRGGBB`) remains the recommended default for simplicity and broad tooling support.
 
 {typographyPropertyList()}