@titan-design/react-ui 0.12.1 → 0.14.0

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

@@ -1,57 +1,14 @@
 import React, { useMemo } from 'react'
-import { View, type ViewProps, type ViewStyle } from 'react-native'
+import { View, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
-import { type ThemeMode } from '../../../theme/tokens/semantic'
-import {
-  type ElevationLevel,
-  getElevationSurface,
-  getElevationShadow,
-  getPressedRecessShadow,
-  getBaseSurfaceColor,
-  type GlowIntensity,
-  getGlowShadow,
-} from '../../../theme/elevation'
-import {
-  SurfaceContext,
-  surfaceBackground,
-  pressedLevel,
-  useSurface,
-  type SurfaceContextValue,
-  type SurfaceLevel,
-} from './SurfaceContext'
+import { type GlowIntensity, getGlowShadow } from '../../../theme/elevation'
+import { SurfaceContext, type SurfaceContextValue } from './SurfaceContext'
+import { useResolvedSurface, type SurfaceDepthProps } from './resolveSurface'
 
-export interface SurfaceProps extends ViewProps {
-  /**
-   * Numeric depth → a computed lighten + shadow (the raised-card model). The
-   * background is derived from the base surface by lightening. Ignored for the
-   * background when `level` is set. Default 0 (flat card).
-   */
-  elevation?: ElevationLevel
-  /**
-   * 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.
-   */
-  level?: SurfaceLevel
-  /**
-   * Sunken "well": render ONE ramp step DOWN from the parent surface's level —
-   * the symmetric twin of a raised surface stepping up — and add an inner-shadow
-   * recess so the surface reads pressed (darker fill + inset shadow). Relative to
-   * the enclosing Surface's level (not this surface's own `level`), and clamped
-   * at the ramp's `inset` floor so it never underflows. One level of depth only.
-   */
-  pressed?: boolean
+export interface SurfaceProps extends ViewProps, SurfaceDepthProps {
   glowColor?: string
   glowIntensity?: GlowIntensity
-  /**
-   * Theme mode. Also seeds the on-surface colour CONTEXT so descendant text /
-   * icons resolve their colour from this surface instead of a `text-*` className
-   * that silently fails to black on raw RN. Inherits the nearest Surface /
-   * ThemeProvider when omitted (default dark — the wall).
-   */
-  theme?: ThemeMode
-  /** Round the corners. Defaults on for the card model, off for a `level` plane. */
+  /** Round the corners. Defaults on for a lifted or pressed surface, off for an absolute plane. */
   rounded?: boolean
   className?: string
   children?: React.ReactNode
@@ -59,17 +16,23 @@ 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 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')`.
+ * context. Depth is relative to the enclosing Surface:
+ *  - `raise` / positive `elevation`: step up the ramp and wear the lift
+ *    treatment (rim-light + ambient shadow). Clamps at `overlay`.
+ *  - `pressed` / negative `elevation`: step down with an inner-shadow recess.
+ *  - `level` (absolute): a flat grey plane straight from a token, for shell
+ *    roots only (shell = background, page = base). No lift.
+ *  - nothing: sit flat on the inherited plane.
+ * Descendants read the surface via {@link useOnSurfaceColor} / {@link useSurfaceMode}
+ * rather than hard-coding `getSemanticColors('dark')`.
  */
 export function Surface({
-  elevation = 0,
+  elevation,
   level,
+  raise,
   pressed = false,
+  lift,
+  liftOptions,
   glowColor,
   glowIntensity,
   theme,
@@ -79,39 +42,21 @@ export function Surface({
   children,
   ...props
 }: SurfaceProps) {
-  const inherited = useSurface()
-  const mode = theme ?? inherited.mode
-  const isPlane = level != null
-
-  // 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 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)
-
-  let backgroundColor: string
-  let shadowStyle: ViewStyle
-  if (pressed) {
-    backgroundColor = surfaceBackground(resolvedLevel, mode)
-    shadowStyle = getPressedRecessShadow(backgroundColor, mode)
-  } else if (isPlane) {
-    backgroundColor = surfaceBackground(level, mode)
-    // Planes own a flat full-bleed background — no depth shadow.
-    shadowStyle = {}
-  } else {
-    backgroundColor = getElevationSurface(baseColor, elevation, mode)
-    shadowStyle = getElevationShadow(baseColor, elevation, mode)
-  }
-
+  const resolved = useResolvedSurface({
+    elevation,
+    level,
+    raise,
+    pressed,
+    lift,
+    liftOptions,
+    theme,
+  })
   const glowStyle = glowColor ? getGlowShadow(glowColor, glowIntensity) : {}
-  // A pressed well and the card model round by default; a flat plane doesn't.
-  const applyRounded = rounded ?? (pressed || !isPlane)
+  const applyRounded = rounded ?? (pressed || level == null)
 
   const value = useMemo<SurfaceContextValue>(
-    () => ({ mode, level: resolvedLevel }),
-    [mode, resolvedLevel]
+    () => ({ mode: resolved.mode, level: resolved.plane }),
+    [resolved.mode, resolved.plane]
   )
 
   return (
@@ -119,7 +64,12 @@ export function Surface({
       <View
         className={cn(applyRounded && 'rounded-2xl', className)}
         // backgroundColor first so a caller `style` can still override it.
-        style={[{ backgroundColor }, shadowStyle, glowStyle, style]}
+        style={[
+          { backgroundColor: resolved.backgroundColor },
+          resolved.depthStyle,
+          glowStyle,
+          style,
+        ]}
         {...props}
       >
         {children}

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

@@ -1,52 +1,31 @@
 // On-surface colour context (TD-05.12).
 //
-// A <Surface> owns a background from a small elevation scale AND publishes the
-// current theme mode so descendant text/icons resolve their colour from "what
-// surface am I on" instead of a `text-*` className. Those classNames silently
-// fail to black when the tree renders as raw RN in the standalone wall SPA
-// (no global.css, no nativewind) — the bug class this primitive retires.
+// A <Surface> owns a background from the surface ramp AND publishes the current
+// theme mode so descendant text/icons resolve their colour from "what surface am
+// I on" instead of a `text-*` className. Those classNames silently fail to black
+// when the tree renders as raw RN in the standalone wall SPA (no global.css, no
+// nativewind), which is the bug class this primitive retires.
 import { createContext, useContext } from 'react'
 import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
+import type { SurfaceLevel } from '../../../theme/surface-planes'
 
-type ColorToken = keyof ReturnType<typeof getSemanticColors>
+// The plane vocabulary lives in the theme so `elevation.ts` can resolve levels
+// to planes without importing a component. Re-exported here for callers that
+// reached it through the Surface module.
+export {
+  SURFACE_LEVEL_TOKEN,
+  PLANE_ORDER,
+  surfaceBackground,
+  pressedLevel,
+  raisedLevel,
+  type SurfaceLevel,
+} from '../../../theme/surface-planes'
 
-/**
- * A Surface's depth on the dark surface ramp. Each addressable level maps to an
- * EXISTING semantic surface/background token (already grounded in the derived
- * surface ramp — TD-surface-tokens S-1 — and theme-aware) — Surface introduces
- * no new hexes. Darkest → lightest:
- *   inset (#13100D) < background (#1C1916) < base (#252321) < elevated (#2A2827) < raised (#2D2C2B) < overlay (#302F2E)
- *
- * `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 = 'frame' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
 
 /** On-surface neutral text roles, resolved for the current surface + theme. */
 export type OnSurfaceRole = 'primary' | 'secondary' | 'tertiary'
 
-// 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<SurfaceLevel, ColorToken>
-
-// 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',
   secondary: 'text-secondary',
@@ -56,7 +35,7 @@ const ON_SURFACE_TOKEN = {
 export interface SurfaceContextValue {
   /** Active theme mode. Defaults to dark (the wall). */
   mode: ThemeMode
-  /** Depth of the nearest enclosing Surface. */
+  /** Plane of the nearest enclosing Surface. */
   level: SurfaceLevel
 }
 
@@ -78,9 +57,9 @@ export function useSurfaceMode(): ThemeMode {
 
 /**
  * Literal-hex on-surface neutral text colours for a theme mode. Uses
- * `getSemanticColors` (literal hex — the TempoBar pattern), never `resolveColor`
- * (which returns `var()` under the RNW vitest alias), so values stay real in
- * tested component code and on raw-RN surfaces alike.
+ * `getSemanticColors` (literal hex), never `resolveColor` (which returns `var()`
+ * under the RNW vitest alias), so values stay real in tested component code and
+ * on raw-RN surfaces alike.
  */
 export function onSurfaceColors(mode: ThemeMode): Record<OnSurfaceRole, string> {
   const c = getSemanticColors(mode)
@@ -95,22 +74,3 @@ export function onSurfaceColors(mode: ThemeMode): Record<OnSurfaceRole, string>
 export function useOnSurfaceColor(role: OnSurfaceRole = 'primary'): string {
   return getSemanticColors(useSurfaceMode())[ON_SURFACE_TOKEN[role]]
 }
-
-/** The background hex for a surface level under a theme mode (literal hex). */
-export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
-  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 `frame` floor so a pressed surface never underflows the bezel.
- *   overlay→raised, raised→elevated, elevated→base, base→background,
- *   background→frame, frame→frame (clamped).
- * Pressed exposes ONE level of depth only (no pressed-2).
- */
-export function pressedLevel(parent: SurfaceLevel): SurfaceLevel {
-  const index = PRESSED_RAMP.indexOf(parent)
-  const down = Math.max(0, index - 1)
-  return PRESSED_RAMP[down]
-}

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

@@ -1,4 +1,10 @@
 export { Surface, type SurfaceProps } from './Surface'
+export {
+  resolveSurfaceDepth,
+  useResolvedSurface,
+  type SurfaceDepthProps,
+  type ResolvedSurface,
+} from './resolveSurface'
 export {
   SurfaceContext,
   useSurface,
@@ -7,7 +13,9 @@ export {
   onSurfaceColors,
   surfaceBackground,
   pressedLevel,
+  raisedLevel,
   SURFACE_LEVEL_TOKEN,
+  PLANE_ORDER,
   type SurfaceLevel,
   type OnSurfaceRole,
   type SurfaceContextValue,

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

@@ -0,0 +1,98 @@
+// How a container decides which plane it sits on and what it wears there.
+//
+// One resolution path shared by <Surface> and <Card>, so the two can never
+// disagree about depth. Everything is RELATIVE to the enclosing Surface unless
+// an absolute `level` names a shell root.
+import { useMemo } from 'react'
+import type { ViewStyle } from 'react-native'
+import {
+  FLOATING_ELEVATION_MIN,
+  getPressedRecessShadow,
+  type ElevationLevel,
+} from '../../../theme/elevation'
+import { liftStyle, type LiftOptions, type LiftStep } from '../../../theme/lift'
+import {
+  pressedLevel,
+  raisedLevel,
+  surfaceBackground,
+  type SurfaceLevel,
+} from '../../../theme/surface-planes'
+import type { ThemeMode } from '../../../theme/tokens/semantic'
+import { useSurface, type SurfaceContextValue } from './SurfaceContext'
+
+export interface SurfaceDepthProps {
+  /** Absolute plane, for shell roots (shell = background, page = base). No lift. */
+  level?: SurfaceLevel
+  /** Planes to step UP from the enclosing Surface, with the lift treatment. */
+  raise?: 1 | 2 | 3
+  /**
+   * Numeric depth relative to the enclosing Surface: negative recesses, 0 sits
+   * flat on the same plane, 1–3 lift, 4–5 float on the overlay plane.
+   */
+  elevation?: ElevationLevel
+  /** One plane DOWN with an inner-shadow recess. */
+  pressed?: boolean
+  /** Force the lift treatment on or off regardless of the step taken. */
+  lift?: boolean
+  /** Tune the lift (rim alpha). Specimens and hero surfaces only. */
+  liftOptions?: LiftOptions
+  /** Override the inherited theme mode. */
+  theme?: ThemeMode
+}
+
+export interface ResolvedSurface {
+  mode: ThemeMode
+  plane: SurfaceLevel
+  backgroundColor: string
+  /** Recess or lift, to compose after `backgroundColor`. */
+  depthStyle: ViewStyle
+  /** Planes stepped up (0 when flat, pressed, or an absolute plane). */
+  step: number
+  lifted: boolean
+}
+
+function recessDepth(inherited: SurfaceContextValue, planesDown: number, mode: ThemeMode) {
+  let plane = inherited.level
+  for (let i = 0; i < planesDown; i++) plane = pressedLevel(plane)
+  const backgroundColor = surfaceBackground(plane, mode)
+  return { plane, backgroundColor, depthStyle: getPressedRecessShadow(backgroundColor, mode) }
+}
+
+/** Pure resolution: the plane, its hex, and the treatment. */
+export function resolveSurfaceDepth(
+  inherited: SurfaceContextValue,
+  props: SurfaceDepthProps
+): ResolvedSurface {
+  const mode = props.theme ?? inherited.mode
+  const elevation = props.elevation ?? 0
+  if (props.pressed || elevation < 0) {
+    const down = props.pressed ? 1 : -elevation
+    return { mode, step: 0, lifted: false, ...recessDepth(inherited, down, mode) }
+  }
+  const step = props.level != null ? 0 : (props.raise ?? elevation)
+  const floating = step >= FLOATING_ELEVATION_MIN
+  const plane = props.level ?? (floating ? 'overlay' : raisedLevel(inherited.level, step))
+  const lifted = props.lift ?? step > 0
+  const liftStep = Math.max(1, Math.min(5, step)) as LiftStep
+  const depthStyle = lifted ? liftStyle(liftStep, mode, props.liftOptions) : {}
+  return { mode, plane, backgroundColor: surfaceBackground(plane, mode), depthStyle, step, lifted }
+}
+
+/** The resolved depth of a container at this point in the tree. */
+export function useResolvedSurface(props: SurfaceDepthProps): ResolvedSurface {
+  const inherited = useSurface()
+  const { level, raise, elevation, pressed, lift, liftOptions, theme } = props
+  return useMemo(
+    () =>
+      resolveSurfaceDepth(inherited, {
+        level,
+        raise,
+        elevation,
+        pressed,
+        lift,
+        liftOptions,
+        theme,
+      }),
+    [inherited, level, raise, elevation, pressed, lift, liftOptions, theme]
+  )
+}

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

@@ -8,7 +8,8 @@ import { getSemanticColors } from '../../../theme/tokens/semantic'
  * palette locks its eligibility mask with a value-level test.
  *
  * Scope: DARK mode only. The north-star diagnosis
- * (sources/design/surface-system-north-star.md) measured and
+ * (`sources/design/surface-system-north-star.md`, in the `voltras-workspace`
+ * active-work initiative rather than this repo) 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
@@ -91,6 +92,10 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
     // 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 are unchanged by the re-space.
+    //
+    // The literal hexes are the POINT of this one test: it pins the bytes, so a
+    // re-space has to come here and say so. Every other test in the suite
+    // references the ramp instead.
     expect(dark['background-frame']).toBe('#100D0A')
     expect(dark['background-base']).toBe('#1C1916')
     expect(dark['surface-base']).toBe('#252321')

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

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

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

@@ -1,6 +1,8 @@
 import React, { forwardRef } from 'react'
 import { Pressable, View, Text, type PressableProps } from 'react-native'
 import { cn } from '../../../utils/cn'
+import { liftStyle } from '../../../theme/lift'
+import { useSurfaceMode } from '../surface'
 
 export type SwitchSize = 'sm' | 'md' | 'lg'
 
@@ -51,6 +53,7 @@ export const Switch = forwardRef<View, SwitchProps>(function Switch(
   ref
 ) {
   const styles = sizeStyles[size]
+  const mode = useSurfaceMode()
 
   const handlePress = () => {
     if (!isDisabled) {
@@ -66,12 +69,14 @@ export const Switch = forwardRef<View, SwitchProps>(function Switch(
         isChecked ? 'bg-brand-primary' : 'bg-hairline-strong'
       )}
     >
+      {/* The thumb is a raised control resting in its track: one plane of lift. */}
       <View
         className={cn(
-          'rounded-full bg-white shadow-sm transition-transform',
+          'rounded-full bg-on-brand-primary transition-transform',
           styles.thumb,
           isChecked && styles.translate
         )}
+        style={liftStyle(1, mode)}
       />
     </View>
   )
@@ -84,11 +89,7 @@ export const Switch = forwardRef<View, SwitchProps>(function Switch(
       accessibilityRole="switch"
       accessibilityState={{ checked: isChecked, disabled: isDisabled }}
       accessibilityLabel={label}
-      className={cn(
-        'flex-row items-center gap-2',
-        isDisabled && 'opacity-50',
-        className
-      )}
+      className={cn('flex-row items-center gap-2', isDisabled && 'opacity-50', className)}
       {...props}
     >
       {label && labelPosition === 'left' && (

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

@@ -5,7 +5,7 @@ import { Tabs, TabList, Tab, TabPanels, TabPanel } from './Tabs'
 const meta: Meta<typeof Tabs> = {
   title: 'Components/Molecules/Tabs',
   component: Tabs,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     variant: {
       control: 'select',

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

@@ -75,10 +75,7 @@ export function Tabs({
   return (
     <TabsContext.Provider value={{ activeIndex, setActiveIndex, variant, orientation }}>
       <View
-        className={cn(
-          orientation === 'vertical' ? 'flex-row' : 'flex-col',
-          className
-        )}
+        className={cn(orientation === 'vertical' ? 'flex-row' : 'flex-col', className)}
         {...props}
       >
         {children}
@@ -99,9 +96,7 @@ export function TabList({ children, className }: TabListProps) {
   const { variant, orientation } = useContext(TabsContext)
 
   const variantStyles = {
-    line: orientation === 'horizontal'
-      ? 'border-b border-hairline'
-      : 'border-r border-hairline',
+    line: orientation === 'horizontal' ? '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',
   }
@@ -151,12 +146,7 @@ export interface TabProps {
 /**
  * Individual tab button.
  */
-export function Tab({
-  index = 0,
-  isDisabled = false,
-  className,
-  children,
-}: TabProps) {
+export function Tab({ index = 0, isDisabled = false, className, children }: TabProps) {
   const { activeIndex, setActiveIndex, variant, orientation } = useContext(TabsContext)
   const isActive = activeIndex === index
 
@@ -170,16 +160,17 @@ export function Tab({
         ? 'border-brand-primary text-brand-primary'
         : 'border-transparent text-text-secondary web:hover:text-text-primary'
     ),
+    // The active enclosed tab is an indicator, not a plane: tone alone marks it.
     enclosed: cn(
       'px-4 py-2 rounded-md',
       isActive
-        ? 'bg-surface-elevated text-text-primary shadow-sm'
+        ? 'bg-surface-elevated text-text-primary'
         : 'text-text-secondary web:hover:text-text-primary'
     ),
     'soft-rounded': cn(
       'px-4 py-2 rounded-full',
       isActive
-        ? 'bg-brand-primary text-white'
+        ? 'bg-brand-primary text-on-brand-primary'
         : 'text-text-secondary web:hover:text-text-primary'
     ),
   }
@@ -202,7 +193,7 @@ export function Tab({
           'font-medium',
           isActive
             ? variant === 'soft-rounded'
-              ? 'text-white'
+              ? 'text-on-brand-primary'
               : 'text-text-primary'
             : 'text-text-secondary'
         )}
@@ -245,9 +236,5 @@ export interface TabPanelProps {
  * Individual tab panel content.
  */
 export function TabPanel({ children, className }: TabPanelProps) {
-  return (
-    <View className={cn('py-4', className)}>
-      {children}
-    </View>
-  )
+  return <View className={cn('py-4', className)}>{children}</View>
 }

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

@@ -1,10 +1,4 @@
-export {
-  Tabs,
-  TabList,
-  Tab,
-  TabPanels,
-  TabPanel,
-} from './Tabs'
+export { Tabs, TabList, Tab, TabPanels, TabPanel } from './Tabs'
 export type {
   TabsProps,
   TabListProps,

package/src/components/ui/tile/Tile.stories.tsx

@@ -9,7 +9,7 @@ const SUCCESS = getSemanticColors('dark')['status-success']
 const meta: Meta<typeof Tile> = {
   title: 'Components/Atoms/Tile',
   component: Tile,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   parameters: {
     docs: {
       description: {

package/src/components/ui/tile/Tile.tsx

@@ -23,6 +23,9 @@ export interface TileProps extends ViewProps {
  * @example
  * <Tile label="Volume" value="76%" />
  * <Tile label="Fatigue" value="MOD" valueColor="#F5A623" />
+ *
+ * @deprecated Use the `Card` stat preset (roadmap decision 1) — removed after
+ * AW-127 consumer migration.
  */
 export function Tile({
   label,

package/src/components/ui/toast/Toast.stories.tsx

@@ -6,7 +6,7 @@ import { Button, ButtonText } from '../button'
 const meta: Meta<typeof Toast> = {
   title: 'Components/Molecules/Toast',
   component: Toast,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     status: {
       control: 'select',

package/src/components/ui/toast/Toast.test.tsx

@@ -90,11 +90,7 @@ describe('ToastProvider', () => {
     const { addToast, removeAllToasts } = useToast()
     return (
       <div>
-        <button
-          onClick={() =>
-            addToast({ title: 'New Toast', status: 'success' })
-          }
-        >
+        <button onClick={() => addToast({ title: 'New Toast', status: 'success' })}>
           Add Toast
         </button>
         <button onClick={removeAllToasts}>Clear All</button>
@@ -179,9 +175,7 @@ describe('ToastProvider', () => {
       return null
     }
 
-    expect(() => render(<BadConsumer />)).toThrow(
-      'useToast must be used within a ToastProvider'
-    )
+    expect(() => render(<BadConsumer />)).toThrow('useToast must be used within a ToastProvider')
   })
 
   describe('positions', () => {