pixelize-design-library 3.0.1-beta.1 → 3.1.0

package/MIGRATION.md

@@ -1,562 +0,0 @@
-# Pixelize v3 migration guide
-
-This guide covers upgrading from the Chakra UI–based v2 to the Tailwind + Radix v3.
-
-> **TL;DR** — replace Chakra props with the new shadcn-style props, import the v3 CSS once at app root, swap `ThemeProvider`/`useCustomTheme()` for the new `ThemeProvider`/`useTheme()`, and treat `Select` consolidation + `Modal → Dialog` as the two biggest API changes.
-
----
-
-## 1. Installation
-
-### Remove
-
-```bash
-npm uninstall @chakra-ui/react @emotion/react @emotion/styled
-```
-
-### Add (already present after `npm install`)
-
-```bash
-# Runtime
-npm install \
-  class-variance-authority clsx tailwind-merge \
-  @radix-ui/react-accordion @radix-ui/react-alert-dialog \
-  @radix-ui/react-avatar @radix-ui/react-checkbox \
-  @radix-ui/react-dialog @radix-ui/react-dropdown-menu \
-  @radix-ui/react-label @radix-ui/react-popover \
-  @radix-ui/react-progress @radix-ui/react-radio-group \
-  @radix-ui/react-select @radix-ui/react-separator \
-  @radix-ui/react-slider @radix-ui/react-slot \
-  @radix-ui/react-switch @radix-ui/react-tabs \
-  @radix-ui/react-tooltip \
-  cmdk date-fns sonner
-
-# Dev
-npm install -D tailwindcss @tailwindcss/typography tailwindcss-animate autoprefixer postcss
-```
-
-### Tailwind config
-
-Copy the library's `tailwind.config.ts` settings (or extend your own) so the CSS variables map to color utility classes:
-
-```ts
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-
-export default {
-    darkMode: "class",
-    content: ["./src/**/*.{ts,tsx}"],
-    theme: {
-        extend: {
-            colors: {
-                primary: {
-                    DEFAULT: "hsl(var(--color-primary) / <alpha-value>)",
-                    foreground: "hsl(var(--color-primary-foreground) / <alpha-value>)",
-                },
-                // … repeat for secondary, background, foreground, card, muted, accent, destructive, success, warning, border, input, ring
-            },
-            borderRadius: { lg: "var(--radius)" },
-        },
-    },
-    plugins: [require("tailwindcss-animate")],
-} satisfies Config;
-```
-
----
-
-## 2. Required CSS imports
-
-Import once in your app entry (e.g. `main.tsx`):
-
-```ts
-// Tailwind directives
-import "./index.css"; // contains @tailwind base; components; utilities;
-
-// Library tokens
-import "pixelize-design-library/src/theme-v2/tokens.css";
-import "pixelize-design-library/src/theme-v2/dark.css";
-
-// Optional preset (pick one)
-import "pixelize-design-library/src/theme-v2/presets/default.css";
-// or "meadow", "rosewood", "skyline", "slate", "emerald", "radiant"
-```
-
-The dark-mode tokens activate automatically when `<html>` has the `.dark` class. Preset tokens activate when `<html>` has the matching `data-theme="..."` attribute. **`ThemeProvider` writes both for you** — you don't toggle them by hand.
-
----
-
-## 3. ThemeProvider setup
-
-```tsx
-// app entry
-import {
-    ThemeProvider,
-    Toaster,
-} from "pixelize-design-library";
-
-import "./index.css";
-import "pixelize-design-library/src/theme-v2/tokens.css";
-import "pixelize-design-library/src/theme-v2/dark.css";
-import "pixelize-design-library/src/theme-v2/presets/default.css";
-
-createRoot(document.getElementById("root")!).render(
-    <ThemeProvider defaultTheme="default" defaultMode="system">
-        <App />
-        <Toaster />
-    </ThemeProvider>,
-);
-```
-
-`ThemeProvider` already mounts a global `TooltipProvider`, so you do not need to wrap separately.
-
----
-
-## 4. Component mapping table
-
-| Old (v2 / Chakra)        | New (v3)                                               | Notes                                                                                                                                   |
-| ------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `Modal`                  | `Dialog` (`Modal` still works as a compat shim)        | See §6.                                                                                                                                 |
-| `Drawer` (old Chakra)    | `Drawer`                                               | API is now `side` + `size` (sm/md/lg/full).                                                                                             |
-| `AlertDialog`            | `AlertDialog`                                          | Cannot dismiss via outside-click (matches Radix semantics).                                                                              |
-| `Select`                 | `Select`                                               | See §5 — consolidated.                                                                                                                  |
-| `SearchSelect`           | `Select searchable`                                    | Same component, set `searchable`.                                                                                                       |
-| `SelectSearch`           | `Select searchable creatable`                          | Same component, add `creatable + onCreateOption`.                                                                                       |
-| `MultiSelect`            | `Select multiple`                                      | Same component, set `multiple`.                                                                                                         |
-| `Checkbox`               | `Checkbox`                                             | Now uses `checked` / `onCheckedChange` (Radix). Boolean `checked` or `"indeterminate"`.                                                  |
-| `RadioButton(Group)`     | `RadioGroup` / `RadioGroupItem`                        | Use `value` + `onValueChange`.                                                                                                          |
-| `Switch`                 | `Switch`                                               | Use `checked` + `onCheckedChange`.                                                                                                      |
-| `Button`                 | `Button`                                               | `colorScheme` → `variant`. `isLoading` retained. `leftIcon` / `rightIcon` accept any ReactNode (Lucide icons work).                      |
-| `TextInput`              | `TextInput`                                            | Props largely retained. `error` is now boolean + `errorMessage`. Floating label via `variant="floating"`. `isInformation` → `informationMessage`. |
-| `InputTextArea`          | `Textarea` (primitive) or `Field` + `Textarea`         | `Textarea` supports `autoResize`, `minRows`, `maxRows`.                                                                                 |
-| `NumberInput`            | `NumberInput`                                          | Now type=text + inputmode=decimal under the hood; arrows + clamp on blur.                                                              |
-| `DatePicker`             | `DatePicker`                                           | Full rewrite (date-fns, fully a11y-correct calendar grid).                                                                              |
-| `PinInput`               | `PinInput`                                             | Auto-advance, paste-to-fill, `mask` for OTP.                                                                                            |
-| `Slider`                 | `Slider`                                               | Single value OR range (pass an array). `marks` + `showTooltip`.                                                                         |
-| `FileUploader`           | `FileUploader`                                         | Built on react-dropzone with theme-aware drag/error states.                                                                             |
-| `ContactForm`            | `ContactForm`                                          | Built-in validation, isLoading state, success state.                                                                                    |
-| `FeedbackForm`           | `FeedbackForm`                                         | 5-star rating + optional comment.                                                                                                       |
-| `Table`                  | `Table`                                                | Generic-typed (`<Table<MyRow>>`). New unified API — see §4a.                                                                             |
-| `Sidebar` (`SideBar`)    | `Sidebar`                                              | Collapsed + mobile drawer modes; pure CSS responsive (no JS sizing).                                                                    |
-| `NavigationBar`          | `NavigationBar`                                        | New `globalSearch`, `notificationCount`, `userMenuItems`, `showThemeSwitcher` props.                                                    |
-| `Breadcrumbs`            | `Breadcrumbs`                                          | `items` is now `{ label, href?, onClick? }[]`, `maxItems` collapses middle.                                                            |
-| `Toaster` + `useToaster` | `Toaster` + `toast`                                    | Now built on `sonner`. `toast.success(...)` etc. No more `useToaster()` hook.                                                           |
-| `ProgressBar`            | `Progress`                                             | `value` is the percentage. `size` controls thickness.                                                                                   |
-| `ProfileCard`            | _Removed_ — compose from `Avatar`, `Badge`, `Card`     | The old composite was rarely a clean fit; assemble what you need.                                                                       |
-| `Card` (Chakra)          | Plain `<div className="rounded-lg border border-border bg-card p-4">` | No need for a component wrapper — use the token classes.                                                                                  |
-| `Tag`                    | `Tag`                                                  | `label`, `onRemove`, `variant`, `size`, `icon`.                                                                                         |
-| `TableToggle` / `Toggle` | `TableToggle` / `Toggle`                               | Now an ARIA toggle button, not a `Switch`.                                                                                              |
-| `Notification`           | `Notification`                                         | Card item for feeds — unread border, dismiss button, action slot.                                                                       |
-| `Timeline`               | `Timeline`                                             | `items` with `variant` per item, `state: 'past' \| 'current' \| 'future'` for dashed connector.                                          |
-| `KanbanBoard`            | `KanbanBoard`                                          | Kept `@hello-pangea/dnd`. Now typed; `onCardMove` receives `{ cardId, fromColumnId, toColumnId, newIndex }`.                            |
-| Apex chart components    | `BarChart` / `LineChart` / `AreaChart` / `PieChart` / `PolarChart` | Theme-aware via `useChartTheme()`.                                                                                                      |
-| `Loading`                | `Loading`                                              | Variants: `spinner` (inline), `overlay` (full screen), `skeleton`.                                                                      |
-| `Skeletons`              | `Skeleton`                                             | Variants: `text`, `circle`, `rectangle`.                                                                                                |
-| `withTheme` HOC          | `ThemeProvider`                                        | Drop the HOC — wrap once at app root.                                                                                                   |
-
----
-
-## 4a. Table prop renames
-
-The Table is generic-typed and has a new prop surface. Every consumer using `<Table>` will get TypeScript errors. Use this table to translate.
-
-### Data shape
-
-| Old | New |
-| --- | --- |
-| `data: DataObject[]` (untyped, used `id` + `content` + per-row callbacks) | `data: T[]` (your own row type) + `rowKey: keyof T \| (row: T) => string \| number` |
-| `columns: TableHeaderProps[]` with `label` / `key` / `render` | `columns: ColumnDef<T>[]` with `id` / `header` / `accessorKey` / `accessorFn` / `cell` |
-
-### Prop renames
-
-| Old prop | New prop |
-| --- | --- |
-| `isPagination` | `pagination` |
-| `noOfRowsPerPage` | `defaultPageSize` |
-| `paginationSelectOptions` | `pageSizeOptions` |
-| `totalRecords` | `totalCount` |
-| `onPagination(page, rows, record, direction)` | `onPageChange(page, pageSize)` |
-| `onNoOfRowsPerPageChange` | folded into `onPageChange` |
-| `isCheckbox` | `selectable` |
-| `selections` | `selectedRows` |
-| `onSelection(keys)` | `onSelectionChange(keys)` |
-| `onGlobalSearch(query)` | `onSearchChange(query)` (set `isServerSearch` to disable client filter) |
-| `onColumnFilter(filters)` | `onFilterChange(filters)` |
-| `isLoading` | same |
-| `loadingSkeletonRows` | `loadingRowCount` |
-| `headerBgColor` / `freezedBgColor` / `headerTextColor` / `freezedTextColor` / `tableBorderColor` | _removed_ — restyle via the `className` prop or by overriding the relevant CSS variables |
-| `noBorders` | same |
-| `tableMaxHeight` | `maxHeight` |
-| `minVisibleRows` / `maxVisibleRows` / `autoFitViewport` | _removed_ — set `maxHeight` and let the table scroll internally |
-| `defaultVisibleColumns: number` | `defaultHiddenColumns: string[]` (list of column ids) |
-| `isVisiblity` | `showColumnToggle` |
-| `isActionFreeze` | _removed_ — use `column.sticky: 'left' \| 'right'` per-column |
-| `headerActions` (Chakra-shaped object) | `headerActions: ReactNode` (compose your own toolbar slot) + `bulkActions` for selection-driven actions |
-| `tableSettings` | `showColumnToggle` + `preferences` |
-| `filterSidebar.isFilterSidebar` | `filterSidebar.enabled` |
-| `filterSidebar.handleSidebarFilterClick` | `filterSidebar.onApply` |
-| `filterSidebar.isApplyLoading` | `filterSidebar.isLoading` |
-| `preferences: { url, token, key, … }` (server-side) | `preferences: { storageKey }` (localStorage only — wire your own server sync via `onSortChange` / `onFilterChange` / `onPageChange`) |
-| `onRowClick(row, header)` | `onRowClick(row, event)` |
-| Row-level `onLink` / `onEdit` / `onDelete` callbacks on individual data rows | _removed_ — add an "Actions" column with `cell: (_, row) => <DropdownMenu>…</DropdownMenu>` |
-| `loadingType` / `loadingContaxt` / `loadingBoxStyle` | _removed_ — `isLoading` now renders skeleton rows; for custom states pass `emptyState` |
-
-### Before / after
-
-```tsx
-// before
-<Table
-    data={users}
-    columns={[
-        { key: "name", label: "Name" },
-        { key: "email", label: "Email" },
-    ]}
-    isPagination
-    paginationMode="client"
-    noOfRowsPerPage={25}
-    paginationSelectOptions={[10, 25, 50]}
-    isCheckbox
-    selections={selected}
-    onSelection={setSelected}
-    onGlobalSearch={(q) => fetch(q)}
-    isLoading={loading}
-    loadingSkeletonRows={5}
-/>;
-
-// after
-<Table<User>
-    data={users}
-    columns={[
-        { id: "name", header: "Name", accessorKey: "name", sortable: true },
-        { id: "email", header: "Email", accessorKey: "email" },
-    ]}
-    rowKey="id"
-    pagination
-    paginationMode="client"
-    defaultPageSize={25}
-    pageSizeOptions={[10, 25, 50]}
-    selectable
-    selectedRows={selected}
-    onSelectionChange={setSelected}
-    onSearchChange={(q) => fetch(q)}
-    isServerSearch
-    isLoading={loading}
-    loadingRowCount={5}
-/>;
-```
-
----
-
-## 4b. Tailwind class migration
-
-The old config exposed **per-shade** tokens (`primary-50…900`, `gray-50…900`, semantic palettes). The new config exposes **semantic** tokens that automatically swap on dark mode and on preset theme changes. There is no `gray-700` anymore — use `muted-foreground` instead.
-
-> **Important**: Tailwind silently drops unknown utility classes. After upgrading, classes like `bg-primary-500` produce **no styles** — not an error. Search-and-replace before deploying.
-
-### Brand
-
-| Old | New | Notes |
-| --- | --- | --- |
-| `bg-primary-50` … `bg-primary-100` | `bg-primary/10` | very light tint |
-| `bg-primary-200` … `bg-primary-400` | `bg-primary/30` … `bg-primary/50` | tints via opacity |
-| `bg-primary-500` / `bg-primary-600` | `bg-primary` | the base brand color |
-| `bg-primary-700` … `bg-primary-900` | `bg-primary` + custom darken via `dark:` if needed | shades collapse |
-| `text-primary-*` | `text-primary` | foreground equivalent: `text-primary-foreground` (the readable color on top of primary) |
-| `border-primary-*` | `border-primary` | |
-| `bg-primary-opacity-{8,16,24,28,32,40}` | `bg-primary/{8,16,24,28,32,40}` | Tailwind opacity modifier |
-
-### Surfaces & text
-
-| Old | New |
-| --- | --- |
-| `bg-background-main` | `bg-background` |
-| `bg-background-secondary` / `bg-background-tertiary` / `bg-background-quaternary` | `bg-card` / `bg-muted` (pick by intent) |
-| `bg-background-light` / `bg-background-medium` | `bg-muted` |
-| `bg-background-accent` / `bg-background-subtle` | `bg-accent` / `bg-muted` |
-| `bg-background-muted` / `bg-background-neutral` | `bg-muted` |
-| `bg-background-base` | `bg-background` |
-| `bg-background-tableHeader` | `bg-muted/50` |
-| `text-text-heading` | `text-foreground` |
-| `text-text-body` | `text-foreground` |
-| `text-text-subtle` | `text-muted-foreground` |
-| `text-text-input` | `text-foreground` |
-| `text-text-headingOpacity-{4,8}` | `text-foreground/{4,8}` |
-
-### Borders
-
-| Old | New |
-| --- | --- |
-| `border-border-default` | `border-border` |
-| `border-border-light` | `border-border/60` |
-| `border-border-dark` | `border-border` (use `dark:` for dark mode tuning) |
-| `border-border-input` | `border-input` |
-| `border-border-error` | `border-destructive` |
-| `border-border-success` | `border-success` |
-| `border-border-warning` | `border-warning` |
-| `border-border-info` | `border-primary` |
-
-### Semantic palettes
-
-| Old | New |
-| --- | --- |
-| `bg-semantic-success-*` | `bg-success` (foreground: `text-success-foreground`) |
-| `bg-semantic-error-*` | `bg-destructive` (foreground: `text-destructive-foreground`) |
-| `bg-semantic-warning-*` | `bg-warning` (foreground: `text-warning-foreground`) |
-| `bg-semantic-info-*` | `bg-primary` (foreground: `text-primary-foreground`) |
-
-### Generic palette (`gray`, `red`, `blue`, etc.)
-
-The new config does **not** redefine `gray`, `red`, `blue`, `green`, `teal`, `cyan`, `purple`, `pink`, `orange`, `yellow`. Tailwind's built-in palette is still available, so `bg-gray-700` continues to resolve to Tailwind's stock gray.
-
-**However**, the old library overrode `gray` with CSS-var-based shades that responded to dark mode. The new approach is to use semantic tokens (`muted`, `muted-foreground`, `accent`, `card`) so colors flip automatically. Migrate `bg-gray-100 → bg-muted` and `text-gray-700 → text-muted-foreground` for theme-aware styling. Leave plain `gray-*` only where you genuinely want a fixed gray that ignores the theme.
-
-### JS-side theme access
-
-```ts
-// before
-import { useCustomTheme } from "pixelize-design-library";
-const theme = useCustomTheme();
-const color = theme.colors.primary[500];
-const bg = theme.colors.background.main;
-
-// after — JS access is no longer needed for colors. If you must read the
-// computed color at runtime (e.g. for canvas/chart libraries), use:
-import { useChartTheme } from "pixelize-design-library";
-const { primary, foreground, background, palette } = useChartTheme();
-// or for arbitrary CSS vars:
-getComputedStyle(document.documentElement).getPropertyValue("--color-primary").trim();
-// (returns the raw "221 83% 53%" HSL channels — wrap in `hsl(...)` to use)
-```
-
-### Quick sed migration script
-
-```bash
-# Run from your consumer app root. Review the diff before committing.
-git ls-files '*.tsx' '*.ts' '*.jsx' '*.js' '*.css' | xargs sed -i.bak -E \
-  -e 's/(bg|text|border|ring|fill|stroke)-primary-[0-9]+/\1-primary/g' \
-  -e 's/(bg|text|border)-background-main/\1-background/g' \
-  -e 's/(bg|text|border)-background-(secondary|tertiary|quaternary|light|medium)/\1-card/g' \
-  -e 's/(bg|text|border)-background-(subtle|muted|neutral)/\1-muted/g' \
-  -e 's/(bg|text|border)-background-accent/\1-accent/g' \
-  -e 's/(bg|text|border)-text-heading/\1-foreground/g' \
-  -e 's/(bg|text|border)-text-(body|input)/\1-foreground/g' \
-  -e 's/(bg|text|border)-text-subtle/\1-muted-foreground/g' \
-  -e 's/(bg|text|border)-border-default/\1-border/g' \
-  -e 's/(bg|text|border)-border-error/\1-destructive/g' \
-  -e 's/(bg|text|border)-border-success/\1-success/g' \
-  -e 's/(bg|text|border)-border-warning/\1-warning/g' \
-  -e 's/(bg|text|border)-border-info/\1-primary/g' \
-  -e 's/(bg|text|border)-semantic-error-[0-9]+/\1-destructive/g' \
-  -e 's/(bg|text|border)-semantic-success-[0-9]+/\1-success/g' \
-  -e 's/(bg|text|border)-semantic-warning-[0-9]+/\1-warning/g' \
-  -e 's/(bg|text|border)-semantic-info-[0-9]+/\1-primary/g' \
-  -e 's/(bg|text|border)-primary-opacity-([0-9]+)/\1-primary\/\2/g'
-
-# Then visually QA. Leftovers to fix by hand:
-git grep -E '\-(primary|background|text|border|semantic)-[0-9]+'
-```
-
----
-
-## 5. Select consolidation (4 → 1)
-
-Old:
-
-```tsx
-<Select options={…} value={v} onChange={setV} />
-<SearchSelect options={…} value={v} onChange={setV} />
-<SelectSearch options={…} value={v} onChange={setV} onCreate={addNew} />
-<MultiSelect options={…} value={vs} onChange={setVs} />
-```
-
-New — one component, additive props:
-
-```tsx
-import { Select } from "pixelize-design-library";
-
-<Select options={…} value={v} onChange={setV} />                          // plain
-<Select options={…} value={v} onChange={setV} searchable />               // searchable
-<Select options={…} value={v} onChange={setV} searchable creatable
-        onCreateOption={addNew} />                                         // create-on-search
-<Select options={…} value={vs} onChange={setVs} multiple searchable
-        clearable maxDisplayed={3} />                                      // multi
-```
-
-Options are typed and groupable:
-
-```ts
-const options: SelectOption[] = [
-    { value: "us", label: "United States", group: "Americas", icon: <Flag /> },
-    { value: "uk", label: "United Kingdom", group: "Europe", description: "GBP" },
-];
-```
-
-Async search:
-
-```tsx
-<Select
-    options={remoteOptions}
-    onSearch={(q) => fetchOptions(q)} // called on every keystroke; no client filter
-    searchable
-    isLoading={isFetching}
-/>
-```
-
----
-
-## 6. Modal → Dialog
-
-The `Modal` export still works as a thin compatibility shim, but new code should use `Dialog`.
-
-Before:
-
-```tsx
-import { Modal, ModalHeader, ModalBody, ModalFooter } from "pixelize-design-library";
-
-<Modal isOpen={open} onClose={() => setOpen(false)}>
-    <ModalHeader>Delete project</ModalHeader>
-    <ModalBody>This cannot be undone.</ModalBody>
-    <ModalFooter>
-        <Button onClick={() => setOpen(false)}>Cancel</Button>
-        <Button colorScheme="red" onClick={remove}>Delete</Button>
-    </ModalFooter>
-</Modal>
-```
-
-After:
-
-```tsx
-import {
-    Dialog,
-    DialogClose,
-    DialogContent,
-    DialogDescription,
-    DialogFooter,
-    DialogHeader,
-    DialogTitle,
-    Button,
-} from "pixelize-design-library";
-
-<Dialog open={open} onOpenChange={setOpen}>
-    <DialogContent size="sm">
-        <DialogHeader>
-            <DialogTitle>Delete project</DialogTitle>
-            <DialogDescription>This cannot be undone.</DialogDescription>
-        </DialogHeader>
-        <DialogFooter>
-            <DialogClose asChild>
-                <Button variant="outline">Cancel</Button>
-            </DialogClose>
-            <Button variant="destructive" onClick={remove}>Delete</Button>
-        </DialogFooter>
-    </DialogContent>
-</Dialog>;
-```
-
-For destructive flows where outside-click dismissal would be a foot-gun, use `AlertDialog` instead.
-
----
-
-## 7. Theming: `useCustomTheme()` → `useTheme()` + CSS variables
-
-The old per-color tokens (e.g. `theme.colors.primary[500]`) are replaced by **CSS variables**. Read them via Tailwind utility classes — never via JS.
-
-Before:
-
-```tsx
-import { useCustomTheme } from "pixelize-design-library";
-
-function MyBadge() {
-    const theme = useCustomTheme();
-    return <span style={{ background: theme.colors.primary[500] }}>Hi</span>;
-}
-```
-
-After:
-
-```tsx
-function MyBadge() {
-    return <span className="bg-primary text-primary-foreground">Hi</span>;
-}
-```
-
-Need to read or set the *theme* (preset) or *mode* (light/dark)? Use `useTheme()`:
-
-```tsx
-import { useTheme } from "pixelize-design-library";
-
-function ThemePicker() {
-    const { theme, setTheme, mode, setMode, resolvedMode } = useTheme();
-    return (
-        <button onClick={() => setMode(resolvedMode === "dark" ? "light" : "dark")}>
-            Toggle (current: {resolvedMode})
-        </button>
-    );
-}
-```
-
-Need to override one color globally? Set the CSS variable on `:root`:
-
-```css
-/* in your app's css */
-:root {
-    --color-primary: 280 80% 55%; /* HSL channels, no hsl() wrapper */
-}
-```
-
----
-
-## 8. Dark mode setup
-
-The library is dark-mode-ready out of the box — you just need to ensure your Tailwind config has `darkMode: "class"` (mirroring the library's) so utility classes like `dark:bg-card` resolve to your own components too.
-
-`ThemeProvider` toggles the `.dark` class for you based on `mode`:
-
-```tsx
-<ThemeProvider defaultMode="system">{children}</ThemeProvider>
-```
-
-To let users override:
-
-```tsx
-const { mode, setMode } = useTheme();
-// setMode("light" | "dark" | "system")
-```
-
-The library persists the choice to `localStorage` under `px-ui-theme` (configurable via `storageKey` on `ThemeProvider`).
-
----
-
-## 9. Removed / replaced APIs
-
-| Removed                  | Use instead                                                                                                  |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `useToaster()` hook      | `toast.success("…")` / `toast.error("…")` from `sonner`-backed `toast` export.                               |
-| `useCustomTheme()`       | `useTheme()` for theme/mode state, Tailwind classes for color tokens.                                        |
-| `withTheme` HOC          | Wrap app in `<ThemeProvider>`.                                                                               |
-| `loadingType`/`loadingContext` props on Table | `isLoading` + `loadingRowCount` (skeleton rows).                                                            |
-| `colorScheme` on Button  | `variant` (`default` / `secondary` / `outline` / `ghost` / `destructive` / `link`).                          |
-| Chakra-style `as` prop   | `asChild` (Radix Slot) on Button and a few others; otherwise just render the right element.                  |
-
----
-
-## 10. Storybook
-
-The repo ships a Storybook 8 setup ([.storybook/main.ts](.storybook/main.ts), [.storybook/preview.tsx](.storybook/preview.tsx)) wired to the v3 `ThemeProvider`. The toolbar offers two controls driven by Storybook globals:
-
-- **Mode** — Light / Dark / System (drives `setMode` on the in-story `ThemeProvider`).
-- **Theme** — 7 presets (drives `setTheme`).
-
-Run with `npm run storybook` → http://localhost:6006.
-
----
-
-## 11. Common gotchas
-
-- **`useTheme()` outside `ThemeProvider`** throws. Always mount the provider at app root (including in tests — wrap with `<ThemeProvider>` in your render helper).
-- **CSS variables not visible** — make sure `tokens.css` is imported *before* component render. If colors look wrong/transparent, the variables aren't defined.
-- **Dark mode doesn't kick in** — confirm Tailwind config has `darkMode: "class"` (not `"media"`), and the html element gets `.dark` (DevTools → Elements pane).
-- **Boolean Chakra props** — Chakra used `isOpen`, `isDisabled`, `isLoading`. The new components mostly keep the `is*` form on form components for consistency (`isDisabled`, `isReadOnly`, `isRequired`), but Radix-derived primitives use the standard React names (`disabled`, `open`, `onOpenChange`). When in doubt, check the component's TypeScript props in your editor.
-
----
-
-Questions or migration friction? Open an issue or ping `#design-system` in Slack.