@lotics/ui 42.0.0 → 42.3.0

package/docs/catalog.md

@@ -1225,6 +1225,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   a record's identity band reporting that record's own state**: derived verdicts on one record
   ("documents incomplete", "2 fields need checking") are the checklist a record must not carry
   (§`checklist`) and restate at a distance what the sections below state in place.
+- **`summary`** — `Summary`: the register summary band, for a set with a SHAPE worth showing —
+  a headline figure, a distribution bar, and the buckets named. A COMPOUND:
+  `Summary.Header` / `Summary.Total` / `Summary.Metric` / `Summary.Distribution` /
+  `Summary.Facts`, composed as children. **Declare the buckets ONCE on the root and every part
+  derives from them** — the headline is their sum (there is no `total` prop to go stale), the
+  segments and the legend swatches are the buckets' own colours. That correspondence is the
+  reason it exists: a `segments` array passed beside an `items` array beside a `total` drifts
+  three ways, invisibly. A `SummaryBucket` must PARTITION the set; an aggregate over the same
+  rows that does not (a condition like "overdue" beside "draft / sent / paid", counted again
+  from a different question) goes to `Summary.Facts` as `extra`, where it renders with NO swatch
+  — the visual difference says it is not a slice of the bar. Ordering is the caller's and is
+  never re-ranked, because for a pipeline the sequence is the process. Pick between the four
+  summaries by what you have: only aggregates → `summary_line`; aggregates + a shape →
+  `summary`; a boxed dashboard stat band → `kpi_strip`; a drill-down facet browser over a large
+  population → `breakdown`.
 - **`use_selection`** — `useSelection`: always-on multi-select state for a register/list —
   the `selected` Set + `toggle`/`setAll`/`allSelected`/`indeterminate`/`count`/`clear`;
   selectability gating stays with the caller. The checkbox-always-visible counterpart to

package/docs/composition.md

@@ -264,9 +264,13 @@ objects — hairlines between them blur into one run-on list.
 | Altitude | Component | Where | Shape |
 |---|---|---|---|
 | Dashboard | `<KPIStrip items={[{label, value, trend?, caption?, tone?, compact?, info?}…]}>` | TOP of a dashboard | a boxed stat band — a `Card` of `KPICard` columns |
-| Register / list | `<SummaryLine items={[{label, value, tone?, compact?, trend?, info?}…]}>` | BELOW the toolbar | a light inline line — a small `Metric` + muted label per item |
+| Register / list | `<SummaryLine items={[{label, value, tone?, compact?, trend?, info?, color?}…]}>` | BELOW the toolbar | a light inline line — a small `Metric` + muted label per item |
+| Register / list, with a SHAPE | `<Summary buckets={…}><Summary.Header>…</Summary.Header><Summary.Distribution/><Summary.Facts/></Summary>` | BELOW the toolbar | headline figure + distribution bar + the buckets named, all derived from one bucket list |
 
-A `SummaryLine` is recomputed from the FILTERED rows so it always describes WHAT'S SHOWN. Both are
+`SummaryLine` is `Summary`'s `Facts` row on its own — reach for the compound when the set has a
+distribution worth drawing, and for the bare line when it is only a few aggregates. A
+`SummaryLine`'s `color` exists so it can double as the bar's legend without giving up its `info`
+popovers. Both are recomputed from the FILTERED rows so they always describe WHAT'S SHOWN. Both are
 INFORMATIONAL — they never filter or navigate (that's the tabs/chips' job); if there are no
 cross-cutting numbers, drop them. Do NOT put a `KPIStrip` on a register page or a `SummaryLine` on
 a dashboard. Card stat rails use `KPICard`.
@@ -474,6 +478,23 @@ content per column and set `flex` from that. A column whose cell holds a PROPORT
 bar) is the exception in one direction only: cap it, because a gauge stops reading as an
 instrument once its track is long enough to be a rule across the row.
 
+**The FIXED columns' widths are the flexible one's budget — so audit them by what they CARRY,
+not by what they are called.** With one `flex` column among N fixed, every pixel a fixed column
+takes comes out of the flexible one, silently and with no measurement pointing at the culprit:
+the symptom appears somewhere else entirely, as truncated content in the column that was
+supposed to have room. The usual offender is a column sized by its HEADER over single-character
+data — a long label above a column of one-digit counts reserves width for a word nobody reads
+twice, and the register's identity column pays for it. Measure the header row's cells and the
+widest CELL content per column; where a column's width is set by its label rather than its
+values, that difference is the identity column's, not its own.
+
+**Space by the RATIO of within-group to between-group, never by absolutes.** Collect the gap
+inside a composed band and the gap between that band and its neighbours, and divide. Near 1 is
+the defect however sensible each number is alone — at 14 inside against 16 between, a headline,
+a chart and a register read as one undifferentiated stack, because nothing on the screen is
+grouped. Aim for roughly 2 or more, and change the BETWEEN gap first: tightening the inside
+crowds the group to buy separation the page should have provided.
+
 Make a register SELECTABLE with the `Table` `leading` gutter + `selectAll` slot — a
 `CheckboxInput` per `TableRow` (its `leading` slot) + a select-all in the header band, the ticked
 rows `marked`, paired with a `FloatingActionBar` (its "Clear" escape is locale-resolved — pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "42.0.0",
+  "version": "42.3.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -8,7 +8,10 @@
       "default": "./src/vite.mjs"
     },
     "./tokens": "./src/tokens.ts",
-    "./colors": "./src/colors.ts",
+    "./colors": {
+      "react-native": "./src/colors.ts",
+      "default": "./src/colors.web.ts"
+    },
     "./deadline": "./src/deadline.ts",
     "./option_badge": "./src/option_badge.tsx",
     "./member_chip": "./src/member_chip.tsx",
@@ -67,6 +70,7 @@
     "./kpi_card": "./src/kpi_card.tsx",
     "./kpi_strip": "./src/kpi_strip.tsx",
     "./summary_line": "./src/summary_line.tsx",
+    "./summary": "./src/summary.tsx",
     "./empty_state": "./src/empty_state.tsx",
     "./error_state": "./src/error_state.tsx",
     "./format_date": "./src/format_date.ts",
@@ -85,7 +89,10 @@
     "./trend_footer": "./src/trend_footer.tsx",
     "./locale": "./src/locale.tsx",
     "./spacing": "./src/spacing.ts",
-    "./theme": "./src/theme.tsx",
+    "./theme": {
+      "react-native": "./src/theme.tsx",
+      "default": "./src/theme.web.tsx"
+    },
     "./progress_bar": "./src/progress_bar.tsx",
     "./form_date_picker": "./src/form_date_picker.tsx",
     "./form_picker": "./src/form_picker.tsx",

package/src/avatar.tsx

@@ -39,7 +39,12 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          { backgroundColor: colors.blue["600"], width: px, height: px },
+          // The initials disc is the one place a member LOOKS like the product,
+          // so it carries the brand accent rather than a fixed blue. NOT a
+          // restyle: `colors.accent` DEFAULTS to this exact blue-600, so an app
+          // that themes nothing renders identical pixels, while one that sets an
+          // accent gets its own hue without this file knowing.
+          { backgroundColor: colors.accent, width: px, height: px },
           style,
         ]}
       >

package/src/avatar.web.tsx

@@ -46,7 +46,12 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          { backgroundColor: colors.blue["600"], width: px, height: px },
+          // The initials disc is the one place a member LOOKS like the product,
+          // so it carries the brand accent rather than a fixed blue. NOT a
+          // restyle: `colors.accent` DEFAULTS to this exact blue-600, so an app
+          // that themes nothing renders identical pixels, while one that sets an
+          // accent gets its own hue without this file knowing.
+          { backgroundColor: colors.accent, width: px, height: px },
           style,
         ]}
       >

package/src/avatar_size.ts

@@ -46,7 +46,16 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
    *  account-menu trigger in a top bar, a prominent row's leading figure. Equals
    *  `CONTROL_HEIGHT` (`control_surface`), so it lines up with the icon buttons
    *  beside it. It was 48, which anchored to nothing: the bar's other controls
-   *  are 40, and a 48px circle among them reads as the one thing that got out. */
+   *  are 40, and a 48px circle among them reads as the one thing that got out.
+   *
+   *  **In a register, the rung follows what the row IS ABOUT, not the density.**
+   *  Where a person is one FIELD of the row — an owner, an assignee beside a
+   *  dozen other columns — the figure is a value like any other and takes `md`.
+   *  Where the person is the row's SUBJECT (a league table of reps, a roster,
+   *  anything grouped BY member), the avatar is that row's leading figure and
+   *  takes this rung; at `md` such a register reads as a list of numbers that
+   *  happens to carry faces. Budget for it: this rung is 12px wider than `md`,
+   *  and in a table it takes those 12 from the flexible column the name is in. */
   lg: 40,
   /** A profile's own header. */
   xl: 72,

package/src/color_tokens.ts

@@ -0,0 +1,422 @@
+const palette = {
+  black: "rgba(0,0,0,1)",
+  white: "rgba(255,255,255,1)",
+
+  // We use RGBA so that we can use React Native Animations with colors
+  red: {
+    50: "rgba(254, 242, 242, 1)",
+    100: "rgba(254, 226, 226, 1)",
+    200: "rgba(254, 202, 202, 1)",
+    300: "rgba(252, 165, 165, 1)",
+    400: "rgba(248, 113, 113, 1)",
+    500: "rgba(239, 68, 68, 1)",
+    600: "rgba(220, 38, 38, 1)",
+    700: "rgba(185, 28, 28, 1)",
+    800: "rgba(153, 27, 27, 1)",
+    900: "rgba(127, 29, 29, 1)",
+    950: "rgba(69, 10, 10, 1)",
+  },
+  orange: {
+    50: "rgba(255, 247, 237, 1)",
+    100: "rgba(255, 237, 213, 1)",
+    200: "rgba(254, 215, 170, 1)",
+    300: "rgba(253, 186, 116, 1)",
+    400: "rgba(251, 146, 60, 1)",
+    500: "rgba(249, 115, 22, 1)",
+    600: "rgba(234, 88, 12, 1)",
+    700: "rgba(194, 65, 12, 1)",
+    800: "rgba(154, 52, 18, 1)",
+    900: "rgba(124, 45, 18, 1)",
+    950: "rgba(67, 20, 7, 1)",
+  },
+  amber: {
+    50: "rgba(255, 251, 235, 1)",
+    100: "rgba(254, 243, 199, 1)",
+    200: "rgba(253, 230, 138, 1)",
+    300: "rgba(252, 211, 77, 1)",
+    400: "rgba(251, 191, 36, 1)",
+    500: "rgba(245, 158, 11, 1)",
+    600: "rgba(217, 119, 6, 1)",
+    700: "rgba(180, 83, 9, 1)",
+    800: "rgba(146, 64, 14, 1)",
+    900: "rgba(120, 53, 15, 1)",
+    950: "rgba(69, 26, 3, 1)",
+  },
+  yellow: {
+    50: "rgba(254, 252, 232, 1)",
+    100: "rgba(254, 249, 195, 1)",
+    200: "rgba(254, 240, 138, 1)",
+    300: "rgba(253, 224, 71, 1)",
+    400: "rgba(250, 204, 21, 1)",
+    500: "rgba(234, 179, 8, 1)",
+    600: "rgba(202, 138, 4, 1)",
+    700: "rgba(161, 98, 7, 1)",
+    800: "rgba(133, 77, 14, 1)",
+    900: "rgba(113, 63, 18, 1)",
+    950: "rgba(66, 32, 6, 1)",
+  },
+  lime: {
+    50: "rgba(247, 254, 231, 1)",
+    100: "rgba(236, 252, 203, 1)",
+    200: "rgba(217, 249, 157, 1)",
+    300: "rgba(190, 242, 100, 1)",
+    400: "rgba(163, 230, 53, 1)",
+    500: "rgba(132, 204, 22, 1)",
+    600: "rgba(101, 163, 13, 1)",
+    700: "rgba(77, 124, 15, 1)",
+    800: "rgba(63, 98, 18, 1)",
+    900: "rgba(54, 83, 20, 1)",
+    950: "rgba(26, 46, 5, 1)",
+  },
+  green: {
+    50: "rgba(240, 253, 244, 1)",
+    100: "rgba(220, 252, 231, 1)",
+    200: "rgba(187, 247, 208, 1)",
+    300: "rgba(134, 239, 172, 1)",
+    400: "rgba(74, 222, 128, 1)",
+    500: "rgba(34, 197, 94, 1)",
+    600: "rgba(22, 163, 74, 1)",
+    700: "rgba(21, 128, 61, 1)",
+    800: "rgba(22, 101, 52, 1)",
+    900: "rgba(20, 83, 45, 1)",
+    950: "rgba(5, 46, 22, 1)",
+  },
+  emerald: {
+    50: "rgba(236, 253, 245, 1)",
+    100: "rgba(209, 250, 229, 1)",
+    200: "rgba(167, 243, 208, 1)",
+    300: "rgba(110, 231, 183, 1)",
+    400: "rgba(52, 211, 153, 1)",
+    500: "rgba(16, 185, 129, 1)",
+    600: "rgba(5, 150, 105, 1)",
+    700: "rgba(4, 120, 87, 1)",
+    800: "rgba(6, 95, 70, 1)",
+    900: "rgba(6, 78, 59, 1)",
+    950: "rgba(2, 44, 34, 1)",
+  },
+  teal: {
+    50: "rgba(240, 253, 250, 1)",
+    100: "rgba(204, 251, 241, 1)",
+    200: "rgba(153, 246, 228, 1)",
+    300: "rgba(94, 234, 212, 1)",
+    400: "rgba(45, 212, 191, 1)",
+    500: "rgba(20, 184, 166, 1)",
+    600: "rgba(13, 148, 136, 1)",
+    700: "rgba(15, 118, 110, 1)",
+    800: "rgba(17, 94, 89, 1)",
+    900: "rgba(19, 78, 74, 1)",
+    950: "rgba(4, 47, 46, 1)",
+  },
+  cyan: {
+    50: "rgba(236, 254, 255, 1)",
+    100: "rgba(207, 250, 254, 1)",
+    200: "rgba(165, 243, 252, 1)",
+    300: "rgba(103, 232, 249, 1)",
+    400: "rgba(34, 211, 238, 1)",
+    500: "rgba(6, 182, 212, 1)",
+    600: "rgba(8, 145, 178, 1)",
+    700: "rgba(14, 116, 144, 1)",
+    800: "rgba(21, 94, 117, 1)",
+    900: "rgba(22, 78, 99, 1)",
+    950: "rgba(8, 51, 68, 1)",
+  },
+  sky: {
+    50: "rgba(240, 249, 255, 1)",
+    100: "rgba(224, 242, 254, 1)",
+    200: "rgba(186, 230, 253, 1)",
+    300: "rgba(125, 211, 252, 1)",
+    400: "rgba(56, 189, 248, 1)",
+    500: "rgba(14, 165, 233, 1)",
+    600: "rgba(2, 132, 199, 1)",
+    700: "rgba(3, 105, 161, 1)",
+    800: "rgba(7, 89, 133, 1)",
+    900: "rgba(12, 74, 110, 1)",
+    950: "rgba(8, 47, 73, 1)",
+  },
+  blue: {
+    50: "rgba(239, 246, 255, 1)",
+    100: "rgba(219, 234, 254, 1)",
+    200: "rgba(191, 219, 254, 1)",
+    300: "rgba(147, 197, 253, 1)",
+    400: "rgba(96, 165, 250, 1)",
+    500: "rgba(59, 130, 246, 1)",
+    600: "rgba(37, 99, 235, 1)",
+    700: "rgba(29, 78, 216, 1)",
+    800: "rgba(30, 64, 175, 1)",
+    900: "rgba(30, 58, 138, 1)",
+    950: "rgba(23, 37, 84, 1)",
+  },
+  indigo: {
+    50: "rgba(238, 242, 255, 1)",
+    100: "rgba(224, 231, 255, 1)",
+    200: "rgba(199, 210, 254, 1)",
+    300: "rgba(165, 180, 252, 1)",
+    400: "rgba(129, 140, 248, 1)",
+    500: "rgba(99, 102, 241, 1)",
+    600: "rgba(79, 70, 229, 1)",
+    700: "rgba(67, 56, 202, 1)",
+    800: "rgba(55, 48, 163, 1)",
+    900: "rgba(49, 46, 129, 1)",
+    950: "rgba(30, 27, 75, 1)",
+  },
+  violet: {
+    50: "rgba(245, 243, 255, 1)",
+    100: "rgba(237, 233, 254, 1)",
+    200: "rgba(221, 214, 254, 1)",
+    300: "rgba(196, 181, 253, 1)",
+    400: "rgba(167, 139, 250, 1)",
+    500: "rgba(139, 92, 246, 1)",
+    600: "rgba(124, 58, 237, 1)",
+    700: "rgba(109, 40, 217, 1)",
+    800: "rgba(91, 33, 182, 1)",
+    900: "rgba(76, 29, 149, 1)",
+    950: "rgba(46, 16, 101, 1)",
+  },
+  purple: {
+    50: "rgba(250, 245, 255, 1)",
+    100: "rgba(243, 232, 255, 1)",
+    200: "rgba(233, 213, 255, 1)",
+    300: "rgba(216, 180, 254, 1)",
+    400: "rgba(192, 132, 252, 1)",
+    500: "rgba(168, 85, 247, 1)",
+    600: "rgba(147, 51, 234, 1)",
+    700: "rgba(126, 34, 206, 1)",
+    800: "rgba(107, 33, 168, 1)",
+    900: "rgba(88, 28, 135, 1)",
+    950: "rgba(59, 7, 100, 1)",
+  },
+  fuchsia: {
+    50: "rgba(253, 244, 255, 1)",
+    100: "rgba(250, 232, 255, 1)",
+    200: "rgba(245, 208, 254, 1)",
+    300: "rgba(240, 171, 252, 1)",
+    400: "rgba(232, 121, 249, 1)",
+    500: "rgba(217, 70, 239, 1)",
+    600: "rgba(192, 38, 211, 1)",
+    700: "rgba(162, 28, 175, 1)",
+    800: "rgba(134, 25, 143, 1)",
+    900: "rgba(112, 26, 117, 1)",
+    950: "rgba(74, 4, 78, 1)",
+  },
+  pink: {
+    50: "rgba(253, 242, 248, 1)",
+    100: "rgba(252, 231, 243, 1)",
+    200: "rgba(251, 207, 232, 1)",
+    300: "rgba(249, 168, 212, 1)",
+    400: "rgba(244, 114, 182, 1)",
+    500: "rgba(236, 72, 153, 1)",
+    600: "rgba(219, 39, 119, 1)",
+    700: "rgba(190, 24, 93, 1)",
+    800: "rgba(157, 23, 77, 1)",
+    900: "rgba(131, 24, 67, 1)",
+    950: "rgba(80, 7, 36, 1)",
+  },
+  rose: {
+    50: "rgba(255, 241, 242, 1)",
+    100: "rgba(255, 228, 230, 1)",
+    200: "rgba(254, 205, 211, 1)",
+    300: "rgba(253, 164, 175, 1)",
+    400: "rgba(251, 113, 133, 1)",
+    500: "rgba(244, 63, 94, 1)",
+    600: "rgba(225, 29, 72, 1)",
+    700: "rgba(190, 18, 60, 1)",
+    800: "rgba(159, 18, 57, 1)",
+    900: "rgba(136, 19, 55, 1)",
+    950: "rgba(76, 5, 25, 1)",
+  },
+  slate: {
+    50: "rgba(248, 250, 252, 1)",
+    100: "rgba(241, 245, 249, 1)",
+    200: "rgba(226, 232, 240, 1)",
+    300: "rgba(203, 213, 225, 1)",
+    400: "rgba(148, 163, 184, 1)",
+    500: "rgba(100, 116, 139, 1)",
+    600: "rgba(71, 85, 105, 1)",
+    700: "rgba(51, 65, 85, 1)",
+    800: "rgba(30, 41, 59, 1)",
+    900: "rgba(15, 23, 42, 1)",
+    950: "rgba(2, 6, 23, 1)",
+  },
+  gray: {
+    50: "rgba(249, 250, 251, 1)",
+    100: "rgba(243, 244, 246, 1)",
+    200: "rgba(229, 231, 235, 1)",
+    300: "rgba(209, 213, 219, 1)",
+    400: "rgba(156, 163, 175, 1)",
+    500: "rgba(107, 114, 128, 1)",
+    600: "rgba(75, 85, 99, 1)",
+    700: "rgba(55, 65, 81, 1)",
+    800: "rgba(31, 41, 55, 1)",
+    900: "rgba(17, 24, 39, 1)",
+    950: "rgba(3, 7, 18, 1)",
+  },
+  zinc: {
+    50: "rgba(250, 250, 250, 1)",
+    100: "rgba(244, 244, 245, 1)",
+    200: "rgba(228, 228, 231, 1)",
+    300: "rgba(212, 212, 216, 1)",
+    400: "rgba(161, 161, 170, 1)",
+    500: "rgba(113, 113, 122, 1)",
+    600: "rgba(82, 82, 91, 1)",
+    700: "rgba(63, 63, 70, 1)",
+    800: "rgba(39, 39, 42, 1)",
+    900: "rgba(24, 24, 27, 1)",
+    950: "rgba(9, 9, 11, 1)",
+  },
+  neutral: {
+    50: "rgba(250, 250, 250, 1)",
+    100: "rgba(245, 245, 245, 1)",
+    200: "rgba(229, 229, 229, 1)",
+    300: "rgba(212, 212, 212, 1)",
+    400: "rgba(163, 163, 163, 1)",
+    500: "rgba(115, 115, 115, 1)",
+    600: "rgba(82, 82, 82, 1)",
+    700: "rgba(64, 64, 64, 1)",
+    800: "rgba(38, 38, 38, 1)",
+    900: "rgba(23, 23, 23, 1)",
+    950: "rgba(10, 10, 10, 1)",
+  },
+  stone: {
+    50: "rgba(250, 250, 249, 1)",
+    100: "rgba(245, 245, 244, 1)",
+    200: "rgba(231, 229, 228, 1)",
+    300: "rgba(214, 211, 209, 1)",
+    400: "rgba(168, 162, 158, 1)",
+    500: "rgba(120, 113, 108, 1)",
+    600: "rgba(87, 83, 78, 1)",
+    700: "rgba(68, 64, 60, 1)",
+    800: "rgba(41, 37, 36, 1)",
+    900: "rgba(28, 25, 23, 1)",
+    950: "rgba(12, 10, 9, 1)",
+  },
+};
+
+/**
+ * THE THREE THEMEABLE ROLES are `background`, `border` and `accent` — and
+ * deliberately nothing else. See `colors.web.ts`, which redefines exactly
+ * these as CSS variables so an app can carry its own identity.
+ *
+ * The line is drawn at MEANING, not at convenience. A palette family
+ * (`red`, `amber`, `emerald`, `zinc`…) is how this system says what something
+ * IS — a status, a valence, a series — so letting an app repaint those would
+ * not restyle the product, it would make it lie. What is left over is chrome:
+ * the paper, the paper's edge, and the one hue that is the customer's rather
+ * than ours. An app can own all of that and change no claim the UI makes.
+ *
+ * This file is the CONTRACT and stays literal: TypeScript resolves `./colors`
+ * here (never the `.web` variant), so both files must carry the same keys or an
+ * app reading `colors.accent` would fail to typecheck against the platform it
+ * actually runs on. It is also what native renders, where `var()` means nothing.
+ */
+export const colors = {
+  ...palette,
+  border: palette.zinc["200"],
+  border_shadow: `0px 1px 2px 0px ${palette.zinc["200"]}`,
+  /** A RAISED surface — Card, Drawer, Modal, the things that sit on the page. */
+  background: palette.white,
+  /**
+   * The one brand hue, and its reach is narrower than the word suggests: it
+   * paints IDENTITY marks — today the avatar's initials disc, the one place a
+   * person is rendered as a coloured shape, on every register in every app.
+   *
+   * It deliberately does NOT paint interaction chrome. The focus ring is
+   * `zinc[900]` and the primary action is near-black because those are the KIT's
+   * semantics, shared across every app so a reader learns them once; repainting
+   * them per tenant would make "what does a focus ring look like" a per-app
+   * question. And never for DATA: a series, a status and a valence all come from
+   * a palette family, so an accent can never overwrite a meaning.
+   */
+  accent: palette.blue["600"],
+  shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,
+};
+
+/**
+ * A low-alpha wash of a palette color (hover tints, dimmed chart segments,
+ * icon discs). Handles the palette's rgba() strings plus rgb()/#RRGGBB.
+ */
+export function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith("rgba(")) return color.replace(/,\s*[\d.]+\s*\)\s*$/, `, ${alpha})`);
+  if (color.startsWith("rgb(")) return color.replace("rgb(", "rgba(").replace(/\)\s*$/, `, ${alpha})`);
+  if (color.startsWith("#") && color.length === 7) {
+    return `${color}${Math.round(alpha * 255)
+      .toString(16)
+      .padStart(2, "0")}`;
+  }
+  return color;
+}
+
+/**
+ * A palette FAMILY name — the single, semantic way to reference a color across
+ * the system (Badge, status indicators, chart series, breakdown segments).
+ * Reference colors by NAME and let the component resolve the shade it needs;
+ * never thread a raw hex through props — it drifts (one call site picks 500,
+ * another 600, and the same "status" renders two greens). Excludes every
+ * non-scale role key — the four themeable roles included, since `solid("accent")`
+ * would otherwise typecheck and hand back `undefined` from a family that has no
+ * shades.
+ */
+export type ColorName = Exclude<
+  keyof typeof colors,
+  "border" | "border_shadow" | "background" | "accent" | "shadow" | "black" | "white"
+>;
+
+/**
+ * The canonical SOLID shade of a family (500) — status dots, status-grid
+ * cells, breakdown segments, chart series. Defined ONCE so every indicator of
+ * the same color agrees on the shade.
+ */
+export function solid(name: ColorName): string {
+  return colors[name][500];
+}
+
+/** A low-alpha wash of a family's solid shade — cell/segment tints, dimmed
+ *  states. `tint("emerald", 0.2)` === `withAlpha(solid("emerald"), 0.2)`. */
+export function tint(name: ColorName, alpha: number): string {
+  return withAlpha(solid(name), alpha);
+}
+
+/** Dark → light stops a `ramp` spans (the usable mid range of a scale). */
+const RAMP_STOPS = [700, 600, 500, 400, 300, 200] as const;
+
+/**
+ * `count` distinct shades of ONE family, strong → light — the monochrome
+ * "one hue family per dimension" data ramp (a Breakdown's segments, an ordered
+ * funnel, any multi-category breakdown of a single dimension). Use this for a
+ * COHERENT dimension instead of hand-picking shades or scattering hues; the
+ * segment LABEL carries identity, the shade only orders. (For semantic
+ * categories whose color carries MEANING — status — give each its own
+ * `ColorName` and `solid()` it, don't ramp.)
+ */
+export function ramp(name: ColorName, count: number): string[] {
+  const scale = colors[name];
+  if (count <= 1) return [scale[600]];
+  return Array.from({ length: count }, (_, i) => {
+    const idx = Math.round((i / (count - 1)) * (RAMP_STOPS.length - 1));
+    return scale[RAMP_STOPS[idx]];
+  });
+}
+
+/**
+ * Is `value` a usable {@link ColorName} — a palette FAMILY, not a role key
+ * (`border`/`background`/…) and not `black`/`white`? A family resolves to a
+ * shade object; the role/scalar keys resolve to a string, so "value is an
+ * object" is the test (no name list to keep in sync).
+ */
+export function isColorName(value: unknown): value is ColorName {
+  return (
+    typeof value === "string" &&
+    value in colors &&
+    typeof (colors as Record<string, unknown>)[value] === "object"
+  );
+}
+
+/**
+ * Coerce an arbitrary color token to a {@link ColorName}, falling back to a
+ * neutral. The single graceful-degradation point for stored option/status
+ * colors: a select option's `color` may be a token a newer table config
+ * introduced that this UI build predates, or absent entirely — either way a
+ * component renders a neutral badge instead of breaking. Used by `OptionBadge`.
+ */
+export function asColorName(value: unknown, fallback: ColorName = "zinc"): ColorName {
+  return isColorName(value) ? value : fallback;
+}