@titan-design/react-ui 0.10.0 → 0.12.0

package/src/theme/barrel.ts

@@ -8,7 +8,8 @@
 // top for the native consumers that deliberately import it.
 export * from './tokens'
 export * from './config'
-export * from './shadows'
+export * from './materials'
+export * from './color-utils'
 export * from './elevation'
 export * from './manifest'
 export { resolveColor } from './resolve-color'
@@ -22,24 +23,16 @@ export type { ThemeProviderProps, ThemeProviderMode } from './ThemeProvider'
 export { getSemanticColors, type ThemeMode } from './tokens/semantic'
 export { getThemeCSSVars, gluestackConfig } from './config'
 export {
-  neumorphicShadows,
-  // Color math utilities (HSV-based)
+  hexToRgb,
+  rgbToHsv,
+  hsvToRgb,
+  rgbToHex,
   lighten,
   darken,
   getHoverColors,
   isDark,
-  hexToRgb,
-  rgbToHsv,
-  // Shadow creation functions
-  createRaisedShadow,
-  createRaisedHoverShadow,
-  createPressedShadow,
-  createPressedHoverShadow,
-  createFlatShadow,
-  shadowColors,
   type ShadowIntensity,
-  type ShadowSurface,
-} from './shadows'
+} from './color-utils'
 export {
   getElevationConfig,
   getElevationSurface,

package/src/theme/color-stories.coverage.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { greyRamp, SURFACE_PLANE_STEPS } from './tokens/primitives'
+import { semanticColorsDark } from './tokens/semantic'
+
+/**
+ * Drift guard for the Foundations/Color stories (VW-33).
+ *
+ * The color stories are the documentation of record for the token layer, and
+ * they have drifted twice: once when the categorical palette replaced the
+ * Paul-Tol scale, and again when the v0.10.0 surface redesign added four
+ * planes (`surface-overlay`, `background-frame`,
+ * `background-subtle`) that no story rendered. Both times the values stayed
+ * correct while the *coverage* silently fell behind — which a screenshot test
+ * cannot catch, because a story that was never written renders nothing.
+ *
+ * Two invariants, deliberately different in kind:
+ *
+ *  1. STRUCTURAL — every `surface-*`/`background-*` token resolves to a plane
+ *     in the shipped ramp. Catches a token added off-ramp (an arbitrary fill),
+ *     which is the failure the ordered-ramp story exists to prevent.
+ *  2. COVERAGE — every other semantic token is named somewhere in the color
+ *     stories, so a new token cannot ship without a swatch.
+ *
+ * The story files are read as TEXT, never imported: they pull in react-native
+ * and nativewind, which throw under the node test environment. (They are also
+ * outside the `stories-smoke` glob, which only composes `components/**` — so
+ * this text guard is the only automated check on the color stories.)
+ *
+ * Both halves of Foundations/Color are scanned as one corpus: `Primitives`
+ * documents the raw scales, `Palettes` the assignments of them. A token is
+ * covered if EITHER names it — which is right, because the sidebar split is an
+ * organising choice and coverage is about the token having a swatch at all.
+ */
+
+const themeDir = path.dirname(fileURLToPath(import.meta.url))
+const storySources = ['ColorPrimitives.stories.tsx', 'ColorPalettes.stories.tsx']
+  .map((f) => readFileSync(path.join(themeDir, f), 'utf8'))
+  .join('\n')
+
+/** Every plane a surface/background token is allowed to land on. */
+const RAMP_PLANES = new Set<string>(
+  Object.values(SURFACE_PLANE_STEPS).map((step) => greyRamp[step])
+)
+
+/**
+ * Token families the color stories are NOT the documentation of record for,
+ * with the story that owns them instead. Add here only with a real owner —
+ * the point of this list is that nothing falls through unowned.
+ */
+const DOCUMENTED_ELSEWHERE: Record<string, string> = {
+  hairline: 'Components/Atoms/Surface (rendered as separators, not swatches)',
+  on: 'Components/Atoms/Surface — OnSurfaceText (paired with their surface)',
+  interactive: 'Components/* (state colors are shown on the components themselves)',
+  avatar: 'Components/Atoms/Avatar',
+}
+
+const isSurfaceToken = (name: string) => /^(surface|background)-/.test(name)
+
+/** Must mirror VARIANT_SUFFIXES in ColorPalettes.stories.tsx (asserted below). */
+const VARIANT_SUFFIXES = ['light', 'dark', 'subtle', 'hover', 'active', 'muted'] as const
+
+describe('Foundations/Color story coverage', () => {
+  it('every surface/background token resolves to a plane in the shipped ramp', () => {
+    const offRamp = Object.entries(semanticColorsDark)
+      .filter(([name]) => isSurfaceToken(name))
+      .filter(([, value]) => !RAMP_PLANES.has(value as string))
+      .map(([name, value]) => `${name}=${value as string}`)
+
+    expect(
+      offRamp,
+      'surface/background tokens whose value is not one of the greyRamp steps ' +
+        'named in SURFACE_PLANE_STEPS. Either fold the value into the ramp, or add ' +
+        'the plane to SURFACE_PLANES in ColorPalettes.stories.tsx and document why ' +
+        'it sits outside the ramp.'
+    ).toEqual([])
+  })
+
+  it("the test's VARIANT_SUFFIXES mirror still matches the story", () => {
+    // The coverage rule below depends on this list matching the one the story
+    // renders from; if they drift, coverage silently over- or under-reports.
+    const declared = storySources.match(/const VARIANT_SUFFIXES = \[([^\]]*)\]/)
+    expect(declared, 'VARIANT_SUFFIXES not found in ColorPalettes.stories.tsx').not.toBeNull()
+    const fromStory = [...declared![1].matchAll(/'([a-z]+)'/g)].map((m) => m[1])
+    expect(fromStory).toEqual([...VARIANT_SUFFIXES])
+  })
+
+  it('the surface story renders every ramp plane', () => {
+    // Each plane is a greyRamp step now, so the ladder must reference the step
+    // rather than a named member of a separate ramp object.
+    const missing = Object.values(SURFACE_PLANE_STEPS)
+      .map((step) => `greyRamp[${step}]`)
+      .filter((ref) => !storySources.includes(ref))
+
+    expect(missing, 'ramp planes absent from the SURFACE_PLANES ladder').toEqual([])
+    // Guard the count too: a plane added to the ramp must gain a row.
+    expect(Object.keys(SURFACE_PLANE_STEPS)).toHaveLength(6)
+  })
+
+  it('every other semantic token is named in a color story', () => {
+    // A token is covered if the story names it literally, or if it is the
+    // `-light`/`-subtle`/… variant of a base the story feeds to VariantMatrix
+    // (which builds those names at runtime, so they never appear as literals).
+    const namedLiterally = (token: string) => storySources.includes(`'${token}'`)
+    const coveredByMatrix = (token: string) =>
+      VARIANT_SUFFIXES.some(
+        (suffix) =>
+          token.endsWith(`-${suffix}`) && namedLiterally(token.slice(0, -(suffix.length + 1)))
+      )
+
+    const undocumented = Object.keys(semanticColorsDark)
+      .filter((name) => !isSurfaceToken(name))
+      .filter((name) => !DOCUMENTED_ELSEWHERE[name.split('-')[0]])
+      .filter((name) => !namedLiterally(name) && !coveredByMatrix(name))
+
+    expect(
+      undocumented,
+      'semantic tokens with no swatch in Foundations/Color. Add one (a plain ' +
+        'ColorSwatch, or the base to a VariantMatrix), or add the family to ' +
+        'DOCUMENTED_ELSEWHERE with the story that owns it.'
+    ).toEqual([])
+  })
+})

package/src/theme/color-story-kit.tsx

@@ -0,0 +1,170 @@
+/**
+ * Shared render parts for the Foundations/Color stories.
+ *
+ * The colour documentation spans two sibling titles — `Foundations/Color/
+ * Primitives` (the raw scales and their validation) and `Foundations/Color/
+ * Palettes` (the organisations of those scales into meaning). Both draw the
+ * same swatch, scale and section furniture, so it lives here rather than being
+ * copied into each.
+ *
+ * NOT a `.stories.tsx`, so Storybook's glob skips it. Note that
+ * `color-stories.coverage.test.ts` scans the STORY files as text for token
+ * names — a token whose only mention is in this file would not count as
+ * documented, which is correct: the swatch has to be in a story to be seen.
+ */
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { bestTextColor } from './tokens/primitives'
+import { semanticColorsDark } from './tokens/semantic'
+
+/**
+ * Hairline around every swatch, so a swatch whose fill matches the page still
+ * reads as one. Sourced from the token layer rather than a literal — the color
+ * stories should not be where raw hexes creep back in.
+ */
+export const SWATCH_BORDER = semanticColorsDark['hairline-default']
+
+export function SectionIntro({ children }: { children: ReactNode }) {
+  return <Text className="text-text-secondary mb-6">{children}</Text>
+}
+
+export function SectionTitle({ children }: { children: string }) {
+  return <Text className="text-lg font-bold text-text-primary mb-3 mt-2">{children}</Text>
+}
+
+export function ColorSwatch({ name, value }: { name: string; value: string }) {
+  const displayValue = value.startsWith('rgba') ? value : value.toUpperCase()
+
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 12 }}>
+      <View
+        style={{
+          width: 48,
+          height: 48,
+          borderRadius: 8,
+          backgroundColor: value,
+          borderWidth: 1,
+          borderColor: SWATCH_BORDER,
+        }}
+      />
+      <View>
+        <Text className="font-semibold text-text-primary text-sm">{name}</Text>
+        <Text className="text-text-secondary text-xs">{displayValue}</Text>
+      </View>
+    </View>
+  )
+}
+
+/**
+ * One scale as a labelled row of steps with the hex under each.
+ *
+ * Steps come from the object itself rather than a fixed list, so a scale with
+ * the 11-step OKLCH shape and one with the legacy 10-step shape both render
+ * without the story knowing which it has.
+ */
+export function ScaleRow({
+  name,
+  scale,
+  note,
+}: {
+  name: string
+  scale: Record<string | number, string>
+  note?: string
+}) {
+  return (
+    <View style={{ marginBottom: 14 }}>
+      <Text className="font-semibold text-text-primary text-sm">{name}</Text>
+      {note ? <Text className="text-text-tertiary text-xs mb-1">{note}</Text> : null}
+      <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 4, marginTop: 4 }}>
+        {Object.entries(scale).map(([step, hex]) => (
+          <View key={step} style={{ alignItems: 'center', width: 62 }}>
+            <View
+              style={{
+                width: 62,
+                height: 46,
+                borderRadius: 6,
+                backgroundColor: hex,
+                borderWidth: 1,
+                borderColor: SWATCH_BORDER,
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              <Text style={{ color: bestTextColor(hex), fontSize: 10, fontWeight: '700' }}>
+                {step}
+              </Text>
+            </View>
+            <Text className="text-text-tertiary" style={{ fontSize: 8, marginTop: 2 }}>
+              {hex.toUpperCase()}
+            </Text>
+          </View>
+        ))}
+      </View>
+    </View>
+  )
+}
+
+export function Demo({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <View
+      style={{
+        padding: 10,
+        backgroundColor: semanticColorsDark['surface-raised'],
+        borderRadius: 8,
+      }}
+    >
+      <Text className="text-text-secondary" style={{ fontSize: 9, marginBottom: 6 }}>
+        {label}
+      </Text>
+      {children}
+    </View>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// colour maths — drives the accessibility / CVD panel
+// ---------------------------------------------------------------------------
+
+const hexToRgb = (hex: string): [number, number, number] => {
+  const h = hex.replace('#', '')
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255) as [number, number, number]
+}
+const toHex = (v: number) =>
+  Math.round(Math.min(1, Math.max(0, v)) * 255)
+    .toString(16)
+    .padStart(2, '0')
+const lin = (c: number) => (c >= 0.04045 ? ((c + 0.055) / 1.055) ** 2.4 : c / 12.92)
+const gamma = (c: number) =>
+  c >= 0.0031308 ? 1.055 * Math.max(0, c) ** (1 / 2.4) - 0.055 : 12.92 * c
+
+const relLum = (hex: string) => {
+  const [r, g, b] = hexToRgb(hex).map(lin)
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** WCAG contrast ratio between two solid colours. */
+export function contrast(a: string, b: string): number {
+  const [l1, l2] = [relLum(a), relLum(b)].sort((x, y) => y - x)
+  return (l1 + 0.05) / (l2 + 0.05)
+}
+
+/** Machado-2009 dichromacy simulation matrices, severity 1.0. */
+export const CVD_MATRICES = {
+  deuteranopia: [
+    0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881,
+  ],
+  protanopia: [
+    0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998,
+  ],
+} as const
+
+/** How `hex` appears to a viewer with the dichromacy described by `matrix`. */
+export function simulateCvd(matrix: readonly number[], hex: string): string {
+  const [r, g, b] = hexToRgb(hex).map(lin)
+  const out = [
+    matrix[0] * r + matrix[1] * g + matrix[2] * b,
+    matrix[3] * r + matrix[4] * g + matrix[5] * b,
+    matrix[6] * r + matrix[7] * g + matrix[8] * b,
+  ].map(gamma)
+  return '#' + out.map(toHex).join('')
+}

package/src/theme/color-utils.ts

@@ -0,0 +1,197 @@
+/**
+ * Colour math shared by the depth system.
+ *
+ * This file used to be `shadows.ts` and shipped a neumorphic shadow builder —
+ * dual opposing shadows, dark bottom-right and light top-left. That was removed
+ * in TD-07.16. Neumorphism needs a mid-tone background (roughly 75-90%
+ * lightness) so BOTH shadows have somewhere to fall; our surfaces sit near 10%,
+ * which leaves the dark half nothing to fall onto. It collapsed to a one-sided
+ * rim light and read as noise on the wall.
+ *
+ * Inline depth is a hairline now (`hairline-*`, self-normalising alpha), texture
+ * is `materials.ts`, and drop-shadow survives only for genuinely FLOATING
+ * things — see `elevation.ts`.
+ *
+ * What is left here is the HSV/hex maths that `elevation.ts` still uses to
+ * derive rim and shadow tints from whatever surface colour it is handed.
+ */
+
+// ============================================================================
+// Color Math Utilities
+// ============================================================================
+
+/**
+ * Parse a hex color to RGB values (0-255).
+ * Supports both #RGB and #RRGGBB formats.
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const cleaned = hex.replace('#', '')
+  
+  let r: number, g: number, b: number
+  
+  if (cleaned.length === 3) {
+    r = parseInt(cleaned[0] + cleaned[0], 16)
+    g = parseInt(cleaned[1] + cleaned[1], 16)
+    b = parseInt(cleaned[2] + cleaned[2], 16)
+  } else if (cleaned.length === 6) {
+    r = parseInt(cleaned.slice(0, 2), 16)
+    g = parseInt(cleaned.slice(2, 4), 16)
+    b = parseInt(cleaned.slice(4, 6), 16)
+  } else {
+    return null
+  }
+  
+  return { r, g, b }
+}
+
+/**
+ * Convert RGB (0-255) to HSV (h: 0-360, s: 0-1, v: 0-1).
+ */
+export function rgbToHsv(r: number, g: number, b: number): { h: number; s: number; v: number } {
+  const rNorm = r / 255
+  const gNorm = g / 255
+  const bNorm = b / 255
+  
+  const max = Math.max(rNorm, gNorm, bNorm)
+  const min = Math.min(rNorm, gNorm, bNorm)
+  const delta = max - min
+  
+  // Value
+  const v = max
+  
+  // Saturation
+  const s = max === 0 ? 0 : delta / max
+  
+  // Hue
+  let h = 0
+  if (delta !== 0) {
+    if (max === rNorm) {
+      h = 60 * (((gNorm - bNorm) / delta) % 6)
+    } else if (max === gNorm) {
+      h = 60 * ((bNorm - rNorm) / delta + 2)
+    } else {
+      h = 60 * ((rNorm - gNorm) / delta + 4)
+    }
+  }
+  if (h < 0) h += 360
+  
+  return { h, s, v }
+}
+
+/**
+ * Convert HSV (h: 0-360, s: 0-1, v: 0-1) to RGB (0-255).
+ */
+export function hsvToRgb(h: number, s: number, v: number): { r: number; g: number; b: number } {
+  const c = v * s
+  const x = c * (1 - Math.abs((h / 60) % 2 - 1))
+  const m = v - c
+  
+  let rPrime: number, gPrime: number, bPrime: number
+
+  if (h >= 0 && h < 60) {
+    rPrime = c; gPrime = x; bPrime = 0
+  } else if (h >= 60 && h < 120) {
+    rPrime = x; gPrime = c; bPrime = 0
+  } else if (h >= 120 && h < 180) {
+    rPrime = 0; gPrime = c; bPrime = x
+  } else if (h >= 180 && h < 240) {
+    rPrime = 0; gPrime = x; bPrime = c
+  } else if (h >= 240 && h < 300) {
+    rPrime = x; gPrime = 0; bPrime = c
+  } else {
+    rPrime = c; gPrime = 0; bPrime = x
+  }
+  
+  return {
+    r: Math.round((rPrime + m) * 255),
+    g: Math.round((gPrime + m) * 255),
+    b: Math.round((bPrime + m) * 255),
+  }
+}
+
+/**
+ * Convert RGB values to hex string.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) => {
+    const clamped = Math.max(0, Math.min(255, Math.round(n)))
+    return clamped.toString(16).padStart(2, '0')
+  }
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+/**
+ * Lighten a color by increasing its HSV Value component.
+ * 
+ * @param hex - The hex color to lighten
+ * @param amount - Amount to increase V by (0-1)
+ */
+export function lighten(hex: string, amount: number = 0.1): string {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return hex
+  
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  const newV = Math.min(1, hsv.v + amount)
+  
+  const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
+  return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
+}
+
+/**
+ * Darken a color by decreasing its HSV Value component.
+ * 
+ * @param hex - The hex color to darken
+ * @param amount - Amount to decrease V by (0-1)
+ */
+export function darken(hex: string, amount: number = 0.1): string {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return hex
+  
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  const newV = Math.max(0, hsv.v - amount)
+  
+  const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
+  return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
+}
+
+/**
+ * Get hover colors for a button based on its background color.
+ * Automatically adapts intensity based on the color's luminance.
+ * 
+ * @param bgColor - The button's background color (hex)
+ * @param intensity - How strong the hover effect should be ('subtle' | 'medium' | 'strong')
+ */
+export function getHoverColors(
+  bgColor: string, 
+  intensity: 'subtle' | 'medium' | 'strong' = 'medium'
+): { raised: string; pressed: string } {
+  const amounts = {
+    subtle: 0.01,
+    medium: 0.02,
+    strong: 0.03,
+  }
+  
+  const amount = amounts[intensity]
+  
+  return {
+    raised: lighten(bgColor, amount),  // Raised hover: lighten (lifting up)
+    pressed: darken(bgColor, amount),  // Pressed hover: darken (pressing down)
+  }
+}
+
+/**
+ * Check if a color is considered "dark" (for choosing text color).
+ * Uses HSV Value component for simplicity.
+ */
+export function isDark(hex: string): boolean {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return true
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  return hsv.v < 0.6
+}
+
+/**
+ * Shadow strength tiers. Retained because `elevation.ts` keys its level table on
+ * them; the neumorphic shadow BUILDERS that used to live here are gone.
+ */
+export type ShadowIntensity = 'subtle' | 'medium' | 'strong'

package/src/theme/config.ts

@@ -77,16 +77,12 @@ export const lightThemeCSSVars = {
   '--color-surface-base': semanticColorsLight['surface-base'],
   '--color-surface-elevated': semanticColorsLight['surface-elevated'],
   '--color-surface-raised': semanticColorsLight['surface-raised'],
-  '--color-surface-inset': semanticColorsLight['surface-inset'],
 
   '--color-background-base': semanticColorsLight['background-base'],
   '--color-background-default': semanticColorsLight['background-default'],
   '--color-background-subtle': semanticColorsLight['background-subtle'],
   '--color-background-frame': semanticColorsLight['background-frame'],
 
-  '--color-border-default': semanticColorsLight['border-default'],
-  '--color-border-subtle': semanticColorsLight['border-subtle'],
-  '--color-border-strong': semanticColorsLight['border-strong'],
   '--color-border-prominent': semanticColorsLight['border-prominent'],
   '--color-border-focus': semanticColorsLight['border-focus'],
 
@@ -204,16 +200,12 @@ export const darkThemeCSSVars = {
   '--color-surface-base': semanticColorsDark['surface-base'],
   '--color-surface-elevated': semanticColorsDark['surface-elevated'],
   '--color-surface-raised': semanticColorsDark['surface-raised'],
-  '--color-surface-inset': semanticColorsDark['surface-inset'],
 
   '--color-background-base': semanticColorsDark['background-base'],
   '--color-background-default': semanticColorsDark['background-default'],
   '--color-background-subtle': semanticColorsDark['background-subtle'],
   '--color-background-frame': semanticColorsDark['background-frame'],
 
-  '--color-border-default': semanticColorsDark['border-default'],
-  '--color-border-subtle': semanticColorsDark['border-subtle'],
-  '--color-border-strong': semanticColorsDark['border-strong'],
   '--color-border-prominent': semanticColorsDark['border-prominent'],
   '--color-border-focus': semanticColorsDark['border-focus'],
 

package/src/theme/depth-calibration.test.tsx

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { composeStories } from '@storybook/react'
+import * as stories from './DepthCalibration.stories'
+
+/**
+ * The calibration rig is the gate on a release tag, and its whole value rests on
+ * one property: the answer key is NOT on screen until the operator asks for it.
+ * A leaked key does not make the panels look broken — it makes them look fine,
+ * and silently converts a measurement into a confirmation.
+ *
+ * The theme stories are outside `stories-smoke.test.tsx`'s
+ * `../components/**` glob, so this file also carries the render smoke for them.
+ */
+const { Hairlines, ToneSteps, PaperMaterial, Banding } = composeStories(stories)
+const ALL = { Hairlines, ToneSteps, PaperMaterial, Banding }
+
+describe('depth calibration rig', () => {
+  for (const [name, Story] of Object.entries(ALL)) {
+    it(`${name} renders`, () => {
+      const result = render(<Story />)
+      expect(result.container.firstChild).toBeTruthy()
+      result.unmount()
+    })
+  }
+
+  it('hides every answer until Reveal is pressed, then shows them', () => {
+    render(<Hairlines />)
+
+    // grey-975 is the ground of row 1; naming a ground names an answer.
+    expect(screen.queryByText(/grey-975/)).toBeNull()
+    expect(screen.queryByText(/decoy/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+
+    expect(screen.getAllByText(/grey-975/).length).toBeGreaterThan(0)
+    expect(screen.getAllByText(/decoy/).length).toBe(4)
+  })
+
+  it('seeds exactly four blank cells across four distinct grounds', () => {
+    render(<Hairlines />)
+    fireEvent.click(screen.getByText('Reveal key'))
+
+    // One decoy per row, so no row can be answered by "the blank one is here again".
+    const decoys = screen.getAllByText(/NONE \(decoy\)/)
+    expect(decoys).toHaveLength(4)
+
+    const rows = decoys.map((n) => n.textContent?.match(/^[A-D](\d)/)?.[1])
+    expect(new Set(rows).size).toBe(4)
+  })
+
+  it('seeds an identical pair among the paper sheets', () => {
+    render(<PaperMaterial />)
+    expect(screen.queryByText(/FLAT \(decoy\)/)).toBeNull()
+
+    // Two byte-identical flats, so "all three look the same" stays an available
+    // answer rather than an admission — the material has to be picked OUT.
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/FLAT \(decoy\)/)).toHaveLength(2)
+  })
+
+  it('pairs the smooth banding control with a hand-quantised reference', () => {
+    // Run 1 was VOID because nothing could band. Run 2 then found the smooth
+    // control ALSO reading clean, which is ambiguous: a blind panel and a render
+    // path that simply does not band both look like "no steps". The hard-edged
+    // reference disambiguates them, so the panel needs BOTH gradients — and
+    // neither may be one of the shipped-material fields.
+    const { container } = render(<Banding />)
+    expect(container.querySelectorAll('[style*="linear-gradient"]')).toHaveLength(2)
+  })
+
+  it('labels the control and the reference distinctly, and only on reveal', () => {
+    render(<Banding />)
+    expect(screen.queryByText(/CONTROL/)).toBeNull()
+    expect(screen.queryByText(/REFERENCE/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/CONTROL/)).toHaveLength(1)
+    expect(screen.getAllByText(/REFERENCE/)).toHaveLength(1)
+  })
+
+  it('seeds a no-floor-line decoy among the inset wells', () => {
+    render(<PaperMaterial />)
+    expect(screen.queryByText(/NONE \(decoy\)/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/NONE \(decoy\)/)).toHaveLength(1)
+  })
+
+  it('seeds an identical pair among the tone-step pairs', () => {
+    render(<ToneSteps />)
+    expect(screen.queryByText(/SAME \(decoy\)/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/SAME \(decoy\)/)).toHaveLength(1)
+  })
+})