pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/theme/platform/highlight.native.js

@@ -0,0 +1,59 @@
+"use strict";
+
+const LIGHT = {
+  subtle: 'rgba(255,255,255,0.05)',
+  raised: 'rgba(255,255,255,0.85)'
+};
+const DARK = {
+  subtle: 'rgba(255,255,255,0.10)',
+  raised: 'rgba(255,255,255,1.0)'
+};
+function layerKey(layer) {
+  return [layer.offsetX, layer.offsetY, layer.blurRadius ?? 0, layer.spreadDistance ?? 0, layer.inset ? 1 : 0, layer.color ?? ''].join('|');
+}
+function dedupeLayers(layers) {
+  const seen = new Set();
+  const out = [];
+  for (const layer of layers) {
+    const key = layerKey(layer);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(layer);
+  }
+  return out;
+}
+export function highlightLevels(level, mode) {
+  return highlight(level, mode);
+}
+export function highlight(level, mode) {
+  if (level === 'none') return [];
+  const palette = mode === 'dark' ? DARK : LIGHT;
+  const color = palette[level];
+  if (level === 'subtle') {
+    return [{
+      offsetX: 0,
+      offsetY: 1,
+      blurRadius: 0,
+      spreadDistance: 0,
+      inset: true,
+      color
+    }];
+  }
+  return [{
+    offsetX: 0,
+    offsetY: 1,
+    blurRadius: 1,
+    spreadDistance: 0,
+    inset: true,
+    color
+  }];
+}
+export function composeBoxShadow(outset, inset) {
+  return dedupeLayers([...outset, ...inset]);
+}
+export function asBoxShadowArray(value) {
+  if (value === undefined) return [];
+  if (typeof value === 'string') return [];
+  return value;
+}
+//# sourceMappingURL=highlight.native.js.map

package/lib/module/theme/platform/index.js

@@ -9,6 +9,11 @@
  */
 export { rem, hairline } from "./units.native.js";
 export { elevation } from "./elevation.native.js";
+export { highlight, highlightLevels, composeBoxShadow } from "./highlight.native.js";
+export { elevatedSurfaces } from "./surfaces.native.js";
+export { STATE_LAYER_OPACITY, rippleColor, stateLayerScrim } from "./stateLayer.native.js";
+export { floatingBackground, floatingSurfaceStyle } from "./floatingSurface.native.js";
+export { springs } from "./motion.native.js";
 export { interFontFamilies, systemFontFamily, fontStyleForWeight } from "./fonts.native.js";
 export { getSystemColorMode, subscribeToSystemColorMode } from "./colorScheme.native.js";
 //# sourceMappingURL=index.js.map

package/lib/module/theme/platform/motion.native.js

@@ -1,15 +1,35 @@
 "use strict";
 
-export const motionDurations = {
-  instant: 0,
-  fast: 150,
-  normal: 200,
-  slow: 300
-};
-export const motionEasings = {
-  standard: 'ease-in-out',
-  enter: 'ease-out',
-  exit: 'ease-in',
-  snap: 'linear'
+export const springs = {
+  spatialFast: {
+    stiffness: 800,
+    damping: 33.94,
+    mass: 1
+  },
+  spatialDefault: {
+    stiffness: 380,
+    damping: 31.19,
+    mass: 1
+  },
+  spatialSlow: {
+    stiffness: 200,
+    damping: 22.63,
+    mass: 1
+  },
+  effectsFast: {
+    stiffness: 3800,
+    damping: 123.29,
+    mass: 1
+  },
+  effectsDefault: {
+    stiffness: 1600,
+    damping: 80.0,
+    mass: 1
+  },
+  effectsSlow: {
+    stiffness: 800,
+    damping: 56.57,
+    mass: 1
+  }
 };
 //# sourceMappingURL=motion.native.js.map

package/lib/module/theme/platform/stateLayer.native.js

@@ -0,0 +1,14 @@
+"use strict";
+
+export const STATE_LAYER_OPACITY = {
+  pressed: 0.1,
+  focus: 0.1,
+  hover: 0.08,
+  dragged: 0.16,
+  disabled: 0.38
+};
+export function stateLayerScrim(mode) {
+  return mode === 'dark' ? '#ffffff' : '#000000';
+}
+export const rippleColor = mode => mode === 'dark' ? 'rgba(255,255,255,0.12)' : 'rgba(0,0,0,0.10)';
+//# sourceMappingURL=stateLayer.native.js.map

package/lib/module/theme/platform/surfaces.native.js

@@ -0,0 +1,11 @@
+"use strict";
+
+export function elevatedSurfaces(palette, mode) {
+  if (mode === 'light') return null;
+  return {
+    elevated1: palette.background[100],
+    elevated2: palette.background[200],
+    elevated3: palette.background[300]
+  };
+}
+//# sourceMappingURL=surfaces.native.js.map

package/lib/module/theme/provider/PixelizeProvider.js

@@ -1,8 +1,9 @@
 "use strict";
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, roleColors } from "../tokens/index.js";
-import { elevation as renderElevation, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
+import { HapticsContext, hasHapticsModule } from "../../core/haptics/index.js";
+import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, roleColors, assertPalette } from "../tokens/index.js";
+import { elevation as renderElevation, elevatedSurfaces, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
 import { DEFAULT_BRAND_STORAGE_NAMESPACE, DEFAULT_STORAGE_NAMESPACE, isThemeMode, isThemeName, memoryStorageAdapter } from "./colorModeStorage.js";
 import { DEFAULT_THEME, loadPaletteSync } from "./loadPalette.js";
 import { ThemeContext, ThemeModeContext } from "./ThemeContext.js";
@@ -16,11 +17,12 @@ const RENDERED_ELEVATION = {
   lg: renderElevation(elevationTokens.lg)
 };
 function buildTheme(brand, mode, interLoaded, paletteOverride) {
-  const palette = paletteOverride ?? loadPaletteSync(brand, mode);
+  const palette = paletteOverride ? assertPalette(paletteOverride, "the `palette` prop") : loadPaletteSync(brand, mode);
   return {
     brand,
     mode,
     colors: roleColors(palette),
+    elevatedSurfaces: elevatedSurfaces(palette, mode),
     palette,
     space,
     radii,
@@ -43,7 +45,8 @@ export function PixelizeProvider({
   storageKey = DEFAULT_STORAGE_NAMESPACE,
   brandStorageKey = DEFAULT_BRAND_STORAGE_NAMESPACE,
   interLoaded = false,
-  palette: paletteProp
+  palette: paletteProp,
+  haptics: hapticsProp
 }) {
   const storage = storageProp ?? memoryStorageAdapter;
   const [modeState, setModeState] = useState(mode);
@@ -61,6 +64,12 @@ export function PixelizeProvider({
     if (typeof __DEV__ !== 'undefined' && !__DEV__) return;
     console.warn('[pixelize-native-library] <PixelizeProvider> has no `storage` adapter, so the theme choice is ' + 'kept in memory and lost on app restart. Pass ' + 'storage={createAsyncStorageAdapter(AsyncStorage)} to persist it.');
   }, [storageProp]);
+  useEffect(() => {
+    if (interLoaded) return;
+    if (process.env.JEST_WORKER_ID !== undefined) return;
+    if (typeof __DEV__ === 'undefined' || !__DEV__) return;
+    console.warn('[pixelize-native-library] Inter is not loaded — register the faces with expo-font and pass ' + 'interLoaded to <PixelizeProvider>. See README.md#typography.');
+  }, [interLoaded]);
   useEffect(() => {
     let cancelled = false;
     Promise.resolve(storage.getItem(storageKey)).then(raw => {
@@ -100,11 +109,15 @@ export function PixelizeProvider({
     brand: brandState,
     setBrand
   }), [modeState, resolvedMode, setMode, brandState, setBrand]);
+  const hapticsEnabled = hapticsProp ?? hasHapticsModule();
   return /*#__PURE__*/_jsx(ThemeContext.Provider, {
     value: theme,
     children: /*#__PURE__*/_jsx(ThemeModeContext.Provider, {
       value: modeValue,
-      children: children
+      children: /*#__PURE__*/_jsx(HapticsContext.Provider, {
+        value: hapticsEnabled,
+        children: children
+      })
     })
   });
 }

package/lib/module/theme/tokens/MODULE.md

@@ -1,8 +1,13 @@
-# tokens/ — the copy-paste zone
+# tokens/ — the portable core
 
-The portable core of the design system, **byte-identical with web's `src/Theme/tokens/`** and
-hash-gated by `.tokens.sha256`. The folder layout mirrors web exactly, so the gate can compare
-like-for-like: `types.ts`, `index.ts`, `primitives/`, `brands/`, `builders/`, `roles/`.
+Platform-neutral data and pure functions: `types.ts`, `index.ts`, `primitives/`, `brands/`,
+`builders/`, `roles/`. Web's `src/Theme/tokens/` is the sibling this folder was seeded from and
+still tracks in shape and naming, but the two are **not** byte-identical and no gate requires them
+to be: mobile owns `roles/`, `assertPalette.ts` and its own `PaletteProps`, and web owns sidebar
+tokens mobile has no rail for.
+
+**[THEME-CONTRACT.md](./THEME-CONTRACT.md) is the source of truth** for required vs derived tokens,
+which token to pick by role, and why nothing may write `palette.x?.y ?? z`.
 
 ## Purity contract (lint + `__tests__/purity.test.ts` enforce it)
 
@@ -15,46 +20,49 @@ Nothing under `tokens/` may contain:
 The one subtlety a hex is allowed: `#rrggbb` / `#rrggbbaa` are values, not units — they parse the
 same on web and RN, so translucency uses 8-digit hex.
 
-**Never edit `tokens/` to fix a mobile problem.** If a token is wrong it is wrong on web too — fix
-it on web and re-copy. (Known live example: `brands/slate/palette.light.ts` `table.hover[500]`
-carries a Cyrillic homoglyph copied verbatim from web; it is fixed upstream, not here. No builder
-reads it, so no palette is affected.)
+**A token that is wrong here is fixed here.** Web is a sibling, not an upstream — the drift gate is
+per-repo by design and never reads the other repo. Flag the same defect for web; do not wait for it.
+`builders/gradientInk.ts` + `__tests__/gradientInk.test.ts` / `gradientTone.test.ts` gate gradient-button
+ink on every brand × mode. `paletteFromAccent()` builds a full `PaletteProps` from a hex accent.
+`primitives/controlSizes.ts` centralises mobile control heights (44/52/56dp).
+
+`brands/slate/palette.light.ts` `table.hover[500]` carried a Cyrillic homoglyph (`"#dfdfе2"`,
+U+0435) on both sides for an unknown period; mobile's copy was fixed 2026-08-31, web's still ships it.
 
-**2026-07-18 — `zinc` dark primary corrected to shadcn's real value.** `PRIMARY_500` in
-`brands/zinc/palette.dark.ts` was `#fafafa` (an approximated "near-white"); verified against
-shadcn's live zinc theme registry and corrected to `#e4e4e7` — shadcn's actual dark `--primary`
-(`#fafafa` is shadcn's `--foreground`, a different token). `gradient.from` now references the
-`PRIMARY_500` constant instead of duplicating the literal, so it can't drift again. Both light
-mode's primary (`#18181b`, already an exact match) and every other zinc role were checked against
-the same registry and left unchanged — see `micro-components/.cursor/modules/theme/MODULE.md` for
-the full verification notes (web is the source of truth for token values).
+`zinc`'s dark `PRIMARY_500` is `#e4e4e7`, shadcn's real dark `--primary`, verified against its live
+theme registry (2026-07-18). `#fafafa` is shadcn's `--foreground` — a different token; do not
+"correct" it back.
 
 ## Brand roster
 
 `brands/` ships 9 identities: `zinc` (mobile-only default, the shadcn look), plus 8 mirroring web —
 `lavender`, `meadow`, `radiant`, `skyline`, `slate`, `emerald`, `rosewood`, `storefront`. Each is a
-`palette.light.ts` (usually `...basePalette` spread + brand overrides — see `emerald`/`storefront` for
-the pattern) and a `palette.dark.ts` (`buildDarkPalette(light)`, no bespoke override unless the brand
-needs one like `zinc`). Add a brand by dropping in both files and registering it in `brands/index.ts`
-+ the `ThemeName` union in `types.ts` — the `it.each(themeNames)` test sweeps pick it up automatically.
+`palette.light.ts` exporting a `BrandPaletteSource` as `source` (usually `...lavenderSource` +
+brand overrides — see `emerald`/`storefront`) and default-exporting `finalizePalette(source)`, plus a
+`palette.dark.ts` (`buildDarkPalette(light)`, no bespoke override unless the brand needs one like
+`zinc`). Add a brand by dropping in both files and registering it in `brands/index.ts`,
+`provider/loadPalette.ts` and the `ThemeName` union — the `it.each(themeNames)` sweeps pick it up.
 
 ## Copied vs not
 
-| Path | Copied to/from web? |
-|------|---------------------|
-| `tokens/**` (this folder) | **Yes** — the hash gate keeps it identical |
+| Path | Shared with web? |
+|------|------------------|
+| `tokens/**` (this folder) | **In shape and intent** — reconcile deliberately, never assume identical |
 | `platform/**` | **Never** — one file per platform, identical export *names*, RN implementations |
 
 `platform/` is where numbers become styles: DP conversion, `StyleSheet.hairlineWidth`, and the
 iOS/Android shadow split. A component imports resolved values from the theme, never from `tokens/`
 math directly.
 
-## The `.tokens.sha256` gate
+## Gates over this folder
 
-CI hashes the contents of `tokens/` and compares against `.tokens.sha256`. A mismatch means web and
-mobile diverged: either an intended change was made on one side (re-copy + regenerate the hash) or an
-accidental edit slipped in (revert it). Because the gate hashes the whole subtree, the **folder shape
-must match web** — a differently-named folder (an old `scale/` or `color/`) can never go green.
+- `__tests__/paletteContrast.test.ts` — 9 brands x 2 modes, 138 assertions: every derived token's
+  contrast guarantee, every colour value parses, no brand file hand-writes a derived token.
+- `roles/__tests__/roleColors.test.ts` — the same sweep one layer up, over `roleColors()`.
+- `__tests__/purity.test.ts` — no unit, CSS string or `platform/` import.
+- `scripts/gates/token-drift.sh` hashes this folder against its **own** committed baseline. That
+  baseline does not exist yet and `pre-pr-check.sh` does not run it, so today it gates nothing —
+  run it with `--update` once, deliberately, if you want it live.
 
 ## RN unit traps baked into the primitives
 

package/lib/module/theme/tokens/THEME-CONTRACT.md

@@ -0,0 +1,187 @@
+# Theme token contract
+
+How colour enters this library, and why nothing may guard a token with `?.` / `??`.
+Read this before adding a token, a brand, or a component that reads a palette.
+
+## The two palette types
+
+| Type | Who writes it | Contains |
+| --- | --- | --- |
+| `BrandPaletteSource` | a brand's `palette.light.ts`, by hand | every hand-authored token, all **required** |
+| `PaletteProps` | `finalizePalette`, at module load | the source **plus** every derived token |
+
+Each `palette.light.ts` annotates `export const source: BrandPaletteSource = { … }` and
+default-exports `finalizePalette(source)`. A missing token is a compile error **in that brand's
+file**. Consumers only ever see `PaletteProps`, where nothing is optional.
+
+Seven brands build on lavender by spreading its `source`, not its finalized default — a brand must
+never inherit another brand's *derived* values.
+
+## Derived tokens — never hand-written
+
+| Token | Derived by | Guarantee |
+| --- | --- | --- |
+| `semanticText.{success,error,warning,info}` | `buildSemanticText` | each status tone as ink, ≥4.5:1 on that palette's canvas |
+| `placeholder[500]` | `finalizePalette` | placeholder ink, ≥4.5:1 on `background[50]` |
+| `table.hover[500]` | `finalizePalette` | hover row steps ≥4.5:1 away from `text[500]` |
+
+Light finalizes in each brand's own file; dark finalizes inside `buildDarkPalette`. `zinc` pins its
+own dark canvas, so `palette.dark.ts` re-finalizes after the override — otherwise its derived tokens
+would be resolved against the canvas it replaced. A hand-copied hex goes stale the moment a canvas
+moves; that is the whole reason these are computed.
+
+`liftToContrast(hex, backdrop, target)` takes no colour-mode argument. It reads the direction from
+the backdrop's own luminance, so "step away from what it sits on" is one rule for both modes and for
+both directions — ink moving off a surface, and a surface moving off ink.
+
+## Tokens with no contrast guarantee
+
+`boxborder`, `border` and `sidebar` are decorative or vestigial. Measured on the canvas,
+`boxborder[500]` is 1.30–2.56:1 in light and 1.84–3.78:1 in dark — it must not be used as a control
+outline. Nothing in this library reads any of the three.
+
+| Need | Use | Never |
+| --- | --- | --- |
+| a control outline (WCAG 1.4.11) | `roleColors().border.interactive` | `boxborder[500]` |
+| status text, icon or border | `palette.semanticText[tone]` | `semantic[tone][500]` — that is the *fill* rung |
+| a status fill | `roleColors().status[role].solid` + `onSolid` | a hand-picked white or black label |
+| accent-coloured text | `roleColors().accent.text` | `primary[500]` — the *filled-control* rung |
+| secondary/muted text | `roleColors().fg.muted` | `gray[400]` — the border/icon rung |
+| a field's placeholder | `roleColors().fg.placeholder` | `fg.muted` — body copy, so empty fields read as filled |
+| a white surface | `background[50]` | `white` — that is ink on a filled control |
+
+`roleColors()` is the supported colour API; the raw palette is available as `useTheme().palette` for
+the few tokens roles do not cover. There is no sidebar rail in this library, so `sidebar` carries a
+background ramp and nothing else — web's `sidebar.active*` / `muted*` / `elevated` tokens are
+deliberately not ported.
+
+## Reading colour
+
+```ts
+const { palette } = useTheme();
+palette.semanticText.error   // guaranteed present
+```
+
+No `?.`, no `??`, no `as unknown as`. `assertPalette` runs once where a palette enters
+(`PixelizeProvider`) and throws naming every missing token. That error is the feature: it is
+visible, it names the fix, and it happens once at the boundary instead of as a wrong colour deep in
+a screen.
+
+## Adding a token
+
+1. Add it to `PaletteProps` in `types.ts`.
+2. Compile. TypeScript names every place that must handle it:
+   - `assertPalette.ts` — `type Unlisted = Exclude<keyof PaletteProps, …>` fails until the token is
+     listed in `REQUIRED_TOKENS`
+   - each brand's `palette.light.ts` — unless the token is derived, in which case exclude it from
+     `BrandPaletteSource` and compute it in `finalizePalette`
+3. Add an assertion of its guarantee to `__tests__/paletteContrast.test.ts`, for **every** brand in
+   **both** modes — no exceptions list.
+
+Adding a brand is the mirror image: one `palette.light.ts` exporting a `BrandPaletteSource`, a
+`palette.dark.ts` calling `buildDarkPalette(light)`, and entries in `brands/index.ts`,
+`provider/loadPalette.ts` and the `ThemeName` union. The `it.each(themeNames)` sweeps pick it up.
+
+## The gate
+
+`__tests__/paletteContrast.test.ts` scores every guarantee above for all 9 brands in both modes —
+138 assertions. It also asserts every colour value in every palette parses, and that no brand file
+writes a derived token by hand.
+
+`slate`'s `table.hover[500]` once shipped a Cyrillic `е` (U+0435) inside `"#dfdfе2"` — a valid-looking
+string that RN resolves to no colour at all. Both repos now ship ASCII-only palette files; the parse
+assertion in `paletteContrast.test.ts` is what keeps it fixed.
+
+## Known gap
+
+The light `semantic` ramps are near-identical across all 9 brands, and their `[500]` rungs measure
+**1.84–3.68:1** against the light canvas — unusable as ink. `semanticText` exists so no call site
+has to know that. Dark needs no such lift (5.05–9.89:1) because `buildDarkPalette` derives the
+status ramps rather than copying them. **Light is the worse mode**: every defect this contract
+resolves was light-only.
+
+## A role colour's lightness direction is not fixed across modes
+
+`bg.sunken` (`background[200]`) is **darker** than `bg.surface` (`background[50]`) in light mode and
+**lighter** than it in dark mode. Measured on `zinc`: light `background[50]` `#ffffff` (L=100.0) vs
+`background[200]` `#f4f4f5` (L=95.9); dark `background[50]` `#0e0e11` (L=6.1) vs `background[200]`
+`#18181b` (L=10.0) — the pair inverts because dark surfaces are built from `SURFACE_TARGETS`
+(`buildDarkPalette.ts`), where `50: 7` sits *below* `200: 11`, the opposite order from light mode's
+hand-authored ramp. A component that reasons "sunken means recessed, so it's darker" is right in
+light and backwards in dark.
+
+**Apply:** never infer a surface's relative lightness from its token name or its light-mode value.
+Compare the actual resolved colours for the mode you're in — `roleColors()` already resolves the
+right token per mode; don't hand-derive "darker than X" from a name.
+
+## An elevation token is not a dark-mode boundary
+
+`elevation` (`tokens/primitives/elevation.ts`) layers are pure black-alpha (`#0000001a` etc.) and
+carry no colour-mode of their own. `platform/elevation.native.ts`'s `elevation()` applies that same
+black shadow regardless of mode — on a dark backdrop a black shadow is barely distinguishable from
+the surface it's supposed to lift off, so a floating surface built from the raw token alone reads as
+flat in dark mode. `platform/floatingSurface.native.ts`'s `floatingSurfaceStyle` exists specifically
+to fix this: in dark mode it swaps in a lighter `DARK_AMBIENT` shadow plus an inset highlight, and
+adds a 1px top hairline at the `lg` level, none of which the raw `elevation` token provides.
+
+**Apply:** a surface that floats and can render in dark mode needs `floatingSurfaceStyle` (or, at
+minimum, a hairline edge) — never the raw `elevation` token alone. (Internal to this repo only:
+`floatingSurfaceStyle` is not re-exported through any public subpath, so this applies to components
+built here, not to consumer apps.)
+
+## Placeholder ink is not muted text
+
+`fg.muted` is body copy. Six components used it as their `placeholderTextColor`, so an empty field
+read as one already typed into. `fg.placeholder` is the rung the brand authored — `placeholder[500]`
+shipped as-is — with a 3:1 floor underneath it, never a 4.5:1 one.
+
+**The sub-4.5 floor is deliberate.** It was tried the other way first: held to body-text contrast the
+hint stopped reading as a hint, which is the bug this section exists to prevent. 3:1 is the 1.4.11
+non-text floor, and it is what the published web library ships. Lavender light is `#7a72b0` at 4.06:1
+in both libraries; every brand lands between 3.96 and 4.13 in light.
+
+The rung is never darkened when it already clears. The floor exists only for a brand whose authored
+rung is too pale for a surface it lands on — and it does fire here, on `radiant light` and
+`rosewood light`, because of the port boundary below.
+
+### Where mobile's field surfaces differ from web's
+
+| | web `fieldSurfaces` | mobile `FIELD_SURFACES` |
+|---|---|---|
+| canvas | `backgroundColor.main` | `backgroundColor.main` |
+| field fill | `gray[50]`, `background[50]` | `background[50]` |
+| pressed | — | `backgroundColor.muted` (`bg.hover`) |
+
+Mobile is touch: a Select or Combobox trigger showing a placeholder goes to `bg.hover` while pressed,
+with the hint still on screen, so that surface is a real pairing here and not on web. On the two
+brands whose `backgroundColor.muted` is a deep tint this pulls the ink above the authored rung. That
+divergence is correct, not drift — do not "fix" it by deleting the pressed surface.
+
+Disabled fills are excluded on purpose: 1.4.3 exempts them, and folding them in would darken the hint
+on every enabled field.
+
+`roleColors.test.ts` gates both halves: the ink clears 3:1 on every field surface, and it is left
+untouched whenever the authored rung already clears. `surfaceRungs.test.ts` deliberately does **not**
+sweep `placeholder[500]` — what ships is `fg.placeholder`, not the raw rung. Web's mirror of this
+lives in `Theme/CHROME-CONSISTENCY.md`.
+
+## Dark-mode surface tint (mobile vs web — owner decision)
+
+`buildDarkPalette.ts` matches web on algorithm and target tables, but mobile keeps brand hue on dark
+surfaces (`SURFACE_SAT = 14`, `GRAY_SAT = 6`) where web uses neutral grey (`0` / `0`). Borders also
+differ slightly (`BORDER_TARGETS` 50–400). **Mobile is intentionally tinted for OLED**; web is
+neutral. Both are valid — pick one canonical behaviour and align both repos; do not change mobile
+unilaterally in a palette port.
+
+## Control size scale (mobile vs web)
+
+Web `CONTROL_SIZES` (`tokens/primitives/controlSizes.ts`) uses 24–56 **px** heights with **`sm`
+default**. Mobile `CONTROL_HEIGHTS` uses 44/52/56 **dp** with **`md` default** — the 44dp floor is
+WCAG 2.5.5 / Apple HIG, not a drift bug. Shared `fontSizes` (12…128) still drive label sizes via
+`CONTROL_LABEL_FONT_SIZE`.
+
+## Line-height vocabulary
+
+Mobile primitives use `tight` / `snug` / `relaxed` / `loose` (ratios stored in `lineHeights.ts`).
+Web's older names (`shorter` / `short` / `tall` / `taller`) are not duplicated here — mobile is
+canonical for this repo.

package/lib/module/theme/tokens/assertPalette.js

@@ -0,0 +1,29 @@
+"use strict";
+
+const REQUIRED_TOKENS = ["gradient", "primary", "secondary", "tertiary", "transparent", "black", "white", "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan", "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder", "boxShadow", "sidebar", "boxborder", "border", "table", "disabled", "semanticText"];
+
+// Adding a token to PaletteProps without listing it here is a compile error, not a silent gap.
+
+export const allPaletteTokensListed = true;
+const NESTED = [["semantic", ["success", "error", "warning", "info"]], ["backgroundColor", ["main", "base"]], ["gradient", ["from", "to"]], ["semanticText", ["success", "error", "warning", "info"]]];
+export const missingPaletteTokens = palette => {
+  if (!palette || typeof palette !== "object") return ["(no palette object)"];
+  const p = palette;
+  const missing = REQUIRED_TOKENS.filter(k => p[k] === undefined).map(String);
+  for (const [group, keys] of NESTED) {
+    const value = p[group];
+    if (!value) continue;
+    for (const key of keys) if (value[key] === undefined) missing.push(`${group}.${key}`);
+  }
+  return missing;
+};
+
+/** Fails once, loudly, where a palette enters — never as a wrong colour deep in a screen. */
+export const assertPalette = (palette, source) => {
+  const missing = missingPaletteTokens(palette);
+  if (missing.length > 0) {
+    throw new Error(`pixelize-native-library: ${source} is missing ${missing.length} palette token(s): ` + `${missing.join(", ")}. Roles read these directly and have no fallback by design.`);
+  }
+  return palette;
+};
+//# sourceMappingURL=assertPalette.js.map

package/lib/module/theme/tokens/brands/emerald/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#0f9d8a";
 const primary = {
@@ -18,11 +19,12 @@ const primary = {
 };
 
 // No `tertiary` override — emerald inherits lavender's purple tertiary, as web ships it.
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
+  // NOTE: stops retuned so white gradient-button text clears AA at both ends — original let it drop to 3.38/2.43.
   gradient: {
-    from: "#0f9d8a",
-    to: "#06b6d4"
+    from: "#0d8474",
+    to: "#048096"
   },
   primary,
   gray: {
@@ -31,7 +33,8 @@ const palette = {
     200: "#dce5e5",
     300: "#c3d2d2",
     400: "#9fb3b3",
-    500: "#7c9191",
+    // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
+    500: "#617474",
     600: "#5e7070",
     700: "#475555",
     800: "#2f3a3a",
@@ -117,9 +120,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/lavender/palette.light.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import finalizePalette from "../../builders/finalizePalette.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#8B3FC8";
 const SECONDARY_ANCHOR = "#1e0f30";
@@ -209,7 +210,7 @@ const backgroundColor = {
   secondary: "#f2edf8",
   tertiary: "#ebe3f4",
   quaternary: "#e2d8ef",
-  light: "#fdfcfe",
+  light: "#ffffff",
   medium: "#e8e0f2",
   accent: "#e0d5ed",
   subtle: "#f5f1fa",
@@ -336,12 +337,12 @@ const disabled = {
   900: "#4b4759"
 };
 
-// Two-tone brand gradient (violet → pink). Each brand overrides with its own pair.
+// Single-hue gradient: white clears AA by margin, not by hundredths. See gradientTone.test.ts.
 const gradient = {
-  from: "#8B3FC8",
-  to: "#EC4899"
+  from: "#8b3fc8",
+  to: "#762d9d"
 };
-const palette = {
+export const source = {
   gradient,
   primary,
   secondary,
@@ -372,5 +373,5 @@ const palette = {
   table,
   disabled
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map