pixelize-design-library 2.3.22 → 2.4.1

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)

package/.cursor/rules

@@ -0,0 +1,31 @@
+## Session start
+- Always read CLAUDE.md before starting any task
+- Always read MODULE.md before touching a component family (`.cursor/modules/<domain>/MODULE.md`)
+- Read one similar existing component before implementing
+- Never invent a new pattern if one already exists
+
+## Implementation
+- Components live in `src/Components/<Name>/`
+- Public API via `src/index.ts` only
+- Demo pages in `src/Pages/` for playground — not published
+- Never add CRM/app-specific API calls to library components
+- Use theme tokens from `src/Theme/` — no hardcoded brand colors
+- Add Jest tests for new behavior (`*.test.tsx`)
+- Keep changes minimal — no scope creep
+
+## Output quality
+- Never create placeholder files unless explicitly asked
+- Never use fake data, lorem ipsum, example.com, or demo seeds
+- Never leave TODO comments — implement fully or report blocked
+- Production-ready components with loading/error states where applicable
+
+## Branch rules
+- Always branch from **develop** — never from main
+- Feature work: `feature/<domain>-<short-description>`
+- Bug fixes: `fix/<domain>-<short-description>`
+- Never commit directly to main
+
+## Commit rules
+- Never commit without explicit user confirmation
+- Never run git push under any condition
+- Never add Cursor co-author lines

package/.cursor/skills/task/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: task
+description: >-
+  Runs the Pixelize Design Library dev pipeline: task-plan → fe-impl → test-create → test-exec → review gate → commit. Use when the user invokes @task, /task, or requests component library delivery.
+disable-model-invocation: true
+---
+
+# Task Pipeline — Pixelize Design Library
+
+Single library repo **Micro-Components** (`pixelize-design-library`). Module docs: `.cursor/modules/<domain>/MODULE.md`.
+
+Run phases in order. Do not skip unless user opts out.
+
+```
+- [ ] 1. Task plan       (agent: task-plan)
+- [ ] 2. Implementation  (agents: fe-impl + be-impl, parallel when both needed)
+- [ ] 3a. Test creation  (agent: test-create)
+- [ ] 3b. Test execution (agent: test-exec)
+- [ ] 4. Review gate     (orchestrator — show diff, wait for user)
+- [ ] 5. Commit          (orchestrator only)
+```
+
+---
+
+## Before Starting
+
+1. Read CLAUDE.md
+2. Confirm user goal — feat / fix / refactor / chore
+3. Tell user which phases apply
+
+---
+
+## Phase 1 — Task Plan
+
+Agent: task-plan → `.cursor/agents/task-plan.md`
+
+- Read `.cursor/modules/<domain>/MODULE.md` for touched component families
+- Plan saved to `.cursor/plans/current.md`
+- If current.md already exists — read it first, user may be resuming
+
+Gate: do not start phase 2 until plan has concrete tasks.
+
+---
+
+## Phase 2 — Implementation
+
+| Plan says | Action |
+|-----------|--------|
+| Library only | Invoke fe-impl only |
+| Both | Rare — fe-impl + test agents |
+
+Pass `.cursor/plans/current.md` to each agent.
+
+If blocked mid-task:
+- Save progress to `.cursor/plans/blocked/<task-name>.md` with exact blocker details
+- Stop pipeline and report to user
+
+Gate: all required agents must report Done or Blocked before phase 3.
+
+---
+
+## Phase 3 — Tests
+
+3a: test-create → `.cursor/agents/test-create.md`
+3b: test-exec → `.cursor/agents/test-exec.md`
+
+Jest: `npm test` from repo root.
+
+Gate: do not proceed to review if tests failed and not explicitly waived by user.
+
+---
+
+## Phase 4 — Review Gate
+
+```bash
+git status
+git diff
+git diff --staged
+git log -5 --oneline
+```
+
+Run git status/diff. STOP and wait for user approval.
+
+```
+CHANGES READY TO COMMIT
+
+Backend:
+- path/to/file — what changed
+
+Frontend:
+- path/to/component — what changed
+
+Tests:
+- path/to/test — what it covers
+
+MODULE.md updates:
+- path/to/MODULE.md
+
+Excluded:
+- none
+```
+
+STOP. Wait for: "yes" / "commit" / "looks good" / "go ahead"
+
+
+## Phase 5 — Commit
+
+### Commit message format
+
+```
+<type>(<module>): <concise imperative title>
+
+Backend:
+- <specific change — file context>
+
+Frontend:
+- <specific change — file context>
+
+Tests:
+- <what is covered and where>
+
+Config:
+- <migrations, registry changes, config updates>
+```
+
+### Commit steps
+
+1. Scan diff — if .env or secrets found, warn user and ask if they want to include. Commit only on confirmation.
+2. git add relevant files — state any exclusions clearly
+3. git commit using HEREDOC — never add Cursor attribution lines
+4. If Cursor injects co-author lines — amend immediately if unpushed
+5. Verify: git status + git log -1 --format=full
+6. Show commit hash to user
+7. Move `.cursor/plans/current.md` → `.cursor/plans/done/<YYYY-MM-DD>-<title>.md`
+
+Never run git push under any condition.
+
+### Commit safety
+
+- Never --no-verify unless user explicitly requests
+- Never force-push any branch
+- Nothing staged → skip commit, report clearly
+
+---
+
+## Final Report
+
+| Phase    | Status         | Notes                             |
+| -------- | -------------- | --------------------------------- |
+| 1 Plan   | done / skipped | saved to .cursor/plans/current.md |
+| 2 Impl   | fe / be / both | done / blocked                    |
+| 3 Tests  | create / exec  | pass / fail / blocked             |
+| 4 Review | approved       | confirmed by user                 |
+| 5 Commit | done / skipped | hash if committed                 |
+
+---
+
+## User Opt-outs
+
+| User says     | Effect                                    |
+| ------------- | ----------------------------------------- |
+| "plan only"   | Stop after phase 1                        |
+| "no tests"    | Skip phase 3 — confirm with user first    |
+| "no commit"   | Stop after phase 4 review                 |
+| "commit only" | Phase 4+5 only — still show diff and wait |
+| "skip review" | Go straight to commit — confirm with user |
+

package/CLAUDE.md

@@ -0,0 +1,148 @@
+# Pixelize Design Library — Agent Guide
+
+Rules for AI assistants working in **Micro-Components** (npm: `pixelize-design-library`).
+
+## 1. App name and purpose
+
+**Pixelize Design Library** — shared React UI component library and theme system for all Pixelize frontends. Published to npm; local Vite playground demos components in `src/Pages/`.
+
+## 2. Stack
+
+| Layer         | Technology                          | Version        |
+| ------------- | ----------------------------------- | -------------- |
+| Framework     | React + TypeScript                  | 18.3.1 / 5.9.3 |
+| UI base       | Chakra UI + Emotion + Framer Motion | 2.8.2          |
+| Build         | `tsc` → `dist/` + CSS copy          | —              |
+| Dev           | Vite playground                     | 6.2.0          |
+| Styling       | Tailwind + global CSS               | 3.4.17         |
+| Tests         | Jest + Testing Library              | 29.7.0         |
+| Package       | `pixelize-design-library`           | 2.2.x          |
+
+Not a monorepo — single package, one `package.json`.
+
+## 3. Repo relationship
+
+| Repo / package              | Role                                              |
+| --------------------------- | ------------------------------------------------- |
+| **Micro-Components** (here) | Source of `pixelize-design-library` npm package   |
+| **crm-frontend**            | Consumer — `npm run pixelize` to update           |
+| **account-frontend**        | Consumer                                          |
+| **social-frontend**         | Consumer                                          |
+| **tickets-frontend**        | Consumer                                          |
+| **crm-mobile**              | Consumer (native-base overlap — check mobile)     |
+| **pixelize-authenticator**  | Companion auth UI package (separate repo)         |
+
+No backend API in this repo. Demo pages may call dev APIs for playground only.
+
+## 4. Folder structure (2 levels)
+
+```
+Micro-Components/
+├── package.json, tsconfig.json, vite.config.ts
+├── src/
+│   ├── index.ts              public exports (~110)
+│   ├── withTheme.tsx         legacy HOC wrapper (light-only, unchanged)
+│   ├── Components/           73 component families
+│   ├── Theme/
+│   │   ├── tokens/           PURE, platform-agnostic — shared with the mobile lib
+│   │   │   ├── types.ts      PaletteProps, ThemeName, ColorMode
+│   │   │   ├── primitives/   space, sizes, radii, shadows, typography, …
+│   │   │   ├── builders/     buildDarkPalette, buildBrandTokens, color math
+│   │   │   └── brands/<brand>/palette.light.ts + palette.dark.ts   (7 brands)
+│   │   ├── chakra/           WEB-ONLY binding (createBrandTheme, componentStyles, fonts)
+│   │   ├── provider/         PixelizeThemeProvider, useThemeMode, ThemeSwitcher
+│   │   ├── useCustomTheme.ts hook used by ~127 components
+│   │   └── index.ts          ThemesList (light) + brandThemes (light+dark)
+│   ├── Pages/                49 Vite demo/playground pages
+│   ├── Utils/, Hooks/, services/, types/
+│   └── App.tsx, Layout.tsx   playground shell
+├── dist/                     publish output (gitignored)
+└── .cursor/modules/          MODULE.md per component domain (22 domains)
+```
+
+### Theme rules (read before touching color)
+
+- **`Theme/tokens/**` must never import Chakra, React, or CSS.** It is copy-paste portable to the
+  mobile design library; one CSS/Chakra import breaks that. Web-only concerns (the Inter font-face
+  import, Chakra's `cssVarPrefix`) live in `Theme/chakra/`.
+- **Dark mode works by swapping which palette the theme carries** — not via `_dark`/`semanticTokens`.
+  `componentStyles` variants are functions of `({ theme })` and `useCustomTheme()` reads
+  `theme.colors`, so both follow the active palette automatically.
+- **Never hardcode a hex in a component.** Read tokens from `useCustomTheme()`, or the component
+  will be 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.
+- Dark palettes are **derived** (`buildDarkPalette`) from each brand's own light palette, so brand
+  hue carries through. Override per brand in that brand's `palette.dark.ts` if ever needed.
+- `withTheme` stays **light-only** so existing apps are visually unchanged; dark is opt-in via
+  `PixelizeThemeProvider` (defaults to `system`).
+
+## 5. Dev commands
+
+```bash
+npm start              # Vite playground
+npm run build          # tsc + copy CSS → dist/
+npm test               # Jest
+npm run test:watch
+npm run remove         # strip dev artifacts from dist before publish
+npm run package        # version patch + build + publish
+```
+
+## 6. Module / component pattern
+
+Follow the **Table** or **KanbanBoard** pattern for complex components:
+
+| Step | Path |
+| ---- | ---- |
+| Component | `src/Components/<Name>/` |
+| Subcomponents | `src/Components/<Name>/Components/` or nested folders |
+| Props/types | `<Name>Props.ts` or colocated types |
+| Tests | `*.test.tsx` next to component |
+| Stories | `*.stories.tsx` (where present) |
+| Demo page | `src/Pages/<name>.tsx` |
+| Public export | add to `src/index.ts` |
+| Module doc | `.cursor/modules/<domain>/MODULE.md` |
+
+Read `.cursor/modules/<domain>/MODULE.md` before touching a component family.
+
+## 7. Publishing integration
+
+- **Exports:** every public component must be exported from `src/index.ts`
+- **Peers:** React 18, Chakra, Emotion — consumers install alongside library
+- **Build:** `npm run build` compiles to `dist/`; never edit `dist/` directly
+- **Version:** patch releases via `npm run package`; CI publishes on merge to `develop`
+- **Breaking changes:** require version bump + consumer update in frontends
+
+## 8. Checklist — adding a new component
+
+1. Read similar component + `.cursor/modules/<domain>/MODULE.md`
+2. Create `src/Components/<Name>/` with component + props
+3. Add demo page in `src/Pages/` if needed
+4. Export from `src/index.ts`
+5. Add Jest tests (`*.test.tsx`)
+6. Update `.cursor/modules/<domain>/MODULE.md`
+7. Verify playground: `npm start`
+8. After merge to develop: consumers run `npm run pixelize` in their frontend
+
+## 9. Do
+
+- Match existing Chakra + design token patterns in `src/Theme/`
+- Keep components framework-agnostic where possible (props in, events out)
+- Add tests for new behavior
+- Use `useCustomTheme` / theme tokens — no hardcoded brand colors
+- Branch from **feature/cursor-ai-setup** or **develop**
+
+## 10. Don't
+
+- Don't add app-specific business logic (CRM entities, API calls) to library components
+- Don't break existing exports without semver major bump
+- Don't edit `dist/` — always change `src/` and rebuild
+- Don't skip `index.ts` export for public components
+- Don't introduce a second component pattern without team agreement
+- Don't commit npm tokens or `.env` secrets
+
+## Task pipeline
+
+- **Feature work:** invoke via **`/` menu → `task`** (not by typing `/task` in the message).
+- Cross-repo: **`/ → design-task**`.
+- One-time status line + hook details: [.cursor/TASK-SETUP.md](.cursor/TASK-SETUP.md).

package/README.md

@@ -191,17 +191,84 @@ function DataTable() {
 
 ## Theming
 
-The library supports custom theming through CSS variables:
-
-```css
-:root {
-  --primary-color: #007bff;
-  --secondary-color: #6c757d;
-  --success-color: #28a745;
-  --danger-color: #dc3545;
-  --warning-color: #ffc107;
-  --info-color: #17a2b8;
+The library ships **7 brand themes** (`lavender`, `meadow`, `radiant`, `skyline`, `slate`,
+`emerald`, `rosewood`), each with a **light and a dark palette**.
+
+### Existing apps (unchanged)
+
+`withTheme` is the original default export and still renders **light only**. Upgrading the package
+changes nothing visually:
+
+```tsx
+import withTheme, { ThemesList } from 'pixelize-design-library';
+
+export default withTheme(App, ThemesList.lavender);
+```
+
+### Opting into light / dark / system
+
+Wrap the app in `PixelizeThemeProvider` instead. It defaults to **`system`** (follows the OS) and
+persists the user's choice to `localStorage`.
+
+```tsx
+import { PixelizeThemeProvider, ThemeSwitcher } from 'pixelize-design-library';
+
+function Root() {
+  return (
+    <PixelizeThemeProvider brand="lavender" defaultMode="system">
+      <App />
+    </PixelizeThemeProvider>
+  );
 }
+
+// Drop the switcher anywhere inside the provider:
+<ThemeSwitcher />                                    // icon toggle
+<ThemeSwitcher variant="segmented" />                // Light / System / Dark
+<ThemeSwitcher variant="menu" showBrandPicker />     // + brand picker
+```
+
+| `PixelizeThemeProvider` prop | Default | Meaning |
+| ---------------------------- | ------- | ------- |
+| `brand` | `"lavender"` | Which brand theme to use |
+| `defaultMode` | `"system"` | `"light"` \| `"dark"` \| `"system"` |
+| `storageKey` | `"pixelize-theme"` | localStorage key |
+| `disablePersistence` | `false` | Don't read/write localStorage |
+
+### Reading or changing the theme in code
+
+```tsx
+import { useThemeMode, useCustomTheme } from 'pixelize-design-library';
+
+const { mode, resolvedMode, setMode, toggle, brand, setBrand } = useThemeMode();
+const theme = useCustomTheme(); // returns the palette for the ACTIVE color mode
+```
+
+`useCustomTheme()` returns the dark palette automatically in dark mode, so components that read
+their colors from it are dark-aware with no extra work.
+
+### Building components
+
+Read colors from the theme — never hardcode a hex, or the component will be stuck in light mode:
+
+```tsx
+const theme = useCustomTheme();
+<Box bg={theme.colors.background[50]} color={theme.colors.text[900]} />  // ✅ adapts
+<Box bg="#ffffff" color="#26213c" />                                     // ❌ breaks in dark
+```
+
+`colors.white` is a **foreground** token (the label on a filled button) and stays white in dark
+mode. For a white **surface**, use `colors.background[50]`.
+
+### Design tokens (shared with the mobile library)
+
+`lightPalettes`, `darkPalettes`, `palettes`, `themeNames`, and `buildDarkPalette` are exported for
+apps that build custom themes. The token source (`src/Theme/tokens/`) is pure TypeScript with no
+Chakra, React, or CSS imports, so it is portable to React Native.
+
+```ts
+import { lightPalettes, buildDarkPalette } from 'pixelize-design-library';
+
+const myDark = buildDarkPalette(lightPalettes.emerald);
 ```
 
 ## TypeScript Support