--- a/design_system/COLORS.md	Tue Aug 04 16:49:11 2026 -0700
+++ b/design_system/COLORS.md	Wed Aug 05 05:25:40 2026 -0700
@@ -4,28 +4,23 @@
 most surfaces; restrained natural colors provide emphasis without making the
 interface feel synthetic or overly saturated.
 
-## Primitive ramps
+## Reference colors
 
-Each family has `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`,
-`900`, and `950` steps:
+`reference.css` exposes the steps required by current themes and components:
 
-- `--zen-color-neutral-*`: warm paper, linen, charcoal, and ink;
-- `--zen-color-red-*`: brick and iron oxide;
-- `--zen-color-orange-*`: persimmon;
-- `--zen-color-amber-*`: straw and ochre;
-- `--zen-color-green-*`: matcha and moss;
-- `--zen-color-teal-*`: aged copper and patina;
-- `--zen-color-blue-*`: faded workwear and indigo;
-- `--zen-color-violet-*`: muted plum;
-- `--zen-color-rose-*`: clay and dusty rose;
-- `--zen-color-brown-*`: kraft paper and wood.
+- `--zenbu-ref-color-neutral-*`: paper, linen, charcoal, and ink;
+- `--zenbu-ref-color-brand-*`: faded workwear and indigo;
+- `--zenbu-ref-color-danger-*`: brick and iron oxide;
+- `--zenbu-ref-color-success-*`: matcha and moss;
+- `--zenbu-ref-color-warning-*`: persimmon and ochre.
 
-Use a primitive when an application needs a precise ramp step. Primitive values
-do not change between light and dark themes.
+Reference values do not change between themes. They are consumed by semantic
+theme mappings, not directly by application components.
 
-## Material aliases
+## Legacy material aliases
 
-Material aliases make one-off composition readable:
+These compatibility aliases preserve existing visual names while migration is
+in progress:
 
 ```css
 var(--zen-color-paper)
@@ -43,21 +38,26 @@
 var(--zen-color-wood)
 ```
 
-## Semantic aliases
+Do not use them in new component CSS; map the intended role through a
+`--zenbu-sys-color-*` token instead.
+
+## Semantic roles
 
 Components should prefer semantic tokens because these adapt to the current
 theme:
 
-- surfaces: `canvas`, `surface`, `surface-raised`, `surface-muted`,
-  `surface-sunken`, and `surface-overlay`;
-- text: `text`, `text-muted`, `text-subtle`, and `text-inverse`;
-- borders: `border`, `border-muted`, and `border-strong`;
-- action: `accent`, `accent-hover`, `accent-muted`, `focus`, `disabled`, and
-  `selection`;
-- status: `info`, `success`, `warning`, `danger`, their `on-*` foregrounds,
-  and their `*-muted` surfaces.
+- surfaces: `--zenbu-sys-color-surface-*`;
+- text and icons: `--zenbu-sys-color-text-*` and
+  `--zenbu-sys-color-icon-*`;
+- borders: `--zenbu-sys-color-border-*`;
+- actions and states: `--zenbu-sys-color-action-*`;
+- status: `--zenbu-sys-color-info-*`, `success-*`, `warning-*`, and
+  `danger-*`;
+- selection and focus: `--zenbu-sys-color-selection-*` and
+  `--zenbu-sys-color-focus-*`.
 
-All names use the `--zen-color-` prefix.
+Legacy `--zen-color-*` values remain compatibility aliases. New code uses the
+`--zenbu-ref-*` / `--zenbu-sys-*` architecture.
 
 Component and catalog styles may not contain raw color literals. Add or reuse a
 token in `tokens.css`, then reference it with `var()`. The Bazel target
@@ -66,7 +66,8 @@
 
 ## Data colors
 
-`--zen-color-data-1` through `--zen-color-data-10` form a categorical palette.
+`--zen-color-data-1` through `--zen-color-data-10` remain the current
+categorical compatibility palette.
 They deliberately vary in both hue and lightness. Keep adjacent series in
 numerical order and provide labels or patterns; color alone must never carry
 meaning.
@@ -75,12 +76,13 @@
 
 ```css
 .repository-summary {
-  border: 1px solid var(--zen-color-border-muted);
-  background: var(--zen-color-surface-muted);
-  color: var(--zen-color-text);
+  border: var(--zenbu-sys-stroke-width) solid
+    var(--zenbu-sys-color-border-subtle);
+  background: var(--zenbu-sys-color-surface-subtle);
+  color: var(--zenbu-sys-color-text-primary);
 }
 
 .repository-summary strong {
-  color: var(--zen-color-indigo);
+  color: var(--zenbu-sys-color-text-link);
 }
 ```