pixelize-design-library 2.3.22 → 2.4.1-beta.2

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

@@ -0,0 +1,431 @@
+# Theme
+
+## Purpose
+
+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/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
+
+- **`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."
+
+**2026-07-20 — `PixelizeThemeProvider` gained an optional `themeOverrides` prop.** Found while
+wiring dark mode into the **tickets** consumer app: it has its own font-stack/compact-control-size/
+component-defaultProps customizations layered onto the brand theme (the old `withTheme(app, theme)`
+pattern spread these onto `ThemesList[brand]` directly), and `PixelizeThemeProvider` had no
+equivalent injection point — its internal `ChakraProvider` is hardcoded to
+`brandThemes[brand][resolvedMode]`. Without this, every consumer app with its own theme
+customizations would have had to build the same workaround (mount its own second `ChakraProvider`
+inside the provider's tree, shadowing the internal one). `themeOverrides?: Record<string, unknown>`
+is deep-merged via `extendTheme(brandThemes[brand][resolvedMode], themeOverrides)`, re-computed
+whenever `brand`/`resolvedMode`/`themeOverrides` change so overrides always layer onto the *current*
+palette. Safe post-resolution: `createBrandTheme` already fixes `config.initialColorMode` to
+`"light"` on every palette, and `extendTheme` is a pure additive merge that doesn't re-derive
+`_dark:` blocks — so this cannot reintroduce the double-adaptation bug the forced light
+`colorModeManager` avoids. Optional, defaults to `undefined` — zero behavior change for existing
+consumers that don't pass it.
+
+**2026-07-20 — `PixelizeThemeProvider` re-syncs `brandState` when the `brand` prop changes post-mount.**
+`brandProp` previously only seeded initial state (`useState(brandProp)`), so a consumer that
+re-renders with a new `brand` after mount (e.g. persisting the pick through its own Redux store
+instead of calling this provider's own `setBrand`) never saw it applied — the same gap `mode`
+already had, worked around elsewhere by callers mirroring it in an effect. Fixed with a `useEffect`
+on `brandProp` (skipping the first run, so it doesn't fight the rehydrate-from-storage effect) that
+calls `setBrandState(brandProp)` only when the **prop itself** changes — not on every local
+`setBrand()` call, so it doesn't fight the user's own in-session `ThemeSwitcher` picking.
+
+**2026-07-20 — `ThemeSwitcher`'s brand menus gained a color swatch dot per brand.** `BrandMenu`
+(icon variant) and `MenuVariant`'s brand submenu both previously showed only the brand name text.
+Each option now renders a small (`0.625rem`) filled circle before the label, colored from that
+brand's own `colors.primary[500]` in **light** mode (`brandThemes[brand].light...primary[500]`) —
+always the light-mode anchor regardless of the switcher's current mode, so the dot is a stable
+brand identifier rather than something that itself flips with dark mode. `ThemeSwitcher.tsx` also
+stopped re-deriving `menuBg`/pushing it back via `sx` on every render (`useSwitcherColors()`) now
+that `Menu.styles.ts` (Wave G) supplies `--menu-bg` centrally — removes a redundant Emotion style
+recompute per render that showed up as flicker while hovering/scrolling the brand list.
+
+## Wave G — global `Menu` component style override (`--menu-bg`), found while auditing tickets
+
+Same bug class as Wave E's `ThemeSwitcher` fix, but at the root instead of per-call-site: Chakra's
+own `Menu` baseStyle hardcodes the `--menu-bg` CSS var to `"#fff"` (gated behind `_dark`, which this
+app's theme-swap never triggers — `PixelizeThemeProvider`'s forced-light `colorModeManager`, Wave D
+above). Every **bare** `<MenuList>` in every consuming app (tickets' board overflow menu,
+`TicketOptionMenu`, rows-per-page menu, etc.) rendered a white dropdown on a dark canvas, and a
+call-site `bg=` prop alone doesn't fix it — that only recolors the list's own box, not the CSS var
+`MenuItem`'s `_focus`/`_active`/`_expanded` states read.
+
+Added `src/Theme/chakra/Menu.styles.ts` (new file, registered in `componentStyles.ts`): a
+`definePartsStyle` override on the `list` anatomy part that sets `--menu-bg` (via `cssVar`) to
+`theme.colors.backgroundColor?.light ?? theme.colors.background?.[50] ?? "#fff"` and `color` to
+`theme.colors.text?.[900]`. This fixes every consumer's bare `MenuList` app-wide with zero
+per-call-site changes — `ThemeSwitcher`'s existing manual `bg=`/`sx={{"--menu-bg": ...}}` workaround
+(Wave E) still works alongside it (an explicit call-site override still wins), it's just no longer
+required for a plain `<MenuList>`. Verified: `tsc --noEmit` clean, lint clean, full `jest` suite
+905/905 (72 suites, up from 902/72 pre-fix — 3 new but this pass added no dedicated `Menu.styles`
+test, the count reflects unrelated in-flight suite growth).
+
+## Wave H — `Popover`/`Skeleton` component-style overrides + native UI `color-scheme`, same audit as Wave G
+
+Same bug class as Wave G's `Menu` fix, found while sweeping the rest of Chakra's own component
+themes for the identical `_dark`-gated hardcoded-white pattern — plus one new bug *class* (native
+browser chrome) the earlier waves never covered.
+
+- **`Popover`** — Chakra's own Popover baseStyle hardcodes `--popper-bg` to `"colors.white"` and
+  `--popper-arrow-shadow-color` to `"colors.gray.200"`, both gated behind `_dark` (confirmed by
+  reading `@chakra-ui/theme`'s `popover.mjs` source directly — `content` is the anatomy part that
+  owns both vars; `--popper-arrow-bg` is untouched because Chakra's own baseStyle already points it
+  at `$popperBg`, so fixing `$popperBg` fixes the arrow fill for free). Every bare
+  `<PopoverContent>` rendered a white card with a light arrow shadow on the dark canvas. Added
+  `src/Theme/chakra/Popover.styles.ts` (new file, registered in `componentStyles.ts`) mirroring
+  `Menu.styles.ts` exactly: `createMultiStyleConfigHelpers(popoverAnatomy.keys)` +
+  `definePartsStyle` on the `content` part, `[$popperBg.variable]` sourced from
+  `theme.colors.backgroundColor?.light ?? theme.colors.background?.[50] ?? "#fff"` (identical
+  fallback chain to Menu) and `[$arrowShadowColor.variable]` from `theme.colors.border?.[200]`.
+- **`Skeleton`** — Chakra's own Skeleton baseStyle hardcodes `--skeleton-start-color`/
+  `--skeleton-end-color` to `colors.gray.100`/`colors.gray.400`, same `_dark`-gated pattern.
+  Verified in `@chakra-ui/react`'s actual `skeleton.mjs` that Chakra's `Skeleton` is a
+  **single-part** style config (`defineStyleConfig`, not a multi-part anatomy like Menu/Popover),
+  and that its `startColor`/`endColor` are **props**, not style-config keys — but those props only
+  ever populate the same two CSS vars when a caller actually passes them (`useToken("colors", ["",
+  ""])` resolves to `undefined`, so `cssVarStyles` stays empty and the base style's vars pass
+  through untouched). That confirms Chakra's own prop-vs-style precedence already does the right
+  thing, so the fix was made at the `componentStyles.ts` level (a `Skeleton: ComponentStyleConfig`
+  entry, same file as `Badge`/`FormError`) rather than touching `Components/Skeletons/Skeletons.tsx`
+  — zero risk to the existing prop passthrough there; a caller-supplied `startColor`/`endColor`
+  still wins exactly as before. Rungs: `gray[100]`/`gray[300]` — `buildDarkPalette.ts`'s `gray`
+  ramp is already role-reversed for dark mode (low rungs go dark, high rungs go light there), so
+  the same two rung indices read as a light shimmer in light mode and a subtle dark-on-dark shimmer
+  in dark mode with no mode branching needed in the override itself.
+- **`color-scheme` CSS property (new bug class)** — native browser UI (the `<select>` popup
+  chrome, the `<input type="date">` calendar picker) is painted by the browser's own UA stylesheet
+  keyed off the CSS `color-scheme` property, entirely outside Chakra/React theming — no component
+  style or palette swap can reach it, which is why this wasn't caught by any earlier wave's
+  component-by-component audit. Neither repo set it anywhere, so that native chrome always rendered
+  light regardless of the app's resolved mode. Fixed in `PixelizeThemeProvider.tsx` with a
+  `useEffect` that sets `document.documentElement.style.colorScheme = resolvedMode` whenever
+  `resolvedMode` changes. Scoped to the provider (not a global stylesheet or index.css rule) so
+  `withTheme` consumers — deliberately light-only per this doc's "Key rules" — see no change;
+  only `PixelizeThemeProvider`/`useThemeMode` consumers get mode-aware native chrome.
+- Full gate green: `tsc --noEmit` clean, lint clean, `jest` 905/905 (72 suites, unchanged from
+  pre-Wave-H — no new dedicated test file added for these three, consistent with Wave G's Menu fix
+  which also shipped without one).
+
+## Wave I — remaining `_dark`-gated component overrides (Modal/Drawer/Avatar/Tabs/Slider/Switch/Tooltip)
+
+Completes the Wave G/H sweep: every other Chakra component whose own baseStyle hardcodes a
+literal behind the never-triggered `_dark` gate (or, for Slider/Switch, no gate at all), fixed
+the same way — a `definePartsStyle`/`ComponentStyleConfig` override registered in
+`componentStyles.ts`, sourcing color from `theme.colors.backgroundColor?.light ?? theme.colors
+.background?.[50]` (or the relevant token) instead of Chakra's literal. See each domain
+MODULE.md for the consumer-facing detail: `Modal`/`Drawer` (overlays, layout-navigation —
+supersedes those modules' earlier per-call-site `bg=` fixes), `Avatar` (account-management),
+`Tabs` (table), `Slider`/`Switch` (inputs-toggle), `Tooltip`/`Skeleton` (overlays, feedback —
+`Tooltip` pins `black`/`white`, the two tokens `buildDarkPalette` never remaps, since a tooltip
+must stay a stable dark chip in either mode rather than following the canvas).
+`componentStyles.ts` now registers 10 chakra-native theme keys total (`Drawer`, `Menu`, `Modal`,
+`Popover`, `Slider`, `Switch`, `Tabs`, `Avatar`, `Skeleton`, `Tooltip`) alongside the library's
+own `Checkbox`/`Input`/`Button`/`Badge`/`FormError`/etc.
+
+## 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/types-exports/MODULE.md

@@ -0,0 +1,17 @@
+# Types & Exports
+
+## Purpose
+
+Public API surface — semver-sensitive.
+
+## Key paths
+
+- `src/index.ts` (~80 value exports + typed Props groups for UserDetails, RolesPermission, CustomModulesTable, SignInActivityTable, OrganizationDetails)
+- `src/types/`
+- `src/withTheme.tsx`
+
+## Key rules
+
+- Every public component must be exported here
+- Breaking export changes require major version bump
+- Run `npm run build` after export changes

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

@@ -0,0 +1,50 @@
+# Utility UI
+
+## Purpose
+
+Generic standalone UI helpers: CopyButton, ScrollToTop, LazyWrapper, MoreItems, EmptyState, PdfViewer, FilePreview, FieldSelectModal, ProfilePhotoViewer, StageProgress.
+
+## Key paths
+
+- `src/Components/CopyButton/`, `ScrollToTop/`, `LazyWrapper/`, `MoreItems/`, `EmptyState/`, `PdfViewer/`, `FilePreview/`, `FieldSelectModal/`, `ProfilePhotoViewer/`, `StageProgress/`
+
+## Key rules
+
+- 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

@@ -0,0 +1,35 @@
+# Utils & Hooks
+
+## Purpose
+
+Shared utilities and hooks: debounce, table helpers, preferences, ref merging,
+truncation detection.
+
+## Key paths
+
+- `src/Utils/table.ts`, `src/Utils/mergeRefs.ts`, `src/Hooks/usePreferences.ts`,
+  `src/Hooks/useIsTruncated.ts`, `src/services/feedback.ts`
+
+## Key rules
+
+- `debounce` exported from index.ts
+- **`useIsTruncated(content?, enabled?)`** (exported) — returns `{ ref, isTruncated }`;
+  attach `ref` to a clamped element to detect real overflow (`scrollWidth/Height`
+  vs `clientWidth/Height`, single- and multi-line). Re-measures on mount, element
+  resize (`ResizeObserver`), and `content` change — never on hover/scroll. Pass
+  `enabled=false` to make it fully inert. Powers `ToolTip overflowOnly` (see
+  `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/pixelize-task-statusline.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Local status line only — never sent to the model. See .cursor/TASK-SETUP.md
+set -euo pipefail
+
+STATE_FILE="${HOME}/.cursor/pixelize-skill-session-state.json"
+
+payload=$(cat)
+dir=$(echo "$payload" | jq -r ".cwd // .workspace.current_dir // empty")
+session_id=$(echo "$payload" | jq -r ".session_id // empty")
+base=$(basename "$dir")
+
+show_no_skill_warning=false
+if [[ -n "$session_id" && -f "$STATE_FILE" ]]; then
+  if jq -e --arg id "$session_id" '.[$id].chatting_without_skill == true' "$STATE_FILE" >/dev/null 2>&1; then
+    show_no_skill_warning=true
+  fi
+fi
+
+case "$base" in
+  account-frontend|account-service)
+    line1="/ → task  (Account FE + BE)"
+    line2=""
+    ;;
+  crm-frontend|crm-service)
+    line1="/ → task  (this repo)"
+    line2="/ → crm-task  (CRM FE + BE)"
+    ;;
+  social-frontend|social-service)
+    line1="/ → task  (this repo)"
+    line2="/ → social-task  (Social FE + BE)"
+    ;;
+  tickets-frontend)
+    line1="/ → task  (this repo)"
+    line2="/ → tickets-task"
+    ;;
+  crm-mobile)
+    line1="/ → task  (this repo)"
+    line2="/ → crm-mobile-task"
+    ;;
+  Micro-Components)
+    line1="/ → task  (this repo)"
+    line2="/ → design-task"
+    ;;
+  hrms)
+    line1="/ → task  (this repo)"
+    line2="/ → hrms-task  (HRMS FE + BE)"
+    ;;
+  *)
+    line1="Open a Pixelize repo root for / → task"
+    line2=""
+    ;;
+esac
+
+if [[ "$show_no_skill_warning" == "true" ]]; then
+  echo -e "\033[1;33m\033[7m  ⚠  CHATTING WITHOUT TASK SKILL — use / menu  ⚠  \033[0m"
+  echo -e "\033[1;33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m"
+fi
+
+echo -e "\033[1;33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m"
+echo -e "\033[1;33m  FEATURE WORK → $line1\033[0m"
+if [ -n "$line2" ]; then
+  echo -e "\033[1;33m  Full pipeline → $line2\033[0m"
+fi
+echo -e "\033[1;33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m"

package/.cursor/plans/current.md

@@ -0,0 +1,12 @@
+# Fix Kanban collapsed column reset on drag
+
+## Problem
+`collapsedColumns` is re-hydrated from stale `kanbanPreferencesJson` whenever `mergedColumns` changes (e.g. after drag when parent updates `data`).
+
+## Solution
+1. Hydrate `collapsedColumns` from preferences **once** (when prefs load and columns exist).
+2. On `mergedColumns` change, only **prune** keys for removed columns — never re-apply saved prefs.
+
+## Files
+- `src/Components/KanbanBoard/KanbanBoard.tsx`
+- `src/Components/KanbanBoard/KanbanBoard.test.tsx`