@titan-design/react-ui 0.10.0 → 0.11.0

package/src/theme/ColorPrimitives.stories.tsx

@@ -0,0 +1,300 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import {
+  primitiveColors,
+  primitiveRamps,
+  surfaceRampDark,
+  backgroundFrameDark,
+  categoricalPalette,
+  CATEGORICAL_CVD_SAFE_MAX,
+} from './tokens/primitives'
+import {
+  SWATCH_BORDER,
+  SectionIntro,
+  SectionTitle,
+  ScaleRow,
+  contrast,
+  CVD_MATRICES,
+  simulateCvd,
+} from './color-story-kit'
+
+/**
+ * Foundations/Color/Primitives — the raw material, and how it is validated.
+ *
+ * This half holds the scales themselves and nothing about what they mean. The
+ * organisations OF these scales — surfaces, categorical, status, brand,
+ * fatigue and the rest — live in the sibling `Foundations/Color/Palettes`.
+ *
+ * This page is a MENU: everything on it is something you may legitimately
+ * reach for today and that survives the migration ahead. The older
+ * `primitiveColors` scales — `charcoal`, `neutral`, `redVivid`, and the support
+ * `blue`/`red` — are deliberately NOT rendered here even though they still have
+ * call sites in `semantic.ts`, because TD-07.14 deletes them. A swatch on a
+ * menu is an invitation, and no annotation is loud enough to cancel that; the
+ * intro carries a one-line pointer instead, so a reader who comes looking for
+ * charcoal learns where it went rather than assuming an oversight.
+ *
+ * The semantic tokens those scales currently back are still documented, with
+ * swatches, in `Foundations/Color/Palettes` — which is what the coverage guard
+ * checks, and why removing the scale rows here costs no coverage.
+ */
+const meta: Meta = {
+  title: 'Foundations/Color/Primitives',
+  tags: ['autodocs'],
+}
+
+export default meta
+
+// ============================================================================
+// 1. Ramps
+// ============================================================================
+
+const CHROMATIC_RAMPS: Array<[keyof typeof primitiveRamps, string]> = [
+  ['red', 'Red'],
+  ['orange', 'Orange'],
+  ['amber', 'Amber'],
+  ['green', 'Green'],
+  ['cyan', 'Cyan'],
+  ['blue', 'Blue'],
+  ['magenta', 'Magenta'],
+]
+
+const KEYWORDS = [
+  { name: 'white', value: primitiveColors.white },
+  { name: 'black', value: primitiveColors.black },
+] as const
+
+/**
+ * The dark surface planes, darkest first — the greys you may actually pick.
+ *
+ * Shown here as a ramp (values only) because a menu of raw scales with no greys
+ * on it would be a lie. The depth semantics, the L* spacing rationale and the
+ * per-plane semantic aliases live in the full `Foundations/Color/Palettes`
+ * surface story, and are deliberately not duplicated.
+ */
+const SURFACE_STEPS: Record<string, string> = {
+  frame: backgroundFrameDark,
+  inset: surfaceRampDark.inset,
+  background: surfaceRampDark.background,
+  base: surfaceRampDark.base,
+  elevated: surfaceRampDark.elevated,
+  raised: surfaceRampDark.raised,
+  overlay: surfaceRampDark.overlay,
+}
+
+export const Ramps: StoryObj = {
+  name: '1. Ramps — Source of Truth',
+  render: () => (
+    <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.
+      </SectionIntro>
+
+      <Text className="text-text-tertiary text-xs mb-6">
+        Looking for <Text className="font-semibold">charcoal</Text>,{' '}
+        <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? They are intentionally not shown — all
+        five retire into a unified warm grey ramp plus the OKLCH ramps under TD-07.14. They still
+        have call sites in `semantic.ts`, so the semantic tokens they back are real and documented
+        in Palettes; the raw scales are not on the menu because you should not be picking from
+        them. Spec: coordination/design-explorations/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.
+      </Text>
+      {CHROMATIC_RAMPS.map(([key, name]) => (
+        <ScaleRow key={key} name={name} scale={primitiveRamps[key]} />
+      ))}
+
+      <SectionTitle>Achromatic — the dark surface ramp</SectionTitle>
+      <Text className="text-text-secondary text-xs mb-4">
+        The greys. A derived depth ladder rather than a generated hue ramp — spaced by perceptual
+        lightness so one step is the same visual distance anywhere in the stack. Shown here as
+        values; the depth semantics and the semantic tokens aliasing each plane are in the
+        Palettes surface story, and are not repeated. Apply them with{' '}
+        <Text className="font-semibold">&lt;Surface level&gt;</Text>, not by reading a step.
+      </Text>
+      <ScaleRow name="Surface (dark)" scale={SURFACE_STEPS} />
+
+      <SectionTitle>Keywords</SectionTitle>
+      <Text className="text-text-secondary text-xs mb-4">
+        Absolute values with no scale. `transparent` is the third and encodes absence — it has no
+        swatch because there is nothing to show.
+      </Text>
+      <View style={{ flexDirection: 'row', gap: 12 }}>
+        {KEYWORDS.map(({ name, value }) => (
+          <View key={name} style={{ alignItems: 'center' }}>
+            <View
+              style={{
+                width: 62,
+                height: 46,
+                borderRadius: 6,
+                backgroundColor: value,
+                borderWidth: 1,
+                borderColor: SWATCH_BORDER,
+              }}
+            />
+            <Text className="text-text-secondary text-xs mt-1">{name}</Text>
+            <Text className="text-text-tertiary" style={{ fontSize: 8 }}>
+              {value.toUpperCase()}
+            </Text>
+          </View>
+        ))}
+      </View>
+    </View>
+  ),
+}
+
+// ============================================================================
+// 2. Accessibility — contrast + CVD
+// ============================================================================
+
+/** The mid-step of each chromatic ramp — the band most fills and strokes land on. */
+const RAMP_MIDS = CHROMATIC_RAMPS.map(([key, name]) => ({
+  name,
+  hex: primitiveRamps[key][500],
+}))
+
+/**
+ * Width of the mode-label gutter. The swatch rows are indented by the same
+ * amount so each simulation strip sits directly under the colour it simulates —
+ * the comparison is worthless if the reader has to count across to pair them.
+ */
+const CVD_LABEL_WIDTH = 96
+
+function CvdStrips({ colors, width }: { colors: readonly string[]; width: number }) {
+  return (
+    <>
+      {(['deuteranopia', 'protanopia'] as const).map((mode) => (
+        <View key={mode} style={{ flexDirection: 'row', alignItems: 'center', marginTop: 3 }}>
+          <Text className="text-text-secondary" style={{ fontSize: 9, width: CVD_LABEL_WIDTH }}>
+            {mode}
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 6 }}>
+            {colors.map((hex, i) => (
+              <View
+                key={i}
+                style={{
+                  width,
+                  height: 14,
+                  borderRadius: 3,
+                  backgroundColor: simulateCvd(CVD_MATRICES[mode], hex),
+                }}
+              />
+            ))}
+          </View>
+        </View>
+      ))}
+    </>
+  )
+}
+
+export const Accessibility: StoryObj = {
+  name: '2. Accessibility — Contrast + CVD',
+  render: () => (
+    <View style={{ padding: 24 }}>
+      <Text className="text-2xl font-bold text-text-primary mb-2">Accessibility</Text>
+      <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.
+      </SectionIntro>
+
+      <SectionTitle>Ramp mid-steps (500)</SectionTitle>
+      <Text className="text-text-secondary text-xs mb-3">
+        The seven hues at the step most fills land on. Red/orange/amber and green/cyan compress
+        toward each other under both dichromacies — which is exactly why the categorical palette
+        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 }}
+      >
+        {RAMP_MIDS.map(({ name, hex }) => (
+          <View key={name} style={{ alignItems: 'center' }}>
+            <View
+              style={{
+                width: 76,
+                height: 40,
+                borderRadius: 6,
+                backgroundColor: hex,
+                borderWidth: 1,
+                borderColor: SWATCH_BORDER,
+              }}
+            />
+            <Text className="text-text-secondary" style={{ fontSize: 9, marginTop: 2 }}>
+              {name}
+            </Text>
+          </View>
+        ))}
+      </View>
+      <CvdStrips colors={RAMP_MIDS.map((r) => r.hex)} width={76} />
+
+      <View style={{ height: 28 }} />
+
+      <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.
+      </Text>
+      {(['default', 'dark'] as const).map((variant) => {
+        const colors = categoricalPalette[variant]
+        const textColor = variant === 'dark' ? primitiveColors.white : primitiveColors.black
+        return (
+          <View key={variant} style={{ marginBottom: 22 }}>
+            <Text
+              className="font-semibold text-text-primary text-sm mb-2"
+              style={{ textTransform: 'capitalize' }}
+            >
+              {variant}
+            </Text>
+            <View
+              style={{
+                flexDirection: 'row',
+                gap: 6,
+                marginBottom: 6,
+                paddingLeft: CVD_LABEL_WIDTH,
+              }}
+            >
+              {colors.map((hex, i) => (
+                <View key={i} style={{ alignItems: 'center' }}>
+                  <View
+                    style={{
+                      width: 56,
+                      height: 40,
+                      borderRadius: 6,
+                      backgroundColor: hex,
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                    }}
+                  >
+                    <Text style={{ color: textColor, fontSize: 11, fontWeight: '700' }}>Aa</Text>
+                  </View>
+                  <Text className="text-text-secondary" style={{ fontSize: 8, marginTop: 2 }}>
+                    {contrast(hex, textColor).toFixed(1)}:1
+                  </Text>
+                </View>
+              ))}
+            </View>
+            <CvdStrips colors={colors} width={56} />
+          </View>
+        )
+      })}
+    </View>
+  ),
+}

package/src/theme/bar-paper.ts

@@ -0,0 +1,59 @@
+// The matte "paper" treatment for a colored bar — a brightness-scaled fractal-noise
+// grain + a crisp top rim-light + a soft contact shadow, so filled bars read as one
+// tactile material across the system (velocity bars, ROM bars, …). Web-only CSS
+// (backgroundImage + boxShadow) — harmless on native (ignored), styled for RNW/web.
+//
+// Promoted out of VelocityStrip so every colored-bar family composes ONE treatment
+// instead of re-rolling it. Consumers spread it onto a bar's style: `...barPaper(hex)`.
+import type { ViewStyle } from 'react-native'
+
+/**
+ * Grain opacity scaled by a color's perceived brightness: a bright bar keeps full
+ * texture, a darker bar carries proportionally less so the grain never reads hot on a
+ * dark tone. Anchored so lum ≈ 0.13 → ≈ 0.06 and lum ≈ 0.58 → ≈ 0.20.
+ */
+function grainOpacityForColor(hex: string): number {
+  const h = hex.replace('#', '')
+  const full =
+    h.length === 3
+      ? h
+          .split('')
+          .map((ch) => ch + ch)
+          .join('')
+      : h
+  const r = parseInt(full.slice(0, 2), 16)
+  const g = parseInt(full.slice(2, 4), 16)
+  const b = parseInt(full.slice(4, 6), 16)
+  if ([r, g, b].some(Number.isNaN)) return 0.14
+  const lum = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+  return Math.min(0.24, Math.max(0.04, 0.02 + 0.31 * lum))
+}
+
+/** The matte paper grain tile (fractalNoise), opacity brightness-scaled to `color`. */
+function barGrain(color: string): string {
+  const op = grainOpacityForColor(color).toFixed(3)
+  return (
+    `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E` +
+    `%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E` +
+    `%3Crect width='120' height='120' filter='url(%23n)' opacity='${op}'/%3E%3C/svg%3E")`
+  )
+}
+
+/**
+ * Paper/raised treatment for a colored bar of the given `color`: brightness-scaled
+ * matte grain + a crisp top rim-light + a defined contact shadow. Spread onto a bar's
+ * style. Presentation-only; scoped to filled bars (not shared strips/dividers).
+ *
+ * `flip` = a vertically-mirrored (`scaleY(-1)`) plot — a `down` wing of the diverging
+ * chart. The contact shadow's y-offset is pre-inverted so the mirror lands it pointing
+ * AWAY from the shared axis (not up across it), and the top rim-light is DROPPED (mirrored
+ * it would sit on the axis edge and read wrong; grain + shadow alone carry the material).
+ */
+export function barPaper(color: string, flip = false): ViewStyle {
+  return {
+    backgroundImage: barGrain(color),
+    boxShadow: flip
+      ? '0 -6px 16px rgba(0,0,0,0.45)'
+      : 'inset 0 1.5px 0 rgba(255,255,255,0.22), 0 6px 16px rgba(0,0,0,0.45)',
+  } as unknown as ViewStyle
+}

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

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { surfaceRampDark, backgroundFrameDark } 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-inset`, `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(surfaceRampDark), backgroundFrameDark])
+
+/**
+ * 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 a step of surfaceRampDark ' +
+        '(or the backgroundFrameDark bezel). 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', () => {
+    // SURFACE_PLANES is built from the ramp exports, so covering the exports
+    // is what proves no plane is missing from the rendered ladder.
+    const referenced = [
+      'surfaceRampDark.inset',
+      'surfaceRampDark.background',
+      'surfaceRampDark.base',
+      'surfaceRampDark.elevated',
+      'surfaceRampDark.raised',
+      'surfaceRampDark.overlay',
+      'backgroundFrameDark',
+    ]
+    const missing = referenced.filter((ref) => !storySources.includes(ref))
+
+    expect(missing, 'ramp planes absent from the SURFACE_PLANES ladder').toEqual([])
+    // Guard the count too: a step added to the ramp must gain a row.
+    expect(Object.keys(surfaceRampDark)).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['border-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('')
+}