@ngrr/ds 0.1.13 → 0.1.16

package/AI.md

@@ -1,18 +1,39 @@
 # DS-Nagarro — AI Agent Rules
 
-> **Single source of truth for AI agents generating code for this design system.**
+> **Single source of truth for AI agents building apps with `@ngrr/ds`.**
 > Compiled from: `foundations.md`, `ds-guidelines.md`, all component docs in `docs/`, and `accessibility-audit-2026-02-28.md`.
 > When in doubt, defer to the specific component doc file.
+>
+> **This file is for consuming the package.** For building components inside the library itself,
+> read `AGENTS.md` instead.
 
 ---
 
 ## How to use this file
 
-1. **Before selecting a component**, check the [Cross-component patterns](#cross-component-patterns) section to determine the correct component from a decision tree.
-2. **Before implementing a component**, read its section below for all props, states, tokens, ARIA requirements, and content rules.
-3. **All code must comply** with [Accessibility requirements](#accessibility-requirements) and avoid everything in [What NOT to do](#what-not-to-do).
-4. **All token references** must use CSS custom properties: `var(--token-name)`. Never hardcode values.
-5. Token naming: Figma slash paths → hyphenated CSS vars. `background/interactive/cta/default` → `var(--background-interactive-cta-default)`.
+1. **Before writing any code**, read the [Setup](#setup--mandatory-css-imports) section and implement the required imports and CSS.
+2. **Before building any page**, read the [AppShell](#appshell--mandatory-root-layout), [Navigation rules](#navigation--page-structure-rules), and [Layout rules](#layout--component-behavior-rules).
+3. **Before selecting a component**, check the [Cross-component patterns](#cross-component-patterns) section to determine the correct component from a decision tree.
+4. **Before implementing a component**, read its section in [Component usage rules](#component-usage-rules) for all props, states, tokens, ARIA requirements, and content rules.
+5. **All code must comply** with [Accessibility requirements](#accessibility-requirements) and avoid everything in [What NOT to do](#what-not-to-do).
+6. **All token references** must use CSS custom properties: `var(--token-name)`. Never hardcode values.
+7. Token naming: Figma slash paths → hyphenated CSS vars. `background/interactive/cta/default` → `var(--background-interactive-cta-default)`.
+
+---
+
+## Setup — mandatory CSS imports
+
+```tsx
+// main.tsx — must be first, before any other imports
+import '@ngrr/ds/style.css'
+import '@ngrr/ds/tokens.css'
+```
+
+### Required CSS on the host app
+```css
+html, body { margin: 0; height: 100%; }
+#root { min-height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
+```
 
 ---
 
@@ -38,9 +59,11 @@ Primitives (raw) → Semantic (intent) → Component (usage)
 | `--background-*` | `background-color` |
 | `--borders-*` | `border-color`, `outline-color` |
 | `--color-surface-*` | `background-color` (component-level) |
+| `--color-dataviz-*` | all chart/graph colors — never use semantic tokens or hex for dataviz |
 | `--font-size-*`, `--font-weight-*`, `--font-line-height-*` | typography |
 | `--space-*` | `gap`, `margin` (between elements) |
 | `--inset-*` | `padding` (inside components) |
+| `--page-margin-x` | `padding-inline` on all containers |
 | `--radius-*` | `border-radius` |
 | `--border-width-*` | `border-width` |
 | `--effects-elevation-*` | `box-shadow` |
@@ -84,1605 +107,1741 @@ Always use these exact identifiers. Never use `base`, `normal`, or `rest`.
 
 ---
 
-## Component Usage Rules
-
----
-
-### Button
-
-**Applies to: `Button` (Main, Destructive, Toggle, Vertical)**
+## AppShell — mandatory root layout
 
-#### When to use
+`AppShell` is the only permitted root layout wrapper. Every page must be inside it. Do not invent wrapper divs or custom layouts.
+```tsx
+import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
+// Icons come from lucide-react — install separately: npm install lucide-react
+import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings } from 'lucide-react';
 
-- **Main button**: default for actions. Not destructive, not icon-only, not vertical.
-- **Destructive button**: irreversible or harmful actions (delete, discard). Same variants as Main but danger color.
-- **Toggle button**: persistent on/off state in toolbars (Bold, Italic, view mode). NOT a one-off action trigger.
-- **Vertical button**: icon + label stacked, in bottom toolbars only.
+<AppShell
+  header={
+    <Navbar
+      title="Dashboard"
+      rightActions={<Button variant="primary" label="New project" />}
+    />
+  }
+  sidebar={
+    <Sidebar
+      selectorProps={{
+        label: 'WorkScope',
+        avatarProps: {
+          size: 'xs',
+          variant: 'organization',
+          fill: 'initials',
+          initials: 'WS',
+          name: 'WorkScope',
+        },
+      }}
+      showSearch
+      searchSlot={<SearchBar placeholder="Search" />}
+      sections={[
+        {
+          id: 'main',
+          items: [
+            { id: 'dashboard', label: 'Dashboard', icon: <LayoutDashboard size={16} />, selected: true, onClick: () => {} },
+            { id: 'projects', label: 'Projects', icon: <FolderKanban size={16} />, onClick: () => {} },
+            { id: 'tasks', label: 'Tasks', icon: <CheckSquare size={16} />, onClick: () => {} },
+            { id: 'people', label: 'People', icon: <Users size={16} />, onClick: () => {} },
+            { id: 'notes', label: 'Notes', icon: <FileText size={16} />, onClick: () => {} },
+          ],
+        },
+      ]}
+      bottomContent={
+        <>
+          <SidebarMenuSelector
+            variant="full"
+            label="Settings"
+            showIcon
+            icon={<Settings size={16} />}
+            onClick={() => {}}
+          />
+          <SidebarMenuSelector
+            variant="full"
+            label="User Name"
+            showAvatar
+            avatarProps={{ size: 'xs', fill: 'initials', initials: 'UN', name: 'User Name' }}
+            onClick={() => {}}
+          />
+        </>
+      }
+    />
+  }
+>
+  {/* page content goes here */}
+</AppShell>
+```
 
-#### Do NOT use a button when
-- Action navigates to a page → use a link
-- Action toggles a setting → use Switcher
-- Action selects from a set → use Segment control or Tab
+**AppShell props:**
+- `header` — `<Navbar />` only
+- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically
+- `children` — main page content
+- `rightPanel` — optional, omit if not needed
+- `footer` — optional, omit if not needed
 
-#### Props and variants
+**Forbidden:**
+- Do not wrap AppShell in any other layout element
+- Do not add sidebar items beyond what is specified
+- Do not invent extra sections, items, or nav elements
 
-```typescript
-type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'plain';
-type ButtonSize = 'sm' | 'md';
-// plain is only available in sm
-```
+---
 
-#### Hierarchy rules
-- **One Primary per view.** Never two Primary buttons side by side unless forced mutually exclusive choice.
-- **Secondary**: supports Primary or equal-weight alternative.
-- **Ghost**: functional/utility (filter, sort, copy). Not a "quieter Primary".
-- **Plain**: dismissive, space-constrained, `sm` only. "Cancel", "Skip".
+### Navbar props
+- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
+- `title` — page title, sentence case
+- `rightActions` — primary CTA button, rightmost position
+- `leftActions` — secondary actions on the left, omit if not needed
+- `onBackClick` — only used with `variant="breadcrumbs"`
+- `breadcrumbItems` — required only when `variant="breadcrumbs"`
 
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Loading` · `Selected` *(Toggle/Vertical only)*
+**Rules:**
+- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes)
+- Back arrow only on detail views using `variant="breadcrumbs"`
+- Primary CTA always in `rightActions`
 
-- `Selected` is a boolean prop. Use `aria-pressed="true/false"` for Toggle/Vertical.
-- Do NOT use `aria-pressed` on Main or Destructive buttons.
-- `Loading` → use `aria-busy="true"` on the button.
-- `Disabled` → never rely on opacity alone. Do not disable Primary as a form validation strategy.
+---
 
-#### Placement
-- Button group order left-to-right: Ghost/Plain → Secondary → **Primary** (most important is trailing).
-- Destructive confirmation: Destructive right, "Cancel" left.
-- Toggle buttons → toolbars only.
-- Vertical buttons → bottom toolbars/action panels only.
+### Sidebar props
+- `sections` — required. Only include sections explicitly specified. Never invent extra items.
+- `selectorProps` — workspace selector at the top. Always set `label` and `avatarProps`.
+- `showSearch` — set to `true` to show the search bar
+- `searchSlot` — pass a `<SearchBar />` component when `showSearch` is true
+- `bottomContent` — use for Settings and User Name, pinned to bottom with a divider. Always include these two items.
+- Never pass `collapsed` — AppShell controls it automatically
 
-#### ARIA
-```tsx
-<button type="button" disabled={disabled} aria-pressed={selected} aria-busy={loading} aria-label="...for icon-only">
+**SidebarMenuItem shape:**
+```ts
+{
+  id: string;
+  label: string;           // sentence case always
+  icon?: React.ReactNode;  // lucide-react icon at size={16}
+  selected?: boolean;      // true only for the active page
+  onClick?: () => void;
+  showBadge?: boolean;
+  badgeCount?: number;
+  badgeVariant?: BadgeVariant;
+  showAvatar?: boolean;
+  avatarProps?: AvatarProps;
+}
 ```
 
-#### Content rules
-- Start with a strong verb: "Save", "Delete", "Export"
-- Specific: "Save changes" not "OK" or "Yes"
-- 1–3 words; 5 maximum
-- Sentence case: "Save changes" not "Save Changes"
-- Destructive labels: name what is destroyed. "Delete account" not "Confirm"
-- Loading labels: present-progressive. "Saving…"
-- Toggle `aria-label`: describes the action, not the state. "Bold" not "Bold is active"
-
 ---
 
-### Avatar / AvatarGroup
+### Hard rules — always follow
+- `AppShell` is always the root — no exceptions
+- `DataTable` must never be wrapped in a `Card`
+- No back arrow on top-level pages: Dashboard, Projects, Tasks, People, Notes
+- CTA hierarchy: Primary (object creation, rightmost in Navbar) → Secondary → Ghost (Export, Share, Edit)
+- All labels and copy: sentence case always ("New project" not "New Project")
+- Icons: from `lucide-react` — install with `npm install lucide-react`
+- Tag variants: `success` = completed, `progress` = in progress, `warning` = at risk, `neutral` = not started
+- Settings and User Name always pinned to sidebar bottom via `bottomContent`
+- Sidebar always full viewport height — guaranteed by AppShell CSS rules above
 
-**Applies to: `Avatar`, `AvatarGroup`**
+---
 
-#### When to use
-- Represents a person or organization where visual identity aids recognition.
-- Do NOT use for generic system processes or when no identity info is available.
+## Navigation & Page Structure Rules
 
-#### Variants
-- `Profile`: individual person
-- `Organization`: company/team
-- Never mix Profile and Organization in the same list without clear reason.
+These rules define how pages are structured, how navigation behaves, and where
+actions are placed. They apply to every screen built with DS-Nagarro components.
+Apply these BEFORE selecting or placing any component.
 
-#### Fill priority (always use highest fidelity available)
-1. `Picture` — real photo/logo
-2. `Initials` — derived from name
-3. `Icon` — anonymous fallback
+---
 
-Never show Icon when Initials are derivable.
+### NAV-01: AppShell is mandatory
+Every page MUST use `AppShell` as its root layout component.
+Never build page layout manually with divs.
+✅ `<AppShell header={...} sidebar={...}>...</AppShell>`
+❌ `<div style={{ display: 'flex' }}>...</div>`
 
-#### Sizes (Avatar: 7-step scale)
-`xxs` · `xs` · `sm` · `md` (default) · `lg` · `xl` · `xxl`
+---
 
-Use consistent sizes within a list. Never mix sizes in a collection.
+### NAV-02: Sidebar structure
+The Sidebar always follows this exact structure — top to bottom:
+1. **Workspace switcher** — top of sidebar
+2. **Main navigation items** — middle (product-specific)
+3. **User profile + Settings** — bottom of sidebar
 
-#### AvatarGroup
-- Sizes: `xxs`, `xs`, `sm` only
-- Show "+" overflow indicator when list exceeds display limit (typically 3–5)
-- Overflow indicator must include full list in `aria-label`
-- Do not use for >20 members without a "view all" affordance
+Never deviate from this order. Never place navigation items above the workspace switcher.
 
-#### ARIA
-```tsx
-// Individual: meaningful avatar
-<img alt="Ana Costa" aria-label="Ana Costa" />
+---
 
-// Icon fill, no identity
-<span aria-hidden="true" />
+### NAV-03: Back arrows — top-level pages
+NEVER show back/forward navigation arrows in the Navbar on top-level section pages.
+Top-level pages are direct sidebar navigation items (e.g. Users, Reports, Pipeline).
+✅ Users page → no back arrow
+✅ Reports page → no back arrow
+❌ Users page → back arrow shown
 
-// AvatarGroup
-<div aria-label="Assigned to: Ana Costa, João Silva, and 2 others">
-```
+---
 
-#### Content rules — Initials
-- Person: first + last initial. "Ana Costa" → "AC"
-- Single name: first two letters. "Cher" → "CH"
-- Organization: first two letters or first letter of each word (max 2). "Design Studio" → "DS"
-- Always uppercase. Max 2 characters.
+### NAV-04: Back arrows — detail views
+ONLY show back arrow in Navbar when the user has navigated INTO a detail view
+(i.e. a record, sub-page, or child of a top-level section).
+✅ Alice Johnson's profile page → show back arrow
+✅ Report detail page → show back arrow
+❌ Top-level Users list → no back arrow
 
 ---
 
-### Badge
+### NAV-05: Navbar title — two modes
 
-**Applies to: `Badge`**
+**Mode 1 — Top-level page:**
+Show plain section title in the Navbar. No breadcrumbs.
+✅ Navbar: "Users"
+✅ Navbar: "Reports"
 
-#### When to use
-- Attach to another element to surface a count or status signal.
-- Notification count on a navigation icon, pending actions, critical status.
-
-#### Do NOT use when
-- Label is text/category → use Tag
-- User can select/dismiss it → use Chip
-- Requires user response → use Toast or alert banner
-- Count is zero → **hide the badge**
-
-#### Variants
-| Variant | Use |
-|---|---|
-| `Highlight soft` | Low urgency — new content, informational count |
-| `Highlight strong` | Moderate urgency — pending actions, unread items |
-| `Informative` | Neutral — generic counts |
-| `Critical` | Urgent — errors, failures. **Use sparingly.** |
-
-#### Sizes
-- `sm`: default — icons, avatars, compact items
-- `lg`: larger host elements
-- `Dot`: presence-only signal. `Highlight strong` and `Critical` only.
-
-#### Count display rules
-- ≤99: show exact count
-- >99: show "99+"
-- 0: **remove the badge entirely**
+**Mode 2 — Detail view (2+ levels deep):**
+Show large `Breadcrumbs` component in the Navbar INSTEAD of a plain title.
+The breadcrumb IS the title — do not show both.
+The current page name (rightmost item) is bold and non-interactive.
+Parent items are interactive links.
 
-#### ARIA
-```tsx
-// Host element's accessible name must include the count
-<button aria-label="Messages, 3 unread" />
-// Dynamic count changes
-<div aria-live="polite" /> // only for meaningful threshold transitions
-```
+✅ Navbar breadcrumb: "Users > **Alice Johnson**"
+❌ Navbar title: "Alice Johnson" + separate breadcrumb below it
+❌ Navbar title: "Users" when inside Alice Johnson's page
 
 ---
 
-### Tag
-
-**Applies to: `Tag`**
-
-#### When to use
-- Non-interactive categorical label or status on content items.
-- Status: "Active", "Archived", "Pending review"
-- Category: "Design", "Bug", "High"
-
-#### Do NOT use when
-- User can interact with it → use Chip
-- It's a numeric count → use Badge
-- Urgent system condition → use Toast
+### NAV-06: Breadcrumb variants — two levels
 
-#### Variants
-| Variant | Semantic meaning |
-|---|---|
-| `Highlight` | Notable, not urgent |
-| `Warning` | Caution — needs awareness soon |
-| `Error` | Something is wrong or blocked |
-| `Success` | Completed, approved, healthy |
-| `Neutral` | Purely categorical, no status weight |
+There are two breadcrumb sizes and they serve different purposes:
 
-Use the variant matching semantic meaning, not preferred color.
+| Variant | Where | Purpose |
+|---|---|---|
+| **Large** (`BreadcrumbsController`) | Navbar | Main navigation hierarchy — replaces page title on detail views |
+| **Small** (`Breadcrumbs`) | Inside page content | Sub-section hierarchy within a detail page |
 
-#### Sizes
-- `md`: default
-- `sm`: dense layouts, multiple tags per item
+NEVER use small breadcrumbs for main navigation.
+NEVER use large breadcrumbs inside content areas.
 
-Use consistent sizes within a list. Never mix on the same row.
+✅ Navbar: large breadcrumb "Users > Alice Johnson"
+✅ Inside content: small breadcrumb "Permissions > Edit role"
+❌ Navbar: small breadcrumb
+❌ Content area: large breadcrumb
 
-#### Tags have NO interaction states. Not clickable. Never.
+---
 
-#### Placement
-- Show max 3 tags per item.
-- Order: severity first (Error → Warning → Success), then category.
-- Do not wrap — truncate and show full value in tooltip if space is insufficient.
+### NAV-07: Breadcrumb format
+Format: `[Parent section] > [Current page]`
+- Parent items: interactive links
+- Current page (rightmost): non-interactive, visually bold
+- Do NOT always prepend root/Home — start from the immediate meaningful parent
+- Never truncate the current page item
 
-#### ARIA
-```tsx
-// Include tag content in accessible name of parent
-<li aria-describedby="tag-status">
-  <span id="tag-status" role="status">Error</span>
-```
+✅ "Users > Alice Johnson"
+✅ "Reports > Q4 2025"
+❌ "Home > Users > Alice Johnson" (unnecessary root)
+❌ "Alice Johnson" alone (missing parent context)
 
 ---
 
-### Chip / ChipGroup
-
-**Applies to: `Chip`, `ChipGroup`**
-
-#### When to use
-- User needs to select, activate, or dismiss a discrete value.
-- Filter controls, multi-value input, toggleable options.
+### NAV-08: Primary CTA placement — top-level pages
+The primary action for a section always sits in the Navbar, to the right of the title.
+NEVER place the primary CTA inside a Card header or content area on a top-level page.
 
-#### Do NOT use when
-- Purely informational → use Tag
-- Mutually exclusive form selection → use Radio
-- Multi-option form selection → use Checkbox
-- Settings toggle → use Switcher
+Primary actions are object-creation actions:
+"New user", "New deal", "Create report", "New email"
 
-#### Sizes
-- `md`: default
-- `sm`: compact layouts
+✅ Navbar: "Users" + [New user — Primary button]
+❌ Card header: [New user — Primary button] on a top-level page
 
-Never mix `md` and `sm` in the same chip group.
+---
 
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Selected` (boolean)
+### NAV-09: CTA hierarchy in Navbar
+When a page has multiple actions, use this hierarchy in the Navbar (right side):
 
-`Selected` combines freely with `Hover`, `Pressed`, `Focused`.
+| Action type | Button variant | Example |
+|---|---|---|
+| Primary object creation | `Primary` | "New deal", "New user" |
+| Important but not primary | `Secondary` | "Import", "Publish" |
+| Utility / contextual actions | `Ghost` | "Share", "Edit", "Export" |
 
-#### Keyboard interaction
-- `Space` or `Enter` → toggle
-- `Tab` → move between chips
+Order right-to-left by importance: Ghost → Secondary → Primary
+(Primary is always the rightmost — trailing edge)
 
-#### ARIA
-```tsx
-// Multi-select filter group
-<div role="group" aria-label="Filter by status">
-  <button role="checkbox" aria-checked="true">Active</button>
-  <button role="checkbox" aria-checked="false">Closed</button>
-</div>
+✅ [Export — Ghost] [Share — Ghost] [Edit — Secondary] [New user — Primary]
+❌ [New user — Primary] [Share — Ghost] (wrong order)
+❌ Two Primary buttons in the same Navbar
 
-// Single-select group
-<div role="radiogroup" aria-label="Filter by status">
-  <button role="radio" aria-checked="true">Active</button>
-</div>
+---
 
-// Dismiss button on chip
-<button aria-label="Remove Active" />
+### NAV-10: Child section CTAs
+When a detail page has sub-sections with their own primary actions,
+those actions belong at the sub-section level — NOT in the top Navbar.
 
-// Disabled chip
-aria-disabled="true"  // keep in reading order
-```
+✅ Alice Johnson page → Navbar: [Save changes — Primary]
+✅ Alice Johnson > Permissions tab → tab-level: [Add permission — Primary]
+❌ Alice Johnson page → Navbar has both "Save changes" AND "Add permission"
 
 ---
 
-### Separator
-
-**Applies to: `Separator`**
-
-#### When to use
-- Visual divider between content sections that are related but distinct.
+### NAV-11: Section headers inside content
+Use the `SectionHeader` component to divide content sections within a page.
+Section headers are standalone dividers — they do NOT need to be inside a Card.
+Description line is optional — use it when the section needs clarification,
+omit it when the title is self-explanatory.
 
-#### Do NOT use when
-- Adequate spacing already separates sections
-- Sections are already separated by color/card borders
-- Purpose is purely decorative
+✅ SectionHeader "Personal info" (no description needed)
+✅ SectionHeader "Permissions" + description "Control what this user can access"
+❌ Wrapping every section in a Card just to have a title
+❌ Using plain `<h2>` or `<h3>` instead of SectionHeader component
 
-#### Directions
-- `Horizontal`: stacked content, spans full container width
-- `Vertical`: side-by-side content, spans full container height
+---
 
-#### ARIA
-```tsx
-// Structural separator
-<hr /> // or <div role="separator" />
+### NAV-12: Page title and section header casing
+ALL page titles, Navbar titles, breadcrumb items, and section headers use sentence case.
+NEVER title case.
 
-// Decorative only
-<div aria-hidden="true" />
-```
+✅ "Personal info", "New user", "Alice Johnson", "Save changes"
+❌ "Personal Info", "New User", "Save Changes"
 
 ---
 
-### Switcher
-
-**Applies to: `Switcher`**
+### NAV-13: Cards vs sections
+Not every content group needs a Card.
+Use a Card when the content is a distinct, self-contained unit that benefits
+from visual elevation or grouping (e.g. a data table, a form block, a summary panel).
+Use SectionHeader + flat content when sections are part of a continuous page flow.
 
-#### When to use
-- Single binary setting, **effect is immediate** (no confirmation step).
-- Enabling features, notification settings, preferences.
+✅ DataTable inside a Card
+✅ SectionHeader "Personal info" → flat form fields below (no Card)
+❌ Every section wrapped in a Card by default
 
-#### Do NOT use when
-- More than 2 states → use Radio or Select
-- Multiple independent options → use Checkbox
-- Requires confirmation before taking effect → use Checkbox
-- Compact toolbar → use Toggle button
-- Choosing between UI views/modes → use Segment control or Tabs
+---
 
-#### Decision: Switcher vs Checkbox vs Toggle button
-| Component | Effect | Context |
-|---|---|---|
-| **Switcher** | Immediate | Settings with visible label |
-| **Checkbox** | Staged (on submit) | Forms |
-| **Toggle button** | Immediate | Icon-only toolbar |
+## Layout & Component Behavior Rules
 
-#### Sizes
-- `md`: default
-- `sm`: dense layouts
+These rules apply globally. Apply them before building any screen or component.
 
-Never mix sizes within a settings group.
+---
 
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+### LCB-01: AppShell scroll — only the content area scrolls
+The sidebar and navbar are always fixed. Only the main content area scrolls.
+Never apply scroll to the full page or the AppShell root.
 
-`Selected` and `Disabled` are independent booleans.
+✅ `<AppShell>` — sidebar and navbar fixed; content area overflows and scrolls independently
+❌ Full page scrolls, taking the sidebar and navbar with it
 
-#### Rules
-- Always pair with a visible label. **Never use a switcher without a label.**
-- When `Selected=True` + `Disabled=True`: always explain why it's locked.
-- If toggle has latency, show loading indicator alongside — don't leave in ambiguous state.
+---
 
-#### Keyboard
-- `Space` → toggle
+### LCB-02: Data visualisation — always use dataviz tokens
+All charts, graphs, and data visualisations must use `--color-dataviz-*` tokens from `tokens.css` for all colors (series, axes, labels, backgrounds).
+Never use hardcoded hex values or generic semantic tokens for dataviz color.
 
-#### ARIA
-```tsx
-<button role="switch" aria-checked={isOn} aria-labelledby="label-id" />
-// Disabled
-aria-disabled="true"  // keep in reading order
-```
+✅ `fill: var(--color-dataviz-1)`
+❌ `fill: #0F766E`
+❌ `fill: var(--background-accent)`
 
 ---
 
-### Checkbox
-
-**Applies to: `Checkbox`**
+### LCB-03: Horizontal spacing — always use `--page-margin-x`
+All horizontal spacing in the content area must use `var(--page-margin-x)`.
+This applies to every container without exception: pages, cards, modals, drawers, tables, lists, and form sections.
+Never introduce independent `padding-left`, `padding-right`, `margin-left`, or `margin-right` values that deviate from this token.
 
-#### When to use
-- User selects any number of independent options (zero to all).
-- Selection takes effect only after **explicit confirmation** (submit button).
+✅ `padding-inline: var(--page-margin-x)` on content areas, modals, drawers, cards
+❌ `padding: 24px` or `margin: 0 16px` hardcoded on any container
+❌ Different horizontal spacing values across containers causing misalignment
 
-#### Do NOT use when
-- Only one can be selected → use Radio
-- Effect is immediate → use Switcher
-- Compact token-like pattern → use Chip
-- Single toggle for a setting → use Switcher
+---
 
-#### Sizes
-- `md`: default
-- `sm`: dense layouts
+### LCB-04: Card internal padding — content must never touch card edges
+Every card must apply internal padding using the correct inset token.
+Content must never touch the card border.
 
-Never mix sizes in a single form group.
+✅ `padding: var(--inset-large)` inside every card
+❌ Card content flush with card edges
 
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+---
 
-**Indeterminate state**: when a parent checkbox controls sub-items with partial selection.
+### LCB-05: Icons — always use Lucide, never system icons
+The only permitted icon library is Lucide (`lucide-react`).
+Never use browser/OS-native icons, emoji, or icons from any other library.
+This applies everywhere: tables, buttons, inputs, menus, empty states, and all other components.
 
-#### Interaction
-- Click on checkbox **or its label** toggles selection (full row is hit target).
-- State changes are staged — not immediate.
+✅ `import { ArrowUpDown } from 'lucide-react'`
+❌ System sort icon (↕) in table column headers
+❌ Any icon not from the Lucide library
 
-#### ARIA
-```tsx
-<fieldset>
-  <legend>Notification preferences</legend>
-  <label>
-    <input type="checkbox" aria-checked="true" /> Send weekly summary
-  </label>
-</fieldset>
+---
 
-// Indeterminate
-aria-checked="mixed"
+### LCB-06: List items — always stretch to full container width
+List items inside any container (modal, drawer, card, page section) must stretch to fill the full available width.
+Never let list items float at an arbitrary width or leave unexplained whitespace to the right.
 
-// Disabled — keep in reading order
-aria-disabled="true"
-```
+✅ List item `width: 100%` of container (minus `--page-margin-x` padding)
+❌ List items sized to content, leaving empty space on the right
 
 ---
 
-### Radio
+### LCB-07: Placeholder content — never leave it in place
+Component slots for icons, help text, and hint icons must never contain placeholder values.
+Either replace with real, meaningful content or hide the slot entirely.
 
-**Applies to: `Radio`**
+This applies to:
+- **Icons** inside inputs, selects, and buttons → replace with a relevant Lucide icon, or hide
+- **Help text** → replace with genuinely useful guidance, or hide
+- **Help/hint icons** → replace with meaningful tooltip content, or hide
 
-#### When to use
-- Exactly one option from a mutually exclusive set.
-- All options visible simultaneously (2–6 items).
-- Effect takes place after **explicit confirmation**.
+✅ Help text: "We'll use this to send you login notifications."
+✅ Icon slot hidden when no meaningful icon applies
+❌ Help text reads "Help text"
+❌ Placeholder diamond icon left inside a Select component
 
-#### Do NOT use when
-- Multiple can be selected → use Checkbox
-- More than 6–7 options → use Select
-- Immediate effect → use Switcher or Segment control
-- Single on/off option → use Checkbox or Switcher
+---
 
-#### Sizes
-- `md`: default
-- `sm`: dense layouts
+### LCB-08: Required fields — use "Optional" label, not asterisk
+Every form field is mandatory by default.
+Never use a red asterisk (`*`) to mark required fields.
+Only mark optional fields, using an "Optional" label styled in `var(--text-tertiary)`, placed inline after the field label.
 
-Never mix sizes within a radio group.
+✅ `Team <span style="color: var(--text-tertiary)">Optional</span>`
+✅ Fields with no qualifier → assumed mandatory
+❌ `First name *` with a red asterisk
+❌ `aria-required="true"` shown visually as an asterisk
 
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+---
 
-No indeterminate state for Radio. A group always has 0–1 selected.
+### LCB-09: Form CTA — disabled until mandatory fields have a value
+The primary submit button in any form (modal, drawer, page) must be disabled until all mandatory fields contain a value.
+On submit, validate all fields and display all errors simultaneously.
+Do not validate in real time as the user types — only on submit attempt.
 
-#### Interaction
-- Click radio **or its label** to select (full row is hit target).
-- Selecting one deselects all others in the group.
-- Keyboard: `Arrow keys` move selection within group. `Tab` exits group.
+Exceptions where real-time validation is acceptable: password strength, character count limits, search/filter fields, OTP.
 
-#### ARIA
-```tsx
-<div role="radiogroup" aria-labelledby="group-label">
-  <label>
-    <input type="radio" aria-checked="true" /> Option A
-  </label>
-</div>
-// Arrow key navigation must move both focus and selection together
-```
+✅ Primary CTA disabled → user fills all mandatory fields → button enables → submit → validate all
+❌ Primary CTA active on an empty form
+❌ Inline errors appearing as the user types in a standard form field
 
 ---
 
-### Tab / CustomViewTab
-
-**Applies to: `Tab` (Navigation, Custom View)**
+### LCB-10: Form submit keyboard shortcut — always show `⌘↵` on primary CTA
+The primary action button in every form must display the `⌘↵` keyboard shortcut hint using the `Shortcut` component.
+`Cmd+Enter` is the standard submit shortcut across all forms.
 
-#### When to use
-- Parallel, mutually exclusive content sections on the same page.
-- Each section is substantial enough to be its own named panel.
-- 2–7 tabs.
+✅ `<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>`
+❌ Primary form button with no keyboard shortcut hint
 
-#### Do NOT use when
-- Sections are sequential steps → use stepper
-- Fewer than 2 tabs
-- More than 6–7 tabs → use sidebar nav or Select
-- Goal is filtering same content → use Chip
+---
 
-#### Tab vs Segment control
-| | Segment control | Tab |
-|---|---|---|
-| What changes | How content is rendered | The content itself |
-| Architecture | Display preference | Part of information architecture |
-| URL typically | Does not update | Updates (sub-routes) |
+### Tag semantic color mapping
 
-#### Rules
-- **One tab must always be selected.** No valid unselected state.
-- All tabs in a group must be the same type.
-- Tab labels: nouns only. No verbs. "Overview" not "View overview".
-- Disabled tabs: explain via tooltip. Remove if always disabled for all users.
-- Content panel must be directly below/adjacent to tabs — never disconnected.
-- Never nest tabs within tabs.
+Always match Tag variant to the semantic meaning of the value. Never use the
+same variant for all tags in a list.
 
-#### Keyboard
-- `Tab` → focus tab row
-- `←` `→` → move between tabs
-- `Enter` / `Space` → select focused tab
-- `Tab` → move into content panel
+| Value meaning | Tag variant |
+|---|---|
+| Done, active, on track, success, approved, complete | success |
+| At risk, pending, in review, in progress, waiting | warning |
+| Behind, blocked, failed, rejected, overdue, error | error |
+| Draft, inactive, unknown, archived, neutral | neutral |
+| Informational, new, upcoming | info |
 
-#### ARIA
-```tsx
-<div role="tablist">
-  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1" tabIndex={0}>Overview</button>
-  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabIndex={-1}>Activity</button>
-</div>
-<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
-<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
-// Only selected tab has tabIndex=0. All others tabIndex=-1.
-// Inactive panels: hidden or aria-hidden="true"
-```
+When in doubt, ask: is this good, bad, cautionary, or neutral?
+Pick the variant that matches that meaning.
 
 ---
 
-### SegmentControl
+### Page margin application
 
-**Applies to: `SegmentControl`, `SegmentControlSelector`**
+The content area must always have horizontal breathing room. Apply
+`var(--page-margin-x)` as `padding-inline` on the direct child of the content area —
+not on individual components.
 
-#### When to use
-- Switch between 2–5 mutually exclusive views or modes.
-- Effect is **immediate** — no content panels, no confirmation.
-- "List", "Grid", "Map" / "Day", "Week", "Month"
+```css
+/* CORRECT */
+.page-content {
+  padding-inline: var(--page-margin-x);
+}
 
-#### Do NOT use when
-- More than 5 options → use Select or Tabs
-- Options have distinct content panels → use Tabs
-- Requires confirmation → use Radio
-- Binary setting → use Switcher
-- Stackable filters → use Chips
+/* WRONG */
+.page-content {
+  padding: 0; /* flush to edges */
+}
+```
 
-#### Rules
-- **One selector always active.** No valid unselected state.
-- All selectors must be equal width.
-- Max 5 options.
-- Never use as navigation.
+This applies to every page without exception: tables, cards, charts, lists,
+empty states. Nothing should ever touch the left or right edge of the content area.
 
-#### ARIA
-```tsx
-<div role="group" aria-label="View mode">
-  <button role="radio" aria-checked="true">List</button>
-  <button role="radio" aria-checked="false">Grid</button>
-</div>
-// Arrow key navigation moves focus and selection together
-```
+---
+
+## Component Usage Rules
 
 ---
 
-### Breadcrumbs / BreadcrumbItem
+### Button
 
-**Applies to: `Breadcrumbs`, `BreadcrumbItem`**
+**Applies to: `Button` (Main, Destructive, Toggle, Vertical)**
 
 #### When to use
-- Clear hierarchy of at least 3 levels.
-- Users navigate between levels frequently.
 
-#### Do NOT use when
-- Hierarchy is flat (≤2 levels)
-- Single-level navigation pattern
-- User arrived via deep link and path is not meaningful
+- **Main button**: default for actions. Not destructive, not icon-only, not vertical.
+- **Destructive button**: irreversible or harmful actions (delete, discard). Same variants as Main but danger color.
+- **Toggle button**: persistent on/off state in toolbars (Bold, Italic, view mode). NOT a one-off action trigger.
+- **Vertical button**: icon + label stacked, in bottom toolbars only.
 
-#### Item types
-| Type | Description |
-|---|---|
-| `Previous` | Ancestor level — interactive link |
-| `Current` | Current location — not a link, not interactive |
-| `Ellipsis` | Collapsed middle levels — expandable on click |
+#### Do NOT use a button when
+- Action navigates to a page → use a link
+- Action toggles a setting → use Switcher
+- Action selects from a set → use Segment control or Tab
 
-- **Last item is always `Current`.** Must not be a link.
-- Never truncate `Current` item.
-- When trail overflows: always keep root (leftmost) and current (rightmost).
+#### Props and variants
+
+```typescript
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'plain';
+type ButtonSize = 'sm' | 'md';
+// plain is only available in sm
+```
+
+#### Hierarchy rules
+- **One Primary per view.** Never two Primary buttons side by side unless forced mutually exclusive choice.
+- **Secondary**: supports Primary or equal-weight alternative.
+- **Ghost**: functional/utility (filter, sort, copy). Not a "quieter Primary".
+- **Plain**: dismissive, space-constrained, `sm` only. "Cancel", "Skip".
+
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Loading` · `Selected` *(Toggle/Vertical only)*
+
+- `Selected` is a boolean prop. Use `aria-pressed="true/false"` for Toggle/Vertical.
+- Do NOT use `aria-pressed` on Main or Destructive buttons.
+- `Loading` → use `aria-busy="true"` on the button.
+- `Disabled` → never rely on opacity alone. Do not disable Primary as a form validation strategy.
+
+#### Placement
+- Button group order left-to-right: Ghost/Plain → Secondary → **Primary** (most important is trailing).
+- Destructive confirmation: Destructive right, "Cancel" left.
+- Toggle buttons → toolbars only.
+- Vertical buttons → bottom toolbars/action panels only.
 
 #### ARIA
 ```tsx
-<nav aria-label="Breadcrumb">
-  <ol>
-    <li><a href="/home">Home</a></li>
-    <li><a href="/projects">Projects</a></li>
-    <li><span aria-current="page">Q4 Campaign</span></li>
-  </ol>
-</nav>
-// Ellipsis
-<button aria-label="Show more breadcrumbs">…</button>
-// Separators — decorative, must not be read aloud
-<span aria-hidden="true">/</span>
+<button type="button" disabled={disabled} aria-pressed={selected} aria-busy={loading} aria-label="...for icon-only">
 ```
 
+#### Content rules
+- Start with a strong verb: "Save", "Delete", "Export"
+- Specific: "Save changes" not "OK" or "Yes"
+- 1–3 words; 5 maximum
+- Sentence case: "Save changes" not "Save Changes"
+- Destructive labels: name what is destroyed. "Delete account" not "Confirm"
+- Loading labels: present-progressive. "Saving…"
+- Toggle `aria-label`: describes the action, not the state. "Bold" not "Bold is active"
+
 ---
 
-### Pagination / PageSelector
+### Avatar / AvatarGroup
 
-**Applies to: `Pagination`, `PageSelector`**
+**Applies to: `Avatar`, `AvatarGroup`**
 
 #### When to use
-- Large dataset divided into pages where user benefits from explicit navigation.
-- Data tables, search results, record lists.
+- Represents a person or organization where visual identity aids recognition.
+- Do NOT use for generic system processes or when no identity info is available.
 
-#### Do NOT use when
-- Dataset fits in one view → show everything
-- Primary interaction is continuous browsing → use infinite scroll
-- Within a compact panel → use load-more button
+#### Variants
+- `Profile`: individual person
+- `Organization`: company/team
+- Never mix Profile and Organization in the same list without clear reason.
 
-#### Rules
-- Always show current page as `Selected`.
-- Always show first and last page numbers.
-- Collapse middle ranges with ellipsis; keep current page ± 1–2 neighbors.
-- Previous/Next arrows: **disable** at boundaries, never hide.
-- Show total record count: "Showing 41–60 of 243 results".
-- After page navigation: move focus to top of updated content area.
+#### Fill priority (always use highest fidelity available)
+1. `Picture` — real photo/logo
+2. `Initials` — derived from name
+3. `Icon` — anonymous fallback
+
+Never show Icon when Initials are derivable.
+
+#### Sizes (Avatar: 7-step scale)
+`xxs` · `xs` · `sm` · `md` (default) · `lg` · `xl` · `xxl`
+
+Use consistent sizes within a list. Never mix sizes in a collection.
+
+#### AvatarGroup
+- Sizes: `xxs`, `xs`, `sm` only
+- Show "+" overflow indicator when list exceeds display limit (typically 3–5)
+- Overflow indicator must include full list in `aria-label`
+- Do not use for >20 members without a "view all" affordance
 
 #### ARIA
 ```tsx
-<nav aria-label="Pagination">
-  <button aria-label="Go to previous page" aria-disabled="true">←</button>
-  <button aria-current="page">3</button>
-  <button>4</button>
-  <button aria-label="More pages">…</button>
-  <button aria-label="Go to next page">→</button>
-</nav>
-// Page change: use aria-live region to announce update
+// Individual: meaningful avatar
+<img alt="Ana Costa" aria-label="Ana Costa" />
+
+// Icon fill, no identity
+<span aria-hidden="true" />
+
+// AvatarGroup
+<div aria-label="Assigned to: Ana Costa, João Silva, and 2 others">
 ```
 
+#### Content rules — Initials
+- Person: first + last initial. "Ana Costa" → "AC"
+- Single name: first two letters. "Cher" → "CH"
+- Organization: first two letters or first letter of each word (max 2). "Design Studio" → "DS"
+- Always uppercase. Max 2 characters.
+
 ---
 
-### Toast (Inline, Rich)
+### Badge
 
-**Applies to: `Toast`**
+**Applies to: `Badge`**
 
 #### When to use
-- Confirm a completed action or surface a system event without interrupting the current task.
-- Non-blocking. Temporary.
+- Attach to another element to surface a count or status signal.
+- Notification count on a navigation icon, pending actions, critical status.
 
 #### Do NOT use when
-- Critical, requires action before continuing → use modal or alert banner
-- Related to a specific form field → use inline validation
-- Complex, multiple actions needed → use Rich toast or reconsider modal
-- Unsolicited marketing/promotional content → never appropriate
-
-#### Types
-- **Inline toast**: single message, brief confirmation.
-- **Rich toast**: title + body + optional action. Use only when additional space is genuinely needed.
+- Label is text/category → use Tag
+- User can select/dismiss it → use Chip
+- Requires user response → use Toast or alert banner
+- Count is zero → **hide the badge**
 
-#### Severity
-| Severity | Use |
+#### Variants
+| Variant | Use |
 |---|---|
-| `Default` | Neutral confirmations, background tasks |
-| `Success` | Most common — action completed as expected |
-| `Warning` | Completed with caveat, system condition |
-| `Error` | Genuine failures only — **persists until dismissed** |
+| `Highlight soft` | Low urgency — new content, informational count |
+| `Highlight strong` | Moderate urgency — pending actions, unread items |
+| `Informative` | Neutral — generic counts |
+| `Critical` | Urgent — errors, failures. **Use sparingly.** |
 
-#### Auto-dismiss durations
-- `Default` / `Success`: 4–5 seconds
-- `Warning`: 6–8 seconds
-- `Error`: persistent or 8–10 seconds minimum
-- Rich toast with action: persist until user acts or dismisses
+#### Sizes
+- `sm`: default — icons, avatars, compact items
+- `lg`: larger host elements
+- `Dot`: presence-only signal. `Highlight strong` and `Critical` only.
 
-Always provide a manual dismiss (×) button.
-Pause auto-dismiss on hover (desktop).
+#### Count display rules
+- ≤99: show exact count
+- >99: show "99+"
+- 0: **remove the badge entirely**
 
 #### ARIA
 ```tsx
-// Success, warning, default
-<div aria-live="polite" role="status">Changes saved.</div>
-
-// Error
-<div aria-live="assertive" role="alert">Couldn't save changes.</div>
-
-// Dismiss button
-<button aria-label="Dismiss notification">×</button>
+// Host element's accessible name must include the count
+<button aria-label="Messages, 3 unread" />
+// Dynamic count changes
+<div aria-live="polite" /> // only for meaningful threshold transitions
 ```
 
 ---
 
-### Tooltip
+### Tag
 
-**Applies to: `Tooltip`**
+**Applies to: `Tag`**
 
 #### When to use
-- Brief supplementary context — hover or keyboard focus only.
-- Label icon-only buttons, reveal truncated text, show keyboard shortcuts.
+- Non-interactive categorical label or status on content items.
+- Status: "Active", "Archived", "Pending review"
+- Category: "Design", "Bug", "High"
 
 #### Do NOT use when
-- Critical info user must see → place inline
-- Content longer than one sentence → use Popover
-- Content has interactive elements → use Popover
-- Trigger is disabled → use visible text explanation instead
-- Touch device as primary platform → ensure info is available another way
+- User can interact with it → use Chip
+- It's a numeric count → use Badge
+- Urgent system condition → use Toast
 
-#### Rules
-- Plain text only. No icons, buttons, or links.
-- One sentence maximum.
-- Appears on hover (100–200ms delay) and keyboard focus. Never on click.
-- Dismiss: cursor leaves, focus moves, or `Escape`.
+#### Variants
+| Variant | Semantic meaning |
+|---|---|
+| `Highlight` | Notable, not urgent |
+| `Warning` | Caution — needs awareness soon |
+| `Error` | Something is wrong or blocked |
+| `Success` | Completed, approved, healthy |
+| `Neutral` | Purely categorical, no status weight |
+
+Use the variant matching semantic meaning, not preferred color.
+
+#### Sizes
+- `md`: default
+- `sm`: dense layouts, multiple tags per item
+
+Use consistent sizes within a list. Never mix on the same row.
+
+#### Tags have NO interaction states. Not clickable. Never.
+
+#### Placement
+- Show max 3 tags per item.
+- Order: severity first (Error → Warning → Success), then category.
+- Do not wrap — truncate and show full value in tooltip if space is insufficient.
 
 #### ARIA
 ```tsx
-<button aria-label="Export as CSV" aria-describedby="tooltip-export">Export</button>
-<div role="tooltip" id="tooltip-export">Export table as CSV</div>
-// Tooltip text and aria-label must match for icon-only buttons
+// Include tag content in accessible name of parent
+<li aria-describedby="tag-status">
+  <span id="tag-status" role="status">Error</span>
 ```
 
 ---
 
-### Popover (Container, Simple Menu, Complex Menu)
+### Chip / ChipGroup
 
-**Applies to: `Popover`**
+**Applies to: `Chip`, `ChipGroup`**
 
-#### When to use
-- Contextual rich content anchored to an element. User clicks to open.
-- Definitions, action menus, date picker triggers, quick-edit panels.
+#### When to use
+- User needs to select, activate, or dismiss a discrete value.
+- Filter controls, multi-value input, toggleable options.
 
 #### Do NOT use when
-- Single short sentence, no interaction → use Tooltip
-- Demands full attention, blocks UI → use Modal
-- Extended task the user interacts with over time → use Drawer
-- Navigation menu → use dedicated nav component
+- Purely informational → use Tag
+- Mutually exclusive form selection → use Radio
+- Multi-option form selection → use Checkbox
+- Settings toggle → use Switcher
 
-#### Types
-- **Container**: free-form rich content
-- **Simple menu**: flat list, 2–6 items, no grouping
-- **Complex menu**: grouped, with section headings, scrollable
+#### Sizes
+- `md`: default
+- `sm`: compact layouts
 
-#### Rules
-- Opens on **click/tap** only. Never on hover.
-- Dismissal: click outside, `Escape`, trigger toggle, or completing action.
-- Do not nest popovers inside other popovers.
-- For menus: selecting an item closes popover automatically.
-- For container with unsaved form input: do NOT auto-close on outside click.
+Never mix `md` and `sm` in the same chip group.
 
-#### Positioning contract (shared `PopoverWrapper`)
-- Default placement: below trigger
-- Gap: `var(--space-tiny)`
-- Flip: only when not enough space below
-- Viewport safe margin: `var(--space-medium)` on all edges
-- Width: match trigger width, minimum 192px
-- Never re-implement per-component popover math — reuse `PopoverWrapper`
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Selected` (boolean)
+
+`Selected` combines freely with `Hover`, `Pressed`, `Focused`.
+
+#### Keyboard interaction
+- `Space` or `Enter` → toggle
+- `Tab` → move between chips
 
 #### ARIA
 ```tsx
-// Trigger
-<button aria-haspopup="true" aria-expanded={isOpen}>Options</button>
+// Multi-select filter group
+<div role="group" aria-label="Filter by status">
+  <button role="checkbox" aria-checked="true">Active</button>
+  <button role="checkbox" aria-checked="false">Closed</button>
+</div>
 
-// Menu type
-<div role="menu">
-  <button role="menuitem">Edit</button>
-  <button role="menuitem">Delete</button>
+// Single-select group
+<div role="radiogroup" aria-label="Filter by status">
+  <button role="radio" aria-checked="true">Active</button>
 </div>
 
-// Container type
-<div role="dialog" aria-label="Filter options">...</div>
+// Dismiss button on chip
+<button aria-label="Remove Active" />
 
-// On open: focus moves INTO popover (first interactive element)
-// On close: focus returns to trigger element
-// Escape: closes and returns focus
-// Arrow keys: navigate between menuitem elements
+// Disabled chip
+aria-disabled="true"  // keep in reading order
 ```
 
 ---
 
-### Modal
+### Separator
 
-**Applies to: `Modal`**
+**Applies to: `Separator`**
 
 #### When to use
-- User must complete a task or make a decision before continuing.
-- Confirmations, compact forms, critical warnings, media previews.
+- Visual divider between content sections that are related but distinct.
 
 #### Do NOT use when
-- Informational only → use Toast or inline message
-- Long, multi-step, complex task → use full page or Drawer
-- Contextually anchored to an element → use Popover
-- User needs to reference background content → use Drawer
-
-#### Rules
-- Every modal must have a **title**.
-- Every modal must have an **explicit dismiss** (× in header + cancel in footer).
-- **One primary action only.** Two equal actions → Secondary + Secondary, not two Primary.
-- Never open a modal from within a modal.
-- Never auto-open on page load.
-- `Escape` must close unless accidental dismissal would cause irreversible data loss.
-- Background page scroll must be disabled while modal is open.
+- Adequate spacing already separates sections
+- Sections are already separated by color/card borders
+- Purpose is purely decorative
 
-#### Interaction
-- Opening: explicit user action only.
-- Focus moves INTO modal on open (first interactive element or container).
-- Focus is **trapped** within modal while open.
-- Focus returns to triggering element on close.
+#### Directions
+- `Horizontal`: stacked content, spans full container width
+- `Vertical`: side-by-side content, spans full container height
 
 #### ARIA
 ```tsx
-<div role="dialog" aria-modal="true" aria-labelledby="modal-title" aria-describedby="modal-desc">
-  <h2 id="modal-title">Delete project</h2>
-  <p id="modal-desc">This will permanently delete the project and all its data. This cannot be undone.</p>
-  <div aria-hidden="true" class="overlay" />  {/* backdrop is aria-hidden */}
-</div>
+// Structural separator
+<hr /> // or <div role="separator" />
+
+// Decorative only
+<div aria-hidden="true" />
 ```
 
 ---
 
-### Input — shared anatomy
-
-**Applies to: all input components**
+### Switcher
 
-#### Anatomy
-```
-[Label]         ← always required (visible or aria-label)
-[Control]       ← must have visible boundary
-[Helper text]   ← optional; replace with real content or hide — never leave placeholder text
-[Error message] ← replaces helper text in error state
-```
+**Applies to: `Switcher`**
 
-#### States
-`Empty` · `Hover` · `Active` · `Filled` · `Focused` · `Error` · `Disabled`
+#### When to use
+- Single binary setting, **effect is immediate** (no confirmation step).
+- Enabling features, notification settings, preferences.
 
-- `Empty` ≠ `Filled`: never conflate. `Empty` has no value, `Filled` always does.
-- `Active` ≠ `Focused`: Active = typing (cursor present). Focused = keyboard focus without typing.
-- `Disabled`: use native `disabled` attribute or `aria-disabled="true"`. Not tab-focusable.
+#### Do NOT use when
+- More than 2 states → use Radio or Select
+- Multiple independent options → use Checkbox
+- Requires confirmation before taking effect → use Checkbox
+- Compact toolbar → use Toggle button
+- Choosing between UI views/modes → use Segment control or Tabs
 
-#### Validation timing
-- **Default**: validate on **blur** (leaving the field).
-- **Real-time** only for: password strength, character count limits, search/filter fields, OTP.
-- On form submit: show **all errors at once**, scroll to and focus the first errored field.
-- Once shown, re-validate in real time as user corrects. Remove error when value becomes valid.
-- Never hide error on blur alone — only when value is actually valid.
+#### Decision: Switcher vs Checkbox vs Toggle button
+| Component | Effect | Context |
+|---|---|---|
+| **Switcher** | Immediate | Settings with visible label |
+| **Checkbox** | Staged (on submit) | Forms |
+| **Toggle button** | Immediate | Icon-only toolbar |
 
-#### Label rules
-- Required for all inputs.
-- Visible label above control is default and preferred.
-- Left-of-control only in Horizontal input layouts.
-- Never use placeholder text as label substitute.
-- Label describes what the field contains: "Email address" not "Enter your email address".
-- Every field is mandatory by default. Only mark optional fields with an "Optional" label in `var(--text-tertiary)` placed inline after the label text. Never use asterisks.
-- Add `aria-required="true"` on all mandatory inputs regardless of visual treatment.
+#### Sizes
+- `md`: default
+- `sm`: dense layouts
 
-#### ARIA — all inputs
-```tsx
-<label htmlFor="email">Email address</label>
-<input
-  id="email"
-  aria-describedby="email-helper email-error"
-  aria-invalid={hasError}
-  aria-required={required}
-  disabled={disabled}
-/>
-<p id="email-helper">We'll only use this to send receipts.</p>
-<p id="email-error" aria-live="polite">Email address is invalid.</p>
-```
+Never mix sizes within a settings group.
 
----
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
 
-### TextInput
+`Selected` and `Disabled` are independent booleans.
 
-**Applies to: `TextInput`**
+#### Rules
+- Always pair with a visible label. **Never use a switcher without a label.**
+- When `Selected=True` + `Disabled=True`: always explain why it's locked.
+- If toggle has latency, show loading indicator alongside — don't leave in ambiguous state.
 
-Single-line free-form text. Use when no more specific input type applies.
+#### Keyboard
+- `Space` → toggle
 
-Do NOT use for multi-line → TextArea | numbers → NumberInput | passwords → PasswordInput | phone → PhoneInput | search → SearchInput | predefined list → Select.
+#### ARIA
+```tsx
+<button role="switch" aria-checked={isOn} aria-labelledby="label-id" />
+// Disabled
+aria-disabled="true"  // keep in reading order
+```
 
 ---
 
-### TextArea
+### Checkbox
 
-**Applies to: `TextArea`**
+**Applies to: `Checkbox`**
 
-Multi-line free-form text.
+#### When to use
+- User selects any number of independent options (zero to all).
+- Selection takes effect only after **explicit confirmation** (submit button).
 
-- Minimum height: 3 lines
-- Allow vertical resize (desktop)
-- Show character count when limit exists: "120 characters remaining" not "380/500"
+#### Do NOT use when
+- Only one can be selected → use Radio
+- Effect is immediate → use Switcher
+- Compact token-like pattern → use Chip
+- Single toggle for a setting → use Switcher
 
----
+#### Sizes
+- `md`: default
+- `sm`: dense layouts
 
-### SearchInput
+Never mix sizes in a single form group.
 
-**Applies to: `SearchInput`**
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
 
-Search and filter interactions.
+**Indeterminate state**: when a parent checkbox controls sub-items with partial selection.
 
-- **Bordered**: standard, full border
-- **Borderless**: inline in toolbars/headers
-- Always include clear (×) button when field has value.
-- `Error` state is for system errors (service unavailable) — NOT for "no results".
-- "No results" → show empty state in results area, not an input error.
+#### Interaction
+- Click on checkbox **or its label** toggles selection (full row is hit target).
+- State changes are staged — not immediate.
 
+#### ARIA
 ```tsx
-<input type="search" />
-<button aria-label="Clear search">×</button>
+<fieldset>
+  <legend>Notification preferences</legend>
+  <label>
+    <input type="checkbox" aria-checked="true" /> Send weekly summary
+  </label>
+</fieldset>
+
+// Indeterminate
+aria-checked="mixed"
+
+// Disabled — keep in reading order
+aria-disabled="true"
 ```
 
 ---
 
-### PasswordInput
+### Radio
 
-**Applies to: `PasswordInput`**
+**Applies to: `Radio`**
 
-- Always include show/hide toggle.
-- Show strength indicator + requirements list for new passwords.
-- Validate confirm password on blur of confirm field only.
-- `Revealed` state: type switches from `password` to `text`.
+#### When to use
+- Exactly one option from a mutually exclusive set.
+- All options visible simultaneously (2–6 items).
+- Effect takes place after **explicit confirmation**.
 
-```tsx
-<input type="password" autocomplete="current-password" />
-// or new-password for registration
-<button aria-label="Show password" /> // toggles to "Hide password"
-```
+#### Do NOT use when
+- Multiple can be selected → use Checkbox
+- More than 6–7 options → use Select
+- Immediate effect → use Switcher or Segment control
+- Single on/off option → use Checkbox or Switcher
 
----
+#### Sizes
+- `md`: default
+- `sm`: dense layouts
 
-### OTPInput
+Never mix sizes within a radio group.
 
-**Applies to: `OTPInput`**
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
 
-- Auto-advance: entering a character moves focus to next field.
-- Auto-submit: when last field filled (fixed length), trigger verification automatically.
-- Paste handling: full code must populate all fields at once.
-- Backspace: moves focus to previous field and clears it.
+No indeterminate state for Radio. A group always has 0–1 selected.
 
-States: `Empty` · `Partially filled` · `Verifying` · `Correct` · `Error` · `Disabled`
+#### Interaction
+- Click radio **or its label** to select (full row is hit target).
+- Selecting one deselects all others in the group.
+- Keyboard: `Arrow keys` move selection within group. `Tab` exits group.
 
+#### ARIA
 ```tsx
-<div role="group" aria-label="Enter 6-digit verification code">
-  <input aria-label="Digit 1 of 6" />
-  <input aria-label="Digit 2 of 6" />
-  ...
+<div role="radiogroup" aria-labelledby="group-label">
+  <label>
+    <input type="radio" aria-checked="true" /> Option A
+  </label>
 </div>
-// Verifying state: aria-live announcement
-// Correct/Error states: must be announced
+// Arrow key navigation must move both focus and selection together
 ```
 
 ---
 
-### NumberInput
+### Tab / CustomViewTab
 
-**Applies to: `NumberInput`**
+**Applies to: `Tab` (Navigation, Custom View)**
 
-- Always define and enforce min/max where applicable.
-- Stepper buttons disable at boundaries.
-- Always allow direct keyboard entry (steppers are not the only input method).
-- Do NOT use for currency, ranges (use Slider), or large numeric IDs.
+#### When to use
+- Parallel, mutually exclusive content sections on the same page.
+- Each section is substantial enough to be its own named panel.
+- 2–7 tabs.
 
----
+#### Do NOT use when
+- Sections are sequential steps → use stepper
+- Fewer than 2 tabs
+- More than 6–7 tabs → use sidebar nav or Select
+- Goal is filtering same content → use Chip
 
-### PhoneInput
+#### Tab vs Segment control
+| | Segment control | Tab |
+|---|---|---|
+| What changes | How content is rendered | The content itself |
+| Architecture | Display preference | Part of information architecture |
+| URL typically | Does not update | Updates (sub-routes) |
 
-**Applies to: `PhoneInput`**
+#### Rules
+- **One tab must always be selected.** No valid unselected state.
+- All tabs in a group must be the same type.
+- Tab labels: nouns only. No verbs. "Overview" not "View overview".
+- Disabled tabs: explain via tooltip. Remove if always disabled for all users.
+- Content panel must be directly below/adjacent to tabs — never disconnected.
+- Never nest tabs within tabs.
 
-- Always use `PhoneInput` for international phone numbers (not a plain TextInput).
-- Pre-select user's locale as default country code.
-- Allow paste of full international number — auto-populate country selector and number field.
-- Uses `PopoverWrapper` for dropdown (do not re-implement positioning).
+#### Keyboard
+- `Tab` → focus tab row
+- `←` `→` → move between tabs
+- `Enter` / `Space` → select focused tab
+- `Tab` → move into content panel
 
+#### ARIA
 ```tsx
-<div role="group" aria-label="Phone number">
-  <select aria-label="Country code" autocomplete="tel-country-code" />
-  <input aria-label="Phone number" autocomplete="tel" />
+<div role="tablist">
+  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1" tabIndex={0}>Overview</button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabIndex={-1}>Activity</button>
 </div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
+// Only selected tab has tabIndex=0. All others tabIndex=-1.
+// Inactive panels: hidden or aria-hidden="true"
 ```
 
 ---
 
-### Select
+### SegmentControl
 
-**Applies to: `Select`**
+**Applies to: `SegmentControl`, `SegmentControlSelector`**
 
-- Use for single-value selection from a fixed list when 7+ options or space-constrained.
-- Do NOT use for ≤6 options with space → use Radio instead.
-- Always include a placeholder option that is NOT a valid value.
-- Add search/filter within dropdown for 20+ options.
+#### When to use
+- Switch between 2–5 mutually exclusive views or modes.
+- Effect is **immediate** — no content panels, no confirmation.
+- "List", "Grid", "Map" / "Day", "Week", "Month"
 
-```tsx
-// Native when possible
-<select aria-required={required} aria-invalid={hasError}>
-  <option value="">Select country</option>
-</select>
+#### Do NOT use when
+- More than 5 options → use Select or Tabs
+- Options have distinct content panels → use Tabs
+- Requires confirmation → use Radio
+- Binary setting → use Switcher
+- Stackable filters → use Chips
 
-// Custom implementation
-<div role="combobox" aria-expanded={open} aria-haspopup="listbox" aria-controls="list">
-<div id="list" role="listbox">
-  <div role="option" aria-selected="true">Portugal</div>
+#### Rules
+- **One selector always active.** No valid unselected state.
+- All selectors must be equal width.
+- Max 5 options.
+- Never use as navigation.
+
+#### ARIA
+```tsx
+<div role="group" aria-label="View mode">
+  <button role="radio" aria-checked="true">List</button>
+  <button role="radio" aria-checked="false">Grid</button>
 </div>
+// Arrow key navigation moves focus and selection together
 ```
 
 ---
 
-### AutocompleteMulti
+### Breadcrumbs / BreadcrumbItem
 
-**Applies to: `AutocompleteMulti`**
+**Applies to: `Breadcrumbs`, `BreadcrumbItem`**
 
-- Search-and-select multiple values from large/dynamic lists.
-- Each selected value becomes a chip inside the input.
-- Backspace on empty field removes last chip.
+#### When to use
+- Clear hierarchy of at least 3 levels.
+- Users navigate between levels frequently.
+
+#### Do NOT use when
+- Hierarchy is flat (≤2 levels)
+- Single-level navigation pattern
+- User arrived via deep link and path is not meaningful
+
+#### Item types
+| Type | Description |
+|---|---|
+| `Previous` | Ancestor level — interactive link |
+| `Current` | Current location — not a link, not interactive |
+| `Ellipsis` | Collapsed middle levels — expandable on click |
+
+- **Last item is always `Current`.** Must not be a link.
+- Never truncate `Current` item.
+- When trail overflows: always keep root (leftmost) and current (rightmost).
 
+#### ARIA
 ```tsx
-<div role="combobox" aria-multiselectable="true" aria-expanded={open}>
-<button aria-label="Remove Portugal">×</button>
-<div role="listbox">
-  <div role="option" aria-selected="true">Portugal</div>
-</div>
-// Chip add/remove: aria-live="polite"
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/home">Home</a></li>
+    <li><a href="/projects">Projects</a></li>
+    <li><span aria-current="page">Q4 Campaign</span></li>
+  </ol>
+</nav>
+// Ellipsis
+<button aria-label="Show more breadcrumbs">…</button>
+// Separators — decorative, must not be read aloud
+<span aria-hidden="true">/</span>
 ```
 
 ---
 
-### HorizontalInput
-
-**Applies to: `HorizontalInput`**
-
-- Label left, control right — layout wrapper only.
-- Use in dense settings panels, property editors.
-- Do NOT use in standard forms, mobile layouts, or with long labels.
-- Label must not wrap — keep to 3–4 words maximum.
-- Consistent label widths within a group.
+### Pagination / PageSelector
 
----
+**Applies to: `Pagination`, `PageSelector`**
 
-### Slider
+#### When to use
+- Large dataset divided into pages where user benefits from explicit navigation.
+- Data tables, search results, record lists.
 
-**Applies to: `Slider`**
+#### Do NOT use when
+- Dataset fits in one view → show everything
+- Primary interaction is continuous browsing → use infinite scroll
+- Within a compact panel → use load-more button
 
-- `Max value` type: one handle
-- `Range` type: two handles — prevent handles from crossing
-- Always show current value alongside handle (tooltip or persistent label).
-- Display min/max labels at track ends.
-- Pair with NumberInput when precision matters.
+#### Rules
+- Always show current page as `Selected`.
+- Always show first and last page numbers.
+- Collapse middle ranges with ellipsis; keep current page ± 1–2 neighbors.
+- Previous/Next arrows: **disable** at boundaries, never hide.
+- Show total record count: "Showing 41–60 of 243 results".
+- After page navigation: move focus to top of updated content area.
 
+#### ARIA
 ```tsx
-<div aria-label="Price range" aria-labelledby="slider-label">
-  <input role="slider"
-    aria-valuenow={120} aria-valuemin={0} aria-valuemax={500}
-    aria-valuetext="€120"
-    aria-label="Minimum price" />
-</div>
-// Arrow keys: ±1 step
-// Page Up/Down: larger increment
-// Home/End: jump to min/max
+<nav aria-label="Pagination">
+  <button aria-label="Go to previous page" aria-disabled="true">←</button>
+  <button aria-current="page">3</button>
+  <button>4</button>
+  <button aria-label="More pages">…</button>
+  <button aria-label="Go to next page">→</button>
+</nav>
+// Page change: use aria-live region to announce update
 ```
 
 ---
 
-### UploadArea
+### Toast (Inline, Rich)
 
-**Applies to: `UploadArea`**
+**Applies to: `Toast`**
 
-- Always provide click-to-browse fallback (not all users can drag-drop).
-- State accepted file types and size limits in Empty state.
-- Reject invalid file types immediately on drop with clear error.
-- Show upload progress after file accepted.
+#### When to use
+- Confirm a completed action or surface a system event without interrupting the current task.
+- Non-blocking. Temporary.
 
-```tsx
-<div role="button" aria-label="Upload files — click or drag and drop"
-  aria-describedby="upload-constraints" tabIndex={0}>
-// Enter/Space when focused: opens system file picker
-// Dropping state: aria-live announcement
-```
+#### Do NOT use when
+- Critical, requires action before continuing → use modal or alert banner
+- Related to a specific form field → use inline validation
+- Complex, multiple actions needed → use Rich toast or reconsider modal
+- Unsolicited marketing/promotional content → never appropriate
 
----
+#### Types
+- **Inline toast**: single message, brief confirmation.
+- **Rich toast**: title + body + optional action. Use only when additional space is genuinely needed.
 
-### ChipsInput
+#### Severity
+| Severity | Use |
+|---|---|
+| `Default` | Neutral confirmations, background tasks |
+| `Success` | Most common — action completed as expected |
+| `Warning` | Completed with caveat, system condition |
+| `Error` | Genuine failures only — **persists until dismissed** |
 
-**Applies to: `ChipsInput`**
+#### Auto-dismiss durations
+- `Default` / `Success`: 4–5 seconds
+- `Warning`: 6–8 seconds
+- `Error`: persistent or 8–10 seconds minimum
+- Rich toast with action: persist until user acts or dismisses
 
-- Free-form entry where each value becomes a chip.
-- Confirm with `Enter` (or comma/Tab as defined per product).
-- Validate each value before converting to chip.
-- Backspace on empty field removes last chip.
+Always provide a manual dismiss (×) button.
+Pause auto-dismiss on hover (desktop).
 
+#### ARIA
 ```tsx
-// Each chip remove button
-<button aria-label="Remove javascript">×</button>
-// Chip additions/removals
-aria-live="polite"
+// Success, warning, default
+<div aria-live="polite" role="status">Changes saved.</div>
+
+// Error
+<div aria-live="assertive" role="alert">Couldn't save changes.</div>
+
+// Dismiss button
+<button aria-label="Dismiss notification">×</button>
 ```
 
 ---
 
-### DatePicker / DateRangePicker
+### Tooltip
 
-**Applies to: `DateTimePicker`**
+**Applies to: `Tooltip`**
 
-- `Single date`: selects one date
-- `Date range`: start + end date — start cannot be after end
+#### When to use
+- Brief supplementary context — hover or keyboard focus only.
+- Label icon-only buttons, reveal truncated text, show keyboard shortcuts.
 
-#### Display modes
-- **Standalone**: always visible
-- **Popover**: triggered by clicking input field (uses `PopoverWrapper`)
+#### Do NOT use when
+- Critical info user must see → place inline
+- Content longer than one sentence → use Popover
+- Content has interactive elements → use Popover
+- Trigger is disabled → use visible text explanation instead
+- Touch device as primary platform → ensure info is available another way
 
 #### Rules
-- Show human-readable format in trigger input: "15 Jan 2026" not "2026-01-15"
-- Communicate date constraints before user opens calendar, not just inside it
-- For range: show both months side by side when range spans months
-- Do NOT pre-select today for historical date entry (e.g. date of birth)
+- Plain text only. No icons, buttons, or links.
+- One sentence maximum.
+- Appears on hover (100–200ms delay) and keyboard focus. Never on click.
+- Dismiss: cursor leaves, focus moves, or `Escape`.
 
+#### ARIA
 ```tsx
-<input aria-haspopup="dialog" aria-expanded={open} />
-<div role="dialog" aria-label="Choose date range">
-  <div role="grid">
-    <div role="gridcell" aria-label="Monday, 15 January 2026" aria-selected="true" tabIndex={0} />
-    <div role="gridcell" aria-label="Tuesday, 16 January 2026" aria-disabled="true" tabIndex={-1} />
-  </div>
-  <button aria-label="Previous month">‹</button>
-  <button aria-label="Next month">›</button>
-</div>
-// Arrow keys: move between days
-// Enter: select day
-// Page Up/Down: navigate months
-// Home/End: first/last day of month
-// Single tabbable day with roving focus — not one tabstop per cell
+<button aria-label="Export as CSV" aria-describedby="tooltip-export">Export</button>
+<div role="tooltip" id="tooltip-export">Export table as CSV</div>
+// Tooltip text and aria-label must match for icon-only buttons
 ```
 
 ---
 
-### Spinner
-
-**Applies to: `Spinner`**
+### Popover (Container, Simple Menu, Complex Menu)
 
-- Use when operation is in progress and duration is unknown.
-- Sizes: `sm` (inline button) · `lg` (panels) · `xl` (page sections) · `xxl` (full-page)
-- Always pair with a label when standalone: "Loading…", "Saving…"
-- Do NOT use multiple spinners simultaneously — consolidate into one.
+**Applies to: `Popover`**
 
-```tsx
-<div role="status" aria-label="Loading results">
-  <svg aria-hidden="true" />
-</div>
-// Completion: aria-live="polite"
-```
+#### When to use
+- Contextual rich content anchored to an element. User clicks to open.
+- Definitions, action menus, date picker triggers, quick-edit panels.
 
----
+#### Do NOT use when
+- Single short sentence, no interaction → use Tooltip
+- Demands full attention, blocks UI → use Modal
+- Extended task the user interacts with over time → use Drawer
+- Navigation menu → use dedicated nav component
 
-### SkeletonLoading
+#### Types
+- **Container**: free-form rich content
+- **Simple menu**: flat list, 2–6 items, no grouping
+- **Complex menu**: grouped, with section headings, scrollable
 
-**Applies to: `SkeletonLoading`**
+#### Rules
+- Opens on **click/tap** only. Never on hover.
+- Dismissal: click outside, `Escape`, trigger toggle, or completing action.
+- Do not nest popovers inside other popovers.
+- For menus: selecting an item closes popover automatically.
+- For container with unsaved form input: do NOT auto-close on outside click.
 
-- Use when content takes >~300ms to load and shape is known.
-- Types: `Avatar` · `Pill` · `Image` · `Card`
-- Always animate (shimmer/pulse) — never show static skeleton shapes.
-- Replace all skeletons simultaneously when content is ready — no piecemeal replacement.
+#### Positioning contract (shared `PopoverWrapper`)
+- Default placement: below trigger
+- Gap: `var(--space-tiny)`
+- Flip: only when not enough space below
+- Viewport safe margin: `var(--space-medium)` on all edges
+- Width: match trigger width, minimum 192px
+- Never re-implement per-component popover math — reuse `PopoverWrapper`
 
+#### ARIA
 ```tsx
-<div aria-busy="true" aria-label="Loading">
-  <div aria-hidden="true" class="skeleton-avatar" />
-  <div aria-hidden="true" class="skeleton-pill" />
+// Trigger
+<button aria-haspopup="true" aria-expanded={isOpen}>Options</button>
+
+// Menu type
+<div role="menu">
+  <button role="menuitem">Edit</button>
+  <button role="menuitem">Delete</button>
 </div>
-// When content ready: aria-busy="false"
-```
 
----
+// Container type
+<div role="dialog" aria-label="Filter options">...</div>
 
-### ProgressBar / LoadingBar
+// On open: focus moves INTO popover (first interactive element)
+// On close: focus returns to trigger element
+// Escape: closes and returns focus
+// Arrow keys: navigate between menuitem elements
+```
 
-**Applies to: `ProgressBar`, `LoadingBar`**
+---
 
-- `LoadingBar`: page-level navigation only, top of viewport. Never inline.
-- `ProgressBar`: measured progress (file upload, onboarding). Always show percentage or step count alongside bar.
+### Modal
 
-```tsx
-<div role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={60}
-  aria-label="Uploading file" />
-// Completion: aria-live="polite"
-```
+**Applies to: `Modal`**
 
----
+#### When to use
+- User must complete a task or make a decision before continuing.
+- Confirmations, compact forms, critical warnings, media previews.
 
-### Scrollbar
+#### Do NOT use when
+- Informational only → use Toast or inline message
+- Long, multi-step, complex task → use full page or Drawer
+- Contextually anchored to an element → use Popover
+- User needs to reference background content → use Drawer
 
-**Applies to: `Scrollbar`**
+#### Rules
+- Every modal must have a **title**.
+- Every modal must have an **explicit dismiss** (× in header + cancel in footer).
+- **One primary action only.** Two equal actions → Secondary + Secondary, not two Primary.
+- Never open a modal from within a modal.
+- Never auto-open on page load.
+- `Escape` must close unless accidental dismissal would cause irreversible data loss.
+- Background page scroll must be disabled while modal is open.
 
-- Never hide scrollbar entirely in scrollable areas.
-- Do not use both vertical and horizontal scrollbars on same container unless content is truly 2D.
-- Custom scrollbars are visual overlays only — underlying scroll must remain keyboard accessible.
+#### Interaction
+- Opening: explicit user action only.
+- Focus moves INTO modal on open (first interactive element or container).
+- Focus is **trapped** within modal while open.
+- Focus returns to triggering element on close.
 
+#### ARIA
 ```tsx
-// Scrollable container
-<div tabIndex={0} />  // allows keyboard focus and arrow key scrolling
+<div role="dialog" aria-modal="true" aria-labelledby="modal-title" aria-describedby="modal-desc">
+  <h2 id="modal-title">Delete project</h2>
+  <p id="modal-desc">This will permanently delete the project and all its data. This cannot be undone.</p>
+  <div aria-hidden="true" class="overlay" />  {/* backdrop is aria-hidden */}
+</div>
 ```
 
 ---
 
-### Shortcut
-
-**Applies to: `Shortcut`**
+### Input — shared anatomy
 
-- Non-interactive display element only.
-- Sizes: `sm` (tooltips/menus) · `md` (standalone/help panels)
-- Colors: `Default` (light BG) · `Inverted` (dark BG)
-- Use platform-standard notation. Detect platform — do not mix Mac/Windows symbols.
-- Keep to keys only: `⌘S` not `⌘ Save`
+**Applies to: all input components**
 
-```tsx
-// Key symbols not reliably announced by screen readers
-<kbd aria-label="Command S">⌘S</kbd>
+#### Anatomy
+```
+[Label]         ← always required (visible or aria-label)
+[Control]       ← must have visible boundary
+[Helper text]   ← optional; replace with real content or hide — never leave placeholder text
+[Error message] ← replaces helper text in error state
 ```
 
----
+#### States
+`Empty` · `Hover` · `Active` · `Filled` · `Focused` · `Error` · `Disabled`
 
-## Cross-component patterns
+- `Empty` ≠ `Filled`: never conflate. `Empty` has no value, `Filled` always does.
+- `Active` ≠ `Focused`: Active = typing (cursor present). Focused = keyboard focus without typing.
+- `Disabled`: use native `disabled` attribute or `aria-disabled="true"`. Not tab-focusable.
 
-These patterns are **decision rules**. Apply before selecting a component.
+#### Validation timing
+- **Default**: validate on **blur** (leaving the field).
+- **Real-time** only for: password strength, character count limits, search/filter fields, OTP.
+- On form submit: show **all errors at once**, scroll to and focus the first errored field.
+- Once shown, re-validate in real time as user corrects. Remove error when value becomes valid.
+- Never hide error on blur alone — only when value is actually valid.
 
-### Pattern 1 — Single select
+#### Label rules
+- Required for all inputs.
+- Visible label above control is default and preferred.
+- Left-of-control only in Horizontal input layouts.
+- Never use placeholder text as label substitute.
+- Label describes what the field contains: "Email address" not "Enter your email address".
+- Every field is mandatory by default. Only mark optional fields with an "Optional" label in `var(--text-tertiary)` placed inline after the label text. Never use asterisks.
+- Add `aria-required="true"` on all mandatory inputs regardless of visual treatment.
 
+#### ARIA — all inputs
+```tsx
+<label htmlFor="email">Email address</label>
+<input
+  id="email"
+  aria-describedby="email-helper email-error"
+  aria-invalid={hasError}
+  aria-required={required}
+  disabled={disabled}
+/>
+<p id="email-helper">We'll only use this to send receipts.</p>
+<p id="email-error" aria-live="polite">Email address is invalid.</p>
 ```
-Does selection require explicit confirmation?
-  Yes → Radio (regardless of option count)
-  No → How many options?
-    2–3 → Segment control
-    4+  → Select
 
-Select has 20+ items?
-  Yes → add search box inside dropdown
-```
+---
 
-### Pattern 2 — Multi select
+### TextInput
 
-```
-How many options?
-  Up to 3 → Chips (shown upfront, immediately toggleable)
-  4+      → Select dropdown + Choice list (Checkbox variant)
+**Applies to: `TextInput`**
+
+Single-line free-form text. Use when no more specific input type applies.
 
-Option set is large (20+), dynamic, or needs typing to find?
-  → Autocomplete multi
-```
+Do NOT use for multi-line → TextArea | numbers → NumberInput | passwords → PasswordInput | phone → PhoneInput | search → SearchInput | predefined list → Select.
 
-### Pattern 3 — Binary (on/off)
+---
 
-```
-Context?
-  Toolbar, icon-only, immediate → Toggle button (+ mandatory Tooltip)
-  Form, deferred, confirmed on submit → Checkbox
-  Settings, labeled, immediate → Switcher
-```
+### TextArea
 
-### Pattern 4 — Filter bar
+**Applies to: `TextArea`**
 
-```
-How many filter values?
-  1         → Toggle button
-  2–5       → Chips in a horizontal bar
-  6+        → "Filters" button → dropdown (6–12) or drawer (13+)
+Multi-line free-form text.
 
-Always: show active state, provide "Clear all" action when any filter active
-```
+- Minimum height: 3 lines
+- Allow vertical resize (desktop)
+- Show character count when limit exists: "120 characters remaining" not "380/500"
 
-### Pattern 5 — Pagination vs Infinite scroll
+---
 
-```
-Content type?
-  Data tables → Pagination
-  Feeds       → Infinite scroll
+### SearchInput
 
-Never mix patterns within the same view.
-```
+**Applies to: `SearchInput`**
 
-### Pattern 6 — Loading state
+Search and filter interactions.
 
-```
-Shape of loading content known?
-  Yes → Skeleton loading
-  No  → Spinner
+- **Bordered**: standard, full border
+- **Borderless**: inline in toolbars/headers
+- Always include clear (×) button when field has value.
+- `Error` state is for system errors (service unavailable) — NOT for "no results".
+- "No results" → show empty state in results area, not an input error.
 
-Scope?
-  Full page navigation          → Loading bar
-  Full page/panel content       → Skeleton or Spinner (xl/xxl)
-  Section/card within page      → Skeleton or Spinner (lg)
-  Inline within a button        → Spinner (sm), button disabled
-  Background (user not waiting) → No indicator; Toast on completion
+```tsx
+<input type="search" />
+<button aria-label="Clear search">×</button>
 ```
 
-### Pattern 7 — Overlay
+---
 
-```
-User must act before continuing?
-  Yes:
-    Critical/destructive confirmation → Alert dialog
-    Other task or form               → Modal
-  No:
-    Content anchored to an element?
-      Yes → Popover (rich) or Tooltip (plain text, 1 line)
-      No  → Toast (notification) or Drawer (extended task)
-```
+### PasswordInput
 
-### Pattern 8 — Empty state
+**Applies to: `PasswordInput`**
 
-```
-Context size?
-  Primary page content area → lg (illustration + title + description + CTA)
-  Card/panel/section        → sm (icon + title + description + CTA)
+- Always include show/hide toggle.
+- Show strength indicator + requirements list for new passwords.
+- Validate confirm password on blur of confirm field only.
+- `Revealed` state: type switches from `password` to `text`.
 
-Cause?
-  First use (nothing created yet)  → Invite. CTA to create first item.
-  Filtered empty (no results)      → "No results for '[query]'" + Clear filters CTA
-  Permission restricted            → Explain restriction + contact admin
-  Error (failed to load)           → See Error pattern; Retry CTA
+```tsx
+<input type="password" autocomplete="current-password" />
+// or new-password for registration
+<button aria-label="Show password" /> // toggles to "Hide password"
 ```
 
-### Pattern 9 — Error
+---
 
-```
-Error scope?
-  Single form field                 → Inline validation message
-  Section within a page             → Error pattern (inline, embedded)
-  Entire page/flow blocked          → Error screen (full-screen replacement)
-```
+### OTPInput
 
-### Pattern 10 — Success feedback
+**Applies to: `OTPInput`**
 
-```
-Action significance?
-  Routine (save, update, delete)    → Toast (Success, auto-dismiss 4–5s)
-  Significant milestone/flow end    → Success screen (Celebration or Confirmation)
-```
+- Auto-advance: entering a character moves focus to next field.
+- Auto-submit: when last field filled (fixed length), trigger verification automatically.
+- Paste handling: full code must populate all fields at once.
+- Backspace: moves focus to previous field and clears it.
 
-### Pattern 11 — Tabs vs Segment control (use both tests)
+States: `Empty` · `Partially filled` · `Verifying` · `Correct` · `Error` · `Disabled`
 
-1. Does each option have a distinct content panel? → **Tabs**
-2. Does switching change how the same content is rendered? → **Segment control**
-3. Could each option exist as its own sub-page/route? → **Tabs**
-4. Is this a display preference, not an architectural division? → **Segment control**
+```tsx
+<div role="group" aria-label="Enter 6-digit verification code">
+  <input aria-label="Digit 1 of 6" />
+  <input aria-label="Digit 2 of 6" />
+  ...
+</div>
+// Verifying state: aria-live announcement
+// Correct/Error states: must be announced
+```
 
 ---
 
-## Navigation & Page Structure Rules
+### NumberInput
 
-These rules define how pages are structured, how navigation behaves, and where
-actions are placed. They apply to every screen built with DS-Nagarro components.
-Apply these BEFORE selecting or placing any component.
+**Applies to: `NumberInput`**
+
+- Always define and enforce min/max where applicable.
+- Stepper buttons disable at boundaries.
+- Always allow direct keyboard entry (steppers are not the only input method).
+- Do NOT use for currency, ranges (use Slider), or large numeric IDs.
 
 ---
 
-### NAV-01: AppShell is mandatory
-Every page MUST use `AppShell` as its root layout component.
-Never build page layout manually with divs.
-✅ `<AppShell header={...} sidebar={...}>...</AppShell>`
-❌ `<div style={{ display: 'flex' }}>...</div>`
+### PhoneInput
 
----
+**Applies to: `PhoneInput`**
 
-### NAV-02: Sidebar structure
-The Sidebar always follows this exact structure — top to bottom:
-1. **Workspace switcher** — top of sidebar
-2. **Main navigation items** — middle (product-specific)
-3. **User profile + Settings** — bottom of sidebar
+- Always use `PhoneInput` for international phone numbers (not a plain TextInput).
+- Pre-select user's locale as default country code.
+- Allow paste of full international number — auto-populate country selector and number field.
+- Uses `PopoverWrapper` for dropdown (do not re-implement positioning).
 
-Never deviate from this order. Never place navigation items above the workspace switcher.
+```tsx
+<div role="group" aria-label="Phone number">
+  <select aria-label="Country code" autocomplete="tel-country-code" />
+  <input aria-label="Phone number" autocomplete="tel" />
+</div>
+```
 
 ---
 
-### NAV-03: Back arrows — top-level pages
-NEVER show back/forward navigation arrows in the Navbar on top-level section pages.
-Top-level pages are direct sidebar navigation items (e.g. Users, Reports, Pipeline).
-✅ Users page → no back arrow
-✅ Reports page → no back arrow
-❌ Users page → back arrow shown
+### Select
 
----
+**Applies to: `Select`**
 
-### NAV-04: Back arrows — detail views
-ONLY show back arrow in Navbar when the user has navigated INTO a detail view
-(i.e. a record, sub-page, or child of a top-level section).
-✅ Alice Johnson's profile page → show back arrow
-✅ Report detail page → show back arrow
-❌ Top-level Users list → no back arrow
+- Use for single-value selection from a fixed list when 7+ options or space-constrained.
+- Do NOT use for ≤6 options with space → use Radio instead.
+- Always include a placeholder option that is NOT a valid value.
+- Add search/filter within dropdown for 20+ options.
+
+```tsx
+// Native when possible
+<select aria-required={required} aria-invalid={hasError}>
+  <option value="">Select country</option>
+</select>
+
+// Custom implementation
+<div role="combobox" aria-expanded={open} aria-haspopup="listbox" aria-controls="list">
+<div id="list" role="listbox">
+  <div role="option" aria-selected="true">Portugal</div>
+</div>
+```
 
 ---
 
-### NAV-05: Navbar title — two modes
+### AutocompleteMulti
 
-**Mode 1 — Top-level page:**
-Show plain section title in the Navbar. No breadcrumbs.
-✅ Navbar: "Users"
-✅ Navbar: "Reports"
+**Applies to: `AutocompleteMulti`**
 
-**Mode 2 — Detail view (2+ levels deep):**
-Show large `Breadcrumbs` component in the Navbar INSTEAD of a plain title.
-The breadcrumb IS the title — do not show both.
-The current page name (rightmost item) is bold and non-interactive.
-Parent items are interactive links.
+- Search-and-select multiple values from large/dynamic lists.
+- Each selected value becomes a chip inside the input.
+- Backspace on empty field removes last chip.
 
-✅ Navbar breadcrumb: "Users > **Alice Johnson**"
-❌ Navbar title: "Alice Johnson" + separate breadcrumb below it
-❌ Navbar title: "Users" when inside Alice Johnson's page
+```tsx
+<div role="combobox" aria-multiselectable="true" aria-expanded={open}>
+<button aria-label="Remove Portugal">×</button>
+<div role="listbox">
+  <div role="option" aria-selected="true">Portugal</div>
+</div>
+// Chip add/remove: aria-live="polite"
+```
 
 ---
 
-### NAV-06: Breadcrumb variants — two levels
+### HorizontalInput
 
-There are two breadcrumb sizes and they serve different purposes:
+**Applies to: `HorizontalInput`**
 
-| Variant | Where | Purpose |
-|---|---|---|
-| **Large** (`BreadcrumbsController`) | Navbar | Main navigation hierarchy — replaces page title on detail views |
-| **Small** (`Breadcrumbs`) | Inside page content | Sub-section hierarchy within a detail page |
+- Label left, control right — layout wrapper only.
+- Use in dense settings panels, property editors.
+- Do NOT use in standard forms, mobile layouts, or with long labels.
+- Label must not wrap — keep to 3–4 words maximum.
+- Consistent label widths within a group.
 
-NEVER use small breadcrumbs for main navigation.
-NEVER use large breadcrumbs inside content areas.
+---
 
-✅ Navbar: large breadcrumb "Users > Alice Johnson"
-✅ Inside content: small breadcrumb "Permissions > Edit role"
-❌ Navbar: small breadcrumb
-❌ Content area: large breadcrumb
+### Slider
 
----
+**Applies to: `Slider`**
 
-### NAV-07: Breadcrumb format
-Format: `[Parent section] > [Current page]`
-- Parent items: interactive links
-- Current page (rightmost): non-interactive, visually bold
-- Do NOT always prepend root/Home — start from the immediate meaningful parent
-- Never truncate the current page item
+- `Max value` type: one handle
+- `Range` type: two handles — prevent handles from crossing
+- Always show current value alongside handle (tooltip or persistent label).
+- Display min/max labels at track ends.
+- Pair with NumberInput when precision matters.
 
-✅ "Users > Alice Johnson"
-✅ "Reports > Q4 2025"
-❌ "Home > Users > Alice Johnson" (unnecessary root)
-❌ "Alice Johnson" alone (missing parent context)
+```tsx
+<div aria-label="Price range" aria-labelledby="slider-label">
+  <input role="slider"
+    aria-valuenow={120} aria-valuemin={0} aria-valuemax={500}
+    aria-valuetext="€120"
+    aria-label="Minimum price" />
+</div>
+// Arrow keys: ±1 step
+// Page Up/Down: larger increment
+// Home/End: jump to min/max
+```
 
 ---
 
-### NAV-08: Primary CTA placement — top-level pages
-The primary action for a section always sits in the Navbar, to the right of the title.
-NEVER place the primary CTA inside a Card header or content area on a top-level page.
+### UploadArea
 
-Primary actions are object-creation actions:
-"New user", "New deal", "Create report", "New email"
+**Applies to: `UploadArea`**
 
-✅ Navbar: "Users" + [New user — Primary button]
-❌ Card header: [New user — Primary button] on a top-level page
+- Always provide click-to-browse fallback (not all users can drag-drop).
+- State accepted file types and size limits in Empty state.
+- Reject invalid file types immediately on drop with clear error.
+- Show upload progress after file accepted.
+
+```tsx
+<div role="button" aria-label="Upload files — click or drag and drop"
+  aria-describedby="upload-constraints" tabIndex={0}>
+// Enter/Space when focused: opens system file picker
+// Dropping state: aria-live announcement
+```
 
 ---
 
-### NAV-09: CTA hierarchy in Navbar
-When a page has multiple actions, use this hierarchy in the Navbar (right side):
+### ChipsInput
 
-| Action type | Button variant | Example |
-|---|---|---|
-| Primary object creation | `Primary` | "New deal", "New user" |
-| Important but not primary | `Secondary` | "Import", "Publish" |
-| Utility / contextual actions | `Ghost` | "Share", "Edit", "Export" |
+**Applies to: `ChipsInput`**
 
-Order right-to-left by importance: Ghost → Secondary → Primary
-(Primary is always the rightmost — trailing edge)
+- Free-form entry where each value becomes a chip.
+- Confirm with `Enter` (or comma/Tab as defined per product).
+- Validate each value before converting to chip.
+- Backspace on empty field removes last chip.
 
-✅ [Export — Ghost] [Share — Ghost] [Edit — Secondary] [New user — Primary]
-❌ [New user — Primary] [Share — Ghost] (wrong order)
-❌ Two Primary buttons in the same Navbar
+```tsx
+// Each chip remove button
+<button aria-label="Remove javascript">×</button>
+// Chip additions/removals
+aria-live="polite"
+```
 
 ---
 
-### NAV-10: Child section CTAs
-When a detail page has sub-sections with their own primary actions,
-those actions belong at the sub-section level — NOT in the top Navbar.
+### DatePicker / DateRangePicker
 
-✅ Alice Johnson page → Navbar: [Save changes — Primary]
-✅ Alice Johnson > Permissions tab → tab-level: [Add permission — Primary]
-❌ Alice Johnson page → Navbar has both "Save changes" AND "Add permission"
+**Applies to: `DateTimePicker`**
 
----
+- `Single date`: selects one date
+- `Date range`: start + end date — start cannot be after end
 
-### NAV-11: Section headers inside content
-Use the `SectionHeader` component to divide content sections within a page.
-Section headers are standalone dividers — they do NOT need to be inside a Card.
-Description line is optional — use it when the section needs clarification,
-omit it when the title is self-explanatory.
+#### Display modes
+- **Standalone**: always visible
+- **Popover**: triggered by clicking input field (uses `PopoverWrapper`)
 
-✅ SectionHeader "Personal info" (no description needed)
-✅ SectionHeader "Permissions" + description "Control what this user can access"
-❌ Wrapping every section in a Card just to have a title
-❌ Using plain `<h2>` or `<h3>` instead of SectionHeader component
+#### Rules
+- Show human-readable format in trigger input: "15 Jan 2026" not "2026-01-15"
+- Communicate date constraints before user opens calendar, not just inside it
+- For range: show both months side by side when range spans months
+- Do NOT pre-select today for historical date entry (e.g. date of birth)
 
----
+```tsx
+<input aria-haspopup="dialog" aria-expanded={open} />
+<div role="dialog" aria-label="Choose date range">
+  <div role="grid">
+    <div role="gridcell" aria-label="Monday, 15 January 2026" aria-selected="true" tabIndex={0} />
+    <div role="gridcell" aria-label="Tuesday, 16 January 2026" aria-disabled="true" tabIndex={-1} />
+  </div>
+  <button aria-label="Previous month">‹</button>
+  <button aria-label="Next month">›</button>
+</div>
+// Arrow keys: move between days
+// Enter: select day
+// Page Up/Down: navigate months
+// Home/End: first/last day of month
+// Single tabbable day with roving focus — not one tabstop per cell
+```
 
-### NAV-12: Page title and section header casing
-ALL page titles, Navbar titles, breadcrumb items, and section headers use sentence case.
-NEVER title case.
+---
 
-✅ "Personal info", "New user", "Alice Johnson", "Save changes"
-❌ "Personal Info", "New User", "Save Changes"
+### Spinner
 
----
+**Applies to: `Spinner`**
 
-### NAV-13: Cards vs sections
-Not every content group needs a Card.
-Use a Card when the content is a distinct, self-contained unit that benefits
-from visual elevation or grouping (e.g. a data table, a form block, a summary panel).
-Use SectionHeader + flat content when sections are part of a continuous page flow.
+- Use when operation is in progress and duration is unknown.
+- Sizes: `sm` (inline button) · `lg` (panels) · `xl` (page sections) · `xxl` (full-page)
+- Always pair with a label when standalone: "Loading…", "Saving…"
+- Do NOT use multiple spinners simultaneously — consolidate into one.
 
-✅ DataTable inside a Card
-✅ SectionHeader "Personal info" → flat form fields below (no Card)
-❌ Every section wrapped in a Card by default
+```tsx
+<div role="status" aria-label="Loading results">
+  <svg aria-hidden="true" />
+</div>
+// Completion: aria-live="polite"
+```
 
 ---
 
-## Layout & Component Behavior Rules
-
-These rules apply globally. Apply them before building any screen or component.
+### SkeletonLoading
 
----
+**Applies to: `SkeletonLoading`**
 
-### LCB-01: AppShell scroll — only the content area scrolls
-The sidebar and navbar are always fixed. Only the main content area scrolls.
-Never apply scroll to the full page or the AppShell root.
+- Use when content takes >~300ms to load and shape is known.
+- Types: `Avatar` · `Pill` · `Image` · `Card`
+- Always animate (shimmer/pulse) — never show static skeleton shapes.
+- Replace all skeletons simultaneously when content is ready — no piecemeal replacement.
 
-✅ `<AppShell>` — sidebar and navbar fixed; content area overflows and scrolls independently
-❌ Full page scrolls, taking the sidebar and navbar with it
+```tsx
+<div aria-busy="true" aria-label="Loading">
+  <div aria-hidden="true" class="skeleton-avatar" />
+  <div aria-hidden="true" class="skeleton-pill" />
+</div>
+// When content ready: aria-busy="false"
+```
 
 ---
 
-### LCB-02: Data visualisation — always use dataviz tokens
-All charts, graphs, and data visualisations must use `--color-dataviz-*` tokens from `tokens.css` for all colors (series, axes, labels, backgrounds).
-Never use hardcoded hex values or generic semantic tokens for dataviz color.
-
-✅ `fill: var(--color-dataviz-1)`
-❌ `fill: #0F766E`
-❌ `fill: var(--background-accent)`
+### ProgressBar / LoadingBar
 
----
+**Applies to: `ProgressBar`, `LoadingBar`**
 
-### LCB-03: Horizontal spacing — always use `--page-margin-x`
-All horizontal spacing in the content area must use `var(--page-margin-x)`.
-This applies to every container without exception: pages, cards, modals, drawers, tables, lists, and form sections.
-Never introduce independent `padding-left`, `padding-right`, `margin-left`, or `margin-right` values that deviate from this token.
+- `LoadingBar`: page-level navigation only, top of viewport. Never inline.
+- `ProgressBar`: measured progress (file upload, onboarding). Always show percentage or step count alongside bar.
 
-✅ `padding-inline: var(--page-margin-x)` on content areas, modals, drawers, cards
-❌ `padding: 24px` or `margin: 0 16px` hardcoded on any container
-❌ Different horizontal spacing values across containers causing misalignment
+```tsx
+<div role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={60}
+  aria-label="Uploading file" />
+// Completion: aria-live="polite"
+```
 
 ---
 
-### LCB-04: Card internal padding — content must never touch card edges
-Every card must apply internal padding using the correct inset token.
-Content must never touch the card border.
+### Scrollbar
 
-✅ `padding: var(--inset-large)` inside every card
-❌ Card content flush with card edges
+**Applies to: `Scrollbar`**
+
+- Never hide scrollbar entirely in scrollable areas.
+- Do not use both vertical and horizontal scrollbars on same container unless content is truly 2D.
+- Custom scrollbars are visual overlays only — underlying scroll must remain keyboard accessible.
+
+```tsx
+// Scrollable container
+<div tabIndex={0} />  // allows keyboard focus and arrow key scrolling
+```
 
 ---
 
-### LCB-05: Icons — always use Lucide, never system icons
-The only permitted icon library is Lucide (`lucide-react`).
-Never use browser/OS-native icons, emoji, or icons from any other library.
-This applies everywhere: tables, buttons, inputs, menus, empty states, and all other components.
+### Shortcut
 
-✅ `import { ArrowUpDown } from 'lucide-react'`
-❌ System sort icon (↕) in table column headers
-❌ Any icon not from the Lucide library
+**Applies to: `Shortcut`**
+
+- Non-interactive display element only.
+- Sizes: `sm` (tooltips/menus) · `md` (standalone/help panels)
+- Colors: `Default` (light BG) · `Inverted` (dark BG)
+- Use platform-standard notation. Detect platform — do not mix Mac/Windows symbols.
+- Keep to keys only: `⌘S` not `⌘ Save`
+
+```tsx
+// Key symbols not reliably announced by screen readers
+<kbd aria-label="Command S">⌘S</kbd>
+```
 
 ---
 
-### LCB-06: List items — always stretch to full container width
-List items inside any container (modal, drawer, card, page section) must stretch to fill the full available width.
-Never let list items float at an arbitrary width or leave unexplained whitespace to the right.
+## Cross-component patterns
 
-✅ List item `width: 100%` of container (minus `--page-margin-x` padding)
-❌ List items sized to content, leaving empty space on the right
+These patterns are **decision rules**. Apply before selecting a component.
 
----
+### Pattern 1 — Single select
 
-### LCB-07: Placeholder content — never leave it in place
-Component slots for icons, help text, and hint icons must never contain placeholder values.
-Either replace with real, meaningful content or hide the slot entirely.
+```
+Does selection require explicit confirmation?
+  Yes → Radio (regardless of option count)
+  No → How many options?
+    2–3 → Segment control
+    4+  → Select
 
-This applies to:
-- **Icons** inside inputs, selects, and buttons → replace with a relevant Lucide icon, or hide
-- **Help text** → replace with genuinely useful guidance, or hide
-- **Help/hint icons** → replace with meaningful tooltip content, or hide
+Select has 20+ items?
+  Yes → add search box inside dropdown
+```
 
-✅ Help text: "We'll use this to send you login notifications."
-✅ Icon slot hidden when no meaningful icon applies
-❌ Help text reads "Help text"
-❌ Placeholder diamond icon left inside a Select component
+### Pattern 2 — Multi select
 
----
+```
+How many options?
+  Up to 3 → Chips (shown upfront, immediately toggleable)
+  4+      → Select dropdown + Choice list (Checkbox variant)
 
-### LCB-08: Required fields — use "Optional" label, not asterisk
-Every form field is mandatory by default.
-Never use a red asterisk (`*`) to mark required fields.
-Only mark optional fields, using an "Optional" label styled in `var(--text-tertiary)`, placed inline after the field label.
+Option set is large (20+), dynamic, or needs typing to find?
+  → Autocomplete multi
+```
+
+### Pattern 3 — Binary (on/off)
+
+```
+Context?
+  Toolbar, icon-only, immediate → Toggle button (+ mandatory Tooltip)
+  Form, deferred, confirmed on submit → Checkbox
+  Settings, labeled, immediate → Switcher
+```
 
-✅ `Team <span style="color: var(--text-tertiary)">Optional</span>`
-✅ Fields with no qualifier → assumed mandatory
-❌ `First name *` with a red asterisk
-❌ `aria-required="true"` shown visually as an asterisk
+### Pattern 4 — Filter bar
 
----
+```
+How many filter values?
+  1         → Toggle button
+  2–5       → Chips in a horizontal bar
+  6+        → "Filters" button → dropdown (6–12) or drawer (13+)
 
-### LCB-09: Form CTA — disabled until mandatory fields have a value
-The primary submit button in any form (modal, drawer, page) must be disabled until all mandatory fields contain a value.
-On submit, validate all fields and display all errors simultaneously.
-Do not validate in real time as the user types — only on submit attempt.
+Always: show active state, provide "Clear all" action when any filter active
+```
 
-Exceptions where real-time validation is acceptable: password strength, character count limits, search/filter fields, OTP.
+### Pattern 5 — Pagination vs Infinite scroll
 
-✅ Primary CTA disabled → user fills all mandatory fields → button enables → submit → validate all
-❌ Primary CTA active on an empty form
-❌ Inline errors appearing as the user types in a standard form field
+```
+Content type?
+  Data tables → Pagination
+  Feeds       → Infinite scroll
 
----
+Never mix patterns within the same view.
+```
 
-### LCB-10: Form submit keyboard shortcut — always show `⌘↵` on primary CTA
-The primary action button in every form must display the `⌘↵` keyboard shortcut hint using the `Shortcut` component.
-`Cmd+Enter` is the standard submit shortcut across all forms.
+### Pattern 6 — Loading state
 
-✅ `<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>`
-❌ Primary form button with no keyboard shortcut hint
+```
+Shape of loading content known?
+  Yes → Skeleton loading
+  No  → Spinner
 
----
+Scope?
+  Full page navigation          → Loading bar
+  Full page/panel content       → Skeleton or Spinner (xl/xxl)
+  Section/card within page      → Skeleton or Spinner (lg)
+  Inline within a button        → Spinner (sm), button disabled
+  Background (user not waiting) → No indicator; Toast on completion
+```
 
-### Tag semantic color mapping
+### Pattern 7 — Overlay
 
-Always match Tag variant to the semantic meaning of the value. Never use the 
-same variant for all tags in a list.
+```
+User must act before continuing?
+  Yes:
+    Critical/destructive confirmation → Alert dialog
+    Other task or form               → Modal
+  No:
+    Content anchored to an element?
+      Yes → Popover (rich) or Tooltip (plain text, 1 line)
+      No  → Toast (notification) or Drawer (extended task)
+```
 
-| Value meaning              | Tag variant  |
-|---------------------------|--------------|
-| Done, active, on track, success, approved, complete | success |
-| At risk, pending, in review, in progress, waiting   | warning |
-| Behind, blocked, failed, rejected, overdue, error   | error   |
-| Draft, inactive, unknown, archived, neutral         | neutral |
-| Informational, new, upcoming                        | info    |
+### Pattern 8 — Empty state
 
-When in doubt, ask: is this good, bad, cautionary, or neutral? 
-Pick the variant that matches that meaning.
+```
+Context size?
+  Primary page content area → lg (illustration + title + description + CTA)
+  Card/panel/section        → sm (icon + title + description + CTA)
 
----
+Cause?
+  First use (nothing created yet)  → Invite. CTA to create first item.
+  Filtered empty (no results)      → "No results for '[query]'" + Clear filters CTA
+  Permission restricted            → Explain restriction + contact admin
+  Error (failed to load)           → See Error pattern; Retry CTA
+```
 
-### Page margin application
+### Pattern 9 — Error
 
-The content area must always have horizontal breathing room. Apply 
-var(--page-margin-x) as padding-inline on the direct child of the content area — 
-not on individual components.
+```
+Error scope?
+  Single form field                 → Inline validation message
+  Section within a page             → Error pattern (inline, embedded)
+  Entire page/flow blocked          → Error screen (full-screen replacement)
+```
 
-/* CORRECT */
-.page-content {
-  padding-inline: var(--page-margin-x);
-}
+### Pattern 10 — Success feedback
 
-/* WRONG */
-.page-content {
-  padding: 0; /* flush to edges */
-}
+```
+Action significance?
+  Routine (save, update, delete)    → Toast (Success, auto-dismiss 4–5s)
+  Significant milestone/flow end    → Success screen (Celebration or Confirmation)
+```
 
-This applies to every page without exception: tables, cards, charts, lists, 
-empty states. Nothing should ever touch the left or right edge of the content area.
+### Pattern 11 — Tabs vs Segment control (use both tests)
+
+1. Does each option have a distinct content panel? → **Tabs**
+2. Does switching change how the same content is rendered? → **Segment control**
+3. Could each option exist as its own sub-page/route? → **Tabs**
+4. Is this a display preference, not an architectural division? → **Segment control**
 
 ---
 
@@ -1972,160 +2131,5 @@ export const DisabledVariant: Story = {
 
 ---
 
-*Generated from DS-Nagarro design system docs. Last updated: 2026-03-10.*
-*Source files: `docs/foundations.md`, `docs/ds-guidelines.md`, and all component docs in `docs/`.*
-
----
-
----
-
-## Consuming the Package — Layout & Navigation
-
-> This section is for AI agents building apps with `@ngrr/ds`, not for building the library itself.
-
-### Setup — mandatory CSS imports
-```tsx
-// main.tsx — must be first, before any other imports
-import '@ngrr/ds/style.css'
-import '@ngrr/ds/tokens.css'
-```
-
-### Required CSS on the host app
-```css
-html, body { margin: 0; height: 100%; }
-#root { min-height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
-```
-
----
-
-### AppShell — mandatory root layout
-
-`AppShell` is the only permitted root layout wrapper. Every page must be inside it. Do not invent wrapper divs or custom layouts.
-```tsx
-import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
-// Icons come from lucide-react — install separately: npm install lucide-react
-import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings } from 'lucide-react';
-
-<AppShell
-  header={
-    <Navbar
-      title="Dashboard"
-      rightActions={<Button variant="primary" label="New project" />}
-    />
-  }
-  sidebar={
-    <Sidebar
-      selectorProps={{
-        label: 'WorkScope',
-        avatarProps: {
-          size: 'xs',
-          variant: 'organization',
-          fill: 'initials',
-          initials: 'WS',
-          name: 'WorkScope',
-        },
-      }}
-      showSearch
-      searchSlot={<SearchBar placeholder="Search" />}
-      sections={[
-        {
-          id: 'main',
-          items: [
-            { id: 'dashboard', label: 'Dashboard', icon: <LayoutDashboard size={16} />, selected: true, onClick: () => {} },
-            { id: 'projects', label: 'Projects', icon: <FolderKanban size={16} />, onClick: () => {} },
-            { id: 'tasks', label: 'Tasks', icon: <CheckSquare size={16} />, onClick: () => {} },
-            { id: 'people', label: 'People', icon: <Users size={16} />, onClick: () => {} },
-            { id: 'notes', label: 'Notes', icon: <FileText size={16} />, onClick: () => {} },
-          ],
-        },
-      ]}
-      bottomContent={
-        <>
-          <SidebarMenuSelector
-            variant="full"
-            label="Settings"
-            showIcon
-            icon={<Settings size={16} />}
-            onClick={() => {}}
-          />
-          <SidebarMenuSelector
-            variant="full"
-            label="User Name"
-            showAvatar
-            avatarProps={{ size: 'xs', fill: 'initials', initials: 'UN', name: 'User Name' }}
-            onClick={() => {}}
-          />
-        </>
-      }
-    />
-  }
->
-  {/* page content goes here */}
-</AppShell>
-```
-
-**AppShell props:**
-- `header` — `<Navbar />` only
-- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically
-- `children` — main page content
-- `rightPanel` — optional, omit if not needed
-- `footer` — optional, omit if not needed
-
-**Forbidden:**
-- Do not wrap AppShell in any other layout element
-- Do not add sidebar items beyond what is specified
-- Do not invent extra sections, items, or nav elements
-
----
-
-### Navbar props
-- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
-- `title` — page title, sentence case
-- `rightActions` — primary CTA button, rightmost position
-- `leftActions` — secondary actions on the left, omit if not needed
-- `onBackClick` — only used with `variant="breadcrumbs"`
-- `breadcrumbItems` — required only when `variant="breadcrumbs"`
-
-**Rules:**
-- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes)
-- Back arrow only on detail views using `variant="breadcrumbs"`
-- Primary CTA always in `rightActions`
-
----
-
-### Sidebar props
-- `sections` — required. Only include sections explicitly specified. Never invent extra items.
-- `selectorProps` — workspace selector at the top. Always set `label` and `avatarProps`.
-- `showSearch` — set to `true` to show the search bar
-- `searchSlot` — pass a `<SearchBar />` component when `showSearch` is true
-- `bottomContent` — use for Settings and User Name, pinned to bottom with a divider. Always include these two items.
-- Never pass `collapsed` — AppShell controls it automatically
-
-**SidebarMenuItem shape:**
-```ts
-{
-  id: string;
-  label: string;           // sentence case always
-  icon?: React.ReactNode;  // lucide-react icon at size={16}
-  selected?: boolean;      // true only for the active page
-  onClick?: () => void;
-  showBadge?: boolean;
-  badgeCount?: number;
-  badgeVariant?: BadgeVariant;
-  showAvatar?: boolean;
-  avatarProps?: AvatarProps;
-}
-```
-
----
-
-### Hard rules — always follow
-- `AppShell` is always the root — no exceptions
-- `DataTable` must never be wrapped in a `Card`
-- No back arrow on top-level pages: Dashboard, Projects, Tasks, People, Notes
-- CTA hierarchy: Primary (object creation, rightmost in Navbar) → Secondary → Ghost (Export, Share, Edit)
-- All labels and copy: sentence case always ("New project" not "New Project")
-- Icons: from `lucide-react` — install with `npm install lucide-react`
-- Tag variants: `success` = completed, `progress` = in progress, `warning` = at risk, `neutral` = not started
-- Settings and User Name always pinned to sidebar bottom via `bottomContent`
-- Sidebar always full viewport height — guaranteed by AppShell CSS rules above
+*Single source of truth for consuming DS-Nagarro. Last updated: 2026-03-16.*
+*Source files: `docs/foundations.md`, `docs/ds-guidelines.md`, and all component docs in `docs/`.*