pixelize-design-library 2.3.22 → 2.4.1

package/.cursor/modules/playground/MODULE.md

@@ -0,0 +1,28 @@
+# Playground
+
+## Purpose
+
+Vite dev playground — demo pages not published to npm.
+
+## Key paths
+
+- `src/Pages/` (49 demo files), `src/App.tsx`, `src/Layout.tsx`
+- `npm start` launches playground
+
+## Key rules
+
+- Demo API calls to dev.pixelizetech.com are playground-only
+- Not included in `dist/` publish output
+
+## Recent changes (WCAG contrast + dark-mode pass)
+
+- `stageProgress.tsx`, `tier1.tsx`, `upgradeButton.tsx`, `orgSwitcher.tsx`: local `Section` demo
+  wrapper switched from hardcoded `bg="white"` / `border="1px solid #E2E8F0"` / `color="gray.700"`
+  to `useCustomTheme()` tokens (`background[50]` / `boxborder[300]` / `text[900]`) — previously
+  stayed white regardless of the active theme.
+- `stageProgress.tsx` (4 captions) and `tier1.tsx` (1 caption): `color="gray.400"` →
+  `theme.colors.gray[500]`, the library's verified muted-text token (`gray.400` fails contrast in
+  dark mode).
+- `card.tsx`: swapped the raw Chakra `Button` (`color="blue"`) for the library's own `Button`
+  (`colorScheme="primary"`) — a component-choice fix, not a Section/caption token pass.
+- Demo-only — no `src/index.ts` export or library API changed.

package/.cursor/modules/table/MODULE.md

@@ -0,0 +1,78 @@
+# Table
+
+## Purpose
+
+Data table with virtualization, filters, pagination, column management.
+
+## Key paths
+
+- `src/Components/Table/`, `Table/components/`, `Table/settings/`, `Table/filters/`, `Table/hooks/`
+- Tests: `components/TableBody.virtualize.test.tsx`, `settings/ManageColumns.test.tsx`
+
+## Key rules
+
+- Core CRM list UI — high change frequency
+- `src/Utils/table.ts` helpers
+
+## Dark mode
+
+Surfaces read `theme.colors.background[50]` via `useCustomTheme()`, so the table follows the
+active palette: `Table` (pagination popover), `TableBody` (expanded-row panel), `CompactSelect`
+(trigger), `LeftFilterPane` (pane + apply/clear footer).
+
+- **`white` is a foreground token, not a surface.** It stays `#fff` in dark, so `bg="white"` /
+  `bg={theme.colors.white}` renders a white slab on the dark canvas — that was the defect this
+  migration fixed. Use `background[50]` (`#ffffff` light, dark-aware) for any surface.
+  `color="white"` on the filter-count badge is correct — it is a label on `primary[500]`.
+- Chakra scale literals (`borderColor="gray.200"`, `_hover={{ bg: "gray.50" }}`) are **already
+  dark-aware** — `createBrandTheme` passes `colors: palette`, so they resolve against the
+  swapped palette. Only for scales the palette defines: `whiteAlpha`/`blackAlpha` are not in it,
+  so they keep Chakra's fixed rgba — `TableGroupRow`'s `_hover={{ bg: "whiteAlpha.500" }}` is
+  still a white wash in dark.
+- `LeftFilterPane` takes `theme` as a **prop** (from `Table`), not from the hook — pass it down.
+
+## WCAG contrast pass (this session)
+
+- `HeaderActions` action-list ink and `TableHeader`'s sort-chevron hover ink + column-header ink
+  now use `accentTextOnCanvas(secondary, canvas)` (from `Theme/tokens/builders/accentText`)
+  instead of a bare `colors.secondary?.[500]` — picks a text color that clears AA against the
+  actual canvas instead of assuming secondary-on-white always passes. Relies on the shared
+  `accentText.ts` guard (theme module) to stay crash-safe when `secondary`/canvas are undefined.
+- `TableBody`'s `StatusCell` ink is no longer hardcoded `white` — it resolves
+  `statusColor.onSolid ?? onFilled(statusColor.solid, white, black)` so the label clears AA
+  against light and dark status fills alike; falls back for callers whose `statusColor` predates
+  `onSolid`.
+- `TableRenderGroup.color` gained an optional `onSolid?: string` (additive, non-breaking).
+- `LeftFilterPane`'s `SectionLabel` tooltip swapped Chakra `Tooltip` → design-library `ToolTip`
+  (drops the manual `bg`/`color`/`theme`-prop overrides — `ToolTip` themes itself).
+- **Filter-sidebar `ModalContent` surface bug (QA-caught, blocking):** `Table.tsx`'s mobile
+  filter-sidebar modal had no explicit `bg=` on `ModalContent`, hitting the same
+  Chakra-hardcoded-`colors.white`-behind-`_dark` bug as `Modal`/`AlertDialog`/`Drawer` (overlays,
+  layout-navigation modules). Fixed with `bg={theme.colors?.background?.[50]}`.
+  `TableSettings.tsx`'s `MotionModalContent` already had this fix from an earlier pass.
+- **`LeftFilterPane`'s date filter (user-reported, blocking):** `LeftFilterPane.tsx` imports the
+  legacy `DatePicker/DatePicker.tsx` directly (not the public `ThemeDatePicker` export) — its
+  `PopoverContent` had the identical missing-`bg=` bug, fixed alongside the other three date/time
+  pickers (see `inputs-date-file` MODULE.md). It's easy to assume this file is dead because the
+  playground's `datePick.tsx` import of it is commented out — it isn't; `LeftFilterPane` is a real
+  consumer.
+- **Row hover invisible in dark mode (QA-reported, fixed):** `TableBody`'s per-cell `_hover`
+  painted `table.hover[300]`, a token built for a light-mode white canvas — in dark mode that rung
+  sits within ~10 lightness points of the near-black canvas (both compressed near L7-15), computing
+  to ~1.2:1 contrast (verified numerically), i.e. no visible hover at all. Fixed via a new pure
+  helper, `getTableRowHoverStyle(colors, isDark)` (`components/tableRowHoverStyle.ts`, same pattern
+  as `Editor/joditThemeVars.ts`): dark mode now fills with `background[900]` (this palette's dark-
+  mode "bright highlight" rung, ~9.7-10.7:1 against the canvas across brands) **and** flips `color`
+  to `backgroundColor.main`, since the row's resting ink (`text[500]`) is tuned for a near-black
+  backdrop and would go illegible against a bright fill — mirrors how Jodit's own dark-mode hover
+  rule flips text to its canvas color alongside a brighter fill. Light mode is untouched
+  (`table.hover[300]`, same as before). Regression tests: `tableRowHoverStyle.test.ts` (lavender +
+  rosewood). Scoped to the per-cell hover mechanism already in place — not restructured to a
+  `<Tr>`-level highlight, since that wasn't the reported defect.
+- **Known gap (found by code review, not fixed this pass):** `Table/filters/CompactSelect.tsx`,
+  `Table/filters/TableFilters.tsx`, and `Table/components/TableActions.tsx` each render a raw
+  Chakra `PopoverContent` with no `bg=` — the identical bug class just fixed in `Table.tsx`'s
+  filter-sidebar modal, `FilterSidebar.tsx`'s two price popovers (layout-navigation module), and
+  `Modal`/`AlertDialog`/`Drawer` (overlays module). Not in this session's diff and not covered by
+  any test, so deliberately deferred rather than expanding this pass's scope — worth a follow-up
+  ticket to make the `ModalContent`/`PopoverContent`/`MenuList` sweep exhaustive across the repo.

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

@@ -0,0 +1,314 @@
+# 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."
+
+## 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`