@ngrr/ds 0.1.4 → 0.1.6

package/AI.md

@@ -0,0 +1,1976 @@
+# DS-Nagarro — AI Agent Rules
+
+> **Single source of truth for AI agents generating code for this design system.**
+> 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.
+
+---
+
+## 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)`.
+
+---
+
+## Token System Rules
+
+These rules apply globally to every component.
+
+### Three-tier model — always resolve through this chain
+
+```
+Primitives (raw) → Semantic (intent) → Component (usage)
+```
+
+- **Use semantic tokens** in all component code. `var(--color-text-primary)` ✅ — `var(--primitive-neutral-900)` ❌
+- **Component tokens** (`var(--color-surface-button-*)`): use these for component-specific overrides; they exist for a reason.
+- **Never hardcode** hex codes, pixel values, or rgba. Everything comes from tokens.
+
+### Token families and their CSS properties
+
+| Token family | CSS property |
+|---|---|
+| `--color-text-*` | `color` |
+| `--background-*` | `background-color` |
+| `--borders-*` | `border-color`, `outline-color` |
+| `--color-surface-*` | `background-color` (component-level) |
+| `--font-size-*`, `--font-weight-*`, `--font-line-height-*` | typography |
+| `--space-*` | `gap`, `margin` (between elements) |
+| `--inset-*` | `padding` (inside components) |
+| `--radius-*` | `border-radius` |
+| `--border-width-*` | `border-width` |
+| `--effects-elevation-*` | `box-shadow` |
+| `--transition-*` | `transition` |
+
+### Space vs Inset — never mix
+
+- `space/*` → gaps **between** elements (gap, margin)
+- `inset/*` → padding **inside** a component
+
+✅ `gap: var(--space-standard)` between items
+✅ `padding: var(--inset-standard)` inside a button
+❌ `gap: var(--inset-standard)` — wrong scale for context
+
+### State name convention
+
+Always use these exact identifiers. Never use `base`, `normal`, or `rest`.
+
+| State | Suffix |
+|---|---|
+| Resting | `default` |
+| Pointer over | `hover` |
+| Mouse pressed | `pressed` |
+| Keyboard focused | `focused` |
+| Non-interactive | `disabled` |
+| Active selection | `selected` (boolean prop, not state variant) |
+| Error | `error` |
+| Success | `success` |
+
+### Size naming convention
+
+| Figma name | Prop value |
+|---|---|
+| Small | `sm` |
+| Medium | `md` |
+| Large | `lg` |
+| xLarge | `xl` |
+| xxLarge | `2xl` |
+
+`md` is always the default. When no size specified, generate with `md`.
+
+---
+
+## Component Usage Rules
+
+---
+
+### Button
+
+**Applies to: `Button` (Main, Destructive, Toggle, Vertical)**
+
+#### When to use
+
+- **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.
+
+#### 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
+
+#### 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
+<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"
+
+---
+
+### Avatar / AvatarGroup
+
+**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.
+
+#### Variants
+- `Profile`: individual person
+- `Organization`: company/team
+- Never mix Profile and Organization in the same list without clear reason.
+
+#### 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
+// 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.
+
+---
+
+### Badge
+
+**Applies to: `Badge`**
+
+#### 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**
+
+#### 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
+```
+
+---
+
+### 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
+
+#### 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
+// Include tag content in accessible name of parent
+<li aria-describedby="tag-status">
+  <span id="tag-status" role="status">Error</span>
+```
+
+---
+
+### 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.
+
+#### Do NOT use when
+- Purely informational → use Tag
+- Mutually exclusive form selection → use Radio
+- Multi-option form selection → use Checkbox
+- Settings toggle → use Switcher
+
+#### Sizes
+- `md`: default
+- `sm`: compact layouts
+
+Never mix `md` and `sm` in the same chip group.
+
+#### 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
+// 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>
+
+// 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" />
+
+// Disabled chip
+aria-disabled="true"  // keep in reading order
+```
+
+---
+
+### Separator
+
+**Applies to: `Separator`**
+
+#### When to use
+- Visual divider between content sections that are related but distinct.
+
+#### Do NOT use when
+- Adequate spacing already separates sections
+- Sections are already separated by color/card borders
+- Purpose is purely decorative
+
+#### 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" />
+
+// Decorative only
+<div aria-hidden="true" />
+```
+
+---
+
+### Switcher
+
+**Applies to: `Switcher`**
+
+#### When to use
+- Single binary setting, **effect is immediate** (no confirmation step).
+- Enabling features, notification settings, preferences.
+
+#### 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 |
+
+#### Sizes
+- `md`: default
+- `sm`: dense layouts
+
+Never mix sizes within a settings group.
+
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+
+`Selected` and `Disabled` are independent booleans.
+
+#### 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
+
+#### ARIA
+```tsx
+<button role="switch" aria-checked={isOn} aria-labelledby="label-id" />
+// Disabled
+aria-disabled="true"  // keep in reading order
+```
+
+---
+
+### Checkbox
+
+**Applies to: `Checkbox`**
+
+#### When to use
+- User selects any number of independent options (zero to all).
+- Selection takes effect only after **explicit confirmation** (submit button).
+
+#### 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
+
+Never mix sizes in a single form group.
+
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+
+**Indeterminate state**: when a parent checkbox controls sub-items with partial selection.
+
+#### Interaction
+- Click on checkbox **or its label** toggles selection (full row is hit target).
+- State changes are staged — not immediate.
+
+#### ARIA
+```tsx
+<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"
+```
+
+---
+
+### Radio
+
+**Applies to: `Radio`**
+
+#### When to use
+- Exactly one option from a mutually exclusive set.
+- All options visible simultaneously (2–6 items).
+- Effect takes place after **explicit confirmation**.
+
+#### 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
+
+Never mix sizes within a radio group.
+
+#### States
+`Default` · `Hover` · `Pressed` · `Focused` · `Disabled`
+
+No indeterminate state for Radio. A group always has 0–1 selected.
+
+#### 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="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
+```
+
+---
+
+### Tab / CustomViewTab
+
+**Applies to: `Tab` (Navigation, Custom View)**
+
+#### 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
+
+#### 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) |
+
+#### 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.
+
+#### Keyboard
+- `Tab` → focus tab row
+- `←` `→` → move between tabs
+- `Enter` / `Space` → select focused tab
+- `Tab` → move into content panel
+
+#### 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"
+```
+
+---
+
+### SegmentControl
+
+**Applies to: `SegmentControl`, `SegmentControlSelector`**
+
+#### 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"
+
+#### 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
+
+#### 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
+```
+
+---
+
+### Breadcrumbs / BreadcrumbItem
+
+**Applies to: `Breadcrumbs`, `BreadcrumbItem`**
+
+#### 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
+<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>
+```
+
+---
+
+### Pagination / PageSelector
+
+**Applies to: `Pagination`, `PageSelector`**
+
+#### When to use
+- Large dataset divided into pages where user benefits from explicit navigation.
+- Data tables, search results, record lists.
+
+#### 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
+
+#### 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
+<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
+```
+
+---
+
+### Toast (Inline, Rich)
+
+**Applies to: `Toast`**
+
+#### When to use
+- Confirm a completed action or surface a system event without interrupting the current task.
+- Non-blocking. Temporary.
+
+#### 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.
+
+#### 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** |
+
+#### 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
+
+Always provide a manual dismiss (×) button.
+Pause auto-dismiss on hover (desktop).
+
+#### 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>
+```
+
+---
+
+### Tooltip
+
+**Applies to: `Tooltip`**
+
+#### When to use
+- Brief supplementary context — hover or keyboard focus only.
+- Label icon-only buttons, reveal truncated text, show keyboard shortcuts.
+
+#### 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
+- 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
+<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
+```
+
+---
+
+### Popover (Container, Simple Menu, Complex Menu)
+
+**Applies to: `Popover`**
+
+#### 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
+
+#### Types
+- **Container**: free-form rich content
+- **Simple menu**: flat list, 2–6 items, no grouping
+- **Complex menu**: grouped, with section headings, scrollable
+
+#### 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.
+
+#### 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
+// 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>
+
+// Container type
+<div role="dialog" aria-label="Filter options">...</div>
+
+// 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
+```
+
+---
+
+### Modal
+
+**Applies to: `Modal`**
+
+#### When to use
+- User must complete a task or make a decision before continuing.
+- Confirmations, compact forms, critical warnings, media previews.
+
+#### 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.
+
+#### 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
+<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>
+```
+
+---
+
+### Input — shared anatomy
+
+**Applies to: all input components**
+
+#### 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`
+
+- `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.
+
+#### 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.
+
+#### 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>
+```
+
+---
+
+### TextInput
+
+**Applies to: `TextInput`**
+
+Single-line free-form text. Use when no more specific input type applies.
+
+Do NOT use for multi-line → TextArea | numbers → NumberInput | passwords → PasswordInput | phone → PhoneInput | search → SearchInput | predefined list → Select.
+
+---
+
+### TextArea
+
+**Applies to: `TextArea`**
+
+Multi-line free-form text.
+
+- Minimum height: 3 lines
+- Allow vertical resize (desktop)
+- Show character count when limit exists: "120 characters remaining" not "380/500"
+
+---
+
+### SearchInput
+
+**Applies to: `SearchInput`**
+
+Search and filter interactions.
+
+- **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.
+
+```tsx
+<input type="search" />
+<button aria-label="Clear search">×</button>
+```
+
+---
+
+### PasswordInput
+
+**Applies to: `PasswordInput`**
+
+- 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`.
+
+```tsx
+<input type="password" autocomplete="current-password" />
+// or new-password for registration
+<button aria-label="Show password" /> // toggles to "Hide password"
+```
+
+---
+
+### OTPInput
+
+**Applies to: `OTPInput`**
+
+- 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.
+
+States: `Empty` · `Partially filled` · `Verifying` · `Correct` · `Error` · `Disabled`
+
+```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
+```
+
+---
+
+### NumberInput
+
+**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.
+
+---
+
+### PhoneInput
+
+**Applies to: `PhoneInput`**
+
+- 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).
+
+```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>
+```
+
+---
+
+### Select
+
+**Applies to: `Select`**
+
+- 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>
+```
+
+---
+
+### AutocompleteMulti
+
+**Applies to: `AutocompleteMulti`**
+
+- 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.
+
+```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"
+```
+
+---
+
+### 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.
+
+---
+
+### Slider
+
+**Applies to: `Slider`**
+
+- `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.
+
+```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
+```
+
+---
+
+### UploadArea
+
+**Applies to: `UploadArea`**
+
+- 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
+```
+
+---
+
+### ChipsInput
+
+**Applies to: `ChipsInput`**
+
+- 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.
+
+```tsx
+// Each chip remove button
+<button aria-label="Remove javascript">×</button>
+// Chip additions/removals
+aria-live="polite"
+```
+
+---
+
+### DatePicker / DateRangePicker
+
+**Applies to: `DateTimePicker`**
+
+- `Single date`: selects one date
+- `Date range`: start + end date — start cannot be after end
+
+#### Display modes
+- **Standalone**: always visible
+- **Popover**: triggered by clicking input field (uses `PopoverWrapper`)
+
+#### 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
+```
+
+---
+
+### Spinner
+
+**Applies to: `Spinner`**
+
+- 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.
+
+```tsx
+<div role="status" aria-label="Loading results">
+  <svg aria-hidden="true" />
+</div>
+// Completion: aria-live="polite"
+```
+
+---
+
+### SkeletonLoading
+
+**Applies to: `SkeletonLoading`**
+
+- 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.
+
+```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"
+```
+
+---
+
+### ProgressBar / LoadingBar
+
+**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.
+
+```tsx
+<div role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={60}
+  aria-label="Uploading file" />
+// Completion: aria-live="polite"
+```
+
+---
+
+### Scrollbar
+
+**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
+```
+
+---
+
+### Shortcut
+
+**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>
+```
+
+---
+
+## Cross-component patterns
+
+These patterns are **decision rules**. Apply before selecting a component.
+
+### Pattern 1 — Single select
+
+```
+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
+
+```
+How many options?
+  Up to 3 → Chips (shown upfront, immediately toggleable)
+  4+      → Select dropdown + Choice list (Checkbox variant)
+
+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
+```
+
+### 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+)
+
+Always: show active state, provide "Clear all" action when any filter active
+```
+
+### Pattern 5 — Pagination vs Infinite scroll
+
+```
+Content type?
+  Data tables → Pagination
+  Feeds       → Infinite scroll
+
+Never mix patterns within the same view.
+```
+
+### Pattern 6 — Loading state
+
+```
+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
+```
+
+### 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)
+```
+
+### Pattern 8 — Empty state
+
+```
+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
+```
+
+### 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)
+```
+
+### Pattern 10 — Success feedback
+
+```
+Action significance?
+  Routine (save, update, delete)    → Toast (Success, auto-dismiss 4–5s)
+  Significant milestone/flow end    → Success screen (Celebration or Confirmation)
+```
+
+### 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**
+
+---
+
+## Navigation & Page Structure Rules
+
+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.
+
+---
+
+### 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>`
+
+---
+
+### 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
+
+Never deviate from this order. Never place navigation items above the workspace switcher.
+
+---
+
+### 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
+
+---
+
+### 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
+
+---
+
+### NAV-05: Navbar title — two modes
+
+**Mode 1 — Top-level page:**
+Show plain section title in the Navbar. No breadcrumbs.
+✅ Navbar: "Users"
+✅ Navbar: "Reports"
+
+**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.
+
+✅ Navbar breadcrumb: "Users > **Alice Johnson**"
+❌ Navbar title: "Alice Johnson" + separate breadcrumb below it
+❌ Navbar title: "Users" when inside Alice Johnson's page
+
+---
+
+### NAV-06: Breadcrumb variants — two levels
+
+There are two breadcrumb sizes and they serve different purposes:
+
+| 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 |
+
+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
+
+---
+
+### 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
+
+✅ "Users > Alice Johnson"
+✅ "Reports > Q4 2025"
+❌ "Home > Users > Alice Johnson" (unnecessary root)
+❌ "Alice Johnson" alone (missing parent context)
+
+---
+
+### 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.
+
+Primary actions are object-creation actions:
+"New user", "New deal", "Create report", "New email"
+
+✅ Navbar: "Users" + [New user — Primary button]
+❌ Card header: [New user — Primary button] on a top-level page
+
+---
+
+### NAV-09: CTA hierarchy in Navbar
+When a page has multiple actions, use this hierarchy in the Navbar (right side):
+
+| 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" |
+
+Order right-to-left by importance: Ghost → Secondary → Primary
+(Primary is always the rightmost — trailing edge)
+
+✅ [Export — Ghost] [Share — Ghost] [Edit — Secondary] [New user — Primary]
+❌ [New user — Primary] [Share — Ghost] (wrong order)
+❌ Two Primary buttons in the same Navbar
+
+---
+
+### 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.
+
+✅ 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"
+
+---
+
+### 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.
+
+✅ 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
+
+---
+
+### 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"
+
+---
+
+### 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.
+
+✅ DataTable inside a Card
+✅ SectionHeader "Personal info" → flat form fields below (no Card)
+❌ Every section wrapped in a Card by default
+
+---
+
+## Layout & Component Behavior Rules
+
+These rules apply globally. Apply them before building any screen or component.
+
+---
+
+### 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.
+
+✅ `<AppShell>` — sidebar and navbar fixed; content area overflows and scrolls independently
+❌ Full page scrolls, taking the sidebar and navbar with it
+
+---
+
+### 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)`
+
+---
+
+### 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.
+
+✅ `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
+
+---
+
+### 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.
+
+✅ `padding: var(--inset-large)` inside every card
+❌ Card content flush with card edges
+
+---
+
+### 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.
+
+✅ `import { ArrowUpDown } from 'lucide-react'`
+❌ System sort icon (↕) in table column headers
+❌ Any icon not from the Lucide library
+
+---
+
+### 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.
+
+✅ List item `width: 100%` of container (minus `--page-margin-x` padding)
+❌ List items sized to content, leaving empty space on the right
+
+---
+
+### 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.
+
+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
+
+✅ 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
+
+---
+
+### 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.
+
+✅ `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
+
+---
+
+### 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.
+
+Exceptions where real-time validation is acceptable: password strength, character count limits, search/filter fields, OTP.
+
+✅ 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
+
+---
+
+### 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.
+
+✅ `<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>`
+❌ Primary form button with no keyboard shortcut hint
+
+---
+
+### Tag semantic color mapping
+
+Always match Tag variant to the semantic meaning of the value. Never use the 
+same variant for all tags in a list.
+
+| 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    |
+
+When in doubt, ask: is this good, bad, cautionary, or neutral? 
+Pick the variant that matches that meaning.
+
+---
+
+### Page margin application
+
+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.
+
+/* CORRECT */
+.page-content {
+  padding-inline: var(--page-margin-x);
+}
+
+/* WRONG */
+.page-content {
+  padding: 0; /* flush to edges */
+}
+
+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.
+
+---
+
+## Copy & content guidelines
+
+### Buttons
+- Start with a strong verb: "Save", "Delete", "Export", "Send", "Create"
+- Be specific: "Save changes" not "OK" or "Yes"
+- 1–3 words; 5 maximum
+- Sentence case: "Save changes" not "Save Changes"
+- Never truncate with ellipsis — rewrite shorter
+- Never use first-person pronouns: "Save changes" not "Save my changes"
+- Destructive: name what is destroyed. "Delete account" not "Confirm"
+- Loading: present-progressive. "Saving…" "Sending…"
+
+### Labels (inputs, checkboxes, radios, switchers)
+- Noun or noun phrase describing the value/setting
+- Sentence case: "Phone number" not "Phone Number"
+- Never describe the action: "Email address" not "Enter your email address"
+- Describe the thing being controlled, not the act of toggling: "Email notifications" not "Turn on email notifications"
+
+### Placeholder text
+- Example of expected format, not a label: "e.g. john@example.com"
+- Never as the only label — it disappears on input
+- Must be clearly distinguishable from user-entered values
+
+### Error messages
+- Full sentences. Full stop at the end.
+- Specific and instructive: what went wrong + how to fix it
+- "Email address is invalid" not "Invalid input"
+- "Password must include at least one uppercase letter" not "Invalid password"
+- Do not blame the user: "Please enter a valid email address" not "You entered an invalid email address"
+- Include "please" when giving an instruction
+
+| Situation | Pattern | Example |
+|---|---|---|
+| Required field empty | Please enter [field name]. | Please enter your first name. |
+| Too long | Please enter fewer than [N] characters. | Please enter fewer than 50 characters. |
+| Too short | Please enter at least [N] characters. | Please enter at least 8 characters. |
+| Wrong format | Please enter [field name] in the correct format. | Please enter your email in the correct format. |
+| System fault | Sorry, [what happened]. Please [action]. | Sorry, we couldn't save your changes. Please try again. |
+
+### Toasts
+- Lead with outcome: "Changes saved" not "We are saving your changes"
+- Past tense for completed actions: "Exported", "Deleted"
+- Present tense for ongoing states: "Connection lost"
+- No "Successfully" prefix: "File uploaded" not "Successfully uploaded file"
+- One sentence max for Inline toast
+
+### Tags
+- 1–3 words. Nouns or adjectives.
+- Sentence case: "In review" not "In Review"
+- Never abbreviate unless universally understood
+- Label and variant must tell the same story
+
+### Chips
+- 1–3 words. Sentence case.
+- Nouns or adjectives. All chips in a group must be parallel in structure.
+- Never truncate with ellipsis — rewrite
+
+### Tabs / Segment control
+- 1–3 words for tabs, 1–2 words for segment control
+- Nouns only. No verbs, no questions.
+- Sentence case.
+
+### Empty states
+- Title: 2–5 words. No punctuation at end. Situation understandable from title alone.
+- Description: 1–2 lines. Full stop.
+- CTA button: 1–3 words. Verb-first. No full stop.
+- Never use: "Oops", "Uh oh", or phrases that trivialise the situation
+- For filtered empty: surface a clear "Clear filters" path
+
+### Modal content
+- Title: 3–6 words. Sentence case. For confirmations: "Delete project" not "Are you sure?"
+- Body for confirmations: one sentence stating consequence and reversibility.
+- Footer primary action: specific verb matching title. "Delete" not "OK" or "Confirm".
+- Cancel: "Cancel" for reversible, "Close" for informational.
+
+---
+
+## Accessibility requirements
+
+### Contrast
+- Normal text: WCAG AA minimum 4.5:1
+- Large text: 3:1 minimum
+- Focus rings: must pass WCAG AA contrast on the background they appear on
+
+### Keyboard
+- All interactive elements must be keyboard operable.
+- Focus order: top to bottom, left to right (LTR)
+- Closed disclosure components (Accordion, Popover, Dropdown): children must NOT be keyboard-reachable until open.
+
+### Focus
+- Always use `:focus-visible`, never `:focus` as the visible ring trigger.
+- Never `outline: none` without explicit replacement.
+- Focus must never be hidden by `overflow: hidden` or clipping on a parent.
+- Focus rings follow component's border radius.
+- Buttons/filled: offset ring using `var(--borders-focus-primary)`.
+- Inputs: border thickens to focus token when focused.
+- Destructive: use `var(--borders-focus-destructive)`.
+
+### Disabled elements
+- Native controls: use `disabled` attribute → removed from tab order.
+- Custom controls: `tabIndex={-1}` + `aria-disabled="true"`.
+- Disabled elements must NOT be focusable.
+- Exception: if user needs to discover the control exists, keep focusable with explanatory `aria-describedby`.
+
+### Color
+- Color alone must never convey meaning.
+- Pair with text, icon, or pattern for any meaning conveyed through color.
+
+### Forms / Inputs
+- Every input must have a programmatic label (`<label for>`, `aria-label`, or `aria-labelledby`).
+- Helper text and error messages: associated via `aria-describedby`.
+- Error state: `aria-invalid="true"` on the control.
+- All inputs are mandatory by default — always add `aria-required="true"`. For optional fields, omit `aria-required` or set to `false`.
+- Do not use `autocomplete="off"` without strong justification.
+- Error messages must not disappear automatically — persist until error is resolved.
+
+### Loading states
+- `aria-busy="true"` while loading. `aria-busy="false"` when complete.
+- Loading spinners: `aria-hidden="true"` on the graphic; the label carries the meaning.
+- Button loading: `aria-busy="true"` on the button.
+
+### Live regions
+- Polite: `aria-live="polite"` — after current interaction completes (Default, Success, Warning toasts; spinner completion; chip changes).
+- Assertive: `aria-live="assertive"` — interrupts immediately (Error toasts).
+
+### Popup / dropdown keyboard contract
+Every popup/dropdown must support:
+- `Arrow` keys: navigate between items
+- `Enter` / `Space`: select/activate
+- `Escape`: close and return focus to trigger
+- Focus return to trigger on close
+
+### Custom widget keyboard contracts
+| Widget type | Required keyboard behavior |
+|---|---|
+| `menuitem` | Enter/Space to activate; Arrow keys to navigate |
+| `switch` | Space to toggle |
+| `checkbox` | Space to toggle |
+| `radio` | Arrow keys to move selection; Space to select (or moves on Arrow) |
+| `slider` | Arrow keys ±1 step; Page Up/Down larger; Home/End min/max |
+| `tab` | Arrow keys between tabs; Enter/Space to activate |
+| `gridcell` | Roving tabindex; Arrow keys to navigate; Enter to select |
+
+### Testing requirements
+Every contribution must:
+- Pass `npm run test:a11y:keyboard-widgets`
+- Pass `npm run test:a11y:stories:light`
+- Pass `npm run test:a11y:stories:dark`
+- Have at least one keyboard interaction test for custom-role widgets
+- Verify disabled state tab-order
+- Verify focus-visible-only ring (never `:focus`)
+- Verify role/name/value for custom widgets
+
+Story-level a11y opt-out (disabled/demo stories):
+```typescript
+// Acceptable — scoped to story level only
+export const DisabledVariant: Story = {
+  parameters: { a11y: { disable: true } }
+  // Add comment explaining intentional exception
+};
+// NEVER disable at component meta level or globally for interactive components
+```
+
+---
+
+## What NOT to do (consolidated don'ts)
+
+### Tokens
+- ❌ Use primitive tokens in component styles. `var(--primitive-neutral-900)` in a button is wrong.
+- ❌ Hardcode hex values, pixel sizes, or rgba in styled components.
+- ❌ Reference `foreground` as a token category — it was renamed to `text`.
+- ❌ Use `base`, `normal`, or `rest` as the default state name — always use `default`.
+- ❌ Use `inset/` tokens for spacing between elements (use `space/`).
+- ❌ Use `space/` tokens for internal component padding (use `inset/`).
+- ❌ Use generic semantic tokens or hardcoded hex values for dataviz colors — always use `--color-dataviz-*`.
+
+### TypeScript
+- ❌ Type props as `string` when a union is possible. `variant: string` is wrong; `variant: 'primary' | 'secondary'` is correct.
+- ❌ Accept `state` as a prop. States are CSS pseudo-classes and boolean props, not a state prop.
+- ❌ Forward Styled Component's styling props to the DOM. Use transient props (`$propName`).
+
+### States
+- ❌ Use `opacity: 0.5` for disabled state. Use explicit disabled tokens: `var(--background-disabled)`, `var(--color-text-disabled)`.
+- ❌ Conditionally render different DOM elements for states.
+- ❌ Use `outline: none` without providing an explicit replacement.
+- ❌ Use `:focus` as the visible focus ring trigger — always `:focus-visible`.
+
+### Buttons
+- ❌ Place two Primary buttons side by side (except forced mutually exclusive choice).
+- ❌ Use Toggle button as a substitute for Switcher.
+- ❌ Use `aria-pressed` on Main or Destructive buttons — only on Toggle/Vertical.
+- ❌ Use vague button labels: "OK", "Yes", "Click here", "Proceed".
+- ❌ Use same label for two buttons on the same screen that do different things.
+- ❌ Truncate a button label with ellipsis.
+- ❌ Auto-confirm destructive actions — always require an explicit user action.
+
+### Components — decision errors
+- ❌ Use Badge when the label is text → use Tag.
+- ❌ Use Tag when the element is interactive → use Chip.
+- ❌ Use Chip when the element is purely informational → use Tag.
+- ❌ Use Checkbox when effect is immediate → use Switcher.
+- ❌ Use Switcher when effect requires confirmation → use Checkbox.
+- ❌ Use Radio for 7+ options → use Select.
+- ❌ Use Segment control for options with distinct content panels → use Tabs.
+- ❌ Use Tooltip when content is longer than one sentence → use Popover.
+- ❌ Use Tooltip when content has interactive elements → use Popover.
+- ❌ Open a Modal from within a Modal — nested modals break focus management.
+- ❌ Open a Popover from within a Popover — nested popovers create layering issues.
+- ❌ Auto-open modals on page load.
+- ❌ Use Toast for critical actions that require user response → use Modal.
+- ❌ Use Toast for inline form field validation → use inline validation.
+- ❌ Use Skeleton for instant operations (<300ms) — avoid flicker.
+- ❌ Use Spinner for operations where content shape is known → use Skeleton.
+- ❌ Use NumberInput for currency amounts or ranges → use Slider for ranges.
+- ❌ Use PasswordInput for PINs or OTPs → use OTPInput.
+- ❌ Use TextInput for multi-line → use TextArea.
+- ❌ Use Plain variant Button in `md` size — Plain is `sm` only.
+
+### Layout and placement
+- ❌ Build page layout manually with divs — always use `AppShell`.
+- ❌ Apply scroll to the full page or AppShell root — only the content area scrolls.
+- ❌ Use hardcoded `padding-left`, `padding-right`, `margin-left`, or `margin-right` on any container — always use `var(--page-margin-x)`.
+- ❌ Allow card content to touch card edges — always apply `padding: var(--inset-large)`.
+- ❌ Leave list items undersized — always stretch to full container width.
+- ❌ Mix Tab and CustomView tab types in the same row.
+- ❌ Nest tabs within tabs.
+- ❌ Place pagination above content — always below.
+- ❌ Mix Pagination and infinite scroll patterns in the same view.
+- ❌ Place Breadcrumbs inside cards, modals, or drawers.
+- ❌ Place Loading bar inline within components — top of viewport only.
+- ❌ Place Segment control in the middle of body content.
+- ❌ Use both vertical and horizontal scrollbars on the same container (unless truly 2D content).
+- ❌ Float a lone button at an arbitrary position — anchor it to the content it acts on.
+- ❌ Place tags at the bottom of an item's hierarchy — always close to what they describe.
+- ❌ Show more than 3 tags on a single item.
+- ❌ Mix Avatar sizes within the same list or group.
+- ❌ Mix Chip sizes in the same group.
+- ❌ Mix Checkbox or Radio sizes in the same group.
+- ❌ Mix Switcher sizes in the same group.
+
+### Icons and placeholder content
+- ❌ Use any icon library other than Lucide (`lucide-react`) — no system icons, no emoji, no other libraries.
+- ❌ Leave placeholder icons in component slots — replace with a meaningful Lucide icon or hide the slot.
+- ❌ Leave placeholder help text in place — replace with real content or hide entirely.
+- ❌ Leave placeholder hint icons in place — replace with meaningful tooltip content or hide.
+
+### Forms
+- ❌ Mark required fields with a red asterisk — use an "Optional" label in `var(--text-tertiary)` for optional fields only.
+- ❌ Enable the primary CTA before all mandatory fields have a value.
+- ❌ Validate form fields in real time as the user types (except: password strength, character count, search, OTP).
+- ❌ Omit the `⌘↵` keyboard shortcut hint from the primary submit button.
+
+### Content writing
+- ❌ Use "Oops", "Uh oh", or diminishing phrases in empty or error states.
+- ❌ Blame the user in error messages.
+- ❌ Show "0" badge — remove the badge when count is zero.
+- ❌ Show a badge with a number > 99 — show "99+".
+- ❌ Use placeholder text as the only label for an input.
+- ❌ Use "Successfully" as a toast prefix — just state the outcome.
+- ❌ Use "OK" or "Confirm" as primary action labels in modals — use specific verbs.
+- ❌ Use "Are you sure?" as a modal title — state what is being confirmed.
+- ❌ Abbreviate chip or tag labels unless universally understood.
+- ❌ Put interactive elements inside a Tooltip.
+
+### Accessibility
+- ❌ Use color alone to convey meaning.
+- ❌ Leave disabled elements focusable (for custom controls without `disabled` attribute).
+- ❌ Allow focus to reach elements inside closed disclosure components.
+- ❌ Allow focus to escape a modal while it is open.
+- ❌ Suppress focus indicators.
+- ❌ Place essential information only in a tooltip — touch users will never see it.
+- ❌ Use `aria-label` alone when a visible label is present — link via `aria-labelledby` instead.
+- ❌ Use `aria-pressed` on non-toggle buttons.
+- ❌ Disable a11y checks at component meta or global level for interactive components.
+- ❌ Static (non-animated) skeleton shapes — must shimmer/pulse.
+- ❌ Replace skeleton placeholders one by one — replace all simultaneously.
+- ❌ Allow custom scrollbars to interfere with native keyboard scroll behavior.
+- ❌ Use `:focus` for OTP or any other component's visible ring — always `:focus-visible`.
+- ❌ Expose technical error codes, stack traces, or internal identifiers to users.
+
+### Exports
+- ❌ Forget to export from component `index.ts`: `export { X } from './X'`
+- ❌ Forget to re-export from `src/index.ts`
+
+---
+
+*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/`.*