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

package/DESIGN-GUIDE.md

@@ -0,0 +1,342 @@
+# Pixelize Design Guide — how to design a page with `pixelize-design-library`
+
+For any developer or LLM building UI in a consumer app. `COMPONENT-GOTCHAS.md` (next to this file)
+says **which component does what**; this file says **how to compose them into a page that looks
+designed**. Read both before building a screen. Everything here is copyable as-is.
+
+**App conventions win.** If the app has its own density/size file (hrms `core/layout/density.ts`,
+tickets `layoutDensity.ts`), use it — it encodes these same rules. Otherwise the library's
+`PageHeader`, `StatCard` and `QueryStateBoundary` already do.
+
+## 1. The look
+
+Calm, dense, professional SaaS admin — Linear/Stripe-dashboard, not a landing page.
+
+- **Hierarchy comes from type and whitespace, not boxes.** One surface per level. Never nest a
+  card inside a card; inside a card, separate with spacing or a `Divider`.
+- **One primary action per view.** One `variant="solid"` button in the page header; everything
+  else `outline` or `ghost`. The only exception is a composer's Send button.
+- **Left-aligned, scannable.** Titles and forms left-aligned; numbers right-aligned in tables.
+- **Color means something.** Neutral by default; brand color for the primary action and selection;
+  semantic color only for status. No decorative gradients, no colored section backgrounds.
+- **Content cards float, data surfaces are ruled.** `Card` is borderless by default
+  (`variant="elevated"`: `background[50]` lifted by the soft `shadows.card`). Tables, filter bars,
+  list panes and fields keep their 1px `boxborder[200]` rule; a `Card` that frames a table or a
+  list of rows takes `variant="outline"`. Heavier shadows only on floating things (menus,
+  popovers, modals) and on hover of a card that is itself clickable.
+- **Paint the page with `backgroundColor.base`.** In light mode it sits one step (1.09:1) below
+  the card, which is what gives a borderless card its top edge; `backgroundColor.main` is a
+  component surface and can be as white as the card.
+
+## 2. Spacing (Chakra units, 1 = 4px)
+
+| Where | Value |
+| --- | --- |
+| Page padding | `px={{ base: 4, md: 6 }} py={{ base: 4, md: 5 }}` |
+| Between page sections | `gap={5}` (a `Flex direction="column"`) |
+| Between cards in a grid | `gap={4}` |
+| Inside a card | `Card`'s own padding — don't add more; `padding="none"` (or `"2xs"`/`"xs"` for dense) instead of `sx={{ p }}`, `bodyProps={{ p: 0 }}` for edge-to-edge content |
+| Between form fields | `gap={4}` vertical, `gap={3}` side by side |
+| Inline clusters (tags, meta, icon + text) | `gap={1.5}`–`gap={2}` |
+| Page header → content | the section gap (`gap={5}`) — no extra margin |
+
+Never raw `px` strings (`"13px"`, `"18px"`) for spacing or size; never `margin` hacks to align.
+Borders are the one px value: `borderWidth="1px"`. Fixed widths (side panel, list pane) in `rem`: `templateColumns={{ base: "1fr", lg: "minmax(0, 1fr) 20rem" }}`.
+
+## 3. Type
+
+| Role | Props |
+| --- | --- |
+| Page title + subtitle | `PageHeader` (18px/600 h1 by default, `sm` muted subtitle; `titleSize="xl"` for a top-level page) — don't hand-build it |
+| Section / card title | `Heading as="h2" fontSize="md" fontWeight={600} color={colors.header[900]}`, in `Card`'s `header` prop |
+| Body | `Text fontSize="sm" color={colors.text[800]}` |
+| Label / meta / helper | `Text fontSize="xs" color={colors.textMuted}` |
+| KPI tile | `StatCard` — pass `trend` and `goodDirection`; the delta is green when the change is *good* (a shorter sales cycle is green); `iconTone` tints the icon chip (unset = brand primary) |
+| Numbers in tables/columns | `sx={NUMERIC_TEXT}` (root export, tabular figures) so digits align; `Table` columns take `align: "end"` |
+| Code, ids, shortcuts | `fontFamily="mono"` (a real monospace stack); shortcut hints are `KbdShortcut`, never a hand-styled `<kbd>` |
+| Overline (rare) | `textStyle="overline"` |
+
+**`textStyle` sets size, line height, weight and tracking in one prop.** Prefer it to hand-picking
+the four: `<Text textStyle="label">`. The ramp (`TEXT_STYLES`, also a root export):
+
+| `textStyle` | Use |
+| --- | --- |
+| `title` · `heading` · `subheading` | page / section / card titles (24 · 20 · 16px) |
+| `body` | running text (14px) |
+| `ui` · `label` | control and form text (13px, weight 500 · 600) |
+| `caption` | helper and meta text (12px) |
+| `overline` | small-caps eyebrow (11px, uppercase) |
+
+Chakra size keys only (`xs-minus xs xs-plus sm md lg xl 2xl`) — never `fontSize="14px"`.
+`xs-plus` (13px) is the control size; `xs-minus` (11px) is for chips, counts, keyboard hints and
+overlines only; nothing is smaller. Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers and the `title` step only.
+
+**Radius and elevation come from the role, not the scale step.** `RADIUS_ROLE` (root export) names
+the radius a surface plays: `control`, `field`, `tooltip` and `media` 8px · `option` 6px · `card`,
+`float`, `dialog` and `sheet` 12px · `chip` full. Anchored popups (`Menu`, `Popover`, `Select`,
+`Dropdown`) all take the 12px radius, and `Menu` and `Popover` the `md` (float) shadow, so a panel
+you build yourself takes `borderRadius={RADIUS_ROLE.float}` and `boxShadow="md"`. A resting card is
+`shadows.card`; heavier shadows belong to floating things only.
+
+## 4. Color — pick by role
+
+`const { colors } = useCustomTheme();` Never a hex, never `gray.500`/`blue.600` literals — those
+stay light in dark mode.
+
+| Need | Token |
+| --- | --- |
+| Page canvas | `colors.backgroundColor.base` |
+| Card / panel surface | `colors.background[50]` |
+| Your own overlay (popover, panel, `ModalContent bg=`) | `colors.surfaceRaised` — divider inside it `raisedRule(colors)`; `Popover*` and `Menu*` come from the package root (Primitives barrel) |
+| Subtle inset (toolbar strip, hovered row, code) | `colors.backgroundColor.secondary` |
+| Border / divider | `colors.boxborder[200]` |
+| Heading ink | `colors.header[900]` |
+| Body ink | `colors.text[800]` |
+| Secondary text, icons | `colors.textMuted` |
+| Brand-colored text/link | `colors.accentText` — never `primary[500]` |
+| Status text/icon | `colors.semanticText.success \| error \| warning \| info` |
+| Status chip | `<Tag label="Won" colorScheme="green" />` (subtle, `sm` by default) — never a painted `Box`. Tone → `colorScheme`: success `green`, warning `orange`, error `red`, info `blue`, neutral `gray`. Quiet rows: `<Tag tone="success" display="dot" label=… />`; map an app's status vocabulary once with `<StatusTag status map label display />` |
+| Selectable list row (inbox, picker) | `listRowBackgrounds(colors)` for hover/selected + `sx={focusVisibleStyles(colors)}`; pad the list `p={2}` so the ring isn't clipped |
+| Option row in a dropdown/menu/select | `optionRowFill` / `optionRowCursorSx` (fill = cursor only) + `optionRowInk` + a trailing `Check` for the selected row — never a selected fill |
+| Any filled surface you paint | `resolveFilledSurface(colors.<scale>, colors)` → `{ fill, color }` |
+| Icon tint chip, avatar tint | `bg={colors.primary.opacity[8]}` + `color={colors.accentText}` (`opacity` exists on `primary`/`secondary`/`tertiary` only) |
+
+**`Tag` — pick `variant` and `colorScheme`/`tone` deliberately, or two chips read as the same thing:**
+
+| Need | Use |
+| --- | --- |
+| Status (draft, active, error, in review, …) | `tone="neutral\|info\|success\|warning\|error"` — wins over `colorScheme` when both are set |
+| Category, label or filter (not a state) | `colorScheme` alone — brand (`primary`/`secondary`/`tertiary`) or a utility scale; never `tone` for a non-status label |
+| Default, everyday chip | `variant="subtle"` (the default) — low-emphasis, sits on any surface |
+| Must stand out (a status that needs attention) | `variant="solid"` |
+| Dense list, table cell, or an already-colored surface | `variant="outline"` — no fill to compete with the surface |
+
+`secondary` and `tertiary` are two distinct accents on every brand except `zinc`, which is
+near-grey and has almost no hue to turn (see `COMPONENT-GOTCHAS.md`) — on `zinc`, reach for a
+utility scheme to tell two categories apart.
+
+## 5. Controls — two scales, `sm` by default
+
+Fields (`TextInput`, `InputTextArea`, `NumberInput`, `Select`, `Search`, the
+`DatePicker` family) sit on `CONTROL_SIZES` — `xs` 32px · `sm` 38px · `md` 40px · `lg` 48px.
+`Button` and every button-like trigger (`SegmentedControl`, `Tabs`, `TableToggle`, `Dropdown`)
+sit on the separate `BUTTON_SIZES` scale — `xs` 24px · `sm` 32px · `md` 40px · `lg` 48px. Both
+**default to `sm`**, so on a desktop page **don't pass `size`**. `RangeSlider` takes the same
+size names but keeps its own track and thumb values. They line up at `md`/`lg`; at
+`sm` a button reads 6px shorter than the field beside it.
+
+| Button role | Props |
+| --- | --- |
+| Primary (one per view) | `variant="solid" colorScheme="primary"` |
+| Secondary | `variant="outline" colorScheme="gray"` |
+| Tertiary / toolbar / row action | `variant="ghost" colorScheme="gray"` |
+| Destructive (confirm step only) | `<AlertDialog tone="danger" confirmButtonText="Delete" … />` — red Confirm, neutral Cancel |
+| Busy | `isLoading` — spinner only, width kept; add `loadingText` only if words must show |
+
+Icons: `lucide-react` only, `size={16}` in controls, `size={14}` inline with `xs` text. Every
+icon-only button gets an `aria-label` and a `ToolTip`. Inline or panel busy indicator: `Spinner`
+(themed; never Chakra's raw one).
+
+**Labels:** use each field's own `label` / `helperText` / `errorMessage` — never wrap a library
+input in `FormControl` + `FormLabel`. In a settings row (title + description left, control right)
+the row title is the label: `<Text as="label" htmlFor={id}>` pointing at the field's `id`.
+
+## 6. Page anatomy
+
+```
+┌ Page header ─ title + subtitle ─────────────── secondary · secondary · PRIMARY ┐
+├ Toolbar ── search · filters ───────────────────────────── view toggle · count ─┤
+│ Content ── table / card grid / form sections                                    │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```tsx
+<Flex direction="column" gap={5} px={{ base: 4, md: 6 }} py={{ base: 4, md: 5 }}>
+  <PageHeader
+    title="Deals"
+    subtitle="248 open · $1.2M pipeline"
+    actions={<>
+      <Button variant="outline" colorScheme="gray" label="Export" />
+      <Button variant="solid" colorScheme="primary" label="New deal" />
+    </>}
+  />
+  <QueryStateBoundary isLoading={isLoading} error={error} onRetry={refetch}
+    isEmpty={deals.length === 0} empty={{ icon: Handshake, title: "No deals yet" }}>
+    {() => <DealsTable deals={deals} />}
+  </QueryStateBoundary>
+</Flex>
+```
+
+`PageHeader` also takes `breadcrumbs`, `leading` (avatar), `titleAddon` (status `Tag`), `meta` (icon
+row) and `tabs` — a record page's whole header. Actions wrap under the title on their own when they do
+not fit (`actionsLayout="auto"`), so don't hand-build a stacked variant. KPI rows are a `SimpleGrid` of `StatCard`s; card
+sections are `Card` with the title in `header`.
+
+| Pattern | Component — don't hand-build it |
+| --- | --- |
+| Multi-step flow (send, import, onboard) with validated Continue and a review step | `WizardDialog` (`Wizard` inline; `chrome="inline"` inside a `WorkspaceWindow` or other host that is already the dialog) — don't hand-roll Back / Continue / Finish around `StageProgress`; each step's `validate` returns its error messages, future steps stay locked until valid, each step's `summary` drives the review |
+| Rich-text template with `${field}` placeholders | `Editor mergeFields={…}` — not a `Select` + caret tracking + dialog beside it; use its `label` / `helperText` / `errorMessage` |
+| A PDF behind auth, shown inline | `PdfViewer getBlob={…}` — the toolbar's Open / Download then work with the token, so don't add your own buttons |
+| Data grid | `Table` — defaults to `variant="studio"` (flat small-caps header, one row rule, the select slot resting on the row number, status as a pill). Pass `variant="classic"` for the banded header and per-column rules; don't restyle the header or rows by hand |
+| Toolbar: search · filters · active-filter chips · count · actions | `FilterBar` (`search`, children, `activeFilters` + `onRemoveFilter`/`onClearAll`, `summary`, `actions`) |
+| Read-only label/value grid (record details, key facts) | `DescriptionList` (`items`, `columns`, `layout="inline"` for a side panel, `copyable`, `isLoading`) |
+| Settings row (title + description left, control right) | `SettingRow` inside a `SettingsSection` (`isDanger` for the danger zone, `action` for a header-right button) |
+| A person: avatar + name (+ role/email, presence, remove) | `PersonChip` (`orientation="vertical"` for a stacked profile block) |
+| An avatar on its own, or a stack of them | `Avatar` / `AvatarGroup` — never pick the fill, it is derived from `name` |
+| Unsaved-changes bar | `SaveBar isOpen={isDirty} onSave onDiscard isSaving` |
+| Create / edit a record in a side panel | `FormDrawer` (`sections`, `errors`, `isDirty`, `isSubmitting`) — don't hand-assemble Drawer + footer + discard confirm. A nested confirm dialog in any `Drawer` / `Modal` goes in `portalChildren` |
+| Detail or sub-table under a table row | `Table renderRowDetail` (+ optional `expandedRows`) — don't put an Accordion outside the Table |
+| Tabs that navigate between routes | `Tabs items=[{ id, label, href }] linkAs={RouterLink} value={currentId}` — never hand-build `Box as={Link}` tabs |
+| Completion / capacity ring | `CircularProgress` (`ProgressBar` stays for linear) |
+| Per-day activity (leave, tasks, shifts) | `CalendarGrid` with `events` mapped from your data — don't hand-roll a month grid |
+| Voice note capture | `AudioRecorder`; `MediaAudioPlayer` for playback |
+| Previewing an attachment (image, video, audio, PDF, Office, text, archive) | `MediaViewer` (`items`, `isOpen`, `onClose`) — omit `index` and it owns navigation itself |
+| Notification tray | `NotificationCenter` — bell plus a two-tab panel (Needs you, Activity) with inline approvals and undo; `NotificationBell` alone is just the badge. `NotificationPanel`, `NotificationList` and `NotificationItem` are deprecated |
+| Notification inbox page | `NotificationInbox` (tabs, search, type filter, bulk actions, reading pane, `variant="phone"`) — share one `NotificationCenterProvider` with the bell |
+| Notification settings page | `NotificationPreferences` (`channels`, `groups`, `values`, `onChange`; locked cells, autosave with rollback) |
+| Confirm that needs the name typed to arm it | `ConfirmDialog confirmationText="delete-me"` — `onConfirm` does **not** close; call `onClose` yourself |
+| Scrim over the page or one panel while something runs | `Backdrop open loader` — `variant="dim"` by default. Add `container` to scope it to the nearest positioned ancestor, `allowBackgroundInteraction` to let clicks through, `onClick` to dismiss |
+| A short "saved" / "copied" / "failed" notice | `useToaster().showToast({ title, status })` (`PixelizeThemeProvider` and `withTheme` mount the provider) — not a `ToolTip`, not an `AlertDialog` |
+| Page through a list that is not a `Table` | `Pagination` (controlled: numbered pages, previous / next, optional rows-per-page picker) |
+| Faceted filter column (checkboxes, radios, ranges) | `FilterSidebar` (`sidebarOptions`; controlled only when both `selected` and `onChange` are set) |
+| Pick one of a few options as cards | `ChoiceCardGroup` of `ChoiceCard`; payment methods are `PaymentOptionGroup` of `PaymentOption` |
+| On / off setting | `ToggleSwitch` — `Switch` is deprecated, a two-option pill is `SegmentedControl` |
+| One-time code | `PinInput` · free-text chips: `TagInput` · email chips: `MultiSelect` (it has no options list) |
+| Copy a value to the clipboard | `CopyButton` (icon, button or menu-item layout) — not a hand-built `navigator.clipboard` button |
+| Plan state and upsell | `PlanBadge` (resolves org plan data into a `PlanPill`), `UpgradeButton` for the CTA, `LimitReachedModal` when a limit is hit |
+| Charts | `ApexBarChart` · `ApexLineChart` · `ApexAreaChart` · `ApexPieChart` · `ApexRadialChart` · `ApexPolarChart`, inside a `Card`; default series colours follow the theme, so don't pass hexes |
+| Whole admin screens (roles matrix, user directory, org list, sign-in history) | `RolesPermission` · `UserDetails` · `OrganizationDetails` · `SignInActivityTable` — don't rebuild them |
+| "+N more" on an overflowed list | `MoreItems` |
+
+**Reach for `Backdrop` in new work** — the `dim` scrim (black at 0.5, no blur, 225ms in /
+195ms out) replaces every hand-rolled `position: fixed` overlay. Never build your own
+scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by default; pass
+`variant="dim"` to route it through `Backdrop`, or just use `Backdrop` directly.
+
+### Parts you reach for through their parent
+
+These are root exports, but each belongs to a parent component; start from the parent unless a row
+here says otherwise.
+
+| Part | Belongs to | Use it for |
+| --- | --- | --- |
+| `DrawerHeader` · `DrawerBody` · `DrawerFooter` | `Drawer` | the only children a `Drawer` renders; style props go straight on each slot. For a create / edit form use `FormDrawer` instead |
+| `ProfileCardHeader` · `ProfileCardBody` · `ProfileCardFooter` | `ProfileCard` | the only children a `ProfileCard` renders; any other sibling is dropped |
+| `StageItem` | `StageProgress` | one chevron, bar or pill stage; `StageProgress` renders it, so don't lay stages out by hand |
+| `FilePreviewTrigger` | `FilePreview` | a thumbnail button that opens one file in a modal; for several attachments use `MediaViewer` |
+| `MediaScrubber` · `MediaStatusPanel` · `MediaDocumentStage` | `MediaViewer` | building a custom media UI: a `role="slider"` seek bar (`onSeek`), the no-preview / error panel (`tone="warning"` for errors), and the document stage driven by a `resolveDocument` you supply |
+| `LazyWrapper` | `React.lazy` | a `Suspense` boundary with the themed spinner; pass `fallback` to replace it |
+| `ScrollbarBox` | any scrolling region | a themed scroll container; give it an `aria-label`, because it is a keyboard stop while it scrolls |
+| `AppearanceSettings` | a settings page | the theme, colour-mode and font-size controls in one panel; brand and font size are controlled, the colour-mode switch reads the theme context |
+| `ApexPolarChart` | `ApexPieChart` | independent magnitudes as wedges of equal angle and varying radius; values that add to a whole belong in `ApexPieChart` |
+
+### Navigation shell
+
+`SideBar` is the rail, `NavigationBar` the top bar, `NavLauncher` the full-height "go anywhere" panel.
+**The app owns the registry, permissions and persistence**; the library owns the look and the keyboard.
+
+- Keep one registry (modules → screens) and derive the rail, the launcher and route guards from it.
+  Filter by permission *before* passing `sections` to `NavLauncher`; use `isLoading` while access is
+  unknown, `linkAs` for the router link, and `extraResults` + `isSearching` for remote (entity) results.
+- Open the launcher with `<NavigationBar leading={<LauncherTrigger onClick isOpen />} />` — never inside
+  `navigationBarText.text`. Neither component binds the chord: the app owns the `mod+k` listener
+  (capture phase) and passes `shortcut={false}` to any page `Search`. Bind it to *open* the launcher only:
+  once open, the launcher refocuses its own field on Cmd/Ctrl+K and `/`, and shows no open-chord hint
+  (`openShortcutHint` is deprecated).
+- Pins live in the app (server or local). Pass them to `NavLauncher` (`pinnedIds`, `onTogglePin`) *and*
+  to `SideBar pinnedItems` + `onUnpin` so the rail shows what the launcher pinned. Persist collapse with
+  `useSidebarPrefs`, and pass `autoCollapse={false}` if the app, not the rail, decides.
+- Replacing a 9-dot app switcher in a nav bar: `<LauncherTrigger display="icon" />` (36px) in `moreIcon`;
+  keep the chip variant (`leading`) where there is room.
+- In a phone-width app bar use `<OrgSwitcher display="auto" />` (avatar below `md`) next to the bell,
+  `LauncherTrigger display="icon"` and the avatar menu; keep every icon control 36px or less and
+  `flexShrink={0}`. The title truncates first.
+- Below `lg` the launcher is a Menu / Quick access / Apps tab bar over one panel (search stays a single
+  stacked list), so design for phone and tablet with that structure, not a long scroll. Pass
+  `headerActions` for the app's own icon button (help, customise) with an `aria-label`.
+- Show the suite's apps with `appsVisibility="always"` and drive plan gating by editing `apps` /
+  `locked`.
+- For Spotlight-style search pass `searchMode="spotlight"` plus `synonyms` for the app's jargon
+  (`pf`, `wfh`), `scopes` for its entity groups, up to 5 `quickActions`, copyable `facts` on reference
+  items and `answers` for one-line lookups. Reuse `LauncherSearchEngine` for any other in-app search
+  instead of writing a matcher.
+- Show shortcut hints with `KbdShortcut`, never a hand-styled `<kbd>`.
+
+## 7. Every page has four states
+
+Design all four, not just the happy path.
+
+`QueryStateBoundary` picks one per content region (loading > no access > error > empty > data). Pass
+`children` as a function when it reads data that may still be undefined. `isForbidden` shows the
+no-access panel between loading and error; `hasData` keeps content on screen during a refetch.
+
+| State | Render |
+| --- | --- |
+| Loading | `loadingFallback` of `Skeletons` shaped like the content (rows, cards, `StatCard isLoading`) — never a lone centered `Spinner` for a page |
+| Empty (first run) | `empty={{ icon, title, description, action }}` — the primary action as `action` |
+| Empty (filtered) | `FilteredEmptyState` (`filterCount`, `onClearFilters`, `onRemoveLastFilter`; `scale="card"` inside a panel) — in the boundary pass `isEmpty` + `isFiltered` |
+| Error | `ErrorState` (the boundary's `errorTitle`/`errorDescription`/`onRetry`): what failed + an outline "Retry" (+ `action` "Back to …" on a detail page) |
+
+Page header stays visible in every state; only the content region swaps. Keep **one solid button
+on screen**: when the whole page is empty, the `EmptyState` action is the solid one and the header
+hides its primary; when only one section is empty on a populated page, that section's action is
+`outline`. Header actions that need data (Export, bulk actions) are disabled outside the data state.
+
+## 8. Never
+
+- Hex colors, Chakra color literals, `px` font sizes, inline `style={{}}` for theme concerns.
+- Raw `@chakra-ui/react` imports — layout primitives (`Box`, `Flex`, `Grid`, `Heading`, `Text`,
+  `Menu`…) come from `pixelize-design-library` too. Anything the library owns a component for
+  (`Tabs`, `Accordion`, `Modal`, `Card`, `Select`, `TextInput`, `Skeletons`…) has no Chakra
+  passthrough at all — the owned component is the only one.
+- Reaching for `SelectV2` (`@deprecated`), `SearchSelect` or `SelectSearch` (not deprecated, but not the
+  preferred picker) in new work.
+  One picker now: `Select` (`native={false}` for the themed, searchable, multi popup).
+  `Dropdown` is the exception — it is an action menu, not a picker, and is not replaced.
+- A card inside a card; a border on a content `Card` (it is borderless by default), or any resting
+  shadow heavier than `shadows.card`.
+- Painting a whole table cell with a status color — use a `Tag` in the cell.
+- Centered page titles, hero-sized headings, `size="lg"` buttons, or `size` props restating the default.
+- More than one solid button in a view; a destructive action without `AlertDialog`.
+- A page with only the data state.
+- **Work around a library gap silently.** If a component is wrong or can't do what the screen
+  needs, report it (see "Found a gap or a bug?" in [COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md)) so
+  it is fixed once, here, and remove your workaround when the issue closes.
+
+
+## 9. Reference pages
+
+Full screens built only from library exports, each with all four states, live in the library
+playground's **Page examples** section (source: `src/Pages/examples/` in the Micro-Components repo —
+not shipped in this package). Start from the closest one:
+
+| Screen you're building | Reference | Shows |
+| --- | --- | --- |
+| Dashboard / overview | `dashboard.tsx` | `StatCard` row, chart `Card`, stage list with `ProgressBar`, task list, `QueryStateBoundary` |
+| List of records | `records.tsx` | saved views, `FilterBar`, `Table` (`isGlobalSearch={false}`, `Tag` cells, row selection), `BulkSelectionBar` (count, facts, ranked actions, clear), `AlertDialog tone="danger"`, create `Drawer` |
+| One record | `recordDetail.tsx` | `PageHeader` with breadcrumbs/avatar/meta, `Tabs` (declarative `items` with `count` badges), `DescriptionList` (grid + inline side panel), `Timeline` (per-event `icon`/`description`), `ErrorState` + back |
+| Settings / long form | `settings.tsx` | `SectionRail` (rail from `lg`, `Select` below, dirty dots), `SettingsSection` + `SettingRow`, `SaveBar`, danger zone |
+| Notification inbox and settings | `demo.notificationInbox.tsx` (`/notificationinbox`), `demo.notificationPreferences.tsx` (`/notificationpreferences`) in the **Feedback & overlays** group | `NotificationInbox` desktop, phone, shared provider with the bell and all load states; `NotificationPreferences` with locked cells, autosave rollback and read-only |
+| Board | `pipeline.tsx` | `KanbanBoard` with custom cards and column totals (`height`/`maxH` to size it) |
+| Inbox / master–detail | `inbox.tsx` | selectable list rows, conversation pane, composer, mobile list↔detail |
+| App launcher (browse, pins, recents, search with actions) | `launcher.tsx` (`/examples/launcher`) | `NavLauncher` with an app-owned registry and role-based permission filter, pinned / frequent / recent ids, `linkAs`, remote results via `extraResults`, `isLoading`, Classic / Spotlight toggle, synonyms, scopes, quick actions, company facts with Copy, answers |
+| Wizard / multi-step dialog | `wizard.tsx` (`/examples/wizard`) | `WizardDialog`, inline `Wizard` and `WizardDialog chrome="inline"` in a `WorkspaceWindow`: per-step `validate` messages, locked future steps, error summary, `summary`-driven review, `isFinishing` |
+| Template editor with merge fields | `templateEditor.tsx` (`/examples/template-editor`) | `Editor mergeFields`: grouped Insert field, chips, unknown-field error chips and `onUnknownTokens`, Make dynamic, side preview, label / helper / error |
+| Shop front (home → listing → product → bag → checkout → order) | `storefront/` | `ProductCard` grid / rail / quick-add, `ProductDetails` + `StickyBuyBar`, `CartItem`, `OrderSummary`, `CouponField`, address/payment groups, `OrderStatusTimeline`, `BagBar`; mobile frame + desktop |
+
+## 10. Shop screens (e-commerce)
+
+For catalogue, product, bag and checkout screens use the commerce kit, not `Card` + `Table`. Detail
+and rules: [COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md) "Commerce kit".
+
+- **Model the product once** as `axes` + `variants` (`OptionAxis[]`, `ProductVariant[]`) and hand the
+  same objects to `ProductCard`, `QuickAddSheet`, `VariantSelector` and `ProductDetails`. Any vertical
+  works — colour/size, pack size, storage, finish, shade — because the components only see axis ids.
+- **Mobile first.** `ProductCard density="compact"` in a 2-up `ProductCardGrid`, a swipe `MediaGallery`,
+  `StickyBuyBar` and `BagBar` pinned at the bottom, sheets (`QuickAddSheet`, filters) instead of popovers.
+- **One loud action per view:** the single brand-filled button is Add to bag / Place order. Wishlist,
+  Buy now, Remove and Move-to-wishlist are soft or ghost.
+- **Be honest:** "N left" only from real stock, delivery as a date (`PincodeChecker`), MRP + discount
+  from `PriceBlock`, the tax note and legal-metrology block in `DetailSections`.
+- **Four states per screen** as usual: `ProductCardSkeleton` / `CartItem isLoading`, first-run and
+  filtered-empty `EmptyState`, `ErrorState` with Retry.