@titan-design/react-ui 0.11.0 → 0.12.1

package/src/stories/PresetShowcase.stories.tsx

@@ -24,7 +24,7 @@ function PresetSwitcher({
   onSwitch: (name: string) => void
 }) {
   return (
-    <View className="flex-row items-center gap-3 p-4 bg-surface-elevated rounded-lg border border-border">
+    <View className="flex-row items-center gap-3 p-4 bg-surface-elevated rounded-lg border border-hairline">
       <Text className="text-text-secondary text-sm font-medium">Active Preset:</Text>
       {Object.keys(presets).map((name) => (
         <Pressable
@@ -33,7 +33,7 @@ function PresetSwitcher({
           className={`px-4 py-2 rounded-md border ${
             activePreset === name
               ? 'bg-brand-primary border-brand-primary'
-              : 'bg-surface-base border-border web:hover:bg-interactive-hover'
+              : 'bg-surface-base border-hairline web:hover:bg-interactive-hover'
           }`}
         >
           <Text
@@ -272,7 +272,7 @@ function TypographyShowcase() {
       </Section>
 
       <Section title="Monospace Font (font-mono)">
-        <View className="bg-surface-elevated rounded-lg p-4 border border-border">
+        <View className="bg-surface-elevated rounded-lg p-4 border border-hairline">
           <Text className="text-sm text-text-primary font-mono">
             {'const theme = applyThemePreset(audiobookPreset)'}
           </Text>
@@ -368,13 +368,13 @@ function ColorPaletteShowcase() {
 
       <Section title="Text 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-elevated border border-border">
+          <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-primary">text-primary</Text>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border">
+          <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>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border">
+          <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>
           </View>
         </View>
@@ -382,32 +382,32 @@ function ColorPaletteShowcase() {
 
       <Section title="Surface Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="surface-base" className="bg-surface-base border border-border" textClass="text-text-primary" />
-          <ColorSwatch label="surface-elevated" className="bg-surface-elevated border border-border" textClass="text-text-primary" />
-          <ColorSwatch label="surface-raised" className="bg-surface-raised border border-border" textClass="text-text-primary" />
-          <ColorSwatch label="surface-overlay" className="bg-surface-overlay border border-border" textClass="text-text-primary" />
-          <ColorSwatch label="surface-input" className="bg-surface-input border border-border" 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-border" textClass="text-text-primary" />
-          <ColorSwatch label="background-default" className="bg-background-default border border-border" textClass="text-text-primary" />
-          <ColorSwatch label="background-subtle" className="bg-background-subtle border border-border" 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-border">
-            <Text className="text-xs font-mono font-medium text-text-primary">border-default</Text>
+          <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>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border-subtle">
-            <Text className="text-xs font-mono font-medium text-text-primary">border-subtle</Text>
+          <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>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border-strong">
-            <Text className="text-xs font-mono font-medium text-text-primary">border-strong</Text>
+          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-hairline-strong">
+            <Text className="text-xs font-mono font-medium text-text-primary">hairline-strong</Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border-focus">
             <Text className="text-xs font-mono font-medium text-text-primary">border-focus</Text>
@@ -425,7 +425,7 @@ function ColorPaletteShowcase() {
 function Section({ title, children }: { title: string; children: React.ReactNode }) {
   return (
     <View className="gap-3">
-      <Text className="text-lg font-semibold text-text-primary font-heading border-b border-border-subtle pb-2">
+      <Text className="text-lg font-semibold text-text-primary font-heading border-b border-hairline-subtle pb-2">
         {title}
       </Text>
       {children}

package/src/theme/ColorPalettes.stories.tsx

@@ -1,17 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
-import {
-  primitiveColors,
-  surfaceRampDark,
-  backgroundFrameDark,
-  categoricalPalette,
-  getCategoricalColor,
-  CATEGORICAL_CVD_SAFE_MAX,
-  divergingScale,
-  sequentialEffort,
-  discreteRainbow,
-  bestTextColor,
-} 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'
@@ -51,22 +40,24 @@ export default meta
 // ============================================================================
 
 /**
- * The dark surface ramp, darkest plane first.
+ * The dark surface planes, darkest first — the depth ladder.
+ *
+ * Each plane is a STEP on `greyRamp` (TD-07.14); the `step` column is the whole
+ * point, because it is what lets a plane and a border be compared on one scale
+ * instead of two. Written as an explicit ordered list because object key order
+ * is not a contract and depth order is what this story is about.
+ * `color-stories.coverage.test.ts` asserts every plane appears here.
  *
- * Order and `lStar` mirror `surfaceRampDark` in tokens/primitives.ts, plus the
- * out-of-ramp `backgroundFrameDark` bezel that sits below it. Written as an
- * explicit ordered list because object key order is not a contract and depth
- * order is the whole point of this story. `color-stories.coverage.test.ts`
- * asserts every ramp step appears here.
+ * The old `inset` plane is absent: it was retired, not renamed. See the ramp in
+ * `Foundations/Color/Primitives`.
  */
 const SURFACE_PLANES = [
-  { hex: backgroundFrameDark, lStar: 3.79, role: 'Frame / bezel — chrome outside the ramp' },
-  { hex: surfaceRampDark.inset, lStar: 4.5, role: 'Sub-shell well / pressed' },
-  { hex: surfaceRampDark.background, lStar: 9, role: 'Shell' },
-  { hex: surfaceRampDark.base, lStar: 13.5, role: 'Main content plane' },
-  { hex: surfaceRampDark.elevated, lStar: 17, role: 'Nav / rail' },
-  { hex: surfaceRampDark.raised, lStar: 20, role: 'Cards' },
-  { hex: surfaceRampDark.overlay, lStar: 22.5, role: 'Hero / popover' },
+  { 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' },
+  { step: 875, hex: greyRamp[875], lStar: 19.9, role: 'Cards' },
+  { step: 850, hex: greyRamp[850], lStar: 22.7, role: 'Hero / popover' },
 ] as const
 
 /** Semantic tokens resolving to `hex`, derived at render so the mapping can't drift. */
@@ -77,7 +68,17 @@ function tokensResolvingTo(hex: string): string[] {
     .sort()
 }
 
-function SurfacePlaneRow({ hex, lStar, role }: { hex: string; lStar: number; role: string }) {
+function SurfacePlaneRow({
+  step,
+  hex,
+  lStar,
+  role,
+}: {
+  step: number
+  hex: string
+  lStar: number
+  role: string
+}) {
   const tokens = tokensResolvingTo(hex)
   return (
     <View style={{ flexDirection: 'row', alignItems: 'center', gap: 16 }}>
@@ -93,7 +94,8 @@ function SurfacePlaneRow({ hex, lStar, role }: { hex: string; lStar: number; rol
       />
       <View style={{ flex: 1 }}>
         <Text className="font-semibold text-text-primary text-sm">
-          {hex.toUpperCase()}{' '}
+          grey-{step}{' '}
+          <Text className="text-text-secondary text-xs font-normal">{hex.toUpperCase()}</Text>{' '}
           <Text className="text-text-tertiary text-xs font-normal">L*{lStar}</Text>
         </Text>
         <Text className="text-text-secondary text-xs">{role}</Text>
@@ -440,7 +442,7 @@ 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
-        `charcoal[500]` #1C1C1C; that is stale, `fatigue-tokens.ts` on main reads `neutral[600]`,
+        `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>
@@ -511,11 +513,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, higher-chroma role (not a modifier of status-error) reserved for
-        destructive emphasis. It is the one status family still sourced from the redVivid support
-        scale rather than the OKLCH ramps, and it is on its way out: under TD-07.14 redVivid
-        retires, status-error-vivid collapses onto status-error&apos;s red[600], and the
-        Indicator&apos;s emphasis moves to a glow derived from red[500].
+        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={[
@@ -571,7 +574,7 @@ 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 charcoal grey ramp
+        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
@@ -594,9 +597,9 @@ export const TextAndBorderColors: StoryObj = {
 
       <SectionTitle>Border</SectionTitle>
       <View style={{ gap: 16 }}>
-        <ColorSwatch name="border-default" value={semanticColorsDark['border-default']} />
-        <ColorSwatch name="border-subtle" value={semanticColorsDark['border-subtle']} />
-        <ColorSwatch name="border-strong" value={semanticColorsDark['border-strong']} />
+        <ColorSwatch name="hairline-default" value={semanticColorsDark['hairline-default']} />
+        <ColorSwatch name="hairline-subtle" value={semanticColorsDark['hairline-subtle']} />
+        <ColorSwatch name="hairline-strong" value={semanticColorsDark['hairline-strong']} />
         <ColorSwatch name="border-prominent" value={semanticColorsDark['border-prominent']} />
         <ColorSwatch name="border-focus" value={semanticColorsDark['border-focus']} />
         <ColorSwatch name="border-input" value={semanticColorsDark['border-input']} />
@@ -626,7 +629,7 @@ const SEM = {
   brandDark: semanticColorsDark['brand-primary-dark'],
   brandSecondary: semanticColorsDark['brand-secondary'],
   spinner: SPINNER_PRIMARY,
-  neutral: primitiveColors.neutral[500],
+  neutral: greyRamp[600],
 } as const
 
 export const RolesInUse: StoryObj = {

package/src/theme/ColorPrimitives.stories.tsx

@@ -3,8 +3,8 @@ import { View, Text } from 'react-native'
 import {
   primitiveColors,
   primitiveRamps,
-  surfaceRampDark,
-  backgroundFrameDark,
+  greyRamp,
+  SURFACE_PLANE_STEPS,
   categoricalPalette,
   CATEGORICAL_CVD_SAFE_MAX,
 } from './tokens/primitives'
@@ -25,18 +25,12 @@ import {
  * organisations OF these scales — surfaces, categorical, status, brand,
  * fatigue and the rest — live in the sibling `Foundations/Color/Palettes`.
  *
- * This page is a MENU: everything on it is something you may legitimately
- * reach for today and that survives the migration ahead. The older
- * `primitiveColors` scales — `charcoal`, `neutral`, `redVivid`, and the support
- * `blue`/`red` — are deliberately NOT rendered here even though they still have
- * call sites in `semantic.ts`, because TD-07.14 deletes them. A swatch on a
- * menu is an invitation, and no annotation is loud enough to cancel that; the
- * intro carries a one-line pointer instead, so a reader who comes looking for
- * charcoal learns where it went rather than assuming an oversight.
- *
- * The semantic tokens those scales currently back are still documented, with
- * swatches, in `Foundations/Color/Palettes` — which is what the coverage guard
- * checks, and why removing the scale rows here costs no coverage.
+ * This page is a MENU: everything on it is something you may legitimately reach
+ * for. It is now also the complete list — TD-07.14 deleted the five older
+ * `primitiveColors` scales (`charcoal`, `neutral`, `redVivid`, and the support
+ * `blue`/`red`) rather than leaving them shelved, so there is no longer a
+ * category of "real but don't pick these". The greys folded into `greyRamp`
+ * below; the chromatics into the OKLCH `primitiveRamps`.
  */
 const meta: Meta = {
   title: 'Foundations/Color/Primitives',
@@ -64,22 +58,55 @@ const KEYWORDS = [
   { name: 'black', value: primitiveColors.black },
 ] as const
 
+/** Which surface plane each ramp step backs, for the annotation row. */
+const PLANE_BY_STEP: Record<number, string> = Object.fromEntries(
+  Object.entries(SURFACE_PLANE_STEPS).map(([plane, step]) => [step, plane])
+)
+
+/** Steps whose value is byte-identical to what shipped in v0.10.0. */
+const ANCHOR_STEPS = new Set<number>(Object.values(SURFACE_PLANE_STEPS))
+
+const GREY_STEPS = Object.keys(greyRamp).map(Number).sort((a, b) => a - b)
+
 /**
- * The dark surface planes, darkest first — the greys you may actually pick.
+ * The grey ramp, rendered as a numbered scale with its plane aliases.
  *
- * Shown here as a ramp (values only) because a menu of raw scales with no greys
- * on it would be a lie. The depth semantics, the L* spacing rationale and the
- * per-plane semantic aliases live in the full `Foundations/Color/Palettes`
- * surface story, and are deliberately not duplicated.
+ * This story used to show six unnumbered plane NAMES here, which was the visible
+ * symptom of the greys not actually being a ramp. The numbers are the content:
+ * they are what let a border, a plane and a text colour be compared on one scale.
  */
-const SURFACE_STEPS: Record<string, string> = {
-  frame: backgroundFrameDark,
-  inset: surfaceRampDark.inset,
-  background: surfaceRampDark.background,
-  base: surfaceRampDark.base,
-  elevated: surfaceRampDark.elevated,
-  raised: surfaceRampDark.raised,
-  overlay: surfaceRampDark.overlay,
+function GreyRampRow() {
+  return (
+    <View style={{ flexDirection: 'row', gap: 4, marginBottom: 4 }}>
+      {GREY_STEPS.map((step) => {
+        const hex = greyRamp[step as keyof typeof greyRamp]
+        const plane = PLANE_BY_STEP[step]
+        return (
+          <View key={step} style={{ flex: 1, alignItems: 'stretch' }}>
+            <View
+              style={{
+                height: 76,
+                borderRadius: 6,
+                backgroundColor: hex,
+                borderWidth: ANCHOR_STEPS.has(step) ? 1.5 : 1,
+                borderColor: ANCHOR_STEPS.has(step) ? '#FF7900' : SWATCH_BORDER,
+              }}
+            />
+            <Text className="text-text-primary" style={{ fontSize: 10, fontWeight: '600', marginTop: 3 }}>
+              {step}
+              {ANCHOR_STEPS.has(step) ? ' ★' : ''}
+            </Text>
+            <Text className="text-text-tertiary" style={{ fontSize: 8 }}>
+              {hex.toUpperCase()}
+            </Text>
+            {plane ? (
+              <Text style={{ fontSize: 8, color: '#FF9628', marginTop: 1 }}>{plane}</Text>
+            ) : null}
+          </View>
+        )
+      })}
+    </View>
+  )
 }
 
 export const Ramps: StoryObj = {
@@ -97,13 +124,14 @@ export const Ramps: StoryObj = {
 
       <Text className="text-text-tertiary text-xs mb-6">
         Looking for <Text className="font-semibold">charcoal</Text>,{' '}
-        <Text className="font-semibold">neutral</Text>, <Text className="font-semibold">redVivid</Text>{' '}
-        or the support <Text className="font-semibold">blue</Text>/
-        <Text className="font-semibold">red</Text> scales? They are intentionally not shown — all
-        five retire into a unified warm grey ramp plus the OKLCH ramps under TD-07.14. They still
-        have call sites in `semantic.ts`, so the semantic tokens they back are real and documented
-        in Palettes; the raw scales are not on the menu because you should not be picking from
-        them. Spec: coordination/design-explorations/foundations/warm-grey-ramp/.
+        <Text className="font-semibold">neutral</Text>,{' '}
+        <Text className="font-semibold">redVivid</Text> or the support{' '}
+        <Text className="font-semibold">blue</Text>/<Text className="font-semibold">red</Text>{' '}
+        scales? All five were DELETED in TD-07.14, not shelved. The two grey scales folded into
+        the warm ramp below — they were cold (neutral ran R−B down to −26) while the surfaces had
+        been warm since v0.10.0, and nothing ever reconciled the two. The chromatics moved to the
+        OKLCH ramps above. Spec and generator:
+        sources/design/foundations/warm-grey-ramp/.
       </Text>
 
       <SectionTitle>Chromatic — OKLCH tonal ramps</SectionTitle>
@@ -119,15 +147,35 @@ export const Ramps: StoryObj = {
         <ScaleRow key={key} name={name} scale={primitiveRamps[key]} />
       ))}
 
-      <SectionTitle>Achromatic — the dark surface ramp</SectionTitle>
+      <SectionTitle>Achromatic — the warm grey ramp</SectionTitle>
+      <Text className="text-text-secondary text-xs mb-3">
+        The ONE grey scale. Fifteen steps, warm at every one (R−B never below +2), spaced by
+        perceptual lightness so a step is the same visual distance anywhere in the stack. It
+        replaced three separate scales — a cold <Text className="font-semibold">charcoal</Text>, a
+        cold <Text className="font-semibold">neutral</Text>, and a standalone surface ramp — which
+        is why the surface planes appear here as ordinary numbered steps rather than as a parallel
+        set of names.
+      </Text>
       <Text className="text-text-secondary text-xs mb-4">
-        The greys. A derived depth ladder rather than a generated hue ramp — spaced by perceptual
-        lightness so one step is the same visual distance anywhere in the stack. Shown here as
-        values; the depth semantics and the semantic tokens aliasing each plane are in the
-        Palettes surface story, and are not repeated. Apply them with{' '}
-        <Text className="font-semibold">&lt;Surface level&gt;</Text>, not by reading a step.
+        Two things about the numbering, both deliberate.{' '}
+        <Text className="font-semibold">975</Text> sits past the end of the shared grid: the
+        canonical L* ladder — the median of the seven chromatic ramps — stops at L*10.3, which is
+        step 950, and the bezel is L*3.8. There was no number left for it.{' '}
+        <Text className="font-semibold">850</Text> and <Text className="font-semibold">875</Text>{' '}
+        are quarter-steps because overlay, raised and elevated sit only ~2.7 L* apart and all three
+        collide on 900 at normal resolution. There is deliberately no{' '}
+        <Text className="font-semibold">inset</Text>: at ΔE 1.10 from the frame it was an
+        imperceptible duplicate, which is why <Text className="font-semibold">&lt;Surface
+        pressed&gt;</Text> kept collapsing into it.
+      </Text>
+      <GreyRampRow />
+      <Text className="text-text-tertiary text-xs mb-4">
+        <Text style={{ color: '#FF9628' }}>★ / orange outline</Text> = a step that also names a
+        surface plane, byte-identical to the value that shipped in v0.10.0 — the surfaces did not
+        move, only their names. Reach for planes with{' '}
+        <Text className="font-semibold">&lt;Surface level&gt;</Text> rather than by reading a step;
+        the depth semantics and per-plane token aliases are in the Palettes surface story.
       </Text>
-      <ScaleRow name="Surface (dark)" scale={SURFACE_STEPS} />
 
       <SectionTitle>Keywords</SectionTitle>
       <Text className="text-text-secondary text-xs mb-4">