@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/feedback/badge.md

@@ -0,0 +1,86 @@
+# Badge
+
+## Metadata
+- Component: Badge
+- Slug: `badge`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add badge`
+- Import: `import { Badge } from '@/components/ui/Badge'`
+- Installed files: `Badge.tsx`, `Badge.types.ts`, `Badge.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/badge
+
+> **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 badge`. It copies the source into your components folder (`components/ui/Badge/`, under `src/` when the project has one); import it as `@/components/ui/Badge`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `ReactNode` | — | Label text |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the badge |
+| `variant?` | `'soft' \| 'solid'` | 'soft' | Visual style |
+| `color?` | `'neutral' \| 'primary' \| 'secondary' \| 'tertiary' \| 'info' \| 'warning' \| 'error'` | 'neutral' | Color scheme |
+| `pill?` | `boolean` | false | Pill shape (rounded-full) |
+| `iconOnly?` | `boolean` | false | Icon-only mode (no text) |
+| `leadingIcon?` | `ReactNode` | — | Leading icon element |
+| `trailingIcon?` | `ReactNode` | — | Trailing icon element |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the badge
+- `variant`: `'soft'` \| `'solid'` — Visual style
+- `color`: `'neutral'` \| `'primary'` \| `'secondary'` \| `'tertiary'` \| `'info'` \| `'warning'` \| `'error'` — Color scheme
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Accessibility
+- Icon-only usage must include an accessible label (`aria-label`).
+- 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-danger-strong)`
+- `var(--ds-color-bg-danger-subtle)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-bg-info-strong)`
+- `var(--ds-color-bg-info-subtle)`
+- `var(--ds-color-bg-success-strong)`
+- `var(--ds-color-bg-success-subtle)`
+- `var(--ds-color-bg-warning-strong)`
+- `var(--ds-color-bg-warning-subtle)`
+- `var(--ds-color-border-danger-strong)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-border-info-strong)`
+- `var(--ds-color-border-success-strong)`
+- `var(--ds-color-border-warning-strong)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-info)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-success)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-themes-badge-)`
+- `var(--ds-themes-badge-badge-background-brand-tertiary-soft)`
+- `var(--ds-themes-badge-badge-background-brand-tertiary-solid)`
+- `var(--ds-themes-badge-badge-background-gold-soft)`
+- `var(--ds-themes-badge-badge-background-gold-solid)`
+- `var(--ds-themes-badge-badge-border-brand-tertiary-soft)`
+- `var(--ds-themes-badge-badge-border-gold-soft)`
+- `var(--ds-themes-text-)`
+- `var(--ds-themes-text-text-brand-tertiary)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add badge` (after `npx sdaia-ui@latest init`), then import `{ Badge }` from `@/components/ui/Badge`.
+- 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/card.md

@@ -0,0 +1,54 @@
+# Card
+
+## Metadata
+- Component: Card
+- Slug: `card`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add card`
+- Import: `import { Card } from '@/components/ui/Card'`
+- Installed files: `Card.tsx`, `Card.types.ts`, `Card.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/card
+
+> **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 card`. It copies the source into your components folder (`components/ui/Card/`, under `src/` when the project has one); import it as `@/components/ui/Card`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `ReactNode` | — | Render children inside the card surface (radius, padding, bg). |
+| `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. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the card.
+  - `'solid'` (default) — opaque raised background.
+  - `'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.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `direction`
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-raised)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add card` (after `npx sdaia-ui@latest init`), then import `{ Card }` from `@/components/ui/Card`.
+- 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/feedback-overview.md

@@ -0,0 +1,37 @@
+# Feedback Overview
+
+## Metadata
+- Component: Feedback Overview
+- Slug: `feedback-overview`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add feedback-overview`
+- Import: `import { FeedbackOverview } from '@/components/ui/FeedbackOverview'`
+- Installed files: `FeedbackOverview.tsx`, `FeedbackOverview.types.ts`, `FeedbackOverview.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/feedback-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 feedback-overview`. It copies the source into your components folder (`components/ui/FeedbackOverview/`, under `src/` when the project has one); import it as `@/components/ui/FeedbackOverview`. 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 |
+| --- | --- | --- | --- |
+| `label?` | `ReactNode` | — | The label shown alongside the reaction buttons. |
+| `labelPlacement?` | `'top' \| 'inline' \| 'bottom'` | 'top' | Where the label is placed relative to the reactions. |
+
+## Options (allowed values)
+- `labelPlacement`: `'top'` \| `'inline'` \| `'bottom'` — Where the label is placed relative to the reactions.
+
+## 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-text-paragraph)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add feedback-overview` (after `npx sdaia-ui@latest init`), then import `{ FeedbackOverview }` from `@/components/ui/FeedbackOverview`.
+- 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/feedback.md

@@ -0,0 +1,46 @@
+# Feedback
+
+## Metadata
+- Component: Feedback
+- Slug: `feedback`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add feedback`
+- Import: `import { Feedback } from '@/components/ui/Feedback'`
+- Installed files: `Feedback.tsx`, `Feedback.types.ts`, `Feedback.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/feedback
+
+> **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 feedback`. It copies the source into your components folder (`components/ui/Feedback/`, under `src/` when the project has one); import it as `@/components/ui/Feedback`. 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?` | `FeedbackType` | 'thumb' | Glyph family — `thumb` (like / dislike) or `emoji` (dislike / neutral / like). |
+| `size?` | `FeedbackSize` | 'md' | — |
+| `value?` | `FeedbackValue \| null` | — | Controlled value. Pass `null` to deselect. |
+| `defaultValue?` | `FeedbackValue \| null` | null | Initial value when uncontrolled. |
+| `onValueChange?` | `(value: FeedbackValue \| null) => void` | — | Fired with the new value (`null` when the active reaction is pressed again). |
+| `disabled?` | `boolean` | false | Disables every reaction button. |
+| `labels?` | `Partial<FeedbackLabels>` | — | Override built-in accessible names (English defaults) to localize the reactions. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. 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-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add feedback` (after `npx sdaia-ui@latest init`), then import `{ Feedback }` from `@/components/ui/Feedback`.
+- 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/help-icon.md

@@ -0,0 +1,57 @@
+# Help Icon
+
+## Metadata
+- Component: Help Icon
+- Slug: `help-icon`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add help-icon`
+- Import: `import { HelpIcon } from '@/components/ui/HelpIcon'`
+- Installed files: `HelpIcon.tsx`, `HelpIcon.types.ts`, `HelpIcon.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/helpicon
+
+> **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 help-icon`. It copies the source into your components folder (`components/ui/HelpIcon/`, under `src/` when the project has one); import it as `@/components/ui/HelpIcon`. 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 |
+| --- | --- | --- | --- |
+| `placement?` | `'top' \| 'bottom' \| 'left' \| 'right'` | 'top' | Side on which the tooltip appears relative to the trigger icon. In RTL the left/right placements are mirrored automatically. |
+| `align?` | `'start' \| 'center' \| 'end'` | 'start' | Alignment of the beak (arrow) along the tooltip edge. For top/bottom placements this controls horizontal position; for left/right placements it controls vertical position. |
+| `open?` | `boolean` | — | Whether the tooltip is currently visible. When provided the component operates in controlled mode. When omitted the component is uncontrolled and shows on hover/focus. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Callback fired when the tooltip open state should change (hover / focus, leaving, or Escape). Use this together with `open` for controlled mode. |
+| `title?` | `ReactNode` | — | Title text displayed at the top of the tooltip. |
+| `description?` | `ReactNode` | — | Description / body text displayed below the title. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root and the tooltip, and used to mirror left/right placements. Unset inherits the page direction (read when the tooltip opens). |
+| `labels?` | `Partial<HelpIconLabels>` | — | Localised built-in strings (trigger button name). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `placement`: `'top'` \| `'bottom'` \| `'left'` \| `'right'` — Which side the tooltip appears on relative to the trigger icon.
+- `align`: `'start'` \| `'center'` \| `'end'` — Where the beak (arrow) sits along the tooltip edge.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root and the tooltip, and used to mirror
+left/right placements. Unset inherits the page direction (read when the tooltip opens).
+
+## Deprecated props
+Do not use in new code:
+- `rtl` — Pass `true` when the component is rendered inside a `dir="rtl"` context.
+
+## 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-color-icon-default)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-radius-full)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add help-icon` (after `npx sdaia-ui@latest init`), then import `{ HelpIcon }` from `@/components/ui/HelpIcon`.
+- 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/loading-indicator.md

@@ -0,0 +1,76 @@
+# Loading Indicator
+
+## Metadata
+- Component: Loading Indicator
+- Slug: `loading-indicator`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add loading-indicator`
+- Import: `import { LoadingIndicator } from '@/components/ui/LoadingIndicator'`
+- Installed files: `LoadingIndicator.tsx`, `LoadingIndicator.types.ts`, `LoadingIndicator.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/loading-indicator
+
+> **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 loading-indicator`. It copies the source into your components folder (`components/ui/LoadingIndicator/`, under `src/` when the project has one); import it as `@/components/ui/LoadingIndicator`. 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 |
+| --- | --- | --- | --- |
+| `indicatorStyle?` | `'arc' \| 'ring' \| 'radial'` | 'arc' | Visual geometry of the spinner (Figma "Style"). |
+| `color?` | `'neutral' \| 'primary'` | 'neutral' | Color theme for the graphic (Figma "Color"). |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | 'xs' | Size of the graphic and matching label typography. |
+| `showLabel?` | `boolean` | true | When true, shows supporting text below the graphic. |
+| `label?` | `ReactNode` | — | Supporting text for this instance (e.g. "Fetching data..."); keep it short because the status is announced to screen readers. Falls back to `labels.loading`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `labels?` | `Partial<LoadingIndicatorLabels>` | — | Override built-in strings (English defaults) to localize the indicator. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `color`.
+
+## Options (allowed values)
+- `indicatorStyle`: `'arc'` \| `'ring'` \| `'radial'` — Spinner geometry style.
+- `arc` → open arc without a track
+- `ring` → track + partial stroke
+- `radial` → Style "Radial Spinner" (spokes)
+- `color`: `'neutral'` \| `'primary'` — Accent palette. Maps to Figma `Color=Neutral` and `Color=Primary`.
+- `size`: `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` — Size scale. Maps to Figma `xSmall` … `xLarge`.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `supportingText`
+
+## 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-primary-100)`
+- `var(--ds-brand-primary-200)`
+- `var(--ds-brand-primary-25)`
+- `var(--ds-brand-primary-300)`
+- `var(--ds-brand-primary-50)`
+- `var(--ds-brand-primary-700)`
+- `var(--ds-brand-primary-800)`
+- `var(--ds-brand-primary-900)`
+- `var(--ds-brand-primary-950)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-emphasis-medium)`
+- `var(--ds-color-bg-emphasis-strong)`
+- `var(--ds-color-bg-inverse)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-default-400)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add loading-indicator` (after `npx sdaia-ui@latest init`), then import `{ LoadingIndicator }` from `@/components/ui/LoadingIndicator`.
+- 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/notification-banner.md

@@ -0,0 +1,73 @@
+# Notification Banner
+
+## Metadata
+- Component: Notification Banner
+- Slug: `notification-banner`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add notification-banner`
+- Import: `import { NotificationBanner } from '@/components/ui/NotificationBanner'`
+- Installed files: `NotificationBanner.tsx`, `NotificationBanner.types.ts`, `NotificationBanner.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/notification-banner
+
+> **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 notification-banner`. It copies the source into your components folder (`components/ui/NotificationBanner/`, under `src/` when the project has one); import it as `@/components/ui/NotificationBanner`. 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 |
+| --- | --- | --- | --- |
+| `layout?` | `'inline' \| 'stacked'` | 'inline' | Layout orientation. - `inline` — media on the start edge, text and actions stacked next to it. - `stacked` — media row on top, text and actions stacked below. |
+| `type?` | `'leading-icon' \| 'avatar' \| 'progress' \| 'image'` | 'leading-icon' | Which media slot is rendered. - `leading-icon` — rounded featured icon (pass via `icon`). - `avatar` — 40 px avatar (pass via `avatar`). - `progress` — avatar + inline `ProgressBar` (pass value via `progress`). - `image` — image block (pass via `imageSrc`). |
+| `title` | `ReactNode` | — | Title text (required) |
+| `description?` | `ReactNode` | — | Supporting description text |
+| `icon?` | `ReactNode` | — | Icon to render inside the featured-icon slot — only used when `type="leading-icon"`. Defaults to `<AlertCircleIcon />` when omitted. |
+| `avatar?` | `NotificationBannerAvatar` | — | Avatar slot content — only used when `type="avatar"` or `type="progress"`. |
+| `imageSrc?` | `string` | — | Image source — only used when `type="image"`. |
+| `imageAlt?` | `string` | '' | Image alt text — only used when `type="image"`. |
+| `progress?` | `number` | — | Progress value 0–100 — only used when `type="progress"`. The progress bar renders only when a value is provided. |
+| `actions?` | `ReactNode` | — | Action buttons rendered in the actions row. Typically one or two `<Button variant="transparent" />` elements. |
+| `onDismiss?` | `() => void` | — | Invoked when the close button is clicked. |
+| `hideCloseButton?` | `boolean` | false | Hide the close button entirely. |
+| `labels?` | `Partial<NotificationBannerLabels>` | — | Override built-in strings (English defaults) to localize the banner. |
+| `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)
+- `layout`: `'inline'` \| `'stacked'` — Layout orientation — inline puts the media on the start edge, stacked puts it above the content.
+- `type`: `'leading-icon'` \| `'avatar'` \| `'progress'` \| `'image'` — Media type rendered alongside the title/description.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `dismissLabel`
+- `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-muted)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-on-default)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `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)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add notification-banner` (after `npx sdaia-ui@latest init`), then import `{ NotificationBanner }` from `@/components/ui/NotificationBanner`.
+- 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/notification-popup.md

@@ -0,0 +1,87 @@
+# Notification Popup
+
+## Metadata
+- Component: Notification Popup
+- Slug: `notification-popup`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add notification-popup`
+- Import: `import { NotificationPopup } from '@/components/ui/NotificationPopup'`
+- Installed files: `NotificationPopup.tsx`, `NotificationPopup.types.ts`, `NotificationPopup.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/notification-popup
+
+> **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 notification-popup`. It copies the source into your components folder (`components/ui/NotificationPopup/`, under `src/` when the project has one); import it as `@/components/ui/NotificationPopup`. 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?` | `'success' \| 'error' \| 'warning' \| 'alert' \| 'input'` | 'success' | Popup type. - `success` / `error` / `warning` — 360 px wide, single centered action button. - `alert` — 360 px wide, two side-by-side action buttons. - `input` — 480 px wide, supports `children` (e.g. radio rows) and `footer` (consent text), with actions rendered as a stacked full-width column. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `title` | `ReactNode` | — | Title text (required). |
+| `description?` | `ReactNode` | — | Supporting description text under the title. |
+| `icon?` | `ReactNode` | — | Override the default per-type icon. Defaults per type: - `success` → `TickIcon` - `error`   → `CloseIcon` - `warning` → `AlertCircleIcon` - `alert`   → `BellIcon` - `input`   → `AlertCircleIcon` |
+| `actions?` | `ReactNode` | — | Action buttons rendered in the actions row. Typically one or two `<Button />` elements — the wrapping row's layout is selected automatically based on `type`, or explicitly via `actionsLayout` if you need to override (e.g. a warning popup with two side-by-side buttons). |
+| `actionsLayout?` | `'single' \| 'pair' \| 'stacked'` | — | Override the default actions-row layout. - `single`  → one centered button (default for success / error / warning) - `pair`    → two side-by-side buttons with `gap-md`, both `flex-1` (default for `alert`) - `stacked` → vertical stack of full-width buttons (default for `input`) |
+| `children?` | `ReactNode` | — | Extra content rendered between the header and the actions row. Used by the `input` type for the radio-row list. |
+| `footer?` | `ReactNode` | — | Footer content rendered under the actions row. Used by the `input` type for the consent / Privacy Policy text. |
+| `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`: `'success'` \| `'error'` \| `'warning'` \| `'alert'` \| `'input'` — Visual/semantic variant — drives icon, featured-icon background, and layout differences.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the popup card.
+  - `'solid'` (default) — opaque subtle background with a hairline border.
+  - `'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.
+- `actionsLayout`: `'single'` \| `'pair'` \| `'stacked'` — Override the default actions-row layout.
+- `single`  → one centered button (default for success / error / warning)
+- `pair`    → two side-by-side buttons with `gap-md`, both `flex-1`
+              (default for `alert`)
+- `stacked` → vertical stack of full-width buttons (default for `input`)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-danger-strong)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-bg-success-strong)`
+- `var(--ds-color-bg-warning-strong)`
+- `var(--ds-color-border-on-default)`
+- `var(--ds-color-border-warning-subtle)`
+- `var(--ds-color-icon-brand-subtle)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-7xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add notification-popup` (after `npx sdaia-ui@latest init`), then import `{ NotificationPopup }` from `@/components/ui/NotificationPopup`.
+- 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.