@titan-design/react-ui 0.12.1 → 0.14.0

package/src/components/ui/skeleton/Skeleton.stories.tsx

@@ -1,17 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View } from 'react-native'
-import {
-  Skeleton,
-  SkeletonText,
-  SkeletonCircle,
-  SkeletonCard,
-  SkeletonListItem,
-} from './Skeleton'
+import { Skeleton, SkeletonText, SkeletonCircle, SkeletonCard, SkeletonListItem } from './Skeleton'
 
 const meta: Meta<typeof Skeleton> = {
   title: 'Components/Atoms/Skeleton',
   component: Skeleton,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     variant: {
       control: 'select',
@@ -64,9 +58,7 @@ export const RectVariant: Story = {
 }
 
 export const RoundedVariant: Story = {
-  render: () => (
-    <Skeleton variant="rounded" width={300} height={200} />
-  ),
+  render: () => <Skeleton variant="rounded" width={300} height={200} />,
 }
 
 export const TextBlock: Story = {

package/src/components/ui/skeleton/Skeleton.tsx

@@ -136,11 +136,7 @@ export interface SkeletonCircleProps {
 /**
  * Circle skeleton for avatars.
  */
-export function SkeletonCircle({
-  size = 40,
-  animation = 'pulse',
-  className,
-}: SkeletonCircleProps) {
+export function SkeletonCircle({ size = 40, animation = 'pulse', className }: SkeletonCircleProps) {
   return (
     <Skeleton
       variant="circle"
@@ -179,12 +175,7 @@ export function SkeletonCard({
   return (
     <View className={cn('rounded-lg overflow-hidden bg-surface-elevated', className)}>
       {hasImage && (
-        <Skeleton
-          variant="rect"
-          width="100%"
-          height={imageHeight}
-          animation={animation}
-        />
+        <Skeleton variant="rect" width="100%" height={imageHeight} animation={animation} />
       )}
       <View className="p-4 gap-3">
         <Skeleton variant="text" width="70%" animation={animation} />
@@ -218,9 +209,7 @@ export function SkeletonListItem({
 }: SkeletonListItemProps) {
   return (
     <View className={cn('flex-row items-center gap-3 p-3', className)}>
-      {hasAvatar && (
-        <SkeletonCircle size={avatarSize} animation={animation} />
-      )}
+      {hasAvatar && <SkeletonCircle size={avatarSize} animation={animation} />}
       <View className="flex-1">
         <SkeletonText lines={lines} animation={animation} />
       </View>

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

@@ -1,10 +1,4 @@
-export {
-  Skeleton,
-  SkeletonText,
-  SkeletonCircle,
-  SkeletonCard,
-  SkeletonListItem,
-} from './Skeleton'
+export { Skeleton, SkeletonText, SkeletonCircle, SkeletonCard, SkeletonListItem } from './Skeleton'
 export type {
   SkeletonProps,
   SkeletonTextProps,

package/src/components/ui/spinner/Spinner.stories.tsx

@@ -5,7 +5,7 @@ import { Spinner } from './Spinner'
 const meta: Meta<typeof Spinner> = {
   title: 'Components/Atoms/Spinner',
   component: Spinner,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     size: {
       control: 'select',

package/src/components/ui/spinner/Spinner.tsx

@@ -2,6 +2,7 @@ import React from 'react'
 import { ActivityIndicator, View, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
 import { SPINNER_PRIMARY, SPINNER_SECONDARY } from '../../../theme/extracted-colors-ui'
+import { primitiveColors } from '../../../theme/tokens/primitives'
 
 export type SpinnerSize = 'sm' | 'md' | 'lg' | 'xl'
 export type SpinnerColor = 'primary' | 'secondary' | 'white' | 'default'
@@ -27,7 +28,8 @@ const sizeMap: Record<SpinnerSize, 'small' | 'large'> = {
 const colorMap: Record<SpinnerColor, string> = {
   primary: SPINNER_PRIMARY,
   secondary: SPINNER_SECONDARY,
-  white: '#FFFFFF',
+  white: primitiveColors.white,
+  // VW-82: Tailwind gray-500; no titan grey matches. Left raw, proposed in the PR.
   default: '#6B7280',
 }
 
@@ -64,10 +66,7 @@ export function Spinner({
       className={cn('items-center justify-center', containerSizes[size], className)}
       {...props}
     >
-      <ActivityIndicator
-        size={sizeMap[size]}
-        color={colorMap[color]}
-      />
+      <ActivityIndicator size={sizeMap[size]} color={colorMap[color]} />
     </View>
   )
 }

package/src/components/ui/stack/Stack.stories.tsx

@@ -5,7 +5,7 @@ import { Stack, HStack, VStack } from './Stack'
 const meta: Meta<typeof Stack> = {
   title: 'Components/Atoms/Stack',
   component: Stack,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     gap: {
       control: 'select',
@@ -35,7 +35,7 @@ type Story = StoryObj<typeof Stack>
 function Box({ children }: { children: string }) {
   return (
     <View className="rounded bg-brand-primary px-4 py-2">
-      <Text className="text-sm text-white">{children}</Text>
+      <Text className="text-sm text-on-brand-primary">{children}</Text>
     </View>
   )
 }
@@ -76,23 +76,23 @@ export const Vertical: Story = {
 export const WithAlignment: Story = {
   render: () => (
     <VStack gap={6}>
-      <Text className="text-sm font-medium text-neutral-400">justify=&quot;between&quot;</Text>
+      <Text className="text-sm font-medium text-text-secondary">justify=&quot;between&quot;</Text>
       <HStack gap={2} justify="between" className="w-full">
         <Box>A</Box>
         <Box>B</Box>
         <Box>C</Box>
       </HStack>
 
-      <Text className="text-sm font-medium text-neutral-400">align=&quot;center&quot;</Text>
+      <Text className="text-sm font-medium text-text-secondary">align=&quot;center&quot;</Text>
       <HStack gap={2} align="center">
         <View className="rounded bg-brand-primary px-4 py-1">
-          <Text className="text-sm text-white">Short</Text>
+          <Text className="text-sm text-on-brand-primary">Short</Text>
         </View>
         <View className="rounded bg-brand-primary px-4 py-4">
-          <Text className="text-sm text-white">Tall</Text>
+          <Text className="text-sm text-on-brand-primary">Tall</Text>
         </View>
         <View className="rounded bg-brand-primary px-4 py-2">
-          <Text className="text-sm text-white">Medium</Text>
+          <Text className="text-sm text-on-brand-primary">Medium</Text>
         </View>
       </HStack>
     </VStack>
@@ -114,7 +114,7 @@ export const GapScale: Story = {
     <VStack gap={6}>
       {([0, 1, 2, 4, 6, 8, 12] as const).map((g) => (
         <VStack key={g} gap={1}>
-          <Text className="text-xs text-neutral-400">gap={g}</Text>
+          <Text className="text-xs text-text-secondary">gap={g}</Text>
           <HStack gap={g}>
             <Box>A</Box>
             <Box>B</Box>

package/src/components/ui/stack/Stack.tsx

@@ -58,7 +58,7 @@ export function Stack({
         align && alignMap[align],
         justify && justifyMap[justify],
         wrap && 'flex-wrap',
-        className,
+        className
       )}
       {...props}
     >

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

@@ -3,25 +3,36 @@ import { View, Text } from 'react-native'
 import { Surface } from './Surface'
 import { useOnSurfaceColor, type SurfaceLevel } from './SurfaceContext'
 import type { ElevationLevel } from '../../../theme/elevation'
+import { semanticColorsLight, semanticColorsDark } from '../../../theme/tokens/semantic'
+import { primitiveRamps } from '../../../theme/tokens/primitives'
 
 const meta: Meta<typeof Surface> = {
   title: 'Components/Atoms/Surface',
   component: Surface,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     elevation: {
       control: { type: 'range', min: -2, max: 5, step: 1 },
-      description: 'Elevation level (-2 to 5)',
+      description:
+        'Depth relative to the enclosing Surface: <0 recess, 0 flat, 1–3 lift a plane each, 4–5 float',
+    },
+    raise: {
+      control: { type: 'range', min: 1, max: 3, step: 1 },
+      description: 'Planes to step UP from the enclosing Surface, with the lift treatment',
     },
     level: {
       control: 'select',
       options: ['frame', 'background', 'base', 'elevated', 'raised', 'overlay'],
-      description: 'Named grey plane (flat background from a semantic token)',
+      description: 'Absolute grey plane for a shell root (flat, no lift)',
     },
     pressed: {
       control: 'boolean',
       description: 'Sunken well: one ramp step DOWN from the parent level + inner-shadow recess',
     },
+    lift: {
+      control: 'boolean',
+      description: 'Force the rim + shadow treatment on or off',
+    },
     theme: {
       control: 'select',
       options: ['light', 'dark'],
@@ -47,45 +58,88 @@ export const Default: Story = {
     elevation: 2,
     theme: 'dark',
   },
-  render: (args) => (
-    <Surface {...args} style={{ padding: 24 }}>
-      <Text style={{ color: '#fff' }}>Default Surface</Text>
-    </Surface>
-  ),
+  render: function Render(args) {
+    return (
+      <Surface {...args} style={{ padding: 24 }}>
+        <Text style={{ color: useOnSurfaceColor('primary') }}>Default Surface</Text>
+      </Surface>
+    )
+  },
+}
+
+/** On-surface elevation label — resolves from whichever Surface encloses it. */
+function ElevationLabel({ level }: { level: ElevationLevel }) {
+  return <Text style={{ color: useOnSurfaceColor('primary') }}>Elevation {level}</Text>
 }
 
+// Every level is a ramp plane. Negative levels recess, 0 sits flat on the page,
+// 1–3 climb one plane each with the lift treatment, 4–5 float on overlay with a
+// larger shadow. Rendered on a `base` page so the relative model has a host.
 export const ElevationLevels: Story = {
   render: () => (
-    <View style={{ gap: 16, padding: 24 }}>
+    <Surface level="base" style={{ gap: 16, padding: 24 }}>
       {([-2, -1, 0, 1, 2, 3, 4, 5] as ElevationLevel[]).map((level) => (
         <Surface key={level} elevation={level} style={{ padding: 16 }}>
-          <Text style={{ color: '#fff' }}>Elevation {level}</Text>
+          <ElevationLabel level={level} />
         </Surface>
       ))}
-    </View>
+    </Surface>
   ),
 }
 
 export const WithGlow: Story = {
-  render: () => (
-    <View style={{ gap: 16, padding: 24 }}>
-      <Surface elevation={2} glowColor="#FF7900" glowIntensity="subtle" style={{ padding: 16 }}>
-        <Text style={{ color: '#fff' }}>Subtle Orange Glow</Text>
-      </Surface>
-      <Surface elevation={2} glowColor="#FF7900" glowIntensity="medium" style={{ padding: 16 }}>
-        <Text style={{ color: '#fff' }}>Medium Orange Glow</Text>
-      </Surface>
-      <Surface elevation={2} glowColor="#FF7900" glowIntensity="strong" style={{ padding: 16 }}>
-        <Text style={{ color: '#fff' }}>Strong Orange Glow</Text>
-      </Surface>
-      <Surface elevation={2} glowColor="#22C55E" glowIntensity="medium" style={{ padding: 16 }}>
-        <Text style={{ color: '#fff' }}>Green Glow (Success)</Text>
-      </Surface>
-      <Surface elevation={2} glowColor="#EF4444" glowIntensity="medium" style={{ padding: 16 }}>
-        <Text style={{ color: '#fff' }}>Red Glow (Error)</Text>
-      </Surface>
-    </View>
-  ),
+  render: function Render() {
+    const onSurface = useOnSurfaceColor('primary')
+    return (
+      <View style={{ gap: 16, padding: 24 }}>
+        <Surface
+          elevation={2}
+          glowColor={primitiveRamps.orange[400]}
+          glowIntensity="subtle"
+          style={{ padding: 16 }}
+        >
+          <Text style={{ color: onSurface }}>Subtle Orange Glow</Text>
+        </Surface>
+        <Surface
+          elevation={2}
+          glowColor={primitiveRamps.orange[400]}
+          glowIntensity="medium"
+          style={{ padding: 16 }}
+        >
+          <Text style={{ color: onSurface }}>Medium Orange Glow</Text>
+        </Surface>
+        <Surface
+          elevation={2}
+          glowColor={primitiveRamps.orange[400]}
+          glowIntensity="strong"
+          style={{ padding: 16 }}
+        >
+          <Text style={{ color: onSurface }}>Strong Orange Glow</Text>
+        </Surface>
+        <Surface
+          elevation={2}
+          glowColor={semanticColorsDark['status-success']}
+          glowIntensity="medium"
+          style={{ padding: 16 }}
+        >
+          <Text style={{ color: onSurface }}>Green Glow (Success)</Text>
+        </Surface>
+        <Surface
+          elevation={2}
+          glowColor={semanticColorsDark['status-error']}
+          glowIntensity="medium"
+          style={{ padding: 16 }}
+        >
+          <Text style={{ color: onSurface }}>Red Glow (Error)</Text>
+        </Surface>
+      </View>
+    )
+  },
+}
+
+/** On-surface plane label — resolves from whichever Surface encloses it. */
+function NamedPlaneLabel({ level }: { level: SurfaceLevel }) {
+  return <Text style={{ color: useOnSurfaceColor('primary') }}>level=&quot;{level}&quot;</Text>
 }
 
 // The named-plane model: flat, full-bleed grey planes straight from the
@@ -96,7 +150,7 @@ export const NamedPlanes: Story = {
     <View style={{ gap: 12, padding: 24 }}>
       {(['background', 'base', 'elevated', 'raised', 'overlay'] as SurfaceLevel[]).map((level) => (
         <Surface key={level} level={level} style={{ padding: 16 }}>
-          <Text style={{ color: '#fff' }}>level=&quot;{level}&quot;</Text>
+          <NamedPlaneLabel level={level} />
         </Surface>
       ))}
     </View>
@@ -187,12 +241,17 @@ export const OnSurfaceText: Story = {
   ),
 }
 
+/** On-surface elevation label for the forced-light demo below. */
+function LightElevationLabel({ level }: { level: ElevationLevel }) {
+  return <Text style={{ color: useOnSurfaceColor('primary') }}>Light Elevation {level}</Text>
+}
+
 export const LightTheme: Story = {
   render: () => (
-    <View style={{ gap: 16, padding: 24, backgroundColor: '#F3F4F6' }}>
+    <View style={{ gap: 16, padding: 24, backgroundColor: semanticColorsLight['background-base'] }}>
       {([0, 1, 2, 3, 4, 5] as ElevationLevel[]).map((level) => (
         <Surface key={level} elevation={level} theme="light" style={{ padding: 16 }}>
-          <Text style={{ color: '#111' }}>Light Elevation {level}</Text>
+          <LightElevationLabel level={level} />
         </Surface>
       ))}
     </View>

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

@@ -12,8 +12,21 @@ import {
   useSurfaceMode,
 } from './SurfaceContext'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { greyRamp, primitiveColors } from '../../../theme/tokens/primitives'
 import { getPressedRecessShadow } from '../../../theme/elevation'
 
+// Planes by RAMP STEP, never by literal bytes: a re-space of the grey ramp
+// should move these expectations with it, not break them. Which step backs
+// which plane is still asserted — that mapping is the behaviour.
+const FRAME = greyRamp[975]
+const BACKGROUND = greyRamp[950]
+const BASE = greyRamp[925]
+const ELEVATED = greyRamp[900]
+const RAISED = greyRamp[875]
+const OVERLAY = greyRamp[850]
+const LIGHT_BASE = primitiveColors.white
+const LIGHT_TEXT_PRIMARY = getSemanticColors('light')['text-primary']
+
 // A descendant probe that renders the on-surface colour + mode it resolves from
 // context, so tests can assert what a nested consumer would actually paint.
 function Probe({ role = 'primary' as const, label = 'probe' }) {
@@ -72,11 +85,56 @@ describe('Surface (card model)', () => {
     expect(screen.getByTestId('my-surface')).toBeInTheDocument()
   })
 
-  it('paints the default flat dark card surface', () => {
+  it('sits flat on the inherited plane by default (dark base, no treatment)', () => {
     render(<Surface testID="s" />)
-    // elevation 0 → base surface (surface-elevated) with no lightening.
-    // TD-surface-tokens S-3 re-space: was #2A2827.
-    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#2C2A28' })
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: BASE })
+    expect(el.style.boxShadow).toBe('')
+  })
+
+  it('lifts onto ramp planes with rim + shadow: elevation 2 from the page is the card plane', () => {
+    render(<Surface elevation={2} testID="s" />)
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: RAISED })
+    expect(el.style.boxShadow).toContain('inset 0 1px 0')
+    expect(el.style.boxShadow).toMatch(/, 0 \d+px \d+px rgba\(0,0,0/)
+  })
+
+  it('raise is relative: one step up from an elevated host lands on raised', () => {
+    render(
+      <Surface level="elevated">
+        <Surface raise={1} testID="s" />
+      </Surface>
+    )
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: RAISED })
+  })
+
+  it('clamps at overlay so raised-on-raised cannot leave the ramp', () => {
+    render(
+      <Surface level="overlay">
+        <Surface raise={2} testID="s" />
+      </Surface>
+    )
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: OVERLAY })
+  })
+
+  it('floats on the overlay plane with a larger shadow and no ring', () => {
+    render(<Surface elevation={4} testID="s" />)
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: OVERLAY })
+    expect(el.style.boxShadow.split(', ').length).toBe(4)
+    expect(el.style.borderWidth).toBe('')
+  })
+
+  it('lets a caller switch the lift off on a raised plane, or on for a named one', () => {
+    render(
+      <>
+        <Surface raise={1} lift={false} testID="flat" />
+        <Surface level="raised" lift testID="lifted" />
+      </>
+    )
+    expect(screen.getByTestId('flat').style.boxShadow).toBe('')
+    expect(screen.getByTestId('lifted').style.boxShadow).toContain('inset 0 1px 0')
   })
 
   describe('accessibility', () => {
@@ -94,10 +152,10 @@ describe('Surface (card model)', () => {
 
 describe('Surface (named plane)', () => {
   it.each([
-    ['background', '#1C1916'],
-    ['base', '#252321'],
-    ['elevated', '#2C2A28'],
-    ['raised', '#31302F'],
+    ['background', BACKGROUND],
+    ['base', BASE],
+    ['elevated', ELEVATED],
+    ['raised', RAISED],
   ] as const)('maps level %s to the surface-ramp token %s', (level, hex) => {
     render(<Surface level={level} testID="s" />)
     expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: hex })
@@ -105,7 +163,7 @@ describe('Surface (named plane)', () => {
 
   it('resolves the light-mode background when theme is overridden', () => {
     render(<Surface level="base" theme="light" testID="s" />)
-    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#FFFFFF' })
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: LIGHT_BASE })
   })
 
   it('lets a caller style override the owned background', () => {
@@ -134,12 +192,12 @@ function lstar(hex: string): number {
 
 describe('Surface (pressed well)', () => {
   it.each([
-    // TD-surface-tokens S-3 re-space: top steps widened (elevated #2C2A28,
-    // raised #31302F, overlay #373635); base/background unchanged.
-    ['overlay', '#373635', '#31302F'], // → raised
-    ['raised', '#31302F', '#2C2A28'], // → elevated
-    ['elevated', '#2C2A28', '#252321'], // → base
-    ['base', '#252321', '#1C1916'], // → background
+    // TD-surface-tokens S-3 re-space widened the top steps; base and
+    // background were unchanged. The pairs below are ramp-adjacent by index.
+    ['overlay', OVERLAY, RAISED], // → raised
+    ['raised', RAISED, ELEVATED], // → elevated
+    ['elevated', ELEVATED, BASE], // → base
+    ['base', BASE, BACKGROUND], // → background
   ] as const)(
     'in a %s parent renders one ramp step down (%s → %s), darker than its parent',
     (parent, parentHex, pressedHex) => {
@@ -155,7 +213,7 @@ describe('Surface (pressed well)', () => {
 
   it('with no enclosing Surface (default base) presses to the background plane', () => {
     render(<Surface pressed testID="well" />)
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: BACKGROUND })
   })
 
   it('clamps at the frame floor: pressed directly in background does not underflow', () => {
@@ -164,8 +222,8 @@ describe('Surface (pressed well)', () => {
         <Surface pressed testID="well" />
       </Surface>
     )
-    // background (#1C1916) steps down to the frame floor (#100D0A), the bezel.
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#100D0A' })
+    // background steps down to the frame floor, the bezel.
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: FRAME })
   })
 
   it('does not step below the floor: pressed within a floor-pressed well stays at frame', () => {
@@ -176,7 +234,7 @@ describe('Surface (pressed well)', () => {
         </Surface>
       </Surface>
     )
-    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: '#100D0A' })
+    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: FRAME })
   })
 
   it('publishes the stepped-down level to descendants so a nested press steps again', () => {
@@ -209,8 +267,8 @@ describe('Surface (pressed well)', () => {
         <Surface pressed testID="well" style={{ boxShadow: undefined }} />
       </Surface>
     )
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
-    expect(lstar('#1C1916')).toBeLessThan(lstar('#252321'))
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: BACKGROUND })
+    expect(lstar(BACKGROUND)).toBeLessThan(lstar(BASE))
   })
 
   it('rounds the well by default and honours an explicit rounded override', () => {
@@ -240,7 +298,7 @@ describe('pressedLevel helper', () => {
 
 describe('getPressedRecessShadow', () => {
   it('returns an inset recess tuned to the fill colour on the web path', () => {
-    const style = getPressedRecessShadow('#1C1916', 'dark') as { boxShadow?: string }
+    const style = getPressedRecessShadow(BACKGROUND, 'dark') as { boxShadow?: string }
     expect(style.boxShadow).toContain('inset')
   })
 })
@@ -262,7 +320,9 @@ describe('Surface on-surface colour context', () => {
 
   it('resolves dark on-surface colours even with no enclosing Surface', () => {
     render(<Probe role="primary" label="p" />)
-    expect(screen.getByTestId('p')).toHaveStyle({ color: getSemanticColors('dark')['text-primary'] })
+    expect(screen.getByTestId('p')).toHaveStyle({
+      color: getSemanticColors('dark')['text-primary'],
+    })
   })
 
   it('flows an overridden theme to descendant text', () => {
@@ -271,7 +331,7 @@ describe('Surface on-surface colour context', () => {
         <Probe role="primary" label="p" />
       </Surface>
     )
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+    expect(screen.getByTestId('p')).toHaveStyle({ color: LIGHT_TEXT_PRIMARY })
     expect(screen.getByTestId('p')).toHaveTextContent('light')
   })
 
@@ -283,15 +343,15 @@ describe('Surface on-surface colour context', () => {
         </Surface>
       </Surface>
     )
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+    expect(screen.getByTestId('p')).toHaveStyle({ color: LIGHT_TEXT_PRIMARY })
   })
 })
 
 describe('surface colour helpers', () => {
   it('surfaceBackground returns literal hex per level + mode', () => {
-    expect(surfaceBackground('elevated', 'dark')).toBe('#2C2A28')
-    expect(surfaceBackground('background', 'dark')).toBe('#1C1916')
-    expect(surfaceBackground('base', 'light')).toBe('#FFFFFF')
+    expect(surfaceBackground('elevated', 'dark')).toBe(ELEVATED)
+    expect(surfaceBackground('background', 'dark')).toBe(BACKGROUND)
+    expect(surfaceBackground('base', 'light')).toBe(LIGHT_BASE)
   })
 
   it('resolves the frame floor from its own semantic token', () => {