@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/general/chart.md

@@ -0,0 +1,25 @@
+# Chart
+
+## Metadata
+- Component: Chart
+- Slug: `chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add chart`
+- Import: `import { Chart } from '@/components/ui/Chart'`
+- Installed files: `Chart.tsx`, `Chart.types.ts`, `Chart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/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 chart`. It copies the source into your components folder (`components/ui/Chart/`, under `src/` when the project has one); import it as `@/components/ui/Chart`. 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
+This component takes no documented props beyond standard HTML attributes.
+
+## 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`).
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add chart` (after `npx sdaia-ui@latest init`), then import `{ Chart }` from `@/components/ui/Chart`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- 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/chip.md

@@ -0,0 +1,90 @@
+# Chip
+
+## Metadata
+- Component: Chip
+- Slug: `chip`
+- Category: General
+- Install: `npx sdaia-ui@latest add chip`
+- Import: `import { Chip } from '@/components/ui/Chip'`
+- Installed files: `Chip.tsx`, `Chip.types.ts`, `Chip.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/chip
+
+> **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 chip`. It copies the source into your components folder (`components/ui/Chip/`, under `src/` when the project has one); import it as `@/components/ui/Chip`. 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'` | — | Text direction of the chip. Leave unset to inherit it from an ancestor (`dir="rtl"` on any parent mirrors the leading / trailing slots). |
+| `variant?` | `'soft' \| 'solid' \| 'neutral' \| 'outline'` | 'soft' | Visual style of the chip |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the chip |
+| `rounded?` | `boolean` | true | Pill-shaped (fully rounded) when true. When false, uses a size-based radius (lg → 8px, md/sm → 6px). |
+| `disabled?` | `boolean` | false | Disables the chip and prevents interaction |
+| `selected?` | `boolean` | false | Marks the chip as selected (toggled on) |
+| `leadingIcon?` | `ReactNode` | — | Icon or node displayed before the label (direction-aware, auto-flips in RTL). |
+| `trailingIcon?` | `ReactNode` | — | Icon or node displayed after the label (direction-aware, auto-flips in RTL). Pair with `onTrailingIconClick` to make it an independent clickable action, e.g. an "×" dismiss button that removes the chip from a filter list without toggling the chip's own selected state. |
+| `onLeadingIconClick?` | `(e: MouseEvent<HTMLSpanElement> \| KeyboardEvent<HTMLSpanElement>) => void` | — | Called when the leading icon area is clicked or activated via keyboard. When provided, the leading icon slot renders as a `role="button"` span with its own focus ring and Enter/Space activation, and the chip root renders as a non-interactive `<span>` (unless `as` is set) so controls are never nested. The event is stopped from propagating to the chip's `onClick`. |
+| `onTrailingIconClick?` | `(e: MouseEvent<HTMLSpanElement> \| KeyboardEvent<HTMLSpanElement>) => void` | — | Called when the trailing icon area is clicked or activated via keyboard. When provided, the trailing icon slot renders as a `role="button"` span with its own focus ring and Enter/Space activation, and the chip root renders as a non-interactive `<span>` (unless `as` is set) so controls are never nested. The event is stopped from propagating to the chip's `onClick`. Common use-case: an "×" icon that removes the chip from a filter list without toggling the chip's selected state. |
+| `trailingIconLabel?` | `string` | — | Accessible label for the trailing icon `role="button"` span, e.g. `Remove ${label}`. Only relevant when `onTrailingIconClick` is provided. Wins over `labels.remove`. |
+| `leadingIconLabel?` | `string` | — | Accessible label for the leading icon `role="button"` span. Only relevant when `onLeadingIconClick` is provided. |
+| `labels?` | `Partial<ChipLabels>` | — | Localised built-in strings. |
+| `avatar?` | `boolean` | false | When `true`, renders a circular avatar image in the leading slot. `leadingIcon` is ignored when `avatar` is `true`. Figma: Avatar property on Chip (node 4113:9553) |
+| `avatarSrc?` | `string` | the default `SaudiAvatar` from sdaia-assets | Image URL/path for the avatar. Only used when `avatar={true}`. |
+| `as?` | `ElementType` | 'button', or 'span' when an icon slot is clickable | Override the rendered HTML element. |
+| `children?` | `ReactNode` | — | — |
+
+Also accepts standard `<button>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the chip. Leave unset to inherit it from an ancestor
+(`dir="rtl"` on any parent mirrors the leading / trailing slots).
+- `variant`: `'soft'` \| `'solid'` \| `'neutral'` \| `'outline'` — Visual style of the chip
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the chip
+
+## 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-)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-bg-disabled-brand)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-chip-bg-neutral-default)`
+- `var(--ds-color-chip-bg-neutral-hovered)`
+- `var(--ds-color-chip-bg-neutral-selected)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-themes-chip-)`
+- `var(--ds-themes-chip-chip-bg-neutral-pressed)`
+- `var(--ds-themes-chip-chip-bg-soft-default)`
+- `var(--ds-themes-chip-chip-bg-soft-hovered)`
+- `var(--ds-themes-chip-chip-bg-soft-pressed)`
+- `var(--ds-themes-chip-chip-bg-soft-selected)`
+- `var(--ds-themes-chip-chip-bg-solid-default)`
+- `var(--ds-themes-chip-chip-bg-solid-hovered)`
+- `var(--ds-themes-chip-chip-bg-solid-pressed)`
+- `var(--ds-themes-chip-chip-bg-solid-selected)`
+- `var(--ds-themes-chip-chip-text-soft)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add chip` (after `npx sdaia-ui@latest init`), then import `{ Chip }` from `@/components/ui/Chip`.
+- 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/code-snippet.md

@@ -0,0 +1,80 @@
+# Code Snippet
+
+## Metadata
+- Component: Code Snippet
+- Slug: `code-snippet`
+- Category: General
+- Install: `npx sdaia-ui@latest add code-snippet`
+- Import: `import { CodeSnippet } from '@/components/ui/CodeSnippet'`
+- Installed files: `CodeSnippet.tsx`, `CodeSnippet.types.ts`, `CodeSnippet.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/code-snippet
+
+> **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 code-snippet`. It copies the source into your components folder (`components/ui/CodeSnippet/`, under `src/` when the project has one); import it as `@/components/ui/CodeSnippet`. 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 |
+| --- | --- | --- | --- |
+| `variant` | `'multi-line-with-tabs' \| 'multi-line-without-tabs' \| 'single-line'` | — | Structural layout / Figma variant. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the chrome (tabs / file header). The code body and the single-line command always render LTR. Unset inherits from the document. |
+| `labels?` | `Partial<CodeSnippetLabels>` | — | Localised built-in strings. |
+| `showHeader?` | `boolean` | true for multi-line variants; no effect for single-line. | When true, shows the top region (tabs or file header for multi-line). |
+| `showLineNumbers?` | `boolean` | true for multi-line variants; no effect for single-line. | Line-number column for multi-line bodies. |
+| `codeBodyMinHeight?` | `string` | — | Tailwind classes for the **multi-line code body row** minimum height (below the header). Merged after the default (~384px). Ignored for `single-line`. |
+| `copyText?` | `string` | — | Clipboard payload when the copy control is used. |
+| `onCopy?` | `() => void \| Promise<void>` | — | Invoked when the copy control is activated after a successful `writeText`, or by itself if `copyText` is empty (handle clipboard yourself). |
+| `showMoreButton?` | `boolean` | true | Renders the secondary "Show more" control under multi-line code. |
+| `onShowMore?` | `() => void` | — | Called when "Show more" is pressed. |
+| `showCopyButton?` | `boolean` | true | Renders the primary copy control. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`, `onCopy`.
+
+## Options (allowed values)
+- `variant`: `'multi-line-with-tabs'` \| `'multi-line-without-tabs'` \| `'single-line'` — Structural layout from Figma "Code Snippet":
+- `multi-line-with-tabs` — underline `Tabs` + line gutter + body
+- `multi-line-without-tabs` — file header row + same body
+- `single-line` — compact command row (label + command + copy)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the chrome (tabs / file header). The code body and the single-line
+command always render LTR. Unset inherits from the document.
+
+## Deprecated props
+Do not use in new code:
+- `showMoreLabel` — Label of the collapsed-code toggle. Wins over `labels.showMore`.
+
+## 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-)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-color-tooltip-bg-on-light)`
+- `var(--ds-color-tooltip-text-heading-on-light)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add code-snippet` (after `npx sdaia-ui@latest init`), then import `{ CodeSnippet }` from `@/components/ui/CodeSnippet`.
+- 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/column-chart.md

@@ -0,0 +1,84 @@
+# Column Chart
+
+## Metadata
+- Component: Column Chart
+- Slug: `column-chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add column-chart`
+- Import: `import { ColumnChart } from '@/components/ui/ColumnChart'`
+- Installed files: `ColumnChart.tsx`, `ColumnChart.types.ts`, `ColumnChart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/column-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 column-chart`. It copies the source into your components folder (`components/ui/ColumnChart/`, under `src/` when the project has one); import it as `@/components/ui/ColumnChart`. 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' \| 'Score' \| 'TrendMatrix' \| 'ValuePanel' \| 'InsightGrid' \| 'GaugeChart' \| 'PulseBox' \| 'MetricCell' \| 'DataCluster' \| 'ProgressMeter' \| 'Forecast' \| 'ScorePod' \| 'IndexTile'` | 'Insight' | Which variant layout to render. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Direction of the root. When omitted the chart inherits the page direction. In RTL the axes mirror: the first category is on the right, the Y axis sits on the right and bars read right-to-left. |
+| `locale?` | `string` | 'en' | BCP 47 locale used to format numbers (derived Y-axis ticks, tooltip and data-table values), e.g. `'ar-SA'`. |
+| `labels?` | `Partial<ColumnChartLabels>` | — | Overrides for the built-in strings (English defaults). |
+| `title?` | `string` | — | Main card title (Insight, Score, DataCluster, IndexTile). Not rendered when omitted. |
+| `note?` | `string` | — | Subtitle / note (Insight, Forecast). Not rendered when omitted. |
+| `dateBadge?` | `string` | — | Date range text shown in the header badge (Insight, DataCluster). Not rendered when omitted. |
+| `label?` | `string` | — | Indicator label. Not rendered when omitted. |
+| `value?` | `string` | — | Metric value string (e.g. `'422.61'`). Not rendered when omitted. |
+| `badge?` | `{ type?: 'increase' \| 'decrease'; value?: string }` | — | ChartBadge config for the primary metric. Not rendered without `value`. |
+| `label2?` | `string` | — | — |
+| `value2?` | `string` | — | — |
+| `badge2?` | `{ type?: 'increase' \| 'decrease'; value?: string }` | — | — |
+| `data?` | `ColumnChartDataPoint[]` | — | Indicator 1 / green series. Values are percentages 0–100 (or absolute, scaled by maxValue). When missing or empty the chart shows the `labels.noData` state. |
+| `data2?` | `ColumnChartDataPoint[]` | — | Indicator 2 / lavender series (Score, InsightGrid, MetricCell, ProgressMeter, ScorePod). |
+| `maxValue?` | `number` | DEFAULT_MAX_VALUE | Maximum Y value used to compute bar heights in full-chart modes. |
+| `xLabels?` | `string[]` | — | X-axis (category) labels. The X axis is not rendered when omitted. |
+| `yLabels?` | `string[]` | — | Y-axis labels listed top→bottom. When omitted, six evenly spaced ticks from `maxValue` to 0 are derived and formatted with `locale`. |
+| `tabs?` | `ColumnChartTab[]` | — | Score tabs. Not rendered when omitted. |
+| `defaultTab?` | `string` | — | — |
+| `onTabChange?` | `(value: string) => void` | — | — |
+| `legend?` | `ColumnChartLegendItem[]` | — | Score legend. Not rendered when omitted. |
+| `metrics?` | `ColumnChartMetric[]` | — | Two metrics for Score, ProgressMeter, ScorePod, IndexTile (bottom rows), MetricCell. |
+| `onActionClick?` | `() => void` | — | — |
+| `actionLabel?` | `string` | — | Bottom indicator label for Forecast (falls back to `label`). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'Insight'` \| `'Score'` \| `'TrendMatrix'` \| `'ValuePanel'` \| `'InsightGrid'` \| `'GaugeChart'` \| `'PulseBox'` \| `'MetricCell'` \| `'DataCluster'` \| `'ProgressMeter'` \| `'Forecast'` \| `'ScorePod'` \| `'IndexTile'` — Which variant layout to render.
+- `dir`: `'ltr'` \| `'rtl'` — Direction of the root. When omitted the chart inherits the page direction.
+In RTL the axes mirror: the first category is on the right, the Y axis
+sits on the right and bars read right-to-left.
+
+## 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-raised)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-chart-series-1)`
+- `var(--ds-color-chart-series-2)`
+- `var(--ds-color-chip-bg-neutral-default)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add column-chart` (after `npx sdaia-ui@latest init`), then import `{ ColumnChart }` from `@/components/ui/ColumnChart`.
+- 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/context-menu.md

@@ -0,0 +1,55 @@
+# Context Menu
+
+## Metadata
+- Component: Context Menu
+- Slug: `context-menu`
+- Category: General
+- Install: `npx sdaia-ui@latest add context-menu`
+- Import: `import { ContextMenu } from '@/components/ui/ContextMenu'`
+- Installed files: `ContextMenu.tsx`, `ContextMenu.types.ts`, `ContextMenu.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/context-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 context-menu`. It copies the source into your components folder (`components/ui/ContextMenu/`, under `src/` when the project has one); import it as `@/components/ui/ContextMenu`. 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. |
+| `items?` | `ContextMenuItem[]` | [] | Ordered list of items and dividers to display in the panel. Figma default: 8 `ContextMenuDropdown` rows with 2 dividers interspersed. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `className?` | `string` | — | Additional class names on the root panel wrapper |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## 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 panel.
+  - `'solid'` (default) — opaque card with the standard drop shadow.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). 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-raised)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add context-menu` (after `npx sdaia-ui@latest init`), then import `{ ContextMenu }` from `@/components/ui/ContextMenu`.
+- 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/digital-stamp.md

@@ -0,0 +1,77 @@
+# Digital Stamp
+
+## Metadata
+- Component: Digital Stamp
+- Slug: `digital-stamp`
+- Category: General
+- Install: `npx sdaia-ui@latest add digital-stamp`
+- Import: `import { DigitalStamp } from '@/components/ui/DigitalStamp'`
+- Installed files: `DigitalStamp.tsx`, `DigitalStamp.types.ts`, `DigitalStamp.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/digital-stamp
+
+> **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 digital-stamp`. It copies the source into your components folder (`components/ui/DigitalStamp/`, under `src/` when the project has one); import it as `@/components/ui/DigitalStamp`. 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 |
+| --- | --- | --- | --- |
+| `message` | `ReactNode` | — | Short verification message shown in the collapsed bar. |
+| `features?` | `DigitalStampFeature[]` | — | Feature rows shown inside the opened panel. Defaults to domain + HTTPS (see `labels`). |
+| `registrationTitle?` | `ReactNode` | — | Optional heading shown above the registration description (e.g. "Registered with DGA"). |
+| `registrationDescription?` | `ReactNode` | — | Descriptive text before the registration number link. Defaults to `labels.registeredOn`. |
+| `registrationNumber?` | `ReactNode` | — | Registration number displayed as a link. |
+| `registrationHref?` | `string` | — | href for the registration number link. |
+| `authorityLogo?` | `ReactNode` | — | Optional DGA (authority) logo node. A default monogram is used when omitted. |
+| `flag?` | `ReactNode` | — | Optional flag node rendered on the leading side (defaults to the Saudi flag). |
+| `defaultOpen?` | `boolean` | false | Uncontrolled initial open state. |
+| `open?` | `boolean` | — | Controlled open state. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Fires when the disclosure toggles. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `labels?` | `Partial<DigitalStampLabels>` | — | Override built-in strings (English defaults) to localize the stamp. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `howYouKnowLabel`
+
+## 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-emphasis-low)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-success-strong)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-link-primary)`
+- `var(--ds-color-link-primary-hovered)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add digital-stamp` (after `npx sdaia-ui@latest init`), then import `{ DigitalStamp }` from `@/components/ui/DigitalStamp`.
+- 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/divider.md

@@ -0,0 +1,65 @@
+# Divider
+
+## Metadata
+- Component: Divider
+- Slug: `divider`
+- Category: General
+- Install: `npx sdaia-ui@latest add divider`
+- Import: `import { Divider } from '@/components/ui/Divider'`
+- Installed files: `Divider.tsx`, `Divider.types.ts`, `Divider.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/divider
+
+> **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 divider`. It copies the source into your components folder (`components/ui/Divider/`, under `src/` when the project has one); import it as `@/components/ui/Divider`. 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 |
+| --- | --- | --- | --- |
+| `lineType?` | `'horizontal' \| 'vertical'` | 'horizontal' | Orientation of the divider. Default: `'horizontal'`. |
+| `color?` | `'neutral' \| 'primary'` | 'neutral' | Color scheme. Default: `'neutral'`. |
+| `thickness?` | `'hairline' \| 'thin' \| 'regular' \| 'thick'` | 'hairline' | Line weight. Default: `'hairline'`. |
+| `length?` | `'full' \| 'inset' \| 'inset-start' \| 'inset-end'` | 'full' | Inset variant — horizontal only. Default: `'full'`. |
+| `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)
+- `lineType`: `'horizontal'` \| `'vertical'` — Orientation of the divider line.
+- `color`: `'neutral'` \| `'primary'` — Color palette (Figma node 4016:1408).
+  neutral → --ds-color-border-default
+  primary → --ds-color-border-brand
+- `thickness`: `'hairline'` \| `'thin'` \| `'regular'` \| `'thick'` — Visual weight of the line.
+  hairline → 1 px
+  thin     → 2 px
+  regular  → 3 px
+  thick    → 4 px
+- `length`: `'full'` \| `'inset'` \| `'inset-start'` \| `'inset-end'` — Inset padding applied to horizontal dividers.
+Uses logical CSS properties so RTL is handled automatically:
+  full        → no inset (full container width)
+  inset       → spacing-3xl on both sides
+  inset-start → spacing-3xl on inline-start (left in LTR, right in RTL)
+  inset-end   → spacing-3xl on inline-end   (right in LTR, left in RTL)
+
+Note: vertical dividers always fill the container height; `length`
+has no effect when lineType="vertical".
+- `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-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-spacing-3xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add divider` (after `npx sdaia-ui@latest init`), then import `{ Divider }` from `@/components/ui/Divider`.
+- 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/donut-chart.md

@@ -0,0 +1,75 @@
+# Donut Chart
+
+## Metadata
+- Component: Donut Chart
+- Slug: `donut-chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add donut-chart`
+- Import: `import { DonutChart } from '@/components/ui/DonutChart'`
+- Installed files: `DonutChart.tsx`, `DonutChart.types.ts`, `DonutChart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/donut-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 donut-chart`. It copies the source into your components folder (`components/ui/DonutChart/`, under `src/` when the project has one); import it as `@/components/ui/DonutChart`. 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 |
+| --- | --- | --- | --- |
+| `variant?` | `'Color Border' \| 'Color Filled'` | 'Color Border' | Rendering style — controls whether the ring has a grey track and whether the pie mode renders ring arcs or solid sectors. |
+| `pie?` | `boolean` | false | `false` — single-arc donut driven by `percentage`. `true`  — multi-slice chart driven by `series` / `sliceData`. |
+| `percentage?` | `number` | — | Fill percentage for donut mode (pie=false), 0–100. Without it the chart renders its no-data state (`labels.noData`). |
+| `slices?` | `DonutChartSliceCount` | — | Number of equal slices in pie mode (pie=true) when no `series` / `sliceData` is given. Ignored when either is supplied. Without `series`, `sliceData` or `slices`, pie mode renders the no-data state. |
+| `series?` | `DonutChartSeriesItem[]` | — | Preferred series JSON for pie mode. Use this when integrating with chart panels/legends to keep values in sync. |
+| `sliceData?` | `DonutChartSliceData[]` | — | Custom per-slice data for pie mode. When provided, overrides `slices` and uses `value` for proportional sizing and `color` for per-slice colour. |
+| `helperText?` | `string` | — | Helper text rendered above the bold label inside the ring. Omit it (or pass `''`) to hide it. |
+| `label?` | `string` | — | Bold value rendered below the helper text. In donut mode defaults to `'${percentage}%'`. Set to `undefined` or `''` to hide. |
+| `size?` | `number` | DEFAULT_SIZE | Diameter of the component in px. All geometry (stroke-width, radius) scales proportionally. |
+| `segmentGap?` | `number` | PIE_RING_GAP_DEG | Gap in degrees between adjacent ring arc segments (pie=true, Color Border). Set to `0` for flush/seamless segments. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. In `'rtl'` the fill arc / pie sectors are mirrored horizontally (they run counter-clockwise from 12 o'clock), matching the chart-wide decision that charts mirror in RTL. When omitted, the direction inherited from the closest `dir` ancestor is used. |
+| `labels?` | `Partial<DonutChartLabels>` | — | Translatable built-in strings (accessible names, no-data message, data-table headers). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `variant`: `'Color Border'` \| `'Color Filled'` — Visual rendering style.
+
+| Value          | pie=false                              | pie=true                        |
+|----------------|----------------------------------------|---------------------------------|
+| 'Color Border' | Grey track ring + green fill arc       | Ring divided into N coloured arc segments (gaps between) |
+| 'Color Filled' | Green arc only, transparent background | Full pie — N solid sectors from centre |
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. In `'rtl'` the fill arc / pie sectors are mirrored
+horizontally (they run counter-clockwise from 12 o'clock), matching the
+chart-wide decision that charts mirror in RTL. When omitted, the direction
+inherited from the closest `dir` ancestor is used.
+
+## 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-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-chart-series-1)`
+- `var(--ds-color-chart-series-2)`
+- `var(--ds-color-chart-series-3)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-xs)`
+- `var(--ds-text-size-display-sm)`
+- `var(--ds-text-size-text-lg)`
+- `var(--ds-themes-chart-chart-series-4)`
+- `var(--ds-themes-chart-chart-series-5)`
+- `var(--ds-themes-chart-chart-series-6)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add donut-chart` (after `npx sdaia-ui@latest init`), then import `{ DonutChart }` from `@/components/ui/DonutChart`.
+- 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/draggable-list.md

@@ -0,0 +1,43 @@
+# Draggable List
+
+## Metadata
+- Component: Draggable List
+- Slug: `draggable-list`
+- Category: General
+- Install: `npx sdaia-ui@latest add draggable-list`
+- Import: `import { DraggableList } from '@/components/ui/DraggableList'`
+- Installed files: `DraggableList.tsx`, `DraggableList.types.ts`, `DraggableList.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/draggable-list
+
+> **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 draggable-list`. It copies the source into your components folder (`components/ui/DraggableList/`, under `src/` when the project has one); import it as `@/components/ui/DraggableList`. 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 |
+| --- | --- | --- | --- |
+| `children?` | `ReactNode` | — | List items (typically `DraggableItem` elements). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction for logical layout. Prefer inheriting from an ancestor; set explicitly for documentation previews. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction for logical layout. Prefer inheriting from an ancestor;
+set explicitly for documentation previews.
+
+## 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-lg)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add draggable-list` (after `npx sdaia-ui@latest init`), then import `{ DraggableList }` from `@/components/ui/DraggableList`.
+- 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.