@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/feedback/notifications.md

@@ -0,0 +1,158 @@
+# Notifications
+
+## Metadata
+- Component: Notifications
+- Slug: `notifications`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add notifications`
+- Import: `import { Notifications } from '@/components/ui/Notifications'`
+- Installed files: `Notifications.tsx`, `Notifications.types.ts`, `Notifications.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/notifications
+
+> **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 notifications`. It copies the source into your components folder (`components/ui/Notifications/`, under `src/` when the project has one); import it as `@/components/ui/Notifications`. 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` | 'Notifications' | Panel heading. Defaults to "Notifications". |
+| `tabs?` | `HorizontalTabItem[]` | — | Tab definitions rendered in the sub-header. Defaults to `[{ value: 'all', label: 'All' }, { value: 'direct', label: 'Direct' }]`. Uses the `HorizontalTabItem` type so consumers can add icons / counts. |
+| `activeTab?` | `string` | — | Controlled active tab value. Defaults to the first tab's value. |
+| `onTabChange?` | `(value: string) => void` | — | Fired when the user switches tabs. |
+| `onMarkAllRead?` | `() => void` | — | "Mark all as Read" action callback. |
+| `onClose?` | `() => void` | — | Fired when the user presses the × close button. |
+| `groups?` | `NotificationGroup[]` | [] | Notification groups to render for every tab (or when no tab-specific override is provided). Each group is a `{ label: string, items: ActivityItemProps[] }` object. |
+| `groupsByTab?` | `Record<string, NotificationGroup[]>` | — | Per-tab group overrides. Keys must match the `value` of a tab item. When the active tab has an entry here its groups are shown instead of `groups`.  Tabs with no entry fall back to `groups`. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `labels?` | `Partial<NotificationsLabels>` | — | Override built-in strings (English defaults) to localize the panel. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. Applied to the root, so tabs, activity items and rows all mirror with it. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the notifications panel.
+  - `'solid'` (default) — opaque white card with a hairline border.
+  - `'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. Applied to the
+root, so tabs, activity items and rows all mirror with it.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Icons (`@platformscode/icons` + `DgaIcon`)
+
+Icons are **not** top-level props on `Notifications`. Pass them through nested tab items and use `sdaia-assets` for feed media. Requires `npx sdaia-ui@latest init` (installs `DgaIcon` + `@platformscode/icons`). Full setup: `setup_project` Step 8.
+
+```tsx
+import { Notifications } from '@/components/ui/Notifications';
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { notification01Stroke, mail01Stroke } from '@platformscode/icons';
+```
+
+### Built-in close control
+
+When `onClose` is set, the panel renders an icon-only close `Button` using `cancel01Stroke` from `@platformscode/icons` (wired inside the installed component). You do not pass this icon unless you replace the whole close affordance yourself.
+
+### Tab icons + counts (`tabs` → `HorizontalTabItem`)
+
+`Notifications` renders tabs with `HorizontalTabs` → `Tab` at **default size `md`**. The `Tab` component sizes slots for you:
+
+| Slot | How `Tab` sizes it | What to pass |
+| --- | --- | --- |
+| `leadingIcon` | Wraps your node in a **`size-icon-sm` (16px)** container | `<DgaIcon data={…} />` only — **no** `className="size-icon-*"` on `DgaIcon` (avoids double sizing / icons looking too small) |
+| `count` | Applies built-in **18px** count pill (`Tab` `COUNT` styles) | A **number or short string** — e.g. `count: 8` or `count: '99+'` |
+
+**Do not** put `<Badge />` in `count`. A `Badge` (`sm` = 22px, `md` = 24px) stacks inside the tab count shell and looks **oversized** next to the 16px tab icon. Use the native count bubble instead.
+
+| Tab intent | Suggested `@platformscode/icons` token |
+| --- | --- |
+| All / inbox | `notification01Stroke` |
+| Direct / messages | `mail01Stroke` |
+| Search / filtered view | `search01Stroke` |
+
+```tsx
+tabs={[
+  {
+    value: 'all',
+    label: 'All',
+    leadingIcon: <DgaIcon data={notification01Stroke} />,
+    count: 8,
+  },
+  {
+    value: 'direct',
+    label: 'Direct',
+    leadingIcon: <DgaIcon data={mail01Stroke} />,
+    count: 2,
+  },
+]}
+```
+
+> **Wrong (icon tiny + count huge):** `leadingIcon={<DgaIcon className="size-icon-xs" … />}` and `count={<Badge size="md">8</Badge>}`.
+
+### Feed rows (`groups` / `groupsByTab` → `ActivityItemProps`)
+
+Each `items[]` entry is passed to `ActivityItem`. There is **no** `icon` prop on feed rows — use `type` and media fields instead:
+
+| `type` | Content | Icons / assets |
+| --- | --- | --- |
+| `'text'` (default) | `title`, `subtext`, `helperText` | `avatarSrc` / `avatarAlt` for the actor photo (defaults to `SaudiAvatar` from `sdaia-assets` when omitted) |
+| `'file'` | `fileName`, `fileSize` | Built-in file visuals from `sdaia-assets` (`PDFSvg`, `Image01SVG`) — not `@platformscode/icons` |
+| `'badge'` | `badges[]` with `label` + `color: 'blue' \| 'gold' \| 'lavender'` | Renders DS `<Badge size="md" pill soft />` inside the row — **not** a tab `count`; do not pass these for tab notification totals |
+| `'comment'` | `comment` bubble text | Avatar as above |
+| `'image'` | `imageSrc`, `imageAlt` | Photo URL, not an icon token |
+
+```tsx
+groups={[
+  {
+    label: 'Today',
+    items: [
+      {
+        type: 'text',
+        title: 'Sara Al-Rashid',
+        subtext: '12:00 PM',
+        helperText: 'Commented on your post.',
+        avatarSrc: '/avatars/sara.jpg',
+        unread: true,
+        primaryAction: { label: 'Reply', onClick: () => {} },
+      },
+    ],
+  },
+]}
+```
+
+For deeper `ActivityItem` API details, install `npx sdaia-ui@latest add activity` and call `get_component_docs` with `activity`.
+
+## 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-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add notifications` (after `npx sdaia-ui@latest init`), then import `{ Notifications }` from `@/components/ui/Notifications`.
+- 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".
+- Tab `leadingIcon`: `<DgaIcon data={…} />` from `@platformscode/icons` (e.g. `notification01Stroke`, `mail01Stroke`) — **no** extra `size-icon-*` on `DgaIcon`; `Tab` applies `size-icon-sm`. Tab `count`: plain number/string only — **never** `<Badge />` in `count` (see **Icons**).
+- Feed rows use `ActivityItemProps` (`type`, `avatarSrc`, …), not a generic `icon` prop — use `sdaia-assets` for default avatars / file glyphs.
+- Provide `onClose` when the panel should show the built-in close control (`cancel01Stroke` inside the component).
+- 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/feedback/progress-bar.md

@@ -0,0 +1,69 @@
+# Progress Bar
+
+## Metadata
+- Component: Progress Bar
+- Slug: `progress-bar`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add progress-bar`
+- Import: `import { ProgressBar } from '@/components/ui/ProgressBar'`
+- Installed files: `ProgressBar.tsx`, `ProgressBar.types.ts`, `ProgressBar.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/progressbar
+
+> **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-bar`. It copies the source into your components folder (`components/ui/ProgressBar/`, under `src/` when the project has one); import it as `@/components/ui/ProgressBar`. 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
+The root is a `role="progressbar"`, which needs an accessible name: pass
+`aria-label` (translated) or `aria-labelledby` pointing at the visible
+heading or file name it reports on. `label` only controls the layout of
+the percentage text.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `progress?` | `number` | 0 | Current progress value (0–100) |
+| `label?` | `'none' \| 'inline' \| 'bottom' \| 'top-floating' \| 'bottom-floating'` | 'none' | Label layout variant |
+| `leadingIcon?` | `boolean` | false | Show leading icon |
+| `trailingIcon?` | `boolean` | false | Show trailing icon |
+| `valueMin?` | `boolean` | false | Show min value (0%) |
+| `valueMax?` | `boolean` | false | Show max value (100%) |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `animateOnView?` | `boolean` | false | Animate fill from 0 when entering the viewport |
+| `labels?` | `Partial<ProgressBarLabels>` | — | Override built-in strings (English defaults) to localize the progress bar. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `label`: `'none'` \| `'inline'` \| `'bottom'` \| `'top-floating'` \| `'bottom-floating'` — Label layout variant
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Accessibility
+Built in (SDAIA review item A7) — verified by `axe scan (aria-progressbar-name) — audit-reports/a11y` in the design system's test suite:
+- The root is a `role="progressbar"` with its current value.
+
+You must:
+- Name it: pass `aria-label` (translated) or `aria-labelledby` pointing at visible text. The `label` prop only sets where the percentage is shown.
+
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add progress-bar` (after `npx sdaia-ui@latest init`), then import `{ ProgressBar }` from `@/components/ui/ProgressBar`.
+- 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/feedback/rating-overview.md

@@ -0,0 +1,58 @@
+# Rating Overview
+
+## Metadata
+- Component: Rating Overview
+- Slug: `rating-overview`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add rating-overview`
+- Import: `import { RatingOverview } from '@/components/ui/RatingOverview'`
+- Installed files: `RatingOverview.tsx`, `RatingOverview.types.ts`, `RatingOverview.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/rating-overview
+
+> **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 rating-overview`. It copies the source into your components folder (`components/ui/RatingOverview/`, under `src/` when the project has one); import it as `@/components/ui/RatingOverview`. 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` | — | Average rating value (supports half steps). Unset renders the empty state: empty stars and no score. |
+| `max?` | `number` | 5 | Scale maximum (number of stars). |
+| `label?` | `ReactNode` | — | Section label (e.g. "Ratings"). |
+| `labelPlacement?` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'start' \| 'end'` | 'top-left' | Where the label sits relative to the stars when not stacked. |
+| `stacked?` | `boolean` | false | Vertical stacked layout (score + stars + helper). |
+| `showHelperText?` | `boolean` | true | Show the helper line under the stars (e.g. total count). |
+| `helperText?` | `string` | — | Helper line below the stars (e.g. total count). Fully customizable string. |
+| `starStyle?` | `RatingStarStyle` | 'solid' | Star visual style passed to `RatingStar`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction for layout and the star half-fill. Unset inherits from the document. |
+| `starSize?` | `number` | 24 | Pixel size for each `RatingStar`. |
+| `labels?` | `Partial<RatingOverviewLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `labelPlacement`: `'top-left'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-right'` \| `'start'` \| `'end'` — Label position relative to the star row when `stacked` is false.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction for layout and the star half-fill. Unset inherits from the document.
+
+## Deprecated props
+Do not use in new code:
+- `direction`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add rating-overview` (after `npx sdaia-ui@latest init`), then import `{ RatingOverview }` from `@/components/ui/RatingOverview`.
+- 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/feedback/rating.md

@@ -0,0 +1,64 @@
+# Rating
+
+## Metadata
+- Component: Rating
+- Slug: `rating`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add rating`
+- Import: `import { Rating } from '@/components/ui/Rating'`
+- Installed files: `Rating.tsx`, `Rating.types.ts`, `Rating.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/rating
+
+> **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 rating`. It copies the source into your components folder (`components/ui/Rating/`, under `src/` when the project has one); import it as `@/components/ui/Rating`. 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` | — | Current value for controlled mode. |
+| `defaultValue?` | `number` | 0 | Initial value for uncontrolled mode. |
+| `max?` | `number` | 5 | Maximum number of stars. |
+| `size?` | `'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | 'md' | Rating size preset. |
+| `style?` | `'solid' \| 'outline'` | 'solid' | Visual style of stars. |
+| `brand?` | `boolean` | true | Fill colour: `true` uses the brand colour (`--ds-color-bg-brand`), `false` the rating orange (`--ds-color-rating-star-filled`). |
+| `step?` | `RatingStep` | 0.5 | Step granularity; default is half star. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Half stars fill from the inline start and the arrow keys follow the reading direction. Unset inherits from the document. |
+| `disabled?` | `boolean` | false | Disables all interactions. |
+| `readOnly?` | `boolean` | false | Prevents update while keeping focus semantics. |
+| `hoverable?` | `boolean` | true | Hover-to-preview behavior. |
+| `starColor?` | `string` | — | Custom active star color (applies to selected and hover preview). |
+| `emptyStarColor?` | `string` | — | Custom empty star color. |
+| `onValueChange?` | `(value: number) => void` | — | Callback when value changes. |
+| `labels?` | `Partial<RatingLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `style`, `dir`.
+
+## Options (allowed values)
+- `size`: `'2xs'` \| `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` \| `'2xl'` — Rating size preset.
+- `style`: `'solid'` \| `'outline'` — Visual style of stars.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Half stars fill from the inline start and the arrow keys follow the
+reading direction. Unset inherits from the document.
+
+## Deprecated props
+Do not use in new code:
+- `direction`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-brand)`
+- `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 rating` (after `npx sdaia-ui@latest init`), then import `{ Rating }` from `@/components/ui/Rating`.
+- 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/feedback/skeleton-avatar.md

@@ -0,0 +1,48 @@
+# Skeleton/Avatars
+
+## Metadata
+- Component: Skeleton/Avatars
+- Slug: `skeleton-avatar`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add skeleton-avatar`
+- Import: `import { SkeletonAvatar } from '@/components/ui/SkeletonAvatar'`
+- Installed files: `SkeletonAvatar.tsx`, `SkeletonAvatar.types.ts`, `SkeletonAvatar.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/skeleton-avatars
+
+> **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 skeleton-avatar`. It copies the source into your components folder (`components/ui/SkeletonAvatar/`, under `src/` when the project has one); import it as `@/components/ui/SkeletonAvatar`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'S' \| 'M' \| 'L'` | 'sm' | Avatar placeholder size. Matches the Figma sizes: - sm: 24px - S: 32px - M: 48px - L: 64px |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'S'` \| `'M'` \| `'L'` — Avatar placeholder size.
+Matches the Figma sizes:
+- sm: 24px
+- S: 32px
+- M: 48px
+- L: 64px
+- `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-alpha-white-40)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-motion-loop-duration)`
+- `var(--ds-motion-loop-easing)`
+- `var(--ds-radius-full)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add skeleton-avatar` (after `npx sdaia-ui@latest init`), then import `{ SkeletonAvatar }` from `@/components/ui/SkeletonAvatar`.
+- 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/feedback/skeleton.md

@@ -0,0 +1,53 @@
+# Skeleton
+
+## Metadata
+- Component: Skeleton
+- Slug: `skeleton`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add skeleton`
+- Import: `import { Skeleton } from '@/components/ui/Skeleton'`
+- Installed files: `Skeleton.tsx`, `Skeleton.types.ts`, `Skeleton.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/skeleton
+
+> **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 skeleton`. It copies the source into your components folder (`components/ui/Skeleton/`, under `src/` when the project has one); import it as `@/components/ui/Skeleton`. 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?` | `'text-sm' \| 'text-md' \| 'text-lg' \| 'text-xl'` | 'text-xl' | Visual size preset for text/block placeholders. Matches the Figma text skeleton scale: - text-sm: 16px line (short) - text-md: 16px line (full) - text-lg: 32px block - text-xl: 92px block Widths are fluid: the skeleton fills its container up to the Figma width (298.664px for text-sm, 336px otherwise). Inside a shrink-to-fit parent (a non-growing flex item, `w-fit`, `inline-flex`) give the parent a width or `flex-1`, or pass a `w-*` class. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `size`: `'text-sm'` \| `'text-md'` \| `'text-lg'` \| `'text-xl'` — Visual size preset for text/block placeholders.
+Matches the Figma text skeleton scale:
+- text-sm: 16px line (short)
+- text-md: 16px line (full)
+- text-lg: 32px block
+- text-xl: 92px block
+
+Widths are fluid: the skeleton fills its container up to the Figma width
+(298.664px for text-sm, 336px otherwise). Inside a shrink-to-fit parent
+(a non-growing flex item, `w-fit`, `inline-flex`) give the parent a width
+or `flex-1`, or pass a `w-*` class.
+- `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-alpha-white-40)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-motion-loop-duration)`
+- `var(--ds-motion-loop-easing)`
+- `var(--ds-radius-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add skeleton` (after `npx sdaia-ui@latest init`), then import `{ Skeleton }` from `@/components/ui/Skeleton`.
+- 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/feedback/toast.md

@@ -0,0 +1,74 @@
+# Toast
+
+## Metadata
+- Component: Toast
+- Slug: `toast`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add toast`
+- Import: `import { Toast } from '@/components/ui/Toast'`
+- Installed files: `Toast.tsx`, `Toast.types.ts`, `Toast.variants.ts`, `ToastProvider.tsx`, `index.ts`
+- Docs: https://ds.nacew.com/components/toast
+
+> **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 toast`. It copies the source into your components folder (`components/ui/Toast/`, under `src/` when the project has one); import it as `@/components/ui/Toast`. 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?` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | 'neutral' | Outcome of the action the toast reports (Figma `Type`). Sets the featured icon and its colour, and the live-region politeness: `error` is announced with `role="alert"` (assertive), every other type with `role="status"` (polite). |
+| `title` | `ReactNode` | — | Short title — one line that says what happened (Figma `Title`). |
+| `message?` | `ReactNode` | — | Optional supporting sentence under the title (Figma `Message`). |
+| `actionLabel?` | `ReactNode` | — | Label of the single action link, e.g. "Undo" (Figma `Action`). The action renders only when this is set together with `onAction` or `actionHref`. |
+| `onAction?` | `(event: MouseEvent<HTMLElement>) => void` | — | Called when the action is activated. The toast then asks to close with reason `'action'`, unless the handler calls `event.preventDefault()`. |
+| `actionHref?` | `string` | — | Renders the action as a real link to this URL instead of a button. |
+| `closeButton?` | `boolean` | true | Shows the close (×) button (Figma `Close Button`). |
+| `onClose?` | `(reason: ToastCloseReason) => void` | — | Called when the toast asks to close: the timer ran out, the close button or the action was used, or Escape was pressed while focus was inside it. Toast is controlled — remove it here (or let `ToastProvider` do it). |
+| `duration?` | `number \| null` | MIN_DURATION_MS | Milliseconds before the toast closes itself. Values under 5000 are raised to 5000 (WCAG 2.2.1, Figma accessibility notes). `null` keeps the toast until the user closes it. The timer pauses while the toast is hovered or holds focus, and while the page is hidden. Ignored for `type="error"`: error toasts never close themselves. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the toast. Inherits from the document when omitted. |
+| `labels?` | `Partial<ToastLabels>` | — | Override built-in strings (English defaults). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `children`, `dir`.
+
+## Options (allowed values)
+- `type`: `'neutral'` \| `'info'` \| `'success'` \| `'warning'` \| `'error'` — Figma `Type` — the outcome the toast reports. A variation of the design
+(icon + colour), not an interaction condition.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the toast. Inherits from the document when omitted.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-spacing-space-1)`
+- `var(--ds-brand-spacing-space-2)`
+- `var(--ds-brand-spacing-space-3)`
+- `var(--ds-brand-spacing-space-4)`
+- `var(--ds-brand-spacing-space-N)`
+- `var(--ds-color-bg-danger-muted)`
+- `var(--ds-color-bg-info-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-success-muted)`
+- `var(--ds-color-bg-warning-muted)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add toast` (after `npx sdaia-ui@latest init`), then import `{ Toast }` from `@/components/ui/Toast`.
+- 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/feedback/tooltip.md

@@ -0,0 +1,72 @@
+# Tooltip
+
+## Metadata
+- Component: Tooltip
+- Slug: `tooltip`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add tooltip`
+- Import: `import { Tooltip } from '@/components/ui/Tooltip'`
+- Installed files: `Tooltip.tsx`, `Tooltip.types.ts`, `Tooltip.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tooltip
+
+> **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 tooltip`. It copies the source into your components folder (`components/ui/Tooltip/`, under `src/` when the project has one); import it as `@/components/ui/Tooltip`. 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?` | `'neutral' \| 'brand'` | 'neutral' | Visual type — neutral (white/dark bg) or brand (green bg). |
+| `beakPlacement?` | `'none' \| 'top' \| 'bottom' \| 'left' \| 'right'` | 'none' | Beak (arrow) placement relative to the tooltip body. `left` / `right` are physical sides (they do not mirror in RTL), matching the Figma RTL frames. |
+| `beakAlignment?` | `'start' \| 'centre' \| 'end'` | 'start' | Beak alignment along the placed edge. Only applies when beakPlacement is not 'none'. |
+| `title?` | `ReactNode` | — | Title text displayed at the top. Also names the tooltip when it renders as a dialog. |
+| `description?` | `ReactNode` | — | Description text below the title. |
+| `icon?` | `ReactNode \| boolean` | — | Leading icon. Pass `true` for the default info icon, or a custom ReactNode. |
+| `media?` | `ReactNode` | — | Media content (image, video) displayed between text and footer. |
+| `primaryAction?` | `TooltipAction` | — | Primary action button (e.g. "Next"). A tooltip must not contain focusable content, so when any action or link is present the bubble renders as a non-modal `role="dialog"` (a rich tooltip / coach mark) named by its `title` instead of `role="tooltip"`. |
+| `secondaryAction?` | `TooltipAction` | — | Secondary action button (e.g. "Skip"). See `primaryAction` for the role change. |
+| `link?` | `TooltipLinkAction` | — | Link action displayed after the buttons. See `primaryAction` for the role change. |
+| `counting?` | `ReactNode` | — | Counting/pagination text (e.g. "1 of 7"). |
+| `children?` | `ReactNode` | — | Extra content rendered after the media slot. Keep it non-interactive for a plain tooltip (no buttons, links or inputs). |
+| `trigger?` | `ReactElement` | — | Element the tooltip describes (e.g. an icon-only `Button`). When provided the tooltip is hidden until the trigger is hovered or receives keyboard focus; it stays open while the pointer is over the trigger or the tooltip, hides on blur / mouse leave, and Escape hides it without moving focus. While shown, the trigger gets `aria-describedby` pointing to the tooltip. The bubble is placed opposite its beak (beak `top` → below the trigger). When omitted, the tooltip renders statically (always visible), e.g. for onboarding steps or documentation. |
+| `open?` | `boolean` | — | Controlled visibility in trigger mode. |
+| `defaultOpen?` | `boolean` | false | Initial visibility in trigger mode (uncontrolled). |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the visibility changes in trigger mode (hover, focus, blur, Escape). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `type`: `'neutral'` \| `'brand'` — Visual type — neutral (white/dark bg) or brand (green bg).
+- `beakPlacement`: `'none'` \| `'top'` \| `'bottom'` \| `'left'` \| `'right'` — Beak (arrow) placement relative to the tooltip body. `left` / `right` are
+physical sides (they do not mirror in RTL), matching the Figma RTL frames.
+- `beakAlignment`: `'start'` \| `'centre'` \| `'end'` — Beak alignment along the placed edge. Only applies when beakPlacement is not 'none'.
+- `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-brand)`
+- `var(--ds-color-button-bg-black-)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-button-bg-black-hovered)`
+- `var(--ds-color-button-bg-black-pressed)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-tooltip-bg-on-dark)`
+- `var(--ds-color-tooltip-text-heading-on-dark)`
+- `var(--ds-color-tooltip-text-paragraph-on-dark)`
+- `var(--ds-radius-m)`
+- `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 tooltip` (after `npx sdaia-ui@latest init`), then import `{ Tooltip }` from `@/components/ui/Tooltip`.
+- 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.