@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/foundations/typography.md

@@ -0,0 +1,45 @@
+# SDAIA Typography
+
+## Typeface
+
+**IBM Plex Sans Arabic** is the official SDAIA typeface for Arabic and Latin text. `npx sdaia-ui@latest init` installs it (`@fontsource/ibm-plex-sans-arabic`, weights 400 / 500 / 600 / 700), imports it from the app entry (`app/layout.tsx`, `pages/_app.tsx` or `src/main.tsx`) and points the font tokens at it. Other brands use their own Latin font and fall back to IBM Plex Sans Arabic for Arabic (topic `theme`).
+
+Do **not** add a Google Fonts `<link>`, a manual `@font-face` or `font-family: system-ui` — they replace or duplicate what `init` set up. The body already uses `var(--ds-text-family-text)`; headings that need the display family use `var(--ds-text-family-display)`.
+
+## Type scale — use the utilities
+
+`init` adds one utility per Figma text style. Each sets **both the size and the line height**, and both step down automatically on tablet (< 1280px) and phone (< 768px):
+
+| Utility | Desktop (size / line height) | Use for |
+| --- | --- | --- |
+| `text-display-2xl` / `-xl` / `-lg` | 72/90 · 60/72 · 48/60 | Hero and landing titles |
+| `text-display-md` / `-sm` / `-xs` | 36/44 · 30/38 · 24/32 | Page and section titles |
+| `text-text-xl` | 20/30 | Lead paragraphs |
+| `text-text-lg` | 18/28 | Large body |
+| `text-text-md` | 16/24 | Body |
+| `text-text-sm` | 14/20 | UI labels, secondary text |
+| `text-text-xs` | 12/18 | Captions, helper text |
+| `text-text-2xs` | 12/18 | Smallest labels |
+
+```tsx
+<h1 className="text-display-sm font-semibold text-[var(--ds-color-text-display)]">Applications</h1>
+<p className="text-text-md text-[var(--ds-color-text-paragraph)]">…</p>
+```
+
+Don't add your own `text-[14px]`, `leading-[…]` or per-breakpoint font sizes on top: the utilities already handle the responsive steps.
+
+## Weights
+
+| Weight | Class | Use for |
+| --- | --- | --- |
+| 400 | `font-normal` | Body text, helper text |
+| 500 | `font-medium` | Labels, buttons, UI controls |
+| 600 | `font-semibold` | Headings, emphasis |
+| 700 | `font-bold` | Rare; strong emphasis |
+
+## Common mistakes
+
+- Loading the font a second time (Google Fonts link, `@font-face`) next to the one `init` installed.
+- Hardcoding `font-family` instead of using the tokens.
+- Setting a size with `text-[…]` and a separate line height, instead of one `text-display-*` / `text-text-*` utility.
+- Adding mobile font step-downs by hand — the utilities already step down.

package/knowledge/general/accordion.md

@@ -0,0 +1,79 @@
+# Accordion
+
+## Metadata
+- Component: Accordion
+- Slug: `accordion`
+- Category: General
+- Install: `npx sdaia-ui@latest add accordion`
+- Import: `import { Accordion } from '@/components/ui/Accordion'`
+- Installed files: `Accordion.tsx`, `Accordion.types.ts`, `Accordion.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/accordion
+
+> **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 accordion`. It copies the source into your components folder (`components/ui/Accordion/`, under `src/` when the project has one); import it as `@/components/ui/Accordion`. 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. Inherits when omitted. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Accordion size |
+| `variant?` | `'light' \| 'light-compact' \| 'block'` | 'light' | Visual style |
+| `state?` | `'default' \| 'hovered' \| 'pressed' \| 'focused' \| 'disabled'` | — | Force a specific visual state (useful for docs/previews) |
+| `iconAlignment?` | `'trailing' \| 'leading'` | 'trailing' | Icon position in the trigger row |
+| `label?` | `ReactNode` | — | Trigger label text/content. Renders nothing when omitted. |
+| `expanded?` | `boolean` | — | Controlled expanded state |
+| `defaultExpanded?` | `boolean` | false | Uncontrolled initial expanded state |
+| `disabled?` | `boolean` | false | Non-interactive state |
+| `onExpandedChange?` | `(expanded: boolean) => void` | — | Fires when expanded state changes |
+| `preserveContentSpaceWhenCollapsed?` | `boolean` | false | Keep content height reserved while collapsed (useful for demos/previews) |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Inherits when omitted.
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Accordion size
+- `variant`: `'light'` \| `'light-compact'` \| `'block'` — Visual style
+- `state`: `'default'` \| `'hovered'` \| `'pressed'` \| `'focused'` \| `'disabled'` — Force a specific visual state (useful for docs/previews)
+- `iconAlignment`: `'trailing'` \| `'leading'` — Icon position in the trigger row
+
+## Deprecated props
+Do not use in new code:
+- `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-default)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-default-disabled)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-icon-sm)`
+- `var(--ds-motion-expand-duration)`
+- `var(--ds-motion-expand-easing)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add accordion` (after `npx sdaia-ui@latest init`), then import `{ Accordion }` from `@/components/ui/Accordion`.
+- 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).
+- Express the disabled state with the `disabled` prop, not custom styling.
+- 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/activity.md

@@ -0,0 +1,44 @@
+# Activity
+
+## Metadata
+- Component: Activity
+- Slug: `activity`
+- Category: General
+- Install: `npx sdaia-ui@latest add activity`
+- Import: `import { Activity } from '@/components/ui/Activity'`
+- Installed files: `Activity.tsx`, `Activity.types.ts`, `Activity.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/activity
+
+> **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 activity`. It copies the source into your components folder (`components/ui/Activity/`, under `src/` when the project has one); import it as `@/components/ui/Activity`. 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 |
+| --- | --- | --- | --- |
+| `items` | `ActivityItemProps[]` | — | The feed items to render. Each entry maps 1-to-1 to an `ActivityItem`. |
+| `divider?` | `boolean` | false | When true a 1 px horizontal rule is inserted between every consecutive pair of items. Gap collapses from 24 px to 12 px on each side of the rule. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## 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-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add activity` (after `npx sdaia-ui@latest init`), then import `{ Activity }` from `@/components/ui/Activity`.
+- 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/app-shell.md

@@ -0,0 +1,64 @@
+# App Shell
+
+## Metadata
+- Component: App Shell
+- Slug: `app-shell`
+- Category: General
+- Install: `npx sdaia-ui@latest add app-shell`
+- Import: `import { AppShell } from '@/components/ui/AppShell'`
+- Installed files: `AppShell.tsx`, `AppShell.types.ts`, `AppShell.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/app-shell
+
+> **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 app-shell`. It copies the source into your components folder (`components/ui/AppShell/`, under `src/` when the project has one); import it as `@/components/ui/AppShell`. 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 |
+| --- | --- | --- | --- |
+| `header?` | `AppShellHeaderProps \| ((layout: AppShellHeaderLayout) => AppShellHeaderProps)` | — | The Nav Header on top of the shell (logo, items, search, actions, labels…). Pass a function to adapt the content to the bar being rendered, e.g. `mobile` on `NavHeaderMenuItem` / `NavHeaderActions` in the compact bar. Omit to render the shell without a header. |
+| `sideNavigation?` | `AppShellSideNavigationProps` | — | The side navigation (`NavBar`: groups, header, footer, labels, style). On desktop it renders as a column at the inline-start edge (the right in Arabic). Below 1280 px it collapses into the header menu: its groups and footer are listed in the Nav Header drawer. Omit for pages without a side navigation (e.g. error pages). |
+| `navigation?` | `'expanded' \| 'collapsed'` | — | Figma `Navigation` — side navigation width on desktop. Controlled; pair with `onNavigationChange`. Omit to let the shell manage it. |
+| `defaultNavigation?` | `'expanded' \| 'collapsed'` | 'expanded' | Initial `navigation` when uncontrolled. |
+| `onNavigationChange?` | `(navigation: AppShellNavigation) => void` | — | Called with the next value when the side navigation toggle is pressed. |
+| `menuOpen?` | `boolean` | — | Whether the header menu (the drawer of the compact bar, < 1280 px) is open. Controlled; pair with `onMenuOpenChange`. Omit to let the shell manage it. |
+| `onMenuOpenChange?` | `(open: boolean) => void` | — | Called when the header menu opens or closes: menu button, Escape, a side navigation item chosen from the drawer, or the viewport growing to desktop width. |
+| `contentClassName?` | `string` | — | Extra classes for the content region (`<main>`), e.g. to remove its padding. |
+| `labels?` | `Partial<AppShellLabels>` | — | Override the built-in accessible strings (English defaults). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. In `rtl` the side navigation sits on the right. Omit to inherit the ambient direction. |
+| `children?` | `ReactNode` | — | Figma `Content` slot — the page content. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `navigation`: `'expanded'` \| `'collapsed'` — Figma `Navigation` — width of the side navigation on desktop (≥ 1280 px).
+- `expanded`  → 255 px, icons + labels
+- `collapsed` → 64 px, icons only
+- `defaultNavigation`: `'expanded'` \| `'collapsed'` — Figma `Navigation` — width of the side navigation on desktop (≥ 1280 px).
+- `expanded`  → 255 px, icons + labels
+- `collapsed` → 64 px, icons only
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. In `rtl` the side navigation sits
+on the right. Omit to inherit the ambient direction.
+
+## 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-color-bg-canvas)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add app-shell` (after `npx sdaia-ui@latest init`), then import `{ AppShell }` from `@/components/ui/AppShell`.
+- 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/area-chart.md

@@ -0,0 +1,89 @@
+# Area Chart
+
+## Metadata
+- Component: Area Chart
+- Slug: `area-chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add area-chart`
+- Import: `import { AreaChart } from '@/components/ui/AreaChart'`
+- Installed files: `AreaChart.tsx`, `AreaChart.types.ts`, `AreaChart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/area-chart
+
+> **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 area-chart`. It copies the source into your components folder (`components/ui/AreaChart/`, under `src/` when the project has one); import it as `@/components/ui/AreaChart`. 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?` | `'Insight' \| 'Detailed Comparison' \| 'Metric' \| 'Summary'` | 'Insight' | Chart variant. - Insight             — dual-area chart with tabs, metric rows, and bottom legend - Detailed Comparison — two overlapping filled areas for comparing series - Metric              — compact KPI card: indicator label + value + sparkline (no badge) - Summary             — compact KPI card: label + badge (top) + value + sparkline (bottom) |
+| `xAxisData?` | `XAxisDataType` | '7 Week Days' | X-axis label preset. Controls both the axis labels and the number of default data points rendered. All types respect this prop. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. In `'rtl'` the chart mirrors: time runs right-to-left (the first category is on the right) and the Y-axis sits on the right. Inherited from the document when omitted. |
+| `locale?` | `string` | — | BCP 47 locale for the x-axis day / month names (Gregorian, via `Intl`) and number formatting in the tooltip, computed Y-axis ticks and data table, e.g. `'ar-SA'`. English names and plain numbers when omitted. |
+| `labels?` | `Partial<AreaChartLabels>` | — | Overrides for the built-in strings (see `AreaChartLabels`). |
+| `height?` | `number` | — | Total root height in px. - Insight defaults to 440 px. - Detailed Comparison defaults to a preset based on `xAxisData`. - Metric and Summary ignore this prop (content-driven height). |
+| `kpiLabel?` | `ReactNode` | — | Indicator label shown above the main value (Metric / Summary / Detailed Comparison). Not rendered when omitted. |
+| `kpiValue?` | `ReactNode` | — | Main KPI value shown in display-xs bold (Metric / Summary / Detailed Comparison). Not rendered when omitted. |
+| `badgeType?` | `ChartBadgeType` | 'increase' | Direction of the ChartBadge delta indicator (Summary only). |
+| `badgeValue?` | `ReactNode` | — | Text inside the ChartBadge (Summary / Detailed Comparison). The badge is not rendered when omitted. |
+| `tabs?` | `HorizontalTabItem[]` | — | Tab items for the HorizontalTabs strip at the top of the Insight card. No tab strip is rendered when omitted. |
+| `activeTab?` | `string` | — | Controlled active tab value (Insight). |
+| `onTabChange?` | `(value: string) => void` | — | Fired when the user selects a different tab (Insight). |
+| `insightRows?` | `AreaChartInsightRow[]` | — | One or two metric rows shown above the chart area (Insight). Each row renders: label, value, and an optional ChartBadge. No rows are rendered when omitted. |
+| `legendLabel1?` | `ReactNode` | labels.seriesName(0) — 'Series 1' | Legend label for Series 1 in the bottom legend strip (Insight). |
+| `legendLabel2?` | `ReactNode` | labels.seriesName(1) — 'Series 2' | Legend label for Series 2 in the bottom legend strip (Insight). |
+| `series1?` | `number[]` | — | Primary (foreground) area values — Insight only (required for a plot). |
+| `series2?` | `number[]` | — | Secondary (background) area values — Insight only (optional). |
+| `yAxisTicks?` | `[string, string, string, string, string, string]` | — | Optional 6-string array used to label the Y-axis ticks (top → bottom). When omitted, ticks are computed from the active dataset's domain. Insight only. |
+| `sparklineData?` | `GraphBaseDataPoint[]` | — | Data forwarded to the embedded sparkline for the Metric, Summary, and Detailed Comparison KPI cards. See `GraphBaseDataPoint` for the shape. The sparkline area stays empty when omitted (no sample data). The sparkline is decorative (`aria-hidden`); the KPI text carries the data. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'Insight'` \| `'Detailed Comparison'` \| `'Metric'` \| `'Summary'` — Chart variant.
+- Insight             — dual-area chart with tabs, metric rows, and bottom legend
+- Detailed Comparison — two overlapping filled areas for comparing series
+- Metric              — compact KPI card: indicator label + value + sparkline (no badge)
+- Summary             — compact KPI card: label + badge (top) + value + sparkline (bottom)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. In `'rtl'` the chart mirrors: time runs right-to-left
+(the first category is on the right) and the Y-axis sits on the right.
+Inherited from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `rtl` — Render in right-to-left orientation.
+
+## 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-brand-muted)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-chart-series-1)`
+- `var(--ds-color-chart-series-2)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-m)`
+- `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-xs)`
+- `var(--ds-text-leading-line-heights-text-lg)`
+- `var(--ds-text-leading-line-heights-text-md)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add area-chart` (after `npx sdaia-ui@latest init`), then import `{ AreaChart }` from `@/components/ui/AreaChart`.
+- 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/audio-player.md

@@ -0,0 +1,85 @@
+# Audio Player
+
+## Metadata
+- Component: Audio Player
+- Slug: `audio-player`
+- Category: General
+- Install: `npx sdaia-ui@latest add audio-player`
+- Import: `import { AudioPlayer } from '@/components/ui/AudioPlayer'`
+- Installed files: `AudioPlayer.tsx`, `AudioPlayer.types.ts`, `AudioPlayer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/audio-player
+
+> **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 audio-player`. It copies the source into your components folder (`components/ui/AudioPlayer/`, under `src/` when the project has one); import it as `@/components/ui/AudioPlayer`. 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?` | `'compact' \| 'detailed'` | 'compact' | Layout variant. Default: 'compact'. |
+| `style?` | `'transparent' \| 'neutral' \| 'brand'` | 'transparent' | Visual style. Default: 'transparent'. |
+| `playing?` | `boolean` | — | Whether the player is playing (controlled). Omit to let the component manage its own state. |
+| `defaultPlaying?` | `boolean` | false | Initial playing state when uncontrolled. Default: false. |
+| `progress?` | `number` | — | Playback progress 0–100 (controlled). Omit to let the component manage its own progress. |
+| `defaultProgress?` | `number` | 0 | Initial progress value when uncontrolled. Default: 0. |
+| `currentTime?` | `string` | '0:00' | Current-time display string, e.g. "0:12". |
+| `duration?` | `string` | '0:00' | Total-duration display string, e.g. "2:32". |
+| `audioName?` | `string` | — | Audio track / episode name. Shown in the detailed variant only. Uses dir="auto" so Arabic text self-detects direction. |
+| `onPlay?` | `() => void` | — | Called when the user requests playback to start. |
+| `onPause?` | `() => void` | — | Called when the user requests playback to pause. |
+| `onSkipBack?` | `() => void` | — | Called when the skip-back button is clicked. |
+| `onSkipForward?` | `() => void` | — | Called when the skip-forward button is clicked. |
+| `onProgressChange?` | `(value: number) => void` | — | Called when the user scrubs the progress bar. Receives the new value in the range 0–100. |
+| `muted?` | `boolean` | — | Whether audio is muted (controlled). Omit to let the component manage its own state. |
+| `defaultMuted?` | `boolean` | false | Initial muted state when uncontrolled. Default: false. |
+| `onVolumeClick?` | `() => void` | — | Called when the volume button is clicked. |
+| `onSettingsClick?` | `() => void` | — | Called when the settings button is clicked. |
+| `labels?` | `Partial<AudioPlayerLabels>` | — | Localised copy for every control label (`aria-label` / `aria-valuetext`). Unset keys fall back to English. See . |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. In `rtl` the row mirrors (play group on the right, progress fills right-to-left, ArrowLeft seeks forward). The time stays LTR. Omit to inherit the direction from the parent. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `style`, `dir`.
+
+## Options (allowed values)
+- `type`: `'compact'` \| `'detailed'` — Layout variant.
+- compact  — single row; controls + progress inline (616×56 Figma frame)
+- detailed — two rows; audio name on top, progress + controls below (504×72 Figma frame)
+- `style`: `'transparent'` \| `'neutral'` \| `'brand'` — Visual style of the audio player shell.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. In `rtl` the row mirrors (play group on the right,
+progress fills right-to-left, ArrowLeft seeks forward). The time stays LTR.
+Omit to inherit the direction from the parent.
+
+## 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-bg-brand)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-strong)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-strong)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-themes-media-media-background-play-neutral)`
+- `var(--ds-themes-media-media-background-transparent)`
+- `var(--ds-themes-media-media-track-bg)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add audio-player` (after `npx sdaia-ui@latest init`), then import `{ AudioPlayer }` from `@/components/ui/AudioPlayer`.
+- 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/avatar-group.md

@@ -0,0 +1,50 @@
+# AvatarGroup
+
+## Metadata
+- Component: AvatarGroup
+- Slug: `avatar-group`
+- Category: General
+- Install: `npx sdaia-ui@latest add avatar-group`
+- Import: `import { AvatarGroup } from '@/components/ui/AvatarGroup'`
+- Installed files: `AvatarGroup.tsx`, `AvatarGroup.types.ts`, `AvatarGroup.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/avatargroup
+
+> **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 avatar-group`. It copies the source into your components folder (`components/ui/AvatarGroup/`, under `src/` when the project has one); import it as `@/components/ui/AvatarGroup`. 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?` | `'group' \| 'individual'` | 'group' | Layout mode. - `group` (default): avatars overlap in a stack via a negative inline margin. - `individual`: avatars are spaced side-by-side. |
+| `items` | `AvatarGroupItem[]` | — | Avatars to render, in visual stacking order (first = on top). |
+| `max?` | `number` | — | Maximum number of avatars to render before collapsing the rest into a `+N` counter. If omitted, every item in `items` is rendered. |
+| `size?` | `AvatarSize` | 'md' | Size applied to every avatar in the group. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `labels?` | `Partial<AvatarGroupLabels>` | — | Override built-in strings (English defaults) to localize the group. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`.
+
+## Options (allowed values)
+- `type`: `'group'` \| `'individual'` — Layout mode.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document 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-color-border-brand)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-md)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add avatar-group` (after `npx sdaia-ui@latest init`), then import `{ AvatarGroup }` from `@/components/ui/AvatarGroup`.
+- 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/avatar.md

@@ -0,0 +1,61 @@
+# Avatar
+
+## Metadata
+- Component: Avatar
+- Slug: `avatar`
+- Category: General
+- Install: `npx sdaia-ui@latest add avatar`
+- Import: `import { Avatar } from '@/components/ui/Avatar'`
+- Installed files: `Avatar.tsx`, `Avatar.types.ts`, `Avatar.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/avatar
+
+> **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 avatar`. It copies the source into your components folder (`components/ui/Avatar/`, under `src/` when the project has one); import it as `@/components/ui/Avatar`. 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 |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl'` | 'md' | Size tier |
+| `type?` | `'initials' \| 'icon' \| 'image'` | 'initials' | Content type |
+| `shape?` | `'round' \| 'square'` | 'round' | Shape |
+| `initials?` | `string` | — | Initials text — used when `type="initials"`. The first two characters will be uppercased and shown. A value starting with `+` (an overflow counter such as `+12`) is shown in full. |
+| `src?` | `string` | — | Image source — used when `type="image"`. When omitted, the avatar renders its neutral background only (no sample picture). |
+| `alt?` | `string` | '' | Alt text for the image — used when `type="image"` |
+| `icon?` | `ReactNode` | — | Custom icon — replaces the default user glyph when `type="icon"` |
+| `statusDot?` | `boolean` | false | Shows the status indicator overlay |
+| `background?` | `boolean` | true | Shows the inner neutral background fill. |
+| `border?` | `boolean` | true | Shows the outer ring border. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'md'` \| `'lg'` \| `'xl'` — Visual size tier
+- `type`: `'initials'` \| `'icon'` \| `'image'` — Content type
+- `shape`: `'round'` \| `'square'` — Shape: round (circle) or rounded-square
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## 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-emphasis-low)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-default)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-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 avatar` (after `npx sdaia-ui@latest init`), then import `{ Avatar }` from `@/components/ui/Avatar`.
+- 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/carousel-image.md

@@ -0,0 +1,103 @@
+# Carousel Image
+
+## Metadata
+- Component: Carousel Image
+- Slug: `carousel-image`
+- Category: General
+- Install: `npx sdaia-ui@latest add carousel-image`
+- Import: `import { CarouselImage } from '@/components/ui/CarouselImage'`
+- Installed files: `CarouselImage.tsx`, `CarouselImage.types.ts`, `CarouselImage.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/carouseimage
+
+> **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 carousel-image`. It copies the source into your components folder (`components/ui/CarouselImage/`, under `src/` when the project has one); import it as `@/components/ui/CarouselImage`. 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 — pass `'rtl'` for Arabic/Hebrew contexts. When omitted it is inherited from an ancestor. |
+| `images` | `CarouselImageItem[]` | — | Images to display, one per slide. |
+| `activeIndex?` | `number` | — | Controlled active index. |
+| `defaultIndex?` | `number` | 0 | Initial slide index when uncontrolled. |
+| `onChange?` | `(index: number) => void` | — | Called whenever the active slide changes. |
+| `loop?` | `boolean` | true | Wrap around when navigating past the first/last slide. |
+| `autoplayMs?` | `number` | — | Auto-advance interval in ms. 0 / undefined disables autoplay. Autoplay pauses while the pointer is over the carousel or focus is inside it. |
+| `showArrows?` | `boolean` | true | Show arrow buttons. |
+| `showDots?` | `boolean` | true | Show pagination dots. |
+| `overlay?` | `boolean` | true | When true, arrows and dots overlay the image (image fills the entire card). When false, arrows sit on the sides and dots sit below the image. |
+| `size?` | `'sm' \| 'md' \| 'full'` | 'md' | Size preset from the Figma spec. Sets the inline max-width and a matching aspect ratio so the carousel never balloons to the full page width. Pass `'full'` to opt out of the constraint. |
+| `arrowVariant?` | `CarouselArrowVariant` | 'brand' | Visual style of the arrows. |
+| `arrowSize?` | `CarouselArrowSize` | 'md' | Size of the arrows. |
+| `dotsVariant?` | `CarouselControlsGroupStyle` | 'brand' | Visual style of the pagination dots. |
+| `dotsSize?` | `CarouselControlsGroupSize` | 'sm' | Size of the pagination dots. |
+| `radiusClassName?` | `string` | 'rounded-[var(--ds-radius-m)]' | Border radius class applied to the viewport. |
+| `ariaLabel?` | `string` | — | Accessible label for the carousel region. Takes precedence over `labels.carousel`. |
+| `labels?` | `Partial<CarouselImageLabels>` | — | Translatable accessible text (English defaults). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — pass `'rtl'` for Arabic/Hebrew contexts. When omitted
+it is inherited from an ancestor.
+- `size`: `'sm'` \| `'md'` \| `'full'` — Size presets matching Figma node 4455:37316 `Carousel Image`:
+  `sm`   — max-w 360px (Figma overlay dimensions)
+  `md`   — max-w 418px (Figma side-arrows dimensions, default)
+  `full` — fills the parent's inline size with no max-width
+
+## Placeholder images (demos & prototypes)
+
+For mockups and AI-generated pages, use **real photo URLs** with a **free license** — not broken `example.com` links or colored divs. Each slide needs `src` + **`alt`** (required).
+
+**Recommended source:** [Unsplash](https://unsplash.com) — [Unsplash License](https://unsplash.com/license): free for commercial and personal use; attribution appreciated but not required. Use `images.unsplash.com` URLs only for **prototypes**; for production, download and self-host (or use your product CDN).
+
+**Tech-themed examples** (copy as-is):
+
+```tsx
+<CarouselImage
+  size="md"
+  ariaLabel="Technology showcase"
+  images={[
+    {
+      src: 'https://images.unsplash.com/photo-1518770660439-4636190af475?w=800&h=450&fit=crop',
+      alt: 'Circuit board and electronic components close-up',
+    },
+    {
+      src: 'https://images.unsplash.com/photo-1485827404703-89b55fcc595e?w=800&h=450&fit=crop',
+      alt: 'White humanoid robot on a neutral background',
+    },
+    {
+      src: 'https://images.unsplash.com/photo-1498050108023-c5249f4df085?w=800&h=450&fit=crop',
+      alt: 'Laptop displaying code on a desk with coffee',
+    },
+  ]}
+/>
+```
+
+| Slide | License | Notes |
+| --- | --- | --- |
+| Circuit / hardware | Unsplash License | `photo-1518770660439` |
+| Robotics / AI | Unsplash License | `photo-1485827404703` |
+| Developer / laptop | Unsplash License | `photo-1498050108023` |
+
+**Alternative (generic, not tech-specific):** [Lorem Picsum](https://picsum.photos/) — `https://picsum.photos/seed/carousel-1/800/450` (change `seed` per slide).
+
+Do not use copyrighted stock, watermarked URLs, or random Google Images links.
+
+## 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-muted)`
+- `var(--ds-motion-transition-duration)`
+- `var(--ds-motion-transition-easing)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add carousel-image` (after `npx sdaia-ui@latest init`), then import `{ CarouselImage }` from `@/components/ui/CarouselImage`.
+- 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".
+- For demos, use the licensed Unsplash URLs in **Placeholder images** (2–3 slides with real `alt` text) — never placeholder.com or invented image paths.
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.