@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/general/pdf-viewer.md

@@ -0,0 +1,91 @@
+# PDF Viewer
+
+## Metadata
+- Component: PDF Viewer
+- Slug: `pdf-viewer`
+- Category: General
+- Install: `npx sdaia-ui@latest add pdf-viewer`
+- Import: `import { PdfViewer } from '@/components/ui/PdfViewer'`
+- Installed files: `PdfViewer.tsx`, `PdfViewer.types.ts`, `PdfViewer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/pdf-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 pdf-viewer`. It copies the source into your components folder (`components/ui/PdfViewer/`, under `src/` when the project has one); import it as `@/components/ui/PdfViewer`. 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 |
+| --- | --- | --- | --- |
+| `breakpoint?` | `'desktop' \| 'tablet' \| 'mobile'` | 'desktop' | Visual breakpoint style from the Figma component. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Forces a direction on the component root (defaults to inheriting). |
+| `labels?` | `Partial<PdfViewerLabels>` | — | Translatable built-in text. Unset keys use the English defaults. |
+| `showHeader?` | `boolean` | true | Shows the top header area. |
+| `headerTitle?` | `ReactNode` | — | Main header title (centered). Note: We intentionally avoid the prop name `title` because it conflicts with the native HTML `title` attribute on div elements. |
+| `headerSubtitle?` | `ReactNode` | — | Header subtitle (centered, e.g. file size). |
+| `infoItems?` | `PdfViewerInfoItem[]` | [] | Optional info items shown under the title (e.g. number/date). |
+| `showCloseButton?` | `boolean` | true | Shows the close button in the header. |
+| `onClose?` | `() => void` | — | Called when the close button is clicked. |
+| `showPrimaryAction?` | `boolean` | true | Shows the primary header action button (download in Figma). |
+| `onPrimaryAction?` | `() => void` | — | Called when the primary action button is clicked. |
+| `showZoomControls?` | `boolean` | true | Shows the bottom zoom controls bar. |
+| `zoom?` | `number` | — | Zoom percentage (controlled). When provided, the zoom buttons will call `onZoomChange` but will not manage internal state. |
+| `defaultZoom?` | `number` | 100 | Initial zoom percentage (uncontrolled). |
+| `minZoom?` | `number` | 25 | Minimum zoom percentage. |
+| `maxZoom?` | `number` | 200 | Maximum zoom percentage. |
+| `zoomStep?` | `number` | 25 | Zoom step used by +/- buttons. |
+| `onZoomChange?` | `(zoom: number) => void` | — | Called whenever zoom changes (both controlled & uncontrolled). |
+| `zoomLabel?` | `ReactNode` | — | Override the label shown in the zoom dropdown (defaults to `${zoom}%`). |
+| `onZoomOut?` | `() => void` | — | Called when the "zoom out" control is clicked (in addition to zoom changing). |
+| `onZoomIn?` | `() => void` | — | Called when the "zoom in" control is clicked (in addition to zoom changing). |
+| `onZoomFit?` | `() => void` | — | Called when the "fit" (reset) control is clicked (in addition to zoom changing). |
+| `onZoomMenu?` | `() => void` | — | Called when the zoom dropdown is clicked. |
+| `children?` | `ReactNode` | — | Main content rendered under the header. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `breakpoint`: `'desktop'` \| `'tablet'` \| `'mobile'` — Visual breakpoint style from the Figma component.
+- `dir`: `'ltr'` \| `'rtl'` — Forces a direction on the component root (defaults to inheriting).
+
+## Deprecated props
+Do not use in new code:
+- `closeLabel` — Accessible label for the close button.
+- `primaryActionLabel` — Primary action label.
+
+## 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-canvas)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-bg-emphasis-strong)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-9xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add pdf-viewer` (after `npx sdaia-ui@latest init`), then import `{ PdfViewer }` from `@/components/ui/PdfViewer`.
+- 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/pie-chart-panel.md

@@ -0,0 +1,86 @@
+# Pie Chart
+
+## Metadata
+- Component: Pie Chart
+- Slug: `pie-chart-panel`
+- Category: General
+- Install: `npx sdaia-ui@latest add pie-chart-panel`
+- Import: `import { PieChartPanel } from '@/components/ui/PieChartPanel'`
+- Installed files: `PieChartPanel.tsx`, `PieChartPanel.types.ts`, `PieChartPanel.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/pie-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 pie-chart-panel`. It copies the source into your components folder (`components/ui/PieChartPanel/`, under `src/` when the project has one); import it as `@/components/ui/PieChartPanel`. 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?` | `'SummaryView' \| 'IndicatorView' \| 'HeroView' \| 'BreakdownPanel' \| 'ComparisonView' \| 'LegendBlock' \| 'LabeledView' \| 'AnnotatedView' \| 'OverviewPanel' \| 'CompactPanel'` | 'SummaryView' | Which layout variant to render. |
+| `title?` | `string` | — | Card title (Display sm / Bold). Also the panel's accessible name. Every text prop below is optional: nothing is rendered for a prop you omit (no placeholder copy). Without `series` the pie shows its no-data state (`labels.noData`). |
+| `note?` | `string` | — | Subtitle / note below the title (Text md / Regular, secondary) |
+| `indicatorName?` | `string` | — | Indicator name label |
+| `indicatorValue?` | `string` | — | Primary metric value e.g. "422.61" |
+| `badgeValue?` | `string` | — | Badge percentage e.g. "12%" |
+| `badgeDirection?` | `'up' \| 'down'` | 'up' | Arrow direction — 'up' = green positive, 'down' = red negative |
+| `dateBadge?` | `string` | — | Date string rendered in a pill e.g. "26/02/2026" |
+| `optionsLabel?` | `string` | labels.options ('Options') | Label for the Options dropdown button in OverviewPanel. |
+| `menuOptions?` | `string[]` | — | List of option labels shown in the Options dropdown (OverviewPanel). When provided the button becomes interactive and opens a menu on click. |
+| `activeOption?` | `string` | — | Currently active option — should match one of the `menuOptions` strings. |
+| `onOptionSelect?` | `(option: string) => void` | — | Called when the user selects an option from the dropdown. |
+| `series?` | `PieChartPanelItem[]` | — | Series items used to build the pie chart + legend / data rows. Max 6 items; each has `label`, `value`, `change`, `percentage`, `color`. |
+| `tabs?` | `PieChartPanelTab[]` | — | Tab items for LabeledView / AnnotatedView |
+| `onTabChange?` | `(index: number) => void` | — | Fired when a tab is clicked |
+| `progress?` | `number` | — | Playback progress 0-100 for the CompactPanel scrubber (controlled). Omit to let the component manage its own scrubber position. |
+| `defaultProgress?` | `number` | 0 | Initial scrubber progress when uncontrolled. |
+| `currentTime?` | `string` | '0:00' | Current-time display string for CompactPanel, e.g. "0:12". |
+| `duration?` | `string` | '0:00' | Total-duration display string for CompactPanel, e.g. "2:32". |
+| `onProgressChange?` | `(value: number) => void` | — | Called when the user scrubs the CompactPanel progress bar. Receives the new value in the range 0-100. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the panel. In RTL the layout mirrors (logical spacing, data-row borders on the right, scrubber fills from the right) and the pie runs counter-clockwise. When omitted, the inherited direction is used. |
+| `labels?` | `Partial<PieChartPanelLabels>` | — | Translatable built-in strings (button names, scrubber, no-data message, data-table headers). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `title`.
+
+## Options (allowed values)
+- `variant`: `'SummaryView'` \| `'IndicatorView'` \| `'HeroView'` \| `'BreakdownPanel'` \| `'ComparisonView'` \| `'LegendBlock'` \| `'LabeledView'` \| `'AnnotatedView'` \| `'OverviewPanel'` \| `'CompactPanel'` — Which layout variant to render.
+- `badgeDirection`: `'up'` \| `'down'` — Arrow direction — 'up' = green positive, 'down' = red negative
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the panel. In RTL the layout mirrors (logical spacing,
+data-row borders on the right, scrubber fills from the right) and the pie
+runs counter-clockwise. When omitted, the inherited direction 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-border-strong)`
+- `var(--ds-color-button-bg-neutral-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-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `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 pie-chart-panel` (after `npx sdaia-ui@latest init`), then import `{ PieChartPanel }` from `@/components/ui/PieChartPanel`.
+- 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/popover.md

@@ -0,0 +1,115 @@
+# Popover
+
+## Metadata
+- Component: Popover
+- Slug: `popover`
+- Category: General
+- Install: `npx sdaia-ui@latest add popover`
+- Import: `import { Popover } from '@/components/ui/Popover'`
+- Installed files: `Popover.tsx`, `Popover.types.ts`, `Popover.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/popover
+
+> **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 popover`. It copies the source into your components folder (`components/ui/Popover/`, under `src/` when the project has one); import it as `@/components/ui/Popover`. 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 popover panel is visible (controlled mode). |
+| `defaultOpen?` | `boolean` | false | Initial open state for uncontrolled mode. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the open state changes (close button click, outside click, Escape). |
+| `trigger?` | `ReactNode` | — | The element that opens/closes the popover on click. When omitted, a default trigger is rendered based on `triggerType`. Pass a single focusable element (e.g. a `<Button>`): it receives `aria-expanded`, `aria-haspopup="dialog"` and `aria-controls`, and focus returns to it when the popover closes. |
+| `triggerType?` | `'button' \| 'link'` | 'button' | Whether the default built-in trigger is a Button or a Link. Only used when `trigger` is not provided. |
+| `triggerLabel?` | `string` | — | Label on the default trigger element. Only used when `trigger` is not provided. Falls back to `labels.trigger`. |
+| `featuredIcon?` | `ReactNode` | — | Custom circular-badge icon shown above the title in the panel. |
+| `title?` | `string` | — | Semibold title text at the top of the panel body. |
+| `helperText?` | `ReactNode` | — | Primary body text (text-sm / regular). |
+| `supportingText?` | `ReactNode` | — | Secondary body text (text-xs / regular, muted). |
+| `image?` | `string \| ReactNode` | — | Image content rendered between supporting text and instance rows. Accepts either: - A `string` URL (rendered as `<img src={...} />`), or - A `ReactNode` (e.g. a pre-composed `<img>` or `<Image>` component). |
+| `imageAlt?` | `string` | '' | Accessible alt text for the image when `image` is a URL string. |
+| `instanceRows?` | `ReactNode` | — | Custom slot rendered below the image inside the panel body. |
+| `children?` | `ReactNode` | — | Free-form content rendered at the bottom of the panel body — after all named slots. |
+| `showCloseButton?` | `boolean` | true | Show the × close button in the top-trailing corner. |
+| `primaryActionLabel?` | `string` | — | Label for the primary (solid-green) action button. When omitted the actions row is hidden. |
+| `secondaryActionLabel?` | `string` | — | Label for the secondary (outlined) action button. When omitted only one button shows. |
+| `onPrimaryAction?` | `() => void` | — | Called when the primary action button is clicked. |
+| `onSecondaryAction?` | `() => void` | — | Called when the secondary action button is clicked. |
+| `actionsAlignment?` | `'start' \| 'center' \| 'end'` | 'start' | Alignment of action buttons in the footer. |
+| `placement?` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | 'bottom' | Where the panel appears relative to the trigger. |
+| `showBeak?` | `boolean` | true | Whether to render the directional arrow (beak). |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. Placement `start`/`end` and the close-button position flip in RTL. |
+| `labels?` | `Partial<PopoverLabels>` | — | Override built-in strings (English defaults) to localize the popover. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `triggerType`: `'button'` \| `'link'` — Whether the default built-in trigger is a Button or a Link.
+- `actionsAlignment`: `'start'` \| `'center'` \| `'end'` — How action buttons are laid out in the panel footer.
+
+- `start`  — buttons sit at the leading edge (natural width).
+- `center` — buttons expand equally to fill the row.
+- `end`    — buttons sit at the trailing edge (natural width).
+- `placement`: `'top'` \| `'top-start'` \| `'top-end'` \| `'bottom'` \| `'bottom-start'` \| `'bottom-end'` \| `'left'` \| `'left-start'` \| `'left-end'` \| `'right'` \| `'right-start'` \| `'right-end'` — Where the popover panel appears relative to its trigger.
+
+- `top` / `bottom`        — panel centered on the trigger horizontally.
+- `*-start` / `*-end`     — panel aligned to the leading / trailing edge.
+- `left` / `right` (and variants) — panel placed to the side of the trigger.
+
+In RTL mode `start` and `end` are automatically mirrored.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the popover panel.
+  - `'solid'` (default) — opaque card with a hairline border + drop shadow.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Reads best when the panel overlays 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.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+Placement `start`/`end` and the close-button position flip in RTL.
+
+## Deprecated props
+Do not use in new code:
+- `instanceRowCount`
+
+## 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-10)`
+- `var(--ds-color-alpha-black-20)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-success-muted)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-color-tooltip-bg-on-dark)`
+- `var(--ds-glass-bg)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+- `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 popover` (after `npx sdaia-ui@latest init`), then import `{ Popover }` from `@/components/ui/Popover`.
+- 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/progress-circle.md

@@ -0,0 +1,63 @@
+# Progress Circle
+
+## Metadata
+- Component: Progress Circle
+- Slug: `progress-circle`
+- Category: General
+- Install: `npx sdaia-ui@latest add progress-circle`
+- Import: `import { ProgressCircle } from '@/components/ui/ProgressCircle'`
+- Installed files: `ProgressCircle.tsx`, `ProgressCircle.types.ts`, `ProgressCircle.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/progresscircle
+
+> **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 progress-circle`. It copies the source into your components folder (`components/ui/ProgressCircle/`, under `src/` when the project has one); import it as `@/components/ui/ProgressCircle`. 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 |
+| --- | --- | --- | --- |
+| `value?` | `number` | 0 | Current progress value (0–100) |
+| `variant?` | `'primary' \| 'neutral'` | 'primary' | Visual style |
+| `shape?` | `'circle' \| 'half-circle'` | 'circle' | Shape of the progress indicator |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | 'md' | Size preset |
+| `valueText?` | `boolean` | true | Show percentage text in the center |
+| `labelText?` | `boolean` | false | Show `label` below the percentage (only visible at md, lg, xl). Nothing is rendered when `label` is not provided. |
+| `label?` | `string` | — | Label text (e.g. "Active Users"). Also used as the accessible name of the progress bar when no `aria-label` / `aria-labelledby` is passed. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `animateOnView?` | `boolean` | false | Animate the progress arc from 0 when the component enters the viewport |
+| `labels?` | `Partial<ProgressCircleLabels>` | — | Override built-in strings (English defaults) to localize the progress circle. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `variant`: `'primary'` \| `'neutral'` — Visual style
+- `shape`: `'circle'` \| `'half-circle'` — Shape of the progress indicator
+- `size`: `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` — Size preset
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `direction`
+
+## Accessibility
+Built in (SDAIA review item A7) — verified by `axe scan (aria-progressbar-name) — audit-reports/a11y` in the design system's test suite:
+- Renders a `role="progressbar"` with its current value, named by `label` (or your `aria-label` / `aria-labelledby`).
+
+You must:
+- Pass a `label` or `aria-label` that says what is progressing.
+
+- 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-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-stepper-button-current)`
+- `var(--ds-color-text-paragraph)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add progress-circle` (after `npx sdaia-ui@latest init`), then import `{ ProgressCircle }` from `@/components/ui/ProgressCircle`.
+- 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/quote.md

@@ -0,0 +1,64 @@
+# Quote
+
+## Metadata
+- Component: Quote
+- Slug: `quote`
+- Category: General
+- Install: `npx sdaia-ui@latest add quote`
+- Import: `import { Quote } from '@/components/ui/Quote'`
+- Installed files: `Quote.tsx`, `Quote.types.ts`, `Quote.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/quote
+
+> **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 quote`. It copies the source into your components folder (`components/ui/Quote/`, under `src/` when the project has one); import it as `@/components/ui/Quote`. 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 |
+| --- | --- | --- | --- |
+| `style?` | `'standard' \| 'centered' \| 'author-image' \| 'author-side'` | 'standard' | Layout variant. |
+| `title?` | `string` | — | Title text rendered as the quote heading. Not rendered when omitted. |
+| `quote?` | `string` | — | Body/quote text (the actual quoted content). Not rendered when omitted. |
+| `authorName?` | `string` | — | Author's display name. Not rendered when omitted. |
+| `authorRole?` | `string` | — | Author's role or title below their name. Not rendered when omitted. |
+| `showStar?` | `boolean` | true | Show the star/favorite icon. Applies to `'standard'` (bottom-end corner) and `'centered'` (top center). Has no visual effect on `'author-image'` or `'author-side'`. |
+| `imageSrc?` | `string` | — | URL of the author photo. Required for `'author-image'` and `'author-side'` styles to display an image. |
+| `imageAlt?` | `string` | '' | Accessible alt text for the author photo. |
+| `className?` | `string` | — | Additional className applied to the card root element. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `style`, `title`, `children`.
+
+## Options (allowed values)
+- `style`: `'standard'` \| `'centered'` \| `'author-image'` \| `'author-side'` — Quote layout style.
+
+- `'standard'`      — flex-col card: title+description on top, author+star row at bottom.
+- `'centered'`      — flex-col card: star centered at top, then title+description centered,
+                      then author centered.
+- `'author-image'`  — flex-row card: 120×120 author photo + name/role on the start side,
+                      title+description on the end side.
+- `'author-side'`   — flex-row card: 160 px wide photo fills full height on the start side,
+                      title+description+author on the end side.
+
+RTL is inherited from `dir="rtl"` on any ancestor, or set explicitly with the
+`dir` prop. The `flex-row` layouts flip visually in RTL via CSS logical properties.
+- `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-canvas)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add quote` (after `npx sdaia-ui@latest init`), then import `{ Quote }` from `@/components/ui/Quote`.
+- 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/radial-stepper.md

@@ -0,0 +1,72 @@
+# Radial Stepper
+
+## Metadata
+- Component: Radial Stepper
+- Slug: `radial-stepper`
+- Category: General
+- Install: `npx sdaia-ui@latest add radial-stepper`
+- Import: `import { RadialStepper } from '@/components/ui/RadialStepper'`
+- Installed files: `RadialStepper.tsx`, `RadialStepper.types.ts`, `RadialStepper.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/radial-stepper
+
+> **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 radial-stepper`. It copies the source into your components folder (`components/ui/RadialStepper/`, under `src/` when the project has one); import it as `@/components/ui/RadialStepper`. 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?` | `'48px' \| '64px' \| '80px' \| '120px'` | '64px' | Ring diameter tier (default: '64px'). Controls CircularItem size AND the text typography tier. |
+| `layout?` | `'Horizontal' \| 'Vertical'` | 'Horizontal' | Flex direction of the component (default: 'Horizontal'). Horizontal: ring left (LTR) or right (RTL) of the text block. Vertical:   ring above, text block below, both centred. |
+| `variant?` | `'Primary' \| 'Neutral'` | 'Primary' | Arc colour theme passed to CircularItem (default: 'Primary'). Named `variant` to avoid conflict with HTMLAttributes.style. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. "rtl": ring moves to the end (right) of a horizontal layout, text right-aligns and the arc fills counter-clockwise. Inherits from the nearest `dir` ancestor when omitted. |
+| `indicator?` | `CircularItemIndicator` | '1 of 4' | Step progress passed directly to CircularItem (default: '1 of 4'). |
+| `previousLabel?` | `string` | — | Text of the previous-step row (e.g. the previous step's name). Takes precedence over `labels.previous`. |
+| `showPrevious?` | `boolean` | true | Show / hide the previous-step row (default: true). |
+| `stepName?` | `string` | — | Current step name. Renders nothing when omitted. |
+| `showStepName?` | `boolean` | true | Show / hide the step-name row (default: true). |
+| `description?` | `string` | — | Step description. Renders nothing when omitted. |
+| `showDescription?` | `boolean` | true | Show / hide the description row (default: true). |
+| `nextLabel?` | `string` | — | Text of the next-step row (e.g. the next step's name). Takes precedence over `labels.next`. |
+| `showNext?` | `boolean` | true | Show / hide the next-step row (default: true). |
+| `labels?` | `Partial<RadialStepperLabels>` | — | Translatable built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `size`: `'48px'` \| `'64px'` \| `'80px'` \| `'120px'` — Physical size of the circular ring.
+Matches the Figma `Size` property names exactly.
+Maps 1-to-1 to CircularItem sizes:
+  48px → Small  |  64px → Medium  |  80px → Large  |  120px → Extra Large
+- `layout`: `'Horizontal'` \| `'Vertical'` — Flex direction of the component.
+Horizontal: ring beside text.
+Vertical:   ring above text.
+- `variant`: `'Primary'` \| `'Neutral'` — Arc colour passed down to CircularItem.
+Primary = green (#1b8354), Neutral = dark navy (#1f2a37).
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. "rtl": ring moves to the end
+(right) of a horizontal layout, text right-aligns and the arc fills
+counter-clockwise. Inherits from the nearest `dir` ancestor 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-)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-size-text-)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add radial-stepper` (after `npx sdaia-ui@latest init`), then import `{ RadialStepper }` from `@/components/ui/RadialStepper`.
+- 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/scatter-chart.md

@@ -0,0 +1,62 @@
+# Scatter
+
+## Metadata
+- Component: Scatter
+- Slug: `scatter-chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add scatter-chart`
+- Import: `import { ScatterChart } from '@/components/ui/ScatterChart'`
+- Installed files: `ScatterChart.tsx`, `ScatterChart.types.ts`, `ScatterChart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/scatter
+
+> **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 scatter-chart`. It copies the source into your components folder (`components/ui/ScatterChart/`, under `src/` when the project has one); import it as `@/components/ui/ScatterChart`. 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 |
+| --- | --- | --- | --- |
+| `title?` | `string` | — | Optional chart title rendered above the chart; it also names the chart. |
+| `points?` | `ScatterPoint[]` | — | Scatter data points in data-space coordinates. When missing or empty the chart shows `labels.noData` — there is no sample data. |
+| `yTicks?` | `string[]` | — | Y-axis tick labels from top to bottom, spread evenly from `yMax` (top) to `yMin` (bottom). An empty string '' renders an invisible spacer row (its grid line stays). When omitted, "nice" ticks are computed from the domain and formatted for `locale`. |
+| `xTicks?` | `string[]` | — | X-axis tick labels from `xMin` to `xMax` (in RTL the axis mirrors, so the first tick is on the right). An empty string '' renders an invisible spacer cell. When omitted, ticks are computed from the domain. |
+| `xMin?` | `number` | derived from `points` (rounded) | Minimum data-space X value. |
+| `xMax?` | `number` | derived from `points` (rounded) | Maximum data-space X value. |
+| `yMin?` | `number` | derived from `points` (rounded) | Minimum data-space Y value. |
+| `yMax?` | `number` | derived from `points` (rounded) | Maximum data-space Y value. |
+| `locale?` | `string` | — | BCP 47 locale for the computed tick labels and table values (`Intl.NumberFormat`), e.g. `'ar-SA'`. |
+| `labels?` | `Partial<ScatterChartLabels>` | — | Overrides for the built-in text (accessible name, messages), e.g. Arabic. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Charts mirror their axes in RTL: the Y axis moves to the right and x grows right-to-left (the origin is at the bottom right). Inherited from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Charts mirror their axes in RTL: the Y axis moves to the
+right and x grows right-to-left (the origin is at the bottom right).
+Inherited from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `type` — Trend preset of the Figma frames.
+- `rtl` — Render in RTL layout (mirrors dot X positions).
+
+## 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-default)`
+- `var(--ds-color-chart-series-1)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add scatter-chart` (after `npx sdaia-ui@latest init`), then import `{ ScatterChart }` from `@/components/ui/ScatterChart`.
+- 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/second-nav-header.md

@@ -0,0 +1,55 @@
+# Second Nav Header
+
+## Metadata
+- Component: Second Nav Header
+- Slug: `second-nav-header`
+- Category: General
+- Install: `npx sdaia-ui@latest add second-nav-header`
+- Import: `import { SecondNavHeader } from '@/components/ui/SecondNavHeader'`
+- Installed files: `SecondNavHeader.tsx`, `SecondNavHeader.types.ts`, `SecondNavHeader.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/second-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 second-nav-header`. It copies the source into your components folder (`components/ui/SecondNavHeader/`, under `src/` when the project has one); import it as `@/components/ui/SecondNavHeader`. 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?` | `SubHeaderItemProps[]` | — | Up to 3 contextual info items (e.g. weather, date, time). Each entry is spread onto a `SubHeaderItem`. |
+| `instance?` | `ReactNode` | — | Custom content injected into the Instance slot (leading side of the trailing group). Typically a breadcrumb, tab set, or status chip. |
+| `label?` | `string` | — | Secondary text label shown in the trailing group (e.g. "List Item"). |
+| `actions?` | `ReactNode` | — | Action content — typically one to three `<Button iconOnly>` elements. Rendered in a `gap-spacing-sm` flex row. |
+| `divider?` | `boolean` | true | Whether to render a bottom border divider. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root element (and every item); inherits from the page when omitted. |
+| `className?` | `string` | — | — |
+
+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 (and every item); inherits from the page 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-bg-canvas)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-4xl)`
+- `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 second-nav-header` (after `npx sdaia-ui@latest init`), then import `{ SecondNavHeader }` from `@/components/ui/SecondNavHeader`.
+- 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.