# Component Gotchas & Decision Guide

For anyone — human or AI — consuming `pixelize-design-library` in an app. Read this **before**
choosing a component or a prop value, not after something looks wrong. Every entry below compiles
cleanly, accepts what you pass, and produces the wrong result with no warning — TypeScript cannot
catch any of these, and a unit suite that mocks the library won't either.

This file ships inside the published package (`node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md`)
so it's available without checking out the library's source repo. Its companion
[DESIGN-GUIDE.md](DESIGN-GUIDE.md) ships beside it and covers how to compose components into a page.

---

## Found a gap or a bug? Report it, then track it

The library exists so a UI change is made **once, here** — not patched per app. So when a component
is wrong, missing a prop, or can't express what a screen needs, **don't work around it in your app
and move on.** Report it upstream; a workaround nobody knows about is a bug that gets rediscovered
in every other app.

**What counts:** a component that renders wrong (misaligned, clipped, wrong size or colour, off the
control scale), a prop you need that doesn't exist, a silent-failure trap that isn't listed below, or
a doc that contradicts what you measured.

**How to report** — one GitHub issue on `pixelize-tech/Micro-Components`, with the label `bug` or
`enhancement`. From a terminal (AI agents included) this is one command:

```bash
gh issue create --repo pixelize-tech/Micro-Components --label bug \
  --title "[consumer] <Component>: <what is wrong>" \
  --body "Version: <output of: npm ls pixelize-design-library>
App / screen: <where you saw it>
Expected: <what should happen>
Actual: <what happens, with measured numbers if it is visual>
Repro: <props / minimal snippet>
Workaround in the app: <none, or what you did and where, so it can be removed>"
```

Measure, don't eyeball: for a visual bug give the rendered size and offset (`getBoundingClientRect`)
and the `size` prop — "icon 1.5px above centre at `sm`" gets fixed; "looks off" doesn't.

**How it is tracked** — the issue is the record; there is no second list.

| State | What it means | What you do |
| --- | --- | --- |
| Open | Reported, not yet fixed | Keep any workaround, and comment its file path on the issue |
| Closed with a version | Fixed in the named beta/release, and the fix is under `### Fixed` in [CHANGELOG.md](CHANGELOG.md) citing the issue | Bump the pin to that version (exact, never a caret on a prerelease), **delete the workaround**, close your own follow-up |
| Closed as `wontfix` / `invalid` / `duplicate` | Not changing, or already covered | Read the reason; the workaround stays, or use the issue it points to |

Before reporting, search first — `gh issue list --repo pixelize-tech/Micro-Components --search "<component>" --state all`
— and check the [CHANGELOG.md](CHANGELOG.md) shipped with your installed version; the gap may already
be fixed in a newer beta.

**Maintainers:** a fix closes its issue in the same change that lands it, and its CHANGELOG line
names the issue number and the version that ships it. A workaround someone left in an app is only
removable if the issue says which version fixes it, so never close without naming one.

---

## A colour rung flips direction between light and dark

`colors.primary[700]` is a deep purple in light mode and a **pale** lavender in dark. The scales are
ordered so a high rung always contrasts with the page canvas, which means its lightness inverts
with the mode. Using one as ink is what the ordering is for; using one as a **background fill**
gives you a dark bar in light mode and a pale one in dark, with whatever you put on top now
unreadable.

```tsx
// Wrong — pale lavender bar in dark mode, and the label on it is unreadable
<Box bg={colors.primary[700]}>…</Box>

// Right — a brand fill that stays a brand fill, with its own guaranteed-AA foreground
const brand = resolveFilledSurface(colors.primary, colors);
<Box bg={brand.activeFill} color={brand.activeColor}>…</Box>
```

`resolveFilledSurface` is exported from the package root. Use `.fill`/`.color` for a standard
brand surface and `.activeFill`/`.activeColor` for a deeper one behind other content.

---

## Choosing between components

### Segmented control look — `SegmentedControl` / `Toggle/TableToggle`

Both take `variant?: "default" | "brandSlide" | "underlineSlide"` (default `"default"` — always
opt-in, never assume a non-default look).

| Context | `variant` | Look |
| --- | --- | --- |
| Most call sites — settings rows, filters, table view switches | `"default"` | Neutral chip |
| The primary, hard-to-miss view switcher on a page (not a dense toolbar) | `"brandSlide"` | Solid brand-filled pill slides behind the active segment |
| A dense toolbar, table header, or anywhere a boxed control feels heavy | `"underlineSlide"` | Thin brand-colored bar glides under the active label, no fill/chip |

Pick by density and emphasis, not by taste. When unsure, or migrating an existing call site, leave
it on `"default"` — it's the only variant guaranteed to match previously-shipped screenshots.

**`brandSlide` no longer guesses its backdrop — and `surface` is now optional.** Until
2.4.2-beta.46 the track was an 8% brand tint composited over the **page canvas**, and the inactive
label's ink was lifted against that same assumed canvas. Dropped into a brand-filled header both
went wrong at once: the tint sank into the bar, and the label landed at **1.03–2.03:1** — rendered,
effectively invisible. The track is now an opaque plate (`colors.surfaceRaised`) whatever it sits
on, so a control on a coloured bar is readable with no prop passed (rest ink 7.58–18.39:1).

Pass `surface` only to aim the plate's 1px edge at the real backdrop instead of the page canvas.
The edge is what carries the boundary: in dark mode the plate and a brand bar can sit at almost the
same lightness (as low as 1.56:1 on radiant), so hue alone would not separate them.

```tsx
<Box bg={theme.colors.primary[700]}>
  <Switch ... surface={theme.colors.primary[700]} />   // optional: sharpens the plate's edge
</Box>
```

### Which "select" component — `Select` is the only one to reach for now

There is now **one** picker. `Select` does both modes off the `native` prop:
`native` (default `true`) renders a real `<select>`; `native={false}` renders the themed,
fully-React popup — searchable, `isMulti` with chips, grouped options, `isClearable`,
`onCreate`, `renderOption`, `onLoadMore`, optional windowing via `virtualizeAfter`.

`isMulti` always forces the popup — there is no native multi-select — and dev-warns if you
also passed `native`.

**Native `Select` is uncontrolled until you pass a `value`.** With no `value` it keeps its own selection
(seeded by `defaultValue`), so `onChange={() => {}}` still lets the user pick. Once a defined `value` has been
passed it is controlled: an `onChange` that does not store the value snaps the field back, and `value` going
back to `undefined` shows the placeholder, not the earlier pick. `variant` (`outline`, `filled`, `flushed`,
`unstyled`) is native-only and inert in popup mode.

**Only `SelectV2` is `@deprecated`. None was deleted; every existing call site still works.**

| Deprecated | Status | Migration |
| --- | --- | --- |
| `SelectV2` | Now a thin wrapper — literally `<Select {...props} native={false} />` | Drop-in. DOM, ARIA roles, keyboard and the `${listboxId}-option-${id}` id scheme are unchanged, so E2E selectors keyed to it still pass |
| `SearchSelect` | **Not deprecated** — implementation untouched, not 1:1 replaceable yet | Hand-migrate. `insideSelect` and the paginated `pagination.onScroll` shape (1-based `startIndex`/`limit`/`query`) have **no** equivalent in `Select` today; `isSelectAll`, `rightIcon`, `isFieldLoading`, `chipMaxLength`, `isChipRemovable` and `footerAction` (closes the popup, unlike `addNew`) now do. Keep using it until they do |
| `SelectSearch` | **Not deprecated** — implementation untouched | Hand-migrate. It is uncontrolled (`initialSelectedOption` seeds state once and never resyncs) and moves real DOM focus into rows; `Select` is controlled and uses `aria-activedescendant` |
| `Dropdown` | **NOT deprecated** — the marker was wrong and was removed 2026-09-21 | Never "migrate" it to `Select`. It is a menu-button (`role="menu"`/`menuitem`, `aria-haspopup="menu"`), not a value picker (`role="combobox"`/`listbox`). Swapping it would be an accessibility regression, and nothing in this library replaces it |

**Still genuinely different, not pickers at all:**

| Doing | Component |
| --- | --- |
| Typing free-text tags, no options list | `TagInput` (any text, your own `validate`). `MultiSelect` is the email-only variant — despite the name there is nothing to pick from; see its gotcha below |
| Choosing which fields/columns to include, in a modal, from a checkbox grid | `FieldSelectModal` |

`onChange` is the change prop on `Select`, `SelectV2` and `SearchSelect` (`SearchSelect.onSelect` is
`@deprecated`, same payload; `onChange` wins when both are set). `Search` uses `onSearch`/`onClear`
(`onclose` is `@deprecated`).

### `Dropdown`'s `handleOptionSelect` takes TWO arguments and TypeScript will not tell you

The prop is `(id, label) => void`. TypeScript accepts a one-argument function anywhere a
two-argument one is expected, so `handleOptionSelect={handleSelect}` where `handleSelect`
is `(id: string | number) => void` compiles cleanly and silently never receives `label`.

Call sites across crm-frontend and commerce hit this, every one a bare function reference rather
than an inline arrow.

**Apply:** pass an inline arrow (`(id, label) => handleSelect(id, label)`) so the arity is
visible at the call site, or declare the handler with both parameters. Grep for
`handleOptionSelect={` followed by a bare identifier.

### `Slider` is an image carousel, not a numeric range input

`Slider` auto-advances a set of images/content on a timer (paused while hovered or focused, never
under reduced motion; `showPauseControl` adds a visible play/pause button) — no numeric value, min/max, or step. The
range-input slider is a separate component named `RangeSlider`, because this library's `Slider`
already owns the name. `RangeSlider` used to be a Chakra passthrough on the `Primitives` barrel; it
is now the library's own themed component, with a real dual-thumb mode and a `marks` prop.

**Apply:** for a numeric/range form control import `RangeSlider` from the package root — never
`Slider`, and no longer from the `Primitives` barrel, which no longer carries it.

### Which "switch" — `ToggleSwitch` / `SegmentedControl` / `Tabs` / `InputSwitch` / `Switch`

| Choosing | Component | Why |
| --- | --- | --- |
| A real on/off toggle | `ToggleSwitch` | `role="switch"` + `aria-checked`, full keyboard support |
| One of 2-5 named options | `SegmentedControl` | `role="radiogroup"`, keyboard-navigable, supports per-option disabling |
| Switching between views or panels | `Tabs` | `role="tablist"` + `aria-controls`, count badges, lazy panels, vertical orientation |
| *(avoid)* | `InputSwitch` | `@deprecated` — now a thin wrapper that renders `ToggleSwitch` |
| *(avoid)* | `Switch` | `@deprecated` — a two-label segmented control (`leftText`/`rightText`), not a boolean; for a single on/off field use `ToggleSwitch` instead |

**Apply:** "on vs off" is always `ToggleSwitch`; 2+ named options is always `SegmentedControl`.

**`SegmentedControl`'s focus ring sits on the track, not the segment** (Button's two-tone ring). It is
driven by a `:focus-visible` check in `onFocus`, so a mouse click stays ringless. `underlineSlide` has no
track chrome, so its focused segment wears the ring instead.

**A focus indicator must never be in a `transition` list.** The 0ms computed style is the transparent
start value, so a screenshot or axe check taken on focus misses it. Field styles go through
`FIELD_TRANSITION` (`Common/fieldStyles.ts`), which animates `border-color` and `background-color`
only; keep `box-shadow` out of any transition you add around a field.

**`SegmentedControl` and `Tabs` look near-identical and are not interchangeable.** They share the
size scale and tokens, so `SegmentedControl variant="underlineSlide"` and `Tabs variant="line"`
render almost the same picture, as do `variant="default"` and `Tabs variant="subtle"`. The
difference is what the control *is*: `SegmentedControl` is a **radiogroup** — it filters or sets a
value and owns nothing else on the page; `Tabs` is a **tablist** — it shows one of several panels
and wires `aria-controls` to them. Pick by that, never by the picture. A screen reader announces
"radio 1 of 3" versus "tab 1 of 3, selected", and only `Tabs` gives you panels, count badges,
`isLazy` and `orientation="vertical"`.

### Circular charts — `ApexPieChart` vs `ApexPolarCharts`

| Need | Component | Why not the other |
| --- | --- | --- |
| Proportional share of a whole — slices sum to 100% | `ApexPieChart` | The default "part of a whole" chart; donut variants support a center total label |
| Compare independent magnitudes on a shared radial grid — values need not sum to anything | `ApexPolarCharts` | Reads like a circular bar chart, not a pie; picking Pie here makes unrelated values look like they must add to 100% |

### Which "button" — `Button` / `ButtonGroupIcon`

| Need | Component | Why not the other |
| --- | --- | --- |
| A single themed, interactive button — any variant/size/colorScheme, dark-mode aware | `Button` | `ButtonGroupIcon` is a fixed icon + text + icon row, not a general button |
| A themed row of icon + text + icon, optionally a dropdown menu on the right | `ButtonGroupIcon` | `Button` is one control; this row wires the left, center and right slots and the dropdown for you |

A gray `ghost` or `outline` `Button` is built for a card, a toolbar or a panel, where its hover step
reads. On the bare page canvas in light mode the hover fill measures only 1.076-1.124:1 against
the canvas across the nine brands (above 1.15:1 on a card), so the hover is faint there. A gray
ghost button that sits directly on `backgroundColor.base` should sit on a `Card` or panel surface
instead.

### Which "card" — `Card` / `ProductCard` / `StatCard` / `PaymentCard`

| Need | Component | Why not the others |
| --- | --- | --- |
| Generic padded container (borderless by default; `variant="outline"` for a ruled one), no commerce semantics | `Card` | Layout wrapper with `header`/`footer` slots and a padded body — see gotcha below |
| Product tile for a grid, list or rail (photo, price, rating, swatches, quick add) | `ProductCard` | Takes the same `axes` / `variants` as `ProductDetails`; for a whole page use `ProductDetails` |
| A KPI figure with delta and sparkline | `StatCard` | Not a product or a container |
| Subscription/pricing-tier card (plans, billing cycle, feature list) | `PaymentCard` | Takes a `Plan` object, unrelated to `options`/`productImage` |

### Managing organizations — `OrganizationDetails` vs `OrgSwitcher`

| Doing | Component | Why not the other |
| --- | --- | --- |
| Quickly changing which org is active for the current session (navbar/header) | `OrgSwitcher` | Compact trigger + searchable popover; no create/rename/delete — session-scoped |
| Managing the org list — rename, delete, accept/decline invites, create new, set a persisted default | `OrganizationDetails` | Full admin panel with bundled CRUD modals; `default`/`onSetDefault` is a persisted preference, not OrgSwitcher's session-scoped `value`/`onChange` |

### Plan/upgrade cluster — `UpgradeButton` / `PlanPill` / `PlanBadge` / `LimitReachedModal`

| Doing | Component | Why not the others |
| --- | --- | --- |
| A prominent, animated "upgrade now" CTA button | `UpgradeButton` | Shimmer/hover-lift button with size variants |
| Showing a plan-state badge and you already have label/tone/copy decided | `PlanPill` | Presentational only — no resolution logic |
| Showing the top-bar plan-name/"upgrade" badge from raw org plan data | `PlanBadge` | Wraps `PlanPill` with `resolvePlanBadge()`; renders nothing if `canManageBilling` is falsy |
| Blocking a user who hit a plan limit, with an explanation and upgrade path | `LimitReachedModal` | Full modal, fully controlled, reuses `UpgradeButton` as its own CTA |

### Top-of-app navigation — `NavigationBar` / `Header` / `SideBar` / `AppSwitcher` / `WorkspaceWindow`

| Need | Component | Why not the others |
| --- | --- | --- |
| Top bar: back control + user-avatar profile/logout dropdown | `NavigationBar` | No page-nav links at all — `navMenu` is only the avatar dropdown's own items |
| Top bar: horizontal page links with active-state highlighting + submenus | `Header` | Desktop submenus are hover-only, see gotcha below; the bar is `min-height: 4.3rem` and grows when the nav wraps |
| Collapsible/dockable left rail — primary in-app navigation + secondary panel | `SideBar` | The persistent nav shell, not for switching between whole apps |
| In-app launcher: browse modules, pins, recents, search | `NavLauncher` opened by a `LauncherTrigger` in `NavigationBar`'s `leading` | An app-owned screen registry, not a cross-app switcher; pins can also surface in `SideBar` `pinnedItems` |
| Key cap or chord hint (`mod+k`) | `Kbd` / `KbdShortcut` | Never hand-style a `<kbd>`; `Search` and `AppSwitcher` already use it |
| Cross-app launcher (CRM/HRMS/Tickets/Billing/...) | `AppSwitcher` (list from `resolveSuiteApps`; `buildSuiteApps` throws on plain `localhost` unless `devFallbackBaseUrl` is set) | Two-column popover grid of separate app origins — `SideBar`'s `otherApps` is the legacy predecessor; don't wire both into one shell |
| Floating Jira-style dialog to view/edit one record without leaving the page | `WorkspaceWindow` | Modal-based floating panel, not page navigation; pairs with `WorkspaceTray` |

### File pickers — `FileUpload` vs `FileUploader`

| Need | Component | Why |
| --- | --- | --- |
| Real `File`/Blob objects to actually upload (FormData/API) | `FileUpload` | Controlled; `onFilesUploaded` carries real `File[]` and validates accept/size with rejection messages |
| Self-contained "add photos, see thumbnails, remove" list with no server upload | `FileUploader` | Manages its own state; its `onFilesChange` metadata discards the real `File` — see gotcha below |

Both files declare a type named `FileUploaderProps`. The one at the package root describes `FileUpload` (`FileUpload/FileUploadProps.tsx`); `FileUploader`'s own props type (`FileUploader/FileUploaderProps.tsx`) is not exported, only its `UploadedFile`. Check which folder a type came from before trusting the name.

### Viewing files — `MediaViewer` / `FilePreview` / `PdfViewer` / `ProfilePhotoViewer`

Four components open a file, and only one of them is the general answer.

| Need | Component | Why |
| --- | --- | --- |
| A gallery of mixed media with next/prev, a filmstrip and per-type stages | `MediaViewer` | The full lightbox: image/video/audio/pdf/doc stages, keyboard nav, fullscreen, download. Collapses the filmstrip and stepper automatically for a single item |
| One file, click-to-open, no gallery | `FilePreview` | Lighter controlled modal; auto-detects type, zoom/rotate for images |
| Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar; `getBlob` for files behind auth |
| Crop/preview a user avatar | `ProfilePhotoViewer` | Avatar-specific, not a general file viewer |

`PdfViewer` shows a fallback when the browser cannot render a PDF inline (`navigator.pdfViewerEnabled === false`) or `getBlob` rejects; `FilePreview`'s `"pdf"` kind renders a bare `<embed type="application/pdf">` and tells you nothing. `MediaViewer` also handles it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.heif`) render an icon and a file-type chip with a download action instead of a blank frame.

`MediaViewer.labels` takes a `Partial<MediaViewerLabels>` — that type and `defaultMediaViewerLabels` are both exported from the package root, so you can merge rather than restate every string.

`MediaViewer`'s `index`/`onIndexChange` are now optional: omit both for uncontrolled (it owns the index, starting at `defaultIndex ?? 0`), or pass both to control it. Passing `index` without `onIndexChange` freezes the viewer — every nav path has nowhere to write the new index — and now warns loudly in dev.

### `HeaderActionsProps` describes a different component than `HeaderActions`

The value `HeaderActions` comes from `Components/Header/HeaderActions.tsx`, which declares its props inline. The type `HeaderActionsProps` re-exported from the package root comes from `Components/Table/TableProps.tsx` — the *table's* internal bulk-action bar. Typing a `HeaderActions` usage with `HeaderActionsProps` compiles into the wrong shape.

**Apply:** don't annotate `HeaderActions` with `HeaderActionsProps`. Let the props infer from the component, or use `React.ComponentProps<typeof HeaderActions>`. Same trap as `FileUploaderProps` above — check which folder a type came from before trusting the name.

### Confirm prompts — `ConfirmDialog` vs `AlertDialog` vs `Modal`

| Need | Component | Why |
| --- | --- | --- |
| A delete/deactivate prompt with a header swatch and a red Confirm | `ConfirmDialog` | The shared shape behind the library's confirm modals; `tone="destructive"` (the default) fills Confirm red |
| A simple two-button yes/no | `AlertDialog` | Lighter; `confirmButtonText`/`cancelButtonText`, `tone="danger"` for a red Confirm |
| Anything else | `Modal` | Named slots only — see the slot gotcha below |

**`ConfirmDialog.onConfirm` does not close the dialog.** It fires and nothing else; you call `onClose` yourself. That is deliberate — it lets you keep the dialog open while an async delete is in flight — but a handler that only calls your delete function leaves the dialog on screen with no error.

`iconBg` and `iconColor` are optional and derive a soft tint from `tone`; if you pass them, read them from `useCustomTheme()` — a hardcoded hex is stuck in light mode. For a delete that names the record, pass `entityName` (+ `entityKind`, `dependents`, `consequence`, `alternative`) instead of hand-building the body; focus opens on Cancel, never the destructive button, and `focusCancelOnOpen={false}` moves it to the close button, not Confirm.

### Busy indicators — `Spinner` vs `Backdrop` vs `Loading`

| Need | Component | Why |
| --- | --- | --- |
| Inline busy mark in a row, cell or button area | `Spinner` | The package-root `Spinner` is the themed one (accent colour, own xs–xl `size` scale), not Chakra's raw spinner |
| **Scrim over the page or one panel — the default for new work** | **`Backdrop`** | `variant="dim"` by default: black at 0.5, no blur, 225ms in / 195ms out, 40px spinner. `container` scopes it, `onClick` dismisses, `invisible` blocks without painting |
| Let clicks reach the page while a scrim is showing | `Backdrop allowBackgroundInteraction` | Drops `pointer-events` on the scrim **and** its transition wrapper. `onClick` cannot fire while set — that is the trade |
| Existing screens already using it | `Loading` | The older API. Its default `variant="frosted"` keeps the heavier house scrim (0.6 + 4px blur) so nothing shifts; `variant="dim"` routes it through `Backdrop` |

**Never hand-roll a scrim.** A `position: fixed` `Box` with your own `rgba()` will not match the
Modal/Drawer overlay, will not fade, and will not follow dark mode. `Backdrop` is the one owner.

One trap if you build anything similar yourself: setting `pointer-events: none` on your overlay is
not enough when the overlay sits inside a transition wrapper — the wrapper keeps capturing clicks.
`Backdrop` sets it on both.

### Data states — `EmptyState` / `ErrorState` / `QueryStateBoundary`

| Need | Component | Why |
| --- | --- | --- |
| "Nothing here yet" with an optional action | `EmptyState` | Neutral placeholder |
| "Nothing matches your filters" | `FilteredEmptyState` | Names the filters, offers Clear and Remove-last; in a boundary use `isEmpty` + `isFiltered` |
| A failed load with retry | `ErrorState` | `role="alert"`, `onRetry`/`isRetrying` built in |
| One fetch that can be loading, forbidden, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > forbidden > error > empty > `children` |

---

## Known gotchas (silent failures)

### `withTheme` mounts a full provider stack per wrapped instance

Each wrapped component gets its own `ChakraProvider` (CSS reset, global styles, CSS variables), `ToasterProvider` and `ColorModeScript`. Wrap the app root once with `PixelizeThemeProvider`; never wrap list items or repeated rows.

### `SearchSelect` with `insideSelect` shows a second `role="listbox"` while open

A test that finds the main dropdown with `getByRole("listbox")` must now pick it by id (`<id>-listbox`).

### `ChoiceCardGroup`'s children must be `ChoiceCard` elements

A wrapper component hides each card's `value` and `disabled` / `isDisabled` from the roving tab stop, so with
nothing selected the group has no Tab stop at all (same rule as `PaymentOptionGroup` / `AddressCardGroup`).
`ChoiceCard` takes `disabled` or its `isDisabled` alias; `AddressCard` and `PaymentOption` still take
`disabled` only. The group is a column; `columns={n}` (n above 1) lays it out as an n-column grid.

### `Pagination` never resets `page` for you

An out-of-range `page` (a filter shrank the result) is displayed clamped but never reported, and changing
rows per page does not reset `page` either. Reset it yourself, in `onPageSizeChange` and when the filters change.

### A component with a behaviour its props do not hint at

- `NoteTextArea`'s `handleCancel` always receives `false`, and `handleSubmit` is called with three arguments although its type declares a fourth (both tagged `@deprecated`).

### Where `ref` lands, and what does not take one

`Checkbox`, `RadioButton`, `ToggleSwitch` and `DatePicker` (every mode) forward to the native `<input>`.
`SegmentedControl` forwards to the radiogroup `<div>`, not a segment; `Tab` to its tab `<button>` (`Tabs`
itself takes no ref); `Avatar` to the outer box; `Tag` to its root, which is a `<button>` only for
`display="dot"` with `onTagClick`, so type that ref as `HTMLElement`. `PinInput`, `FileUpload`,
`SettingRow` and `Tabs` do not forward a ref.

### Root attributes on the page primitives, and `Skeletons` props that are ignored

`PageHeader`, `StatCard`, `SaveBar`, `EmptyState`, `DescriptionList`, `FilterBar` and `Skeletons` put
`className`, `style`, `id`, `data-*` and `aria-*` on their outermost element. `StatCard` applies
`aria-label` only when `onClick` makes it a button; `DescriptionList`'s loading grid keeps its own
`aria-label="Loading"`. `Skeletons` still accepts `alignSelf` and `flexShrink`, now `@deprecated`, but never
applies them; wrap it in a `Box` to position it.

### `Table` `HeaderActions` item with `customComponent` and `onClick` is mouse-only unless the custom component is focusable

The wrapper is deliberately not a button; make the custom component a button, or the action cannot be reached from the keyboard.

### Defaults changed in 2.4.2-beta.44 — read this first when upgrading from beta.43

| Component | beta.43 → beta.44 | Restore the old look |
| --- | --- | --- |
| Fields, selects, buttons (`Button`, `TextInput`, `InputTextArea`, `NumberInput`, DatePicker family, `Select`, `SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Dropdown`, `SegmentedControl`) | Default size `md` → `sm`. Fields/selects read `CONTROL_SIZES` (xs 32 / sm 38 / md 40 / lg 48); `Button`/`SegmentedControl`/`Tabs`/`TableToggle`/`Dropdown`'s trigger read the separate `BUTTON_SIZES` (xs 24 / sm 32 / md 40 / lg 48). `SegmentedControl` has no `xs` — see the gotcha below | `size="md"` |
| `Button` | Text one step smaller (sm 14→13px, md 16→14, lg 18→16). Busy = spinner only, width kept (was "Loading" + spinner). Outline: 1px border, hover is a tint, not a fill | `loadingText="Loading"` |
| `Tag` | `solid`/`md` → `subtle`/`sm`. Hover + pointer only with `onTagClick`; `maxW` truncates with the full text as a title. Exact heights 20/24/28/32, weight 500, 1px inset ring (never adds height); subtle is a light tint with ink ≥ 6:1 | `variant="solid" size="md"` |
| `resolveSoftTone` | `bg`/`border` are now translucent (alpha hex) — composite onto the surface before `contrastRatio`; optional 3rd `surface` arg; adds `hoverBg`/`activeBg`. Badge/Alert/Toaster/EmptyState follow | — |
| `resolveFilledSurface` | Still white-first; when a white-labelled fill would vanish on the canvas (zinc dark primary) it falls back to a light fill with dark ink. Takes `background` in `colors` now | — |
| `Checkbox` / `RadioButton` | Box 16/20/24 → 14/16/20; label 14px; 1px border; one fill rung for every `colorScheme`. **`RadioButton colorScheme` now applies** (was always primary) | — |
| `ToggleSwitch` / `SegmentedControl` / `TableToggle` | Off track lifted to 3:1; thumb ink flips on light fills. Radius `lg`; `TableToggle` tooltips = button names, `aria-pressed` | — |
| `MultiSelect` | Default `md` → `sm`; real `<label>`; shared two-tone focus ring | `size="md"` |
| Selected rows (`Dropdown`, `SelectV2`, `SearchSelect`, `SelectSearch`, `MoreItems`, `Table` filters, menus) | Dark aliases `backgroundColor.tertiary` to the panel, so a selected row sat at 1.025:1 and was invisible. It is now lifted to a perceptible step. Light is byte-identical on eight brands; `zinc` moves slightly, having been below the step too | — |
| `tertiary` | Was an exact copy of `secondary` on six brands and of `primary` on three, so `colorScheme="tertiary"` rendered as another scheme. Now a real third accent: `primary`'s hue turned 60° at `secondary`'s luminances, so contrast is unchanged | use `secondary` |
| `SelectV2` | Trigger is now `div[role=combobox]`, not `<button>` — widen a `useRef<HTMLButtonElement>` to `HTMLDivElement`; assert `aria-disabled`, not `toBeDisabled()`. `isMulti` shows removable `Tag` chips (`maxVisibleChips`, default 6, then `+N`); Backspace removes the last; `maxLabelsBeforeSummary` now only shapes the `aria-label`. Read-only is `data-readonly`, not `aria-readonly` | custom `renderValue` for text |
| `SearchSelect` / `SelectSearch` | Menu radius `lg` → `xl`, shadow `lg`. `SearchSelect`'s button triggers are now `role=button` named `"Label: value"`; only the text input is `role=combobox` — update `getByRole("combobox")` queries | — |
| `TextInput` | **`type="password"` now auto-renders a show/hide toggle** — a plain password field gains a button it did not have in beta.43. Suppressed automatically when `inputRightIcon` is set, so a hand-rolled toggle never doubles up; `isPasswordToggleDisabled` opts out entirely. Also new: `variant` (`outline` default / `filled` / `flushed`), `isClearable`, `showCharacterCount` + `maxLength`, `inputLeftAddon`/`inputRightAddon`, `isLoading`. `inputStyle`/`leftElementStyle`/`rightElementStyle` are now `SystemProps` and `inputGroupStyle` is `CSSProperties` — all four were bare `object`, so a wrong key that used to compile now fails | `isPasswordToggleDisabled` |
| Chakra passthroughs | 34 barrel value exports (and 12 type exports) that duplicated an owned component were removed: `Input`, `Textarea`, `Progress`, `Radio`, `RadioGroup`, `Skeleton`, `ModalOverlay`, `ModalContent`, `ModalCloseButton`, `CardBody`, `ChakraCard`, `ChakraSelect`, `ChakraModal`(+`Body`/`Header`/`Footer`) the `Tabs`/`Accordion` families, and the Chakra slider sub-parts. `Tabs`, `Accordion` and `RangeSlider` now resolve to the library's own themed components (`RangeSlider` gained a real dual-thumb mode and a `marks` prop). Each removal is a compile error, never a silent swap | use the owned component — `TextInput`, `InputTextArea`, `ProgressBar`, `RadioButton`, `Skeletons`, `Modal`, `Card`, `Select` |
| `Avatar` / `AvatarGroup` | Now the library's own components, not Chakra passthroughs. `AvatarProps` is a closed list (`name`, `src`, `size` `2xs`–`xl`, `status`, `ariaLabel`, `getInitials`, `data-testid`) — Chakra style props and `2xl` no longer compile, and **`name` is now required `string`**, so a `user.name?: string` call site fails. The fill is derived from `name`, so stop passing `bg`/`color`; it follows brand and dark mode on its own. `AvatarGroup` takes `people=[{name, src}]`, not `<Avatar>` children, so it can build one accurate group label. Measured by typecheck: 13 of 18 consumer files break | wrap in a `Box` for placement/shadow; resolve `name` at the call site |
| `SettingsSection` | New optional `action` slot, right of the title/description on the header row — additive, nothing changes without it | — |
| `Button` | Icon-only buttons are square | — |
| `ProgressBar` | Fill lifted to ≥ 3:1 on its track — green/orange/blue/cyan are visibly darker in light mode | — |
| `PhoneNumberInput` | Default `size` `md` → `sm`, so it matches the `TextInput`s beside it | `size="md"` |
| `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches on `PhoneNumberInput` and `NoteTextArea` (`PinInput` takes none); labels bound; PIN digits grouped and named | — |
| `RangeDatePicker` | Outside click keeps a fully picked range (was discarded) | — |
| `FilePreview` / `ContactForm` | Radius `2xl` → `xl` | — |
| `Avatar` / `Timeline` / `Table` | Generated avatar fills now guarantee ≥ 4.5:1 initials (a name may get a different shade); Timeline rail lifted to 3:1; Table status/filter chips use the soft recipe; stray radii → `lg`/`xl`/`full` | — |
| `AlertDialog` | Yes/No → Confirm/Cancel; Cancel is a neutral gray outline (was red) | `confirmButtonText`/`cancelButtonText`; `tone="danger"` for a red Confirm |
| `Modal` | Page scroll now locks (`blockScrollOnMount` was silently off); `motionPreset="scale"`; theme scrim (60% black + blur) — drop any `overlaybackdropFilter` hue-rotate workaround; `isLoading` keeps header + close button | `blockScrollOnMount={false}` |
| `Toaster` | `showToast` returns an id; `update(id, patch)` / `close(id)`; `loading` toasts never auto-dismiss | pass `duration` |
| `ToolTip` | `openDelay` 0 → 300ms; 13px themed look | `openDelay={0}` |
| `InputTextArea` / `FileUpload` / `TextInput` | Width 500px → 100% / `maxSizeKB` 5 → 5120 / no default "Placeholder" text | `width="500px"` / — (5 KB was a bug) / — |
| `DatePicker` (no `pickerType`) | Inference is case-sensitive: `MM` is month, `mm` minutes. `dd/MM/yyyy` was misread as date+time and showed time selects; it is now date-only | `pickerType="datetime"` |
| `EmptyState` | Title is an `h3`; image is decorative (`alt=""`, was the title) | `titleAs`, `imageAlt` |
| Theme `Badge` / `Card` / field labels | Badge: pill, no uppercase, default `sm`. Card: default variant `elevated` (borderless, `shadows.card`). Label colour `text[700]`; helper/error row 12px | `size`/`variant` props |
| `Header` | `position: sticky; top: 0`, z-index `sticky` (1100); `rightSlot` mounts once, not per layout | — |
| `Table` | Radius `xl`; row height 32/40/52 by density; filter button is named "Filter {label}" (tests querying "Search" break); client pagination resets to page 1 when `data.length` changes | — |
| `KanbanBoard` | `height`/`maxH` props replace the clipping wrapper; `height="100%"` needs a parent with a definite height | — |
| `ProfileCard` / `SideBar` | `variant="outlein"` now draws an outline; header divider 1px `boxborder[200]` / mobile backdrop uses the shared scrim | — |
| `SideBar` | Scroll-container and submenu ids are generated (`useId`) — `#sidebar-scroll-container` / `#submenu-<label>` no longer exist; rail rows 32px, the mobile drawer's too, submenu rows 28px; count badges use soft tone. In the drawer, a menu with `secondaryItems` starts its panel as the icon strip (labels only as `aria-label`s until expanded) on screens up to ~373px, and the panel can no longer overflow the drawer | — |
| `ToggleSwitch` | No `aria-required` on the switch (invalid for `role=switch`); `isRequired` still shows `*` | — |
| `KanbanBoard` / `PdfViewer` / `UserDetails` | Cards, drag handles and toolbar links get accessible names; scroll panels are focusable regions; `UserDetails` badges 12px | — |
| `NumberInput` / `FileUpload` | Steppers exactly half the field height; drop-zone border 1px (was 2px) | — |
| `HeaderActions` | Edit/Create are real `<button>`s (keyboard reachable, focus ring); select named by `select.ariaLabel` or its placeholder | — |
| `SearchSelect` | New `aria-label` prop for fields without a visible `label` | — |
| New root exports | `mergeRefs`/`setRef`, `rafThrottle`, `toWords`, `useDebouncedCallback`/`useDebouncedValue`, and the chart theming kit (`getCategoricalSeriesColors`, `chartInk`, `labelOnSeries`, …) — previously internal-only | — |
| `toWords` | Now splits camelCase (`nextFollowUp` → `Next Follow Up`), so `Timeline`/`KanbanBoard` auto-labels read correctly instead of `Nextfollowup` | pass an explicit label |
| Focus rings (all controls) | `focusRing.ring` is now the brand accent itself (lavender `#8B3FC8`), not a near-black band — the white halo already separates it from a filled control | — |
| `Tag` | Label line-height 1.45 so descenders (`p`, `g`, `y`) are no longer clipped by the ellipsis overflow | — |
| `Toaster` | `error` toasts announce assertively (`role="alert"`); status icons have a text equivalent | — |
| `FeedbackForm` | Built on `TextInput`/`InputTextArea`/`RadioButtonGroup`; required fields show `*` in the label | — |
| `PinInput` | `size` now works (square cells 32 / 38 / 40 / 48 today, default `sm`) — it was silently ignored | `size="md"` |
| `Tag` | New `leadingIcon` (decorative, before the label) and `isDisabled` (sets `aria-disabled` + native `disabled` on the clickable/remove buttons, so they leave the tab order — not just dimmed) | — |
| `ToolTip` | Defaults a Popper `preventOverflow` padding of 8px, so a bubble near the right edge no longer overhangs by a subpixel and raises page scrollbars. A caller-supplied `preventOverflow` modifier still wins | pass your own `modifiers` |
| `Table` / `KanbanBoard` | Column sort buttons and draggable cards now show the library focus ring on keyboard focus (was an opacity flicker / the browser default outline). Kanban card wrappers render as Chakra `Box`; keyboard drag (Space, arrows, Space) is unchanged | — |
| `Search` / `FilterBar` / `SettingRow` / `NoteTextArea` | `Search` names itself from `placeholder` when there's no `label`/`aria-label`. `FilterBar` wraps `search` in a `role="search"` landmark named by `searchLabel` (default "Search"). `SettingRow` auto-wires an unnamed `control` to the row's title/description via `aria-labelledby`/`aria-describedby` unless it already has its own `aria-label`. `NoteTextArea` adds `titleAriaLabel`/`noteAriaLabel` (default "Note title" / `customPlaceholder`) | — |

### Removed barrel exports → what to import instead (beta.44)

Every name below stopped resolving from `pixelize-design-library` in beta.44. Each is a **compile
error**, never a silent swap, and each has an owned replacement that is already exported. Props
differ — this is a rewrite of the call site, not a rename.

| No longer exported | Import instead | Note |
| --- | --- | --- |
| `Input` | `TextInput` | Owns its label, helper/error text and password toggle |
| `Textarea` | `InputTextArea` | |
| `ChakraModal`, `ModalContent`, `ModalOverlay`, `ModalCloseButton`, `ChakraModalHeader`, `ChakraModalBody`, `ChakraModalFooter` | `Modal` | `Modal` renders the overlay, content and close button itself — drop those three. **`ModalHeader`/`ModalBody`/`ModalFooter` are still exported** and are still how you fill it; only the `Chakra`-prefixed aliases went. Header text can come from `title`/`subtitle` instead |
| `ChakraCard`, `CardBody` | `Card` | `header`/`footer` slots + `bodyProps` |
| `ChakraSelect` | `Select` | |
| `Radio`, `RadioGroup` | `RadioButton` / `RadioButtonGroup` | |
| `Skeleton` | `Skeletons` | Takes `borderRadius` |
| `Progress` | `ProgressBar` | |
| `AccordionItem`, `AccordionButton`, `AccordionPanel`, `AccordionIcon` | `Accordion` | Takes an `items` array, not compound children |
| `SliderTrack`, `SliderFilledTrack`, `SliderThumb`, `SliderMark` | `Slider` / `RangeSlider` | Owned components; the Chakra sub-parts are gone |

**Ten names still resolve** and only narrowed their props — `Accordion`, `Avatar`, `AvatarGroup`,
`RangeSlider`, `Spinner`, `Tab`, `TabList`, `TabPanel`, `TabPanels`, `Tabs`. They now point at the
library's own themed component rather than the Chakra passthrough.

### `CONTROL_SIZES` (fields) and `BUTTON_SIZES` (buttons) are separate scales — changing one never changes the other

Fields/selects (`TextInput`, `Select`, `MultiSelect`, `SearchSelect`, `NumberInput`, `PinInput`, the
`DatePicker` family, …) read `CONTROL_SIZES` — xs 32 · sm 38 · md 40 · lg 48. `Button` and every
button-like trigger (`SegmentedControl`, `Tabs`, `TableToggle`, `Dropdown`'s trigger) read the
separate `BUTTON_SIZES` — xs 24 · sm 32 · md 40 · lg 48. They used to share one token, which is what
let a field-only size bump leak into buttons — the split is now gate-tested
(`Common/sizeScaleOwnership.test.ts`).

**Apply:** a PR that "just" bumps a form-field size should never touch `Button.styles.ts`,
`SegmentedControl`, `Tab`, `TableToggle` or `Dropdown` — if it does, it's reading the wrong token.

### `controlSizeStyles()`'s `minH` silently overrides a smaller `h` override

`fieldStyles.ts`'s `controlSizeStyles()` sets both `h` and `minH` to the same token value. A caller
overriding only `h` with a smaller literal compiles and renders, but the inherited `minH` still
wins, so the field stays at the token height.

**Apply:** override both `h` and `minH` together, or don't override either.

### `Tag`'s `onIconClick` renders nothing without `icon` — the remove button silently never appears

`onIconClick` only turns `icon` into a remove button; it has no effect on its own (`Tag.tsx`
`{icon && (onIconClick ? … : …)}`). Passing `onIconClick` alone — expecting a default close
affordance the way Chakra's own `TagCloseButton` or AntD's `closable` work — compiles fine and
renders a plain tag with no way to remove it.

**Apply:** always pass both `icon` (e.g. `lucide-react`'s `X`) and `onIconClick` together for a
removable chip. `icon` alone (no `onIconClick`) is the decorative case — a plain right-side icon
with no click affordance, aria-hidden.

### `Tag display="dot"` ignores `variant` and icons; `StatusTag` renders an unknown status neutral

`display="dot"` ignores `variant`, `icon`, `leadingIcon` and `onIconClick`. `StatusTag`'s `map` is
keyed by your status union, but a runtime value outside it (API drift) renders a neutral chip and
only warns in development — guard upstream if a silent neutral would mislead.

### A rounded box with `overflow: hidden` clips glyphs at the corners — never round the clipping element

`border-radius` reshapes the overflow clip, so a pill-shaped element with `overflow: hidden`
clips text along an **ellipse**, not a rectangle. A leading `p`, `j`, `g`, `q` or `y` loses part
of its descender to the bottom-left curve. It looks like a font or line-height problem; it is not.
This shipped in `Tag`, where the label carried both `borderRadius: "full"` (to round its focus
ring) and `overflow: hidden` (for `text-overflow: ellipsis`).

The two cannot live on the same element. `overflow-clip-margin` does not rescue it either:
`text-overflow: ellipsis` needs a non-`clip` horizontal axis, and mixing `hidden`/`clip` across
axes collapses both to `hidden`, which makes the margin inert.

**Apply:** keep the radius on the outer element and put `overflow: hidden` +
`text-overflow: ellipsis` on a square (`borderRadius: 0`) child. Chakra's `TagLabel` also forces
`noOfLines={1}` as a style prop, which outranks the theme — pass `noOfLines={undefined}` to drop
it. In your own components, the same rule holds for any rounded chip, avatar or badge that clips
its own text. The `/tag` playground's "Glyph clipping" section renders every letter leading and
trailing at all four sizes as the visual check.

### `colorScheme="tertiary"` is a real third accent from beta.44 (it used to be a duplicate)

Through beta.43 `tertiary` was an exact copy of `secondary` on six brands and of `primary` on three,
so the two schemes were indistinguishable. It is now `primary`'s hue turned 60° re-solved to
`secondary`'s luminances, so every contrast guarantee is unchanged.

**Apply:** `secondary` vs `tertiary` is now a real visual distinction on every brand except `zinc`,
which is near-grey and has almost no hue to turn — use a semantic scheme (`blue`, `teal`, `purple`)
there if the two categories must read apart.

### Brand palettes and non-default themes are lazy; library style functions may return cached objects

Before its first read, a brand palette or a non-default light theme is an object of getters. Reading
any key turns it into plain data; spread, `Object.keys`, JSON and assignment behave as before, but
`Object.getOwnPropertyDescriptor` reports an accessor until then. Style functions in a library
theme's `theme.components` receive props through a tracking Proxy and may return a cached object, so
never mutate what they return.

### Reduced motion is per component unless the app passes `reducedMotion="global"`

The library's own animations honour `prefers-reduced-motion` one component at a time. For one
document-wide rule, pass `reducedMotion="global"` to `PixelizeThemeProvider`;
transitions and animations then collapse to one near-instant pass. Add `pz-motion-keep`
(`MOTION_KEEP_CLASS`) to any loop that is essential feedback; Chakra spinners and progress bars are
kept automatically.

A popup opened inside another popup takes `zIndex="popoverNested"` (1510), never `skipLink` (1600).
`fontSize="xs-plus"` is 13px, the control size; use it instead of a `13px` literal.

### Your own overlay painted `background[50]` sinks into the dark canvas

In dark mode `background[50]` is the card plane, one step above the canvas; an overlay painted with it
merges into the cards under it. Library dialogs, drawers, popovers and menus paint `colors.surfaceRaised`,
one step above the card in dark and identical `#ffffff` in light. A custom panel, popover or
`ModalContent bg=` should read `surfaceRaised` too, and a divider inside it `raisedRule(colors)`.

### Named fills nearly vanish on a dark card

In dark mode `backgroundColor.light`, `tertiary`, `medium` and `tableHeader` sit only 1.01-1.05:1 off
`background[50]`, `muted` 1.00-1.06:1 off `surfaceRaised`, and `boxborder[200]` 1.10-1.16:1 off a card and
1.00-1.06:1 off `surfaceRaised`. Never paint a named canvas fill or raw `boxborder[200]` on a card or overlay:
use `bandOn(fill, surface)` for a header strip, hover or selection tint, `recessOn(fill, surface)` for a shaded
or off cell, `cardRule(colors)` for a rule inside a card and `raisedRule(colors)` for a rule inside an overlay.
All four return the old value unchanged in light mode.

### `background[600]` is a mid-grey on Zinc, not a pale tint

The light `background` ramps are hand-written per brand. Eight stay pale through `[600]` (1.41-1.91:1 off the canvas);
Zinc is a full neutral ramp whose `[600]` is `#71717a` (4.83:1), dark enough that ink lifted to AA on it turns white.
Pick a pale fill by contrast, never by step number: the default tracks of `SegmentedControl` and `TableToggle` keep
`[600]` only where it is no darker than `boxborder[500]`.

### A Chakra `ModalHeader` inside a coloured box keeps its own ink

The theme gives `ModalHeader` `color: colors.header[900]` and a bottom rule. Wrapping it in a
`Box bgGradient=… color={ink}` does not recolour it: the header paints `header[900]` itself, so the
title is dark navy on a blue/purple gradient (3.11–4.11:1 in light across the 9 brands, against
4.62:1 for the gradient's own ink). Icons and badges inside it that read `currentColor` follow the
header, not the box.

**Apply:** put the ink on the header itself — `<ModalHeader color={resolved.ink} borderBottomWidth={0}>`
with `resolved = resolveGradient(stops, colors.white, colors.black)` — or use `LimitReachedModal`.
For an accent icon on the gradient, use `resolved.ink` unless the accent clears 3:1 on both
`resolved.from` and `resolved.to`; a theme `yellow[300]` drops to 2.61:1 in dark.

### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot — use `portalChildren`

All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
`Modal`, `AlertDialog`, a confirm dialog, a live region) silently never mounts; dev builds of all three
warn once per dropped child type. All three
look through `<>...</>` Fragments around a slot, at any depth (so `<>{cond && <DrawerFooter>...}</>` still renders)
and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot onto the real
header/body/footer — any other wrapper element still drops the slot.

**Apply:** pass a nested confirm dialog, toast host or live region to `Drawer` / `Modal` as
`portalChildren`. It renders **inside** the dialog content after the slots (a sibling in the portal
would be `aria-hidden` by Chakra, so a live region there is never announced); a nested `AlertDialog`
portals out on its own, stacks above and returns focus. It unmounts with the dialog, so reset its
open state when the parent closes. `ProfileCard` has no such prop — keep its confirm dialog outside,
as a sibling in a wrapping fragment. When a ternary picks between bodies, branch into a variable
rendered inside one body slot, rather than returning fragment-wrapped slots per branch. `Drawer`'s
misspelled `vaiant` is `@deprecated` — use `variant`.

A `Drawer` with no `DrawerHeader` is an unnamed dialog (axe `aria-dialog-name`) unless you pass its own
`aria-label` or `aria-labelledby`; dev builds warn once when it opens. `contentProps["aria-labelledby"]` is
overwritten, so it never names the drawer (`contentProps["aria-label"]` is kept).

### `FormDrawer` has no browser validation, and its submit button sits outside the `<form>`

It sets `noValidate`: validate in `onSubmit` and pass messages via `errors`. Error-summary focus
fires only after a submit; if validation is async, set `isSubmitting` synchronously in `onSubmit` so
focus waits for the result, otherwise errors that arrive later are not focused. The footer submit
button is tied to the form with the `form` attribute — Enter-to-submit works in browsers, but
jsdom / user-event only simulates it for a form with exactly one text field, so use
`fireEvent.submit(form)` in tests. `isSubmitDisabled` swallows both: `onSubmit` is not called while it is true.

### `QueryStateBoundary` evaluates JSX `children` even while loading

JSX children are built before the boundary decides what to show, so `data.items.map(...)` crashes
while `data` is still `undefined`. **Apply:** pass `children` as a function — `{() => <List
items={data.items} />}` — whenever it reads data that may not exist yet.

### `QueryStateBoundary` `isForbidden` and `hasData`

An `isForbidden` function is only called when `error` is set (never with `undefined`); `isForbidden:
true` shows the panel even with no error. `isLoading` + `hasData` keeps `children` visible during a
refetch, so pass `hasData` only when data is genuinely loaded — otherwise a first load shows a blank
region.

### `StatCard`'s delta colour follows `trend` vs `goodDirection`, not `trend` alone

Green when `trend === goodDirection`, red otherwise — a falling cost with `goodDirection="down"` is
green. Pass `onClick` for a clickable card (it renders its own `<button>`); never wrap it in one.

### `CircularProgress` `tone="info"` is the brand primary, not blue

Unlike `Tag` (`tone`) and `StatCard` (`iconTone`), where `info` is blue, the default `tone="info"` here paints the brand
primary scale. `aria-label` is required — the ring has no visible caption.

### `TextInput variant="filled"` has no border, only a fill that barely separates it

`filled` draws no resting border (`borderColor: "transparent"`), so the field's edge is the fill
alone. That fill sits well under
the 3:1 that WCAG 1.4.11 asks of a control boundary, in light and dark. The focus ring
and the invalid border still show, but a resting empty field can be hard to find.

**Apply:** use the default `variant="outline"` for any form a person must find and fill in. Keep
`filled` for fields whose position is already obvious from the layout.

### A clickable `TextInput` icon is a real button — give it a name

With `onRightIconClick`/`onLeftIconClick` the icon renders as a `<button>`. Without
`rightIconAriaLabel`/`leftIconAriaLabel` it is announced as "{label}: right icon action".

### `SelectSearch`'s `isRequired` shows the asterisk but never announces "required"

`SelectSearch` sets `aria-required` by hand on its Chakra `Input`, but Chakra's `useFormControl`
re-adds its own `"aria-required"` key *after* spreading your props, computed from the surrounding
`FormControl`. That `FormControl` is never given `isRequired`, so the attribute is recomputed as
undefined and stripped. Verified by DOM dump: the rendered `<input>` carries no `aria-required`
even when `isRequired` is passed. The visible asterisk comes from a separate custom label, so the
field *looks* required to sighted users and is silent to a screen reader.

**Apply:** prefer `Select` (`native={false}`) for new work — `SelectSearch` is not deprecated, but `Select` marks required
state on a plain `Box` combobox that Chakra does not rewrite. If you must stay on `SelectSearch`,
set the required state on your own wrapping `FormControl`. Note the obvious one-line fix inside the
component is not neutral: Chakra's `useFormControl` also emits native `required`, which would add
browser validation to a *filter* input that was never submitted before.

### `Select` with `onSearchChange` no longer filters locally (beta.48)

Passing `onSearchChange` means the server owns matching, so `Select` stops applying its own
substring filter to `options`. Before this, a fuzzy or ranked server result whose label did not
literally contain the typed text was fetched and then hidden. Pass `filterOptions={true}` to keep
the local pass on top, or `filterOptions={false}` to drop it even without `onSearchChange`.

**Apply:** if a server-backed `Select` suddenly shows more rows than it used to, that is this fix,
not a regression. Paged `Select`s should also pass `hasMore={false}` once the last page lands —
without it, `onLoadMore` fires again every time the user reaches the bottom.

### `Select` with `isMulti` keeps picks that leave `options` (beta.48)

`onChange` used to be built from the options currently in the list, so replacing `options` with a
server-search result silently dropped every earlier pick the new page did not contain — the chips
vanished and the next selection emitted a truncated array. Selected options are now remembered
independently of `options`.

**Apply:** nothing to change. If you worked around this by merging the old selection back in
yourself, that workaround is now redundant.

### `Table`'s column search covers every page (beta.48)

The per-column search box used to run after the page slice, so it matched only the rows on screen
while the pager still counted the whole data set. It now runs first: the page count, the
`1 - 20 of N` readout and the rows all come from the matched set, and a new search returns to page
1. Under `paginationMode="server"` the client still only sees the loaded page — filter on the
server there.

**Apply:** a client-side table that looked like it had "no matches" past page 1 now finds them.

### A button inside a `Select` `renderOption` row selects the row — use `optionAction`

`renderOption` output sits inside `role="option"`, whose click selects. A `<button>` you place in it bubbles to the row
(and fails axe `nested-interactive`, since options are presentational children). Pass `optionAction={{ icon, label, onAction }}`
instead: it renders a pointer-only, `aria-hidden` control that calls `onAction(option)` and stops the click. It is not
focusable, so give keyboard users the same action elsewhere.

### `Select`'s `onChange` never fires for the built-in placeholder

`Select` resolves the changed value against its `options` list and calls `onChange` only on a hit.
The built-in `placeholder` renders as its own empty-value option, which isn't in `options` — so
picking it resolves to no match and nothing fires. An "Any / All / None" reset built on the
placeholder alone is a dead control; the value snaps back and no filter clears.

**Apply:** fine for a plain pick-one-of-N. For a clearable filter, add an explicit
`{ id: "", label: "Any" }` entry to `options` instead of relying on the placeholder. With
`isReadOnly`, `onChange` never fires at all.

### `MultiSelect` is an email-chip input, not a picker

Despite the name, `MultiSelect` takes **no `options` prop at all**. Typed text is validated as an
email address and rejected if it doesn't match — there is no way to choose from a product/entity
list.

**Apply:** use `Select` with `isMulti` to pick multiple values from an options list.

### `Table`'s `onRowClick` is dead if every column has a `node` renderer

Row-click is gated **per column**, not per row: a column supplying a custom `node` renderer
swallows the click on that cell. Give every column a `node` and `onRowClick` becomes dead code —
accepted, typed, never called.

**Apply:** leave at least one column without a `node`, or put an explicit control inside a `node`
renderer instead of relying on row click.

Setting `onRowClick` makes every row a tab stop: Enter or Space on the focused row (not on a checkbox,
button or link inside it) fires `onRowClick` with the first visible column that has no `node`. A table
without `onRowClick`, one whose every column has a `node`, and a table that is `isLoading` get no tab
stop. The column resize handle is a bare `div` with a `mousedown` handler and is unreachable by keyboard.

**Apply:** expect one extra Tab stop per row once you pass `onRowClick`, and update any tab-order test.
Controls inside a row keep their own keys; give a `node` column a real `Button` or link for the actions
that must not depend on the row.

### `Table.renderRowDetail` runs for every row on every render, and `expandedRows` ids match strictly

It decides whether each row gets a chevron, so an inline function re-renders every row (defeating
`TableRow`'s memo) — wrap it in `useCallback` / `useMemo`. `expandedRows` ids compare with `===`, so
`1` and `"1"` are different: keep the id type the same as `row.id`. It is not the older
`row.content` + `isContent` expander (chevron before the checkbox, index-based); both can coexist,
but only `row.content` still disables grouped virtualisation.

### `error` without `errorMessage` shows no message — and erases `helperText`

Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
`SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Checkbox`, the `DatePicker` variants,
`PhoneNumberInput`) turns the border red and sets `aria-invalid` when `error` is `true` but renders
no message when `errorMessage` is empty. Worse, `helperText` only renders when `!error` — so the
guidance disappears exactly when it's needed, leaving a red field with no text.

**Apply:** never pass `error` without `errorMessage`. Gate `error` on a `touched` flag so a field
whose defaults arrive asynchronously doesn't open already red.

### A wrapper presetting a prop must destructure with a default, not rely on JSX prop order

Wrapping a library component to preset a prop (e.g. `Table`'s `variant`) as
`<Table variant="classic" {...props} />` silently reverts to the library's own default the moment a
caller passes `variant={undefined}` — a later spread always wins in JSX, even with `undefined`,
and the library component resolves that `undefined` via its own default parameter.

**Apply:**
```tsx
const AppTable = ({ variant = 'classic', ...props }: TableProps) => <Table variant={variant} {...props} />;
```
Applies to any library prop with a default value, not just `Table`'s `variant`.

### `FormWrapper` forwards extra props to the outer wrapper only

`id`, `data-*`, `aria-*`, `className`, `style` and handlers land on the outermost `Box`; the bordered content `Box`
receives nothing, and `children` is not type-matched.

**Apply:** put a margin override on `FormWrapper` itself (`className`/`style`); there is no prop for the content box's padding or border.

### `ContactForm`'s `apiKey` prop is a POST URL, not an auth token

Despite the name, `apiKey` is the fallback submit endpoint: only when no `onSubmit` is given, the form
does `fetch(apiKey, { method: "POST", headers: { "Content-Type": "application/json" }, body })` — never a
credential header. With both set, `onSubmit` wins and `apiKey` is never fetched. With neither, submit
shows an inline "API key missing" alert. A real API key/secret fails as an invalid URL or a non-OK
response, surfaced only as a generic "Failed to send message" alert, and there is no `headers` prop.

**Apply:** pass the full POST URL, never a token. If the endpoint needs auth headers, pass `onSubmit`
and make the request yourself.

### `ContactForm` can't tell its parent the submission result

It renders its own success/error alert from local state and has no `onSuccess` or `onError` prop. The
only hook is `onSubmit(payload)`, which replaces the `apiKey` fetch: it is awaited, a resolve shows the
success alert and clears the form, a throw shows "Failed to send message". The `apiKey` path tells the
parent nothing. Separately, the email field is validated for format but its "required" check is
commented out, so a blank email submits successfully with no error shown.

**Apply:** to redirect, toast or update state when the enquiry sends, pass `onSubmit` and do it there
(rethrow to show the failure alert). Don't rely on `email` being enforced as required — validate it
yourself first if that matters.

### `VerifyEmailOtp` can't accept alphanumeric codes, and appends "your new Pixel Account"

It wraps Chakra's `PinInput` without forwarding a `type`, so Chakra's `type="number"` default
applies — any letter typed is silently rejected (the character never appears, no error shown).
`VerifyEmailOtpProps` has no `type` field and no `...rest` escape hatch. Its `description` also gets
a second line, "your new Pixel Account", unless you pass `subtitle` (`""` drops it).

**Apply:** only use this component for numeric-only OTPs. Always pass `subtitle` outside the Pixel Account
product; for a non-English UI pass `labels`. For an alphanumeric code build the card from `PinInput`.

### `ApexLineChart` only ever renders one line, frozen at mount

`data`/`series` changes after the first render are silently ignored unless the component remounts
(no effect syncs later prop changes into state); `series` only reads index 0 for the line's name
despite the plural name; `variant="realtime"` replaces your data with random numbers on an interval
rather than animating it. Its `legendStyle` prop also type-checks but has no effect, unlike the
identical prop on `ApexPieChart`/`ApexPolarCharts`.

**Apply:** remount (`key`) `ApexLineChart` when the underlying data changes. Don't use
`variant="realtime"` expecting it to reflect a live feed.

### `ApexPieChart`'s `showDataLabels` can be silently overridden by chart height

With the default `labelPlacement="auto"`, a **numeric** `height` under 240 forces labels off even
with `showDataLabels={true}` — no warning. Slices under `minLabelPercent` (default 8%) render blank
label text rather than being hidden as a unit.

**Apply:** pass `labelPlacement="inside"`/`"outside"` explicitly for small numeric-height charts;
lower `minLabelPercent` when every slice needs a visible value.

### `ApexBarChart` and `ApexAreaChart` silently drop `data` when `series` is also passed

`series` always wins over `data` with no warning, on both components — a natural mistake when
migrating from single- to multi-series. Separately, `ApexBarChart`'s `barColor` array only paints one
color per bar when `distributed={true}`; with the default `false`, every bar takes `barColor[0]` and
the rest of the array is silently unused. `ApexRadialChart`'s `hollowSize` has its own unrelated trap
— it's silently overridden to a fixed `"52%"` whenever `variant="multi"`.

**Apply:** never pass `data` and `series` together on `ApexBarChart`/`ApexAreaChart`. Set
`distributed` whenever `ApexBarChart`'s `barColor` has more than one color. Don't expect
`ApexRadialChart`'s `hollowSize` to apply under `variant="multi"`.

### `Skeletons`' `isLoaded` and `borderRadius` only work for `type="skeleton"`

`type="circle"`/`"text"` never receive `isLoaded`, `borderRadius` (or `children`/`bg`/`color`/
`fadeDuration`) — passing them compiles and is silently dropped; the shimmer never stops no matter
what `isLoaded` is set to. Neither `Skeletons` nor `ProgressBar` forwards a `ref`; `ProgressBar`'s
`color` is `@deprecated` (use `colorScheme`).

**Apply:** for `circle`/`text`, control visibility by conditionally rendering the `Skeletons` element
itself, not via `isLoaded`.

### Eight exports start with `Notification` and only the Notification Center family is a tray

Autocomplete offers `Notification`, `NotificationBell`, `NotificationPanel`, `NotificationList`, `NotificationItem` and the
newer `NotificationCenter`, `NotificationInbox`, `NotificationPreferences`, `NotificationRow`, `NotificationDetail`. Only
`Notification` is unrelated — a standalone countdown card from a different era, and picking it for an inbox row is the
common mistake.

| Export | What it actually is |
| --- | --- |
| `NotificationCenter` | **Use this.** The bell plus a two-tab panel (Needs you, Activity) with inline approvals and undo |
| `NotificationInbox` | **Use this** for the full page: tabs, search, bulk actions, reading pane |
| `NotificationPreferences` | **Use this** for the settings page: type-by-channel switches with autosave |
| `NotificationRow` / `NotificationDetail` | One entry as a row / in full, for your own surface inside a `NotificationCenterProvider` |
| `NotificationBell` | The badge/bell button only. Requires `aria-label`; it renders no list. `NotificationCenter` wraps it |
| `NotificationPanel`, `NotificationList`, `NotificationItem` | **Deprecated**, behaviour unchanged. Replaced by `NotificationCenter`, `NotificationInbox` and `NotificationRow` |
| `Notification` | **Not deprecated.** A dated countdown card — its dot colour comes from `dueDate`/`endDate` math, not from a tone. `NotificationRow` cannot replace it: `formatRelativeTime` clamps every future date to "Just now" |

`Notification` is kept only because nothing else does that date-driven countdown; it is not a thin
alias, so it has not been removed.

**Apply:** for a notification tray use `NotificationCenter`; for a page, `NotificationInbox`. Reach for `Notification` only
when you specifically want the deadline-countdown card, and read the gotcha below before you do.

### Notification Center: four silent traps

- **Counts must come from the server.** `counts.needsYou` and `counts.unread` are never derived from the loaded `entries`,
  because a paged list under-counts. The library only adjusts them optimistically and never below 0.
- **`onAction` must reject with a kind to get the right row.** `notificationActionError("conflict" | "forbidden" |
  "reasonRequired" | "failed", message?)` (or an HTTP 409/403) picks the status line. Any other rejection reads as
  `failed` with Try again, so a "someone already decided this" case looks like a retryable error.
- **A feature exists only when its callback is passed.** No `onArchive` means no Archived tab and no archive button; no
  `onRestore` no restore; no `onAction` no decision buttons; no `onMarkRead` no read toggle. Nothing is disabled, it is
  absent.
- **One provider per page, or the components do not share state.** `NotificationCenter` and `NotificationInbox` given their
  own source props each run a private provider with its own undo queue. To share, pass the props to one
  `NotificationCenterProvider` and none to the components. Keep `categories` and `labels` stable references, and mount a
  `ToasterProvider` above (`PixelizeThemeProvider` supplies one).

### `Notification`'s `onClick` only reaches the title text, and its status dot has two gates

`onClick` is wired solely to the title text — the card, avatar, and description are not clickable
despite the generic prop name. Separately, `warningColor`/`errorColor`/`successColor` only take
effect when `showStatus` is also `true`, and populating `notification.status` (e.g. `"blocked"`) has
no effect at all — the dot's color comes purely from `dueDate`/`endDate` math.

**Apply:** for a fully clickable card, wrap it yourself with your own `onClick`. Always pair the
three color overrides with `showStatus`; don't use `status` to drive dot color.

### `FeedbackForm` shows a success toast and resets even with no `onSubmit`/`submitUrl`

Both props are optional, and when neither is provided, submit still falls through to the success
toast and form reset — validation, spinner, and reset all work end-to-end while the payload is never
sent or captured anywhere. Separately, `defaultValues` only seeds state at mount (no resync if it
arrives later from an async fetch), and its toast comes from `useToaster`, so it throws outside a
`ToasterProvider` (`PixelizeThemeProvider` and `withTheme` mount one) — the same portal issue
documented for `Toaster`/`Modal` can still hide the toast when this form is embedded in a `Modal`.

**Apply:** always pass `onSubmit` or `submitUrl` — treat a bare `<FeedbackForm />` as a bug, not a
minimal valid usage. Key the element to force a remount if `defaultValues` arrives late. Verify the
toast actually appears if embedding inside a `Modal`.

### `Checkbox`'s `variant` is a no-op

Typed and accepted (`@deprecated`), but `Checkbox.styles.ts` defines no `variants` key, so no value changes the
look. (`error` now sets `isInvalid` and links its message — no need to pass both.)

### `Slider`'s pagination dots can desync from the visible slide

The main track sorts `images` by `order`; the pagination dots map over the unsorted array. Passing
`images` out of `order` sequence makes the active dot point at the wrong slide.

**Apply:** pre-sort `images` by `order` before passing them in.

### `TextLabel`'s `isInformation` alone renders no icon — it also needs `informationMessage`

The info-tooltip icon is gated on `isInformation && informationMessage` — both must be truthy or
nothing renders, not even a bare icon. `TextLabel` is the shared label engine behind most fields in
the library (`TextInput`, `NumberInput`, `PhoneNumberInput`, `RadioButton`, `PinInput`,
`InputSwitch`, `SelectV2`, the `DatePicker` family, `InputTextArea`, `SelectSearch`, `Search`,
`SearchSelect`, `MultiSelect`, `Select`), so the same silent no-op repeats at every one of them.

**Apply:** always pass `isInformation` and `informationMessage` together; never treat
`isInformation` alone as "use a default message."

### `Timeline`'s `onEditNote` editor doesn't auto-close without `editNoteLoading` — unlike add-note

Add-note has a back-compat fallback that closes its editor immediately if `addNoteLoading` is never
wired. Edit-note has no equivalent fallback — its only close path is an effect watching
`editNoteLoading` transition `true → false`. Wire `onEditNote` without `editNoteLoading` and Save
looks like it does nothing: the form stays open with no error or feedback.

**Apply:** always pass `editNoteLoading` alongside `onEditNote`, even a client-only flag flipped
right after the call resolves.

### `Timeline`'s `events` prop is `@deprecated` and still renders nothing

Pass `timelineEvents`; `events` (and the `TimelineEvent` type) is never read, not even as a fallback.
Rows are now static unless you pass `onEventClick`.

### `Timeline` drops events with an unparseable `created_at`, with no visible trace

An event whose formatted date resolves to `"Invalid Date"` is excluded from every date group — not
shown in a fallback bucket, just gone. The only signal is a `console.warn` inside the formatter.

**Apply:** validate/normalize `created_at` before handing events to `Timeline` — a bad timestamp is
silent, total content loss for that row.

### `Reorder`'s `onReorder` fires even when nothing moved

A drag that ends back at its starting index still has a drop target and still calls `onReorder` with
a new array reference in the same order.

**Apply:** compare source/destination index (or diff the array) before persisting a reorder, if a
no-op write matters. `showRemoveIcon`/`onRemove` are declared on `ReorderListProps` and work as
expected; a missing-name item's image alt falls back to `item-<1-based position>`.

### `Divider` isn't exported from the package at all

`src/Components/Divider/` doesn't appear in `src/index.ts`, though it still compiles into `dist/`
and is deep-import-reachable. The library's own `Divider` is always vertical, fixed size/color,
zero props — a different thing from the general-purpose (horizontal, styleable) `Divider`
re-exported from the `Primitives` barrel.

**Apply:** for a divider in a consuming app, use the `Divider` from `Primitives`, not this library's
own.

### `KanbanActions` is exported but still not wired into `KanbanBoard`

`KanbanBoard`'s header select/edit/create bar is driven by its own `kanbanSelect`/`kanbanEdit`/
`kanbanCreate` props, via a different internal component. `KanbanActions` is a separate, standalone
component (exported from the package root as of 2.4.2-beta.39) that a consumer must render and wire
up itself — its `options`-driven buttons always render with no permission gating, unlike
`KanbanBoard`'s own header actions, which respect `permissions.isEditable`/`isCreatable`.

**Apply:** use `KanbanBoard`'s own `kanbanSelect`/`kanbanEdit`/`kanbanCreate` props for the board's
built-in header actions. Reach for `KanbanActions` only when building a custom toolbar outside
`KanbanBoard`, and gate it yourself — it has no permissions awareness of its own.

### `KanbanBoard`'s `permissions.isEditable: false` disables card drag but not column-reorder drag

Card `Draggable`s get `isDragDisabled={!canDrag}`; the column-reorder `Draggable` (active when
`enableColumnReorder` is true) never checks it — a "read-only" board still lets users reorder whole
columns.

**Apply:** also set `enableColumnReorder={false}` to fully lock a read-only board.

### `KanbanBoard`'s `collapsedColumns` only seeds initial state — not a live controlled prop

It seeds a `useState` lazy initializer once, on mount. Without the `preferences` feature wired, a
later render passing a different `collapsedColumns` value does nothing, despite the name implying a
controlled value.

**Apply:** to force a column open/closed post-mount without `preferences`, remount the board (change
its `key`) rather than re-passing the prop.

### `KanbanBoard`'s `account.customNode` silently drops delete/open/expand for that one card

An item with `customNode` set renders that function instead of `AccountCard`, so `onDelete`,
`onOpen`, `isDeletable`, and expand/collapse never apply — even though they read as board-wide
props. Mixing plain and `customNode` items in one column produces inconsistent per-card behavior.

**Apply:** don't expect board-wide card actions to reach a `customNode` card; wire them inside your
custom render instead.

### `KanbanBoard`'s `AccountCard` only renders string-typed fields

A numeric field on an `Account` (allowed by its index signature) is never shown in the card's field
list. The label is the key run through `toWords`, which splits snake_case, kebab-case and camelCase:
`account_name` renders "Account Name" and `nextFollowUp` renders "Next Follow Up".

**Apply:** keep numeric display values as strings.

### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id

Despite the callback parameter being named `colId`-adjacent, what's actually passed is
`columns[colId].items.map(item => item.id)` — the cards that were in the column, never the column's
own id.

**Apply:** track which column was being deleted another way (e.g. hover/selection state captured
before the click) if you need the column id itself.

### `isRequired` is decorative on some fields, native on others — same prop name, different behavior

`NumberInput` sets native `required` (browser bubble, blocks submit).
`TextInput` and `InputTextArea` set only `aria-required` — announced, but no native validation.
`PhoneNumberInput` and `PinInput` pass it only to the label (draws a `*`); the field gets nothing.

**Apply:** don't rely on `isRequired` for native form validation — validate required fields yourself
regardless of which component you're using.

### `NoteTextArea`'s `saveButtonLoading` going `true → false` clears the draft even on a failed save

The effect that resets note/title/files fires whenever `saveButtonLoading` goes falsy — there's no
separate success/failure signal, so a parent that turns off the loading flag after a failed save
silently discards everything the user typed.

**Apply:** don't flip `saveButtonLoading` back to `false` on failure without your own recovery path
(e.g. keep the draft in your own state and re-seed it).

### `InputSwitch` now renders `ToggleSwitch` — `.chakra-switch__*` selectors match nothing

`InputSwitch` is `@deprecated` and wraps `ToggleSwitch`, which is not a Chakra `Switch`. An `sx`
targeting `.chakra-switch__track`/`__thumb` still compiles and lands on the wrapper, but styles
nothing. `colorScheme` and `isReadOnly` are real now (colorScheme used to be silently discarded);
`variant`/`spacing`/`isFocusable` stay typed `@deprecated` no-ops. **Apply:** migrate to
`ToggleSwitch` (`fieldLabel` for the label InputSwitch drew above the track) and drop those selectors.

**This breaks tests, not types.** Chakra's `Switch` rendered `role="checkbox"`; `ToggleSwitch`
renders the correct `role="switch"`, so `getByRole("checkbox", { name })` silently stops matching
while everything still compiles. Two consumer repos hit this on the beta.44 upgrade. **Apply:**
change those queries to `getByRole("switch", …)`.

Same shape of trap on `Tabs`: the owned `Tab` forwards no `data-testid`, so `getByTestId("…-tab-…")`
queries must become `getByRole("tab", { name })`.

### `AlertDialog`'s `colorScheme`/`size`/`status`/`variant`/`addRole` are dead props

Typed but never read, and `@deprecated` as a group (editors may not strike each one through). Use
`tone="danger"` for a red Confirm, or `button1Style`/`button2Style`.

### `AlertDialog`'s `onClose` also fires on Escape and overlay click

`closeOnEsc`/`closeOnOverlayClick` default to `true`, and every dismiss path calls the same
`onClose`. **Apply:** don't read `onClose` as "the user chose Cancel"; pass both as `false` when
only the buttons may close it.

### `ToolTip`'s `overflowOnly` silently no-ops on non-single-element children

The truncation ref only attaches when `children` passes `React.isValidElement` — a bare string, a
Fragment, or multiple children skip that branch, so the tooltip always shows instead of
only-when-truncated (the opposite of the prop's contract).

**Apply:** give `overflowOnly`/`OverflowToolTip` exactly one real element as `children` (e.g. a
single `Text noOfLines`), never a Fragment or bare text.

### `ToolTip` mounts Chakra's tooltip only after the first hover or focus

Until the trigger is hovered or focused (or `isOpen`/`defaultIsOpen` is set), `ToolTip` renders just the
child, with no tooltip element and no document listeners. A test that mocks Chakra's `Tooltip` and
expects it mounted at render time must hover or focus the trigger first
(`fireEvent.pointerEnter(trigger)` or `userEvent.hover`).

### A keyboard-focusable `ToolTip` trigger must be a native control — never a `span` with `aria-label`

`ToolTip` adds `aria-describedby` to its trigger but no role and no name. An icon-only trigger written
`<Box as="span" tabIndex={0} aria-label={hint}>` (a column-header hint, an info icon) fails axe
`aria-prohibited-attr`: `aria-label` is not allowed on a role-less span, so a conforming screen reader may drop
it and announce a nameless generic element (Chrome's tree still shows the name).

**Apply:** use `<Box as="button" type="button" aria-label={hint} bg="transparent" border="0" p={0}
cursor="default">`. It is still a Tab stop and the tooltip still opens on focus; measured pixel-identical to
the span, closed and focused. `role="img"` on the span also passes axe but changes the focused state.

### `Toaster`'s `showToast({ children })` is a dead prop, and its two `onClose`s are different functions

`children` is `@deprecated` and never read — only `title`/`description`/`actions` render. The `onClose` you pass to `showToast` is wired to
Chakra's `onCloseComplete` (fires after the exit animation, on any dismiss path); the `onClose` your
`actions` render-prop receives is a different, immediate per-toast dismiss function.

**Apply:** pass `description`, not `children`. Don't assume your `onClose` fires the instant the
user clicks close — it fires after the exit transition completes.

### `ButtonGroupIcon`'s dropdown needs `rightIcon` **and** `rightIconDropdown` both set

The `Menu`/`dropdownOptions` branch only renders inside `rightIcon && rightIconDropdown`. Supplying
`dropdownOptions` alone, or `rightIconDropdown` without `rightIcon`, silently renders nothing on the
right side. Separately, `onButtongroupClick` is wired to Chakra `ButtonGroup`'s own `onClick` on the
wrapping div — native DOM bubbling means it fires on every click inside the group (left icon, center
button, right icon/dropdown), not just a "clicked outside the buttons" signal.

**Apply:** always set `rightIcon` + `rightIconDropdown={true}` together for the dropdown. Don't use
`onButtongroupClick` to detect background clicks — inspect `event.target` if you need to distinguish.

### `Card` already wraps `children` in a padded `CardBody` — a nested one doubles the padding

`header`/`footer` now render, and `children` sit in a flex `CardBody` laid out by `direction`/
`align`/`justify`. Code written for the old Card that nested its own `CardBody` now gets padding
twice. `colorScheme` does nothing (the Card theme never reads it) and `color` is its `@deprecated` alias; the three divider props are `@deprecated` and
draw nothing.

**Apply:** drop the nested `CardBody`, or pass `bodyProps={{ p: 0 }}`.

To change the padding, use `padding="none" | "2xs" | "xs" | "sm" | "md" | "lg"`. `sx={{ p: ... }}` on
the container *adds* to the body padding (double inset) and `sx={{ p: 0 }}` does nothing. `padding`
is no longer Chakra's style prop (omitted from the type) — use `p` for a raw value. With
`padding="none"` the header keeps `xs` padding.

### Commerce kit — read before building a shop screen

`ProductCard`, `ProductDetails`, `VariantSelector` and the bag pieces share one contract: pass
`axes: OptionAxis[]` + `variants: ProductVariant[]`, never per-vertical props. A variant's
`options` must set every axis, or `findVariant` returns `undefined`.

- **`layout="auto"` on `MediaGallery` and `ProductDetails` follows the container, not the window**
  (560px / 960px of their own width), falling back to the window query only until the first measure.
  `ProductCard`'s `layout` (`grid`/`list`/`rail`) has no `auto`. `QuickAddSheet`'s `presentation="auto"`
  (`ProductCard`'s `quickAddPresentation`) reads the window (modal from `48em`); pass it explicitly inside a phone-width frame.
- **Drawers and modals portal to the window, never into your phone frame.** `ProductCard`'s quick-add
  sheet needs `quickAddPresentation="drawer"` and `quickAddDrawerProps={{ maxW: "390px !important", mx: "auto" }}`
  there; the `!important` is needed because Chakra's slide sets an inline `max-width: 100vw`.
- **`OptionChip` `unavailable` is visual and announced only** — `onSelect` still fires so a parent
  can re-derive the other axes. Guard it yourself if the pick must be refused.
- **`WishlistToggle` flips its default name and `aria-pressed` together** — on cards pass a fixed
  `label` (`Save ${title}`).
- **Group children must be direct children.** `AddressCardGroup` / `PaymentOptionGroup` read the
  roving tab stop from their children's `value`; a wrapper component hides it.
- **`BagBar` and `StickyBuyBar` are CSS-sticky, not fixed.** Make them the last child of the
  scrolling container; `StickyBuyBar` also needs a parent taller than the viewport.
- **"N left" appears only from a real `stock` count** at or below `LOW_STOCK_THRESHOLD` (5).

### `PaymentCard`'s `onHover` never fires its `"card"` variant, and the CTA hides unless `isRenewal`

`onHover`'s type promises `"card" | "button"`, but no hover handler exists on the outer plan card —
only the CTA button wires hover. Separately, the CTA (and its callbacks) disappears whenever
`isActive` is true unless `isRenewal` is also set, regardless of `plan.buttonText`.

**Apply:** don't build "card" hover analytics on this prop. Pass `isRenewal` to show a CTA on the
current/active plan.

### `OrganizationDetails`' `defaultOrg === 1` silently overrides an explicit `canDelete: true`

`isProtected` is computed as `item.defaultOrg === 1 || canProtect` — `defaultOrg` short-circuits the
`canDelete`/role check unconditionally. An org that is both the user's default and marked
`canDelete: true` still renders a disabled delete button, with only a tooltip explaining why.

**Apply:** don't rely on `canDelete` alone to guarantee delete is enabled — check `defaultOrg` too.

### `OrganizationDetails`, `CustomModulesTable`'s create/edit/delete modals show no error UI on rejection

`onCreateOrganization`/`onDeleteOrganization`/`onEditOrganization` (and `CustomModulesTable`'s
`onUpdateModule`/`onDeleteModule`) are `await`ed and the modal only resets on success — a rejection
is an unhandled promise rejection with zero visible feedback.

**Apply:** wrap your own handler in try/catch and show your own error toast; the library never does
it for you.

### `OrgSwitcher`'s `onChange` doesn't fire on re-selecting the already-active org, and has a closed prop list

Re-clicking the current org closes the popover but skips `onChange` entirely (`org.id !== value` gate)
— don't rely on it for a side effect that must run on every click (analytics, refetch). Separately,
the trigger has no `...rest`/`ref` escape hatch: a `data-testid`, `id`, or positioning `ref` can't
reach it.

**Apply:** don't depend on `onChange` firing for a repeat pick. There's no supported way to attach
test hooks or a ref to the trigger.

### `OrgSwitcher`'s popup dialog is named by `ariaLabel`, and its rows follow `Select`'s state ladder

The open `role="dialog"` now has `aria-label={ariaLabel}` (it had none), so a translated app should pass `ariaLabel` in its own
language; the trigger name still reads `${ariaLabel}, ${org name}`. Rows are 4px inset with the option radius, fill the active org,
and ring on `:focus-visible` only.

### `OrgSwitcher display="full"` still squeezes the navbar title on phones — use `display="auto"`

Inside a `NavigationBar` `moreIcon` cluster, a full trigger needs about 88px (avatar + chevron) even
when its label truncates to nothing, and the title is the first thing to give way. With a long org name
the title is invisible on 320-375px bars, and a smaller `maxWidth` does not change that.

**Apply:** `display="auto"` (avatar + chevron below `md`, full from `md`) or `"avatar"`. Both layouts
name the trigger `${ariaLabel}, ${org name}` (the placeholder when no org is active), and in avatar mode
the name appears in a tooltip that wraps a `span` around the trigger, so don't pass the trigger a ref. `auto` falls back to `"full"` where
`matchMedia` is missing (SSR, jsdom). `NavigationBar`'s `moreIcon` root is `min-width: 0`: give your
own icon buttons `flexShrink={0}` and let any label truncate.

### `UpgradeButton`'s gold icon accent silently falls back to the label color on low contrast

Two different ratios apply. The label and subtitle ink clears **4.5:1** (AA text) on both gradient stops:
`resolveGradient` darkens the stops until it does, so a custom `gradient` may paint darker than the
colors you passed (the built-in variants are pinned per brand and mode in `upgradeButtonInk.test.ts`).
The gold icon accent only needs **3:1** (non-text) against both of those painted stops; when it misses
either, the icon silently switches to the label ink. An explicit `iconColor` is used as given, unchecked.

**Apply:** don't assume the icon stays gold with a custom `gradient` — check contrast yourself if the
gold accent is load-bearing for your design.

### `PlanPill`/`PlanBadge` always render as a real, focusable `<button>` — even with no `onClick`

`as="button"`, `cursor="pointer"`, and the hover-lift are unconditional. Omitting the optional
`onClick` does not get you a static/informational pill — it stays tabbable and screen-reader
-announced as a button regardless.

**Apply:** there is currently no way to get a non-interactive plan badge from this component.

### `LimitReachedModal`'s `onUpgrade` never triggers `onClose`, and needs both `limit` and `used` to show usage

Clicking the CTA calls only `onUpgrade` — confirmed by the component's own test. Separately, the
inline usage line renders only when **both** `limit` and `used` are non-nullish; passing just one
silently omits the whole line.

**Apply:** close the modal yourself inside your `onUpgrade` handler if upgrading should dismiss it.
Always pass `limit`/`used` together, or neither.

### `CustomModulesTable`'s `ModuleItem.module_id` is the one snake_case field on an otherwise camelCase type

A loosely-typed API response cast straight to `ModuleItem[]` can leave `module_id: undefined` with
no compile error, colliding React `key`s.

**Apply:** map the API field explicitly to `module_id` — don't assume this type is uniformly
camelCase like its sibling payload type (`UpdateModulePayload.moduleId`).

### `RolesPermission`'s permission matrix silently reroutes every column for an "Automation" row

Any `permissions[]` row whose `module` case-insensitively equals `"automation"` collapses every
column onto a single `automation` boolean — only the Read cell renders/toggles, and clicking it
calls `onPermissionChange(module, "automation")`, not `"read"`. Separately, `roles_id` (typed
`string`) is coerced via `Number()` before `onDeleteRole` fires — a UUID or ObjectId silently
becomes `NaN`.

**Apply:** if a row's `module` can be `"automation"`, expect only its Read checkbox to work, toggling
`automation` — create/edit/delete/import/export are unreachable for that row. Only pass
numeric-string `roles_id` values.

### Several delete/deactivate modals close before their async handler can be awaited

`RolesPermission`'s `DeleteRoleModal` and `UserDetails`' `DeactivateConfirmModal` call their
handlers fire-and-forget (typed plain `() => void`) and close synchronously in the same tick — the
opposite failure mode from the create/edit modals above, whose handlers are genuinely awaited.

**Apply:** any `isLoading`/spinner wiring for delete/deactivate can never be seen — handle
loading/error UI outside these two modals (e.g. a toast).

### `UserDetails`' Change Role and Resend Invitation buttons silently no-op when `userId` is null

Only Deactivate actually disables itself when `selectedUser.userId` is null — the other two stay
visually enabled and do nothing on click. Separately, `ChangeRoleModal` pre-selects the current role
by case-insensitive **label text** match, not an id — any mismatch (whitespace, a renamed role)
silently opens the modal with nothing pre-selected, no error shown.

**Apply:** always populate `selectedUser.userId` when those two actions should be usable. Keep
`currentRole` as the exact display label kept in sync with `roleOptions[].label`.

### `FileUploader`'s `onFilesChange` discards the real `File`, and its `acceptTypes`/`maxFiles` enforce nothing

`FileUploader` hands back lightweight `{id, name, size, previewUrl}` metadata — the original `File`
is discarded in `handleFiles`, so it can never back an actual upload. `acceptTypes` only sets the
native picker's `accept` attribute; drag-and-drop ignores it completely and no code path rejects a
wrong-type file. Exceeding `maxFiles` silently truncates the list with no error.

**Apply:** need real file bytes or enforced validation → use `FileUpload`, not `FileUploader`.

Each image's `previewUrl` is a `blob:` URL. `FileUploader` revokes it when the image is removed,
truncated by `maxFiles`, rejected by `maxTotalSize` or still listed when it unmounts. Do not
reuse a `previewUrl` from `onFilesChange` after the component is gone. (`FileUpload` revokes its own
thumbnail URLs.)

### `DatePicker`'s `pickerType` does nothing when `isRange` is set, and no variant has a seconds control

`RangeDatePicker` never reads `pickerType` — whether time inputs show is controlled entirely by
whether `dateFormat` contains time tokens. Separately, every time-capable picker caps at minute
granularity regardless of `dateFormat` — a format containing `ss` compiles and parses but seconds
are never user-editable.

**Apply:** for a range picker, control the time row via `dateFormat`, never `pickerType`. Don't
request second-precision input from any DatePicker variant.

### `SingleDatePicker`/`TimeOnlyPicker` default to `Date` objects — opt into strings with `valueFormat="iso"`

By default `selectedDate`/`value`/`onChange` speak `Date`. `valueFormat="iso"` switches one instance
to strings: `yyyy-MM-dd` (date), `HH:mm` (time, 24h), local `yyyy-MM-dd'T'HH:mm:ss` (datetime, no
offset). An unparsable string reads as `null`. `RangeDatePicker` and legacy `DatePicker` stay Date-only.

**Apply:** use this instead of `TextInput type="date"/"time"` plus hand-rolled ISO parsing.

### `TimeOnlyPicker` ignores the date-range props and `autoComplete`

Label and `name` now work. `minDate`/`maxDate`/`disableFutureDates`/`disablePastDates` are still
dropped, and `autoComplete` is forced to `"off"`. `DatePicker`'s `disabled`/`placeholderText` are
`@deprecated` — use `isDisabled`/`placeholder` (the new name wins when both are set).

### `Editor`'s `config` prop can silently break dark mode, and its `key` prop can never reach Jodit

`Editor` computes `config.theme`/`config.popupRoot` itself to fix Jodit's dark-mode/popup theming,
then spreads your `config` on top — any `theme`/`popupRoot` key you pass wins and silently disables
the fix. Separately, `key` is typed as if readable, but React reserves and strips it before the
component sees `props`, so it's always `undefined` internally and can't force a remount. `editorRef`
is also `null` until Jodit's lazy-loaded chunk resolves — a mount-time effect reading it gets nothing.

**Apply:** never set `theme`/`popupRoot` inside the `config` you pass to `Editor`. To force a
remount, wrap `<Editor>` itself in a keyed parent, not via `Editor`'s own `key` prop.

`Editor` keeps Jodit's defaults for the source view, and those defaults (`sourceEditor: "ace"`,
`beautifyHTML: true`) load Ace and js-beautify from `cdnjs.cloudflare.com` when the editor mounts.
Under a strict Content-Security-Policy, offline, or in a privacy review, those requests are blocked
or are an outbound call you did not ask for.

**Apply:** pass `config={{ sourceEditor: "area", beautifyHTML: false }}` to drop both calls (source
mode becomes a plain textarea), or point Jodit's `sourceEditorCDNUrlsJS` and `beautifyHTMLCDNUrlsJS`
at copies you host.

### `PdfViewer` `getBlob` — fetched on mount only; the toolbar already has Open and Download

- **Swapping the file needs a new React `key`.** `getBlob` is read through a ref and fetched on mount,
  so an inline arrow is safe, but changing it never refetches — the old document silently stays.
- **The default fallback shows only a message while the toolbar is visible**; with
  `showToolbar={false}` it adds its own Open and Download buttons. `getBlob` mode makes the toolbar's
  actions work for authed files, so an app need not render its own — or pass `showToolbar={false}`.
- Pass exactly one of `pdfUrl` / `getBlob`.

### `WizardDialog` — `validate` must be pure; controlled `stepId` does not unlock steps

`validate` runs on Continue, on Finish, and again for every step on Finish. Passing `stepId` controls
the visible step only: stages past the furthest valid step stay disabled. Esc, close, Back and Cancel
are disabled while `isFinishing`. With `chrome="inline"` there is no Modal at all: no focus trap, no Esc,
no close X and no `role="dialog"` (the host window supplies them), `size` is ignored, and nothing renders
while `isOpen` is false; Cancel still calls `onClose`, so the host must close itself there.

### `PageHeader` actions wrap by default

`actionsLayout` defaults to `"auto"`, so actions that do not fit drop below the title at `md`+. A
test asserting the old single-row layout needs `actionsLayout="inline"`.

### `Editor` merge fields — chips, raw values and stale closures

- **Chips are `<span data-field contenteditable="false">`.** Do not style or strip `[data-field]` in
  consumer CSS or sanitisers, and sanitise the raw `${path}` value `onChange` reports, not Jodit's HTML.
- **A hand-typed `${path}` stays plain text** until `value` is next applied from outside; only tokens
  inserted through the menu / `apiRef` or already present in `value` become chips. Unknown-token
  detection still runs on the raw value.
- **`config.extraButtons[].exec` goes stale** (the memo key is `JSON.stringify`, which drops functions).
  Use `toolbarButtons` — React buttons, always current.
- **`jodit-react` binds `onChange` / `onBlur` once, keyed on handler identity, not `config`.** After
  Jodit is re-created (readonly or height change) a stable handler stops receiving events. `Editor`
  binds them itself per instance; don't copy the pattern when wrapping Jodit directly.

- **`EditorMergeField` `object`, `objectDescription`, `description`, `example`, `source` and `image` do nothing inside
  `Editor`.** They are metadata for a field browser you build; only `path`, `label`, `group` and `sample` are read.

### `toCsv` — no BOM by default, and formula-like text gains a `'`

Excel reads a BOM-less CSV as ANSI and garbles non-ASCII text: pass `{ bom: true }` when the file is for Excel. A cell
starting with `=`, `+`, `-` or `@` (a signed plain number excepted) is written with a leading `'`; set
`escapeFormulas: false` on a column such as phone numbers (`+91 ...`) only when you control every value in it.

### `Editor`'s Jodit toolbar is fixed for screen readers and keyboard, from our wrapper only

Jodit's own markup (`node_modules/jodit`) put `aria-label` on each button's `role="listitem"`
wrapper instead of the real inner `<button>`, used the invalid ARIA role `"trigger"` for its
dropdown-chevron spans, gave `listitem` no `role="list"` ancestor, and ships every toolbar button
at `tabindex="-1"` unless `config.allowTabNavigation` is on — so by default the toolbar failed
axe's `button-name`/`aria-roles`/`aria-required-parent` and was entirely unreachable by keyboard.
`Editor` now sets `allowTabNavigation: true` by default (same override rule as `theme`/`popupRoot`
above — a value you pass in `config` wins) and runs a `MutationObserver`-backed DOM pass
(`joditAccessibility.ts`) that copies each button's real name onto it and fixes the two roles.

**Apply:** nothing — this is automatic. Set `config.allowTabNavigation: false` only if you
deliberately want the toolbar out of the tab order; you'll reintroduce the keyboard-reachability gap.

The editing area is a `role="textbox"` that Jodit leaves nameless. `Editor` names it from `label` when
there is one, else from `labels.editor` (default `Rich text editor`), and sets `aria-readonly` while
`config.readonly` is on. Two unlabelled editors on one page announce identically unless each gets its own
`labels.editor`.

Jodit also ships the editing area at `tabindex="-1"`, so no keyboard could reach the text and a scrollable
read-only editor could not be scrolled. `Editor` sets `tabIndex: 0` (a `config.tabIndex` you pass wins) and
lights the Jodit frame while focus is inside it. Tab then walks toolbar, editing area, Jodit's status-bar
buttons (`config.statusbar: false` drops those). Inside a table cell Tab and Shift+Tab stay with Jodit (next
cell, a new row after the last, a new row above the first): arrow out of the table before tabbing away.

### `SearchSelect` and `SelectSearch` search `option.label` only (so does `Select` unless you widen it)

Neither checks a rendered secondary field (`option.description`, a custom `view` node, `option.email`
on a profile row) — typing text that's visibly on-screen in a secondary field returns no match. `Select`
and `SelectV2` (popup mode) match the label too, until you pass `searchFields={["label","description"]}`
or a `filterOption(option, query)`.

**Apply:** on `SearchSelect`/`SelectSearch`, fold a secondary field into `option.label` yourself, or
pre-filter `options` before passing them in.

### `SearchSelect` selected rows are filled now, and the ring is keyboard-only

Checked or selected option rows paint the `Select` selected fill; hover and keyboard cursor step it deeper, and
Arrow/Home/End add a 1px neutral inset ring (the mouse clears it). A test or screenshot that expects an unfilled selected
row, or reads the label colour from `text[700]`, now sees the neutral ink ladder in light. Behaviour, ids and ARIA are unchanged.

### `SelectSearch` keyboard focus draws a neutral ring, not the browser outline

Rows are real focus targets; `:focus-visible` now paints the `Select` 1px inset ring (and `outline` stays transparent for forced-colors),
and a reopened single selection is filled. A visual or E2E test that expects the UA outline on a focused row no longer sees it.

### `SearchSelect` never virtualizes

Despite the prop name, `virtualization` does nothing — every filtered option renders as a real DOM
node. Page a large dataset in via `pagination` instead. (`chip.maxChips={0}` now works: no chips,
just "+N".)

### `SelectSearch`'s Enter key requires an exact full-label match, not the keyboard-highlighted option

Typing a partial query and pressing Enter without arrowing down first does not pick the
visually-highlighted top option — it only fires if the typed text exactly equals an option's full
label. `SelectV2`/`SearchSelect` both correctly select the highlighted option on Enter; `SelectSearch`
doesn't. Two more props (`isSearchEnabled`, `BottomIconStyle`) are typed but never read, and
`initialSelectedOption` only seeds selection at mount with no resync if the real value arrives later.

**Apply:** tell users to arrow down before Enter with this component specifically. Don't pass
`initialSelectedOption` before the real value is known (or key the component to force a remount).

### `FieldSelectModal`'s "Select all" ignores the active search filter, and resets on any parent re-render

The header checkbox (and its indeterminate state) always operates on the complete `fields` list, not
the search-filtered subset — clicking it while filtered silently selects/clears fields the user can't
see. Separately, an effect re-seeds selection whenever `fields`/`defaultSelected` changes
**reference**, so an inline array literal for either prop silently wipes in-progress picks on the
next parent re-render.

**Apply:** clear the search before using "Select all." Memoize `fields`/`defaultSelected` in the
parent before passing them down.

### `Dropdown`'s `ButtonText`/`text` are mutually exclusive per `dropdownType`, silently

The `"button"` trigger renders `ButtonText` only; the `"text"` trigger renders `text` only — pairing
the wrong prop with the active `dropdownType` renders an icon-only or bare-chevron trigger with no
visible label, and the `aria-label` fallback then substitutes "Open menu" as the accessible name too.
Separately, `buttonProps.sx` fully replaces the built-in trigger style rather than merging, silently
dropping the hover transition.

**Apply:** pair `ButtonText` with the default/`"button"` type and `text` with `dropdownType="text"`.
Fold custom styling into `dropDownButtonStyle`, not `buttonProps.sx`.

### Every `Search` grabs a page-wide Ctrl+K by default

Each mounted `Search` registers its own `window` Ctrl+K listener, so two on one view race for the
keypress. **Apply:** pass `shortcut={false}` on all but one. `showShortcutHint={false}` only hides
the hint; the listener stays.

The same applies to a launcher: `NavLauncher` and `LauncherTrigger` bind no chord to *open* (once open,
the launcher uses Cmd/Ctrl+K and `/` only to refocus its own field), and the library
reserves `mod+k` for the app's own palette. The app must pass `shortcut={false}` on every page
`Search`, or claim the chord in capture phase (`keydown` on `window` with `capture: true`) before
the `Search` listeners see it — otherwise the first mounted `Search` takes Ctrl+K.

### `NavLauncher` — the app owns routing, registry, query and chord

- **`linkAs` must forward `className`, `ref`, `onClick`, `href`, `target`, `rel`, `tabIndex` and
  `aria-hidden`** to its anchor. Dropping `className` loses all row styling; dropping `onClick` means
  a click never closes the launcher.
- **`onNavigate` fires for keyboard opens only** (Enter, mod+Enter). Pointer clicks follow the
  rendered links, so a router `linkAs` must do the navigation.
- **Controlled `query`:** the launcher still calls `onQueryChange("")` when it closes; the app must
  apply it or the stale query reopens.
- **Search rows are not nested links.** The visible label is a text-only `role="option"`; the real
  anchor is an `aria-hidden`, `tabIndex={-1}` overlay (so copy-link and mod-click work) and pin / ↗
  are `aria-hidden` siblings. Screen readers use Enter / mod+Enter. Do not nest links inside the
  option — axe `nested-interactive` fails.
- **The apps section decides "compact" with `matchMedia("(min-width: 48em)")`, the layout with
  `(min-width: 62em)`** (`lg`). Both fall back to desktop (apps hidden, two panes) where `matchMedia`
  is missing (SSR, jsdom), so tests must stub both to see the apps section or the tab bar.
- **Below `lg` only the selected tab's panel is mounted.** Pinned / Frequently visited / Recent
  (Quick access tab) and the apps list (Apps tab) are not in the DOM until their tab is clicked; the
  Quick access tab is omitted when it would be empty, and a single remaining tab hides the bar. The
  search view is different: no tab bar, stacked results plus the Quick access rail. A phone or tablet
  consumer test that looks for an app or a pin must click the tab first.
- **`P` on a focused NavLauncher row pins it.** Any other printable key pressed on a row, tab or
  button (not Space, no modifier) is appended to the query and focuses the field; in the field `P`
  types the letter.
- **Esc is handled by the launcher, not the Drawer** (`closeOnEsc` is off): it clears a non-empty
  query and keeps focus in the field, and closes only when the query is empty. The keydown is stopped inside
  the launcher, so a consumer `Escape` listener on `document` never sees it.
- **The dialog's accessible name is always `labels.title`** (a hidden heading, through `Drawer`'s
  `aria-labelledby`); the search value, scope chips and `headerActions` no longer join it. A consumer
  test asserting the old "Menu leave" style name must assert `labels.title` instead.
- **The result count is `aria-hidden`; the announcement is a separate visually hidden `aria-live="polite"`
  node, deliberately not `role="status"`**, so `getByRole("status")` still matches only the no-results
  message and the loading skeleton.
- **Left/Right/Home/End in the search field edit the caret** until a result has been navigated by
  arrow/Page keys (→ at the end of the text enters the grid); any change to the query hands them back
  to the caret. Do not "fix" this by binding them to results.
- **`NavLauncher` `suggestions` empty falls back to `noResultsHint`** instead of showing chips.
- **`PinToggle` / `NewTabLink` are opacity 0 until row hover or focus-within**, so a consumer's own row must carry `data-group` (or `role="group"`) to reveal them.
- **`LauncherLabels.screensGroup` is unused** by search now (sections replaced the flat group); kept so label objects still type-check.
- **`LauncherLabels` gained required keys** (`hintClickNewTab`, `newTabTip`, `resultsCount`, `tabsLabel`,
  `tabMenu`, `tabQuickAccess`, `tabApps`). The `labels` prop is `Partial<LauncherLabels>` and is fine;
  a consumer that annotates a *full* `LauncherLabels` object fails to compile.
- **`openShortcutHint` and `labels.hintOpenMenu` are deprecated no-ops:** the open chord is no longer
  shown in the footer. Drop them; the footer's hints are arrows, ENTER, ⌘ ENTER, ⌘ + click, P, ESC.
  Both are optional, so a full `LauncherLabels` object needs no `Omit<LauncherLabels, "hintOpenMenu">`.
- **`apps` is data-driven.** Gate by plan by changing the array or setting `locked` / `lockedReason`;
  keep `id`s stable (hues and `key` derive from them), and pass `color` on an app whose mark must not
  shift when siblings are added or removed. Locked rows are not links, not focusable, `aria-disabled`,
  tooltip = `lockedReason`. Pass `appsVisibility="always"` to show them above `md`.
- **Never use `:has()` in an emotion style.** jsdom's (nwsapi) `getComputedStyle` can throw ("not a valid selector") and takes every consumer test that opens a
  Drawer down with it. The launcher marks row focus with a `data-row-focus` attribute instead. If you
  hit that error in your own tests on a newer jsdom, report it with the selector.
- **Launcher rows are CSS containers** (`container-type: inline-size`, name `launcher-row`); jsdom
  drops `@container` rules, so tests assert the style objects (`titleInset`, `WIDE_ROW`), not the
  stylesheet.
- **A search row without `href` (an action with `run`) cannot open in a new tab:** any click, with or
  without Cmd/Ctrl, runs it and closes the launcher, same as Enter.
- **Spotlight search is opt-in (`searchMode="spotlight"`).** Without it matching, ranking and row
  order are exactly as before; `scopes`, `quickActions`, `answers`, `facts` and `groupLimit` work in
  both modes. Facts are searchable in spotlight only.
- **Two search models, and classic never matches a screen on its module.** Classic (the default) runs
  `searchLauncherSections`: registry order, no ranking, and every query word must appear in one row's
  own label or keywords. "leave balance" therefore finds nothing unless one screen's keywords carry
  both words. Spotlight ranks and also matches a screen on its module and section labels, so the same
  query finds Leave › Balances. The exported `searchLauncher` (one flat Screens group) is legacy and
  `@deprecated`; the component never calls it.
- **Scope chips live in the header row and are always shown** (their own header row below `md`);
  while a query is active each chip's name carries its count ("People, 3 results"), so a test that
  types first must match `getByRole("radio", { name: /^People/ })`, not the bare label.
- **Picking a chip other than All or Screens with an empty field lists that scope** exactly as
  passed: its `actions` or `extraResults` groups, so a remote group with nothing loaded yet shows
  `labels.scopeEmpty`. Load the scope's items when `onScopeChange` fires if it should list them.
- **Quick actions show only under All with an empty query, as the first block of the menu** (not
  while `isLoading`); only the first 5 render.
- **Closing resets the scope to "all"** and calls `onScopeChange("all")`; a controlled `activeScope`
  must apply it, like `onQueryChange("")`.
- **`facts` swap the Quick access rail for a Preview pane at `lg`** whenever any visible result has
  facts; below `lg` the active result's facts dock under the list. Copy buttons are never inside an
  `option` or the listbox (axe `nested-interactive`, `aria-required-children`).
- **An answer without `run` or `href` copies `answer.value` on Enter/click**; answers show in the
  All scope only.
- **`extraResults` groups are not filtered** unless `matchLocally: true`; remote rows the query does not
  match stay listed (score 0) and can never be the Top hit.
- **`LauncherSearchEngine` searches what it is given.** It has no React, DOM or network; build the
  index with `createIndex` once per data change, not per keystroke.
- **`LauncherTrigger` does not bind its shortcut**; `shortcut={null}` removes the hint and
  `aria-keyshortcuts`. An explicit `aria-label` hides the visible label from assistive tech, so keep
  the visible text inside the label (WCAG 2.5.3). `display="icon"` has no visible text: the label is
  its accessible name and tooltip.

### `Header`'s desktop submenus open on hover only — no keyboard or click trigger

Dropdown children are gated on local hover state (`onMouseEnter`/`onMouseLeave`), with no `onFocus`.
A keyboard user tabbing to a parent item can never open its children on the desktop layout — the
identical data renders as a click-toggled accordion on mobile.

**Apply:** don't put anything a keyboard user must reach behind `children` on desktop; use `rightSlot`
(real focusable buttons) for critical actions until this gets a keyboard path.

### `WorkspaceWindow`'s `state="maximized"` is indistinguishable from `"medium"`

The component only branches on `state === "minimized"` — size is always the same fixed constant, and
`onMedium`/`onMaximize` are `@deprecated` callbacks that are never invoked anywhere in the component.

**Apply:** treat `state` as effectively two-valued (open vs. `"minimized"`); don't wire a maximize
control expecting `onMaximize` to fire.

### `FilterSidebar`'s `selected` without `onChange` makes every filter silently inert

Passing `selected` alone (uncontrolled companion `onChange` omitted) computes the next filter state
on every click and discards it — checkboxes visibly never check, forever, with no error. Separately,
`onApply`, `headerPadding`, and `sliderMode` are all typed and accepted but have zero effect, as is
`FilterSection.checkboxes` (all four are `@deprecated`); radio-vs-checkbox mode is actually decided by
`type === "radio" || section.radio`.

**Apply:** always pass `selected` and `onChange` together, or omit `selected` and let `FilterSidebar`
own its state.

Separately, `FilterSidebar` skips re-rendering sections whose `section` object is unchanged, so build `sidebarOptions`
once (module constant or `useMemo`); fresh section objects every render re-render every section on each range drag. Don't reach for `onApply`/`headerPadding`/`sliderMode`/`FilterSection.checkboxes` —
none of them do anything.

### `Breadcrumbs`' `isLastChild` prop is accepted but never read

It's declared on the type (`@deprecated`) but omitted from the component's destructure entirely.

**Apply:** don't pass it expecting it to mark or style the final crumb — there's nothing it can do.

With `overflow="wrap" | "truncate"` each crumb is `noOfLines={1}` with a `title`, so one very long
label ellipsizes; the default `"nowrap"` is unchanged.

### `Accordion`'s `items[].buttonProps` replaces, not merges, the expanded/hover highlight

It spreads after the built-in `bg`/`_hover` that encode `isExpanded` state — passing `bg` or
`_hover` there silently kills that item's expanded indication. An `sx` inside `buttonProps` or
`itemProps` is always overwritten by `customStyles`.

**Apply:** style around the defaults via `customStyles` (merged through `sx`) when the highlight
must survive.

### `Table`: memoise `columns` if users can hide or reorder columns without `savePreferences`

A new `columns` identity re-applies the column defaults and discards those local changes. Passing an
equal array again no longer costs a re-render, but the reset still happens.

**Apply:** define `columns` at module level or in `useMemo`.

### `Table`'s `LeftFilterPane` Clear All only re-applies filters in `"sidebar"` mode

`handleClear` calls `onClear` unconditionally, but only calls `onApply(cleared)` when
`filterMode === "sidebar"` — in `"modal"` mode, Clear All visually unchecks every filter but never
tells the parent the selection changed, so a consumer whose `onClear` doesn't itself reset
applied/query state keeps serving pre-clear filtered data.

**Apply:** when using `filterMode="modal"`, drive your data refetch from `onClear`, not `onApply` —
don't assume `onApply` fires on every Clear All.

### `ScrollToTop` watches one `parentElement` hop, not "the nearest scrollable ancestor"

It reads `scrollTop` off its immediate DOM parent only, with no upward search for an `overflow:
auto/scroll` element. Wrap it in one extra layout `<div>` and the button silently never appears — no
error, no warning, `scrollTop` on a non-scrolling parent just stays `0` forever.

**Apply:** `ScrollToTop`'s JSX parent must be the actual scroll container, or pass `useWindow` when
the page itself scrolls.

### `ProfilePhotoViewer`'s PDF detection breaks the moment a file is picked, and a new `photoUrl` discards the preview

PDF detection is a literal `.endsWith(".pdf")` check — picking a file through the built-in editor
replaces the value with a base64 data URI that never ends in `.pdf`, so a freshly-picked PDF renders
as a broken image instead of the intended file badge (only the original URL prop is detected
correctly). Separately, a changed `photoUrl` re-syncs the component and replaces any locally picked
preview (a same-URL re-render keeps it), so a parent that updates `photoUrl` before the upload has
finished makes the preview vanish mid-upload.

**Apply:** don't use the built-in edit flow for PDF documents; detect kind from `File.type` in your
own handler instead. Update `photoUrl` only once the upload has finished. `key={photoUrl}` is no
longer needed.

### `Tabs` link mode needs `href` on every item, and has no default current item

One item without `href` makes the whole thing a normal tablist and `href` is ignored everywhere (a
dev-only `console.warn` is the only signal). Button tabs select the first enabled item when `value`
is missing; link tabs mark nothing `aria-current` until you pass `value`. A plain left-click calls
`onChange` but never `preventDefault`s; modifier and middle clicks only open the link. `isDisabled`
link items render as a non-link `span`.

**Apply:** `Tabs items=[{ id, label, href }] linkAs={RouterLink} value={currentId}` with `value`
derived from the route, and never hand-build `Box as={Link}` tabs.

### `BulkSelectionBar` renders nothing at `selectedCount` 0, and `sticky` needs a scroll ancestor

With no persistent live region it announces count changes itself (the node mounts empty and fills in
an effect), so don't also announce from your own region. `placement="sticky"` pins only inside an
ancestor scroll container — an ancestor with `overflow: hidden` silently disables it. Combining it
with `Table`'s `headerActions` gives two action sets for one selection.

### `SectionRail` chooses rail vs `Select` with `matchMedia` at render time

It renders the rail when `matchMedia` is missing (SSR). In the `Select` branch a dirty section's
option reads `"Label (dirtyHint)"` — a native `<option>` cannot hold a dot.

### `CalendarGrid` is fully controlled, ignores time of day, and `renderDayCell` turns multi-day bars off

Without `onDateChange` / `onViewChange` the toolbar's Today/Prev/Next and the view switcher are
hidden and arrow keys stop at the edge of the visible range, so the grid looks static — wire both.
`start` / `end` are read as local calendar dates (`end` inclusive): a UTC-midnight `Date` shows the
previous day in a negative-offset zone, so build date-only values with `new Date(y, m, d)`.
`renderDayCell` replaces each cell's chips wholesale: a 3-day event is passed to it for all 3 days
but is no longer drawn as one bar, and `onEventClick` never fires from your own content. A cell is named by
its date and count followed by everything inside it, your content included, so keep that content short.

### `AudioRecorder` needs a secure context, and `onRecorded` is not called after unmount

`getUserMedia` is undefined on plain http (except localhost), so the component shows its
"unsupported" state there, not "permission denied". A parent that navigates away mid-recording gets
no `onRecorded` call (the mic is released instead), and an empty recording never calls it either.

### `FilePreview` infers file kind from `fileName`, not `fileUrl`, and never resets zoom/rotation on its own

Once `fileName` is set, `fileUrl`'s own extension is never consulted — a friendly display name with
no extension forces the "preview unavailable" fallback even when `fileUrl` points at a perfectly
renderable file. Separately, cycling `fileUrl` while the modal stays open (a gallery next/prev)
carries the previous image's zoom/rotation into the new one.

**Apply:** keep the real extension on `fileName`, or pass `fileType` explicitly to skip inference.
Remount via `key={fileUrl}` when swapping the file in place instead of just changing the prop.

### An overflowing `ScrollbarBox` is a tab stop — give it an `aria-label`

While its content overflows a scrollable axis (more than 1px) and holds no button, link or field, the
box takes `tabIndex={0}` so a keyboard user can scroll it, and rings on `:focus-visible` only. A box that
fits, scrolls `hidden`, or already holds something focusable gets no stop, and a mouse click shows no ring.
Without `aria-label` the stop is unnamed (no `role="region"` either), so a screen reader announces nothing
useful at it.

**Apply:** pass `aria-label` ("Recent deals") on every `ScrollbarBox` that can overflow, and don't wrap one
around a list of controls just to get a stop.

### `StageProgress`'s `tooltipThreshold`/`minStageWidth` no-op under `variant="stepper"`, and a stale `value` blanks the tracker

Both props stop having any effect the moment a tracker switches to the stepper variant. Separately,
if `value` matches no `stage.id` (e.g. `stages` was filtered/re-derived and went stale), every stage
silently renders as `"upcoming"` — no stage is ever active or completed, with no error. The match is
also a strict `===`: a numeric `stage.id` compared against a string `value` (or vice versa) never
matches either, even when the "same" stage is clearly intended.

**Apply:** don't rely on either prop once on the stepper variant. Re-validate `value` against the
current `stages` list whenever it's filtered, and keep `id`/`value` the same primitive type at every
call site.

### A `StageProgress` strip is a tab stop only when no stage is a button — name it with `aria-label`

At a narrow width the strip scrolls sideways. Stage buttons already let a keyboard user reach every stage,
so an interactive strip gets no extra stop. A strip with nothing focusable (`isReadOnly`, or every stage
disabled) takes `tabIndex={0}` while it overflows and rings on `:focus-visible` only; nothing changes at
rest, on a mouse click, or while the stages fit. Without `aria-label` the stop is unnamed. A `stepper`
keeps its `ol` role, so its `aria-label` names the list rather than a region.

**Apply:** pass `aria-label` ("Deal stages") on every read-only `StageProgress` that can overflow.

### `Table`'s `isVisiblity`, `tableSettings`, `handleExportChange`/`exportOptions`/`exportLabel`, `onColumnFilter`, `headerBgColor`/`tableBorderColor`, and a column's `isSearch` are dead props — all `@deprecated`

Grepped account-frontend, tickets, crm-frontend, hrms and social-frontend: zero consumers set any of
the `TableProps` ones. Every prop below carries `@deprecated` in `TableProps.tsx` (eight on `TableProps`,
plus `isSearch` on the column definition `TableHeaderProps`) rather than being removed outright, in case
an app outside those five repos relies on one. None of them does anything in the current implementation,
despite being typed (and some documented on the demo page):

- `isVisiblity` — `Table`'s own destructure never lists it, so a consumer's value is dropped. It's
  hardcoded `true` into both `Pagination` call sites regardless, and `Pagination` doesn't read it
  either. It is a misspelling of `isVisibility`, but do not rename it (breaking change) — and do not
  expect it to do anything if you do.
- `tableSettings` (`{filters, filterSelected, onFilterSelection}`) — `Table` passes it to
  `TableSettings`, but `TableSettings`'s function signature never destructures it.
- `handleExportChange` / `exportOptions` / `exportLabel` — `Table` renders no export UI at all; none
  of the three are read anywhere.
- `onColumnFilter` — `Table.tsx` never references it.
- `headerBgColor` / `tableBorderColor` — the header paints the variant's own background; neither is read.
- column `isSearch` (on `TableHeaderProps`) — every column gets the filter popover regardless.

**Apply:** don't reach for any of these expecting an effect. Column visibility is driven by
`isTableSettings` (shows the Settings gear) + `preferences` (server persistence) + the Manage
Columns tab — not by `isVisiblity`/`tableSettings`.

### `Table`'s `preferences` prop is silent-by-default, not required

Omitting `preferences` (or leaving `preferences.url` empty, the default) does not throw or disable
the table — the persistence hooks both early-return when the base URL is falsy. The table works
fully in memory; it just never persists column order/visibility, density, or grouping across
reloads. When you do wire a `url`, `token` is sent as a **raw** `Authorization` header value — do
not prefix it with `"Bearer "` yourself expecting the hook to strip it.

**Apply:** treat `preferences` as opt-in persistence, not a required config block. If settings
aren't surviving a refresh, check `preferences.url` is actually set before assuming a bug.

### `SearchSelect`'s `height` prop only resizes the `insideSelect` segment, not the field

Despite the name, `height` is read only to size the nested `insideSelect` trigger. The main
control's height always comes from `size`'s token set — passing `height` with no `insideSelect`
configured has no visible effect at all.

**Apply:** to change the main field's height, change `size`; `height` only matters when
`insideSelect` is also passed.

### `SearchSelect`'s `pagination` now takes an explicit "has more" signal — prefer it at an exact-multiple total

Without `pagination.hasMore`/`pagination.totalRecords`, `hasMore` still falls back to guessing from
`options.length % (pagination.limit ?? 10) === 0`. A total that's an exact multiple of `limit`
(30 items, limit 10) still looks like "more pages exist" for the *first* extra scroll, firing one
empty `onScroll` call — after that empty response, `SearchSelect` stops asking (it no longer loops
forever the way earlier versions did).

**Apply:** pass `pagination.hasMore` (a boolean) or `pagination.totalRecords` (a count) so the field
never fires that one avoidable empty request; both take precedence over the `limit` guess.

### `RolesPermission`'s `RoleData.permission`/`designation`/`makeSuperAdmin`/`automation`/`trackLocation`/`show_records` are dead weight in this component

None of these fields are read by `RolesPermission` — the roles list only renders
`roleName`/`createdBy`/`created_at`/`roles_id`. They exist solely to be round-tripped unchanged
through `onViewRole`/`onEditRole` so the consumer can prefill its own edit form. Setting them has no
visible effect inside this component.

**Apply:** treat these fields as pass-through-only storage — populate them for your own edit form,
not to change anything `RolesPermission` itself renders.

### `OrganizationDetails`' `OrganizationItem.uiInvite` is never read

Active vs. invited organizations are decided purely by which array (`activeOrganizations` vs
`invitedOrganizations`) an item is placed in — `uiInvite` is carried on the type but
`OrganizationDetails` never inspects it.

**Apply:** don't rely on `uiInvite` to control which section an item renders in — move the item
between the two arrays instead.

### `OrganizationDetails`' `onSetDefault`/`onAcceptInvite`/`onDeclineInvite` are fire-and-forget despite their `Promise<void>` signature

Unlike `onCreateOrganization`/`onEditOrganization`/`onDeleteOrganization` (all awaited), these three
are called without `await` — the `switchingOrgIds`/`respondingOrgIds` spinner arrays are entirely
consumer-managed state, not driven by this component resolving the promise.

**Apply:** don't assume symmetry with the awaited callbacks in the same props interface; manage your
own loading state for these three around the promise you return.

### `OrganizationDetails`' `CreateOrgFormValues.default`/`defaultOrg` are dead fields — now `@deprecated`

The built-in `CreateOrgModal`'s internal state and submit handler never set or forward them, and the
public `onCreateOrganization` callback's parameter type doesn't declare them at all — populating
them in a custom create form has no effect on the built-in flow. account-frontend, the only real
consumer of `OrganizationDetails`, never reads either field. Both are now `@deprecated` in
`OrganizationDetailsProps.tsx`.

**Apply:** don't rely on these two fields to pre-mark a newly created org as default.

### `SideBar`'s `selectedSubMenu` prop is accepted but never read — now `@deprecated`

`SidebarProps.selectedSubMenu` is threaded through `SideBar` → `MenuItems` → `MenuItemBox`, but the
component's destructure never includes it — passing it has no effect of any kind. Zero consumers set
it; now `@deprecated` in `SideBarProps.tsx`.

**Apply:** don't pass `selectedSubMenu` expecting it to highlight a submenu row.

### `SideBar` pinned rows, `autoCollapse` and `collapseTransition`

- **`autoCollapse={false}` also silences the `open` prop** (`open` works by calling `changeToggle`).
  Drive collapse with `toggle` only.
- **A pinned id highlights only in the pinned block** while `activePinnedId` matches, and the parent
  submenu of a pinned child does not auto-open. An `activePinnedId` past `pinnedLimit` expands the
  list so the active state never disappears.
- **Pinned rows are anchors with `href={url}`**: a plain click calls `handleMenuClick` (and closes the
  overlay), modified clicks fall through to the browser. Unpin is a sibling button, never nested.
- **`collapseTransition` affects the `lg`+ inline rail only** — overlay slide, drag and `mobileNav`
  are untouched.
- **The rail focus ring is lifted per surface** (`sidebarFocus.ts`) because `colors.focusRing.ring` is
  derived for the page canvas and fails 3:1 on the rail for five light brands. The lasting fix is a
  `sidebar.focusRing` theme token.

### `KanbanBoard`'s `kanbanSelect`/`onOpen` don't check `permissions` — decision: accepted as-is

Looked like an asymmetry with the gated `kanbanEdit`/`kanbanCreate`/`onDelete`, but on inspection
`kanbanSelect` is a header filter dropdown (`options`/`onSelectChange`/`value`) — a view-level
affordance, not a mutation trigger — and `onOpen` (opening a card) is a view action too. Both are
already covered by the existing `permissions.isViewable` gate: the whole board (including the
header) returns `null` before rendering when `isViewable` is `false`, so a viewer who can't see the
board can't reach either. Gating them a second time against `isEditable`/`isCreatable`/`isDeletable`
would be wrong — filtering/opening isn't an edit, create, or delete. No code change made.

**Apply:** if you need `kanbanSelect` or `onOpen` gated on something narrower than view access, gate
it yourself (e.g. `isSelect: canEdit`); the component won't do it for you.

### `SideBar`'s `locked` menu-item flag — decision: fixed to actually block interaction

Previously `locked` only swapped in a padlock icon; the click handler checked `disabled`, not
`locked`, so a `locked: true` item still fully navigated. Zero consumers set `locked: true` in
account-frontend, tickets, crm-frontend, hrms, social-frontend or crm-mobile, so there was no
working behavior to preserve — the misleading name was a trap waiting for the first adopter. As of
this release, `locked` blocks clicks/expansion the same way `disabled` does, in both the expanded
sidebar (`MenuItemBox`) and the collapsed-sidebar flyout (`MenuPopoverContent`), for both top-level
and submenu items. `disabled` is unchanged and still works independently.

**Apply:** `locked: true` alone now prevents interaction; you no longer need to also set
`disabled: true`.

**Follow-up (same trap, missed spot): `SecondaryBar` still ignored `locked`.** `SecondaryBar.tsx`'s
`CollapsedItem`/`ExpandedItem` render the same `MenuProps` shape via a top-level item's
`secondaryItems`, but their click guards checked only `menuDisabled(item)` — never `item.locked` —
and neither rendered the lock icon, so a locked secondary item stayed fully clickable and looked
identical to an unlocked one. Fixed the same way as `MenuItemBox`/`MenuPopoverContent`. Also added
`lockedReason?: string` (`MenuProps`) — an optional per-item tooltip, shown on hover/focus of a
locked row anywhere in `SideBar` (rail row, submenu row, both collapsed-rail flyouts, and
`SecondaryBar`), via the library's own `ToolTip`.

### `SideBar` menu-item labels clipped the bottom of descenders (g/y/p/q/j) — fixed

`TextTruncation.tsx`'s label used `overflow="hidden"` (both axes) with `lineHeight="1"`, so the line
box was exactly font-size tall and any glyph descender got clipped flat — reported live on
lfour.pixelizetech.com ("Legal Requests").

**An earlier fix here did not work and shipped looking correct.** It paired `overflowX="hidden"`
(needed for the ellipsis) with `overflowY="clip"` + `sx={{ overflowClipMargin: "3px" }}`. CSS
discards that: when one axis is `clip` and the other is a non-`clip`, non-`visible` value, `clip`
computes to `hidden` — the mirror of the `visible`→`auto` rule. Measured in Chrome 152,
`overflow-x: hidden; overflow-y: clip` computes to `hidden`/`hidden`, so `overflow-clip-margin` was
inert on all 177 elements carrying it.

The working fix is vertical padding to grow the clip box, cancelled by an equal negative margin so
the label's layout height is unchanged: `py="0.35em" my="-0.35em"`. The padding must suit the
line-height — `0.35em` clears `lineHeight: 1`, while `Tag`'s label needs only `0.2em` at
`lineHeight: 1.45` (a bigger box there would push its focus ring outside the pill).

**Apply:** nothing to do — this was a rendering bug, not a prop. Building another truncated
single-line label? Use the `py`/negative-`my` pair. `overflow-clip-margin` only works when **both**
axes are `clip`, which `text-overflow: ellipsis` rules out.

### `SideBar` nav list showed a bare, unthemed scrollbar when items overflowed — fixed

`SideBar.tsx`'s `#sidebar-scroll-container` used `Constants/Sidebar.ts`'s `FlexCss`, which only set
the `::-webkit-scrollbar-*` pseudo-elements — never the standard `scrollbar-width`/`scrollbar-color`
properties. Chromium honors the webkit pseudo-elements, but any engine that reads the standard
properties first, or doesn't support the pseudo-elements at all, fell back to the browser's default
scrollbar: a plain bar with no relation to the dark sidebar theme, showing up the moment a nav list
(enough sections/items) overflowed the viewport. Fixed by switching to the already-written
`cssForScrollBar(theme)` (same file), which sets `scrollbarWidth`/`scrollbarColor` **and** the
webkit pseudo-elements, themed to `sidebar.background[500]` / `sidebar.mutedIcon`/`mutedLabel`,
hidden until hover. `FlexCss` is removed — `cssForScrollBar` is now the only scrollbar treatment
the SideBar uses. (2026-09-29: the thumb was briefly brand `primary[500]`/`[700]` — since fixed to
the neutral tokens shown above; `SecondaryBar`'s own scroll panel got the same styling and a
duplicate-id fix in the same pass.)

**Apply:** nothing to do. If a nav list is long enough to scroll, the bar now stays invisible until
hovered, in the sidebar's own colors, on every engine — not just Chromium.

### `SideBar` contrast pass — badge dot, hover fills, missing-icon fallback, default avatar/logo (2026-09-29) — fixed

A themed-UI audit found six real defects, none of them behavior changes: the collapsed-rail
notification dot (`red[400]`) is now `sidebar.semanticText.error`, which stays legible against the
rail in both modes instead of drifting; six `whiteAlpha.100` hover/rest fills that sat below the
sidebar's own perceptible-step floor are now `whiteAlpha.200`, matching every other row's hover;
the collapsed-flyout submenu (`MenuPopoverContent`) no longer shows Chakra's built-in "?" glyph for
a sub-item with no `icon` — it draws the same small dot the always-visible inline submenu already
used; hovering an *active* flyout row no longer gets visibly lighter-then-darker (it now steps
`.300` -> `.400`, like every other active row); and the default (no `logo`/`avatarUrl`) header logo
tile and footer avatar initials no longer paint a raw `primary` fill, which was within ~1:1 of the
rail — invisible — on zinc, skyline and storefront.

**Apply:** nothing to do — same props, same markup, visuals only. If you rendered a `SideBar` or
`SecondaryBar` with a screenshot baseline captured before 2026-09-29, expect the badge dot color,
some hover states, and the default logo/avatar tile to look different.

### `SideBar` contrast pass round 2 — muted icon/label under a hover fill, inline-submenu state (2026-09-29) — fixed

A follow-up audit found `sidebar.mutedIcon`/`mutedLabel` could dip under WCAG AA when sitting on
top of an active or hovered row (the whiteAlpha overlay steps), even though the same token cleared
AA against the bare rail — the token was never resolved against that combined surface. Also, the
expanded rail's always-visible inline submenu only swapped an active row's label to white with no
fill or accent bar, unlike every other active row in the family (top-level rows, the
collapsed-flyout submenu). Both fixed with no prop or markup changes.

**Apply:** nothing to do — same props, visuals only. Expect a muted icon/label under a hover/active
row to read slightly lighter than before on some brands, and an active inline-submenu item to now
show a fill and left accent bar matching the rest of the sidebar's active-row styling.

### `KanbanBoard`'s `permissions.isViewable: false` hides everything, including header actions

Not just the columns — the select/edit/create header bar disappears too, since the whole component
returns `null` before rendering anything.

**Apply:** there's no prop for hiding only the board body while keeping header actions visible.

### `Switch` was forced to 200px even with no labels — it overflowed a narrow cell

`Switch` (`leftText`/`rightText`) kept a 12.5rem minimum width regardless of whether any label was
set. Used as a boolean toggle — the wrong component for that, but the mistake shipped live in
tickets' project custom-fields page — an unlabelled instance rendered as two unlabelled brand-filled
pills at 200px inside a 120px table cell, overflowing by 80px. The width floor now only applies once
`leftText`/`rightText` is actually set; an unlabelled instance shrinks to fit (~58px measured).

**Apply:** for a single on/off field use `ToggleSwitch`, not `Switch`, even now that it no longer
overflows — a two-option segmented control still announces as `role="radiogroup"`, not
`role="switch"`. Swapping `Switch` for `ToggleSwitch` changes `getByRole("radio", …)` queries to
`getByRole("switch", …)` — the same test break the `InputSwitch` → `ToggleSwitch` migration caused.

### A `SearchSelect`/`Select` custom row node inherits the row's font size and padding — don't restate them

`SearchSelect`'s `option.view` and `Select`'s `renderOption` render straight inside the option row,
which now carries its own `fontSize`/`px`/`py` so a plain-text row is legible with no extra markup.
A custom node that also sets its own `px`/`py`/`fontSize` stacks on top of the row's rather than
replacing it — this is what made rows in crm-frontend render 57–75px tall instead of the ~30px every
other row uses.

**Apply:** size a custom `option.view`/`renderOption` node yourself only when it needs something
*different* from the row default — inherit by default, don't restate it.

### A custom option row's sub-line must not use `colors.textMuted` directly

A selected row sits on a tinted fill, and the hovered-selected rung is the busiest one in the
ladder. In dark mode `surfaceRaised` carries only ~0.86 of contrast headroom above AA, so raw
`textMuted` on that rung measures **4.00–4.22:1** in 6 of 9 brands — under the 4.5:1 a 12px
sub-line needs. The library's own rows no longer use it.

**Apply:** in a `SearchSelect` `option.view` or `Select` `renderOption` node, read the sub-line ink
from `optionRowDescriptionInk(theme.colors)` (exported from the package root) rather than
`theme.colors.textMuted`. It is a no-op in light mode. The row's main label is
`optionRowInk(theme.colors, isSelected)` with `optionRowWeight(isSelected)` — never brand ink.

### A custom option list must not fill the selected row

`listRowBackgrounds(colors).selected` and `.active` sit within 1.02:1 of each other on every brand
and mode, so a list that fills both the selected row and the hovered row shows two identical fills
and the user cannot tell which one is chosen. Library option lists paint one fill — the cursor's —
and mark selection with `optionRowWeight` plus a trailing `Check` in `colors.accentText`. (`Select`'s own popup
additionally fills the selected row (neutral grey rungs in both modes, identical on every brand; not exported); a custom list keeps one fill.)

**Apply:** `bg={optionRowFill(listRowBackgrounds(colors), isActive)}` for an index-driven list, or
`{...optionRowCursorSx(listRowBackgrounds(colors))}` for rows that take DOM focus; both are exported
from the package root. Text is `optionRowInk(colors, isSelected)`, unchanged on hover.

### `Table`'s node column `label` needs `labelText` unless its text is plain children

`columns[].label` accepts a node (an icon, a tooltip trigger) as well as a string or number. Every
place that cannot render a node — the sort and filter button names, Manage Columns, the Group
picker, filter chips, saved preferences and `onRowClick`'s `header.label` — uses a plain-text name
instead: `labelText` if set, else the node's literal text children, else the column `id`. A node
whose text comes from inside a component (`<MyHeader title="Revenue" />`, a `t()` call inside a
child) has no literal children, so those places silently read the raw `id`.

A wide node header is also **clipped, not ellipsized** — the header's ellipsis only works on bare
text. Column widths come from the rendered DOM, never from label length, so sizing is unaffected.

**Apply:** set `labelText` on every node label; put an `isTruncated` `Text` inside the node if it
can outgrow the column. An icon-only tooltip trigger inside the node is a native `button`, not a `span`
with `aria-label` (see the `ToolTip` gotcha above).

### `FormField`, `IconButton`, `SkipLink`: what their props do not hint at

- **`FormField` + library fields:** `TextInput` inherits FormField's `error` and `isRequired` because it checks
  for a parent `FormControl`. `InputTextArea`, `NumberInput`, `Select`, the date pickers and `PhoneNumberInput`
  wrap themselves in their own and do **not**: pass `error`/`isRequired` to those directly, and never give a
  wrapped field its own `label` as well, or it renders two.
- **`FormField isRequired` sets native `required` on Chakra-based controls** (as Chakra's `FormControl` does), so
  the browser blocks an empty submit. Add `noValidate` to the `<form>` if you validate yourself. Native children
  get `aria-required` only.
- **`FormField` children:** pass one element or a function. A Fragment is rendered untouched and gets no wiring.
  `id` is the control's id (the root takes none); a child's own `id` is adopted when FormField has none.
- **`IconButton` warns once per mount in development without `aria-label`/`aria-labelledby`.** `title` does not
  count. Size the icon yourself (xs 12 · sm 14 · md 16 · lg 18): the button does not resize it.
- **`SkipLink`** must be the first focusable element on the page. Its target gains `tabindex="-1"` if it is not
  focusable, and keeps it. A missing target falls back to the browser's hash jump (and warns in development).

### `formatDate`, `TimePicker`, `TagInput`: what their props do not hint at

- `formatDate` reads a bare `YYYY-MM-DD` as that calendar day, not UTC midnight. Pass a `Date` only when you mean
  an instant. Epoch *seconds* are not detected: multiply by 1000 first.
- `TimePicker` fires `onChange` with a `Date` on the day of `value` (else `baseDate`, else today). It never clears
  to `null` on its own: pass `onClear` to make "--" pickable once a time is set (it then fires instead of `onChange`).
- For free-text chips that are not email addresses use `TagInput`: same look as `MultiSelect`, any text, with
  your own `validate`. Its rejection messages and add/remove announcements are English by default; translate them
  with `labels` (functions, e.g. `duplicate: (entry) => ...`), including `labels.remove` for each chip's remove button
  (default `Remove <tag>`).
- **Button press scale matches a real `:active` only.** A `MenuButton as={Button}` held open by Chakra's
  `data-active` keeps the darker pressed fill but does not stay at 0.98. A consumer `_active={{ transform }}`
  loses to the press rule while the pointer is down; use `variant="unstyled"` or an `sx` `&:active` with
  `!important`.

### `Card` is borderless by default (`elevated`)

A Card that frames a table or a list of rows needs `variant="outline"`. `borderColor` alone shows nothing, because
the default border width is 0, and the outline rule is Chakra `gray[200]`, not `boxborder[200]`. Paint the page with
`backgroundColor.base`: on `backgroundColor.main` a borderless card can be white on white.

### `Select` / `SearchSelect` multi rows have no checkbox role

Query rows with `getAllByRole("option")` and check `aria-selected`. The row's checkbox is decorative and no longer
exposes `role="checkbox"`, so `getByRole("checkbox")` finds nothing inside the popup.

### Page behind an open `WorkspaceWindow` is `aria-hidden`

While a window is open (not minimized) role queries for background elements need `{ hidden: true }` or a test id.