npm - @ngrr/ds - Versions diffs - 0.1.29 → 0.1.32 - Mend

@ngrr/ds 0.1.29 → 0.1.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/AI-short.md +243 -0
package/AI.md +814 -1691
package/README.md +50 -1
package/dist/components/atoms/Avatar/Avatar.d.ts +2 -2
package/dist/components/atoms/Badge/Badge.d.ts +4 -4
package/dist/ds-nagarro.es.js +23 -8
package/dist/ds-nagarro.umd.js +1 -1
package/dist/style.css +2 -0
package/dist/tokens.css +183 -70
package/package.json +4 -4
package/AGENTS.md +0 -461
package/CLAUDE.md +0 -6
package/dist/ds.css +0 -2

package/AI.md CHANGED Viewed

@@ -2,22 +2,19 @@
 > **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.
+> **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 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)`.
+1. **Before writing any code** — read [Setup](#setup--mandatory-css-imports) and implement the required imports and CSS.
+2. **Before building any page** — read [AppShell](#appshell--mandatory-root-layout) and [Hard rules](#hard-rules--read-before-writing-any-code).
+3. **Before selecting a component** — check [Cross-component patterns](#cross-component-patterns).
+4. **Before implementing a component** — read its section in [Component usage rules](#component-usage-rules).
+5. **All token references** must use CSS custom properties: `var(--token-name)`. Never hardcode values.
+6. Token naming: Figma slash paths → hyphenated CSS vars. `background/interactive/cta/default` → `var(--background-interactive-cta-default)`.
 ---
@@ -32,185 +29,181 @@ 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; }
+#root { height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
 ```
----
-## Token System Rules
-These rules apply globally to every component.
-### Three-tier model — always resolve through this chain
+### Required wrapper for AppShell
+AppShell needs a full-viewport parent. Always wrap it — never set height on AppShell itself:
-```
-Primitives (raw) → Semantic (intent) → Component (usage)
+```tsx
+// App.tsx or your route root
+<div style={{ height: '100vh', display: 'flex' }}>
+  <AppShell ...>
+    ...
+  </AppShell>
+</div>
 ```
-- **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
+## Hard rules — read before writing any code
-| Token family | CSS property |
-|---|---|
-| `--color-text-*` | `color` |
-| `--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` |
-| `--transition-*` | `transition` |
+These are the most violated rules. Read them first. They apply to every page, every component, every line of code.
-### Space vs Inset — never mix
+### Layout
+- `AppShell` is the **only** permitted root layout. Never build layout with raw divs.
+- `AppShell` always lives inside `<div style={{ height: '100vh', display: 'flex' }}>` — never add height directly to AppShell.
+- Page content always wrapped in `<div style={{ paddingInline: 'var(--page-margin-x)', paddingBlock: 'var(--inset-large)' }}>` inside AppShell's content slot.
+- Only the content area scrolls. Sidebar and Navbar are always fixed. Never apply scroll to the full page.
+- `DataTable` is **never** wrapped in a `Card` — always full-width.
+- Never add `padding`, `margin`, `gap`, `min-height`, or any spacing override directly on a DS-Nagarro component. Apply spacing tokens to wrapper/container elements only.
+- Never add padding or margin directly to `<Card>` — wrap children in `<div style={{ padding: 'var(--inset-large)' }}>`.
-- `space/*` → gaps **between** elements (gap, margin)
-- `inset/*` → padding **inside** a component
+### Typography
+- Never set `font-family` anywhere in app code — it is inherited from the design system.
+- Never use raw `<h1>`–`<h6>` or `<p>` elements with custom font styling.
+- Never set `font-size` with raw pixel values — always use `var(--font-size-*)` tokens.
+- Never use serif, system, or any non-design-system font.
-✅ `gap: var(--space-standard)` between items
-✅ `padding: var(--inset-standard)` inside a button
-❌ `gap: var(--inset-standard)` — wrong scale for context
+### Buttons and CTAs
+- Primary CTA always in Navbar `rightActions` — never inside a Card, never floating.
+- Never create a floating action button (FAB). Never use `position: fixed` or `position: absolute` on any Button.
+- Maximum one Primary button per view.
+- Button order right-to-left: Ghost → Secondary → Primary (Primary is always rightmost).
-### State name convention
+### Navigation
+- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes).
+- All titles, labels, and copy: sentence case always. Never title case.
-Always use these exact identifiers. Never use `base`, `normal`, or `rest`.
+### Tokens
+- Never hardcode hex values, pixel sizes, or rgba. Everything comes from tokens.
+- Never use `--inset-*` for gaps between elements — use `--space-*`.
+- Never use `--space-*` for padding inside components — use `--inset-*`.
+- Never use generic semantic tokens or hardcoded hex for dataviz — always `--color-dataviz-*`.
+- Always look on tokens.css for available tokens. Tokens are descriptive enough to understand the purpose. Use them accordingly. For example: You need a space between fields on a form, use --space-form-vertical. You need a border radius for a card, use  --surface-card-radius. You need a gutter between cards, use --grid-cards-gutter.
-| 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` |
+### Tags
+- Always match Tag `variant` to the semantic meaning. Never use the same variant for all tags in a list.
+- Tags are non-interactive. Never make a Tag clickable.
-`md` is always the default. When no size specified, generate with `md`.
+### Icons
+- Only `lucide-react` is permitted — bundled inside `@ngrr/ds`, no separate install needed.
+- Never use system icons, emoji, or any other icon library.
+- Never leave placeholder icons in component slots.
+### Dark mode
+- Dark mode is controlled by `data-theme="dark"` on the root element.
+- Never use `@media (prefers-color-scheme: dark)` for dark mode.
 ---
 ## 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.
+`AppShell` is the only permitted root layout wrapper. Every page must be inside it.
 ```tsx
-import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
-// Icons come from lucide-react — bundled inside @ngrr/ds, no separate install needed
+import { AppShell, Navbar, Sidebar, SidebarMenuSelector, Button, SearchBar } from '@ngrr/ds';
+// Icons from lucide-react — bundled inside @ngrr/ds, no separate install needed
 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>
+// Always wrap AppShell in a full-height div — never add height to AppShell itself
+<div style={{ height: '100vh', display: 'flex' }}>
+  <AppShell
+    header={
+      <Navbar
+        variant="title"
+        title="Dashboard"
+        rightActions={<Button variant="primary" size="md">New project</Button>}
+      />
+    }
+    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={() => {}}
+            />
+          </>
+        }
+      />
+    }
+  >
+    {/* Always include this wrapper div — never skip it */}
+    <div style={{
+      paddingInline: 'var(--page-margin-x)',
+      paddingBlock: 'var(--inset-large)',
+    }}>
+      {/* page content here */}
+    </div>
+  </AppShell>
+</div>
 ```
-**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
+### AppShell props
+- `header` — `<Navbar />` only. Always set `variant` explicitly.
+- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically.
+- `children` — main page content. Always wrap in the padding div shown above.
+- `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
+### SidebarMenuSelector variant
+AppShell controls the collapsed state and passes it to Sidebar automatically. Mirror it in `bottomContent`:
----
+```tsx
+// collapsed is injected by AppShell — use it to switch variant
+<SidebarMenuSelector variant={collapsed ? 'icon' : 'full'} label="Settings" ... />
+<SidebarMenuSelector variant={collapsed ? 'icon' : 'full'} label="User Name" ... />
+```
 ### Navbar props
-- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
+- `variant` — always set explicitly: `'title'` for top-level pages | `'breadcrumbs'` for detail views
 - `title` — page title, sentence case
-- `rightActions` — primary CTA button, rightmost position
+- `rightActions` — primary CTA, rightmost. Never inside a Card. Never floating.
 - `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
+- `showSearch` / `searchSlot` — pass `<SearchBar />` when search is needed.
+- `bottomContent` — Settings and User Name, pinned to bottom. Always include both.
+- Never pass `collapsed` — AppShell controls it.
-**SidebarMenuItem shape:**
+### SidebarMenuItem shape
 ```ts
 {
   id: string;
@@ -228,279 +221,371 @@ import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings }
 ---
-### 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` — bundled inside `@ngrr/ds`, no separate install needed
-- 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
----
+## Token system rules
-## Navigation & Page Structure Rules
+### Three-tier model — always resolve through this chain
+```
+Primitives (raw) → Semantic (intent) → Component (usage)
+```
+- Use semantic tokens in all app code: `var(--color-text-primary)` ✅ — `var(--primitive-neutral-900)` ❌
+- Never hardcode hex codes, pixel values, or rgba.
-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.
+### 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) |
+| `--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 page content wrappers |
+| `--radius-*` | `border-radius` |
+| `--border-width-*` | `border-width` |
+| `--effects-elevation-*` | `box-shadow` |
+| `--transition-*` | `transition` |
-### 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>`
+### Space vs Inset — never mix
+- `--space-*` → gaps **between** elements (`gap`, `margin`)
+- `--inset-*` → padding **inside** a component
----
+✅ `gap: var(--space-standard)` between cards
+✅ `padding: var(--inset-large)` inside a card's content wrapper
+❌ `gap: var(--inset-standard)` — wrong token family for gaps
-### 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
+**Spacing tokens — Source: Figma size collection**
-Never deviate from this order. Never place navigation items above the workspace switcher.
+space/* = gaps between sibling elements
+inset/* = padding inside components
+Rule: same name = same value across both scales.
----
+| Token | Value |
+|---|---|
+| --space-none | 0px |
+| --space-micro | 2px |
+| --space-tiny | 4px |
+| --space-small | 8px |
+| --space-compact | 12px |
+| --space-medium | 16px |
+| --space-large | 24px |
+| --space-spacious | 32px |
+| --space-ample | 48px |
+| --space-grand | 64px |
+| --space-toolbar-standard | 16px (→ space-medium) |
+| --space-form-vertical | 32px (→ space-spacious) |
+| Token | Value |
+|---|---|
+| --inset-none | 0px |
+| --inset-micro | 2px |
+| --inset-tiny | 4px |
+| --inset-small | 8px |
+| --inset-compact | 12px |
+| --inset-medium | 16px |
+| --inset-large | 24px |
+| --inset-spacious | 32px |
+**Radius tokens — Source: Figma size collection → radius/***
+| Token | Value | Use |
+|---|---|---|
+| --radius-none | 0px | Sharp corners |
+| --radius-xsmall | 4px | Tooltips |
+| --radius-small | 12px | Inputs, chips |
+| --radius-standard | 16px | Buttons, tags, controls |
+| --radius-large | 24px | Cards |
+| --radius-xlarge | 32px | Modals |
+| --radius-full | 9999px | Pills, avatars |
+Component-specific aliases:
+- --surface-tooltip-radius → --radius-xsmall (4px)
+- --surface-popover-radius → --radius-standard (16px)
+- --surface-card-radius → --radius-large (24px)
+- --surface-modal-radius → --radius-xlarge (32px)
+**Z-index tokens — Source: Figma size collection → z-index/***
+| Token | Value |
+|---|---|
+| --z-index-sticky | 1020 |
+| --z-index-fixed | 1030 |
+| --z-index-modal-backdrop | 1040 |
+| --z-index-modal | 1050 |
+| --z-index-popover | 1060 |
+| --z-index-tooltip | 1070 |
+**Breakpoint tokens — Source: Figma size collection → breakpoints/***
+NOTE: These must always be raw px values. Never use var() for breakpoints —
+CSS custom properties do not resolve inside @media queries.
+| Token | Value |
+|---|---|
+| --breakpoint-mobile | 480px |
+| --breakpoint-tablet | 768px |
+| --breakpoint-desktop | 1280px |
+| --breakpoint-desktop-large | 1440px |
-### 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
+**Transition tokens — Source: Figma motion collection → transition/***
----
+| Token | Value | Use |
+|---|---|---|
+| --transition-instant | 0ms ease | No animation |
+| --transition-fast | 150ms ease | General UI |
+| --transition-normal | 250ms ease | General UI |
+| --transition-slow | 400ms ease | General UI |
+| --transition-popover | 150ms ease | Popovers |
+| --transition-switcher | 150ms ease | Toggle switches |
+| --transition-drawer | 250ms ease | Drawers |
+| --transition-modal | 0ms ease | Modals |
+**Grid tokens — Source: Figma size collection → grid/***
+| Token | Value |
+|---|---|
+| --grid-columns | 12 |
+| --grid-gutter | 16px |
+| --grid-margin-x | 16px |
+| --grid-cards-gutter | 16px |
-### 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
+### Typography — never override
+```tsx
+// CORRECT
+<div style={{
+  fontSize: 'var(--font-size-body-l)',
+  fontWeight: 'var(--font-weight-semibold)',
+  color: 'var(--color-text-primary)',
+}}>
----
+// WRONG — every one of these
+<h2 style={{ fontFamily: 'Georgia, serif' }}>        // never set font-family
+<p style={{ fontSize: '18px', fontWeight: 700 }}>    // never raw px
+<div style={{ fontFamily: 'Inter, sans-serif' }}>    // never set font-family
+```
-### NAV-05: Navbar title — two modes
+## Token invention rule
-**Mode 1 — Top-level page:**
-Show plain section title in the Navbar. No breadcrumbs.
-✅ Navbar: "Users"
-✅ Navbar: "Reports"
+NEVER create CSS custom properties that do not correspond to a variable
+in the Figma size, color, motion, or typography collections.
-**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.
+If a token does not exist in Figma, do not create it — not even as a
+convenience alias or layout helper. If a token is needed, ask the user
+to create it in Figma first, then mirror it in tokens.css.
-✅ Navbar breadcrumb: "Users > **Alice Johnson**"
-❌ Navbar title: "Alice Johnson" + separate breadcrumb below it
-❌ Navbar title: "Users" when inside Alice Johnson's page
+### Known fabricated token patterns to reject:
----
+The following were invented by AI agents and removed. Never recreate them:
-### NAV-06: Breadcrumb variants — two levels
+- layout/page-margin-x · layout/section-spacing-* · layout/card-padding
+  → These don't exist in Figma. Use --inset-medium and --space-* instead.
+- space/comfortable · space/generous · space/ample (old names)
+  → Old invented names. Use --space-large, --space-spacious, --space-ample.
+- inset/xlarge
+  → Renamed to --inset-spacious in Figma and CSS.
+- radius/medium (6px) · radius/large (8px)
+  → Were wrong values. Correct scale is radius/small=12, radius/standard=16.
+- font-size/display-s at 1.125rem
+  → Wrong value. Correct is 1.5rem (24px per Figma).
+- --space-comfortable (20px)
+  → Never existed in Figma. Use --space-large (24px).
+- var() inside @media queries using breakpoint tokens
+  → CSS custom properties don't resolve in @media. Always use raw px.
-There are two breadcrumb sizes and they serve different purposes:
+---
-| Variant | Where | Purpose |
-|---|---|---|
-| **Large** (`BreadcrumbsLarge`) | Navbar | Main navigation hierarchy — replaces page title on detail views |
-| **Small** (`Breadcrumbs`) | Inside page content | Sub-section hierarchy within a detail page |
+## Tag semantic mapping — critical
-NEVER use small breadcrumbs for main navigation.
-NEVER use large breadcrumbs inside content areas.
+Always match Tag `variant` to the semantic meaning of the value. Never use the same variant for all tags in a list.
-✅ Navbar: large breadcrumb "Users > Alice Johnson"
-✅ Inside content: small breadcrumb "Permissions > Edit role"
-❌ Navbar: small breadcrumb
-❌ Content area: large breadcrumb
+| 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` |
----
+```tsx
+// WRONG — same variant for every tag
+<Tag variant="warning">In progress</Tag>
+<Tag variant="warning">Completed</Tag>    // completed = success
+<Tag variant="warning">Not started</Tag>  // not started = neutral
-### 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
+// CORRECT — variant matches meaning
+<Tag variant="warning">In progress</Tag>
+<Tag variant="success">Completed</Tag>
+<Tag variant="neutral">Not started</Tag>
+<Tag variant="error">Blocked</Tag>
+```
-✅ "Users > Alice Johnson"
-✅ "Reports > Q4 2025"
-❌ "Home > Users > Alice Johnson" (unnecessary root)
-❌ "Alice Johnson" alone (missing parent context)
+Tags are non-interactive. Never make a Tag clickable.
 ---
-### 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.
+## KPI / stat card pattern
-Primary actions are object-creation actions:
-"New user", "New deal", "Create report", "New email"
+Dashboard summary cards must always use this pattern. Never invent custom layouts with raw HTML or custom typography.
-✅ Navbar: "Users" + [New user — Primary button]
-❌ Card header: [New user — Primary button] on a top-level page
----
+```tsx
+<Card>
+  <div style={{ padding: 'var(--inset-large)' }}>
+    <div style={{
+      fontSize: 'var(--font-size-body-s)',
+      color: 'var(--color-text-secondary)',
+      marginBottom: 'var(--space-tiny)',
+    }}>
+      Active projects
+    </div>
+    <div style={{
+      fontSize: 'var(--font-size-heading-l)',
+      fontWeight: 'var(--font-weight-semibold)',
+      color: 'var(--color-text-primary)',
+    }}>
+      14
+    </div>
+    {/* Optional trend line */}
+    <div style={{
+      fontSize: 'var(--font-size-body-s)',
+      color: 'var(--color-text-success)',  // or --color-text-danger for negative
+      marginTop: 'var(--space-tiny)',
+    }}>
+      +2 this week
+    </div>
+  </div>
+</Card>
+```
-### NAV-09: CTA hierarchy in Navbar
-When a page has multiple actions, use this hierarchy in the Navbar (right side):
+Rules:
+- Always use `<Card>` as the container — never a raw div with manual border/shadow.
+- Always use `var(--font-size-*)` tokens — never raw px values.
+- Always use `var(--color-text-*)` tokens — never hardcode colors.
+- Never set `font-family` — it is inherited.
-| 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)
+## Card structure
-✅ [Export — Ghost] [Share — Ghost] [Edit — Secondary] [New user — Primary]
-❌ [New user — Primary] [Share — Ghost] (wrong order)
-❌ Two Primary buttons in the same Navbar
+`Card` has three areas: optional header (`SectionHeader`), content area (`children`), optional bottom bar (`Toolbar`).
----
+```tsx
+// CORRECT
+<Card title="Team members">
+  <div style={{ padding: 'var(--inset-large)' }}>
+    {/* content here */}
+  </div>
+</Card>
-### 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.
+// WRONG
+<Card style={{ padding: 'var(--inset-large)' }}>            // never on Card itself
+<SectionHeader style={{ padding: 'var(--inset-small)' }} /> // never — pre-built
+<Toolbar style={{ padding: 'var(--inset-small)' }} />       // never — pre-built
+```
-✅ 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"
+- Header and bottom bar are pre-built instances — never add padding, margin, or gap to them.
+- Content area has no built-in padding — always wrap children in a div with `padding: var(--inset-large)`.
+- `DataTable` is never wrapped in a `Card` — always full-width.
 ---
-### 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.
+## Navigation & page structure rules
+### NAV-01: AppShell is mandatory
+Every page MUST use `AppShell` as its root layout.
+✅ `<AppShell header={...} sidebar={...}>...</AppShell>`
+❌ `<div style={{ display: 'flex' }}>...</div>`
-✅ 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-02: Sidebar structure — top to bottom, never deviate
+1. Workspace switcher
+2. Main navigation items
+3. User profile + Settings
----
+### NAV-03 / NAV-04: Back arrows
+- **Top-level pages** (Dashboard, Projects, Tasks, People, Notes): NEVER show back arrow.
+- **Detail views** (a record or child page): ONLY then show back arrow via `variant="breadcrumbs"`.
-### NAV-12: Page title and section header casing
-ALL page titles, Navbar titles, breadcrumb items, and section headers use sentence case.
-NEVER title case.
+### NAV-05: Navbar title — two modes
+- **Top-level page**: `variant="title"` with page name. No breadcrumbs.
+- **Detail view**: `variant="breadcrumbs"` with `BreadcrumbsLarge`. The breadcrumb IS the title — never show both.
-✅ "Personal info", "New user", "Alice Johnson", "Save changes"
-❌ "Personal Info", "New User", "Save Changes"
+### NAV-06: Breadcrumb variants
+| Variant | Where |
+|---|---|
+| `BreadcrumbsLarge` | Navbar only — replaces page title on detail views |
+| `Breadcrumbs` (small) | Inside page content — sub-section hierarchy only |
----
+Never use small breadcrumbs for main navigation. Never use large breadcrumbs inside content.
-### 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.
+### NAV-07: Breadcrumb format
+`[Parent] > [Current page]` — start from immediate parent, not root/Home.
+Current page (rightmost): non-interactive, bold. Never truncate it.
-✅ DataTable inside a Card
-✅ SectionHeader "Personal info" → flat form fields below (no Card)
-❌ Every section wrapped in a Card by default
+✅ "Projects > Q4 Campaign"
+❌ "Home > Projects > Q4 Campaign" (unnecessary root)
----
+### NAV-08: Primary CTA placement
+Primary CTA always in Navbar `rightActions`. Never inside a Card. Never floating. Never `position: fixed/absolute`.
-## Layout & Component Behavior Rules
+✅ Navbar: "Projects" + [New project — Primary]
+❌ Floating `+` button positioned absolutely
-These rules apply globally. Apply them before building any screen or component.
+### NAV-09: CTA hierarchy in Navbar
+Right-to-left: Ghost → Secondary → **Primary** (Primary always rightmost).
+Maximum one Primary button per view.
----
+### NAV-11: Section headers
+Use `SectionHeader` component to divide content sections. Never use raw `<h2>` or `<h3>`.
+Section headers do NOT need to be inside a Card.
-### 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.
+### NAV-12: Casing
+ALL page titles, Navbar titles, breadcrumbs, section headers, button labels: sentence case. Never title case.
+✅ "New project" ✅ "Save changes" ❌ "New Project" ❌ "Save Changes"
-✅ `<AppShell>` — sidebar and navbar fixed; content area overflows and scrolls independently
-❌ Full page scrolls, taking the sidebar and navbar with it
+### NAV-13: Cards vs sections
+Not every content group needs a Card. Use `SectionHeader` + flat content for continuous page flow.
+Use Card only for distinct, self-contained units (form block, summary panel).
+❌ Wrapping every section in a Card by default.
 ---
-### 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.
+## Layout & component behavior rules
+### LCB-01: Scroll
+Sidebar and Navbar are always fixed. Only main content area scrolls.
+Never apply scroll to the full page or AppShell root.
+### LCB-02: Dataviz colors
+All charts and graphs must use `--color-dataviz-*` tokens for all colors.
 ✅ `fill: var(--color-dataviz-1)`
 ❌ `fill: #0F766E`
 ❌ `fill: var(--background-accent)`
----
-### LCB-03: Horizontal spacing — always use `--page-margin-x`
-`var(--page-margin-x)` is the horizontal breathing room for page content. Apply it as `padding-inline` on your own layout wrapper elements inside the content area. Never apply it directly to DS-Nagarro components — they manage their own internal spacing.
+### LCB-03: Horizontal spacing
+`var(--page-margin-x)` applies as `padding-inline` on your own wrapper divs. Never on DS-Nagarro components.
 ```tsx
-// CORRECT — applied to your own wrapper div inside AppShell's content slot
+// CORRECT
 <AppShell ...>
-  <div style={{ paddingInline: 'var(--page-margin-x)' }}>
-    {/* page content here */}
+  <div style={{ paddingInline: 'var(--page-margin-x)', paddingBlock: 'var(--inset-large)' }}>
+    {/* content */}
   </div>
 </AppShell>
 // WRONG
-<Navbar style={{ paddingInline: 'var(--page-margin-x)' }} />  // DS-Nagarro component — never
-padding: 24px  // hardcoded value — never
-margin: 0 16px  // hardcoded value — never
+<Navbar style={{ paddingInline: 'var(--page-margin-x)' }} />  // never on DS component
+padding: 24px  // never hardcoded
 ```
----
-### LCB-04: Card internal padding — content must never touch card edges
-`Card` has three areas: an optional header (`SectionHeader`), a content area (`children`), and an optional bottom bar (`Toolbar`). The header and bottom bar are pre-built component instances — never add padding, margin, or gap to them. The content area has no built-in padding — always wrap `children` in a div with `padding: var(--inset-large)` so content never touches the card edges.
-```tsx
-// CORRECT
-<Card title="Team members">
-  <div style={{ padding: 'var(--inset-large)' }}>
-    {/* content here */}
-  </div>
-</Card>
-// WRONG
-<SectionHeader style={{ padding: 'var(--inset-small)' }} />  // pre-built instance — never
-<Toolbar style={{ padding: 'var(--inset-small)' }} />        // pre-built instance — never
-// Card children with no padding wrapper — content touches card edges
-```
----
-### LCB-05: Icons — always use Lucide, never system icons
-The only permitted icon library is Lucide (`lucide-react`). It is bundled inside `@ngrr/ds` — no separate install is needed.
-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.
+### LCB-05: Icons
+Only `lucide-react`. Bundled in `@ngrr/ds` — no separate install.
+Applies everywhere: tables, buttons, inputs, menus, empty states.
-✅ `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-06b: DataTable multi-selection — BulkActionBar placement
-When a DataTable supports row selection, selecting one or more rows must show a `BulkActionBar` fixed at the bottom center of the table's container. The bar is dismissed via its × button, which must clear the entire selection.
-`BulkActionBar` only accepts a `className` prop for styling — it has no `style` prop. Positioning must go on a wrapper div around the component.
+### LCB-06: List items
+Always stretch to full container width (`width: 100%`). Never let items float at arbitrary width.
+### LCB-06b: DataTable multi-selection — BulkActionBar
 ```tsx
-// Table container must be position: relative
 <div style={{ position: 'relative' }}>
   <DataTable ... />
   {selectedCount > 0 && (
@@ -519,306 +604,216 @@ When a DataTable supports row selection, selecting one or more rows must show a
   )}
 </div>
 ```
+- `BulkActionBar` only accepts `className` — positioning goes on the wrapper div.
+- Only render when `selectedCount > 0`.
+- Action labels must be count-aware: `"Delete 3"` not `"Delete"`.
+- `onDismiss` must clear the entire selection.
-Rules:
-- Only render when `selectedCount > 0` — never mount with zero selected items
-- Always centered horizontally: `left: 50%` + `transform: translateX(-50%)`
-- Always `var(--inset-large)` from the bottom of the table container
-- Table container must be `position: relative` — never position relative to the viewport
-- Action labels must be count-aware: `"Delete 3"` not `"Delete"`
-- `onDismiss` must clear the entire selection, not just hide the bar
----
-### 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.
+### LCB-07: Placeholder content
+Never leave placeholder values in component slots. Replace with real content or hide the slot.
+- Icon slots → meaningful Lucide icon or hidden
+- Help text → real guidance or hidden
+- Hint icons → real tooltip content or hidden
-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
+### LCB-08: Required fields
+Every field is mandatory by default. Never use a red asterisk.
+Mark optional fields only: `Team <span style="color: var(--color-text-tertiary)">Optional</span>`
-✅ 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-09: Form CTA
+Primary submit must be disabled until all mandatory fields have a value.
+Validate all fields on submit only — not in real time (exceptions: password strength, character count, search, OTP).
----
-### 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-10: Form keyboard shortcut
+Every primary submit button must show `⌘↵` using the `Shortcut` component.
+`<Button variant="primary">Save changes <Shortcut>⌘↵</Shortcut></Button>`
 ---
-### 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.
+## Cross-component patterns
-✅ 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
+Apply these before selecting any component.
----
+### Pattern 1 — Single select
+```
+Requires confirmation?
+  Yes → Radio
+  No → 2–3 options → SegmentControl
+       4+ options  → Select (add search for 20+)
+```
-### 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 2 — Multi select
+```
+Up to 3 options → Chips (shown upfront)
+4+ options      → Select + Checkbox list
+Large/dynamic   → AutocompleteMulti
+```
-✅ `<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>`
-❌ Primary form button with no keyboard shortcut hint
+### Pattern 3 — Binary (on/off)
+```
+Toolbar, icon-only, immediate → Toggle button (+ Tooltip)
+Form, confirmed on submit     → Checkbox
+Settings, labeled, immediate  → Switcher
+```
----
+### Pattern 4 — Filter bar
+```
+1 value   → Toggle button
+2–5       → Chips in a horizontal bar
+6–12      → "Filters" button → dropdown
+13+       → "Filters" button → drawer
-### Tag semantic color mapping
+Always: show active state, provide "Clear all" when any filter is active
+```
-Always match Tag variant to the semantic meaning of the value. Never use the
-same variant for all tags in a list.
+### Pattern 5 — Pagination vs infinite scroll
+```
+Data tables → Pagination
+Feeds       → Infinite scroll
+Never mix both in the same view
+```
-| 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 6 — Loading state
+```
+Shape known?
+  Yes → Skeleton
+  No  → Spinner
-When in doubt, ask: is this good, bad, cautionary, or neutral?
-Pick the variant that matches that meaning.
+Scope:
+  Full page navigation       → LoadingBar
+  Full page/panel content    → Skeleton or Spinner (xl/xxl)
+  Section/card within page   → Skeleton or Spinner (lg)
+  Inline in a button         → Spinner (sm), button disabled
+  Background task            → No indicator; Toast on completion
+```
----
+### Pattern 7 — Overlay
+```
+Must act before continuing?
+  Yes → destructive confirmation → Alert dialog
+      → other task or form      → Modal
+  No  → anchored to element     → Popover or Tooltip
+      → not anchored            → Toast or Drawer
+```
-### Page margin application
+### Pattern 8 — Empty state
+```
+Primary page content area → lg (illustration + title + description + CTA)
+Card/panel/section        → sm (icon + title + description + CTA)
-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.
+First use        → invite to create first item
+No results       → "No results for '[query]'" + Clear filters CTA
+Permission error → explain restriction
+Load error       → Retry CTA
+```
-```css
-/* CORRECT */
-.page-content {
-  padding-inline: var(--page-margin-x);
-}
+### Pattern 9 — Error
+```
+Single form field     → Inline validation message
+Section within page   → Inline error pattern
+Entire page blocked   → Error screen
+```
-/* WRONG */
-.page-content {
-  padding: 0; /* flush to edges */
-}
+### Pattern 10 — Success feedback
+```
+Routine action (save, delete) → Toast (success, auto-dismiss 4–5s)
+Significant milestone         → Success screen
 ```
-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 SegmentControl
+1. Each option has a distinct content panel? → **Tabs**
+2. Switching changes how the same content is rendered? → **SegmentControl**
+3. Each option could be its own sub-route? → **Tabs**
+4. Display preference, not architecture? → **SegmentControl**
+### Component decision table
+| Situation | Component |
+|---|---|
+| Toggle between 2–5 mutually exclusive views | `SegmentControl` — never plain text or custom buttons |
+| Each option has a distinct content panel | `Tabs` |
+| User selects or filters with a toggleable option | `Chip` |
+| Non-interactive status or category label | `Tag` |
+| User clicks a table row to see details | `Drawer` |
+| User must complete a task before continuing | `Modal` |
+| Numeric count on a nav icon | `Badge` |
+| List needing sorting, filtering, or pagination | `DataTable` |
+| No results or first-time empty section | `EmptyState` |
+| Content loading, shape is known | `Skeleton` |
+| Content loading, shape is unknown | `Spinner` |
 ---
-## Component Usage Rules
+## 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
+// plain is sm only
 ```
-#### 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".
+**When to use each variant:**
+- `primary` — one per view, object creation, rightmost in Navbar
+- `secondary` — supports primary or equal-weight alternative
+- `ghost` — utility actions (filter, sort, export, copy)
+- `plain` — dismissive, space-constrained, sm only ("Cancel", "Skip")
-#### States
-`Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Loading` · `Selected` *(Toggle/Vertical only)*
+**Placement:** Ghost/Plain → Secondary → **Primary** (left to right)
+**Never:** `position: fixed/absolute` on any Button. Never two Primary buttons side by side.
-- `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.
+**States:** `Default` · `Hover` · `Pressed` · `Focused` · `Disabled` · `Loading` · `Selected` (Toggle/Vertical only)
+- `aria-pressed` only on Toggle/Vertical buttons — never on Main or Destructive.
+- `aria-busy="true"` when Loading.
-#### 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.
+**Content:** Strong verb first. "Save changes" not "OK". Sentence case. 1–5 words max.
-#### 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.
+**Variants:** `Profile` (person) · `Organization` (company/team)
+**Fill priority:** `Picture` → `Initials` → `Icon` (never show Icon when Initials are derivable)
+**Sizes:** `xxs` · `xs` · `sm` · `md` · `lg` · `xl` · `xxl` — consistent within a list, never mixed
+**AvatarGroup sizes:** `xxs`, `xs`, `sm` only. Show "+" overflow for lists beyond display limit.
-#### Fill priority (always use highest fidelity available)
-1. `Picture` — real photo/logo
-2. `Initials` — derived from name
-3. `Icon` — anonymous fallback
+**Initials:** Person → first + last initial ("Ana Costa" → "AC"). Max 2 chars, always uppercase.
-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.
+**Use for:** numeric counts and status signals attached to another element.
+**Never use when:** label is text → use Tag | user can dismiss → use Chip | count is zero → hide badge entirely.
-#### 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:** `Highlight soft` · `Highlight strong` · `Informative` · `Critical`
+**Count display:** ≤99 exact · >99 show "99+" · 0 remove badge entirely
-#### 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.
+See [Tag semantic mapping](#tag-semantic-mapping--critical) above.
-#### Tags have NO interaction states. Not clickable. Never.
+**Sizes:** `md` default · `sm` dense layouts. Consistent within a list, never mixed.
+**Max 3 tags per item.** Order: Error → Warning → Success → category.
+**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>
 ```
@@ -827,259 +822,83 @@ Use consistent sizes within a list. Never mix on the same row.
 ### 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
+**Use for:** user-togglable selections — filter controls, multi-value input.
+**Never use when:** purely informational → Tag | mutually exclusive form selection → Radio | settings toggle → Switcher.
-Never mix `md` and `sm` in the same chip group.
+**Sizes:** `md` default · `sm` compact. Never mix in the same 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.
+**Use for:** visual divider between related but distinct sections.
+**Do not use when:** spacing already separates sections | sections are separated by card borders.
-#### 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" />
+<hr />  // structural
+<div aria-hidden="true" />  // decorative only
 ```
 ---
 ### Switcher
-**Applies to: `Switcher`**
-#### When to use
-- Single binary setting, **effect is immediate** (no confirmation step).
-- Enabling features, notification settings, preferences.
+**Use for:** single binary setting with **immediate** effect.
+**Never use when:** requires confirmation → Checkbox | toolbar icon-only → Toggle button | choosing UI views → SegmentControl/Tabs.
-#### 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
+**Sizes:** `md` default · `sm` dense. Never mix within a group.
+**Always pair with a visible label.**
-#### 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).
+**Use for:** multiple independent options, staged (confirmed on submit).
+**Never use when:** single selection → Radio | immediate effect → Switcher.
-#### 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
+**Indeterminate:** `aria-checked="mixed"` when parent has partial sub-selection.
-#### 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>
+  <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**.
+**Use for:** exactly one from a mutually exclusive set (2–6 items), staged.
+**Never for:** 7+ options → Select | immediate effect → Switcher/SegmentControl.
-#### 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>
+  <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.
+**Use for:** 2–7 parallel, mutually exclusive content sections.
+**Never for:** sequential steps → stepper | filtering same content → Chip | display preference → SegmentControl.
-#### 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
+- One tab always selected. Tab labels: nouns only. Never nest tabs.
+- Keyboard: `←/→` between tabs, `Tab` into content panel.
-#### 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>
@@ -1087,165 +906,72 @@ No indeterminate state for Radio. A group always has 0–1 selected.
 </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"
+**Use for:** 2–5 mutually exclusive views with **immediate** effect.
+**Never for:** options with distinct content panels → Tabs | navigation | binary setting → Switcher.
+**Never replace with** plain text, custom buttons, or any non-DS-Nagarro component.
-#### 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
+- One selector always active. Equal-width selectors. Max 5 options.
-#### 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).
+See [NAV-06](#nav-06-breadcrumb-variants) and [NAV-07](#nav-07-breadcrumb-format) above.
-#### 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>
+<span aria-hidden="true">/</span>  // separator — decorative, never read aloud
 ```
 ---
 ### 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
+**Use for:** large datasets in data tables and record lists.
+**Never for:** continuous browsing → infinite scroll | compact panel → 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.
+- Always show first and last page numbers. Disable (never hide) Previous/Next at boundaries.
+- Show record count: "Showing 41–60 of 243 results".
-#### 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`**
+**Use for:** non-blocking confirmation of a completed action.
+**Never for:** critical actions requiring response → Modal | form field validation → inline validation.
-#### When to use
-- Confirm a completed action or surface a system event without interrupting the current task.
-- Non-blocking. Temporary.
+**Severity:** `Default` · `Success` · `Warning` · `Error` (Error persists until dismissed)
+**Auto-dismiss:** Default/Success 4–5s · Warning 6–8s · Error persistent
-#### 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
+<div aria-live="polite" role="status">Changes saved.</div>   // success/default/warning
+<div aria-live="assertive" role="alert">Save failed.</div>   // error only
 <button aria-label="Dismiss notification">×</button>
 ```
@@ -1253,125 +979,50 @@ Pause auto-dismiss on hover (desktop).
 ### 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.
+**Use for:** brief supplementary context on hover/focus. Icon-only button labels.
+**Never for:** content > 1 sentence → Popover | interactive content → Popover | disabled triggers.
-#### 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
+- Plain text only. One sentence max. Never on click.
-#### 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
+<button aria-describedby="tooltip-1">Export</button>
+<div role="tooltip" id="tooltip-1">Export table as CSV</div>
 ```
 ---
 ### 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
+**Use for:** contextual rich content anchored to an element. Opens on click only.
+**Never for:** 1 short sentence → Tooltip | full attention → Modal | extended task → Drawer.
+- Never nest popovers. Menu items auto-close on selection.
+- Form containers do NOT auto-close on outside click.
+- Positioning via shared `PopoverWrapper` — never re-implement.
 ```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
+**Use for:** user must complete a task or decide before continuing.
+**Never for:** informational only → Toast | long task → Drawer | anchored content → Popover.
+- Every modal needs a title and an explicit dismiss (× + Cancel).
+- One Primary action only. Never nest modals. Never auto-open on page load.
+- Focus trapped inside while open. Returns to trigger on close.
 ```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 */}
+  <p id="modal-desc">This cannot be undone.</p>
 </div>
 ```
@@ -1379,49 +1030,23 @@ Pause auto-dismiss on hover (desktop).
 ### 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
+[Label]        ← always required (visible or aria-label)
+[Control]      ← must have visible boundary
+[Helper text]  ← optional; real content or hidden — never leave placeholder text
+[Error]        ← 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
+**Validation timing:** on blur by default. Real-time only for password strength, character count, search, OTP.
+On form submit: show all errors at once, focus first errored field.
+**Every field is mandatory by default.** Only mark optional fields:
+`Team <span style="color: var(--color-text-tertiary)">Optional</span>`
 ```tsx
 <label htmlFor="email">Email address</label>
-<input
-  id="email"
-  aria-describedby="email-helper email-error"
-  aria-invalid={hasError}
-  aria-required={required}
-  disabled={disabled}
-/>
+<input id="email" aria-describedby="email-helper email-error"
+  aria-invalid={hasError} aria-required={true} />
 <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>
 ```
@@ -1429,764 +1054,262 @@ Pause auto-dismiss on hover (desktop).
 ---
 ### 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.
----
+Single-line free-form text. Do NOT use for: multi-line → TextArea | numbers → NumberInput | passwords → PasswordInput | phone → PhoneInput | search → SearchInput | fixed 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"
----
+Multi-line text. Minimum 3 lines height. Allow vertical resize. Show character count when limited: "120 characters remaining".
 ### SearchInput
-**Applies to: `SearchInput`**
-Search and filter interactions.
-- **Bordered**: standard, full border
-- **Borderless**: inline in toolbars/headers
+- **Bordered**: standard | **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>
-```
----
+- `Error` state: system errors only — NOT for "no results" (use EmptyState).
 ### 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"
-```
----
+Always include show/hide toggle. Show strength indicator for new passwords. `autocomplete="current-password"` or `"new-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
-```
----
+Auto-advance on character entry. Auto-submit on last field. Full paste support. Backspace clears and moves to previous field.
 ### 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.
----
+Define and enforce min/max. Stepper buttons disable at boundaries. Always allow direct keyboard entry. Do NOT use for currency or ranges.
 ### 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>
-```
----
+Always use for international numbers — never plain TextInput. Pre-select user's locale. `PopoverWrapper` for country dropdown.
 ### 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>
-```
----
+7+ options or space-constrained → Select. ≤6 options with space → Radio instead.
+Include placeholder that is NOT a valid value. Add search for 20+ options.
 ### 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"
-```
----
+Search-and-select multiple values. Each selected value becomes a chip. Backspace on empty removes last chip.
 ### 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.
----
+Label left, control right. Dense settings panels only. Do NOT use in standard forms, mobile, or with long labels.
 ### 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
-```
----
+- `Max value`: one handle | `Range`: two handles, cannot cross
+- Always show current value. Show min/max at track ends. Pair with NumberInput for precision.
 ### 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
-```
----
+Click-to-browse fallback always. State accepted types and size limits. Show upload progress after acceptance.
 ### 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"
-```
----
+Free-form entry. Confirm with Enter. Validate before converting. Backspace on empty removes last chip.
 ### 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
-```
----
+Human-readable format in trigger: "15 Jan 2026" not "2026-01-15". Do NOT pre-select today for historical dates. Range: show both months side by side when spanning months.
 ### 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.
+Unknown duration. Sizes: `sm` · `lg` · `xl` · `xxl`. Always pair with a label when standalone. Never multiple spinners simultaneously.
 ```tsx
-<div role="status" aria-label="Loading results">
-  <svg aria-hidden="true" />
-</div>
-// Completion: aria-live="polite"
+<div role="status" aria-label="Loading results"><svg aria-hidden="true" /></div>
 ```
----
 ### 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.
+Shape is known, load takes >~300ms. Always animate (shimmer/pulse — never static). Replace all skeletons simultaneously.
 ```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
-```
----
+- `ProgressBar`: measured progress. Always show percentage or step count alongside.
 ### 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**
+Non-interactive display element only. Platform-standard notation. Keys only: `⌘S` not `⌘ Save`.
 ---
 ## 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
+- Strong verb first: "Save", "Delete", "Export", "Send"
+- Specific: "Save changes" not "OK" or "Yes" or "Confirm"
+- 1–3 words; 5 maximum. Sentence case. Never truncate.
+- Destructive: name what is destroyed. "Delete account" not "Confirm".
+- Loading: present-progressive. "Saving…"
-### 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. |
+### Labels
+- Noun or noun phrase. Sentence case.
+- Describe the field: "Email address" not "Enter your email address".
-### 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
+### Error messages
+- Full sentences with full stop. Specific and instructive.
+- Do not blame the user: "Please enter a valid email" not "You entered an invalid email".
-### 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
+| Situation | Pattern |
+|---|---|
+| Required field empty | Please enter [field name]. |
+| Too long | Please enter fewer than [N] characters. |
+| Wrong format | Please enter [field name] in the correct format. |
+| System fault | Sorry, [what happened]. Please [action]. |
-### Chips
-- 1–3 words. Sentence case.
-- Nouns or adjectives. All chips in a group must be parallel in structure.
-- Never truncate with ellipsis — rewrite
+### Toasts
+- Lead with outcome: "Changes saved" not "We are saving your changes".
+- No "Successfully" prefix — state the outcome directly.
-### Tabs / Segment control
-- 1–3 words for tabs, 1–2 words for segment control
-- Nouns only. No verbs, no questions.
-- Sentence case.
+### Tags and Chips
+- 1–3 words. Sentence case. Label and variant must tell the same story.
 ### 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.
+- Title: 2–5 words, no punctuation at end.
+- Description: 1–2 lines with full stop.
+- CTA: 1–3 words, verb-first.
+- Never use "Oops" or "Uh oh".
+### Modals
+- Title: 3–6 words, sentence case. "Delete project" not "Are you sure?"
+- Primary action: specific verb. "Delete" not "OK" or "Confirm".
+- 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.
+- Normal text: WCAG AA minimum 4.5:1 | Large text: 3:1 minimum
 ### Focus
-- Always use `:focus-visible`, never `:focus` as the visible ring trigger.
+- Always `: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)`.
+- Focus must never be hidden by `overflow: hidden` on a parent.
+### Keyboard
+- All interactive elements keyboard operable. Focus order: top-to-bottom, left-to-right.
+- Closed disclosure components: children NOT keyboard-reachable until open.
+- Every popup/dropdown: Arrow keys navigate · Enter/Space select · Escape closes and returns focus.
 ### 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`.
+- Native: `disabled` attribute (removed from tab order).
+- Custom: `tabIndex={-1}` + `aria-disabled="true"`.
+- Never focusable unless user needs to discover it exists.
 ### 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
+Color alone must never convey meaning. Always pair with text, icon, or pattern.
+### Forms
+- Every input needs a programmatic label.
+- Helper text and errors: `aria-describedby`. Error state: `aria-invalid="true"`.
+- All inputs: `aria-required="true"` by default. Optional fields: omit or set `false`.
+- Errors persist until resolved — never auto-dismiss.
+### Loading
 - `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.
+- Spinner graphic: `aria-hidden="true"` — the label carries the meaning.
 ### 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
+- `aria-live="polite"` — success/default/warning toasts, spinner completion.
+- `aria-live="assertive"` — error toasts only.
 ### Custom widget keyboard contracts
-| Widget type | Required keyboard behavior |
+| Widget | Required 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) |
+| `radio` | Arrow keys move selection |
 | `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)
+| `gridcell` | Roving tabindex; Arrow keys navigate; Enter selects |
+---
+## What NOT to do
+### Layout
+- ❌ Build layout with raw divs — always use `AppShell`
+- ❌ Add `min-height`, `height`, or sizing directly to `<AppShell>`
+- ❌ Skip the `<div style={{ height: '100vh', display: 'flex' }}>` wrapper around AppShell
+- ❌ Skip the `paddingInline: var(--page-margin-x)` content wrapper inside AppShell
+- ❌ Apply scroll to the full page — only the content area scrolls
+- ❌ Apply spacing tokens directly on a DS-Nagarro component — wrappers only
+- ❌ Add padding/margin directly to `<Card>` — wrap children in a div instead
+- ❌ Leave Card children without a padding wrapper
+- ❌ Add padding/margin/gap to Card header (`SectionHeader`) or bottom bar (`Toolbar`)
+- ❌ Wrap `DataTable` in a `Card`
+- ❌ Place the primary CTA inside a Card or content area
+- ❌ Create a floating action button — use Navbar `rightActions`
+- ❌ Use `position: fixed` or `position: absolute` on any Button
+- ❌ Nest tabs within tabs
+- ❌ Place pagination above content — always below
+- ❌ Mix Pagination and infinite scroll in the same view
+- ❌ Place Breadcrumbs inside cards, modals, or drawers
+- ❌ Place LoadingBar inline — top of viewport only
+- ❌ Show more than 3 tags on a single item
+- ❌ Mix Avatar, Chip, Checkbox, Radio, or Switcher sizes within the same group
+### Typography
+- ❌ Set `font-family` anywhere in app code
+- ❌ Use raw `<h1>`–`<h6>` or `<p>` with custom font styling
+- ❌ Set `font-size` with raw pixel values
+- ❌ Use serif, system, or any non-design-system font
 ### 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.
-- ❌ Apply `padding-inline: var(--page-margin-x)` to a DS-Nagarro component — only to your own wrapper div inside the content area.
-- ❌ Use hardcoded `padding-left`, `padding-right`, `margin-left`, or `margin-right` — always use `var(--page-margin-x)` on your own wrapper elements.
-- ❌ Add padding, margin, gap, or any spacing override directly to a DS-Nagarro component element. All components have internal spacing built in — overriding it breaks their proportions. To space components relative to each other, apply spacing tokens to wrapper/container elements only.
-- ❌ Add padding, margin, or gap to the Card header (`SectionHeader`) or bottom bar (`Toolbar`) — they are pre-built component instances with their own spacing.
-- ❌ Leave Card `children` without a padding wrapper — always wrap in a div with `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.
+- ❌ Hardcode hex values, pixel sizes, or rgba
+- ❌ Use primitive tokens (`--primitive-neutral-900`) in app code
+- ❌ Use `--inset-*` for gaps between elements — use `--space-*`
+- ❌ Use `--space-*` for padding inside components — use `--inset-*`
+- ❌ Use generic semantic tokens or hardcoded hex for dataviz — use `--color-dataviz-*`
+- ❌ Override dark mode with `@media (prefers-color-scheme: dark)` — use `data-theme="dark"`
+### Buttons and CTAs
+- ❌ Place two Primary buttons side by side
+- ❌ Use vague labels: "OK", "Yes", "Confirm", "Click here", "Proceed"
+- ❌ Use `aria-pressed` on Main or Destructive buttons
+- ❌ Truncate a button label with ellipsis
+### Components
+- ❌ Use Tag when element is interactive — use Chip
+- ❌ Use Chip when element is purely informational — use Tag
+- ❌ Use Badge when label is text — use Tag
+- ❌ Use same Tag variant for all tags in a list
+- ❌ Make a Tag clickable
+- ❌ Use SegmentControl for options with distinct content panels — use Tabs
+- ❌ Replace SegmentControl with plain text or custom buttons
+- ❌ Use Checkbox when effect is immediate — use Switcher
+- ❌ Use Switcher when effect requires confirmation — use Checkbox
+- ❌ Use Radio for 7+ options — use Select
+- ❌ Open a Modal from within a Modal
+- ❌ Auto-open modals on page load
+- ❌ Use Toast for actions requiring user response — use Modal
+- ❌ Use Spinner when content shape is known — use Skeleton
+- ❌ Use Plain variant Button in `md` size — Plain is `sm` only
+### Icons and placeholders
+- ❌ Use any icon library other than `lucide-react`
+- ❌ Install `lucide-react` separately — it is bundled inside `@ngrr/ds`
+- ❌ Leave placeholder icons, help text, or hint icons in place
 ### 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.
+- ❌ Mark required fields with a red asterisk
+- ❌ Enable primary CTA before all mandatory fields have a value
+- ❌ Validate in real time as the user types (except: password strength, character count, search, OTP)
+- ❌ Omit `⌘↵` shortcut from the primary submit button
+### Content
+- ❌ Title case anywhere — always sentence case
+- ❌ Use "Oops", "Uh oh" in empty or error states
+- ❌ Use "Successfully" as a toast prefix
+- ❌ Use "Are you sure?" as a modal title
+- ❌ Show badge with count 0 — hide it entirely
+- ❌ Show badge count above 99 — show "99+"
+- ❌ 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`
+- ❌ Use color alone to convey meaning
+- ❌ Use `:focus` for visible rings — always `:focus-visible`
+- ❌ Use `outline: none` without an explicit replacement
+- ❌ Leave disabled custom elements focusable
+- ❌ Allow focus to reach elements inside closed disclosure components
+- ❌ Allow focus to escape an open modal
+- ❌ Show static (non-animated) skeleton shapes
+- ❌ Replace skeleton placeholders one by one — replace all simultaneously
 ---
-*Single source of truth for consuming DS-Nagarro. Last updated: 2026-03-16.*
+*Single source of truth for consuming DS-Nagarro. Last updated: 2026-04-01.*
 *Source files: `docs/foundations.md`, `docs/ds-guidelines.md`, and all component docs in `docs/`.*