--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/COLORS.md	Tue Aug 04 15:12:09 2026 -0700
@@ -0,0 +1,86 @@
+# Zenbu UI color
+
+The Zenbu palette is warm, quiet, and material-oriented. Paper neutrals carry
+most surfaces; restrained natural colors provide emphasis without making the
+interface feel synthetic or overly saturated.
+
+## Primitive ramps
+
+Each family has `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`,
+`900`, and `950` steps:
+
+- `--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.
+
+Use a primitive when an application needs a precise ramp step. Primitive values
+do not change between light and dark themes.
+
+## Material aliases
+
+Material aliases make one-off composition readable:
+
+```css
+var(--zen-color-paper)
+var(--zen-color-washi)
+var(--zen-color-linen)
+var(--zen-color-sumi)
+var(--zen-color-brick)
+var(--zen-color-persimmon)
+var(--zen-color-ochre)
+var(--zen-color-moss)
+var(--zen-color-patina)
+var(--zen-color-indigo)
+var(--zen-color-plum)
+var(--zen-color-clay)
+var(--zen-color-wood)
+```
+
+## Semantic aliases
+
+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.
+
+All names use the `--zen-color-` prefix.
+
+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
+`//design_system/test:design_system_policy_test` rejects hex, functional, or
+named colors anywhere else in the design-system source.
+
+## Data colors
+
+`--zen-color-data-1` through `--zen-color-data-10` form a categorical 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.
+
+## Usage
+
+```css
+.repository-summary {
+  border: 1px solid var(--zen-color-border-muted);
+  background: var(--zen-color-surface-muted);
+  color: var(--zen-color-text);
+}
+
+.repository-summary strong {
+  color: var(--zen-color-indigo);
+}
+```