@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/general/dropdown.md

@@ -0,0 +1,90 @@
+# Dropdown
+
+## Metadata
+- Component: Dropdown
+- Slug: `dropdown`
+- Category: General
+- Install: `npx sdaia-ui@latest add dropdown`
+- Import: `import { Dropdown } from '@/components/ui/Dropdown'`
+- Installed files: `Dropdown.tsx`, `Dropdown.types.ts`, `Dropdown.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/dropdown
+
+> **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 dropdown`. It copies the source into your components folder (`components/ui/Dropdown/`, under `src/` when the project has one); import it as `@/components/ui/Dropdown`. 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 — set to 'rtl' for Arabic. Passed to the root element; inherits from the page when omitted. |
+| `labels?` | `Partial<DropdownLabels>` | — | Override the built-in accessible strings (English defaults). |
+| `type?` | `'button' \| 'icon' \| 'avatar'` | 'button' | Determines which trigger element is rendered. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment of the panel — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `alignment?` | `'start' \| 'center' \| 'end'` | 'end' | Panel alignment relative to the trigger. |
+| `placement?` | `'top' \| 'bottom'` | 'bottom' | Whether the panel opens above or below the trigger. |
+| `label?` | `string` | — | Label for the button trigger. Used when type="button". Nothing is rendered when omitted. |
+| `variant?` | `ButtonMenuVariant` | 'primary' | Visual variant for the ButtonMenu trigger. Defaults to 'primary'. |
+| `size?` | `ButtonMenuSize` | 'md' | Size of the ButtonMenu trigger. Defaults to 'md'. |
+| `avatarSrc?` | `string` | — | URL of the avatar image. Used when type="avatar". |
+| `avatarAlt?` | `string` | — | Alt text for the avatar image. |
+| `header?` | `DropdownListHeaderProps` | — | Props forwarded to the DropdownListHeader at the top of the panel. |
+| `items?` | `DropdownItem[]` | [] | Rows rendered in the panel body as ContextMenuDropdown entries. |
+| `disabled?` | `boolean` | false | Whether the panel is disabled. Prevents opening. |
+| `open?` | `boolean` | — | Controlled open state. When provided, the component is fully controlled — pair with `onOpenChange`. |
+| `defaultOpen?` | `boolean` | false | Initial open state for uncontrolled usage. Ignored when `open` is provided. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the open state changes (trigger click or outside click). Required for controlled usage. |
+| `className?` | `string` | — | Additional class names on the root wrapper |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — set to 'rtl' for Arabic. Passed to the root element; inherits from the page when omitted.
+- `type`: `'button'` \| `'icon'` \| `'avatar'` — Trigger type — maps Figma "Type" property:
+  Button → ButtonMenu trigger (label + chevron)
+  Icon   → more-vertical (⋮) icon-only trigger
+  Avatar → circular avatar image trigger
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the dropdown panel.
+  - `'solid'` (default) — opaque raised surface 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.
+- `alignment`: `'start'` \| `'center'` \| `'end'` — Panel alignment relative to the trigger — maps Figma "Alignment" property.
+  start  → panel aligns to the inline-start edge of the trigger
+  center → panel centered below the trigger
+  end    → panel aligns to the inline-end edge of the trigger
+- `placement`: `'top'` \| `'bottom'` — Whether the panel opens above or below the trigger.
+
+## 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-bg-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-form-option-bg-hover)`
+- `var(--ds-color-form-option-bg-pressed)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-icon-default-disabled)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add dropdown` (after `npx sdaia-ui@latest init`), then import `{ Dropdown }` from `@/components/ui/Dropdown`.
+- 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".
+- 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/empty-state.md

@@ -0,0 +1,60 @@
+# Empty State
+
+## Metadata
+- Component: Empty State
+- Slug: `empty-state`
+- Category: General
+- Install: `npx sdaia-ui@latest add empty-state`
+- Import: `import { EmptyState } from '@/components/ui/EmptyState'`
+- Installed files: `EmptyState.tsx`, `EmptyState.types.ts`, `EmptyState.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/empty-state
+
+> **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 empty-state`. It copies the source into your components folder (`components/ui/EmptyState/`, under `src/` when the project has one); import it as `@/components/ui/EmptyState`. 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?` | `'no-data' \| 'no-connection' \| 'error' \| 'no-notifications' \| 'connection-lost' \| 'page-not-found'` | 'no-data' | Content/layout preset from Figma (State Types). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `labels?` | `Partial<EmptyStateLabels>` | — | Override built-in strings (English defaults) to localize the empty state. |
+| `illustration?` | `ReactNode` | — | Illustration element. When omitted, no illustration slot is rendered. |
+| `heading?` | `boolean` | true | Shows the heading/title area. |
+| `helperText?` | `boolean` | true | Shows the supporting/helper text. |
+| `button?` | `boolean` | true | Shows the call-to-action button. |
+| `headingContent?` | `ReactNode` | — | Heading content. Nothing is rendered when omitted (no sample copy ships as a default). |
+| `helperTextContent?` | `ReactNode` | — | Supporting text content. Nothing is rendered when omitted. |
+| `buttonLabel?` | `string` | — | Button label. The built-in button renders only when a label is provided. |
+| `onButtonClick?` | `() => void` | — | Click handler for the built-in button. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `type`: `'no-data'` \| `'no-connection'` \| `'error'` \| `'no-notifications'` \| `'connection-lost'` \| `'page-not-found'` — Content/layout preset from Figma (State Types).
+- `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-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add empty-state` (after `npx sdaia-ui@latest init`), then import `{ EmptyState }` from `@/components/ui/EmptyState`.
+- 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/filtration.md

@@ -0,0 +1,85 @@
+# Filtration
+
+## Metadata
+- Component: Filtration
+- Slug: `filtration`
+- Category: General
+- Install: `npx sdaia-ui@latest add filtration`
+- Import: `import { Filtration } from '@/components/ui/Filtration'`
+- Installed files: `Filtration.tsx`, `Filtration.types.ts`, `Filtration.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/filtration
+
+> **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 filtration`. It copies the source into your components folder (`components/ui/Filtration/`, under `src/` when the project has one); import it as `@/components/ui/Filtration`. 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 |
+| --- | --- | --- | --- |
+| `triggerType?` | `'button' \| 'icon'` | 'button' | Controls the shape of the trigger: `'button'` (default) — black pill with filter icon, label, and chevron. `'icon'` — bare 24×24 filter icon with no background. |
+| `triggerLabel?` | `string` | "Filter" | Label shown inside the button trigger (accessible name of the icon trigger and of the panel). Wins over `labels.trigger`. |
+| `activeFilters?` | `FiltrationActiveFilter[]` | [] | Array of active filters currently applied. When non-empty, a row of dismissible green solid Chips is rendered between the trigger and the panel. |
+| `onRemoveFilter?` | `(id: string) => void` | — | Called when the user presses × on an active-filter chip. Receives the `id` of the chip that was dismissed. |
+| `removeFilterLabel?` | `(label: string) => string` | (label) => `Remove ${label}` | Accessible name of each chip's remove (×) control. Localise here, e.g. `(label) => \`إزالة ${label}\``. Wins over `labels.removeFilter`. |
+| `sections?` | `FiltrationSectionConfig[]` | [] | Ordered array of filter sections rendered inside the FiltrationList panel. Supports all nine section types: search, checkbox, select, radio, chip, range, amount, date, custom. |
+| `applyLabel?` | `string` | "Apply Filters" | Label for the primary "Apply" button. Wins over `labels.apply`. |
+| `clearLabel?` | `string` | "Clear" | Label for the secondary "Clear" button. Wins over `labels.clear`. |
+| `activeFilterCount?` | `number` | — | Number shown in parentheses next to the apply label, e.g. "Apply Filters (3)" (format via `labels.applyWithCount`). Falls back to `activeFilters.length` when omitted. |
+| `onApply?` | `() => void` | — | Called when the user presses the Apply button inside the panel. |
+| `onClear?` | `() => void` | — | Called when the user presses the Clear button inside the panel. |
+| `showActions?` | `boolean` | true | When `false`, hides the Apply / Clear footer inside the FiltrationList. Defaults to `true`. |
+| `open?` | `boolean` | — | Controlled open state. When provided, the consumer drives open/close. Combine with `onOpenChange` to handle toggle events. |
+| `defaultOpen?` | `boolean` | false | Uncontrolled initial open state. Defaults to `false`. Ignored when `open` is provided. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called whenever the panel open state changes. |
+| `labels?` | `Partial<FiltrationLabels>` | — | Localised built-in strings (trigger, panel and chip strings). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction of the trigger, chips and panel. Omit to inherit: the portaled panel then copies the trigger's computed direction when it opens. |
+| `className?` | `string` | — | Extra class names forwarded to the root element. |
+| `children?` | `ReactNode` | — | Custom content to render inside the panel below the filter sections. |
+
+## Options (allowed values)
+- `triggerType`: `'button'` \| `'icon'` — Visual style of the trigger button
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction of the trigger, chips and panel. Omit to inherit:
+the portaled panel then copies the trigger's computed direction when it opens.
+
+## Deprecated props
+Do not use in new code:
+- `rtl` — Enables RTL layout by setting `dir="rtl"` on the root element.
+
+## Accessibility
+Built in (SDAIA review item A7) — verified by `axe scan (nested-interactive) — audit-reports/a11y` in the design system's test suite:
+- Chips contain no nested interactive controls (no button inside a button).
+
+- 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-emphasis-medium)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-button-bg-black-focused)`
+- `var(--ds-color-button-bg-black-hovered)`
+- `var(--ds-color-button-bg-black-pressed)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-motion-enter-duration)`
+- `var(--ds-motion-enter-easing)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-2xl)`
+- `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 filtration` (after `npx sdaia-ui@latest init`), then import `{ Filtration }` from `@/components/ui/Filtration`.
+- 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/footer.md

@@ -0,0 +1,59 @@
+# Footer
+
+## Metadata
+- Component: Footer
+- Slug: `footer`
+- Category: General
+- Install: `npx sdaia-ui@latest add footer`
+- Import: `import { Footer } from '@/components/ui/Footer'`
+- Installed files: `Footer.tsx`, `Footer.types.ts`, `Footer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/footer
+
+> **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 footer`. It copies the source into your components folder (`components/ui/Footer/`, under `src/` when the project has one); import it as `@/components/ui/Footer`. 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 |
+| --- | --- | --- | --- |
+| `labels?` | `Partial<FooterLabels>` | — | Translatable built-in strings, shared with every `Footer.*` part inside. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Direction — applied to the root and drives RTL layout. |
+| `compact?` | `boolean` | false | Compact vertical spacing. When `true` the root uses the "Small" footer padding from Figma (shorter `py`, same `px`). Use for minimal footers that do not include link columns or a newsletter block. |
+| `children?` | `ReactNode` | — | — |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Direction — applied to the root and drives RTL layout.
+
+## 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-bg-overlay)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-5xl)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-7xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add footer` (after `npx sdaia-ui@latest init`), then import `{ Footer }` from `@/components/ui/Footer`.
+- 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/line-chart.md

@@ -0,0 +1,95 @@
+# Line Chart
+
+## Metadata
+- Component: Line Chart
+- Slug: `line-chart`
+- Category: General
+- Install: `npx sdaia-ui@latest add line-chart`
+- Import: `import { LineChart } from '@/components/ui/LineChart'`
+- Installed files: `LineChart.tsx`, `LineChart.types.ts`, `LineChart.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/line-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 line-chart`. It copies the source into your components folder (`components/ui/LineChart/`, under `src/` when the project has one); import it as `@/components/ui/LineChart`. 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' \| 'Comparison' \| 'Score' \| 'Forecast'` | 'Insight' | Chart variant. - Insight     — single line with a highlighted data point - Comparison  — two series lines for comparing datasets - Score       — single line with a goal reference line - Forecast    — solid past line + dashed future projection |
+| `xAxisData?` | `XAxisDataType` | '7 Week Days' | X-axis label preset. |
+| `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 for number formatting in the tooltip, Y-axis and data table, e.g. `'ar-SA'`. English names and plain numbers when omitted. |
+| `labels?` | `Partial<LineChartLabels>` | — | Overrides for the built-in strings (see `LineChartLabels`). |
+| `title?` | `string` | — | Optional chart title rendered above the legend. |
+| `height?` | `number` | — | Total chart height in px (including legend + x-axis). Defaults to a preset based on xAxisData. |
+| `graphStyle?` | `'noisy' \| 'smooth' \| 'elastic'` | 'smooth' | Line interpolation style — matches Figma _Graph Base style variants. |
+| `showLegend?` | `boolean` | true | When false, no legend row is rendered. |
+| `legendPosition?` | `'bottom-center' \| 'bottom-left' \| 'bottom-right' \| 'top-center' \| 'top-left' \| 'top-right'` | 'bottom-center' | Where to place the legend (horizontal line swatch + label per series). |
+| `showYAxis?` | `boolean` | true | When false, the Y-axis labels are hidden. |
+| `showXAxis?` | `boolean` | true | When false, the X-axis labels are hidden. |
+| `showGridLines?` | `boolean` | true | When false, horizontal grid lines are hidden. |
+| `showHoverIndicator?` | `boolean` | true | When false, hover crosshair, dots, and tooltip are disabled. |
+| `showAreaFill?` | `boolean` | true | When false, hides area/gradient fills under the line (Insight, Forecast regions). Lines remain visible. Useful for compact sparkline-style previews. |
+| `series1Color?` | `string` | 'var(--ds-color-chart-series-1)' | Stroke/fill color for series 1. SVG `stroke` is set inline — parent CSS cannot override. |
+| `series2Color?` | `string` | 'var(--ds-color-chart-series-2)' | Stroke color for series 2 (Comparison). Drawn before series 1 in the SVG. |
+| `series1?` | `number[]` | — | Primary line values — required by `type="Insight"`, `"Comparison"` (drawn in `series1Color`) and `"Score"`. Length should match the X-axis preset (e.g. 7 for `'7 Week Days'`). |
+| `series2?` | `number[]` | — | Secondary line values for `type="Comparison"` (drawn in `series2Color`). |
+| `goal?` | `number` | — | Goal reference value for `type="Score"`. Rendered as a dashed horizontal line. |
+| `past?` | `number[]` | — | Historic portion of the series for `type="Forecast"` — drawn solid (required for that type). The last value also anchors the start of `future` (one-point overlap). |
+| `future?` | `number[]` | — | Projected portion for `type="Forecast"` — drawn dashed. First value should equal the last value of `past` so the two segments meet. |
+| `splitIndex?` | `number` | — | Index in the full timeline where `past` ends and `future` begins. Defaults to `past.length - 1`. |
+| `series1Label?` | `string` | labels.seriesName(0) — 'Series 1' | Name of the line drawn in `series1Color` (legend + data table). Applies to Insight, Comparison, Score, and Forecast. |
+| `series2Label?` | `string` | labels.seriesName(1) — 'Series 2' | Name of the second line (Comparison only). |
+| `goalLabel?` | `string` | labels.goal — 'Goal' | Name of the goal line (Score only). |
+| `forecastLabel?` | `string` | labels.forecast — 'Forecast' | Name of the projection (Forecast only). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'Insight'` \| `'Comparison'` \| `'Score'` \| `'Forecast'` — Chart variant.
+- Insight     — single line with a highlighted data point
+- Comparison  — two series lines for comparing datasets
+- Score       — single line with a goal reference line
+- Forecast    — solid past line + dashed future projection
+- `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.
+- `graphStyle`: `'noisy'` \| `'smooth'` \| `'elastic'` — Controls line interpolation style — matches Figma _Graph Base style variants.
+- noisy   → straight line segments (angular, thorny)
+- smooth  → gentle Catmull-Rom curves
+- elastic → more pronounced, bouncy curves
+- `legendPosition`: `'bottom-center'` \| `'bottom-left'` \| `'bottom-right'` \| `'top-center'` \| `'top-left'` \| `'top-right'` — Legend row placement relative to the chart.
+- `bottom-*` — below the X-axis (default).
+- `top-*` — below the optional title, above the plot.
+
+## 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-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-chart-series-3)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add line-chart` (after `npx sdaia-ui@latest init`), then import `{ LineChart }` from `@/components/ui/LineChart`.
+- 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/list.md

@@ -0,0 +1,91 @@
+# List
+
+## Metadata
+- Component: List
+- Slug: `list`
+- Category: General
+- Install: `npx sdaia-ui@latest add list`
+- Import: `import { List } from '@/components/ui/List'`
+- Installed files: `List.tsx`, `List.types.ts`, `List.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/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 list`. It copies the source into your components folder (`components/ui/List/`, under `src/` when the project has one); import it as `@/components/ui/List`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Description
+A single list row. Every content slot renders only when its content prop is
+provided — the boolean toggles (`textLead`, `tag`, `button`, …) only decide
+whether provided content is shown; nothing is rendered as sample copy.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'small' \| 'medium' \| 'large'` | "small" | Figma variant: row size. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `textLead?` | `boolean` | true | Figma toggle: show primary text (`leadText`) in the lead section. |
+| `descriptionLead?` | `boolean` | false | Figma toggle: show description text (`leadDescriptionText`) in the lead section. |
+| `secondTextLead?` | `boolean` | false | Figma toggle: show second text (`leadSecondText`) in the lead section. |
+| `textTrailing?` | `boolean` | true | Figma toggle: show primary trailing text (`trailingText`). |
+| `descriptionTrailing?` | `boolean` | false | Figma toggle: show trailing description text (`trailingDescriptionText`). |
+| `secondTextTrailing?` | `boolean` | false | Figma toggle: show second trailing text (`trailingSecondText`). |
+| `leadingIcon?` | `boolean` | true | Figma toggle: show the leading icon (`iconNode`). |
+| `checkbox?` | `boolean` | false | Figma toggle: show checkbox. |
+| `avatar?` | `boolean` | false | Figma toggle: show the avatar (`avatarNode`). |
+| `trailingIcon?` | `boolean` | true | Figma toggle: show the trailing icon (`iconNode`). |
+| `tag?` | `boolean` | false | Figma toggle: show the trailing tag (`tagLabel`). |
+| `button?` | `boolean` | false | Figma toggle: show the trailing button (`buttonLabel`). |
+| `iconNode?` | `ReactNode` | — | Icon for the leading / trailing icon slots. Those slots render only when it is provided. |
+| `avatarNode?` | `ReactNode` | — | Avatar content (e.g. an `<Avatar>`). The avatar slot renders only when it is provided. |
+| `tagLabel?` | `ReactNode` | — | Tag label. The tag renders only when it is provided. |
+| `buttonLabel?` | `ReactNode` | — | Button label. The button renders only when it is provided. |
+| `leadText?` | `ReactNode` | — | Lead main text. |
+| `leadSecondText?` | `ReactNode` | — | Lead second text. |
+| `leadDescriptionText?` | `ReactNode` | — | Lead description. |
+| `trailingText?` | `ReactNode` | — | Trailing main text. |
+| `trailingSecondText?` | `ReactNode` | — | Trailing second text. |
+| `trailingDescriptionText?` | `ReactNode` | — | Trailing description. |
+| `divider?` | `boolean` | false | Figma toggle: show divider line at bottom. |
+| `background?` | `boolean` | false | Figma toggle: show the default surface background. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`.
+
+## Options (allowed values)
+- `size`: `'small'` \| `'medium'` \| `'large'` — Visual size from the Figma component variants.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+- `seondTextTrailing`
+
+## 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-low)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-3xl)`
+- `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 list` (after `npx sdaia-ui@latest init`), then import `{ List }` from `@/components/ui/List`.
+- 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/media-gallery.md

@@ -0,0 +1,85 @@
+# Media Gallery
+
+## Metadata
+- Component: Media Gallery
+- Slug: `media-gallery`
+- Category: General
+- Install: `npx sdaia-ui@latest add media-gallery`
+- Import: `import { MediaGallery } from '@/components/ui/MediaGallery'`
+- Installed files: `MediaGallery.tsx`, `MediaGallery.types.ts`, `MediaGallery.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/media-gallery
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add media-gallery`. It copies the source into your components folder (`components/ui/MediaGallery/`, under `src/` when the project has one); import it as `@/components/ui/MediaGallery`. 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 |
+| --- | --- | --- | --- |
+| `toolbar?` | `boolean` | true | Show the toolbar (search + view toggle + action buttons). Default: true |
+| `searchValue?` | `string` | — | Controlled value for the search input. |
+| `onSearchChange?` | `(value: string) => void` | — | Called when the search input value changes. |
+| `activeView?` | `'list' \| 'grid'` | — | Currently active view mode. Controls which view-toggle button appears selected. Default: 'grid' |
+| `onViewChange?` | `(view: MediaGalleryView) => void` | — | Called when the user clicks a view-toggle button. |
+| `onFilterClick?` | `() => void` | — | Called when the filter button is clicked. Visible on both desktop and mobile/tablet toolbars. |
+| `onDeleteClick?` | `(selectedImages: MediaGalleryImage[]) => void` | — | Called when the delete/trash button is clicked. Receives the images that are selected at the time of the click. Desktop toolbar only. |
+| `onExportClick?` | `(selectedImages: MediaGalleryImage[]) => void` | — | Called when the Export button is clicked. Receives the images that are selected at the time of the click. Desktop toolbar only. |
+| `onAddClick?` | `() => void` | — | Called when the Add button is clicked. Desktop toolbar only. |
+| `onMoreClick?` | `() => void` | — | Called when the mobile/tablet "more" (…) button is clicked. Mobile/tablet toolbar only. |
+| `images?` | `MediaGalleryImage[]` | [] | Array of image items to render in the gallery grid. Responsive grid columns: 2 (mobile) → 3 (tablet) → 5 (desktop). Image size scales accordingly: sm → md → lg. |
+| `pagination?` | `boolean` | true | Show the pagination section. Default: true |
+| `currentPage?` | `number` | 1 | Current page number (1-indexed). Default: 1 |
+| `totalPages?` | `number` | 1 | Total number of pages. Default: 1 |
+| `onPageChange?` | `(page: number) => void` | — | Called when the user navigates to a different page. |
+| `labels?` | `Partial<MediaGalleryLabels>` | — | Translatable built-in text. Unset keys use the English defaults. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — set to 'rtl' for Arabic/Hebrew. Inherits from the page when omitted. Applied to the root element and forwarded to Pagination. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `activeView`: `'list'` \| `'grid'` — View mode for the image grid.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — set to 'rtl' for Arabic/Hebrew. Inherits from the page
+when omitted. Applied to the root element and forwarded to Pagination.
+
+## Deprecated props
+Do not use in new code:
+- `searchPlaceholder` — Placeholder text for the search input.
+- `emptySearchLabel` — Message shown when the search query matches no images.
+- `exportLabel` — Label for the Export button.
+- `addLabel` — Label for the Add button.
+
+## 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-low)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-strong)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-none)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add media-gallery` (after `npx sdaia-ui@latest init`), then import `{ MediaGallery }` from `@/components/ui/MediaGallery`.
+- 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.