@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/general/media-viewer.md

@@ -0,0 +1,78 @@
+# Image Viewer
+
+## Metadata
+- Component: Image Viewer
+- Slug: `media-viewer`
+- Category: General
+- Install: `npx sdaia-ui@latest add media-viewer`
+- Import: `import { MediaViewer } from '@/components/ui/MediaViewer'`
+- Installed files: `MediaViewer.tsx`, `MediaViewer.types.ts`, `MediaViewer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/image-viewer
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add media-viewer`. It copies the source into your components folder (`components/ui/MediaViewer/`, under `src/` when the project has one); import it as `@/components/ui/MediaViewer`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | Whether the viewer is open. |
+| `onClose` | `() => void` | — | Called when the viewer should close (close button, backdrop click, Escape key). |
+| `images?` | `MediaViewerImage[]` | [] | List of images to view. |
+| `currentIndex?` | `number` | — | 0-based index of the currently visible image (controlled). |
+| `onIndexChange?` | `(index: number) => void` | — | Called when the user navigates to a different image. |
+| `zoom?` | `number` | — | Zoom level (1 = 100 %, 2 = 200 %, etc.). When provided the component is fully controlled for zoom. When omitted the component manages zoom internally. |
+| `onZoomChange?` | `(zoom: number) => void` | — | Called when zoom changes. |
+| `minZoom?` | `number` | 0.5 | Minimum zoom. Default 0.5 |
+| `maxZoom?` | `number` | 3 | Maximum zoom. Default 3 |
+| `zoomStep?` | `number` | 0.25 | Zoom step per click. Default 0.25 |
+| `onShare?` | `() => void` | — | Called when the Share button is clicked. |
+| `onPrint?` | `() => void` | — | Called when the Print button is clicked. |
+| `overlay?` | `boolean` | false | Overlay mode — image fills the full area and all controls (header, arrows, zoom) are absolutely positioned on top of it. Default: false (Standard mode — header above, image, zoom below). |
+| `labels?` | `Partial<MediaViewerLabels>` | — | Translatable built-in text. Unset keys use the English defaults. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the page when omitted. In RTL the layout mirrors: "previous" sits on the right and ArrowLeft goes to the next image. |
+| `contained?` | `boolean` | false | Render inline instead of as a fixed full-viewport overlay. Skips createPortal and body scroll lock — use in docs/demos where the viewer should be embedded in the page rather than covering it. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the page when omitted. In RTL the layout
+mirrors: "previous" sits on the right and ArrowLeft goes to the next image.
+
+## Deprecated props
+Do not use in new code:
+- `rtl` — Enable right-to-left layout.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-alpha-black-50)`
+- `var(--ds-brand-alpha-black-70)`
+- `var(--ds-brand-alpha-black-80)`
+- `var(--ds-color-alpha-black-)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-border-on-dark-40)`
+- `var(--ds-color-button-bg-transparent-)`
+- `var(--ds-color-button-bg-transparent-hovered)`
+- `var(--ds-color-button-bg-transparent-pressed)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-on-color-subtle)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-7xl)`
+- `var(--ds-spacing-8xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add media-viewer` (after `npx sdaia-ui@latest init`), then import `{ MediaViewer }` from `@/components/ui/MediaViewer`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/menu.md

@@ -0,0 +1,66 @@
+# Menu
+
+## Metadata
+- Component: Menu
+- Slug: `menu`
+- Category: General
+- Install: `npx sdaia-ui@latest add menu`
+- Import: `import { Menu } from '@/components/ui/Menu'`
+- Installed files: `Menu.tsx`, `Menu.types.ts`, `Menu.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/menu
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add menu`. It copies the source into your components folder (`components/ui/Menu/`, under `src/` when the project has one); import it as `@/components/ui/Menu`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root element. Inherits from the page when omitted. |
+| `sections?` | `MenuSectionData[]` | — | Sections to render. Each section is a group label + list of items, separated by a divider. |
+| `value?` | `string \| null` | — | Controlled selected value. |
+| `defaultValue?` | `string \| null` | null | Uncontrolled initial selected value. |
+| `onValueChange?` | `(value: string) => void` | — | Fires when the user selects an item. Receives the item's `value` (or its fallback key). |
+| `background?` | `boolean` | false | Show the menu background (white / dark surface). Defaults to `false` (transparent). |
+| `border?` | `boolean` | false | Show the outer border. Defaults to `false`. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). `'glass'` overrides `background` / `border`. |
+| `divider?` | `boolean` | true | Render dividers between sections. Defaults to `true`. |
+| `children?` | `ReactNode` | — | Custom content — if provided, overrides `sections` so consumers can compose freely. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root element. Inherits from the page when omitted.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the menu container.
+  - `'solid'` (default) — honors the `background` / `border` toggles.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Provides its own background and edge, so it
+    overrides `background` / `border`. Reads best placed over imagery or color.
+
+The visual is provided by the shared `.glass-surface` utility, so it is
+theme-aware (light / dark) and identical across every component that
+exposes a `surface` prop.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add menu` (after `npx sdaia-ui@latest init`), then import `{ Menu }` from `@/components/ui/Menu`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/metric.md

@@ -0,0 +1,92 @@
+# Metric
+
+## Metadata
+- Component: Metric
+- Slug: `metric`
+- Category: General
+- Install: `npx sdaia-ui@latest add metric`
+- Import: `import { Metric } from '@/components/ui/Metric'`
+- Installed files: `Metric.tsx`, `Metric.types.ts`, `Metric.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/metric
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add metric`. It copies the source into your components folder (`components/ui/Metric/`, under `src/` when the project has one); import it as `@/components/ui/Metric`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `action?` | `'Default' \| 'Footer' \| 'Header'` | 'Default' | Card action layout. - Default: no action bar; MoreVertical (⋮) lives in the label row only. - Header:  "View report" link in a top bar (border-b), content below. - Footer:  Content at top, then "View report" link / outlined button in a bottom bar (border-t). |
+| `type?` | `'Compact' \| 'Icon Left' \| 'Icon Top' \| 'Icon Left + Text'` | 'Compact' | Icon and layout variant. - Compact:          No icon. Label row + value row. - Icon Left:        40 px star to the start; label + value stacked in the adjacent column. - Icon Top:         40 px star alone in the heading row; label then value below. - Icon Left + Text: Star + label share the heading row; value + trend below. |
+| `trend?` | `'None' \| 'Badge' \| 'Text'` | 'None' | Trend indicator variant shown next to (or below) the value. - None:  No indicator. - Badge: Bordered pill with a green dot and `trendValue` text (e.g. "100%"). - Text:  Coloured `trendValue` followed by muted `trendLabel` (e.g. "100% vs last month"). |
+| `graph?` | `'None' \| 'Compact' \| 'Large'` | 'None' | Sparkline graph variant. - None:    No chart. - Compact: Fixed 128×64 px sparkline aligned to the end of the value row. - Large:   Full-width sparkline below the content. |
+| `chartTrend?` | `SparklineTrend` | 'Positive' | Trend direction for the embedded sparkline. |
+| `chartValues?` | `number[]` | — | Data points plotted by the sparkline (`graph="Compact"` / `"Large"`). The chart is then exposed as a figure named by `label` (or `labels.chart`). Without it no sparkline is drawn (there is no built-in sample shape). |
+| `label?` | `string` | — | Metric label / title text. Not rendered when omitted. |
+| `value?` | `string` | — | Main metric value (e.g. "2,000"). Not rendered when omitted. |
+| `trendValue?` | `string` | — | Percentage or indicator value used by both `trend="Badge"` and `trend="Text"`. - Badge: shown as the text inside the pill (e.g. "100%"). - Text:  shown in accent colour before `trendLabel` (e.g. "100%"). |
+| `trendLabel?` | `string` | — | Secondary label appended after `trendValue` when `trend="Text"`. (e.g. "vs last month") |
+| `actionLabel?` | `string` | — | Action button label shown in the header / footer bar (e.g. "View report"). The bar is only rendered when a label is provided. |
+| `onAction?` | `() => void` | — | Called when the action button is clicked. |
+| `onMoreOptions?` | `() => void` | — | Called when the MoreVertical (⋮) icon is clicked. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `labels?` | `Partial<MetricLabels>` | — | Override built-in strings (English defaults) to localize the card. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `action`: `'Default'` \| `'Footer'` \| `'Header'` — Card action layout.
+- Default: no action bar; MoreVertical (⋮) lives in the label row only.
+- Header:  "View report" link in a top bar (border-b), content below.
+- Footer:  Content at top, then "View report" link / outlined button in a bottom bar (border-t).
+- `type`: `'Compact'` \| `'Icon Left'` \| `'Icon Top'` \| `'Icon Left + Text'` — Icon and layout variant.
+- Compact:          No icon. Label row + value row.
+- Icon Left:        40 px star to the start; label + value stacked in the adjacent column.
+- Icon Top:         40 px star alone in the heading row; label then value below.
+- Icon Left + Text: Star + label share the heading row; value + trend below.
+- `trend`: `'None'` \| `'Badge'` \| `'Text'` — Trend indicator variant shown next to (or below) the value.
+- None:  No indicator.
+- Badge: Bordered pill with a green dot and `trendValue` text (e.g. "100%").
+- Text:  Coloured `trendValue` followed by muted `trendLabel` (e.g. "100% vs last month").
+- `graph`: `'None'` \| `'Compact'` \| `'Large'` — Sparkline graph variant.
+- None:    No chart.
+- Compact: Fixed 128×64 px sparkline aligned to the end of the value row.
+- Large:   Full-width sparkline below the content.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-chart-lavender)`
+- `var(--ds-color-chart-series-)`
+- `var(--ds-color-chart-series-1)`
+- `var(--ds-color-chart-series-2)`
+- `var(--ds-color-icon-default-400)`
+- `var(--ds-color-link-primary-hovered)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-display-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add metric` (after `npx sdaia-ui@latest init`), then import `{ Metric }` from `@/components/ui/Metric`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/nav-bar.md

@@ -0,0 +1,62 @@
+# Nav Bar
+
+## Metadata
+- Component: Nav Bar
+- Slug: `nav-bar`
+- Category: General
+- Install: `npx sdaia-ui@latest add nav-bar`
+- Import: `import { NavBar } from '@/components/ui/NavBar'`
+- Installed files: `NavBar.tsx`, `NavBar.types.ts`, `NavBar.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/nav-bar
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add nav-bar`. It copies the source into your components folder (`components/ui/NavBar/`, under `src/` when the project has one); import it as `@/components/ui/NavBar`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. Omit to inherit the ambient direction from the page. |
+| `variant?` | `'default' \| 'gray' \| 'brand'` | 'default' | Visual background / colour variant. Controls sidebar background, text colours, and icon colours across all composed sub-components. |
+| `collapsed?` | `boolean` | false | Whether the sidebar is in its collapsed (icon-only) state. - Desktop collapsed → 64 px wide, icons only. - Mobile collapsed  → full-width 68 px header strip with hamburger icon. Pass `false` for the expanded (full) view. |
+| `mobile?` | `boolean` | — | Enable mobile layout mode. - When `collapsed` is true  → renders only the header strip + hamburger. - When `collapsed` is false → renders a modal overlay drawer (focus is moved into it, trapped, and returned to the hamburger on close). Omit to switch automatically below 768 px. |
+| `onToggle?` | `() => void` | — | Called when the header toggle (desktop), the hamburger (mobile collapsed) or the close button (mobile expanded) is activated, and on Escape in the mobile drawer. The parent is responsible for toggling `collapsed`. |
+| `headerProps?` | `Omit<HeaderItemProps, 'variant' \| 'size'>` | — | Props forwarded to the built-in `HeaderItem` at the top of the sidebar. The `variant` and `size` props are derived from the NavBar's own `variant` and `collapsed` props — do not override them here. An `aria-label` passed here overrides the toggle label from `labels`. |
+| `footerProps?` | `Omit<FooterItemProps, 'variant' \| 'size'>` | — | Props forwarded to the built-in `FooterItem` at the bottom of the sidebar. The `variant` and `size` props are derived from the NavBar — do not override them here. |
+| `groups?` | `NavBarGroup[]` | [] | Navigation groups to render in the scrollable content area. Items render as buttons in a list; the selected item carries `aria-current="page"`. |
+| `labels?` | `Partial<NavBarLabels>` | — | Override the built-in accessible strings (English defaults). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Omit to inherit the ambient
+direction from the page.
+- `variant`: `'default'` \| `'gray'` \| `'brand'` — Visual background variant of the sidebar.
+- `default`  — `--ds-color-bg-default` background
+- `gray`     — `--ds-color-bg-canvas` background
+- `brand`    — `--ds-color-bg-brand` background, on-color text on all sub-components
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-alpha-black-40)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-canvas)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-primitive-alpha-black-40)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add nav-bar` (after `npx sdaia-ui@latest init`), then import `{ NavBar }` from `@/components/ui/NavBar`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/nav-header.md

@@ -0,0 +1,125 @@
+# Nav Header
+
+## Metadata
+- Component: Nav Header
+- Slug: `nav-header`
+- Category: General
+- Install: `npx sdaia-ui@latest add nav-header`
+- Import: `import { NavHeader } from '@/components/ui/NavHeader'`
+- Installed files: `NavHeader.tsx`, `NavHeader.types.ts`, `NavHeader.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/nav-header
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add nav-header`. It copies the source into your components folder (`components/ui/NavHeader/`, under `src/` when the project has one); import it as `@/components/ui/NavHeader`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Description
+NavHeader props.
+
+Extends `HTMLAttributes<HTMLElement>` (minus `title`, which we shadow so
+consumers can pass a richer ReactNode label for the mobile footer block).
+
+The component is *pure composition* — every interactive sub-element
+is a separate `sdaia-ui` component that the consumer passes in:
+
+  - `logo`      → typically `<NavLogoPlaceholder size="medium" text="…" />`
+  - `items`     → array of `<NavHeaderMenuItem />` (desktop row / mobile stack)
+  - `search`    → a `<TextInput placeholder="Search" />`
+  - `actions`   → a `<NavHeaderActions />`
+  - `menuContent` → what to render inside the expanded dropdown/drawer.
+                    Typically `<NavHeaderDropdownItemList />`,
+                    `<NavHeaderMenuCard />`, or any combination.
+  - `mobileFooter` → optional footer block for the mobile drawer
+                     (links + NavHeaderActions).
+
+This keeps NavHeader agnostic to concrete content (labels, hrefs, copy,
+localisation) and prevents us from duplicating the public APIs of the
+reused components.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'default' \| 'menu' \| 'menu-compact'` | 'default' | Visual type — controls which menu-panel density is rendered when `menuOpen` is true. When `type='default'` the menu panel is never rendered regardless of `menuOpen`. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). Applies to the bar plus the desktop dropdown and mobile drawer. |
+| `mobile?` | `boolean` | — | Layout override. - `undefined` (default — recommended for app code) Auto-responsive: renders BOTH branches and uses CSS to switch at the `md` breakpoint (≥768 px → desktop bar, <768 px → mobile bar + drawer). The same `<NavHeader />` adapts to any viewport without a JS resize listener. - `true` → force the mobile layout regardless of viewport. Useful for documentation demos that want to showcase the mobile variant inside a desktop preview frame. - `false` → force the desktop layout regardless of viewport. Useful for documentation demos that want to showcase the desktop variant inside a constrained preview frame. |
+| `menuOpen?` | `boolean` | false | Whether the menu panel (desktop dropdown or mobile drawer) is open. Controlled. The component toggles the hamburger glyph to match but never owns this state itself — the consumer passes the latest value via props and updates it in response to `onOpenChange`. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Fires when the user clicks the mobile hamburger or × button. The consumer is expected to flip `menuOpen` in response. Ignored on desktop (where menu open/close is driven by individual `<NavHeaderMenuItem open>` buttons in the bar). |
+| `onDropdownClose?` | `() => void` | — | Fires when the user presses Escape while focus is inside the open desktop dropdown panel (or on its trigger). Close the dropdown in response (flip the open `<NavHeaderMenuItem open>` to `false`); focus returns to that trigger automatically. Escape inside the open mobile drawer calls `onOpenChange(false)` and returns focus to the menu toggle. |
+| `labels?` | `Partial<NavHeaderLabels>` | — | Override the built-in accessible strings (English defaults). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root `<nav>`; inherits from the page when omitted. |
+| `logo?` | `ReactNode` | — | Logo slot — typically `<NavLogoPlaceholder size="medium" text="…" />`. Nothing is rendered when omitted (no sample logo). |
+| `items?` | `ReactNode[]` | — | Main navigation items — one entry per `<NavHeaderMenuItem />`. On desktop they render as a horizontal row inside the bar; on mobile they render stacked inside the drawer, interleaved with any `menuContent` the consumer passes. When empty / omitted, the item row is hidden on desktop and the mobile drawer falls back to rendering only `search`, `menuContent`, `mobileFooter`, and `actions`. |
+| `search?` | `ReactNode` | — | Search input. Rendered inline between the items and the actions on desktop; rendered at the top of the drawer on mobile. Omit to hide. Typically `<TextInput placeholder="Search" fullWidth />`. |
+| `actions?` | `ReactNode` | — | Trailing cluster — Log in / Sign Up buttons (logged-out) or an avatar + identity (logged-in). Typically `<NavHeaderActions />`. Rendered inline on desktop; stacked at the bottom of the drawer on mobile. |
+| `menuContent?` | `ReactNode` | — | Content rendered inside the expanded menu panel. On desktop this renders as an absolutely-positioned dropdown below the bar; on mobile it renders inline inside the drawer, between `search` and the footer. Ignored when `type='default'`, or when `menuOpen` is false on mobile. On desktop the dropdown is only shown when `type !== 'default'` AND at least one `<NavHeaderMenuItem open>` is in `items` — i.e. the consumer controls open/close by flipping the `open` prop on the relevant item. |
+| `mobileFooter?` | `ReactNode` | — | Mobile-only footer block shown at the bottom of the drawer — typically a `<div>` with secondary-link columns. Omit to hide. Has no effect on desktop. |
+| `className?` | `string` | — | Extra classes merged onto the root element. |
+| `barClassName?` | `string` | — | Extra classes merged onto the inner bar `<div>` (the element that carries the responsive horizontal padding). Use this to override padding in constrained contexts such as documentation preview frames, e.g. `barClassName="px-spacing-xl"`. |
+| `dropdownClassName?` | `string` | — | Extra classes merged onto the desktop dropdown panel `<div>`. The full panel (`type="menu"`) aligns its columns with responsive `px-*`; the compact panel (`type="menu-compact"`) sits inside the bar gutter with responsive `inset-x-*`. Use this alongside `barClassName` to keep the dropdown edge-aligned with a locked bar, e.g. `dropdownClassName="px-spacing-xl"` (menu) or `dropdownClassName="inset-x-spacing-xl"` (menu-compact). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `type`: `'default'` \| `'menu'` \| `'menu-compact'` — Layout tier — drives the structure of the header bar and, when a menu
+panel is present, the visual density of the dropdown.
+
+ - `default`       → header bar only, no menu panel
+ - `menu`          → header bar + full menu panel: flush under the bar,
+                     full width, flat (no radius or shadow), with a
+                     separator line under the bar while it is open;
+                     full drawer on mobile
+ - `menu-compact`  → header bar + compact menu panel: a floating card
+                     inset by the bar gutter, 8 px below the bar, rounded,
+                     with a drop shadow; same drawer on mobile
+
+Both panels use Background/background-raised. The component does not
+generate the content; the consumer passes it in via `menuContent`.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the header shell (bar + dropdown + drawer).
+  - `'solid'` (default) — opaque backgrounds, with the standard drop
+    shadow on the floating compact dropdown and the drawer.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Reads best when the header overlays imagery
+    or color, e.g. a sticky bar above a hero.
+
+The visual is provided by the shared `.glass-surface` utility, so it is
+theme-aware (light / dark) and identical across every component that
+exposes a `surface` prop. Orthogonal to `type` and `menuOpen`.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root `<nav>`; inherits from the page
+when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-spacing-space-3)`
+- `var(--ds-brand-spacing-space-4)`
+- `var(--ds-brand-spacing-space-5)`
+- `var(--ds-brand-spacing-space-6)`
+- `var(--ds-brand-spacing-space-N)`
+- `var(--ds-color-)`
+- `var(--ds-color-bg-canvas)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-8xl)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add nav-header` (after `npx sdaia-ui@latest init`), then import `{ NavHeader }` from `@/components/ui/NavHeader`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/number.md

@@ -0,0 +1,72 @@
+# Number
+
+## Metadata
+- Component: Number
+- Slug: `number`
+- Category: General
+- Install: `npx sdaia-ui@latest add number`
+- Import: `import { Number } from '@/components/ui/Number'`
+- Installed files: `Number.tsx`, `Number.types.ts`, `Number.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/number
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add number`. It copies the source into your components folder (`components/ui/Number/`, under `src/` when the project has one); import it as `@/components/ui/Number`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'StatPair' \| 'StatHighlight' \| 'StatSplit' \| 'StatComparisonBlock' \| 'StatSideList' \| 'StatExtendedPanel' \| 'StatMixedStack' \| 'StatOptionBlock' \| 'StatDetailPair' \| 'StatInlineGroup' \| 'StatHeaderSplit' \| 'StatListStack'` | 'StatPair' | Layout type. |
+| `label?` | `string` | — | Label / indicator name above the primary value. Not rendered when unset. |
+| `value?` | `string` | — | Large primary value (e.g. "422.61"). Not rendered when unset. |
+| `trend?` | `'positive' \| 'negative'` | 'positive' (layouts with a badge) | Trend direction for the primary badge. |
+| `trendValue?` | `string` | — | Trend badge text (e.g. "12%"). The badge renders only when this is set. |
+| `label2?` | `string` | — | — |
+| `value2?` | `string` | — | — |
+| `trend2?` | `'positive' \| 'negative'` | 'negative' (layouts with a badge) | Trend direction for the secondary badge. |
+| `trendValue2?` | `string` | — | — |
+| `title?` | `string` | — | Card title — StatInlineGroup only. Not rendered when unset. |
+| `rows?` | `NumberRow[]` | [] | Up to 3 secondary data rows (label + medium value, optional badge). |
+| `menuLabel?` | `string` | — | Dropdown button label — StatExtendedPanel only. Wins over `labels.menu`. |
+| `onMenuClick?` | `() => void` | — | — |
+| `onMoreClick?` | `() => void` | — | More-options (⋮) click handler — StatInlineGroup only |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the card. Unset inherits from the closest `dir` ancestor. |
+| `labels?` | `Partial<NumberLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `type`: `'StatPair'` \| `'StatHighlight'` \| `'StatSplit'` \| `'StatComparisonBlock'` \| `'StatSideList'` \| `'StatExtendedPanel'` \| `'StatMixedStack'` \| `'StatOptionBlock'` \| `'StatDetailPair'` \| `'StatInlineGroup'` \| `'StatHeaderSplit'` \| `'StatListStack'` — Layout type.
+- `trend`: `'positive'` \| `'negative'` — Trend direction for the primary badge.
+- `trend2`: `'positive'` \| `'negative'` — Trend direction for the secondary badge.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the card. Unset inherits from the closest `dir` ancestor.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add number` (after `npx sdaia-ui@latest init`), then import `{ Number }` from `@/components/ui/Number`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/page-template.md

@@ -0,0 +1,80 @@
+# Page Template
+
+## Metadata
+- Component: Page Template
+- Slug: `page-template`
+- Category: General
+- Install: `npx sdaia-ui@latest add page-template`
+- Import: `import { PageTemplate } from '@/components/ui/PageTemplate'`
+- Installed files: `PageTemplate.tsx`, `PageTemplate.types.ts`, `PageTemplate.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/page-template
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add page-template`. It copies the source into your components folder (`components/ui/PageTemplate/`, under `src/` when the project has one); import it as `@/components/ui/PageTemplate`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'list' \| 'detail' \| 'form' \| 'settings' \| 'dashboard' \| 'sign-in' \| 'error-403' \| 'error-404' \| 'error-500'` | 'list' | Figma `Type`. |
+| `shell?` | `PageTemplateShellProps` | — | Renders the page inside an `AppShell` with these props (header, side navigation…). Omit when the page already sits in an App Shell, e.g. one placed in a shared layout. Ignored by `sign-in`. The Figma error templates use the shell without `sideNavigation`. |
+| `title` | `ReactNode` | — | Page title, rendered as the page's `<h1>` (sign-in card heading, error title). |
+| `description?` | `ReactNode` | — | Supporting text under the title: the sign-in subtitle, the error explanation, or an optional intro line on app pages. |
+| `breadcrumb?` | `ReactNode` | — | App pages: breadcrumb above the title, typically a `<Breadcrumb />`. |
+| `status?` | `ReactNode` | — | App pages: element next to the title, e.g. a status `<Badge />` (Detail). |
+| `actions?` | `ReactNode` | — | App pages: page-level buttons at the end of the title row. Error pages: recovery buttons under the description. |
+| `aside?` | `ReactNode` | — | App pages: secondary column (360 px) beside the content once the page is 960 px wide, stacked under it below (e.g. the Detail template's side cards). The page width is measured with a container query (`@container/page-template`), so it also works in a narrow box. |
+| `logo?` | `ReactNode` | — | Sign-in: logo at the top of the card, typically `<NavLogoPlaceholder />`. |
+| `code?` | `ReactNode` | — | Error pages: the status code. Defaults to the code of the `type` (`403`, `404`, `500`). |
+| `footer?` | `ReactNode` | — | Sign-in: line at the bottom of the card (e.g. a help link). Error pages: small print under the actions (e.g. the error reference). |
+| `children?` | `ReactNode` | — | App pages: the page content under the header (or beside `aside`). Sign-in: the form inside the card. Error pages: extra content under the message. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. Omit to inherit the ambient direction. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`, `children`.
+
+## Options (allowed values)
+- `type`: `'list'` \| `'detail'` \| `'form'` \| `'settings'` \| `'dashboard'` \| `'sign-in'` \| `'error-403'` \| `'error-404'` \| `'error-500'` — Figma `Type` — which starting-point template the page follows.
+
+The type picks the page frame:
+- `list` · `detail` · `form` · `settings` · `dashboard` → app page: page
+  header (breadcrumb, title, status, actions) above the page content,
+  inside the App Shell. These five share the frame; they differ in the
+  content you compose (table, cards, form sections, metrics…).
+- `sign-in` → a centred card on the canvas, without the App Shell.
+- `error-403` · `error-404` · `error-500` → a centred status message
+  (code, title, description, recovery actions, reference).
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. Omit to inherit the ambient direction.
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-canvas)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-display-2xl)`
+- `var(--ds-text-leading-line-heights-display-sm)`
+- `var(--ds-text-leading-line-heights-display-xs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add page-template` (after `npx sdaia-ui@latest init`), then import `{ PageTemplate }` from `@/components/ui/PageTemplate`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.