@titan-design/react-ui 0.11.0 → 0.12.1

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)

package/src/components/ui/surface/SurfaceContext.ts

@@ -7,7 +7,6 @@
 // (no global.css, no nativewind) — the bug class this primitive retires.
 import { createContext, useContext } from 'react'
 import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
-import { surfaceRampDark } from '../../../theme/tokens/primitives'
 
 type ColorToken = keyof ReturnType<typeof getSemanticColors>
 
@@ -18,32 +17,35 @@ type ColorToken = keyof ReturnType<typeof getSemanticColors>
  * no new hexes. Darkest → lightest:
  *   inset (#13100D) < background (#1C1916) < base (#252321) < elevated (#2A2827) < raised (#2D2C2B) < overlay (#302F2E)
  *
- * `inset` is the ramp's deepest pit — the sub-shell well. It's the floor a
- * `<Surface pressed>` clamps at (see {@link pressedLevel}); it has no shipped
- * semantic token yet, so {@link surfaceBackground} resolves it from the
- * `surface-inset` token when present, else the `surfaceRampDark.inset` primitive.
+ * `frame` is the bezel the ramp sits inside — the top bar / side nav chrome —
+ * and the floor a `<Surface pressed>` clamps at (see {@link pressedLevel}).
+ *
+ * It replaced a separate `inset` level in TD-07.14. That level was RETIRED, not
+ * renamed: at ΔE 1.10 from the frame it was an imperceptible duplicate, which is
+ * exactly why pressed (surface − 1) kept collapsing into it.
  */
-export type SurfaceLevel = 'inset' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+export type SurfaceLevel = 'frame' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
 
 /** On-surface neutral text roles, resolved for the current surface + theme. */
 export type OnSurfaceRole = 'primary' | 'secondary' | 'tertiary'
 
-// Which semantic token backs each ADDRESSABLE level. Values live in `semantic.ts`
-// and stay in sync with the charcoal ramp — this map never carries literal hexes.
-// `inset` is intentionally absent: it has no shipped semantic token yet, so it's
-// resolved separately (token-or-primitive) in `surfaceBackground`.
+// Which semantic token backs each level. Values live in `semantic.ts` and stay
+// in sync with the grey ramp — this map never carries literal hexes. Every level
+// is present now: swapping `inset` (which had no token) for `frame` (which does)
+// is what made this a total map and removed `surfaceBackground`'s special case.
 export const SURFACE_LEVEL_TOKEN = {
+  frame: 'background-frame',
   background: 'background-base',
   base: 'surface-base',
   elevated: 'surface-elevated',
   raised: 'surface-raised',
   overlay: 'surface-overlay',
-} as const satisfies Record<Exclude<SurfaceLevel, 'inset'>, ColorToken>
+} as const satisfies Record<SurfaceLevel, ColorToken>
 
-// Darkest → lightest, INCLUDING the inset floor. A `<Surface pressed>` renders
-// one index DOWN from its parent's level and clamps at `inset` (index 0). Kept
-// in lockstep with the derived ramp and the surface.contract.test PLANE_ORDER.
-const PRESSED_RAMP = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
+// Darkest → lightest. A `<Surface pressed>` renders one index DOWN from its
+// parent's level and clamps at `frame` (index 0). Kept in lockstep with the grey
+// ramp and the surface.contract.test PLANE_ORDER.
+const PRESSED_RAMP = ['frame', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
 
 const ON_SURFACE_TOKEN = {
   primary: 'text-primary',
@@ -94,29 +96,17 @@ export function useOnSurfaceColor(role: OnSurfaceRole = 'primary'): string {
   return getSemanticColors(useSurfaceMode())[ON_SURFACE_TOKEN[role]]
 }
 
-/**
- * The inset floor hex — the ramp's deepest pit that a pressed surface clamps at.
- * Prefers the `surface-inset` semantic token (theme-aware; being promoted in a
- * parallel token change) and falls back to the `surfaceRampDark.inset` primitive
- * (#13100D, dark-ramp only) until that token ships.
- */
-function insetFloor(mode: ThemeMode): string {
-  const colors = getSemanticColors(mode) as Record<string, string>
-  return colors['surface-inset'] ?? surfaceRampDark.inset
-}
-
 /** The background hex for a surface level under a theme mode (literal hex). */
 export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
-  if (level === 'inset') return insetFloor(mode)
   return getSemanticColors(mode)[SURFACE_LEVEL_TOKEN[level]]
 }
 
 /**
  * The level a `<Surface pressed>` resolves to: its parent's level stepped one
  * index DOWN the ramp — the symmetric twin of a raised surface stepping up —
- * clamped at the `inset` floor so a pressed surface never underflows the pit.
+ * clamped at the `frame` floor so a pressed surface never underflows the bezel.
  *   overlay→raised, raised→elevated, elevated→base, base→background,
- *   background→inset, inset→inset (clamped).
+ *   background→frame, frame→frame (clamped).
  * Pressed exposes ONE level of depth only (no pressed-2).
  */
 export function pressedLevel(parent: SurfaceLevel): SurfaceLevel {

package/src/components/ui/surface/surface.contract.test.ts

@@ -8,7 +8,7 @@ import { getSemanticColors } from '../../../theme/tokens/semantic'
  * palette locks its eligibility mask with a value-level test.
  *
  * Scope: DARK mode only. The north-star diagnosis
- * (coordination/design-explorations/surface-system-north-star.md) measured and
+ * (sources/design/surface-system-north-star.md) measured and
  * fixed the dark ramp specifically; light mode has its own latent collisions
  * (e.g. `surface-overlay` === `surface-base`, both `#FFFFFF`) that were never
  * part of this investigation — flagged as a follow-up, not silently patched
@@ -20,7 +20,7 @@ import { getSemanticColors } from '../../../theme/tokens/semantic'
  * derived, not hand-picked") deliberately supersedes that with DIMINISHING
  * steps — the frame->content jump is biggest, each plane above adds less.
  * As of S-3 (this re-space) the steps are 4.5 / 4.5 / 3.5 / 3 / 2.5
- * (inset->background / background->base / base->elevated / elevated->raised /
+ * (frame->background / background->base / base->elevated / elevated->raised /
  * raised->overlay) — the top three widened from the original 2.5/2/1.5 taper
  * so the content planes read as distinct without leaning on the hairline
  * alone (R3 still carries the rest, per "lightness is a *secondary* cue").
@@ -73,10 +73,10 @@ function compositeOver(baseHex: string, overlay: string): string {
 
 const dark = getSemanticColors('dark')
 
-// The 6-plane derivation, in darkest -> lightest order. `inset` is now a real
-// shipped token (`surface-inset`, promoted at S-3 — see semantic.ts comment).
+// The 6-plane derivation, in darkest -> lightest order. The floor is `frame`;
+// the old `inset` plane was retired in TD-07.14 for being ΔE 1.10 from it.
 const RAMP_HEX = {
-  inset: dark['surface-inset'],
+  frame: dark['background-frame'],
   background: dark['background-base'],
   base: dark['surface-base'],
   elevated: dark['surface-elevated'],
@@ -84,14 +84,14 @@ const RAMP_HEX = {
   overlay: dark['surface-overlay'],
 } as const
 
-const PLANE_ORDER = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
+const PLANE_ORDER = ['frame', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
 
 describe('surface ramp contract (dark) — token-value guardrails', () => {
   it('ships the deriveSurfaceRamp() output verbatim for the addressable planes', () => {
     // Locked values from surface-system-north-star.md (re-spaced S-3) — see
     // surfaceRampDark in primitives.ts for the derivation this must match
-    // byte-for-byte. background/base/inset are unchanged by the re-space.
-    expect(dark['surface-inset']).toBe('#13100D')
+    // byte-for-byte. background/base are unchanged by the re-space.
+    expect(dark['background-frame']).toBe('#100D0A')
     expect(dark['background-base']).toBe('#1C1916')
     expect(dark['surface-base']).toBe('#252321')
     expect(dark['surface-elevated']).toBe('#2C2A28')
@@ -110,8 +110,8 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
       }
     })
 
-    it('clears ΔL* >= 4 at the two foundational steps (inset->background, background->base)', () => {
-      const dL_insetToBackground = lstar(RAMP_HEX.background) - lstar(RAMP_HEX.inset)
+    it('clears ΔL* >= 4 at the two foundational steps (frame->background, background->base)', () => {
+      const dL_insetToBackground = lstar(RAMP_HEX.background) - lstar(RAMP_HEX.frame)
       const dL_backgroundToBase = lstar(RAMP_HEX.base) - lstar(RAMP_HEX.background)
       expect(dL_insetToBackground).toBeGreaterThanOrEqual(4)
       expect(dL_backgroundToBase).toBeGreaterThanOrEqual(4)
@@ -158,14 +158,10 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
         dark['surface-raised'],
         dark['surface-overlay'],
         dark['surface-input'],
-        dark['surface-inset'],
       ])
-      const solidBorders = [
-        'border-default',
-        'border-subtle',
-        'border-strong',
-        'border-prominent',
-      ] as const
+      // `border-prominent` is the only solid border left; the quiet three are
+      // alpha hairlines now and cannot equal a fill.
+      const solidBorders = ['border-prominent'] as const
       for (const token of solidBorders) {
         expect(
           surfaceHexes.has(dark[token]),
@@ -185,10 +181,17 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
     // the S-3 ramp (default dropped 8->7 — the `overlay` plane now measures
     // ~7.97, just under the old floor); a wall-display calibration pass (S-6)
     // may retune the alpha values themselves.
+    //
+    // S-6 DID (VW-99). The alphas went up ×1.5 to .09/.135/.21: on the wall at
+    // ~3 m `subtle` rendered but was indiscernible, and `default` — which has had
+    // no solid-border fallback since TD-07.14 — went weak on the lightest plane.
+    // Floors below re-measured against the new alphas. Note new `subtle` now
+    // measures exactly where old `default` did (min 7.97), and the new `default`
+    // where old `strong` did (min 12.26) — each tier onto a measured-good rung.
     const HAIRLINES = {
-      subtle: { token: 'hairline-subtle', floor: 5 },
-      default: { token: 'hairline-default', floor: 7 },
-      strong: { token: 'hairline-strong', floor: 12 },
+      subtle: { token: 'hairline-subtle', floor: 7 },
+      default: { token: 'hairline-default', floor: 12 },
+      strong: { token: 'hairline-strong', floor: 18 },
     } as const
 
     for (const [name, { token, floor }] of Object.entries(HAIRLINES)) {
@@ -203,30 +206,40 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
       })
     }
 
-    it('is near-constant (self-normalizing) across all planes: spread < 4 L* per tier', () => {
-      // Measured spread (inset..overlay): subtle ~1.6, default ~2.2, strong ~3.2 —
-      // still far tighter than a solid border token (which swings ~5.6 -> 0
-      // across this same ramp, see R4). "Near-constant" is relative to that,
-      // not perfectly flat — alpha-over-white is sublinear in L* as the base
-      // lightens, which is exactly the R3 floor-vs-doc discrepancy noted above.
+    it('is near-constant (self-normalizing) across all planes: spread stays proportional', () => {
+      // Measured RELATIVE spread ((max-min)/min): subtle 0.27, default 0.29,
+      // strong 0.29 — and, importantly, those are the same figures the OLD
+      // .06/.09/.14 family produced (0.28 / 0.27 / 0.28). Self-normalization
+      // survived the S-6 retune untouched.
+      //
+      // This assertion used to be an ABSOLUTE `spread < 4 L*`, which was the
+      // wrong metric: absolute spread scales with the alpha, so ANY strengthening
+      // fails it no matter how well the property holds. The S-6 ×1.5 retune
+      // tripped it (strong 3.46 -> 5.29) purely arithmetically. A ratio is
+      // scale-invariant, which is what "self-normalizing" actually claims.
+      //
+      // Contrast a solid border token, which swings ~5.6 -> 0 across this same
+      // ramp (see R4): the point is not a tight absolute band, it is that no
+      // plane ever loses the cue. Alpha-over-white is sublinear in L* as the
+      // base lightens, which is the R3 floor-vs-doc discrepancy noted above.
       for (const { token } of Object.values(HAIRLINES)) {
         const hairlineColor = dark[token as keyof typeof dark]
         const deltas = PLANE_ORDER.map((plane) => {
           const planeHex = RAMP_HEX[plane]
           return lstar(compositeOver(planeHex, hairlineColor)) - lstar(planeHex)
         })
-        expect(Math.max(...deltas) - Math.min(...deltas)).toBeLessThan(4)
+        const min = Math.min(...deltas)
+        expect((Math.max(...deltas) - min) / min, `${token} relative spread`).toBeLessThan(0.35)
       }
     })
   })
 
-  describe('R4 — border-on-surface clears ΔL* >= 3 (fixes the invisible-hairline collision)', () => {
-    it('border-subtle is no longer invisible on surface-raised (the original bug)', () => {
-      const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark['surface-raised']))
-      expect(dL).toBeGreaterThanOrEqual(3)
-    })
-
-    it('border-subtle clears ΔL* >= 3 against base/elevated/raised/overlay', () => {
+  // R4 used to check that the solid `border-subtle` hex did not match the plane
+  // it sat on. Those solid borders are gone (TD-07.14) — separation is R3's
+  // alpha hairlines, which cannot collide with a plane by construction. What is
+  // left to guard is the one border still solid.
+  describe('R4 — border-prominent, the last solid border', () => {
+    it('clears ΔL* >= 3 on every content plane', () => {
       const planes = [
         'surface-base',
         'surface-elevated',
@@ -234,13 +247,13 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
         'surface-overlay',
       ] as const
       for (const plane of planes) {
-        const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark[plane]))
-        expect(dL, `border-subtle vs ${plane}`).toBeGreaterThanOrEqual(3)
+        const dL = Math.abs(lstar(dark['border-prominent']) - lstar(dark[plane]))
+        expect(dL, `border-prominent vs ${plane}`).toBeGreaterThanOrEqual(3)
       }
     })
   })
 
-  describe('R5 — background-frame and surface-inset (S-3 new tokens)', () => {
+  describe('R5 — background-frame, the ramp floor', () => {
     it('background-frame is darker than background-base', () => {
       expect(lstar(dark['background-frame'])).toBeLessThan(lstar(dark['background-base']))
     })
@@ -255,14 +268,18 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
         'surface-raised',
         'surface-overlay',
         'surface-input',
-        'surface-inset',
       ] as const
       for (const token of otherTokens) {
         expect(dark['background-frame'], `background-frame vs ${token}`).not.toBe(dark[token])
       }
     })
 
-    it('surface-inset is the darkest surface-family token', () => {
+    // `surface-inset` used to sit between frame and background as the darkest
+    // surface-family token. TD-07.14 retired it: at delta-E 1.10 from the frame
+    // it was an imperceptible duplicate, which is why `<Surface pressed>`
+    // (surface - 1) kept collapsing into it. `frame` is the floor now, so the
+    // rule that matters is that nothing in the surface family goes below it.
+    it('background-frame is darker than every surface-family token', () => {
       const surfaceFamily = [
         'surface-base',
         'surface-elevated',
@@ -270,14 +287,10 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
         'surface-overlay',
         'surface-input',
       ] as const
-      const insetL = lstar(dark['surface-inset'])
+      const frameL = lstar(dark['background-frame'])
       for (const token of surfaceFamily) {
-        expect(insetL, `surface-inset vs ${token}`).toBeLessThan(lstar(dark[token]))
+        expect(frameL, `background-frame vs ${token}`).toBeLessThan(lstar(dark[token]))
       }
     })
-
-    it('surface-inset is distinct from background-frame', () => {
-      expect(dark['surface-inset']).not.toBe(dark['background-frame'])
-    })
   })
 })

package/src/components/ui/switch/Switch.tsx

@@ -63,7 +63,7 @@ export const Switch = forwardRef<View, SwitchProps>(function Switch(
       className={cn(
         'rounded-full p-0.5 transition-colors',
         styles.track,
-        isChecked ? 'bg-brand-primary' : 'bg-border-strong'
+        isChecked ? 'bg-brand-primary' : 'bg-hairline-strong'
       )}
     >
       <View

package/src/components/ui/tabs/Tabs.tsx

@@ -100,8 +100,8 @@ export function TabList({ children, className }: TabListProps) {
 
   const variantStyles = {
     line: orientation === 'horizontal'
-      ? 'border-b border-border'
-      : 'border-r border-border',
+      ? 'border-b border-hairline'
+      : 'border-r border-hairline',
     enclosed: 'bg-surface-raised rounded-lg p-1',
     'soft-rounded': 'bg-surface-raised rounded-full p-1',
   }

package/src/components/ui/toolbar-button/ToolbarButton.stories.tsx

@@ -10,7 +10,7 @@ const meta: Meta<typeof ToolbarButton> = {
   argTypes: {
     variant: {
       control: 'select',
-      options: ['default', 'neumorphic'],
+      options: ['default', 'raised'],
     },
     isActive: {
       control: 'select',
@@ -60,7 +60,7 @@ export const Default: Story = {
   args: {
     label: 'Settings',
     icon: <SettingsIcon />,
-    variant: 'neumorphic',
+    variant: 'raised',
     showLabel: true,
   },
 }
@@ -319,7 +319,7 @@ export const CompactMode: Story = {
             onPress={() => setIsCompact(!isCompact)}
           />
         </View>
-        <View className="h-px bg-border" />
+        <View className="h-px bg-hairline" />
         <ToolbarButtonGroup gap="sm">
           <ToolbarButton
             label="Filter"
@@ -351,8 +351,8 @@ export const Variants: Story = {
       <View>
         <Text className="text-text-secondary text-xs mb-2">Neumorphic (with 3D inset shadows)</Text>
         <View style={{ flexDirection: 'row', gap: 8 }}>
-          <ToolbarButton label="Inactive" icon={<SettingsIcon />} variant="neumorphic" isActive={false} />
-          <ToolbarButton label="Active" icon={<SettingsIcon />} variant="neumorphic" isActive={true} />
+          <ToolbarButton label="Inactive" icon={<SettingsIcon />} variant="raised" isActive={false} />
+          <ToolbarButton label="Active" icon={<SettingsIcon />} variant="raised" isActive={true} />
         </View>
       </View>
       <View>

package/src/components/ui/toolbar-button/ToolbarButton.test.tsx

@@ -96,7 +96,7 @@ describe('ToolbarButton', () => {
 
   describe('variants', () => {
     it('renders with neumorphic variant (default)', () => {
-      render(<ToolbarButton label="Neumorphic" variant="neumorphic" />)
+      render(<ToolbarButton label="Neumorphic" variant="raised" />)
       expect(screen.getByRole('button', { name: 'Neumorphic' })).toBeInTheDocument()
     })
 

package/src/components/ui/toolbar-button/ToolbarButton.tsx

@@ -1,10 +1,12 @@
 import React, { useState, useCallback, createContext, useContext } from 'react'
 import { View, Text, Pressable, type ViewProps, StyleSheet, Platform } from 'react-native'
 import { cn } from '../../../utils/cn'
-import { neumorphicShadows, getHoverColors } from '../../../theme'
+import { getHoverColors } from '../../../theme'
+import { greyRamp } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 import { resolveColor } from '../../../theme/resolve-color'
 
-export type ToolbarButtonVariant = 'default' | 'neumorphic'
+export type ToolbarButtonVariant = 'default' | 'raised'
 export type ToolbarButtonSize = 'sm' | 'md' | 'lg'
 
 interface ToolbarButtonContextType {
@@ -47,9 +49,19 @@ export interface ToolbarButtonProps extends ViewProps {
   className?: string
 }
 
-// Base button color
-const BUTTON_BG = '#3C3C3C'
-const MENU_BG = '#2C2C2C'
+const SEMANTIC = getSemanticColors('dark')
+
+// Base button colours. These were raw `#3C3C3C`/`#2C2C2C` literals — old cold
+// charcoal steps that survived the grey migration only because they were plain
+// strings rather than scale references.
+const BUTTON_BG = greyRamp[800]
+const MENU_BG = greyRamp[900]
+
+// Inline depth is a HAIRLINE, not a shadow (TD-07.16). On a ~10% lightness
+// surface a dual-opposing neumorphic shadow has no room below to read; alpha
+// composites by the same amount over any plane, so the edge holds everywhere.
+const EDGE = { borderWidth: 1, borderColor: SEMANTIC['hairline-default'] } as const
+const EDGE_PRESSED = { borderWidth: 1, borderColor: SEMANTIC['hairline-strong'] } as const
 
 // Calculate hover colors using color math
 const hoverColors = getHoverColors(BUTTON_BG, 'medium')
@@ -100,7 +112,7 @@ export function ToolbarButton({
   isActive,
   isDisabled = false,
   size = 'md',
-  variant = 'neumorphic',
+  variant = 'raised',
   tooltip,
   showLabel = true,
   onPress,
@@ -135,26 +147,28 @@ export function ToolbarButton({
   }
 
   // Get shadow and background styles for neumorphic variant
-  const getNeumorphicStyle = () => {
+  /**
+   * Raised/pressed treatment. Depth comes from the FILL plus a hairline edge —
+   * pressed sits darker with a stronger edge, raised sits lighter with a quieter
+   * one. It used to come from a two-layer neumorphic shadow, which the surface
+   * exploration ruled out for inline hierarchy: it needs a mid-tone background
+   * for the dark half to have somewhere to fall, and these buttons sit at ~10%
+   * lightness.
+   */
+  const getRaisedStyle = () => {
     if (isDisabled) {
       return styles.disabledBg
     }
-    
-    const shadows = neumorphicShadows.charcoal
-    
     if (showActive) {
-      // Active = pressed/sunken appearance
       return {
-        backgroundColor: isHovered ? hoverColors.pressed : BUTTON_BG,
-        ...(isHovered ? shadows.pressedHover.subtle : shadows.pressed.subtle),
-      }
-    } else {
-      // Inactive = raised/elevated appearance
-      return {
-        backgroundColor: isHovered ? hoverColors.raised : BUTTON_BG,
-        ...(isHovered ? shadows.raisedHover.subtle : shadows.raised.subtle),
+        backgroundColor: isHovered ? hoverColors.pressed : greyRamp[900],
+        ...EDGE_PRESSED,
       }
     }
+    return {
+      backgroundColor: isHovered ? hoverColors.raised : BUTTON_BG,
+      ...EDGE,
+    }
   }
 
   return (
@@ -180,9 +194,9 @@ export function ToolbarButton({
             className
           )}
           style={[
-            variant === 'neumorphic' && getNeumorphicStyle(),
+            variant === 'raised' && getRaisedStyle(),
             variant === 'default' && {
-              backgroundColor: showActive ? BUTTON_BG : '#6E6E6E',
+              backgroundColor: showActive ? BUTTON_BG : greyRamp[600],
             },
           ]}
         >
@@ -232,7 +246,7 @@ export function ToolbarButton({
             <View
               className={cn(
                 'absolute z-50 top-full left-0 mt-1',
-                'rounded-lg shadow-lg border border-border',
+                'rounded-lg shadow-lg border border-hairline',
                 'min-w-[150px] overflow-hidden',
                 `bg-[${MENU_BG}]`
               )}