@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/ui/trigger/TriggerSurface.tsx

@@ -0,0 +1,81 @@
+import React, { isValidElement, cloneElement } from 'react'
+import { Pressable, type AccessibilityState } from 'react-native'
+
+type Handler = (...args: never[]) => void
+type Handlers = Record<string, Handler | undefined>
+
+export interface TriggerSurfaceProps {
+  /** Pressable handlers (onPress, onHoverIn, …) for whichever element owns the interaction. */
+  handlers: Handlers
+  /** Role for the wrapper when it is the one handling the interaction. */
+  accessibilityRole?: 'button'
+  /** Merged onto whichever element ends up owning the interaction. */
+  accessibilityState?: AccessibilityState
+  className?: string
+  children: React.ReactNode
+}
+
+type ComposableChildProps = Handlers & { accessibilityState?: AccessibilityState }
+
+function chain(childHandler: Handler | undefined, ownHandler: Handler | undefined): Handler {
+  return (...args: never[]) => {
+    childHandler?.(...args)
+    ownHandler?.(...args)
+  }
+}
+
+/**
+ * Give interaction handling to a composed child instead of wrapping it in a second Pressable.
+ *
+ * React Native Web lets only the innermost pressable in a chain handle a gesture:
+ * PressResponder calls `stopPropagation()` on the click that drives `onPress`,
+ * and `useHover` contains hover the same way. A trigger that wraps a `Pressable`
+ * child (a `Button`, say) in its own `Pressable` therefore never sees the
+ * interaction — in a browser the trigger looks completely dead.
+ *
+ * A component child may be a Pressable, so the handlers are cloned onto it and
+ * the wrapper drops the button role — that also leaves one `[role=button]`
+ * rather than an invalid button-inside-button pair. The wrapper stays a
+ * Pressable, out of the tab order, to still catch children that turn out not to
+ * be pressable. Host elements (`<button>`, `<span>`) cannot take these handlers
+ * and do not swallow the gesture, so for those the wrapper handles it.
+ */
+export function TriggerSurface({
+  handlers,
+  accessibilityRole,
+  accessibilityState,
+  className,
+  children,
+}: TriggerSurfaceProps) {
+  const child = isValidElement(children) ? children : null
+  const childCanCompose = child !== null && typeof child.type !== 'string'
+
+  if (!childCanCompose) {
+    return (
+      <Pressable
+        accessibilityRole={accessibilityRole}
+        accessibilityState={accessibilityState}
+        className={className}
+        {...handlers}
+      >
+        {children}
+      </Pressable>
+    )
+  }
+
+  const childElement = child as React.ReactElement<ComposableChildProps>
+  const composed: ComposableChildProps = {}
+  for (const [name, handler] of Object.entries(handlers)) {
+    composed[name] = chain(childElement.props[name], handler)
+  }
+  composed.accessibilityState = {
+    ...childElement.props.accessibilityState,
+    ...accessibilityState,
+  }
+
+  return (
+    <Pressable focusable={false} tabIndex={-1} className={className} {...handlers}>
+      {cloneElement(childElement, composed)}
+    </Pressable>
+  )
+}

package/src/components/ui/trigger/index.ts

@@ -0,0 +1,2 @@
+export { TriggerSurface } from './TriggerSurface'
+export type { TriggerSurfaceProps } from './TriggerSurface'

package/src/stories/PresetShowcase.stories.tsx

@@ -70,9 +70,7 @@ function SideBySideShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Preset Showcase
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Preset Showcase</Text>
         <Text className="text-text-secondary text-base">
           Toggle between presets to see how the entire design system adapts.
         </Text>
@@ -89,14 +87,14 @@ function SideBySideShowcase() {
           Subheading (font-heading)
         </Text>
         <Text className="text-base text-text-primary font-body">
-          Body text using font-body. The quick brown fox jumps over the lazy dog. This
-          demonstrates how paragraph text renders under the current preset.
+          Body text using font-body. The quick brown fox jumps over the lazy dog. This demonstrates
+          how paragraph text renders under the current preset.
         </Text>
         <Text className="text-sm text-text-secondary font-body">
           Secondary body text for captions and supporting content.
         </Text>
         <Text className="text-sm text-text-primary font-mono">
-          {'const monospace = \'font-mono rendering\''}
+          {"const monospace = 'font-mono rendering'"}
         </Text>
       </Section>
 
@@ -195,20 +193,40 @@ function SideBySideShowcase() {
       {/* Toasts */}
       <Section title="Toasts">
         <View className="gap-3">
-          <Toast title="Operation successful" description="Your changes have been saved." status="success" />
-          <Toast title="Something went wrong" description="Please try again later." status="error" />
+          <Toast
+            title="Operation successful"
+            description="Your changes have been saved."
+            status="success"
+          />
+          <Toast
+            title="Something went wrong"
+            description="Please try again later."
+            status="error"
+          />
           <Toast title="Heads up" description="This action cannot be undone." status="warning" />
-          <Toast title="New update available" description="Version 2.0 is ready to install." status="info" />
+          <Toast
+            title="New update available"
+            description="Version 2.0 is ready to install."
+            status="info"
+          />
         </View>
       </Section>
 
       {/* Status Colors */}
       <Section title="Status Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <Badge color="success" size="lg">Success</Badge>
-          <Badge color="error" size="lg">Error</Badge>
-          <Badge color="warning" size="lg">Warning</Badge>
-          <Badge color="info" size="lg">Info</Badge>
+          <Badge color="success" size="lg">
+            Success
+          </Badge>
+          <Badge color="error" size="lg">
+            Error
+          </Badge>
+          <Badge color="warning" size="lg">
+            Warning
+          </Badge>
+          <Badge color="info" size="lg">
+            Info
+          </Badge>
         </View>
       </Section>
     </View>
@@ -225,9 +243,7 @@ function TypographyShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Typography
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Typography</Text>
         <Text className="text-text-secondary text-base">
           How fonts and text styles change across presets.
         </Text>
@@ -252,9 +268,9 @@ function TypographyShowcase() {
 
       <Section title="Body Font (font-body)">
         <Text className="text-base text-text-primary font-body">
-          Regular body text. Design systems provide a shared language for product teams.
-          By codifying decisions into reusable components and tokens, teams move faster
-          while maintaining visual consistency across every surface.
+          Regular body text. Design systems provide a shared language for product teams. By
+          codifying decisions into reusable components and tokens, teams move faster while
+          maintaining visual consistency across every surface.
         </Text>
         <Text className="text-base font-semibold text-text-primary font-body">
           Bold body text. Emphasis and hierarchy within paragraph content.
@@ -263,8 +279,8 @@ function TypographyShowcase() {
           Italic body text. Used for quotations, citations, and emphasis.
         </Text>
         <Text className="text-sm text-text-secondary font-body">
-          Small / secondary text. Captions, labels, and supporting information
-          that supplements the main content without competing for attention.
+          Small / secondary text. Captions, labels, and supporting information that supplements the
+          main content without competing for attention.
         </Text>
         <Text className="text-xs text-text-tertiary font-body">
           Extra-small / tertiary text. Timestamps, metadata, fine print.
@@ -287,19 +303,14 @@ function TypographyShowcase() {
 
       <Section title="Mixed Typography">
         <Card className="p-5 gap-3">
-          <Text className="text-2xl font-bold text-text-primary font-heading">
-            Chapter One
-          </Text>
+          <Text className="text-2xl font-bold text-text-primary font-heading">Chapter One</Text>
           <Text className="text-base text-text-secondary font-body">
-            It was a bright cold day in April, and the clocks were striking thirteen.
-            Winston Smith, his chin nuzzled into his breast in an effort to escape the
-            vile wind, slipped quickly through the glass doors of Victory Mansions,
-            though not quickly enough to prevent a swirl of gritty dust from entering
-            along with him.
-          </Text>
-          <Text className="text-xs text-text-tertiary font-mono">
-            George Orwell, 1984
+            It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith,
+            his chin nuzzled into his breast in an effort to escape the vile wind, slipped quickly
+            through the glass doors of Victory Mansions, though not quickly enough to prevent a
+            swirl of gritty dust from entering along with him.
           </Text>
+          <Text className="text-xs text-text-tertiary font-mono">George Orwell, 1984</Text>
         </Card>
       </Section>
     </View>
@@ -332,9 +343,7 @@ function ColorPaletteShowcase() {
   return (
     <View className="gap-6 p-6 bg-background-default min-h-screen">
       <View className="gap-2">
-        <Text className="text-3xl font-bold text-text-primary font-heading">
-          Color Palette
-        </Text>
+        <Text className="text-3xl font-bold text-text-primary font-heading">Color Palette</Text>
         <Text className="text-text-secondary text-base">
           Semantic color tokens rendered as swatches. Toggle presets to compare palettes.
         </Text>
@@ -347,13 +356,21 @@ function ColorPaletteShowcase() {
           <ColorSwatch label="brand-primary" className="bg-brand-primary" />
           <ColorSwatch label="brand-primary-light" className="bg-brand-primary-light" />
           <ColorSwatch label="brand-primary-dark" className="bg-brand-primary-dark" />
-          <ColorSwatch label="brand-primary-subtle" className="bg-brand-primary-subtle" textClass="text-text-primary" />
+          <ColorSwatch
+            label="brand-primary-subtle"
+            className="bg-brand-primary-subtle"
+            textClass="text-text-primary"
+          />
         </View>
         <View className="flex-row gap-3 flex-wrap mt-2">
           <ColorSwatch label="brand-secondary" className="bg-brand-secondary" />
           <ColorSwatch label="brand-secondary-light" className="bg-brand-secondary-light" />
           <ColorSwatch label="brand-secondary-dark" className="bg-brand-secondary-dark" />
-          <ColorSwatch label="brand-secondary-subtle" className="bg-brand-secondary-subtle" textClass="text-text-primary" />
+          <ColorSwatch
+            label="brand-secondary-subtle"
+            className="bg-brand-secondary-subtle"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
@@ -372,7 +389,9 @@ function ColorPaletteShowcase() {
             <Text className="text-xs font-mono font-medium text-text-primary">text-primary</Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-hairline">
-            <Text className="text-xs font-mono font-medium text-text-secondary">text-secondary</Text>
+            <Text className="text-xs font-mono font-medium text-text-secondary">
+              text-secondary
+            </Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-hairline">
             <Text className="text-xs font-mono font-medium text-text-tertiary">text-tertiary</Text>
@@ -382,26 +401,60 @@ function ColorPaletteShowcase() {
 
       <Section title="Surface Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="surface-base" className="bg-surface-base border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-elevated" className="bg-surface-elevated border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-raised" className="bg-surface-raised border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-overlay" className="bg-surface-overlay border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="surface-input" className="bg-surface-input border border-hairline" textClass="text-text-primary" />
+          <ColorSwatch
+            label="surface-base"
+            className="bg-surface-base border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-elevated"
+            className="bg-surface-elevated border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-raised"
+            className="bg-surface-raised border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-overlay"
+            className="bg-surface-overlay border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="surface-input"
+            className="bg-surface-input border border-hairline"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
       <Section title="Background Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="background-base" className="bg-background-base border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="background-default" className="bg-background-default border border-hairline" textClass="text-text-primary" />
-          <ColorSwatch label="background-subtle" className="bg-background-subtle border border-hairline" textClass="text-text-primary" />
+          <ColorSwatch
+            label="background-base"
+            className="bg-background-base border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="background-default"
+            className="bg-background-default border border-hairline"
+            textClass="text-text-primary"
+          />
+          <ColorSwatch
+            label="background-subtle"
+            className="bg-background-subtle border border-hairline"
+            textClass="text-text-primary"
+          />
         </View>
       </Section>
 
       <Section title="Border Colors">
         <View className="flex-row gap-3 flex-wrap">
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-hairline-default">
-            <Text className="text-xs font-mono font-medium text-text-primary">hairline-default</Text>
+            <Text className="text-xs font-mono font-medium text-text-primary">
+              hairline-default
+            </Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-hairline-subtle">
             <Text className="text-xs font-mono font-medium text-text-primary">hairline-subtle</Text>

package/src/test/no-device-internals.test.ts

@@ -21,13 +21,13 @@ describe('no-device-internals', () => {
         // Dimension and ratio strings: the `\b` guard before `0x` means a digit
         // followed by `x` never reads as a hex literal. These exact strings
         // tripped an earlier, looser sweep.
-        { code: "// icons render at 20x20" },
-        { code: "// 200x400 intrinsic -> ~160x320 px" },
+        { code: '// icons render at 20x20' },
+        { code: '// 200x400 intrinsic -> ~160x320 px' },
         // SVG path coordinates — digit-only runs are not byte frames.
         { code: 'const d = "M12 2 22 12 12 22 2 12Z"' },
         { code: 'const d = "M7 7 17 17 12 22 12 2 17 7 7 17"' },
         // Timestamps — `-` and `:` are not byte separators.
-        { code: "// datetime // 2024-01-15 14:30" },
+        { code: '// datetime // 2024-01-15 14:30' },
         // "cascade" in its CSS sense is ordinary styling vocabulary.
         { code: "// RN doesn't cascade text color, so hand-color the text" },
         // Plain numbers and durations.

package/src/theme/ChoosingTokens.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import tokensDoc from '../../TOKENS.md?raw'
+import { Typography } from '../components/custom/Typography'
+
+/**
+ * Rendered straight from `packages/ui/TOKENS.md` via Vite's `?raw`, deliberately
+ * as its markdown source rather than a hand-built React page. A prettier page
+ * would be a second copy of the rules that can drift from the file — and a token
+ * guide that disagrees with itself is worse than a plain one. The content is
+ * mostly aligned tables, which read fine in mono.
+ */
+function ChoosingTokens() {
+  return (
+    <View className="gap-4 p-6">
+      <Typography variant="h3" className="text-text-primary">
+        Choosing tokens
+      </Typography>
+      <Typography variant="body2" className="text-text-secondary">
+        The decision table to read before writing a component. Source of truth:{' '}
+        <Text className="font-mono text-text-primary">packages/ui/TOKENS.md</Text> — this page
+        renders that file, so the two cannot disagree.
+      </Typography>
+      <View className="rounded-lg bg-surface-raised p-4">
+        <Text className="font-mono text-xs leading-5 text-text-secondary">{tokensDoc}</Text>
+      </View>
+    </View>
+  )
+}
+
+const meta: Meta<typeof ChoosingTokens> = {
+  title: 'Foundations/Choosing Tokens',
+  component: ChoosingTokens,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Which palette for which meaning, how to resolve a colour in code, and the type/spacing ' +
+          'scales. Rendered from `packages/ui/TOKENS.md`.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof ChoosingTokens>
+
+export const Default: Story = {}

package/src/theme/ColorPalettes.stories.tsx

@@ -1,6 +1,15 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
-import { categoricalPalette, getCategoricalColor, CATEGORICAL_CVD_SAFE_MAX, divergingScale, sequentialEffort, discreteRainbow, bestTextColor, greyRamp } from './tokens/primitives'
+import {
+  categoricalPalette,
+  getCategoricalColor,
+  CATEGORICAL_CVD_SAFE_MAX,
+  divergingScale,
+  sequentialEffort,
+  discreteRainbow,
+  bestTextColor,
+  greyRamp,
+} from './tokens/primitives'
 import { semanticColorsLight, semanticColorsDark } from './tokens/semantic'
 import { WORKOUT_TOKENS } from './workout-tokens'
 import { WORKOUT_PILL_DELOAD } from './extracted-colors-dataviz'
@@ -52,7 +61,12 @@ export default meta
  * `Foundations/Color/Primitives`.
  */
 const SURFACE_PLANES = [
-  { step: 975, hex: greyRamp[975], lStar: 3.8, role: 'Frame / bezel — chrome the ramp sits inside' },
+  {
+    step: 975,
+    hex: greyRamp[975],
+    lStar: 3.8,
+    role: 'Frame / bezel — chrome the ramp sits inside',
+  },
   { step: 950, hex: greyRamp[950], lStar: 9, role: 'Shell' },
   { step: 925, hex: greyRamp[925], lStar: 13.9, role: 'Main content plane' },
   { step: 900, hex: greyRamp[900], lStar: 17.2, role: 'Nav / rail' },
@@ -113,12 +127,12 @@ export const SurfaceRamp: StoryObj = {
     <View style={{ padding: 24 }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Surface Ramp (Dark Mode)</Text>
       <SectionIntro>
-        The v0.10.0 surface foundation, and the assignment the most surfaces depend on. Depth is
-        an <Text className="font-semibold">ordered ramp</Text>, not a set of unrelated fills —
-        planes are spaced by perceptual lightness (L*) on a diminishing taper, so &quot;one step
-        up&quot; is the same visual distance anywhere in the stack. Listed darkest first. Several
-        semantic tokens deliberately share a plane (shown per row); that aliasing is what lets a
-        component say what it <Text className="italic">is</Text> rather than how deep it sits.
+        The v0.10.0 surface foundation, and the assignment the most surfaces depend on. Depth is an{' '}
+        <Text className="font-semibold">ordered ramp</Text>, not a set of unrelated fills — planes
+        are spaced by perceptual lightness (L*) on a diminishing taper, so &quot;one step up&quot;
+        is the same visual distance anywhere in the stack. Listed darkest first. Several semantic
+        tokens deliberately share a plane (shown per row); that aliasing is what lets a component
+        say what it <Text className="italic">is</Text> rather than how deep it sits.
       </SectionIntro>
 
       <View style={{ gap: 14 }}>
@@ -132,9 +146,9 @@ export const SurfaceRamp: StoryObj = {
         scales — the greys it is built from are in Foundations/Color/Primitives. To apply it at
         runtime use <Text className="font-semibold text-text-primary">&lt;Surface level&gt;</Text>{' '}
         and <Text className="font-semibold text-text-primary">useOnSurfaceColor</Text> rather than
-        reading tokens directly — see Components/Atoms/Surface. Shadow and glow treatments layered
-        on top of these planes are in Foundations/Shadows; the legacy numeric elevation scale is
-        in Foundations/Elevation.
+        reading tokens directly — see Components/Atoms/Surface. How a plane says it is ABOVE its
+        neighbour (tone, lift, hairline, material) and how the elevation levels map onto these steps
+        are in Foundations/Depth.
       </Text>
     </View>
   ),
@@ -188,16 +202,14 @@ export const CategoricalPalette: StoryObj = {
       <SectionIntro>
         Seven hues in one canonical order —{' '}
         <Text className="font-semibold">blue → magenta → red → orange → green → cyan → amber</Text>{' '}
-        — expressed as references into the tonal ramps. The sequence is nested-stable: a chart
-        with N series takes the first N colors and a series&apos; index does not shift as N
-        changes. The worst-case deuteranopia/protanopia ΔE floor of 8 holds through the first{' '}
-        {CATEGORICAL_CVD_SAFE_MAX} (
-        <Text className="font-semibold">CATEGORICAL_CVD_SAFE_MAX</Text>); the 7th is extended and
-        wants a legend or a second encoding. Two variants ship:{' '}
+        — expressed as references into the tonal ramps. The sequence is nested-stable: a chart with
+        N series takes the first N colors and a series&apos; index does not shift as N changes. The
+        worst-case deuteranopia/protanopia ΔE floor of 8 holds through the first{' '}
+        {CATEGORICAL_CVD_SAFE_MAX} (<Text className="font-semibold">CATEGORICAL_CVD_SAFE_MAX</Text>
+        ); the 7th is extended and wants a legend or a second encoding. Two variants ship:{' '}
         <Text className="font-semibold">default</Text> (vivid, for neutral/light surfaces, legible
-        under black text) and <Text className="font-semibold">dark</Text> (deeper, for white text
-        on a filled swatch). A third &quot;light&quot; variant was dropped — `default` doubles as
-        it.
+        under black text) and <Text className="font-semibold">dark</Text> (deeper, for white text on
+        a filled swatch). A third &quot;light&quot; variant was dropped — `default` doubles as it.
       </SectionIntro>
 
       <CategoricalRow name="Default (black text)" colors={categoricalPalette.default} />
@@ -394,8 +406,8 @@ export const FatigueRomPalette: StoryObj = {
         </Text>{' '}
         One scheme shared by the two live-quality readouts — the ROM progression bars and the
         ghost-spark current line. Deliberately no greens and no ambers: those languages belong to
-        the verdict tones and the velocity-loss bands (stories 3 and 4), and reusing them here
-        would make &quot;fine&quot; and &quot;fast&quot; look like the same claim. Every stop is a
+        the verdict tones and the velocity-loss bands (stories 3 and 4), and reusing them here would
+        make &quot;fine&quot; and &quot;fast&quot; look like the same claim. Every stop is a
         reference into the tonal ramps.
       </SectionIntro>
 
@@ -426,8 +438,8 @@ export const FatigueRomPalette: StoryObj = {
       <Text className="text-text-secondary text-xs mb-3">
         A controlled rep (grind signature below GRIND_THRESHOLD = {GRIND_THRESHOLD}) stays in the
         silver family, dimming toward DRIFT_GREY with tempo deviation — a &quot;drifting but not
-        failing&quot; cue that never becomes a color. At or above the threshold the line runs
-        light → mid → deep by severity.
+        failing&quot; cue that never becomes a color. At or above the threshold the line runs light
+        → mid → deep by severity.
       </Text>
       <View style={{ flexDirection: 'row', gap: 32 }}>
         <FatigueRampStrip
@@ -442,8 +454,8 @@ export const FatigueRomPalette: StoryObj = {
         DRIFT_GREY is `neutral[600]` #4B5563, and the unified warm grey ramp assigns it no
         destination — the 15-row fold maps the other greys but skips this one. It needs an
         assignment before that migration lands. Note that the recovered spec records DRIFT_GREY as
-        `grey[500]` #1C1C1C; that is stale, `fatigue-tokens.ts` on main reads `neutral[600]`,
-        which puts it in the expensive half of the fold rather than the cheap one.
+        `grey[500]` #1C1C1C; that is stale, `fatigue-tokens.ts` on main reads `neutral[600]`, which
+        puts it in the expensive half of the fold rather than the cheap one.
       </Text>
     </View>
   ),
@@ -461,7 +473,9 @@ export const FatigueRomPalette: StoryObj = {
  * buries. Columns are derived from the shipped tokens, so a new modifier shows
  * up here without editing the story.
  */
-const VARIANT_SUFFIXES = ['light', 'dark', 'subtle', 'hover', 'active', 'muted'] as const
+// Wash rungs run subtle -> muted -> strong (0.12 / 0.30 / 0.50) so the matrix
+// reads as the ramp it is.
+const VARIANT_SUFFIXES = ['light', 'dark', 'subtle', 'muted', 'strong', 'hover', 'active'] as const
 
 function variantsOf(base: string, palette: Record<string, string>) {
   return [
@@ -513,12 +527,12 @@ export const StatusColors: StoryObj = {
       <Text className="text-2xl font-bold text-text-primary mb-2">Status Colors</Text>
       <SectionIntro>
         Status roles and their modifiers. <Text className="font-semibold">status-error-vivid</Text>{' '}
-        is a separate role (not a modifier of status-error) reserved for destructive
-        emphasis. It used to be the one status family sourced from the `redVivid` support scale
-        rather than the OKLCH ramps; TD-07.14 deleted that scale, so the family now resolves to
-        the same red[600]/[500]/[700] steps as status-error. The two are therefore identical in
-        value today — the role is kept distinct because emphasis is meant to come from a glow
-        derived from red[500], not from a second, higher-chroma red.
+        is a separate role (not a modifier of status-error) reserved for destructive emphasis. It
+        used to be the one status family sourced from the `redVivid` support scale rather than the
+        OKLCH ramps; TD-07.14 deleted that scale, so the family now resolves to the same
+        red[600]/[500]/[700] steps as status-error. The two are therefore identical in value today —
+        the role is kept distinct because emphasis is meant to come from a glow derived from
+        red[500], not from a second, higher-chroma red.
       </SectionIntro>
       <VariantMatrix
         bases={[
@@ -557,8 +571,8 @@ export const ResultColors: StoryObj = {
       <Text className="text-2xl font-bold text-text-primary mb-2">Result / Outcome Colors</Text>
       <SectionIntro>
         Colors for indicating positive, negative, or neutral outcomes. Distinct from status: these
-        encode the <Text className="italic">direction of a change</Text> (did this get better?),
-        not a system state.
+        encode the <Text className="italic">direction of a change</Text> (did this get better?), not
+        a system state.
       </SectionIntro>
       <VariantMatrix
         bases={['result-improve', 'result-degrade', 'result-inconclusive', 'result-neutral']}
@@ -574,11 +588,11 @@ export const TextAndBorderColors: StoryObj = {
     <View style={{ padding: 24 }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Text & Border Colors</Text>
       <SectionIntro>
-        The dark-mode text and border roles. Today the border family is the grey grey ramp
-        assigned to line-work, and text-tertiary and the link colors come from the neutral and
-        blue support scales — all three of which are pending migration (TD-07.14): the greys fold
-        into one warm grey ramp and the links move to the OKLCH blue. These are the roles that
-        will move most, because the mid-grey text steps shift furthest. Prefer{' '}
+        The dark-mode text and border roles. Today the border family is the grey grey ramp assigned
+        to line-work, and text-tertiary and the link colors come from the neutral and blue support
+        scales — all three of which are pending migration (TD-07.14): the greys fold into one warm
+        grey ramp and the links move to the OKLCH blue. These are the roles that will move most,
+        because the mid-grey text steps shift furthest. Prefer{' '}
         <Text className="font-semibold">useOnSurfaceColor</Text> for text sitting on a{' '}
         <Text className="font-semibold">&lt;Surface&gt;</Text> — it picks the right text role for
         the plane instead of hardcoding one, which is also what makes the migration survivable.
@@ -782,7 +796,10 @@ export const RolesInUse: StoryObj = {
         <Demo label="IntensityBar · effort">
           <View style={{ flexDirection: 'row', gap: 2, width: 132 }}>
             {sequentialEffort.map((hex, i) => (
-              <View key={i} style={{ flex: 1, height: 20, backgroundColor: hex, borderRadius: 2 }} />
+              <View
+                key={i}
+                style={{ flex: 1, height: 20, backgroundColor: hex, borderRadius: 2 }}
+              />
             ))}
           </View>
         </Demo>
@@ -832,10 +849,10 @@ export const LegacyDataVisualizationColors: StoryObj = {
       </Text>
       <SectionIntro>
         <Text className="font-semibold">Do not use for new work.</Text> Paul Tol&apos;s
-        discrete-rainbow scale behind the `data-1..10` tokens — no longer consumed by any
-        component. Use the Categorical Palette (story 2) for charts and qualitative series. This
-        story exists because the tokens are still shipped, and a shipped token without a swatch is
-        the drift the coverage test guards against; it goes away when the tokens do.
+        discrete-rainbow scale behind the `data-1..10` tokens — no longer consumed by any component.
+        Use the Categorical Palette (story 2) for charts and qualitative series. This story exists
+        because the tokens are still shipped, and a shipped token without a swatch is the drift the
+        coverage test guards against; it goes away when the tokens do.
       </SectionIntro>
 
       <View style={{ gap: 16 }}>