@titan-design/react-ui 0.12.1 → 0.13.0

package/src/theme/ColorPrimitives.stories.tsx

@@ -66,7 +66,9 @@ const PLANE_BY_STEP: Record<number, string> = Object.fromEntries(
 /** 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)
+const GREY_STEPS = Object.keys(greyRamp)
+  .map(Number)
+  .sort((a, b) => a - b)
 
 /**
  * The grey ramp, rendered as a numbered scale with its plane aliases.
@@ -92,7 +94,10 @@ function GreyRampRow() {
                 borderColor: ANCHOR_STEPS.has(step) ? '#FF7900' : SWATCH_BORDER,
               }}
             />
-            <Text className="text-text-primary" style={{ fontSize: 10, fontWeight: '600', marginTop: 3 }}>
+            <Text
+              className="text-text-primary"
+              style={{ fontSize: 10, fontWeight: '600', marginTop: 3 }}
+            >
               {step}
               {ANCHOR_STEPS.has(step) ? ' ★' : ''}
             </Text>
@@ -115,11 +120,10 @@ export const Ramps: StoryObj = {
     <View style={{ padding: 24 }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Ramps</Text>
       <SectionIntro>
-        Every raw colour value titan ships, as ordered scales. Nothing here carries meaning — a
-        ramp step becomes a border or a status only when a semantic token or a palette references
-        it, which is what{' '}
-        <Text className="font-semibold">Foundations/Color/Palettes</Text> documents. Everything on
-        this page is current and safe to pick.
+        Every raw colour value titan ships, as ordered scales. Nothing here carries meaning — a ramp
+        step becomes a border or a status only when a semantic token or a palette references it,
+        which is what <Text className="font-semibold">Foundations/Color/Palettes</Text> documents.
+        Everything on this page is current and safe to pick.
       </SectionIntro>
 
       <Text className="text-text-tertiary text-xs mb-6">
@@ -127,21 +131,20 @@ export const Ramps: StoryObj = {
         <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/.
+        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>
       <Text className="text-text-secondary text-xs mb-4">
-        Seven OKLCH-generated hue ramps, 11 perceptual steps each (50 → 950), built with
-        hue-torsion and a chroma arc anchored through the brand/semantic hexes. These are the
-        source of truth for chromatic hexes: the categorical, diverging, effort and fatigue
-        palettes are all references into these steps rather than duplicated values, so re-tuning a
-        ramp moves them together. Amber absorbs the former yellow (lemon → warm body) and cyan
-        absorbs the former steel.
+        Seven OKLCH-generated hue ramps, 11 perceptual steps each (50 → 950), built with hue-torsion
+        and a chroma arc anchored through the brand/semantic hexes. These are the source of truth
+        for chromatic hexes: the categorical, diverging, effort and fatigue palettes are all
+        references into these steps rather than duplicated values, so re-tuning a ramp moves them
+        together. Amber absorbs the former yellow (lemon → warm body) and cyan absorbs the former
+        steel.
       </Text>
       {CHROMATIC_RAMPS.map(([key, name]) => (
         <ScaleRow key={key} name={name} scale={primitiveRamps[key]} />
@@ -157,16 +160,15 @@ export const Ramps: StoryObj = {
         set of names.
       </Text>
       <Text className="text-text-secondary text-xs mb-4">
-        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.
+        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">
@@ -258,8 +260,8 @@ export const Accessibility: StoryObj = {
       <SectionIntro>
         How the raw material behaves for viewers who cannot separate the hues, and under text.
         Dichromacy is simulated with the Machado-2009 matrices at severity 1.0. Converging strips
-        across two swatches mean those two are the same colour to that viewer — which is a
-        problem only where hue is carrying the meaning on its own.
+        across two swatches mean those two are the same colour to that viewer — which is a problem
+        only where hue is carrying the meaning on its own.
       </SectionIntro>
 
       <SectionTitle>Ramp mid-steps (500)</SectionTitle>
@@ -269,9 +271,7 @@ export const Accessibility: StoryObj = {
         below fans its picks across lightness instead of taking all seven at 500, and why the
         ordered scales in Palettes encode magnitude in lightness rather than hue.
       </Text>
-      <View
-        style={{ flexDirection: 'row', gap: 6, marginBottom: 6, paddingLeft: CVD_LABEL_WIDTH }}
-      >
+      <View style={{ flexDirection: 'row', gap: 6, marginBottom: 6, paddingLeft: CVD_LABEL_WIDTH }}>
         {RAMP_MIDS.map(({ name, hex }) => (
           <View key={name} style={{ alignItems: 'center' }}>
             <View
@@ -297,8 +297,8 @@ export const Accessibility: StoryObj = {
       <SectionTitle>Categorical series — in-place text contrast</SectionTitle>
       <Text className="text-text-secondary text-xs mb-3">
         The palette that has to survive this test in production. All pairs hold ΔE ≥ 8 through the
-        first {CATEGORICAL_CVD_SAFE_MAX}; the 7th is extended and wants a legend. The palette
-        itself is documented in Palettes — this is the validation of it.
+        first {CATEGORICAL_CVD_SAFE_MAX}; the 7th is extended and wants a legend. The palette itself
+        is documented in Palettes — this is the validation of it.
       </Text>
       {(['default', 'dark'] as const).map((variant) => {
         const colors = categoricalPalette[variant]

package/src/theme/Depth.stories.tsx

@@ -3,12 +3,13 @@ import { View, Text } from 'react-native'
 import { greyRamp } from './tokens/primitives'
 import { getSemanticColors } from './tokens/semantic'
 import {
+  ELEVATION_PLANE,
+  FLOATING_ELEVATION_MIN,
   getElevationSurface,
   getElevationShadow,
-  getBaseSurfaceColor,
-  FLOATING_ELEVATION_MIN,
   type ElevationLevel,
 } from './elevation'
+import { liftStyle, LIFT_RIM_ALPHA } from './lift'
 import { paperSheet, insetWell, barPaper } from './materials'
 import { SectionIntro, SectionTitle } from './color-story-kit'
 
@@ -17,15 +18,19 @@ const t = getSemanticColors('dark')
 /**
  * Foundations/Depth — how a surface says how far away it is.
  *
- * There are exactly three mechanisms, and which one applies is not a taste call:
+ * Four mechanisms, and which one applies is not a taste call:
  *
- *   TONE      how deep a plane sits          — the grey ramp
- *   HAIRLINE  where one plane ends           — alpha, self-normalising
- *   MATERIAL  what a plane is made of        — paper, well
+ *   TONE      which plane a surface sits on       — the grey ramp
+ *   LIFT      that it rests ON the plane below    — rim-light + ambient shadow
+ *   HAIRLINE  where one plane ends                — alpha, self-normalising
+ *   MATERIAL  what a plane is made of             — paper, well
  *
- * Drop-shadow is deliberately not on that list for anything inline. This page
- * exists because the system previously had a fourth mechanism — a neumorphic
- * dual-opposing shadow — that could not work here and was removed in TD-07.16.
+ * Tone and lift travel together: every lifted plane wears both. This page
+ * previously taught that levels 0–3 separate by tone alone and that drop-shadow
+ * belongs to floating overlays only (TD-07.16). That was reversed on 2026-09-08:
+ * the upper ramp steps are ΔL* 2.5–3 apart, too tight for tone to carry the
+ * separation on its own, and a soft ambient shadow is not inert on a dark plane
+ * once a rim-light gives the edge something to fall from.
  */
 const meta: Meta = {
   title: 'Foundations/Depth',
@@ -35,7 +40,6 @@ export default meta
 
 const CONTENT_LEVELS: ElevationLevel[] = [0, 1, 2, 3]
 const FLOATING_LEVELS: ElevationLevel[] = [4, 5]
-const base = getBaseSurfaceColor('dark')
 
 function Swatch({
   label,
@@ -69,21 +73,21 @@ function Swatch({
 }
 
 export const Mechanisms: StoryObj = {
-  name: '1. The three mechanisms',
+  name: '1. The four mechanisms',
   render: () => (
-    <View style={{ padding: 24, backgroundColor: greyRamp[975] }}>
+    <View style={{ padding: 24, backgroundColor: greyRamp[925] }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Depth</Text>
       <SectionIntro>
-        Three mechanisms, in the order you should reach for them. A surface that needs to read as
-        deeper takes a TONE; one that needs an edge takes a HAIRLINE; one that needs to feel
-        physical takes a MATERIAL. Drop-shadow is not on the list for anything that is not
-        floating — see section 3 for why.
+        Four mechanisms, in the order you should reach for them. A surface that sits higher takes a
+        TONE and, with it, a LIFT; one that only needs an edge takes a HAIRLINE; one that needs to
+        feel physical takes a MATERIAL. Tone is the only cue that works identically on web and
+        native, so it is never optional; the others sit on top of it.
       </SectionIntro>
 
       <SectionTitle>Tone — the grey ramp</SectionTitle>
       <Text className="text-text-secondary text-xs mb-3">
-        The primary cue and the only one that works identically on web and native. Every plane is
-        a ramp step.
+        Every plane is a ramp step. Nothing derives a colour between two steps: the elevation levels
+        in section 2 index this list, they do not lighten a base.
       </Text>
       <View style={{ flexDirection: 'row', gap: 10, marginBottom: 22 }}>
         {[975, 950, 925, 900, 875, 850].map((step) => (
@@ -96,12 +100,43 @@ export const Mechanisms: StoryObj = {
         ))}
       </View>
 
+      <SectionTitle>Lift — resting on the plane below</SectionTitle>
+      <Text className="text-text-secondary text-xs mb-3">
+        A crisp 1px top rim-light at {LIFT_RIM_ALPHA.dark} (one grade under paperSheet&apos;s 0.20
+        hero rim, chosen side by side in Lab/Depth) plus a soft ambient shadow that grows with the
+        planes crossed. Both are lit from above. This is what separates a card from the page when
+        the tone step alone is ΔL* 3. It is not a hairline ring: a ring is an edge, and stays the
+        divider&apos;s job.
+      </Text>
+      <View style={{ flexDirection: 'row', gap: 10, marginBottom: 22 }}>
+        <Swatch
+          label="tone only"
+          note="grey-875 on grey-925: the step is there, but the card is not resting on anything."
+          style={{ backgroundColor: greyRamp[875] }}
+        />
+        <Swatch
+          label="tone + rim"
+          note="the rim gives the top edge a lit lip."
+          style={{
+            backgroundColor: greyRamp[875],
+            boxShadow: `inset 0 1px 0 rgba(255,255,255,${LIFT_RIM_ALPHA.dark})`,
+          }}
+        />
+        <Swatch
+          label="tone + rim + shadow"
+          note="the default for any lifted plane: liftStyle(2)."
+          style={{
+            backgroundColor: greyRamp[875],
+            ...(liftStyle(2, 'dark') as Record<string, unknown>),
+          }}
+        />
+      </View>
+
       <SectionTitle>Hairline — where a plane ends</SectionTitle>
       <Text className="text-text-secondary text-xs mb-3">
-        Alpha-white, so it composites toward white by the same amount on any background and holds
-        a near-constant ΔL* wherever it lands. A solid border swings wildly across the ramp; this
-        does not. It is the default separator, and it is what replaced the solid dark border
-        tokens.
+        Alpha-white, so it composites toward white by the same amount on any background and holds a
+        near-constant ΔL* wherever it lands. It is the divider, the table rule, and the opt-in edge
+        of an `outline` card. It is not the default edge of a lifted card.
       </Text>
       <View style={{ flexDirection: 'row', gap: 10, marginBottom: 22 }}>
         {(['hairline-subtle', 'hairline-default', 'hairline-strong'] as const).map((token) => (
@@ -120,87 +155,118 @@ export const Mechanisms: StoryObj = {
 
       <SectionTitle>Material — what a plane is made of</SectionTitle>
       <Text className="text-text-secondary text-xs mb-3">
-        Used sparingly. Paper is for HERO surfaces only and takes muted tones only — vivid colour
-        is ink ON paper, never the paper itself. There are no levels of paper; one treatment, or
-        the texture stops meaning anything.
+        Used sparingly. Paper is for HERO surfaces only and takes muted tones only; vivid colour is
+        ink ON paper, never the paper itself. There are no levels of paper. The lift above is
+        paper&apos;s rim and contact shadow without the grain: the same light, one grade quieter.
       </Text>
       <View style={{ flexDirection: 'row', gap: 10, marginBottom: 8 }}>
         <Swatch
           label="paperSheet"
-          note="tonal fill (ΔL* ≤ 3) + grain + dither + rim + contact shadow. Hero surfaces."
+          note="grain + rim + contact shadow. Hero surfaces."
           style={paperSheet(greyRamp[875]) as Record<string, unknown>}
         />
         <Swatch
           label="insetWell"
-          note="inner top cut + a light line on the floor. The floor rim is the half that says 'below'."
+          note="inner top cut + a light line on the floor. Also the recess of every pressed surface."
           style={insetWell(greyRamp[950]) as Record<string, unknown>}
         />
         <Swatch
           label="barPaper"
           note="the same grain curve, tuned for a small saturated element."
-          style={{ ...(barPaper(t['status-info']) as Record<string, unknown>), backgroundColor: t['status-info'] }}
+          style={{
+            ...(barPaper(t['status-info']) as Record<string, unknown>),
+            backgroundColor: t['status-info'],
+          }}
         />
       </View>
       <Text className="text-text-tertiary text-xs">
-        Materials are web/RNW only — `backgroundImage` and multi-layer `boxShadow` are ignored on
-        native. Every material keeps a solid `backgroundColor` underneath so a surface never
-        depends on one, and a material must never be the only thing carrying meaning.
+        Lift and materials are web/RNW only — `backgroundImage` and multi-layer `boxShadow` are
+        ignored on native, which gets one shadow. Every treatment keeps a solid `backgroundColor`
+        underneath, so a surface never depends on one, and a treatment is never the only thing
+        carrying meaning.
       </Text>
     </View>
   ),
 }
 
 export const Elevation: StoryObj = {
-  name: '2. Elevation — tone below, shadow only when floating',
+  name: '2. Elevation — planes on the ramp, lifted',
   render: () => (
-    <View style={{ padding: 24, backgroundColor: greyRamp[975] }}>
+    <View style={{ padding: 24, backgroundColor: greyRamp[925] }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Elevation</Text>
       <SectionIntro>
-        Levels 0–3 are separated by TONE ALONE. They cast no shadow, because a dark-on-dark drop
-        shadow is inert — it costs a composite layer and shows nothing. From{' '}
-        <Text className="font-semibold">{FLOATING_ELEVATION_MIN}</Text> up the element is
-        genuinely floating over a backdrop, where a large soft shadow describes separation rather
-        than rank, and there the shadow returns.
+        A level is a ramp plane plus the lift that plane wears. Level 0 is the page. Levels 1–3
+        climb one plane each and lift; from {FLOATING_ELEVATION_MIN} up the element is floating over
+        a backdrop, so it stays on the overlay plane and the shadow does the separating. In a
+        component the numbers are RELATIVE to the enclosing Surface, clamped at overlay, so a card
+        inside a card cannot leave the ramp.
       </SectionIntro>
+      <Text className="text-text-secondary text-xs mb-4">
+        Lift sparingly, and only over something much larger. A card lifts off the page; a small card
+        lifted off a small card reads as clutter, not depth. Inside a lifted surface, organise with
+        an inset well (`CardInset`, `Surface pressed`), a tone-only `filled` tile, or a hairline
+        divider, and save a second lift for a surface that genuinely floats over the first.
+      </Text>
 
-      <SectionTitle>Content levels — tone only</SectionTitle>
+      <SectionTitle>Content levels — tone + lift</SectionTitle>
       <View style={{ flexDirection: 'row', gap: 10, marginBottom: 22 }}>
         {CONTENT_LEVELS.map((lv) => (
           <Swatch
             key={lv}
             label={`elevation ${lv}`}
-            note={`${getElevationSurface(base, lv, 'dark')} · no shadow`}
-            style={{
-              backgroundColor: getElevationSurface(base, lv, 'dark'),
-              borderWidth: 1,
-              borderColor: t['hairline-default'],
-              ...(getElevationShadow(base, lv, 'dark') as Record<string, unknown>),
-            }}
+            note={`${ELEVATION_PLANE[lv]} · ${getElevationSurface(lv, 'dark')}${lv > 0 ? ` · liftStyle(${lv})` : ' · the page'}`}
+            // Level 0 IS the page, so a solid swatch on the page would be an
+            // invisible rectangle. A dashed outline gives the row a fourth slot
+            // and says why it has nothing to draw.
+            style={
+              lv === 0
+                ? {
+                    borderWidth: 1,
+                    borderStyle: 'dashed',
+                    borderColor: t['hairline-default'],
+                  }
+                : {
+                    backgroundColor: getElevationSurface(lv, 'dark'),
+                    ...(getElevationShadow(lv, 'dark') as Record<string, unknown>),
+                  }
+            }
           />
         ))}
       </View>
 
-      <SectionTitle>Floating levels — shadow returns, always with a ring</SectionTitle>
+      <SectionTitle>Floating levels — overlay plane, larger shadow, no ring</SectionTitle>
       <View style={{ flexDirection: 'row', gap: 24, marginBottom: 8 }}>
         {FLOATING_LEVELS.map((lv) => (
           <Swatch
             key={lv}
             label={`elevation ${lv}`}
-            note={`${getElevationSurface(base, lv, 'dark')} · casts a shadow`}
+            note={`${ELEVATION_PLANE[lv]} · ${getElevationSurface(lv, 'dark')} · three ambient layers`}
             style={{
-              backgroundColor: getElevationSurface(base, lv, 'dark'),
-              borderWidth: 1,
-              borderColor: t['hairline-strong'],
-              ...(getElevationShadow(base, lv, 'dark') as Record<string, unknown>),
+              backgroundColor: getElevationSurface(lv, 'dark'),
+              ...(getElevationShadow(lv, 'dark') as Record<string, unknown>),
             }}
           />
         ))}
       </View>
       <Text className="text-text-tertiary text-xs">
-        A floating surface should carry a hairline ring as well as its shadow — the shadow places
-        it above the page, the ring gives it an edge that survives on a panel where the shadow is
-        washed out by glare.
+        A floating surface carries the same rim as a card, not a hairline ring. The rim is the edge
+        that survives glare; a ring on top of it would be a second edge saying the same thing.
       </Text>
+
+      <SectionTitle>Recessed levels — one and two planes down</SectionTitle>
+      <View style={{ flexDirection: 'row', gap: 10, marginBottom: 8 }}>
+        {([-1, -2] as ElevationLevel[]).map((lv) => (
+          <Swatch
+            key={lv}
+            label={`elevation ${lv}`}
+            note={`${ELEVATION_PLANE[lv]} · ${getElevationSurface(lv, 'dark')} · insetWell recess`}
+            style={{
+              backgroundColor: getElevationSurface(lv, 'dark'),
+              ...(getElevationShadow(lv, 'dark') as Record<string, unknown>),
+            }}
+          />
+        ))}
+      </View>
     </View>
   ),
 }
@@ -208,19 +274,21 @@ export const Elevation: StoryObj = {
 export const WhyNotNeumorphism: StoryObj = {
   name: '3. Why not neumorphism',
   render: () => (
-    <View style={{ padding: 24, backgroundColor: greyRamp[975] }}>
+    <View style={{ padding: 24, backgroundColor: greyRamp[925] }}>
       <Text className="text-2xl font-bold text-text-primary mb-2">Why not neumorphism</Text>
       <SectionIntro>
         The system used to ship a neumorphic builder — a dark shadow bottom-right paired with a
-        light rim top-left. It was removed rather than retuned, and the reason is a lightness
-        budget rather than a preference, so it is worth being able to see.
+        light rim top-left. It was removed rather than retuned, and the reason is a lightness budget
+        rather than a preference, so it is worth being able to see.
       </SectionIntro>
 
       <Text className="text-text-secondary text-xs mb-4">
         Neumorphism needs a MID-TONE ground (roughly 75–90% lightness) so the dark half has
-        somewhere to fall and the light half has somewhere to rise. Our surfaces sit near 10%.
-        Below them there is almost nothing left — so the dark half disappears and the treatment
-        collapses to a one-sided rim, which reads as a smudge rather than as depth.
+        somewhere to fall and the light half has somewhere to rise. Our surfaces sit near 10%. Below
+        them there is almost nothing left — so the dark half disappears and the treatment collapses
+        to a one-sided rim, which reads as a smudge rather than as depth. The lift keeps the one
+        half that works (the top rim) and moves the shadow to where there IS room: straight down,
+        onto the plane below.
       </Text>
 
       <View style={{ flexDirection: 'row', gap: 24 }}>
@@ -294,9 +362,8 @@ export const WhyNotNeumorphism: StoryObj = {
                 width: 110,
                 height: 66,
                 borderRadius: 10,
-                backgroundColor: greyRamp[900],
-                borderWidth: 1,
-                borderColor: t['hairline-default'],
+                backgroundColor: greyRamp[875],
+                ...(liftStyle(2, 'dark') as Record<string, unknown>),
               }}
             />
           </View>
@@ -305,7 +372,7 @@ export const WhyNotNeumorphism: StoryObj = {
 
       <Text className="text-text-tertiary text-xs mt-4">
         Same treatment, same offsets, different ground. The middle panel is the one that shipped.
-        The right panel is one tone step plus a hairline — cheaper, and it survives glare.
+        The right panel is two ramp steps plus the lift: the rim from above, the shadow below.
       </Text>
     </View>
   ),

package/src/theme/DepthCalibration.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text, Pressable } from 'react-native'
 import { greyRamp } from './tokens/primitives'
 import { getSemanticColors } from './tokens/semantic'
-import { getBaseSurfaceColor, getElevationSurface, type ElevationLevel } from './elevation'
+import { getElevationSurface, type ElevationLevel } from './elevation'
 import { grainForTone, paperSheet } from './materials'
 
 /**
@@ -19,8 +19,9 @@ import { grainForTone, paperSheet } from './materials'
  * north-star doc set its floors explicitly "to survive glare + a mediocre
  * panel", and none of them have been looked at on the panel. That matters more
  * than the numbers suggest: solid dark borders were DELETED, so if the hairlines
- * wash out there is no fallback, and elevation levels 1-3 are separated by tone
- * alone now that shadow is gated behind FLOATING_ELEVATION_MIN.
+ * wash out there is no fallback. Elevation levels now resolve to the ramp planes
+ * themselves and wear a lift (rim + shadow) on top; C2 measures the tone half of
+ * that pairing on its own, because the lift must never be the only cue.
  *
  * WHY FORCED-CHOICE. "Does this look OK?" is close to unfalsifiable at
  * threshold — you are asking someone to report the absence of a faint thing they
@@ -45,7 +46,6 @@ const meta: Meta = {
 export default meta
 
 const t = getSemanticColors('dark')
-const base = getBaseSurfaceColor('dark')
 
 /**
  * The rig's ground sits BELOW the ramp, at true black.
@@ -105,7 +105,7 @@ function Panel({
             borderRadius: 8,
             borderWidth: 1,
             borderColor: t['hairline-strong'],
-            backgroundColor: getElevationSurface(base, 2, 'dark'),
+            backgroundColor: getElevationSurface(2, 'dark'),
           }}
         >
           <Text className="text-text-primary" style={{ fontSize: 14, fontWeight: '600' }}>
@@ -233,7 +233,9 @@ export const Hairlines: StoryObj = {
 
 // ── C2 · tone steps ─────────────────────────────────────────────────────────
 
-const STAIRCASE: ElevationLevel[] = [0, 1, 2, 3, 4, 5]
+// Levels 4 and 5 share the overlay plane by design (past the ramp the shadow
+// separates), so the staircase stops at the last distinct tone.
+const STAIRCASE: ElevationLevel[] = [-2, -1, 0, 1, 2, 3]
 
 /**
  * Adjacent-step pairs, with the lighter side pre-assigned to a fixed side and
@@ -244,13 +246,13 @@ const STEP_PAIRS: { left: ElevationLevel; right: ElevationLevel; label: string }
   { left: 1, right: 0, label: '1' },
   { left: 2, right: 3, label: '2' },
   { left: 2, right: 2, label: '3' },
-  { left: 3, right: 4, label: '4' },
+  { left: -1, right: 0, label: '4' },
   { left: 1, right: 2, label: '5' },
-  { left: 5, right: 4, label: '6' },
+  { left: -2, right: -1, label: '6' },
 ]
 
 export const ToneSteps: StoryObj = {
-  name: 'C2 · Tone steps — levels 1-3 have nothing else',
+  name: 'C2 · Tone steps — the ramp with the lift stripped off',
   render: () => (
     <Panel
       title="C2 · Tone steps"
@@ -266,13 +268,13 @@ export const ToneSteps: StoryObj = {
             {STAIRCASE.map((lv) => (
               <View
                 key={lv}
-                style={{ flex: 1, backgroundColor: getElevationSurface(base, lv, 'dark') }}
+                style={{ flex: 1, backgroundColor: getElevationSurface(lv, 'dark') }}
               />
             ))}
           </View>
           <Text className="text-text-tertiary" style={{ fontSize: 13, marginTop: 8 }}>
             {revealed
-              ? `6 bands / 5 edges — elevation 0…5, colorAdjustment 0 · .025 · .05 · .075 · .10 · .13`
+              ? `6 bands / 5 edges — elevation -2…3 = frame · background · base · elevated · raised · overlay`
               : 'Edges visible: ______'}
           </Text>
 
@@ -285,13 +287,13 @@ export const ToneSteps: StoryObj = {
                   <View
                     style={{
                       flex: 1,
-                      backgroundColor: getElevationSurface(base, pair.left, 'dark'),
+                      backgroundColor: getElevationSurface(pair.left, 'dark'),
                     }}
                   />
                   <View
                     style={{
                       flex: 1,
-                      backgroundColor: getElevationSurface(base, pair.right, 'dark'),
+                      backgroundColor: getElevationSurface(pair.right, 'dark'),
                     }}
                   />
                 </View>
@@ -310,18 +312,18 @@ export const ToneSteps: StoryObj = {
           {revealed ? (
             <View style={{ marginTop: 14, maxWidth: 1000 }}>
               <KeyLine>
-                {'Pair 1 is the one that matters: it is the 0.025 step from level 0 to level 1, the ' +
-                  'smallest in the ladder and the one carrying the most UI. Pair 3 is the decoy.'}
+                {'Pair 2 is the one that matters: raised → overlay is the tightest step on the ' +
+                  'ramp (ΔL* 2.5) and the one a card inside a card lands on. Pair 3 is the decoy.'}
               </KeyLine>
               <KeyLine>
                 {'PASS: all five edges counted on the staircase, pairs 1/2/4/5/6 called correctly, ' +
-                  'pair 3 called SAME. Missing pair 1 means level 1 is not a level — it is level 0 ' +
-                  'with extra bookkeeping, and no shadow is coming to save it below level 4.'}
+                  'pair 3 called SAME. In production every lifted plane also wears a rim + shadow, ' +
+                  'but the tone must carry on its own — native has no multi-layer shadow at all.'}
               </KeyLine>
               <KeyLine>
-                {'Retune lever: widen `colorAdjustment` on elevation levels 1-3 in elevation.ts. ' +
-                  'Level 5 is the ceiling the ladder has to fit under, so widening the bottom ' +
-                  'compresses the top — re-space the whole ladder rather than nudging one entry.'}
+                {'Retune lever: the ramp itself (tokens/primitives.ts, greyRamp 850–975). The ' +
+                  'elevation ladder no longer has values of its own to widen — it reads the ramp — ' +
+                  'so a missed step is a ramp finding, and re-spacing goes through the generator.'}
               </KeyLine>
             </View>
           ) : null}
@@ -578,7 +580,7 @@ const BAND_FIELDS: { key: string; answer: string; style: Record<string, unknown>
     style: {
       backgroundImage: `linear-gradient(180deg, ${BAND_STEPS.map(
         (hex, i) =>
-          `${hex} ${(i / BAND_STEPS.length) * 100}%, ${hex} ${((i + 1) / BAND_STEPS.length) * 100}%`,
+          `${hex} ${(i / BAND_STEPS.length) * 100}%, ${hex} ${((i + 1) / BAND_STEPS.length) * 100}%`
       ).join(', ')})`,
     },
   },

package/src/theme/ThemeProvider.test.tsx

@@ -14,7 +14,7 @@ describe('ThemeProvider', () => {
     render(
       <ThemeProvider>
         <Text>inside</Text>
-      </ThemeProvider>,
+      </ThemeProvider>
     )
     expect(screen.getByText('inside')).toBeInTheDocument()
   })
@@ -23,7 +23,7 @@ describe('ThemeProvider', () => {
     render(
       <ThemeProvider mode="light">
         <Text>light</Text>
-      </ThemeProvider>,
+      </ThemeProvider>
     )
     expect(screen.getByText('light')).toBeInTheDocument()
   })
@@ -32,7 +32,7 @@ describe('ThemeProvider', () => {
     render(
       <ThemeProvider mode="light">
         <ModeProbe />
-      </ThemeProvider>,
+      </ThemeProvider>
     )
     expect(screen.getByText('light')).toBeInTheDocument()
   })
@@ -41,7 +41,7 @@ describe('ThemeProvider', () => {
     render(
       <ThemeProvider mode="system">
         <ModeProbe />
-      </ThemeProvider>,
+      </ThemeProvider>
     )
     expect(screen.getByText('dark')).toBeInTheDocument()
   })