@kitn.ai/ui 0.26.0 → 0.28.0

package/src/ui/select.tsx

@@ -0,0 +1,168 @@
+import { type JSX, For, Show, createEffect, splitProps } from 'solid-js';
+import { ChevronDown } from 'lucide-solid';
+import { cn } from '../utils/cn';
+import { FIELD_BASE, FIELD_INVALID } from './input';
+
+/** One choice in a {@link Select}. */
+export interface SelectOption<T = string> {
+  /** The value this row selects. Compared to the select's `value` by identity. */
+  value: T;
+  /** Visible text. Defaults to `String(value)`. Native `<option>`s hold text, not markup. */
+  label?: string;
+  /** Disable this option alone (the select's `disabled` disables the whole control). */
+  disabled?: boolean;
+}
+
+export interface SelectProps<T = string>
+  extends Omit<JSX.SelectHTMLAttributes<HTMLSelectElement>, 'value' | 'children'> {
+  /**
+   * The choices, in display order. Rendered in full: the kit never truncates,
+   * re-orders or de-duplicates a consumer's option list.
+   *
+   * Omit it and pass `children` instead when you need `<optgroup>`s or anything else
+   * a flat list cannot express.
+   */
+  options?: readonly SelectOption<T>[];
+  /**
+   * The selected value, matched against each option's `value` by IDENTITY (so a
+   * numeric enum selects on the number, not on its string form). Pass an array for a
+   * `multiple` select.
+   */
+  value?: T | readonly T[];
+  /**
+   * Text for a leading, disabled, empty-valued option — the "nothing chosen yet" row.
+   * Omitted means no such row is rendered at all; there is no default placeholder,
+   * because inventing one would put words in the consumer's UI.
+   */
+  placeholder?: string;
+  /** Force the invalid (destructive-border) state. Matches `Input`'s. */
+  invalid?: boolean;
+  /** Raw `<option>` / `<optgroup>` children, for lists `options` cannot express.
+   *  `value` still drives the selection when you use these: it is applied to the
+   *  rendered options rather than quietly doing nothing. */
+  children?: JSX.Element;
+  /** Extra classes for the positioning wrapper that holds the chevron. */
+  containerClass?: string;
+}
+
+/**
+ * A select. A REAL native `<select>` behind `appearance: none`, in a box consistent
+ * with {@link Input}, with the kit's own chevron drawn over it.
+ *
+ * **Native, not a listbox, and that is the design.** A hand-built popup can be made to
+ * look identical and cannot be made to behave identically: the native control brings
+ * the platform picker on mobile, type-ahead on desktop, form participation, and the
+ * OS's own accessibility tree. This kit's control audit found every one of its
+ * accessibility defects in a control that had replaced a native element.
+ *
+ * The trade is that the *dropdown list itself* stays OS chrome — it renders outside the
+ * page and no stylesheet reaches it. What the kit can do is make it follow the kit's
+ * light/dark mode rather than the OS's, which `color-scheme` on the element host
+ * already does (`src/elements/styles.css`). Styling the closed control and leaving the
+ * open list to the platform is the whole of the bargain.
+ *
+ * Everything not listed in `SelectProps` is forwarded to the `<select>`, so `id`,
+ * `name`, `required`, `disabled`, `multiple`, `size`, `aria-*`, any `data-*` hook and
+ * the DOM events behave exactly as they do on a plain select. No validation is
+ * applied: `required` reaches the native attribute and stops there.
+ *
+ * ```tsx
+ * <Select
+ *   options={[{ value: 'low' }, { value: 'high', label: 'High priority' }]}
+ *   value={sev()}
+ *   placeholder="Choose a severity…"
+ *   onChange={(e) => setSev(e.currentTarget.value)}
+ * />
+ * ```
+ */
+export function Select<T = string>(props: SelectProps<T>): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'class', 'containerClass', 'options', 'value', 'placeholder', 'invalid', 'children', 'ref',
+  ]);
+
+  // A `multiple` select is a scrolling list box, not a closed control: there is no
+  // collapsed state for a chevron to point at, and `appearance: none` on one buys
+  // nothing. So the custom chrome applies to the single-value shape only.
+  const isMulti = () => !!rest.multiple;
+
+  const isSelected = (v: T): boolean => {
+    const sel = local.value;
+    if (Array.isArray(sel)) return (sel as readonly T[]).includes(v);
+    return sel === v;
+  };
+
+  // Nothing chosen yet, for deciding whether the placeholder row is the selected one.
+  // Array-aware on purpose: an empty array means nothing is selected, and without this
+  // branch the browser would fall through to auto-selecting the first NON-disabled
+  // option — i.e. showing a real choice while the caller's state said none was made.
+  const isEmpty = (): boolean => {
+    const v = local.value;
+    if (Array.isArray(v)) return v.length === 0;
+    return v === undefined || v === null || (v as unknown) === '';
+  };
+
+  return (
+    <div class={cn('relative block w-full', local.containerClass)}>
+      <select
+        {...rest}
+        ref={(el) => {
+          // `ref` is split out and re-applied by hand because this component needs the
+          // element itself for the `children` path below. Solid always hands a component
+          // a ref FUNCTION (a variable ref compiles into one), so the typeof guard is for
+          // the hand-written object case only.
+          const forward = local.ref;
+          if (typeof forward === 'function') (forward as (el: HTMLSelectElement) => void)(el);
+
+          // `value` drives the `options` list declaratively (each `<option selected>`),
+          // which cannot reach options the CALLER rendered as `children`. Applying it
+          // imperatively for that path is the difference between "children are an
+          // escape hatch" and "`value` silently does nothing once you use one".
+          createEffect(() => {
+            if (local.children === undefined) return;
+            const v = local.value;
+            if (v === undefined || v === null) return;
+            if (Array.isArray(v)) {
+              const wanted = new Set((v as readonly unknown[]).map(String));
+              for (const o of el.options) o.selected = wanted.has(o.value);
+            } else {
+              el.value = String(v);
+            }
+          });
+        }}
+        class={cn(
+          FIELD_BASE,
+          // `peer` so the chevron beside it can dim with the control.
+          'peer',
+          // `pr-9` reserves the lane the chevron sits in, so a long option label never
+          // slides under it.
+          !isMulti() && 'cursor-pointer appearance-none pr-9',
+          local.invalid && FIELD_INVALID,
+          local.class,
+        )}
+      >
+        <Show when={local.placeholder !== undefined}>
+          <option value="" disabled selected={isEmpty()}>
+            {local.placeholder}
+          </option>
+        </Show>
+        <For each={local.options}>
+          {(opt) => (
+            <option value={String(opt.value)} disabled={opt.disabled} selected={isSelected(opt.value)}>
+              {opt.label ?? String(opt.value)}
+            </option>
+          )}
+        </For>
+        {local.children}
+      </select>
+      <Show when={!isMulti()}>
+        {/* `pointer-events-none` so the chevron is decoration and every click, including
+            one landing on the arrow, still opens the native picker. `aria-hidden`
+            because the select already announces itself as a combo box. */}
+        <ChevronDown
+          aria-hidden="true"
+          class="pointer-events-none absolute right-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground peer-disabled:opacity-50"
+        />
+      </Show>
+    </div>
+  );
+}

package/src/ui/slider.tsx

@@ -0,0 +1,178 @@
+import { type JSX, Show, splitProps, createSignal } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface SliderProps
+  extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'type' | 'children' | 'min' | 'max' | 'step' | 'value'> {
+  /**
+   * Lowest selectable value. REQUIRED, and deliberately so.
+   *
+   * A range with no `min`/`max` is not a slider, it is a slider-shaped guess, and the
+   * guess belongs to whoever knows what the number means. `SliderWidget` reading a
+   * JSON-Schema field still defaults an absent `minimum` to 0 — that is the WIDGET's
+   * decision about a consumer-authored schema, and it stays there rather than being
+   * quietly adopted by every caller of this component.
+   */
+  min: number;
+  /** Highest selectable value. REQUIRED for the same reason as `min`. */
+  max: number;
+  /** Granularity. Omitted means the native default (1); `'any'` means continuous. */
+  step?: number | 'any';
+  /** The current value. Controlled — drive it from `onInput`. Omit for uncontrolled. */
+  value?: number;
+  /** Initial value when uncontrolled. */
+  defaultValue?: number;
+  /**
+   * Show the current value beside the track. Off by default.
+   *
+   * Two shapes, because one is not enough and three would be too many. `true` renders
+   * the raw number, which is what most sliders want. A FUNCTION renders whatever it
+   * returns, because plenty of sliders are not counting bare numbers: `60%`, `3 of 5`,
+   * `1m 30s`. A boolean alone cannot express those, and a formatter alone would make
+   * the common case read `valueLabel={(v) => v}`.
+   *
+   * The readout is `aria-hidden`. The input already reports the same number through
+   * `aria-valuenow` / `aria-valuetext`, so an exposed copy would be announced twice.
+   *
+   * NOTE ON STRUCTURE: with a readout the component renders a flex row around the
+   * input; without one it is still a bare `<input>` and nothing changes for existing
+   * callers. Toggling this at runtime therefore rebuilds the input element, which is
+   * fine for a control panel and not something a real app does mid-drag.
+   */
+  valueLabel?: boolean | ((value: number) => JSX.Element);
+}
+
+/**
+ * A slider. A REAL `<input type="range">` behind `appearance: none`, styled by the
+ * kit's `.kai-range` rule, never a `<div>` with a drag handler.
+ *
+ * The native control brings the whole keyboard contract (arrows, Home, End,
+ * PageUp/PageDown), pointer and touch dragging, form participation via `name`, and
+ * the `slider` role with a live value announcement — all of it for free and all of it
+ * correct. Every accessibility defect this kit's control audit found was in a control
+ * that had replaced the native element with something hand-rolled.
+ *
+ * What the component adds is the **filled track**. `.kai-range` paints the portion
+ * left of the thumb from a `--kai-range-fill` custom property, and until now every
+ * caller computed that percentage itself. It is arithmetic over `min`, `max` and the
+ * current value — three things this component already has — so no consumer should
+ * ever write it again.
+ *
+ * Everything not listed in `SliderProps` is forwarded to the input, so `id`, `name`,
+ * `disabled`, `required`, `aria-*` and any `data-*` hook behave exactly as they do on
+ * a plain `<input>`. No clamping and no validation is applied: a value outside
+ * `min`..`max` is the browser's business, not ours.
+ *
+ * ```tsx
+ * <Slider min={0} max={100} step={5} value={v()} onInput={(e) => setV(e.currentTarget.valueAsNumber)} />
+ * ```
+ */
+export function Slider(props: SliderProps): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'class', 'style', 'min', 'max', 'step', 'value', 'defaultValue', 'ref', 'valueLabel',
+  ]);
+
+  // The uncontrolled mirror. A slider's fill has to follow the thumb even when nobody
+  // is holding the value in a signal, so the component tracks the live value itself
+  // through a NATIVE `on:input` listener. That is `on:` and not `onInput` on purpose:
+  // `onInput` stays in `rest` and reaches the input untouched, so a caller's handler
+  // is neither wrapped nor swallowed, and the two listeners simply both run.
+  const [live, setLive] = createSignal<number | undefined>(props.defaultValue);
+
+  // HTML's own rule for a range with no value: the midpoint of the span. Restated here
+  // rather than left to the browser because the fill has to agree with the thumb on the
+  // very first paint, before any input event exists.
+  const current = () => local.value ?? live() ?? (local.min + local.max) / 2;
+
+  const fill = (): string => {
+    const lo = local.min;
+    const hi = local.max;
+    if (!(hi > lo)) return '0%';
+    // Clamp: a value outside the range is the caller's to fix, but a track painted
+    // 140% wide is a rendering artefact nobody asked for.
+    const pct = ((current() - lo) / (hi - lo)) * 100;
+    return `${Math.min(100, Math.max(0, pct))}%`;
+  };
+
+  // Merge rather than replace: `style` is a legitimate thing to pass a slider, and the
+  // fill is a custom property that has to survive alongside it. Solid accepts either a
+  // string or an object here, so both shapes are handled.
+  const style = (): string | JSX.CSSProperties => {
+    const s = local.style;
+    if (typeof s === 'string') return `${s.replace(/;\s*$/, '')};--kai-range-fill:${fill()}`;
+    return { ...(s ?? {}), '--kai-range-fill': fill() } as JSX.CSSProperties;
+  };
+
+  // CONTROLLED-MODE RECONCILIATION. A controlled `<input type="range">` in Solid can
+  // drift: the browser moves the thumb on a drag, and if the caller's `value` does not
+  // change in response, the bound expression is unchanged, so Solid never writes the
+  // DOM back. The thumb ends up somewhere the component's own state says it is not —
+  // and because the fill is derived from `value`, the two visibly DISAGREE. That is the
+  // exact symptom reported against the Storybook Playground: thumb slides, track does
+  // not. A pinned, writer-less `<Slider value={40} />` is a legitimate thing to render,
+  // and it should look pinned rather than half-moved.
+  //
+  // WHY A MICROTASK AND NOT THE HANDLER OR A BARE EFFECT. Both of those run too early
+  // and would break the ordinary controlled case. The `on:input` listener above is
+  // attached to the TARGET, so it runs before the caller's `onInput`, which Solid
+  // delegates at the document; snapping back there would hand the caller's handler a
+  // value we had already reset. A `createEffect` is flushed at the end of the update
+  // that `setLive` starts, which is still inside the target listener and therefore also
+  // before the delegated one. A microtask runs after the whole event turn: every input
+  // listener has run and any signal the caller set has propagated, so a value that
+  // still disagrees means the caller genuinely did not accept the edit.
+  let el: HTMLInputElement | undefined;
+  const reconcileControlled = () => {
+    const v = local.value;
+    // Uncontrolled: `live` is the truth and the DOM is already showing it.
+    if (v === undefined || el === undefined) return;
+    if (el.valueAsNumber !== v) el.value = String(v);
+  };
+
+  const readout = (): JSX.Element => {
+    const vl = local.valueLabel;
+    return typeof vl === 'function' ? vl(current()) : current();
+  };
+
+  const control = () => (
+    <input
+      {...rest}
+      type="range"
+      class={cn('kai-range', local.class)}
+      style={style()}
+      min={local.min}
+      max={local.max}
+      step={local.step}
+      value={local.value ?? live() ?? undefined}
+      ref={(node) => {
+        // `ref` is split out and re-applied by hand because this component needs the
+        // element for the reconciliation above. Solid always hands a component a ref
+        // FUNCTION (a variable ref compiles into one), so the typeof guard is for the
+        // hand-written object case only.
+        el = node;
+        const forward = local.ref;
+        if (typeof forward === 'function') (forward as (n: HTMLInputElement) => void)(node);
+      }}
+      on:input={(e) => {
+        setLive((e.currentTarget as HTMLInputElement).valueAsNumber);
+        queueMicrotask(reconcileControlled);
+      }}
+    />
+  );
+
+  return (
+    <Show when={local.valueLabel} fallback={control()}>
+      <div class="flex items-center gap-3">
+        {control()}
+        {/* aria-hidden: the input already announces this number. The readout is a
+            second copy for the eyes only, and exposing it would double the
+            announcement on every step of a drag. */}
+        <span
+          aria-hidden="true"
+          class="min-w-9 shrink-0 rounded-md bg-background px-2 py-1 text-center text-sm font-medium tabular-nums text-foreground shadow-sm"
+        >
+          {readout()}
+        </span>
+      </div>
+    </Show>
+  );
+}

package/src/ui/switch.tsx

@@ -1,7 +1,12 @@
-import { createSignal } from 'solid-js';
+import { type JSX, createSignal, splitProps } from 'solid-js';
 import { cn } from '../utils/cn';
 
-export interface SwitchProps {
+export interface SwitchProps
+  extends Omit<
+    JSX.ButtonHTMLAttributes<HTMLButtonElement>,
+    | 'type' | 'role' | 'aria-checked' | 'children' | 'ref'
+    | 'onChange' | 'onchange' | 'onClick' | 'onclick' | 'onKeyDown' | 'onkeydown'
+  > {
   /** Controlled checked state. When set, the component defers state to the
    *  parent; drive it from `onChange`. Omit for uncontrolled (internal) state. */
   checked?: boolean;
@@ -26,51 +31,74 @@ export interface SwitchProps {
 /**
  * A toggle switch (`role="switch"`). Controlled via `checked`, or uncontrolled
  * from `defaultChecked`. Keyboard-operable (Space/Enter) and theme-tokened.
+ *
+ * Anything not named in `SwitchProps` is forwarded to the inner button, so `id`,
+ * `aria-required` / `aria-invalid` / `aria-describedby` and any `data-*` hook land
+ * on the focusable element without a caller stamping them through a `ref`. The
+ * switch keeps ownership of `type`, `role`, `aria-checked` and the toggle handlers:
+ * those are the control, not decoration.
  */
 export function Switch(props: SwitchProps) {
-  const [internal, setInternal] = createSignal(props.defaultChecked ?? false);
-  const isControlled = () => props.checked !== undefined;
-  const isOn = () => (isControlled() ? !!props.checked : internal());
+  const [local, rest] = splitProps(props, [
+    'checked', 'defaultChecked', 'disabled', 'label', 'name', 'value', 'onChange', 'buttonRef', 'class',
+  ]);
+  const [internal, setInternal] = createSignal(local.defaultChecked ?? false);
+  const isControlled = () => local.checked !== undefined;
+  const isOn = () => (isControlled() ? !!local.checked : internal());
 
   const toggle = () => {
-    if (props.disabled) return;
+    if (local.disabled) return;
     const next = !isOn();
     if (!isControlled()) setInternal(next);
-    props.onChange?.(next);
+    local.onChange?.(next);
   };
 
   return (
     <>
-      {props.name != null && (
+      {local.name != null && (
         <input
           type="checkbox"
-          name={props.name}
-          value={props.value ?? 'on'}
+          name={local.name}
+          value={local.value ?? 'on'}
           checked={isOn()}
-          disabled={props.disabled}
+          disabled={local.disabled}
           aria-hidden="true"
           tabindex={-1}
           style={{ position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', clip: 'rect(0 0 0 0)', 'white-space': 'nowrap' }}
           onChange={() => { /* driven by the button; keep the input in sync only */ }}
         />
       )}
+      {/* `{...rest}` comes FIRST so the attributes below win: a caller can add an
+          `id` or an `aria-describedby`, but cannot turn this into something that is
+          no longer a switch. */}
       <button
+        {...rest}
         type="button"
         role="switch"
-        ref={props.buttonRef}
+        ref={local.buttonRef}
         aria-checked={isOn()}
-        aria-label={props.label}
-        disabled={props.disabled}
+        aria-label={local.label}
+        disabled={local.disabled}
         onClick={toggle}
         onKeyDown={(e) => {
           if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); toggle(); }
         }}
         class={cn(
-          'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full transition-colors',
+          'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border transition-colors',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
           'disabled:cursor-not-allowed disabled:opacity-50',
-          isOn() ? 'bg-primary' : 'bg-muted',
-          props.class,
+          // WCAG 2.1 SC 1.4.11: the track IS this control's visual boundary, so it
+          // needs 3:1 against the surface behind it. The OFF fill cannot carry that
+          // — `--color-muted` is a shared surface token (measured 1.10:1 light on
+          // `--color-background`) and darkening it to clear 3:1 would repaint every
+          // muted surface in the kit. So the boundary moves to a border on the
+          // control-edge token `--color-input`, which exists for exactly this and is
+          // already held to the 3:1 floor for radios, checkboxes and inputs
+          // (tests/primitives/control-contrast.test.ts). The ON track keeps its
+          // ~17:1 `--color-primary` fill and takes a transparent border purely so
+          // the two states stay the same size — the fill still paints under it.
+          isOn() ? 'border-transparent bg-primary' : 'border-input bg-muted',
+          local.class,
         )}
       >
         <span
@@ -79,7 +107,10 @@ export function Switch(props: SwitchProps) {
             // On the `primary` track use `primary-foreground` so the thumb stays
             // visible in both themes (in dark mode `primary` is light, where a
             // hard-coded white thumb vanished). Off-track stays white over `muted`.
-            isOn() ? 'translate-x-[1.125rem] bg-primary-foreground' : 'translate-x-0.5 bg-white',
+            // The track is `border-box` with a 1px border, so the thumb travels
+            // inside a 34px box: 2px in from each inner edge keeps both end
+            // positions 3px from the track's outer edge.
+            isOn() ? 'translate-x-4 bg-primary-foreground' : 'translate-x-0.5 bg-white',
           )}
         />
       </button>

package/src/utils/cn.ts

@@ -2,19 +2,25 @@ import { clsx, type ClassValue } from 'clsx';
 import { extendTailwindMerge } from 'tailwind-merge';
 
 // The kit defines custom font-size utilities via @theme tokens in theme.css:
-// text-caption / text-meta / text-body / text-title. tailwind-merge has no way
-// to know these are font sizes, so by default it buckets e.g. `text-body` with
-// text COLORS and drops a real color (`text-transparent`, `text-foreground`, …)
+// text-micro / text-caption / text-meta / text-compact / text-body / text-title.
+// tailwind-merge has no way to know these are font sizes, so by default it
+// buckets `text-body` with text COLORS and drops a real color
+// (`text-transparent`, `text-foreground`, …)
 // whenever both appear in the same cn() call — which silently broke TextShimmer
 // inside the web components (the element adds `text-body`, dropping
 // `text-transparent`, so the gradient stayed hidden behind opaque text).
 //
 // Register them in the `font-size` group so they conflict only with other font
-// sizes (text-xs/sm/base/lg/…) and never with text colors.
+// sizes (text-xs/sm/base/lg/…) and never with text colors. Since theme.css now
+// re-points Tailwind's own scale at the same tokens (text-xs ≡ text-meta,
+// text-sm ≡ text-body, text-base ≡ text-title), the semantic name and its
+// Tailwind alias are literally the same size — so they MUST land in one group
+// or `cn('text-sm', 'text-body')` would emit two classes for one declaration.
+// `text-lg` needs no entry: it is already a stock Tailwind font size.
 const twMerge = extendTailwindMerge({
   extend: {
     classGroups: {
-      'font-size': [{ text: ['caption', 'meta', 'body', 'title'] }],
+      'font-size': [{ text: ['micro', 'caption', 'meta', 'compact', 'body', 'title'] }],
     },
   },
 });

package/theme.css

@@ -74,8 +74,68 @@
      added at the bottom. */
   --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));
   --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));
+  /* UNREAD indicator — a dedicated token (owner ruling, 2026-08-26), not a
+     reuse of --color-destructive: unread is notification semantics, not
+     error, so a consumer re-theming "danger" red must not also move every
+     unread dot. Used identically by all three places an unread conversation
+     surfaces: the list-row trailing dot (ConversationPanel), the header
+     toggle's badge (ChatThread), and Dock's own closed-launcher badge.
+     A vivid "messenger red" (Tailwind red-500 territory, the Intercom/iOS
+     badge convention) rather than the darker --color-destructive hue: the
+     first pass at this token picked a color that read as legible-on-paper
+     but visually flat/dark next to the launcher's near-black ring. This one
+     value is used in BOTH light and dark (no .dark override below) because
+     it independently clears 3:1 (WCAG 1.4.11, non-text) against every real
+     surface an unread dot sits on in EITHER mode: light row/card background
+     (white) 3.78:1, light Dock-launcher ring (--color-primary, near-black)
+     4.68:1, dark row/card background (near-black) 4.73–4.35:1, dark
+     Dock-launcher ring (--color-primary, near-white) 3.62:1. (Measured via
+     the WCAG relative-luminance formula against this file's own light/dark
+     --color-background/-card/-primary values — see
+     .superpowers/sdd/2026-08-26-conversations/rework-report.md Round 4 for
+     the worked numbers.) Override via --kai-color-unread; a construct author
+     can also set it per-widget through `theme.unreadColor` (construct
+     vocabulary — see agent-tooling/construct/schema.ts). */
+  --color-unread: var(--kai-color-unread, hsl(0 84% 60%));
+  /* MARKED text — the fill behind a keyword the app has flagged (the composer's
+     `highlights` rules, decorated through the CSS Custom Highlight API). This is
+     `<mark>`, not a selection and not a status: a warm yellow, the convention
+     every browser already ships for <mark> and every reader already reads as
+     "someone marked this". Deliberately NOT derived from --color-primary — that
+     token is a NEUTRAL near-black in light and near-white in dark, so any tint of
+     it is grey, which is why the highlight used to be invisible. Also not blue
+     (the browser's own ::selection is blue — a highlight must not read as a
+     selection), not red (error) and not the skill/agent pill hues (blue/violet).
+     OPAQUE, so it composites predictably over whichever field it lands on.
+     Override via --kai-color-highlight. Light: near-black text over it is 15.6:1;
+     dark: near-white text over it is 6.7:1 — both well clear of WCAG AA. */
+  --color-highlight: var(--kai-color-highlight, hsl(45 96% 78%));
+  /* SELECTED text — the kit's own ::selection fill, applied inside every kai-*
+     shadow root (see src/elements/styles.css for the scoping rationale). The kit
+     owns this because leaving it to the UA meant the browser's blue outranked the
+     kit's own deliberate emphasis: a marked keyword was LESS prominent than an
+     incidental drag-select. Stays in the cool/blue family the UA trained everyone
+     to read as "selected", so it can never be confused with the warm --color-highlight
+     mark above; OPAQUE, so a selection over a mark composites cleanly (selection
+     paints on top of a custom highlight) instead of muddying into a third colour.
+     The FOREGROUND is set too, and that is not cosmetic: without it the selected
+     glyph keeps its own colour, and the kit's coloured text — muted text (3.8:1),
+     the skill/agent pill hues (3.6:1 / 4.0:1), inline code (4.7:1) — lands at or
+     under WCAG AA on this fill. Forcing the foreground token makes the guarantee
+     hold for every glyph regardless of what colour it had. Light 13.99:1,
+     dark 8.87:1. Override via --kai-color-selection(-foreground). */
+  --color-selection: var(--kai-color-selection, hsl(213 94% 87%));
+  --color-selection-foreground: var(--kai-color-selection-foreground, hsl(240 10% 3.9%));
   --color-border: var(--kai-color-border, hsl(240 5.9% 90%));
-  --color-input: var(--kai-color-input, hsl(240 5.9% 90%));
+  /* CONTROL boundary — the visible edge of an interactive form control (text
+     input, textarea, select, the radio/checkbox ring). WCAG 2.1 SC 1.4.11
+     Non-text Contrast requires >=3:1 against the adjacent surface for exactly
+     this: a control whose boundary you cannot see is not perceivable. That is
+     why this is NOT --color-border: a divider or a card outline is decorative
+     and may sit below 3:1, a control's edge may not. Do NOT use border-input
+     for list wrappers or panel outlines — use border-border there.
+     Contrast is the requirement; a thicker border does not satisfy 1.4.11. */
+  --color-input: var(--kai-color-input, hsl(240 5% 53%));
   /* Focus ring — a deliberate blue (not a neutral) so keyboard focus is always
      obvious and on-brand in both modes. Light uses a strong blue; dark uses a
      brighter one for contrast on dark surfaces. Both clear WCAG 2.1 non-text
@@ -108,18 +168,42 @@
   --radius-lg: var(--radius);
   --radius-xl: calc(var(--radius) + 4px);
 
-  /* Typography scale — semantic sizes shared by all components. Each generates a
-     Tailwind utility (text-caption / text-meta / text-body / text-title). To
-     restyle the kit's typography, override the namespaced --kai-text-* token on
-     :root (e.g. `--kai-text-body: 0.9375rem`) — it pierces the Shadow DOM via the
+  /* Typography scale — ONE scale for the whole kit. Each semantic name
+     (text-micro / text-caption / text-meta / text-compact / text-body /
+     text-title / text-lg)
+     resolves through a namespaced --kai-text-* token, so overriding that token
+     on :root restyles the kit globally — it pierces the Shadow DOM via the
      var() fallback, exactly like the --kai-color-* tokens. The bare --text-*
-     names stay internal so a host's own --text-* can't collide. (Message/markdown/
-     input reading size also scales with the `proseSize` prop; these tokens cover
-     the fixed chrome & controls.) */
-  --text-caption: var(--kai-text-caption, 0.6875rem);  --text-caption--line-height: 1rem;      /* 11px — micro labels, badges, sub-counts */
-  --text-meta: var(--kai-text-meta, 0.75rem);     --text-meta--line-height: 1.1rem;       /* 12px — controls, toggles, switchers, captions */
-  --text-body: var(--kai-text-body, 0.875rem);    --text-body--line-height: 1.45rem;      /* 14px — primary reading text */
-  --text-title: var(--kai-text-title, 1rem);        --text-title--line-height: 1.5rem;      /* 16px — emphasis / headers */
+     names stay internal so a host's own --text-* can't collide.
+
+     Tailwind's OWN scale is re-pointed at the same tokens: in Tailwind v4 the
+     `text-xs` / `text-sm` / `text-base` / `text-lg` utilities are generated FROM
+     --text-xs/sm/base/lg in this very @theme block, so aliasing them makes
+     text-xs ≡ text-meta, text-sm ≡ text-body, text-base ≡ text-title and
+     text-lg ≡ text-lg. That matters because the vast majority of the kit's call
+     sites spell the Tailwind name; without the alias the --kai-text-* knobs
+     reached ~12% of them and the "globally" promise in the theming guide was
+     false. Defaults are byte-identical to stock Tailwind, so nothing moves
+     until a consumer actually sets a --kai-text-* token — including in a
+     consumer's own Tailwind build that imports this file, which is the point:
+     one scale everywhere, kit and app moving together.
+
+     Line-heights are UNITLESS RATIOS (Tailwind's own), never fixed rem. A fixed
+     leading does not scale: --kai-text-body: 1.25rem under the old 1.45rem
+     leading gave 20px text on 23.2px leading — near solid-set — which made the
+     themable token unsafe to actually theme.
+     (Message/markdown reading size also scales with the `proseSize` prop; these
+     tokens cover the fixed chrome & controls.) */
+  --text-micro: var(--kai-text-micro, 0.625rem);      --text-micro--line-height: calc(0.875 / 0.625);   /* 10px — badges, pills, uppercase eyebrows */
+  --text-caption: var(--kai-text-caption, 0.6875rem); --text-caption--line-height: calc(1 / 0.6875);    /* 11px — micro labels, sub-counts, xs code */
+  --text-meta: var(--kai-text-meta, 0.75rem);         --text-meta--line-height: calc(1 / 0.75);         /* 12px — controls, toggles, switchers, captions */
+  --text-xs: var(--kai-text-meta, 0.75rem);           --text-xs--line-height: calc(1 / 0.75);           /* ≡ text-meta */
+  --text-compact: var(--kai-text-compact, 0.8125rem); --text-compact--line-height: calc(1.21875 / 0.8125); /* 13px — dense chrome & code: a notch below body */
+  --text-body: var(--kai-text-body, 0.875rem);        --text-body--line-height: calc(1.25 / 0.875);     /* 14px — primary reading text */
+  --text-sm: var(--kai-text-body, 0.875rem);          --text-sm--line-height: calc(1.25 / 0.875);       /* ≡ text-body */
+  --text-title: var(--kai-text-title, 1rem);          --text-title--line-height: calc(1.5 / 1);         /* 16px — emphasis / headers */
+  --text-base: var(--kai-text-title, 1rem);           --text-base--line-height: calc(1.5 / 1);          /* ≡ text-title */
+  --text-lg: var(--kai-text-lg, 1.125rem);            --text-lg--line-height: calc(1.75 / 1.125);       /* 18px — section headings, lg prose */
 
   @keyframes typing { 0%,100% { transform: translateY(0); opacity: .5 } 50% { transform: translateY(-2px); opacity: 1 } }
   @keyframes loading-dots { 0%,100% { opacity: 0 } 50% { opacity: 1 } }
@@ -180,8 +264,23 @@
   --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));
   --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));
   --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));
+  /* Unread indicator — dark. Same value as light (see the light block for the
+     full contrast note): one vivid red independently clears 3:1 against both
+     modes' real surfaces, so there is nothing to flip here. Still redeclared
+     for override symmetry with every other semantic color in this file. */
+  --color-unread: var(--kai-color-unread, hsl(0 84% 60%));
+  /* Marked text — dark. A deep warm amber rather than the light yellow: a pale
+     highlighter on a near-black field would blow out and force the text to flip
+     colour. See the light block for the full note. */
+  --color-highlight: var(--kai-color-highlight, hsl(40 75% 26%));
+  /* Selected text — dark. A deep blue rather than the light one, for the same
+     reason the mark darkens. See the light block for the full note. */
+  --color-selection: var(--kai-color-selection, hsl(217 60% 32%));
+  --color-selection-foreground: var(--kai-color-selection-foreground, hsl(0 0% 98%));
   --color-border: var(--kai-color-border, hsl(45 4% 17%));
-  --color-input: var(--kai-color-input, hsl(45 4% 17%));
+  /* Control boundary — see the light block. Lifted to clear 3:1 (SC 1.4.11)
+     against the dark background and card surfaces. */
+  --color-input: var(--kai-color-input, hsl(45 4% 48%));
   --color-ring: var(--kai-color-ring, hsl(217 91% 68%));
   --color-scrollbar-thumb: var(--kai-color-scrollbar-thumb, hsl(45 3% 30%));
   --color-scrollbar-thumb-hover: var(--kai-color-scrollbar-thumb-hover, hsl(45 3% 42%));