@titan-design/react-ui 0.10.0 → 0.12.0

package/src/components/custom/charts/live-rep-growth.ts

@@ -0,0 +1,91 @@
+// The newest-rep grow-from-bottom entrance, shared by SetBarChart (hero / dual / ROM)
+// and VelocityStrip's framed + bare expanded charts. Promoted out of VelocityStrip so
+// every value-height bar family animates the live rep identically instead of re-rolling
+// the hook.
+import { useEffect, useState } from 'react'
+import { Animated, Easing } from 'react-native'
+
+const ANIMATION_EASING = Easing.bezier(0.22, 1, 0.36, 1)
+
+/**
+ * Growth-factor overshoot for a new-peak bar: it grows past its full height then
+ * settles back to 1 (a small bounce), rather than the plain 0→1 grow every other
+ * bar gets. Modest (12%) since it stretches actual bar HEIGHT, not a uniform scale
+ * — a large overshoot here reads as a much bigger jump than the same factor did
+ * against the old whole-bar scale pop.
+ */
+const PEAK_OVERSHOOT = 1.12
+
+function getReducedMotionPreference(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+/** Track the OS "reduce motion" preference; falls back to `false` (jsdom/SSR). */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(getReducedMotionPreference)
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)')
+    const handler = () => setReduced(mq.matches)
+    handler()
+    mq.addEventListener?.('change', handler)
+    return () => mq.removeEventListener?.('change', handler)
+  }, [])
+  return reduced
+}
+
+/**
+ * The newest-rep entrance shared by SetBarChart and the framed / bare `expanded` charts:
+ * the bar GROWS UP FROM THE BASELINE (0 → full height), reading as though it's tracking
+ * the rep as it lands. A new set peak overshoots past full height then settles (a small
+ * bounce) instead of the plain grow. Honors reduced motion (jumps straight to full
+ * height, no animation). Returns a 0→1(+overshoot) growth-factor `Animated.Value`;
+ * callers interpolate it against their own target height. Inert while `active` is
+ * false or no live rep is present.
+ */
+export function useLiveRepGrowth(
+  active: boolean,
+  liveRepIndex: number | undefined,
+  liveVelocity: number | undefined,
+  isNewPeak: boolean
+): Animated.Value {
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const [liveGrowth] = useState(() => new Animated.Value(1))
+  useEffect(() => {
+    if (!active || liveRepIndex == null || liveVelocity == null) return
+    if (prefersReducedMotion) {
+      liveGrowth.setValue(1)
+      return
+    }
+    liveGrowth.setValue(0)
+    if (isNewPeak) {
+      Animated.sequence([
+        Animated.timing(liveGrowth, {
+          toValue: PEAK_OVERSHOOT,
+          duration: 220,
+          easing: Easing.out(Easing.quad),
+          useNativeDriver: false,
+        }),
+        Animated.spring(liveGrowth, {
+          toValue: 1,
+          friction: 5,
+          tension: 140,
+          useNativeDriver: false,
+        }),
+      ]).start()
+    } else {
+      // Plain entrance: a clean ease-out grow with no overshoot (ANIMATION_EASING has
+      // no control point above y=1) — it reads as tracking the rep, not bouncing.
+      Animated.timing(liveGrowth, {
+        toValue: 1,
+        duration: 300,
+        easing: ANIMATION_EASING,
+        useNativeDriver: false,
+      }).start()
+    }
+  }, [active, liveRepIndex, liveVelocity, isNewPeak, prefersReducedMotion, liveGrowth])
+  return liveGrowth
+}
+
+export { ANIMATION_EASING }

package/src/components/custom/index.ts

@@ -9,6 +9,7 @@ export * from './TimerReadout'
 export * from './CircularTimer'
 export * from './Metric'
 export * from './Workout'
+export * from './Fatigue'
 export * from './Treemap'
 export * from './Scatter'
 export * from './Gauge'

package/src/components/custom/stepper/Stepper.stories.tsx

@@ -137,7 +137,7 @@ export const VerticalWithContent: Story = {
             <Text className="text-text-secondary text-sm">
               Fill in your profile details to continue.
             </Text>
-            <View className="bg-surface-input border border-border rounded-md px-3 py-2">
+            <View className="bg-surface-input border border-hairline rounded-md px-3 py-2">
               <Text className="text-text-secondary text-sm">Display Name</Text>
             </View>
           </View>

package/src/components/custom/stepper/Stepper.tsx

@@ -91,7 +91,7 @@ function StepConnector({ index }: StepConnectorProps) {
       <View
         className={cn(
           'flex-1 h-0.5 mx-2',
-          isCompleted ? 'bg-brand-primary' : 'bg-border'
+          isCompleted ? 'bg-brand-primary' : 'bg-hairline'
         )}
       />
     )
@@ -101,7 +101,7 @@ function StepConnector({ index }: StepConnectorProps) {
     <View
       className={cn(
         'w-0.5 h-8 ml-4 my-1',
-        isCompleted ? 'bg-brand-primary' : 'bg-border'
+        isCompleted ? 'bg-brand-primary' : 'bg-hairline'
       )}
     />
   )
@@ -171,7 +171,7 @@ export function StepIndicator({
   const statusStyles: Record<StepStatus, string> = {
     completed: 'bg-brand-primary border-brand-primary',
     active: 'bg-brand-primary border-brand-primary',
-    upcoming: 'bg-surface-base border-border-strong',
+    upcoming: 'bg-surface-base border-hairline-strong',
     error: 'bg-status-error border-status-error',
   }
 

package/src/components/shell/DeviceMenu.tsx

@@ -43,7 +43,7 @@ export function DeviceMenu({
       <PopoverTrigger>
         <DeviceIndicator status={status} />
       </PopoverTrigger>
-      <PopoverContent className="right-0 left-auto mt-[10px] w-[326px] bg-surface-elevated border border-border-strong rounded-[10px] p-[7px]">
+      <PopoverContent className="right-0 left-auto mt-[10px] w-[326px] bg-surface-elevated border border-hairline-strong rounded-[10px] p-[7px]">
         <Typography
           variant="monoLabel"
           color="tertiary"
@@ -52,7 +52,7 @@ export function DeviceMenu({
           Devices — {boundCount} bound · {availCount} available
         </Typography>
         {devices.map((device, i) => (
-          <View key={device.id} className={cn(i > 0 && 'border-t border-border')}>
+          <View key={device.id} className={cn(i > 0 && 'border-t border-hairline')}>
             <DeviceRow
               device={device}
               onPress={onSelectDevice ? () => onSelectDevice(device) : undefined}

package/src/components/shell/SideNav.tsx

@@ -55,7 +55,7 @@ export function SideNav({
     <View
       accessibilityRole="tablist"
       className={cn(
-        'w-[60px] items-center gap-[6px] border-r border-border bg-background-base py-3',
+        'w-[60px] items-center gap-[6px] border-r border-hairline bg-background-base py-3',
         className
       )}
     >

package/src/components/shell/TopBar.tsx

@@ -58,7 +58,7 @@ export function TopBar({
       // shared chrome gradient (web); solid bg-surface-elevated is the native fallback
       style={surfaceGradient.chrome() as object}
       className={cn(
-        'h-[46px] flex-row items-center gap-[14px] px-4 bg-surface-elevated border-b border-border',
+        'h-[46px] flex-row items-center gap-[14px] px-4 bg-surface-elevated border-b border-hairline',
         className
       )}
     >

package/src/components/ui/autocomplete/Autocomplete.stories.tsx

@@ -287,7 +287,7 @@ export const FormExample: Story = {
           isRequired
         />
 
-        <View className="pt-2 border-t border-border">
+        <View className="pt-2 border-t border-hairline">
           <Text className="text-sm text-text-secondary">
             Selected: {country ? `${countryOptions.find(c => c.value === country)?.label}` : '-'}
             {city ? `, ${cityOptions[country!]?.find(c => c.value === city)?.label}` : ''}

package/src/components/ui/autocomplete/Autocomplete.tsx

@@ -238,7 +238,7 @@ export function Autocomplete<T extends string = string>({
           <View
             className={cn(
               'absolute z-50 top-full left-0 right-0 mt-1',
-              'bg-surface-elevated rounded-md shadow-lg border border-border',
+              'bg-surface-elevated rounded-md shadow-lg border border-hairline',
               'max-h-60 overflow-hidden'
             )}
           >

package/src/components/ui/avatar/Avatar.tsx

@@ -67,7 +67,7 @@ export function Avatar({
       accessibilityLabel={alt || resolvedFallback || 'Avatar'}
       className={cn(
         'items-center justify-center rounded-full overflow-hidden',
-        !nameColor && 'bg-border-strong',
+        !nameColor && 'bg-hairline-strong',
         styles.container,
         className
       )}
@@ -102,7 +102,7 @@ const badgeColors: Record<string, string> = {
   success: 'bg-status-success',
   error: 'bg-status-error',
   warning: 'bg-status-warning',
-  default: 'bg-border-strong',
+  default: 'bg-hairline-strong',
 }
 
 /**

package/src/components/ui/badge/Badge.tsx

@@ -25,7 +25,7 @@ export interface BadgeProps extends ViewProps {
 
 const variantColorStyles: Record<BadgeVariant, Record<BadgeColor, string>> = {
   solid: {
-    default: 'bg-border-strong text-text-inverse',
+    default: 'bg-hairline-strong text-text-inverse',
     primary: 'bg-brand-primary text-text-inverse',
     secondary: 'bg-brand-secondary text-text-inverse',
     success: 'bg-status-success text-text-inverse',
@@ -43,7 +43,7 @@ const variantColorStyles: Record<BadgeVariant, Record<BadgeColor, string>> = {
     info: 'bg-status-info-subtle text-status-info',
   },
   outline: {
-    default: 'border border-border-strong text-text-secondary',
+    default: 'border border-hairline-strong text-text-secondary',
     primary: 'border border-brand-primary text-brand-primary',
     secondary: 'border border-brand-secondary text-brand-secondary',
     success: 'border border-status-success text-status-success',

package/src/components/ui/card/Card.tsx

@@ -45,10 +45,10 @@ export interface CardProps extends ViewProps {
 
 const variantStyles: Record<CardVariant, string> = {
   elevated: '', // Will be set dynamically via elevation system
-  outline: 'border-2 border-border-strong',  // Thicker border with stronger contrast
+  outline: 'border-2 border-hairline-strong',  // Thicker border with stronger contrast
   filled: '', // Will be set dynamically via elevation system
-  accent: 'border border-border',
-  subtle: 'border border-border-subtle',
+  accent: 'border border-hairline',
+  subtle: 'border border-hairline-subtle',
 }
 
 /**

package/src/components/ui/checkbox/Checkbox.tsx

@@ -91,7 +91,7 @@ export const Checkbox = forwardRef<View, CheckboxProps>(function Checkbox(
           styles.box,
           isChecked || isIndeterminate
             ? 'bg-brand-primary border-brand-primary'
-            : 'bg-transparent border-border',
+            : 'bg-transparent border-hairline',
           isInvalid && 'border-status-error',
           !isDisabled && 'web:hover:border-brand-primary'
         )}

package/src/components/ui/collapse/Collapse.tsx

@@ -180,7 +180,7 @@ export function Accordion({
 
   return (
     <AccordionContext.Provider value={{ openIndices, toggleIndex, allowMultiple }}>
-      <View className={cn('w-full divide-y divide-border', className)} {...props}>
+      <View className={cn('w-full divide-y divide-hairline', className)} {...props}>
         {React.Children.map(children, (child, index) => {
           if (React.isValidElement(child)) {
             return React.cloneElement(child as React.ReactElement<any>, { index })

package/src/components/ui/data-row/DataRow.stories.tsx

@@ -73,6 +73,6 @@ export const CustomClassName: Story = {
   args: {
     label: 'Bordered Row',
     value: 'With custom styles',
-    className: 'border-b border-border px-4',
+    className: 'border-b border-hairline px-4',
   },
 }

package/src/components/ui/drawer/Drawer.tsx

@@ -125,7 +125,7 @@ export function Drawer({
         >
           {/* Header */}
           {(title || showCloseButton) && (
-            <View className="flex-row items-center justify-between px-4 py-3 border-b border-border">
+            <View className="flex-row items-center justify-between px-4 py-3 border-b border-hairline">
               {title && (
                 <Text className="text-lg font-semibold text-text-primary">
                   {title}
@@ -165,7 +165,7 @@ export interface DrawerHeaderProps extends ViewProps {
 export function DrawerHeader({ className, children, ...props }: DrawerHeaderProps) {
   return (
     <View
-      className={cn('px-4 py-3 border-b border-border', className)}
+      className={cn('px-4 py-3 border-b border-hairline', className)}
       {...props}
     >
       {children}
@@ -217,7 +217,7 @@ export function DrawerFooter({ className, children, ...props }: DrawerFooterProp
     <View
       className={cn(
         'flex-row items-center justify-end gap-3',
-        'px-4 py-3 border-t border-border',
+        'px-4 py-3 border-t border-hairline',
         className
       )}
       {...props}

package/src/components/ui/form-field/FormField.tsx

@@ -253,7 +253,7 @@ export function FormActions({
     <View
       className={cn(
         'flex-row items-center gap-3 pt-4',
-        'border-t border-border mt-4',
+        'border-t border-hairline mt-4',
         alignStyles[align],
         className
       )}

package/src/components/ui/help-tip/HelpTip.tsx

@@ -155,7 +155,7 @@ export function HelpTip({
           className={cn(
             'absolute z-50',
             'bg-surface-elevated rounded-lg shadow-lg',
-            'border border-border',
+            'border border-hairline',
             'px-3 py-2',
             placementStyles[placement],
             tooltipClassName

package/src/components/ui/menu/Menu.tsx

@@ -116,7 +116,7 @@ export function MenuList({ children, className }: MenuListProps) {
       <View
         className={cn(
           'absolute z-50 top-full left-0 mt-1 min-w-[160px]',
-          'bg-surface-elevated rounded-lg shadow-lg border border-border',
+          'bg-surface-elevated rounded-lg shadow-lg border border-hairline',
           'py-1 overflow-hidden',
           className
         )}
@@ -195,7 +195,7 @@ export interface MenuDividerProps {
  * Divider between menu items.
  */
 export function MenuDivider({ className }: MenuDividerProps) {
-  return <View className={cn('h-px bg-border my-1', className)} />
+  return <View className={cn('h-px bg-hairline my-1', className)} />
 }
 
 export interface MenuGroupProps {

package/src/components/ui/pill/Pill.tsx

@@ -27,7 +27,7 @@ export interface PillProps extends ViewProps {
 
 const variantColorStyles: Record<PillVariant, Record<PillColor, string>> = {
   subtle: {
-    default: 'bg-surface-raised border-border-subtle text-text-secondary',
+    default: 'bg-surface-raised border-hairline-subtle text-text-secondary',
     primary: 'bg-brand-primary/10 border-brand-primary/25 text-brand-primary',
     secondary: 'bg-brand-secondary/10 border-brand-secondary/25 text-brand-secondary',
     success: 'bg-status-success/10 border-status-success/25 text-status-success',
@@ -36,7 +36,7 @@ const variantColorStyles: Record<PillVariant, Record<PillColor, string>> = {
     info: 'bg-status-info/10 border-status-info/25 text-status-info',
   },
   outline: {
-    default: 'border-border text-text-secondary',
+    default: 'border-hairline text-text-secondary',
     primary: 'border-brand-primary text-brand-primary',
     secondary: 'border-brand-secondary text-brand-secondary',
     success: 'border-status-success text-status-success',

package/src/components/ui/popover/Popover.stories.tsx

@@ -152,12 +152,12 @@ export const WithFormContent: Story = {
           <Text className="text-text-secondary text-xs">
             Enter your new display name below.
           </Text>
-          <View className="bg-surface-input border border-border rounded-md px-3 py-2">
+          <View className="bg-surface-input border border-hairline rounded-md px-3 py-2">
             <Text className="text-text-secondary text-sm">John Doe</Text>
           </View>
           <View style={{ flexDirection: 'row', gap: 8, justifyContent: 'flex-end' }}>
             <PopoverCloseButton>
-              <View className="px-3 py-1.5 rounded-md bg-surface-elevated border border-border">
+              <View className="px-3 py-1.5 rounded-md bg-surface-elevated border border-hairline">
                 <Text className="text-text-primary text-sm">Cancel</Text>
               </View>
             </PopoverCloseButton>

package/src/components/ui/popover/Popover.tsx

@@ -188,7 +188,7 @@ export function PopoverContent({ children, className }: PopoverContentProps) {
       <View
         className={cn(
           'absolute z-50 min-w-[200px]',
-          'bg-surface-elevated rounded-lg shadow-lg border border-border',
+          'bg-surface-elevated rounded-lg shadow-lg border border-hairline',
           'p-4',
           placementStyles[placement],
           className

package/src/components/ui/progress/Progress.tsx

@@ -230,7 +230,7 @@ export function CircularProgress({
             cy={center}
             r={radius}
             fill="none"
-            stroke="var(--color-border-default)"
+            stroke="var(--color-hairline-default)"
             strokeWidth={strokeWidth}
           />
           {/* Progress arc */}
@@ -325,7 +325,7 @@ export function ProgressSteps({
               className={cn(
                 'rounded-full',
                 dot,
-                index <= currentStep ? colorStyles[color] : 'bg-border-strong'
+                index <= currentStep ? colorStyles[color] : 'bg-hairline-strong'
               )}
             />
 
@@ -335,7 +335,7 @@ export function ProgressSteps({
                 className={cn(
                   'flex-1 mx-1',
                   connector,
-                  index < currentStep ? colorStyles[color] : 'bg-border-strong'
+                  index < currentStep ? colorStyles[color] : 'bg-hairline-strong'
                 )}
               />
             )}

package/src/components/ui/radio/Radio.stories.tsx

@@ -188,7 +188,7 @@ export const FormExample: Story = {
           <Radio value="yearly">Yearly (save 20%)</Radio>
         </RadioGroup>
         
-        <View className="pt-4 border-t border-border">
+        <View className="pt-4 border-t border-hairline">
           <Text className="text-sm text-text-secondary">
             Selected: {plan} plan, billed {billing}
           </Text>

package/src/components/ui/radio/Radio.tsx

@@ -117,10 +117,10 @@ const sizeConfig: Record<RadioSize, { outer: string; inner: string; text: string
 }
 
 const colorStyles: Record<RadioColor, { checked: string; unchecked: string }> = {
-  primary: { checked: 'border-brand-primary bg-brand-primary', unchecked: 'border-border-strong' },
-  secondary: { checked: 'border-brand-secondary bg-brand-secondary', unchecked: 'border-border-strong' },
-  success: { checked: 'border-status-success bg-status-success', unchecked: 'border-border-strong' },
-  error: { checked: 'border-status-error bg-status-error', unchecked: 'border-border-strong' },
+  primary: { checked: 'border-brand-primary bg-brand-primary', unchecked: 'border-hairline-strong' },
+  secondary: { checked: 'border-brand-secondary bg-brand-secondary', unchecked: 'border-hairline-strong' },
+  success: { checked: 'border-status-success bg-status-success', unchecked: 'border-hairline-strong' },
+  error: { checked: 'border-status-error bg-status-error', unchecked: 'border-hairline-strong' },
 }
 
 /**

package/src/components/ui/select/Select.tsx

@@ -145,7 +145,7 @@ export function Select<T extends string = string>({
             isInvalid
               ? 'border-border-input-error'
               : variant === 'filled'
-                ? 'border-border-subtle'
+                ? 'border-hairline-subtle'
                 : 'border-border-input',
             !isDisabled && !isInvalid && 'web:hover:border-border-input-hover',
             isOpen && 'border-border-input-focus',
@@ -187,7 +187,7 @@ export function Select<T extends string = string>({
             <View
               className={cn(
                 'absolute z-50 top-full left-0 right-0 mt-1',
-                'bg-surface-elevated rounded-md shadow-lg border border-border',
+                'bg-surface-elevated rounded-md shadow-lg border border-hairline',
                 'max-h-60 overflow-hidden'
               )}
             >
@@ -229,7 +229,7 @@ function SelectOption<T>({ option }: SelectOptionComponentProps<T>) {
         <View
           className={cn(
             'w-4 h-4 mr-3 rounded border',
-            selected ? 'bg-brand-primary border-brand-primary' : 'border-border-strong'
+            selected ? 'bg-brand-primary border-brand-primary' : 'border-hairline-strong'
           )}
         >
           {selected && <Text className="text-white text-xs text-center">✓</Text>}

package/src/components/ui/surface/Surface.stories.tsx

@@ -15,8 +15,8 @@ const meta: Meta<typeof Surface> = {
     },
     level: {
       control: 'select',
-      options: ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'],
-      description: 'Named charcoal plane (flat background from a semantic token)',
+      options: ['frame', 'background', 'base', 'elevated', 'raised', 'overlay'],
+      description: 'Named grey plane (flat background from a semantic token)',
     },
     pressed: {
       control: 'boolean',
@@ -88,7 +88,7 @@ export const WithGlow: Story = {
   ),
 }
 
-// The named-plane model: flat, full-bleed charcoal planes straight from the
+// The named-plane model: flat, full-bleed grey planes straight from the
 // semantic surface tokens — reaching the darker nav/page shades the numeric
 // lighten model can't. These back the shell / rail / stage.
 export const NamedPlanes: Story = {

package/src/components/ui/surface/Surface.test.tsx

@@ -11,6 +11,7 @@ import {
   useSurface,
   useSurfaceMode,
 } from './SurfaceContext'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 import { getPressedRecessShadow } from '../../../theme/elevation'
 
 // A descendant probe that renders the on-surface colour + mode it resolves from
@@ -157,17 +158,17 @@ describe('Surface (pressed well)', () => {
     expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
   })
 
-  it('clamps at the inset floor: pressed directly in background does not underflow', () => {
+  it('clamps at the frame floor: pressed directly in background does not underflow', () => {
     render(
       <Surface level="background">
         <Surface pressed testID="well" />
       </Surface>
     )
-    // background (#1C1916) steps down to the inset floor (#13100D), the pit.
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#13100D' })
+    // background (#1C1916) steps down to the frame floor (#100D0A), the bezel.
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#100D0A' })
   })
 
-  it('does not step below the floor: pressed within a floor-pressed well stays at inset', () => {
+  it('does not step below the floor: pressed within a floor-pressed well stays at frame', () => {
     render(
       <Surface level="background">
         <Surface pressed>
@@ -175,7 +176,7 @@ describe('Surface (pressed well)', () => {
         </Surface>
       </Surface>
     )
-    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: '#13100D' })
+    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: '#100D0A' })
   })
 
   it('publishes the stepped-down level to descendants so a nested press steps again', () => {
@@ -230,9 +231,9 @@ describe('pressedLevel helper', () => {
     ['raised', 'elevated'],
     ['elevated', 'base'],
     ['base', 'background'],
-    ['background', 'inset'],
-    ['inset', 'inset'],
-  ] as const)('steps %s down to %s (clamped at inset)', (parent, expected) => {
+    ['background', 'frame'],
+    ['frame', 'frame'],
+  ] as const)('steps %s down to %s (clamped at frame)', (parent, expected) => {
     expect(pressedLevel(parent)).toBe(expected)
   })
 })
@@ -253,14 +254,15 @@ describe('Surface on-surface colour context', () => {
         <Probe role="tertiary" label="t" />
       </Surface>
     )
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#F3F4F6' })
-    expect(screen.getByTestId('s')).toHaveStyle({ color: '#9CA3AF' })
-    expect(screen.getByTestId('t')).toHaveStyle({ color: '#6B7280' })
+    const t = getSemanticColors('dark')
+    expect(screen.getByTestId('p')).toHaveStyle({ color: t['text-primary'] })
+    expect(screen.getByTestId('s')).toHaveStyle({ color: t['text-secondary'] })
+    expect(screen.getByTestId('t')).toHaveStyle({ color: t['text-tertiary'] })
   })
 
   it('resolves dark on-surface colours even with no enclosing Surface', () => {
     render(<Probe role="primary" label="p" />)
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#F3F4F6' })
+    expect(screen.getByTestId('p')).toHaveStyle({ color: getSemanticColors('dark')['text-primary'] })
   })
 
   it('flows an overridden theme to descendant text', () => {
@@ -292,15 +294,26 @@ describe('surface colour helpers', () => {
     expect(surfaceBackground('base', 'light')).toBe('#FFFFFF')
   })
 
-  it('resolves the inset floor from the surfaceRampDark.inset primitive (no token yet)', () => {
-    expect(surfaceBackground('inset', 'dark')).toBe('#13100D')
+  it('resolves the frame floor from its own semantic token', () => {
+    // The old `inset` level had no token and fell back to a primitive. `frame`
+    // has `background-frame`, which is what let SurfaceContext drop the special
+    // case in surfaceBackground().
+    expect(surfaceBackground('frame', 'dark')).toBe(getSemanticColors('dark')['background-frame'])
   })
 
-  it('onSurfaceColors returns the neutral text ramp as literal hex', () => {
-    expect(onSurfaceColors('dark')).toEqual({
-      primary: '#F3F4F6',
-      secondary: '#9CA3AF',
-      tertiary: '#6B7280',
+  it('onSurfaceColors returns the text ramp as literal hex', () => {
+    const t = getSemanticColors('dark')
+    const got = onSurfaceColors('dark')
+    expect(got).toEqual({
+      primary: t['text-primary'],
+      secondary: t['text-secondary'],
+      tertiary: t['text-tertiary'],
     })
+    // The actual contract this test guards: LITERAL hex, never a var() — under
+    // the RNW alias resolveColor() returns 'var(--color-…)', which silently
+    // breaks any consumer doing colour maths on the result.
+    for (const [role, value] of Object.entries(got)) {
+      expect(value, role).toMatch(/^#[0-9A-F]{6}$/i)
+    }
   })
 })

package/src/components/ui/surface/Surface.tsx

@@ -28,7 +28,7 @@ export interface SurfaceProps extends ViewProps {
    */
   elevation?: ElevationLevel
   /**
-   * Named charcoal plane (shell / rail / stage). Sets the background directly
+   * Named grey plane (shell / rail / stage). Sets the background directly
    * from a semantic surface token — reaching the darker nav/page planes the
    * lighten model can't — and drops the default rounding + auto shadow so the
    * plane reads full-bleed. Composable with `elevation`'s glow.
@@ -61,7 +61,7 @@ export interface SurfaceProps extends ViewProps {
  * A container that OWNS its background and establishes an on-surface colour
  * context. Two grounded ways to pick the background:
  *  - `elevation` (numeric): the raised-card model — lighten-from-base + shadow.
- *  - `level` (named): a flat charcoal plane straight from a semantic token,
+ *  - `level` (named): a flat grey plane straight from a semantic token,
  *    for the shell / rail / stage backgrounds.
  * Either way, descendants read the surface via {@link useOnSurfaceColor} /
  * {@link useSurfaceMode} rather than hard-coding `getSemanticColors('dark')`.
@@ -86,7 +86,7 @@ export function Surface({
   // Three grounded ways to own a background, in precedence order:
   //  - pressed: a well ONE ramp step DOWN from the parent level (relative),
   //    with an inner-shadow recess — clamps at the `inset` floor.
-  //  - level (named plane): a flat charcoal plane straight from a token.
+  //  - level (named plane): a flat grey plane straight from a token.
   //  - elevation (numeric): the raised-card model — lighten-from-base + shadow.
   const baseColor = getBaseSurfaceColor(mode)
   const resolvedLevel = pressed ? pressedLevel(inherited.level) : (level ?? inherited.level)