@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/actions/link.md

@@ -0,0 +1,76 @@
+# Link
+
+## Metadata
+- Component: Link
+- Slug: `link`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add link`
+- Import: `import { Link } from '@/components/ui/Link'`
+- Installed files: `Link.tsx`, `Link.types.ts`, `Link.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/link
+
+> **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 link`. It copies the source into your components folder (`components/ui/Link/`, under `src/` when the project has one); import it as `@/components/ui/Link`. 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?` | `AnchorHTMLAttributes<HTMLAnchorElement>['dir']` | — | Text direction applied to the root ('ltr' \| 'rtl'). Leave unset to inherit. Typed as the native `dir` attribute for backward compatibility. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the link |
+| `variant?` | `'primary' \| 'neutral' \| 'danger'` | 'primary' | Visual style |
+| `inline?` | `boolean` | false | Show underline |
+| `disabled?` | `boolean` | false | Disabled state |
+| `visited?` | `boolean` | false | Visited state (controlled) |
+| `leadingIcon?` | `ReactNode` | — | Leading icon element (e.g. `<DgaIcon data={…Stroke} />`), sized by a size-icon-* token |
+| `trailingIcon?` | `ReactNode` | — | Trailing icon element |
+| `as?` | `'a' \| 'button'` | 'a' | Renders a `<button type="button">` with the link styling instead of an `<a>`, for in-page actions that do not navigate (e.g. "Clear selection"). `href`, `target` and the other anchor-only attributes are ignored then. |
+| `children?` | `ReactNode` | — | Link content |
+
+Also accepts standard `<a>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the link
+- `variant`: `'primary'` \| `'neutral'` \| `'danger'` — Visual style. `danger` uses the Link/link-danger tokens — for links that
+point at a problem, such as the items of an `ErrorSummary`.
+- `as`: `'a'` \| `'button'` — Element the link renders.
+
+## 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-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-link-)`
+- `var(--ds-color-link-danger)`
+- `var(--ds-color-link-danger-focused)`
+- `var(--ds-color-link-danger-hovered)`
+- `var(--ds-color-link-danger-pressed)`
+- `var(--ds-color-link-danger-visited)`
+- `var(--ds-color-link-neutral)`
+- `var(--ds-color-link-neutral-focused)`
+- `var(--ds-color-link-neutral-hovered)`
+- `var(--ds-color-link-neutral-pressed)`
+- `var(--ds-color-link-neutral-visited)`
+- `var(--ds-color-link-primary)`
+- `var(--ds-color-link-primary-focused)`
+- `var(--ds-color-link-primary-hovered)`
+- `var(--ds-color-link-primary-pressed)`
+- `var(--ds-color-link-primary-visited)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add link` (after `npx sdaia-ui@latest init`), then import `{ Link }` from `@/components/ui/Link`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Express the disabled state with the `disabled` prop, not custom styling.
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/actions/modal.md

@@ -0,0 +1,103 @@
+# Modal
+
+## Metadata
+- Component: Modal
+- Slug: `modal`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add modal`
+- Import: `import { Modal } from '@/components/ui/Modal'`
+- Installed files: `Modal.tsx`, `Modal.types.ts`, `Modal.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/modal
+
+> **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 modal`. It copies the source into your components folder (`components/ui/Modal/`, under `src/` when the project has one); import it as `@/components/ui/Modal`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open?` | `boolean` | — | Controlled visibility. When omitted the modal is open for as long as it is mounted, so the existing `{open && <Modal onClose={…} />}` pattern keeps working. Pass `open={false}` to keep it mounted but closed (plays the exit animation and returns focus to the opener). |
+| `inline?` | `boolean` | false | Static showcase mode — renders only the card, in place, with no portal, overlay, focus trap, Escape handling or scroll lock. For documentation / design previews only. Real dialogs must leave this off so keyboard and screen-reader users get the modal behaviour. |
+| `container?` | `Element \| null` | — | Element the dialog is portalled into. Defaults to `document.body`. Theme (`.theme-dark`), brand (`.brand-*`) and direction are copied from where the Modal is rendered, so a body portal still matches a locally themed section. |
+| `closeOnEscape?` | `boolean` | true | Close (calls `onClose`) when Escape is pressed. Default `true`. |
+| `closeOnOverlayClick?` | `boolean` | true | Close (calls `onClose`) when the overlay outside the card is clicked. Default `true`. |
+| `lockScroll?` | `boolean` | true | Prevent the page behind the dialog from scrolling while open. Default `true`. |
+| `initialFocusRef?` | `RefObject<HTMLElement \| null>` | — | Element that receives focus when the dialog opens. Defaults to the first `[autofocus]`/`[data-autofocus]` element, then the first focusable element inside the dialog, then the dialog itself. |
+| `restoreFocus?` | `boolean` | true | Return focus to the element that opened the dialog when it closes. Default `true`. |
+| `overlayClassName?` | `string` | — | Extra classes for the overlay (backdrop) element. |
+| `showHeader?` | `boolean` | true | Show the ModalHeader section |
+| `divider?` | `boolean` | true | Show the divider between the content and the actions (hidden when no action renders). |
+| `showActions?` | `boolean` | true | Show the ModalActions section |
+| `mobile?` | `boolean` | false | Mobile layout — narrower width + stacked actions |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `title?` | `string` | — | Dialog title — also the dialog's accessible name (`aria-labelledby`). |
+| `supportingText?` | `string` | — | Supporting text — also the dialog's description (`aria-describedby`). |
+| `showSupportingText?` | `boolean` | true | Show supporting text |
+| `headerPlacement?` | `ModalHeaderPlacement` | 'start' | Header placement layout |
+| `featuredIcon?` | `ReactNode` | — | Featured icon in header |
+| `showCloseButton?` | `boolean` | true | Show close button in header |
+| `onClose?` | `() => void` | — | Called by the close button, Escape and overlay click. |
+| `actionsType?` | `ModalActionsType` | 'hug-start' | Actions layout type (overridden to "stack" when mobile=true) |
+| `primaryLabel?` | `string` | — | Primary button label — the button renders only when a label is set. |
+| `secondaryLabel?` | `string` | — | Secondary button label — the button renders only when a label is set. |
+| `showSecondary?` | `boolean` | true | Show secondary button (still requires `secondaryLabel`). Default `true`. |
+| `tertiaryLabel?` | `string` | — | Tertiary button label — the button renders only when a label is set. |
+| `showTertiary?` | `boolean` | false | Show tertiary button (also requires `tertiaryLabel`). Default `false`. |
+| `onPrimaryClick?` | `() => void` | — | Primary button click handler |
+| `onSecondaryClick?` | `() => void` | — | Secondary button click handler |
+| `onTertiaryClick?` | `() => void` | — | Tertiary button click handler |
+| `labels?` | `Partial<ModalLabels>` | — | Override built-in strings (English defaults) to localize the modal. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted (the portalled dialog copies the direction of the place the Modal is rendered). |
+| `children?` | `ReactNode` | — | Body content, rendered below the title / supporting text. |
+| `className?` | `string` | — | Additional class name (applied to the dialog card). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`, `title`.
+
+## Options (allowed values)
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the modal card.
+  - `'solid'` (default) — opaque card with the standard surface 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 (the portalled
+dialog copies the direction of the place the Modal is rendered).
+
+## Deprecated props
+Do not use in new code:
+- `closeLabel`
+
+## Accessibility
+Built in (SDAIA review item A4) — verified by `tests/a11y/keyboard/modal.spec.ts` in the design system's test suite:
+- Renders a `role="dialog"` with `aria-modal="true"`, named by its `title`.
+- Opening moves focus into the dialog.
+- `Tab` / `Shift+Tab` are trapped inside the dialog while it is open.
+- `Escape` calls `onClose` (`closeOnEscape`, default `true`) and focus returns to the element that opened it.
+
+You must:
+- Pass a `title` (it is the dialog's accessible name) and an `onClose` handler.
+
+- 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-alpha-black-70)`
+- `var(--ds-color-alpha-black-50)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-default)`
+- `var(--ds-motion-enter-duration)`
+- `var(--ds-motion-enter-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add modal` (after `npx sdaia-ui@latest init`), then import `{ Modal }` from `@/components/ui/Modal`.
+- 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/actions/pagination.md

@@ -0,0 +1,69 @@
+# Pagination
+
+## Metadata
+- Component: Pagination
+- Slug: `pagination`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add pagination`
+- Import: `import { Pagination } from '@/components/ui/Pagination'`
+- Installed files: `Pagination.tsx`, `Pagination.types.ts`, `Pagination.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/pagination
+
+> **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 pagination`. It copies the source into your components folder (`components/ui/Pagination/`, under `src/` when the project has one); import it as `@/components/ui/Pagination`. 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?` | `'numeric' \| 'text' \| 'button'` | "numeric" | Figma variant: Numeric / Text / Button |
+| `placement?` | `'start' \| 'center' \| 'end'` | "start" | Figma variant: Start / Center / End |
+| `mobile?` | `boolean` | false | Figma variant: Mobile |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. When omitted the component follows the nearest `dir` ancestor. |
+| `fullWidth?` | `boolean` | false | Stretch the pagination to fill its parent container instead of clamping to the desktop/mobile max widths. Use for layouts (e.g. MediaGallery) where the prev / "Page X of Y" / next row must span the device width. |
+| `page?` | `number` | 1 | Current page (1-indexed). Used to render the selected cell and selector. Clamped to `1…totalPages`. |
+| `totalPages?` | `number` | — | Total pages. Used to render the page cells and the "Page X of Y" text. When omitted no page cells or summary are rendered. |
+| `onPageChange?` | `(page: number) => void` | — | Called when a user clicks prev/next or a page cell. Without it the pagination is read-only (prev/next disabled, cells not interactive). |
+| `labels?` | `Partial<PaginationLabels>` | — | Translatable built-in strings (visible and accessible). |
+| `liveSummary?` | `boolean` | false | Announces the "Page X of Y" summary of the text type politely (`aria-live="polite"`) when the page changes — for pagination that swaps the content above it, such as a `Table`'s footer. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `type`: `'numeric'` \| `'text'` \| `'button'` — Figma variant: Numeric / Text / Button
+- `placement`: `'start'` \| `'center'` \| `'end'` — Figma variant: Start / Center / End
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. When omitted the component follows
+the nearest `dir` ancestor.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-brand-muted)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-form-field-text-pressed)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-none)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add pagination` (after `npx sdaia-ui@latest init`), then import `{ Pagination }` from `@/components/ui/Pagination`.
+- 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/actions/radio-button.md

@@ -0,0 +1,88 @@
+# Radio Button
+
+## Metadata
+- Component: Radio Button
+- Slug: `radio-button`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add radio-button`
+- Import: `import { RadioButton } from '@/components/ui/RadioButton'`
+- Installed files: `RadioButton.tsx`, `RadioButton.types.ts`, `RadioButton.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/radiobutton
+
+> **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 radio-button`. It copies the source into your components folder (`components/ui/RadioButton/`, under `src/` when the project has one); import it as `@/components/ui/RadioButton`. 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` | — | Label displayed next to the radio button |
+| `placement?` | `'start' \| 'end' \| 'top' \| 'bottom'` | 'start' | Where the radio sits relative to the label (Figma Placement). |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the radio button |
+| `variant?` | `'primary' \| 'neutral'` | 'primary' | Visual style variant |
+| `error?` | `string` | — | Error message displayed below the radio button. Sets `aria-invalid` and is linked via `aria-describedby`. |
+| `helperText?` | `string` | — | Helper text displayed under the label (or below the control when there is no label) |
+| `checked?` | `boolean` | — | Whether the radio is selected (controlled). Omit for an uncontrolled radio. |
+| `defaultChecked?` | `boolean` | — | Initial selected state for uncontrolled usage. Ignored when `checked` is supplied. |
+| `onCheckedChange?` | `(checked: boolean) => void` | — | Called with the new checked state when the user selects this radio. Like the native `change` event, it fires on selection only (a radio is not notified when a sibling in its group is picked). Native `onChange` keeps working. |
+| `validationBehavior?` | `'native' \| 'aria'` | 'native' | How `required` is enforced. `'native'` sets the native `required` attribute (browser validation bubble on submit); `'aria'` renders `aria-required="true"` instead and leaves validation to you. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the radio and its label. Omit to inherit from the closest `dir` ancestor. |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`, `type`, `readOnly`.
+
+## Options (allowed values)
+- `placement`: `'start'` \| `'end'` \| `'top'` \| `'bottom'` — Position of the radio relative to the label block (Figma Placement).
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the radio button
+- `variant`: `'primary'` \| `'neutral'` — Visual style variant
+- `validationBehavior`: `'native'` \| `'aria'` — How `required` is enforced. `'native'` sets the native `required` attribute (browser validation
+bubble on submit); `'aria'` renders `aria-required="true"` instead and leaves validation to you.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the radio and its label. Omit to inherit from the closest `dir` ancestor.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+Built in (SDAIA review item A1) — verified by `tests/a11y/keyboard/mouse-toggles.spec.ts` in the design system's test suite:
+- A click on the circle selects it, also when there is no visible label.
+
+You must:
+- Group radios that answer one question (one `name`) and give the group a 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-bg-default)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-disabled)`
+- `var(--ds-color-control-border)`
+- `var(--ds-color-control-neutral-checked)`
+- `var(--ds-color-control-neutral-hovered)`
+- `var(--ds-color-control-neutral-pressed)`
+- `var(--ds-color-control-pressed)`
+- `var(--ds-color-control-primary-checked)`
+- `var(--ds-color-control-primary-hovered)`
+- `var(--ds-color-control-primary-pressed)`
+- `var(--ds-color-form-field-border-danger)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-icon-lg)`
+- `var(--ds-icon-sm)`
+- `var(--ds-icon-xl)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `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 radio-button` (after `npx sdaia-ui@latest init`), then import `{ RadioButton }` from `@/components/ui/RadioButton`.
+- 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/actions/switch.md

@@ -0,0 +1,87 @@
+# Switch
+
+## Metadata
+- Component: Switch
+- Slug: `switch`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add switch`
+- Import: `import { Switch } from '@/components/ui/Switch'`
+- Installed files: `Switch.tsx`, `Switch.types.ts`, `Switch.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/switch
+
+> **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 switch`. It copies the source into your components folder (`components/ui/Switch/`, under `src/` when the project has one); import it as `@/components/ui/Switch`. 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 |
+| --- | --- | --- | --- |
+| `checked?` | `boolean` | — | Whether the switch is on (controlled). Omit (together with `on`) for an uncontrolled switch. |
+| `defaultChecked?` | `boolean` | — | Initial state for uncontrolled usage. Ignored when `checked` (or `on`) is supplied. |
+| `onCheckedChange?` | `(checked: boolean) => void` | — | Called with the new on/off state when the user toggles the switch. Native `onChange` keeps working. |
+| `size?` | `'md' \| 'lg'` | 'md' | Size of the switch |
+| `label?` | `ReactNode` | — | Label displayed next to the switch |
+| `placement?` | `'start' \| 'end' \| 'top' \| 'bottom'` | 'start' | Where the switch sits relative to the label (Figma Placement). |
+| `error?` | `string` | — | Error message. Sets `aria-invalid` and is linked via `aria-describedby`. |
+| `helperText?` | `string` | — | Helper text |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the switch and its label. Omit to inherit from the closest `dir` ancestor. |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`, `type`.
+
+## Options (allowed values)
+- `size`: `'md'` \| `'lg'` — Size of the switch
+- `placement`: `'start'` \| `'end'` \| `'top'` \| `'bottom'` — Position of the switch relative to the label block (Figma Placement).
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the switch and its label. Omit to inherit from the closest `dir` ancestor.
+
+## Deprecated props
+Do not use in new code:
+- `on` — Whether the switch is on (controlled).
+- `rtl`
+
+## Accessibility
+Built in (SDAIA review item A6) — verified by `tests/a11y/keyboard/switch.spec.ts, tests/a11y/keyboard/mouse-toggles.spec.ts` in the design system's test suite:
+- Exposes `role="switch"`, named by its visible label; `Space` toggles it.
+- Error text is linked with `aria-describedby` and sets `aria-invalid`.
+- The off track keeps ≥ 3:1 contrast against the page in light and dark.
+- A click on the track or the thumb toggles it, also without a visible label.
+
+You must:
+- Without a visible label, pass `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-bg-default)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-button-bg-primary-focused)`
+- `var(--ds-color-button-bg-primary-hovered)`
+- `var(--ds-color-button-bg-primary-pressed)`
+- `var(--ds-color-form-field-border-)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-form-field-border-hovered)`
+- `var(--ds-color-form-field-border-pressed)`
+- `var(--ds-color-form-switch-track-off-)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add switch` (after `npx sdaia-ui@latest init`), then import `{ Switch }` from `@/components/ui/Switch`.
+- 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/actions/tag.md

@@ -0,0 +1,69 @@
+# Tag
+
+## Metadata
+- Component: Tag
+- Slug: `tag`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add tag`
+- Import: `import { Tag } from '@/components/ui/Tag'`
+- Installed files: `Tag.tsx`, `Tag.types.ts`, `Tag.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tag
+
+> **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 tag`. It copies the source into your components folder (`components/ui/Tag/`, under `src/` when the project has one); import it as `@/components/ui/Tag`. 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?` | `string` | — | Label text. Unset (and no `children`) renders no label. |
+| `children?` | `ReactNode` | — | Label content used when `label` is unset. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'lg' | Size of the tag. |
+| `leading?` | `'default' \| 'icon' \| 'country' \| 'avatar' \| 'dot'` | 'default' | Leading element type. |
+| `action?` | `'text-only' \| 'icon' \| 'count'` | 'text-only' | Action element type. |
+| `leadingIcon?` | `ReactNode` | — | Custom leading icon (overrides default) |
+| `trailing?` | `boolean` | true | Whether to show the trailing element. |
+| `count?` | `number` | — | Count value (when action="count"). Unset renders no count badge. |
+| `avatarSrc?` | `string` | — | Avatar image src (when leading="avatar"). Unset → no avatar is drawn (there is no bundled fallback). |
+| `flagSrc?` | `string` | — | Flag image src (when leading="country"). Unset → no flag is drawn (there is no bundled fallback). |
+| `dotColor?` | `string` | 'var(--ds-color-bg-brand)' | Dot color (when leading="dot"). |
+| `onClose?` | `() => void` | — | Called when the close icon is clicked |
+| `disabled?` | `boolean` | false | Disabled state |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Unset inherits from the document. |
+| `labels?` | `Partial<TagLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the tag.
+- `leading`: `'default'` \| `'icon'` \| `'country'` \| `'avatar'` \| `'dot'` — Leading element type.
+- `action`: `'text-only'` \| `'icon'` \| `'count'` — Action element type.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Unset inherits from the document.
+
+## 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-border-default-strong)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-default)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xs)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add tag` (after `npx sdaia-ui@latest init`), then import `{ Tag }` from `@/components/ui/Tag`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Express the disabled state with the `disabled` prop, not custom styling.
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/agent-activity.md

@@ -0,0 +1,65 @@
+# Agent Activity
+
+## Metadata
+- Component: Agent Activity
+- Slug: `agent-activity`
+- Category: AI
+- Install: `npx sdaia-ui@latest add agent-activity`
+- Import: `import { AgentActivity } from '@/components/ui/AgentActivity'`
+- Installed files: `AgentActivity.tsx`, `AgentActivity.types.ts`, `AgentActivity.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/agent-activity
+
+> **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 agent-activity`. It copies the source into your components folder (`components/ui/AgentActivity/`, under `src/` when the project has one); import it as `@/components/ui/AgentActivity`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'brand' \| 'neutral' \| 'outline'` | 'brand' | Visual style of the activity card. - `brand`   — raised surface (default) - `neutral` — subtle surface - `outline` — transparent surface |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Inherits from the document when unset. |
+| `label?` | `ReactNode` | — | Header label (e.g. `Live Operation Log`). |
+| `date?` | `ReactNode` | — | Header date / scope shown on the trailing side (e.g. `June 2026`). |
+| `headerIcon?` | `string` | timeHalfPassStroke | Header icon — a `@platformscode/icons` data URL. |
+| `showHeader?` | `boolean` | true | Show the header row (label + date). |
+| `action` | `ReactNode` | — | The activity description — the core log line. |
+| `animated?` | `boolean` | true | Fade the action line in — and replay the fade whenever a string `action` changes (live log cycling). Collapses under `prefers-reduced-motion`. |
+| `live?` | `boolean` | true | Announce a changed `action` to screen readers — the action line is a polite live region (`aria-live="polite"`). The timestamp is outside the region, so a ticking clock is never announced. Set to `false` for static/historic entries (e.g. a run-history list). |
+| `actionIcon?` | `string` | wrench02Stroke | Leading action icon — a `@platformscode/icons` data URL. |
+| `showActionIcon?` | `boolean` | true | Show the leading action icon. |
+| `timestamp?` | `ReactNode` | — | Trailing timestamp (e.g. `14:20:34.120`). |
+| `showTimestamp?` | `boolean` | true | Show the trailing timestamp. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout. Inherits from the document when unset.
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-2xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add agent-activity` (after `npx sdaia-ui@latest init`), then import `{ AgentActivity }` from `@/components/ui/AgentActivity`.
+- 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/ai/agent-card.md

@@ -0,0 +1,65 @@
+# Agent Card
+
+## Metadata
+- Component: Agent Card
+- Slug: `agent-card`
+- Category: AI
+- Install: `npx sdaia-ui@latest add agent-card`
+- Import: `import { AgentCard } from '@/components/ui/AgentCard'`
+- Installed files: `AgentCard.tsx`, `AgentCard.types.ts`, `AgentCard.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/agent-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 agent-card`. It copies the source into your components folder (`components/ui/AgentCard/`, under `src/` when the project has one); import it as `@/components/ui/AgentCard`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'brand' \| 'neutral' \| 'outline'` | 'brand' | Visual style of the agent card. - `brand`   — raised surface + brand-tinted avatar tile (default) - `neutral` — subtle surface + muted avatar tile - `outline` — transparent surface + outlined avatar tile |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Inherits from the document when unset. |
+| `icon?` | `string` | roboticStroke | Avatar icon — a `@platformscode/icons` data URL. |
+| `name` | `ReactNode` | — | Agent name. |
+| `role?` | `ReactNode` | — | Agent role / description. |
+| `showRole?` | `boolean` | true | Show the role line. |
+| `showStatus?` | `boolean` | true | Show the status — renders both the avatar presence dot and the status badge. |
+| `status?` | `ReactNode` | labels.status ('Active') | Status badge label. Wins over `labels.status`; pass `null` to hide the badge while keeping the presence dot. |
+| `statusColor?` | `BadgeColor` | 'primary' | Status badge colour. |
+| `statusDot?` | `StatusDotStatus` | 'online' | Presence-dot status colour. |
+| `labels?` | `Partial<AgentCardLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `title`, `role`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout. Inherits from the document when unset.
+
+## 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-brand-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add agent-card` (after `npx sdaia-ui@latest init`), then import `{ AgentCard }` from `@/components/ui/AgentCard`.
+- 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.