pixelize-design-library 2.3.21 → 2.4.1-beta.1

package/.cursor/modules/theme/MODULE.md

@@ -2,14 +2,313 @@
 
 ## Purpose
 
-Eight brand presets (Default, Dark, Emerald, Meadow, Radiant, Rosewood, Skyline, Slate), `useCustomTheme`, `withTheme` HOC, token builders.
+Nine brand presets (lavender, meadow, radiant, skyline, slate, emerald, rosewood, storefront, zinc),
+each with a **light and dark palette**; `useCustomTheme`, the legacy `withTheme` HOC,
+`PixelizeThemeProvider` + `useThemeMode` + `ThemeSwitcher`, and the pure token layer shared with the
+mobile design library.
 
 ## Key paths
 
-- `src/Theme/`, `src/withTheme.tsx`
-- Export: `useCustomTheme`, `ThemesList`, `withTheme`
+- `src/Theme/tokens/` — **pure, platform-agnostic** (no Chakra/React/CSS imports)
+  - `types.ts` — `PaletteProps`, `ThemeName`, `ColorMode`, `ColorScale`
+  - `primitives/` — space, sizes, radii, shadows, typography, breakpoints, zIndices
+  - `builders/` — `color.ts` (hex/HSL/WCAG math), `buildDarkPalette.ts`
+  - `brands/<brand>/palette.light.ts` + `palette.dark.ts`
+- `src/Theme/chakra/` — **web-only** binding: `createBrandTheme`, `componentStyles`, `fonts.web.ts`
+- `src/Theme/provider/` — `PixelizeThemeProvider`, `useThemeMode`, `ThemeSwitcher`
+- `src/Theme/useCustomTheme.ts` — hook read by ~127 components
+- `src/Theme/index.ts` — `ThemesList` (light) + `brandThemes` (light+dark)
+- `src/withTheme.tsx`
+- Exports: `useCustomTheme`, `ThemesList`, `withTheme`, `PixelizeThemeProvider`, `useThemeMode`,
+  `ThemeSwitcher`, `brandThemes`, `lightPalettes`, `darkPalettes`, `palettes`, `themeNames`,
+  `buildDarkPalette`
+- Also exported (Wave D follow-up, see below): the WCAG contrast helpers `isDarkCanvas`,
+  `onFilled`, `onGradient`, `accentTextOnCanvas`, `pickAccentText`, `AA_NORMAL_TEXT`,
+  `DARK_CANVAS_LUMINANCE` (`builders/accentText.ts`) and the pure color-math primitives
+  `relativeLuminance`, `contrastRatio`, `hexToRgb`, `hexToRgba`, `compositeOver`, `rgbToHex`,
+  `rgbToHsl`, `hslToRgb`, `hexToHsl`, `hslToHex`, `withLightness`, `mix` + types `Rgb`/`Hsl`
+  (`builders/color.ts`)
+
+## How dark mode works
+
+Dark mode **swaps which palette the theme carries** (`brandThemes[brand][light|dark]`) rather than
+using Chakra `semanticTokens` / `_dark`. This is deliberate: components interpolate **resolved hex**
+from `useCustomTheme()`, and `componentStyles` variants are functions of `({ theme })` — so both
+follow the active palette with **zero per-component edits**.
+
+Dark palettes are **derived** from each brand's own light palette by `buildDarkPalette`, so brand hue
+carries through. Structural ramps (background/text/border/…) are rebuilt at explicit lightness
+targets around the brand hue; utility hues are reversed; accents are **adaptively lifted** to
+maximize canvas contrast without ever regressing the white-on-accent label below
+`min(4.5, lightModeContrast)`.
 
 ## Key rules
 
-- Consumers wrap app with `withTheme`; use theme tokens not hardcoded colors
-- Chart colors from theme via `chartColorsFromTheme`
+- **`tokens/` must never import Chakra, React, or CSS** — it is copy-paste portable to the mobile
+  design library. Web-only concerns live in `chakra/`.
+- **Never hardcode a hex in a component** — read from `useCustomTheme()`, or it is stuck in light mode.
+- **`colors.white` is a foreground token** (the label on a filled button) and stays white in dark.
+  For a white *surface* use `colors.background[50]` — identical `#ffffff` in light, dark-aware.
+- `withTheme` stays **light-only** so existing consumer apps are visually unchanged; dark is opt-in
+  via `PixelizeThemeProvider` (defaults to **`system`**).
+- `src/index.ts` is **append-only** — `src/index.publicApi.test.ts` asserts every previously
+  published name still exists (consumer contract guard).
+- Chart colors from theme via `chartColorsFromTheme`.
+
+## Recent changes (WCAG contrast + dark-mode pass)
+
+- **Badge** is now themed in `chakra/componentStyles.ts` (no `Components/Badge/` family — style
+  config lives here). `solid`/`subtle` variants guard non-hex `colorScheme` swatches (Chakra's
+  built-in `blackAlpha`/`whiteAlpha` are `rgba()` strings, not hex — `isHexColor()` falls back to
+  `swatch?.[800]` instead of throwing). `subtle` also verifies `contrastRatio(accent, bg) >= 4.5`
+  before using the brand-hue accent from `accentTextOnCanvas`, else falls back to `onFilled()`
+  (provably-always-AA) — fixes a near-miss (measured 4.42, needs 4.5) on the yellow scale in dark mode.
+- `tokens/builders/accentText.ts`: `pickAccentText`/`accentTextOnCanvas` now take
+  `primary: ColorScale | undefined` and return a safe white/black fallback instead of throwing
+  when the scale is missing (regression: some call sites had dropped defensive `?.` chaining).
+  New `onFilled(fill, white, black)` export — provably clears AA against any fill; used by Badge.
+- 4x `brands/{emerald,meadow,radiant,rosewood}/palette.light.ts`: `gray[500]` (the de-facto
+  muted-text token, ~43 call sites) retuned to clear AA (>=4.5) against every `backgroundColor`
+  surface actually rendered as a `bg=` today (main/secondary/light/subtle), while staying
+  lighter than `gray[600]` (ramp order preserved). See "Known gaps" below for what this did
+  **not** cover.
+- `tokens/builders/chartColorsFromTheme.ts`: removed unused `chartTooltipBackground`/
+  `chartTooltipForeground` exports (dead code — no callers after `ApexLineChart.tsx` stopped
+  using them in this same pass).
+
+## Wave D — WCAG follow-up pass
+
+- `gray[500]` retune (same methodology as the four brands above) extended to
+  `brands/{lavender,skyline,slate}/palette.light.ts` — these three had the identical unfixed gap
+  (lavender failed all 4 `backgroundColor` surfaces at 3.96-4.45; skyline/slate failed
+  `secondary`/`subtle`), missed by the earlier pass.
+- **Gradient stop retune (7 brands)** — every brand's `gradient: {from, to}` token had a stop pair
+  where neither pure white nor pure black cleared AA at both ends. Darkened the lighter stop per
+  brand (user-approved trade-off — this is the only Wave D change that visibly shifts brand
+  identity, not just a muted/secondary token) so white gradient-button text clears AA at both ends.
+  `accentText.ts` gained `onGradient(from, to, white, black)` — picks `onFilled` against whichever
+  stop has the higher `relativeLuminance` (the harder case); safe **once** the gradient's own stops
+  are tuned this way, not guaranteed for an arbitrary caller-overridden gradient (see
+  `account-management` MODULE.md — `UpgradeButton`'s `gradient` prop).
+- **`error`/`red[500]` AA gap** — architecturally different from `gray[500]`: a saturated red's low
+  WCAG luminance weight makes a single-value retune mathematically impossible within the
+  `error600` lightness boundary. Fixed instead by routing every hardcoded `red[500]`/`error[500]`
+  text call site through `accentTextOnCanvas`, which walks to `error[700]` (clears 5.46-6.21 across
+  all 7 brands) automatically. No palette edits needed — `red`/`semantic.error` are identical
+  across brands (only `lavender` defines them; others inherit via spread).
+- **`pickAccentText` hardened against a partial `ColorScale`** — the rung-walk in
+  `accentText.ts` previously assumed every caller supplies all of rungs 500-900 and crashed
+  (`hexToRgb(undefined)`) on a sparse scale (a real risk for any consumer with a hand-built or
+  test-mock theme, not just this repo's own tests). Now treats a missing rung as "doesn't clear
+  AA" and keeps walking; falls back to the nearest defined rung, then to safe white/black if the
+  scale is empty.
+
+## Wave D — QA-driven follow-up (user ran a Chrome-extension-based contrast/AA pass against the live playground)
+
+- **Margin-safety correction on the 7-brand gradient retune above.** Direct re-measurement found
+  every brand's darkened stop cleared AA by **less than 0.02** (e.g. 4.502 vs the 4.5 cutoff) —
+  too thin to trust against rounding/rendering variance, and a systemic gap across all 7 brands'
+  first-pass tuning (the search stopped the instant AA was crossed, with no margin built in).
+  Rebuilt every brand's thin-margin stop(s) with a **safe ≥4.6 target** instead of the bare 4.5
+  cutoff, using the same HSL-preserving-hue/saturation darkening search. Final margins verified
+  live via Playwright: 4.581–4.834 across all 7 brands. Established going forward: **a contrast
+  value that clears AA by <0.02 should be treated as failing**, not passing.
+- **`Modal`/`AlertDialog`/`Drawer` dark-mode surface bug** — see overlays / layout-navigation
+  MODULE.md. Root cause: these hardcode Chakra's literal `colors.white` baseStyle (gated behind
+  `_dark`), unlike `Card`, which already routes through the patched `chakra-body-bg`/
+  `chakra-body-text` semantic tokens — the QA report's claim that `Card` was also broken did not
+  reproduce under direct Playwright measurement **at the time**, in a fresh browser context. See
+  the correction below: `Card` *can* break, conditionally, and the real fix was one level up
+  from any single component.
+- **`Card`/`ProfileCard` dark-mode surface bug (user-reported via screenshot, blocking) — corrects
+  the claim above.** The claim that this app's theme-swap dark mode "never triggers" Chakra's
+  `_dark:` selector was wrong: `_dark:` maps to `.chakra-ui-dark &` / `[data-theme=dark] &`, and
+  Chakra's own `ColorModeProvider` (which every `ChakraProvider` wraps internally, regardless of
+  this app's separate palette-swap mechanism) sets that class/attribute from its **own**
+  `localStorage["chakra-ui-color-mode"]` key — entirely separate from this app's own
+  `"pixelize-theme"` storage key — and that stored value **wins over** `theme.config
+  .initialColorMode: "light"` on every load if present. A fresh browser context has no such
+  stored value, so the earlier Playwright measurement never saw the bug; a browser where
+  Chakra's native color mode was ever toggled to `"dark"` on this origin (by this app or an
+  earlier version of it) does, permanently, until that one key is cleared. Confirmed live:
+  seeding `localStorage["chakra-ui-color-mode"] = "dark"` reproduces the exact reported symptom —
+  `Card`'s default `"elevated"` variant carries Chakra's own un-migrated
+  `_dark: { bg: "colors.gray.700" }`, and this app's dark ramp runs dark→light, so `gray[700]`
+  resolves to L≈79% (a light, brand-tinted gray) instead of the correct dark `chakra-body-bg`.
+  `ProfileCard` hits the identical path (also a bare `ChakraCard` with no explicit `bg=`).
+  `PricingCard`/`PaymentCard` were never affected — they set an explicit `bg={theme.colors
+  .background[50]}` themselves, which wins over the variant's `_dark:` block regardless.
+  **Fixed at the root, not per-component:** `PixelizeThemeProvider` now passes a
+  `colorModeManager` to `ChakraProvider` that always returns `"light"` and never persists,
+  severing Chakra's native color mode from `localStorage` entirely — so no un-migrated `_dark:`
+  block anywhere (present or future, not just `Card`) can fire regardless of what's stored.
+  Verified live via Playwright: reproduced the bug by seeding the stale key, confirmed the fix
+  neutralizes it (`Card` background back to the correct dark canvas color in both the fresh and
+  stale-storage cases).
+- Same "text-as-scale-rung fails AA against its canvas" pattern (established by the `error`/
+  `red[500]` fix above) applied to two more call sites found by the QA pass: `Notification`'s
+  time-elapsed orange icon/text (feedback module) and `FileUploader`'s blue accent text
+  (inputs-date-file module).
+- **`gray[500]` margin widen (`slate`/`rosewood`), code-review catch:** the same "<0.02 margin
+  should be treated as failing" rule established above for the gradient stops also applied to
+  the earlier `gray[500]` retune — `slate` measured 4.509 and `rosewood` 4.516 against their
+  `secondary` `backgroundColor` surface, both too thin. Darkened each by ~0.7 lightness points
+  (hue/saturation preserved, same HSL search as the gradient fix) to a safe ≥4.6 margin against
+  all four surfaces; the other 5 brands' `gray[500]` already cleared ≥4.6 and needed no change.
+  All 7 brands' `gray[500]` comment updated to state the ≥4.6 standard explicitly.
+- **`FormError` (`chakra/componentStyles.ts`), code-review catch:** Chakra's stock
+  `FormErrorMessage`/`FormErrorIcon` both hardcode `colors.red.500` via a shared `--form-error-color`
+  CSS var — the library's `FormError` override (added earlier this pass) fixed the `text` anatomy
+  part via `accentTextOnCanvas` but missed the `icon` part, which stayed on Chakra's raw
+  `red.500` and kept the same AA gap for any consumer rendering `<FormErrorIcon/>`. Both parts now
+  share one computed `color`.
+
+## Wave D — public export of the WCAG contrast helpers (user request: "export anything useful for consumers")
+
+- `accentText.ts`'s helpers and `color.ts`'s pure color math were internal-only (imported by
+  ~25 components + `chakra/componentStyles.ts`) despite being generic, dependency-free, and
+  already the load-bearing logic behind this whole pass's AA fixes. Promoted to `src/index.ts`
+  as additive exports (append-only guard test updated) so a consumer building a custom component
+  against this library's `ColorScale`/`PaletteProps` tokens can reuse the same contrast logic
+  instead of re-deriving WCAG math themselves.
+- **Deliberately NOT exported:** `pickActiveAccent` (`Header.tsx`, this pass's BLOCKING fix) — it's
+  a narrow, Header-specific non-text-accent picker (hardcoded `ACTIVE_ACCENT_TARGET = 3`, a search
+  order tuned for one component's underline accent), not a general-purpose public utility.
+- `accentTextOnCanvas`'s search-direction assumption (canvas darkness implies a dark-mode-shaped
+  scale — see the Header bug in layout-navigation MODULE.md) holds for every one of its ~25
+  internal call sites because both the scale and the canvas always come from the SAME active
+  theme mode there. A consumer passing an unrelated custom scale/canvas pairing could still hit
+  the same edge case Header did; `pickAccentText(primary, canvas, mode)` (explicit mode, no
+  guessing) is the safer of the two for that case and is exported alongside it for that reason.
+
+## Wave B — 8th brand (`storefront`), cross-repo coordination with the mobile design library
+
+- Added `brands/storefront/palette.{light,dark}.ts`, registered in `types.ts` (`ThemeName`),
+  `brands/index.ts` (`lightPalettes`/`darkPalettes`/`palettes`/`themeNames`), `Theme/index.ts`
+  (`ThemesList`/`brandThemes`), and `provider/colorModeStorage.ts`'s `VALID_BRANDS` allowlist (a
+  hand-maintained literal array, **not** derived from `themeNames` — easy to miss; a stale stored
+  `brand: "storefront"` would otherwise be silently rejected back to the default brand).
+- Anchor `primary[500] = "#004f4b"` (deep spruce teal, H≈177° S=100% L≈15.5%) — decided in
+  cross-repo coordination with the sibling `Mobile-Components` design library, which owns and has
+  already shipped the separate `zinc` brand (the true shadcn-clone) across all 8 brands; do not
+  conflate the two — `storefront` is this repo's own brand, `zinc` is mobile's.
+- Structural ramps (`gray`, `background`, `border`, `boxborder`, `table.hover`, `backgroundColor`,
+  `sidebar.background`) were derived by **rehuing `emerald`'s exact ramp** (same lightness/
+  saturation curve per stop, hue rotated to storefront's 177°) rather than a fresh hand-tune —
+  emerald is the closest existing single-hue teal brand, so this reuses an already-AA-verified
+  shape instead of guessing new numbers. `primary` itself uses a custom lightness curve (500 pinned
+  to the exact anchor hex; 50-400 and 600-900 solved so the anchor sits proportionally where the
+  curve requires — emerald's own anchor is far lighter (L=33.7) than storefront's (L=15.5), so its
+  literal curve doesn't transplant; only the *shape* (fractional position + step ratios) carries
+  over). `gradient` mirrors emerald's "same hue, darker `to` stop" pattern, tuned to a ≥4.6 white-
+  text-contrast margin at both stops per the Wave D "don't trust a <0.02 margin" rule (measured
+  4.98 / 6.96).
+- **Zero hand-tuning needed post-registration** — unlike the 7 existing brands (which each needed a
+  `gray[500]`/gradient retune pass, see Wave D above), `storefront` passed every existing
+  `it.each(themeNames)` AA assertion (`accentText.test.ts`, `buildDarkPalette.test.ts`, etc.) on the
+  first run, because the rehue-from-emerald approach inherited an already-AA-clean shape. Full gate
+  green: `tsc --noEmit` clean, `jest` 791/791 (65 suites), lint clean.
+- Dark palette is the plain `buildDarkPalette(light)` derivation (matches `slate`'s pattern) — no
+  bespoke override needed. The generic derivation's `accentLightnessDelta` cap (which assumes a
+  white button label) is architecturally incompatible with a true "near-white primary in dark mode"
+  requirement, but `storefront` doesn't need that — that requirement belongs to mobile's `zinc`.
+
+## Wave E — ThemeSwitcher brand-list `MenuList` dark-mode fix (user-reported, blocking)
+
+`ThemeSwitcher.tsx`'s brand-picker (`BrandMenu` + `MenuVariant`) `MenuList` had no explicit `bg=`,
+so in dark mode it fell through to Chakra's `Menu` baseStyle hardcoded `--menu-bg: #fff` (gated
+behind `_dark`, same bug class as `NavigationBar`/`ButtonGroupIcon`'s `MenuList` fix above) — a
+white dropdown with only the checked item's checkmark-opacity change to distinguish rows, so every
+unselected brand name read as near-white-on-white. Fixed with the same pattern: both `bg=` (colors
+the list's own box) **and** `sx={{ "--menu-bg": ... }}` (colors the var other pseudo-states read)
+on both `MenuList`s, plus an explicit `color=` for the item text (was inheriting ambient
+`text[900]`, now reads `menuColor` from the same theme-derived palette). New `useSwitcherColors()`
+hook centralizes all of `ThemeSwitcher`'s token reads. Verified: `tsc`/lint clean, all 63 existing
+`Theme/provider` tests still pass (no behavior regression, dark-mode-only fix).
+
+## Wave F — 9th brand (`zinc`), ported from the mobile design library's shadcn clone
+
+User request: "add zinc theme exactly same as mobile," then "both mobile and web's zinc theme
+should me similar to shadcn theme as close as possible" — so the goal is maximum fidelity to
+mobile's `zinc` (itself "the shadcn look"), adapted only where web's own invariants require it.
+
+- Added `brands/zinc/palette.{light,dark}.ts`, registered in `types.ts` (`ThemeName`),
+  `brands/index.ts`, `Theme/index.ts` (`ThemesList`/`brandThemes`), and
+  `provider/colorModeStorage.ts`'s `VALID_BRANDS` allowlist — same 4-file wiring as `storefront`
+  (Wave B).
+- **Light palette**: ported verbatim from `Mobile-Components/src/theme/tokens/brands/zinc/
+  palette.light.ts` — no web-side changes needed, passed every existing AA sweep unmodified.
+- **Dark palette — INVERTS the primary**, unlike every other brand: the filled button is
+  near-white (`#e4e4e7`) carrying a near-black label (`#18181b`, 13.96:1), the opposite of every
+  other brand's "lifted-but-still-dark" dark primary. `primary`/`secondary`/the numeric
+  `background` ramp/`text`/`header`/`gray`/`border`/`boxborder`/`placeholder`/`disabled`/`table`
+  are pinned as literals ported verbatim from mobile to preserve the authentic shadcn look;
+  `accentText` is recomputed against the overridden `primary` (not spread from the generic
+  derivation, which would be stale).
+- **`backgroundColor` (named surfaces) and `sidebar` intentionally do NOT port mobile's literal
+  values** — the one deliberate deviation from "exactly same as mobile," found by running zinc
+  through web's existing `it.each(themeNames)` test sweeps:
+  - Mobile's zinc dark `backgroundColor` maps its 12 named surfaces onto only 5 distinct hexes
+    (e.g. `quaternary`/`medium`/`neutral` are all `#18181b`), which fails web's
+    `darkSurfaces.test.ts` invariant that every named surface is a visually distinct elevation
+    step (`ALIASED_SURFACES = ["light","tertiary"]` is the only sanctioned exception, shared by
+    every brand). Retuning each collision by hand would be arbitrary; instead `backgroundColor`
+    falls through to `...derived` (the same generic `buildDarkPalette` staircase every other
+    brand gets) — zinc's hue (~240°, near-zero saturation) survives the derivation as a
+    visually-identical cool neutral, just with distinct steps.
+  - Mobile's zinc dark `sidebar` is separately tuned from its light `sidebar` — but every web
+    brand's dark `sidebar` is identical to its light `sidebar` (`buildDarkPalette.ts`: "sidebar is
+    already near-black in light mode, so it needs no inversion"), an invariant the SideBar
+    dark-mode accent fix (this repo, same branch) depends on. `sidebar` falls through to
+    `derived.sidebar` instead, matching every other brand.
+- **Fixed 3 test assertions that hardcoded a white filled-button label**, a bar only zinc's
+  inverted primary fails (every other brand's dark primary still carries a white label, so this
+  was never exercised before): `accentText.test.ts` ("dark filled-button label never regresses
+  below its light-mode contrast") and `buildDarkPalette.test.ts` (2 assertions: "never lifts the
+  accent past what light theme already ships" + "keeps solid-button labels readable against the
+  accent fill"). All 3 now check via `onFilled(fill, white, black)` — whichever ink clears AA —
+  instead of assuming white specifically, which is the correct brand-agnostic contract (the same
+  one components already use) and a strictly more correct check, not a loosened one.
+- **Fixed a pre-existing bug in `ButtonGroupIcon.tsx`'s gradient variant** (2 spots, both hardcoded
+  `theme.colors.white` for the label), independent of zinc but only caught because zinc's near-
+  white gradient stops (originally `{from:"#fafafa", to:"#a1a1aa"}`) make the failure visible —
+  same bug class already fixed elsewhere per `Button.styles.ts`'s own comment ("was a hardcoded
+  `theme.colors.white` — fails AA for any colorScheme whose [500] doesn't clear white contrast").
+  Now uses `onGradient(from, to, white, black)`, matching the established pattern.
+- Full gate green: `tsc --noEmit` clean, lint clean, `jest` 902/902 (72 suites, up from 869/72 pre-
+  zinc — 33 new tests from the added `zinc` sweep, zero regressions).
+
+**2026-07-18 — dark primary corrected to shadcn's actual value.** The original port used `#fafafa`
+for the dark-mode filled primary, approximated as "near-white" rather than checked against shadcn's
+real registry. Fetched shadcn's live zinc theme (`ui.shadcn.com/r/colors/zinc.json`, OKLCH tokens)
+and converted precisely: shadcn's dark `--primary` is `oklch(0.92 0.004 286.32)` → `#e4e4e7`
+(zinc-200), one shade dimmer than pure white — `#fafafa` is actually shadcn's `--foreground`
+(default dark-mode body text), not `--primary`. Updated `PRIMARY_500` and the dependent
+`gradient.from` (now references the constant instead of a duplicated literal) in both this repo and
+Mobile-Components; `accentText`/`boxShadow.primary` recompute automatically since they already
+derive from `PRIMARY_500` rather than being spread from the generic derivation. Light mode's
+primary (`#18181b`) already matched shadcn's `--primary` exactly — no change there. Verified every
+other light/dark role against the same live registry (`background`, `card`, `muted`/`secondary`/
+`accent`, `border`/`input`, `muted-foreground`) — all already matched shadcn within rounding.
+`fg.default`/`text[500]` (light `#18181b` vs shadcn `--foreground` `#09090b`) and the dark `bg.surface`
+elevation step (`#0e0e11` vs shadcn's card `#18181b`) were deliberately left as-is: both are
+shared-shape/shared-role values that would require restructuring the 10-step ramp or the
+cross-brand `roles/bg.surface` mapping, not a zinc-only anchor swap — out of scope for a
+change scoped to "don't break anything."
+
+## Known gaps
+
+- `KanbanBoard.tsx` uses `var(--chakra-colors-gray-300)`, but `cssVarPrefix` is `"ck"` — that
+  variable has never resolved (pre-existing; out of scope for the dark-mode task).
+- `backgroundColor.muted`/`accent`/`tertiary`/`quaternary`/etc. are **not** covered by the
+  `gray[500]` retune above — 0-1 live usages in the whole codebase, and the one live
+  `backgroundColor.muted` usage pairs with `gray[600]` text, not `gray[500]`. Intentionally
+  deferred, not fixed.
+- **Found during Wave D live re-verification, NOT fixed (outside the QA report's scope, flagging
+  for a follow-up pass):** the SideBar's notification-count badge ("10") measures ≈1.2-1.6:1
+  against its translucent primary-tinted pill background — fails badly. The playground's own
+  `/header` demo bar's raw-Chakra "Logout" ghost button measures ≈3.5:1 — same root cause as the
+  already-documented Header Bug B ("Login" button, layout-navigation MODULE.md): a raw Chakra
+  `Button` picking up the library's ghost-variant ink tuned for the page canvas, not Header's own
+  dark bar. Neither was in the QA report or its established follow-up patterns, so left untouched
+  rather than silently expanding this pass's scope.

package/.cursor/modules/utility-ui/MODULE.md

@@ -13,3 +13,38 @@ Generic standalone UI helpers: CopyButton, ScrollToTop, LazyWrapper, MoreItems,
 - FilePreview also exports `FilePreviewTrigger`; StageProgress also exports `StageItem` (StepperStage is internal)
 - LazyWrapper wraps lazy/Suspense loading; ScrollToTop is a scroll-position helper — keep them framework-agnostic (props in, events out)
 - Single-file components (CopyButton, ScrollToTop, LazyWrapper, PdfViewer, FieldSelectModal) have no colocated Props file — types are inline
+
+## Dark mode
+
+CopyButton, EmptyState, FieldSelectModal, FilePreview, LazyWrapper, MoreItems, PdfViewer,
+ProfilePhotoViewer and StageProgress take their colors from `useCustomTheme()` or from Chakra scale
+tokens (FilePreviewTrigger's `bg="gray.100"`) — both resolve against the swapped palette. The `#…` literals
+left in FilePreview / StageProgressProps are `??` fallbacks behind optional token reads — never live
+colors. `blackAlpha.*` scrims are deliberate: a scrim stays black in both modes.
+
+- **Portalled overlay surfaces must pin their own `bg`.** Chakra drives Modal/Popover panels off its
+  own default (`colors.white`, or `gray.700` under `_dark` — a *light* grey in our derived dark
+  palettes), which does not track the swapped palette. FieldSelectModal, FilePreview and MoreItems
+  each set `bg={theme.colors.background[50]}`; MoreItems' `PopoverArrow` needs its own `bg` too
+  (that prop is what sets `--popper-arrow-bg`).
+- StageProgress colors resolve through `resolveStagePalette(theme, colorScheme)` in
+  `StageProgressProps.tsx` — StageItem and StepperStage share it, so add a stage color there, not in
+  a component. Its `onStrong` (label on a filled stage) is now `onFilled(strong, white, black)` —
+  picks whichever of white/black clears AA against that scheme's actual `strong` rung, instead of
+  assuming white always works; StepperStage's *unfilled* circle still uses `background[50]` because
+  that one is a surface.
+- LazyWrapper's default spinner lives in a `DefaultFallback` subcomponent — `useCustomTheme()` is a
+  hook, so it cannot be called from the plain `fallback` node.
+
+### WCAG-contrast fixes (this pass)
+
+- **CopyButton "menu-item" ink**: `accent` now resolves via `accentTextOnCanvas(theme.colors.primary,
+  theme.colors.backgroundColor.main)` instead of raw `primary[500]` — `primary[500]` is tuned for a
+  label *on* a filled button, not ink read directly off the canvas, and was failing AA (as low as
+  4.07 measured) in 5 of 7 brands in dark mode.
+- **MoreItems popover item label**: reads `gray[500]` (the library's verified muted-text token) in
+  place of a locally-picked, non-standard rung.
+- **Control-boundary borders** (WCAG 1.4.11, needs >=3.0 against any named surface up to `muted`)
+  bumped to `boxborder[800]`: CopyButton's "button"-variant border (was raw `gray[200]`) and
+  ProfilePhotoViewer's edit-icon border (was `boxborder[300]`) — both render as an actual control
+  boundary, not decoration, so they need the stronger rung.

package/.cursor/modules/utils-hooks/MODULE.md

@@ -21,3 +21,15 @@ truncation detection.
   `overlays`).
 - **`mergeRefs(...refs)`** (internal) — combine a caller ref with an injected one
   when cloning an element.
+
+## Recent changes
+
+- **`table.ts` — AA-safe `onSolid` ink.** `TablePaletteColor` gained an optional
+  `onSolid` field; `buildTablePalette` and `pickTableColor` now compute it via
+  `onFilled()` (`Theme/tokens/builders/accentText.ts`) against the theme's
+  `white`/`black`, instead of assuming a fixed ink color. `pickTableColor` gained
+  an optional trailing `theme` param to supply this — both additions are
+  backward-compatible; existing callers without `theme` still work (fall back to
+  `#FFFFFF`/`#000000`). `table.test.ts` updated to assert the `onFilled()` math,
+  e.g. `#8B3FC8` clears white at 5.765 (onSolid stays white) while `#ff0000`
+  fails white at 3.998 and falls back to black at 5.252.

package/.cursor/plans/current.theme-tokens-dark-mode.md

@@ -0,0 +1,77 @@
+
+---
+
+# RESUME POINT — paused 2026-07-16 ~12:50, user resuming in ~1hr
+
+## State: SAFE TO PAUSE
+Working tree is green: `tsc` 0, `lint` clean, **679/679 tests**, `build` 0.
+Nothing committed yet. Branch `feature/theme-tokens-dark-mode`. Vite dev server may still be on :5173.
+
+## Scope decision (user answered popup — BINDING)
+1. **"Full WCAG + polish now (light WILL change)"** — the earlier "never touch light / don't affect
+   consumers" constraint is now **RELEASED** for visual changes. API compatibility still absolute
+   (`src/index.publicApi.test.ts` must stay green). Light-mode *pixels* may change; consumers need
+   no code edits.
+2. **shadcn theme = exact zinc/slate clone** — match real shadcn default tokens (zinc/slate
+   neutrals, near-black primary in light, near-white primary in dark, minimal color).
+
+## What is DONE
+- Portable `Theme/tokens/**` (pure, no Chakra/React/CSS) + `Theme/chakra/**` web binding.
+- 7 brands x light+dark; `PixelizeThemeProvider` (defaults `system`) + `useThemeMode` + `ThemeSwitcher`.
+- 29 families migrated hex->tokens. MODULE.md doc-sync done for 12 domains.
+- Fixed already: `accentText` token; Button outline/ghost/link on-canvas text; ghost hover tint;
+  dark `gray[500]` ramp L48->L52.
+
+## THE ROOT CAUSE (next thing to fix — Wave A)
+`liftScale()` in `tokens/builders/buildDarkPalette.ts` adds a lightness delta to EVERY rung, so for
+**brand (primary/secondary/tertiary) and semantic** scales in dark:
+- `[50]`/`[100]` stay near-white (lum ~0.907) -> used as tint chips/avatars/hover => **17 pages
+  render light surfaces on the dark canvas** (this is the broken Accordion the user screenshotted).
+- `[600]`+ stay DARKER than `[500]` -> but components use `primary[600]` as **text**
+  (e.g. `Accordion.tsx:90`) => dark-on-dark, contrast **1.34**.
+- Utility hues (gray/red/green/blue/...) are `reverseScale`d and are CORRECT already.
+
+**Fix:** give brand+semantic a proper dark ramp — monotonic **dark->light** across 50->900, with
+`[500]` PINNED to the adaptive white-label-safe accent (`accentLightnessDelta`, do not change it).
+Proposed targets (verify empirically): 50:12, 100:16, 200:22, 300:32, 400:44, 500:<accent>,
+600:67, 700:76, 800:85, 900:93.
+
+**Cascade (Wave A2):** flipping the ramp breaks `Button.styles.ts` `solid._hover: bg=[600]` /
+`_active: bg=[700]` — those become LIGHT, so the white label fails. Semantics should be "one step
+darker" per mode: light uses `[600]`/`[700]`, dark must use `[400]`/`[300]`. `onCanvasText` and
+`onCanvasHoverBg` helpers already exist in `Button.styles.ts` — extend that pattern.
+
+**Obsolete test:** `Button.styles.test.ts` "light mode is untouched" pins light to `primary[500]`.
+The user has now approved light changes, so that test must be REWRITTEN (not deleted) to assert the
+new intended light values.
+
+## Verified audit numbers (baseline to beat)
+Auditor: `scratchpad/audit-all-pages.cjs` (walks all 51 pages; `MODE=Light|Dark`, `ONLY_PAGE=<name>`).
+Reports: `scratchpad/shots-all/report.json` (dark), `scratchpad/shots-light/report.json` (light).
+
+|                        | DARK | LIGHT |
+|------------------------|------|-------|
+| failing text signatures | 95  | 118   |
+| worst ratio             | 1.0 | 1.0   |
+| near-invisible (<1.5)   | 16  | 6     |
+| pages w/ light surface  | 17  | n/a   |
+
+- 43 dark failures ALSO fail in light => pre-existing debt.
+- **52 dark failures are NEW** across 24 pages => the dark-mode regression to fix.
+- Light's 118 are PRE-EXISTING (present on base commit, untouched by this task).
+
+## Known, deliberately NOT yet fixed
+- `bg={colors.white}` used as a SURFACE in 8 files (never in the 29-family scope because they use a
+  token, not a hex — a hex-only grep could not see them):
+  FileUpload:153, Dropdown:197, Reorder:44, Form/FormWrapper:36, Accordion:46,
+  ProfilePhotoViewer:190, KanbanBoard/AccountCard:54, Header/components/desktopMenu:83
+  -> should become `colors.background[50]` (identical #ffffff in light, dark-aware).
+- `KanbanBoard.tsx:876` uses `var(--chakra-colors-gray-300)` but `cssVarPrefix` is `"ck"` — that var
+  has NEVER resolved. Pre-existing; unrelated to dark mode.
+
+## CI reality (pre-existing, do NOT silently "fix")
+`.github/workflows/build.yml` runs `npm run test:coverage` with an 80% global threshold.
+**Base commit already fails it** (branches 62.57%). Our branch reads ~42% because
+`src/index.publicApi.test.ts` imports the barrel, growing the coverage denominator 101 -> 302 files.
+That is the TRUE coverage finally being measured, not a regression. Lowering the threshold =
+weakening a safety guard => user decision, not ours.

package/.cursor/plans/current.theme-tokens-dark.md

@@ -0,0 +1,155 @@
+# Theme refactor → portable tokens + full dark mode + exported theme switcher
+
+## Complexity
+hard
+
+## Goal
+1. **Restructure theme into a pure, platform-agnostic token layer** (zero Chakra/React/CSS imports)
+   so the mobile design library can copy-paste it. Web-only Chakra binding lives separately.
+2. **Full dark mode** across every component (derived from each brand's existing colors).
+3. **Export** `PixelizeThemeProvider` + `useThemeMode()` + `<ThemeSwitcher/>` for consuming apps.
+4. Refactor/improve along the way (dedupe 7 identical brand theme files, types, a11y contrast).
+
+## Constraints (non-negotiable)
+- **Backward compatible — zero consumer rework.** No removed/renamed public exports, no changed
+  prop signatures. `pixelize-design-library` stays **2.x**.
+- **Light mode must stay pixel-identical.** Dark mode is purely additive.
+- **Keep existing internal import paths as re-export shims** — `Theme/useCustomTheme` (91 importers)
+  and `Theme/themeProps` (~20 importers) must not move.
+- Purity boundary: `Theme/tokens/**` must never import Chakra, React, or CSS.
+  (`fonts.ts` CSS side-effect + `common.ts` `cssVarPrefix` are web-only → stay in web layer.)
+
+## Phase checklist
+- [x] 1. Plan
+- [ ] 2a. Wave 0a — token restructure (serial)
+- [ ] 2b. Wave 0b — dark palettes + provider/hook/switcher (serial)
+- [ ] 2c. Wave 1 — component hex migration (PARALLEL, 17 disjoint families)
+- [ ] 3a/3b. Tests
+- [ ] 3d. Doc sync
+- [ ] 3c. PR readiness (lint + typecheck + test + build)
+- [ ] 4. Review gate
+- [ ] 5. Commit
+
+## Baseline
+- `npx tsc --noEmit` → **exit 0** (green before any change).
+- Branch: `develop`, clean tree. Package v2.3.21.
+
+---
+
+## Architecture — the linchpin
+
+Components read **resolved hex strings** via `useCustomTheme()` and interpolate them:
+```tsx
+border={`0.063rem solid ${theme.colors.border?.[500]}`}
+```
+Chakra `semanticTokens` **cannot** work here (they only resolve as style-prop token names).
+
+**Therefore:** make `useCustomTheme()` **color-mode-aware** — it returns the dark palette when
+`colorMode === "dark"`. All **127** token-consuming files then flip to dark with **zero edits**.
+Remaining real work = the **22** files that hardcode hex.
+
+## Target structure
+
+```
+src/Theme/
+  tokens/                       ← PURE. zero Chakra/React/CSS. Copy-paste to mobile.
+    index.ts                    ← barrel (brands, primitives, builders, types)
+    types.ts                    ← PaletteProps, ThemeName, ColorMode
+    primitives/                 ← space, sizes, radii, shadows, zIndices,
+                                   breakpoints, lineHeights, letterSpacings, typography
+    builders/
+      buildBrandTokens.ts       ← moved (already pure)
+      buildDarkPalette.ts       ← NEW: pure light→dark derivation
+    brands/<brand>/palette.light.ts + palette.dark.ts   ← 7 brands
+  chakra/                       ← WEB-ONLY binding
+    createBrandTheme.ts         ← factory replacing 7 duplicated theme.ts
+    componentStyles.ts          ← moved
+    fonts.web.ts                ← CSS side-effect import + typography
+  provider/                     ← NEW
+    PixelizeThemeProvider.tsx, useThemeMode.ts, ThemeSwitcher.tsx, storage.ts
+  useCustomTheme.ts             ← KEEP PATH, now color-mode-aware
+  themeProps.ts                 ← KEEP PATH, re-export shim
+  index.ts, <Brand>/theme.ts, <Brand>/palette.ts   ← KEEP PATHS as shims
+```
+
+## Dark palette derivation (my call — "mix of existing theme colours")
+Pure `buildDarkPalette(lightPalette)`, applied to all 7 brands — **role-preserving inversion**:
+- **Surface/neutral/text/border scales** (`background`, `text`, `header`, `placeholder`, `border`,
+  `boxborder`, `table.hover`, `disabled`, `gray`): reverse the ramp (50↔900 …) so each index keeps
+  its semantic role but flips lightness. Because each brand's light ramps are already brand-tinted
+  (lavender's gray is violet-tinted), reversing yields **brand-tinted dark for free** — no invented hexes.
+- **Named surface keys** (`backgroundColor.{main,secondary,…,tableHeader}`): explicit dark anchors;
+  elevation goes **lighter** in dark (inverse of light mode).
+- **Brand/semantic** (`primary`, `secondary`, `tertiary`, `semantic.*`): keep hue; accessible accent
+  on dark shifts lighter.
+- **`boxShadow`**: deepen. **`sidebar`**: already dark in light mode → keep near-identical.
+- Verify WCAG AA contrast for text-on-surface pairs.
+
+## API contract (FROZEN)
+Additive exports from `src/index.ts` — nothing removed:
+```ts
+export { PixelizeThemeProvider } from "./Theme/provider/PixelizeThemeProvider";
+export { useThemeMode } from "./Theme/provider/useThemeMode";
+export { ThemeSwitcher } from "./Theme/provider/ThemeSwitcher";
+export type { ColorMode, ThemeName, PaletteProps } from "./Theme/tokens/types";
+// unchanged: default withTheme, useCustomTheme, ThemesList, all 73 components
+```
+```ts
+type ColorMode = "light" | "dark" | "system";
+useThemeMode(): {
+  mode: ColorMode;            // user selection
+  resolvedMode: "light"|"dark";// after system resolution
+  setMode(m: ColorMode): void;
+  toggle(): void;
+  brand: ThemeName;
+  setBrand(b: ThemeName): void;
+};
+<PixelizeThemeProvider brand? defaultMode? storageKey? disablePersistence?>
+<ThemeSwitcher variant?="icon"|"segmented"|"menu" showBrandPicker?=false />
+```
+- Persisted to localStorage; SSR-safe (no window access during render).
+- `withTheme` keeps working unchanged (delegates to the provider internally).
+
+## Wave plan (parallel/serial split)
+- **Wave 0a — SERIAL (orchestrator).** Token restructure + shims. Pure moves, zero behavior change.
+  Gate: `tsc --noEmit` exit 0.
+- **Wave 0b — SERIAL (orchestrator).** `buildDarkPalette`, 7 dark palettes, color-mode-aware
+  `useCustomTheme`, provider/hook/switcher, componentStyles `_dark`, exports.
+  Serial because every Wave-1 agent depends on this contract.
+- **Wave 1 — PARALLEL (17 disjoint families).** Migrate the 22 hex files → tokens.
+  *Proof of independence:* each agent owns exactly one `src/Components/<Family>/` folder; the sets are
+  pairwise disjoint; **no agent touches** `src/index.ts`, `src/Theme/**`, `src/withTheme.tsx`,
+  `src/App.tsx`, `src/Layout.tsx`, `src/global.css`, or any git/npm command. No new exports needed
+  (all 22 files are in already-exported components) → shared registry untouched.
+- **Wave 2 — SERIAL.** `global.css` dark, playground demo, docs, full verify.
+
+## Files — Wave 1 lanes (22 files / 17 families, pairwise disjoint)
+| Lane | Family | Files |
+|---|---|---|
+| 1 | UserDetails | UserDetails.tsx (16), DeactivateConfirmModal.tsx (3) |
+| 2 | OrganizationDetails | OrganizationDetails.tsx (16), DeleteOrgModal.tsx (2) |
+| 3 | OrgSwitcher | OrgSwitcher.tsx (13), OrgSwitcherProps.tsx (8) |
+| 4 | RolesPermission | RolesPermission.tsx (8), DeleteRoleModal.tsx (2) |
+| 5 | Toaster | Toaster.tsx (8) |
+| 6 | StageProgress | StageProgressProps.tsx (7) |
+| 7 | PdfViewer | PdfViewer.tsx (6) |
+| 8 | CustomModulesTable | CustomModulesTable.tsx (5), DeleteModuleModal.tsx (2) |
+| 9 | CopyButton | CopyButton.tsx (5) |
+| 10 | SignInActivityTable | SignInActivityTable.tsx (5) |
+| 11 | EmptyState | EmptyState.tsx (4) |
+| 12 | FilePreview | FilePreview.tsx (4) |
+| 13 | FieldSelectModal | FieldSelectModal.tsx (3) |
+| 14 | UpgradeButton | UpgradeButton.tsx (3) |
+| 15 | MoreItems | MoreItems.tsx (2) |
+| 16 | LazyWrapper | LazyWrapper.tsx (1) |
+| 17 | ToolTip | ToolTip.tsx (1) |
+
+## Risks
+- 38 **test/story** files assert hardcoded hex → may break when components move to tokens. Handled in 3a/3b.
+- `Switch.tsx` / `InputSwitch.tsx` already call `useColorModeValue` → will finally activate under the
+  provider; verify they look right in both modes.
+- `Theme/Default/palette` imported directly by 2 DatePicker tests → keep shim path.
+- Coverage thresholds are 80% global; new provider/builder code needs tests to hold the gate.
+
+## Files-changed manifest
+(updated as waves land)