@titan-design/react-ui 0.12.1 → 0.14.0

package/docs/library-roadmap.md

@@ -0,0 +1,99 @@
+# Library roadmap — decided 2026-09-08
+
+The operator reviewed a deep critique of `packages/ui` (attached as
+`docs/audits/2026-09-08-library-critique.md`) and answered its sixteen
+competing-system questions. This file is the record. When a change touches
+one of these areas, it follows the decision here or reopens it explicitly.
+
+## Standing policies
+
+**Colour.** Every colour used anywhere comes from a colour ramp (`greyRamp`,
+the OKLCH ramps in `theme/tokens/primitives.ts`). Semantic tokens and palettes
+reference ramp steps; components use only semantic tokens. No file declares
+its own colour. The eslint token-purity error block extends to every family;
+the raw-colour baseline (`titan/no-raw-color`) shrinks per PR and is deleted at
+zero. Workout and Fatigue are not dark-only by design: they become theme-correct.
+
+**Consumers.** We own every downstream consumer of `@titan-design/react-ui`
+(audiobook, source-linked; voltras-mcp; agent-chat, tokens only; voltras
+mobile; codewatch; two stale forks). Breaking changes are allowed. A component
+being retired is marked `@deprecated` in code first so no new usage appears,
+and each consumer gets a follow-up task to migrate.
+
+**Depth.** See Foundations/Depth. Tone plus lift (rim 0.12, ambient shadow
+scaled by planes crossed) on every raised plane; floating surfaces carry the
+rim and no hairline ring; lift sparingly, inset inside cards; light mode is
+deferred to its own pass.
+
+## Decisions (critique §B)
+
+| # | Question | Decision |
+|---|---|---|
+| 1 | Container | `Card` is the only content container. `Surface` is for shell roots (shell, page, rail). `Tile` becomes a Card stat preset. `Section`/`SectionHeader` become Card presets (voltras mobile uses them), not deleted. |
+| 2 | numeric vs named elevation | Both public: `level` is absolute for shell roots, `raise`/`elevation` are relative. Landed in #166. |
+| 3 | Pills | One `Pill` primitive (tone / size / leading slot). `Badge`, `Chip`, `StatusPill`, `PrBadge`, `MuscleGroupChip` survive as thin presets (external users). `BaseBadge`, `WorkoutPill`, `SessionStatePill`, `WeightBadge`, `SeverityLabel`, `CoChangeChip` fold in or are deleted. |
+| 4 | Divider | Every rule is a `Divider`. `border-hairline*` is legal only on Card `outline`/`subtle`, Table rules, and input borders. |
+| 5 | HelpTip | Delete `HelpTip` and `LabelWithHelp`; a Tooltip story shows the pattern. |
+| 6 | Theme source | `SurfaceContext`/`ThemeProvider` only. `utils/useTheme.ts` is deleted (Card no longer uses it after #166). |
+| 7 | Workout/Fatigue dark-only? | No. Full theme-correct port (E3), in the batches below. |
+| 8 | Colour math | One `theme/color-math.ts` with CIELAB L* as the sanctioned metric; duplicate `hexToRgb` ×4, `mixHex` ×4, luminance ×3, test `lstar` ×3 deleted. |
+| 9 | Typography | `Typography` and `Eyebrow` move into `ui/`; re-export shims stay in `custom/`. |
+| 10 | Dot | `Indicator` survives. `StatusDot`'s consumers migrate; its inline glows route through `getGlowShadow`. Fatigue README corrected. |
+| 11 | Metric | One `Metric` with size / align / trend. `MetricTiles` becomes a preset (one external site); `MetricCell` deleted (no consumers). |
+| 12 | paperSheet | Stays hero-only. Cards use the lift (rim 0.12); grain is not on ordinary cards. |
+| 13 | Formatters | `utils/format/{number,time,workout}`. No component-local `formatX` or inline `toFixed`; lint enforces after migration. |
+| 14 | Storybook tree | Six groups: `Foundations/` · `Components/Atoms|Molecules|Organisms/` (ui/* only) · `Custom/<Family>/` · `Shell/` · `Pages/` · `Lab/<Family>/` (src/lab only). |
+| 15 | Lint | One mechanism: the per-family token-purity error block, extended everywhere; baseline retired at zero. |
+| 16 | Light mode | Deferred. Task filed. Not a target for any family until the dark port is done. |
+
+## Epics, in order
+
+**E1 · Depth follow-ups** (after #166; starts now)
+- 13 `ui/*` overlays (autocomplete, drawer, help-tip, indicator, menu, modal, popover, select, switch, tabs, toast, toolbar-button, tooltip) move from Tailwind `shadow-*` + hairline ring to the floating lift recipe. Done when `grep -rE "shadow-(sm|md|lg|xl|2xl)" src/components/ui` is empty.
+- Delete `utils/useTheme.ts`.
+- Replace literal-hex pins in `Surface.test.tsx`, `surface.contract.test.ts`, `Card.test.tsx`, `elevation.test.ts` with `greyRamp[...]` references.
+- Purge stale comments: `SessionRail.stories.tsx:40`, `utils/colors.ts:4`, `SessionRail.tsx:16-17`, the skill's `gotchas.md` "Neumorphic depth" section.
+- Delete the `lab/north-star/surfaces.ts` fork and `DualGhostLine`'s local copies; point lab at `theme/materials`.
+- Glow shadows (StatusDot ×7, Indicator, MesoCard, BodyMap, ZoneTrack, IntensityBar, PrHistoryModal) route through `getGlowShadow`.
+
+**E4 · Storybook reorganisation** (can run beside E1 on non-overlapping files)
+- Retitle onto the six-group tree; fix `Composes` links.
+- Move the 8 `Lab/`-titled files out of `src/components` (they publish to npm today).
+- Delete duplicate `Lab/ActiveWork/*` (6), `Lab/Components/*` (3), `Lab/Archive/Surface`, each with a REJECTED.md entry.
+- ASCII titles; one naming convention per family.
+- `autodocs` + a `Composes` line on every hardened story; decorators compose `<Surface level="base">`.
+- Thin per-state stories to Default + controls (Input 15, Card 14, Alert 14, Toast 13).
+
+**E5 · Governance refresh** (after E4 so tags land on final titles)
+- Regenerate `arch-graph.json`; CI fails when it is older than the newest `index.ts`.
+- REJECTED.md backfill for the ten archived directions plus retired `inset`, `tonalFill`/`ditherTile`, `data-1..10`.
+- `status:` tags; MATURITY review for `ui/*` (38 primitives, not 52).
+- READMEs for `ui/*`, charts, Prose; fix Fatigue README's StatusDot line.
+- Update the workflow skill's `gotchas.md` and `06-lint-guardrails.md`.
+
+**E2 · Consolidation** (decisions 1, 3, 4, 5, 10, 11)
+- Card as sole container; Tile and Section as presets; loose `bg-surface-*` Views (58 sites) onto Card.
+- Pill primitive + presets; `Chip` loses `neutral-*`/`text-white`.
+- Divider everywhere (21 rules). Indicator over StatusDot. Metric absorbs MetricTiles; MetricCell deleted. HelpTip deleted.
+- Each retired export: `@deprecated` first, then a consumer-update task per downstream repo.
+
+**E3 · Port Workout and Fatigue** (decisions 7, 8, 9, 13, 15)
+- Typography + Eyebrow into `ui/`; `theme/color-math.ts`; `utils/format/*`.
+- Workout batches from the 2026-09-08 audit, smallest drift and most consumers first:
+  - B1 (S): MetricCell, SetStrip, SetTableHeader, SetsRepsLoad, ExerciseHeading, ExerciseIndicator, ExerciseCardHeading, PrBadge.
+  - B2 (M): SegmentedBar, MuscleGroupChip, PlaceholderStrip, ScheduleTiles, StatusPill, SupersetWrapper, MesoProgressBar, Sparkline, VolumeLandmarkBar, SessionHeader, WeekRow, WorkoutCard.
+  - B3 (M): StatusDot (6 cross-family consumers), WeightBadge (the one render-path `getSemanticColors('dark')` bug, lines 46 and 105), ExerciseCard, SetRow, SetBar, WorkoutPill.
+  - B4 (M/L): InputBar, PrHistoryModal, RestTimer, SessionRail, BodyMap (the pattern to copy: three correct `resolveColor` calls; one leftover module constant), MesoCard.
+  - B5 (L): MesoStatusCard (drift 40, highest), TempoDisplay, BodyMapDetailPanel, StrengthTrendChart, ZoneTrack, CapacityBandChart, IntensityBar, ReadinessCheck, the five page organisms, VelocityStrip (1,468 lines).
+- Fatigue: 9 module constants, local colour math.
+- `ui/*`: 81 raw `Text` onto Typography; Button `#ffffff`, Alert `bg-black`, Tooltip `bg-neutral-800`, Spinner hex.
+- Lint: every family in the error block; delete `raw-color-baseline.json` at zero.
+- Move `velocity-story-kit.tsx` and `setHeadingKit.tsx` out of `components/`.
+
+**E6 · Code-quality floor** (independent)
+- Split the 29 functions over 100 lines (four charts >300 lines; VelocityStrip).
+- eslint warnings 81 → 0. `axe` in the 16 test files lacking it. Delete the 18 gitignored `tmp-*.mjs`.
+
+## Consumer follow-ups (one task per repo when E2 lands)
+
+audiobook/frontend (Badge, Chip, StatusPill) · voltras-mcp (Pill, Badge, PrBadge, MuscleGroupChip, MetricTiles, StatusPill type) · voltras mobile (Card, Metric, Section, SectionHeader, `getSemanticColors`/`alpha`) · codewatch (Badge, Metric) · voltras-mcp-wave0 and codewatch-wt-c76 (stale forks: retire or repoint).

package/docs/render-testing-pattern.md

@@ -0,0 +1,130 @@
+# Render tests and the visual-baseline layers
+
+What a render test proves in this library, what it doesn't, and when to reach for one of
+the three visual layers instead.
+
+## What a render test is
+
+Every component ships a `Component.test.tsx` next to it — 149 of them today, one per
+component, each importing `render`/`screen` from `@testing-library/react`
+(`grep -l "from '@testing-library/react'" src -r --include="*.test.tsx" | wc -l`). A
+render test mounts the component with React Testing Library and asserts against the DOM
+it produces: text is present, a role exists, a prop toggles an attribute, `jest-axe`
+finds no violations. `src/components/ui/button/Button.test.tsx` is the reference shape —
+mount variants, fire events, assert on `screen`, then an `accessibility` block running
+`axe(container)`.
+
+Coverage thresholds are enforced by Vitest, scoped to components only
+(`vitest.config.ts:26-31`):
+
+```ts
+coverage: {
+  include: ['src/components/**/*.{ts,tsx}'],
+  exclude: ['src/**/*.stories.tsx', 'src/**/*.test.tsx', 'src/**/index.ts'],
+  thresholds: { statements: 80, branches: 80, functions: 80, lines: 80 },
+}
+```
+
+## What it does NOT prove
+
+**A render test that asserts a component mounts and toggles does not prove it renders
+correctly.** Testing Library's queries only see whatever the test environment's DOM
+diffing actually produced — and that instrumentation can miss a real defect even when a
+component is visibly broken. VW-100's fix for `AdvancedAccordion` hit this directly: a
+deliberately-broken control produced **zero warnings** under the (React Native) jest-expo
+harness, because the strict-mode instrumentation needed a real React fiber render pass
+that harness wasn't doing. The render test only proved the component mounted and
+toggled — not that it looked right. Titan's own render tests use a real browser DOM via
+jsdom + RTL rather than jest-expo, which is a stronger environment, but the underlying
+limit is the same: **DOM assertions do not check pixels.** Nothing in this suite is
+visual proof. That's what the three layers below are for. Don't read a green render
+suite, or green coverage numbers, as evidence a component looks correct — only that its
+DOM/behavior contract holds.
+
+## The three visual layers, and when to reach for each
+
+Titan runs `@playwright/test` `^1.58.2` (`packages/ui/package.json`) against four
+configs. Three are wired into `.github/workflows/visual.yml`; the fourth is a local-only
+dev harness (see below).
+
+| Layer                              | Config                               | Script                 | What it actually checks                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------------------- | ------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 — component screenshot baselines | `playwright.baseline.config.ts`      | `test:visual:baseline` | Boots the specimen dev server (`pnpm specimen`, port 5200) and runs `specimen/baseline/**/*.screenshot.test.ts` against committed `*-chromium-linux.png` baselines, `maxDiffPixelRatio: 0.01`. 68 baselines exist today, generated from the pinned `mcr.microsoft.com/playwright:v1.58.2-noble` container so they're byte-comparable to CI.                                                          |
+| 2 — Storybook story baselines      | `playwright.config.ts` (the default) | `test:visual:stories`  | Boots Storybook (`pnpm storybook --ci`, port 6006) and runs `tests/visual/stories.spec.ts`, which enumerates `index.json` and screenshots every story matching `SCOPE = /^(shell-\|icons-\|icons--)/` — today that's the shell family plus the icon primitive, not the whole library. The clock is frozen and CSS animations disabled so control-driven/animated stories snapshot deterministically. |
+| 3 — HTML-vs-React parity           | `playwright.comparison.config.ts`    | `test:visual:compare`  | Boots the specimen dev server and runs `specimen/**/*.visual.test.ts`: a computed-style comparison between a hand-written HTML reference and the React/NativeWind render of the same component, to catch NativeWind/RNW output drifting from the intended CSS.                                                                                                                                       |
+| — token-resolution harness         | `playwright.tokens.config.ts`        | `test:visual:tokens`   | Runs `specimen/token-resolution.spec.ts` against the specimen server. Not referenced anywhere in `.github/workflows/`, so it is a **local-only dev tool** — it does not gate anything today.                                                                                                                                                                                                         |
+
+Two files under `tests/visual/` — `visual.spec.ts` (a bare "storybook loads" smoke check)
+and `validation.spec.ts` (ad hoc, assertion-free screenshot capture to
+`tests/visual/validation/`) — exist but aren't targeted by any `package.json` script or
+CI step. They're leftover/manual tooling, not part of the gated pattern; don't treat them
+as covering anything.
+
+**When to reach for which:** a render test for behavior/a11y on every component, always.
+Layer 3 when you're worried NativeWind's web output has drifted from what the class names
+should compute to. Layer 1 when you want a pixel-exact regression gate on a specific
+component in isolation. Layer 2 when the thing you're worried about only shows up in a
+real Storybook story (composition, controls, live/animated state) rather than the
+specimen harness.
+
+## Do the visual layers actually run on pull requests?
+
+**Partially.** `.github/workflows/visual.yml` triggers on `push`/`pull_request` to
+`main`, and Layers 1 and 3 run their real gating scripts (`test:visual:baseline`,
+`test:visual:compare`) — a pixel or computed-style mismatch fails the PR. **Layer 2 does
+not currently gate anything**: the CI step runs `test:visual:stories:update` (the
+`--update-snapshots` seed variant), not the gate, because baselines for it aren't
+committed yet — the workflow's own comment calls this out as a bootstrap step and
+documents the two-line change (commit the seeded PNGs, swap the script to
+`test:visual:stories`) that would turn it into a real gate. Until that happens, a story
+visual regression in the shell/icons scope will not fail your PR.
+
+## Where a new component's test goes, and its minimal shape
+
+`Component.test.tsx` sits beside `Component.tsx` in `src/components/ui/<name>/` (or
+`custom/<Family>/`), per the file-structure convention in the repo's `CLAUDE.md`.
+Minimal shape, following `Button.test.tsx`:
+
+```tsx
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { Component } from './Component'
+
+describe('Component', () => {
+  it('renders correctly', () => {
+    render(<Component />)
+    // assert on screen.getBy...
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Component />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})
+```
+
+A new component does not automatically get a Layer 1/2/3 visual test — those are opted
+into per-component (Layer 1) or per-story-scope (Layer 2), and per hand-written reference
+(Layer 3). Nothing in the current config auto-enrolls a new component into any of them.
+
+## How the visual baselines are updated, and what a moved baseline means in review
+
+- **Layer 1** (`test:visual:baseline:update`) regenerates `*-chromium-linux.png` under
+  `specimen/baseline/**/*.screenshot.test.ts-snapshots/`. `visual.yml` always runs this
+  step (`if: always()`) in the same pinned container as the gate and uploads the result
+  as the `component-visual-baselines` artifact, so a genuinely-changed component's
+  baseline comes back different while every unchanged one is byte-identical — no local
+  rendering noise. Refreshing means: download that artifact, commit the changed PNGs.
+- **Layer 2** (`test:visual:stories:update`) regenerates
+  `tests/visual/reference/stories.spec.ts-snapshots/` the same way, uploaded as
+  `storybook-visual-baselines`; per the previous section this currently runs
+  unconditionally (it's the seed step, not a gate).
+- **Layer 3** has no baseline images to move — it's a computed-style comparison, not a
+  screenshot diff.
+
+**A moved baseline in review is a rendering change, not a rubber stamp.** Because Layer 1
+baselines are only ever regenerated in the pinned container, a diff limited to the
+changed component's PNG(s) is a real signal that its markup or styles moved — reviewers
+should ask what changed and why, the same as any other diff, rather than treating "CI
+regenerated it" as self-justifying.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titan-design/react-ui",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Cross-platform design system built on Gluestack UI",
   "author": "Henry Jewkes",
   "license": "MIT",

package/src/arch/Architecture.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { useEffect, useMemo, useState } from 'react'
 import { getSemanticColors } from '../theme/tokens/semantic'
+import { primitiveColors } from '../theme/tokens/primitives'
+import { alpha } from '../utils/colors'
 import graph from './arch-graph.json'
 
 /**
@@ -396,7 +398,7 @@ function RenderModal({
       style={{
         position: 'fixed',
         inset: 0,
-        background: 'rgba(0,0,0,0.66)',
+        background: alpha(primitiveColors.black, 0.66),
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',

package/src/arch/arch-graph.freshness.test.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+// @ts-expect-error — plain-ESM build tooling, shared with scripts/arch-graph.mjs
+import { componentBarrelHash } from '../../scripts/barrel-hash.mjs'
+import graph from './arch-graph.json'
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const REPO_ROOT = path.resolve(PKG_ROOT, '../..')
+
+describe('arch-graph.json freshness', () => {
+  it('records the barrel hash it was generated from', () => {
+    expect(graph.componentBarrelHash).toMatch(/^sha256:[0-9a-f]{64}$/)
+  })
+
+  it('matches the current component barrels', () => {
+    expect(
+      graph.componentBarrelHash,
+      'arch-graph.json is stale: a component barrel changed since it was generated. ' +
+        'Run `pnpm arch:graph -- --reindex` from the repo root and commit the result.'
+    ).toBe(componentBarrelHash(PKG_ROOT))
+  })
+
+  it('tallies every configured consumer, so none can be silently scored as zero usage', () => {
+    const configured = graph.summary.consumers.map((c) => c.name)
+    for (const component of graph.components) {
+      expect(
+        Object.keys(component.xproj)
+          .filter((k) => k !== 'total')
+          .sort(),
+        `${component.name}.xproj is missing a configured consumer. A consumer absent from ` +
+          'the tally scores 0 usage, which lands its components on the `dead` list.'
+      ).toEqual([...configured].sort())
+    }
+  })
+
+  // The consumer list is committed precisely so every machine computes the same
+  // `dead` verdicts. Adding a consumer without regenerating leaves a graph that
+  // looks authoritative and is wrong about the repo that was just added.
+  it('was generated from the committed consumer list', () => {
+    const shared = JSON.parse(
+      readFileSync(path.join(REPO_ROOT, 'scripts/arch.config.json'), 'utf8')
+    ) as { consumers: { name: string }[] }
+
+    expect(
+      graph.summary.consumers.map((c) => c.name).sort(),
+      'arch-graph.json was generated from a different consumer set than ' +
+        'scripts/arch.config.json. Run `pnpm arch:graph -- --reindex` and commit the result.'
+    ).toEqual(shared.consumers.map((c) => c.name).sort())
+  })
+})