@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/actions/button-menu.md

@@ -0,0 +1,82 @@
+# Button Menu
+
+## Metadata
+- Component: Button Menu
+- Slug: `button-menu`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add button-menu`
+- Import: `import { ButtonMenu } from '@/components/ui/ButtonMenu'`
+- Installed files: `ButtonMenu.tsx`, `ButtonMenu.types.ts`, `ButtonMenu.variants.ts`, `ButtonMenuPanel.tsx`, `index.ts`, `useMenuButton.ts`
+- Docs: https://ds.nacew.com/components/buttonmenu
+
+> **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 button-menu`. It copies the source into your components folder (`components/ui/ButtonMenu/`, under `src/` when the project has one); import it as `@/components/ui/ButtonMenu`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction applied to the trigger (and its menu). Leave unset to inherit. |
+| `variant?` | `'neutral' \| 'primary' \| 'secondary-solid' \| 'secondary-outline' \| 'subtle' \| 'transparent'` | 'neutral' | Visual style variant. Defaults to 'neutral'. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size tier. Defaults to 'md'. |
+| `leadingIcon?` | `ReactNode` | — | Icon displayed before the label. Direction-aware: appears on the logical start side. |
+| `iconOnly?` | `boolean` | false | When true: renders only the leading icon + trailing chevron, no label text. Uses the same padding as a regular button (not the square icon-only padding). Give the button an accessible name with `aria-label`. |
+| `disabled?` | `boolean` | false | Disables the button and prevents interaction. |
+| `selected?` | `boolean` | false | Shows the selected (pressed-in) look. ButtonMenu also shows it while its menu is open. Unlike Button, it never sets `aria-pressed` — a menu button exposes `aria-expanded` instead. |
+| `fullWidth?` | `boolean` | false | Makes the button take the full width of its container. |
+| `as?` | `ElementType` | — | Override the rendered HTML element (e.g. 'a' for link-styled trigger). |
+| `children?` | `ReactNode` | — | Button label. Hidden when iconOnly is true. |
+| `menuItems?` | `ButtonMenuItem[]` | — | Actions of the built-in WAI-ARIA menu. When provided, clicking the button (or pressing Enter / Space / ArrowDown / ArrowUp) opens a `role="menu"` panel with full keyboard support. Omit it to wire your own menu and pass `open` so the trigger exposes `aria-expanded`. |
+| `open?` | `boolean` | — | Open state of the menu (controlled). Sets `aria-expanded` on the trigger — also when you render your own menu instead of `menuItems`. |
+| `defaultOpen?` | `boolean` | — | Initial open state when uncontrolled (built-in menu only). |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the built-in menu opens or closes. |
+| `menuAlign?` | `'start' \| 'end'` | 'start' | Which edge of the trigger the built-in menu aligns to (logical, so it flips in RTL). Use 'end' for overflow menus near the end of a row. |
+
+Also accepts standard `<button>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction applied to the trigger (and its menu). Leave unset to inherit.
+- `variant`: `'neutral'` \| `'primary'` \| `'secondary-solid'` \| `'secondary-outline'` \| `'subtle'` \| `'transparent'` — Six visual styles — matches Figma "Button_Menu" Style property exactly.
+Maps 1-to-1 to the existing Button variants.
+Destructive is excluded — not in the Figma ButtonMenu spec.
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Three sizes — maps Figma Large→lg, Medium→md, Small→sm
+- `menuAlign`: `'start'` \| `'end'` — Which edge of the trigger the built-in menu aligns to (logical, so it
+flips in RTL). Use 'end' for overflow menus near the end of a row.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## 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-bg-emphasis-high)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-danger-strong)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-button-bg-danger-secondary-default)`
+- `var(--ds-color-button-bg-danger-secondary-hovered)`
+- `var(--ds-color-form-option-bg-hover)`
+- `var(--ds-color-form-option-bg-pressed)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add button-menu` (after `npx sdaia-ui@latest init`), then import `{ ButtonMenu }` from `@/components/ui/ButtonMenu`.
+- 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/button-split.md

@@ -0,0 +1,69 @@
+# Button Split
+
+## Metadata
+- Component: Button Split
+- Slug: `button-split`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add button-split`
+- Import: `import { ButtonSplit } from '@/components/ui/ButtonSplit'`
+- Installed files: `ButtonSplit.tsx`, `ButtonSplit.types.ts`, `ButtonSplit.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/buttonsplit
+
+> **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 button-split`. It copies the source into your components folder (`components/ui/ButtonSplit/`, under `src/` when the project has one); import it as `@/components/ui/ButtonSplit`. 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 for the main action button. Use `label` for the explicit prop-driven API (preferred). |
+| `variant?` | `'neutral' \| 'primary' \| 'secondary-solid' \| 'secondary-outline' \| 'subtle' \| 'transparent'` | 'neutral' | Visual style variant. Defaults to 'neutral'. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size tier. Defaults to 'md'. |
+| `leadingIcon?` | `ReactNode` | — | Icon displayed before the label in the main action button. Direction-aware: appears on the logical-start side. |
+| `onClick?` | `ButtonHTMLAttributes<HTMLButtonElement>['onClick']` | — | Click handler for the main action button (start section). Separate from the dropdown menu button click. |
+| `onMenuClick?` | `ButtonHTMLAttributes<HTMLButtonElement>['onClick']` | — | Click handler for the dropdown/menu chevron button (end section). Called when the chevron is clicked regardless of `open` / `onOpenChange`. |
+| `menuItems?` | `ButtonSplitMenuItem[]` | — | Items rendered inside the dropdown menu panel. When provided, clicking the chevron toggles the panel. |
+| `open?` | `boolean` | — | Controlled open state of the dropdown panel. When provided together with `onOpenChange`, the component is fully controlled. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the open state should change (controlled mode). |
+| `labels?` | `Partial<ButtonSplitLabels>` | — | Translatable built-in strings (English defaults). |
+| `defaultOpen?` | `boolean` | — | Initial open state of the dropdown panel when uncontrolled. |
+| `disabled?` | `boolean` | false | Disables both button sections simultaneously. |
+| `className?` | `string` | — | Additional className applied to the outer wrapper. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Direction override for RTL layout. Leave unset to inherit. |
+| `mainButtonProps?` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' \| 'disabled'>` | — | Extra props forwarded to the main action button element. |
+| `menuButtonProps?` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' \| 'disabled'>` | — | Extra props forwarded to the menu/chevron button element. |
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'primary'` \| `'secondary-solid'` \| `'secondary-outline'` \| `'subtle'` \| `'transparent'` — Six visual styles — matches Figma "Button_Split" Style property exactly.
+"Transparence" (Figma typo) is normalised to "transparent" in the API.
+Maps 1-to-1 to the existing Button variant names.
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Three sizes — maps Figma Large→lg, Medium→md, Small→sm
+- `dir`: `'ltr'` \| `'rtl'` — Direction override for RTL layout. Leave unset to inherit.
+
+## Deprecated props
+Do not use in new code:
+- `children` — Legacy children API — used as label text when `label` is not provided.
+- `menuAriaLabel` — Accessible label for the chevron/menu button.
+- `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-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-border-on-dark-40)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add button-split` (after `npx sdaia-ui@latest init`), then import `{ ButtonSplit }` from `@/components/ui/ButtonSplit`.
+- 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/button.md

@@ -0,0 +1,101 @@
+# Button
+
+## Metadata
+- Component: Button
+- Slug: `button`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add button`
+- Import: `import { Button } from '@/components/ui/Button'`
+- Installed files: `Button.tsx`, `Button.types.ts`, `Button.variants.ts`, `index.ts`, `resolveButtonStyle.ts`
+- Docs: https://ds.nacew.com/components/button
+
+> **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 button`. It copies the source into your components folder (`components/ui/Button/`, under `src/` when the project has one); import it as `@/components/ui/Button`. 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?` | `ButtonHTMLAttributes<HTMLButtonElement>['dir']` | — | Text direction applied to the button root. Leave unset to inherit from the page; icons placed with `leadingIcon` / `trailingIcon` follow it. Use 'ltr' \| 'rtl'; typed as the native `dir` attribute for backward compatibility. |
+| `variant?` | `'neutral' \| 'primary' \| 'secondary-solid' \| 'secondary-outline' \| 'subtle' \| 'transparent'` | 'primary' | Visual style of the button |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the button |
+| `disabled?` | `boolean` | false | Disables the button and prevents interaction |
+| `leadingIcon?` | `ReactNode` | — | Icon displayed before the button label (direction-aware) |
+| `trailingIcon?` | `ReactNode` | — | Icon displayed after the button label (direction-aware) |
+| `iconOnly?` | `boolean` | false | Renders the button as a square icon-only button |
+| `selected?` | `boolean` | false | Marks the button as selected (toggled on) |
+| `fullWidth?` | `boolean` | false | Makes the button take the full width of its container |
+| `destructive?` | `boolean` | false | Applies destructive (danger) styling to the current `variant`. Matches Figma `Destructive=True` — not a separate style value. Works with: primary, secondary-solid, secondary-outline, subtle, transparent. |
+| `as?` | `ElementType` | — | Override the rendered HTML element |
+| `href?` | `string` | — | Destination URL when rendering the button as a link (`as="a"`). Only meaningful on an anchor element. |
+| `target?` | `HTMLAttributeAnchorTarget` | — | Anchor `target` — only meaningful alongside `href`. |
+| `rel?` | `string` | — | Anchor `rel` — only meaningful alongside `href`. |
+| `children?` | `ReactNode` | — | — |
+
+Also accepts standard `<button>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'primary'` \| `'secondary-solid'` \| `'secondary-outline'` \| `'subtle'` \| `'transparent'` — Style variants — matches Figma `Style` (Transparent, not ghost).
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the button
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+- `leftIcon`
+- `rightIcon`
+
+## 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-default)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-danger-strong)`
+- `var(--ds-color-border-danger-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-button-bg-black-focused)`
+- `var(--ds-color-button-bg-black-hovered)`
+- `var(--ds-color-button-bg-black-pressed)`
+- `var(--ds-color-button-bg-black-selected)`
+- `var(--ds-color-button-bg-danger-primary-default)`
+- `var(--ds-color-button-bg-danger-primary-hovered)`
+- `var(--ds-color-button-bg-danger-primary-pressed)`
+- `var(--ds-color-button-bg-danger-primary-selected)`
+- `var(--ds-color-button-bg-danger-secondary-default)`
+- `var(--ds-color-button-bg-danger-secondary-hovered)`
+- `var(--ds-color-button-bg-danger-secondary-pressed)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-button-bg-neutral-selected)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-button-bg-primary-hovered)`
+- `var(--ds-color-button-bg-primary-pressed)`
+- `var(--ds-color-button-bg-primary-selected)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-link-danger)`
+- `var(--ds-color-link-danger-hovered)`
+- `var(--ds-color-link-danger-pressed)`
+- `var(--ds-color-link-icon-danger-hovered)`
+- `var(--ds-color-link-icon-danger-pressed)`
+- `var(--ds-color-link-primary)`
+- `var(--ds-color-link-primary-hovered)`
+- `var(--ds-color-link-primary-pressed)`
+- …and 10 more
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add button` (after `npx sdaia-ui@latest init`), then import `{ Button }` from `@/components/ui/Button`.
+- 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/content-switcher.md

@@ -0,0 +1,66 @@
+# Content Switcher
+
+## Metadata
+- Component: Content Switcher
+- Slug: `content-switcher`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add content-switcher`
+- Import: `import { ContentSwitcher } from '@/components/ui/ContentSwitcher'`
+- Installed files: `ContentSwitcher.tsx`, `ContentSwitcher.types.ts`, `ContentSwitcher.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/contentswitcher
+
+> **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 content-switcher`. It copies the source into your components folder (`components/ui/ContentSwitcher/`, under `src/` when the project has one); import it as `@/components/ui/ContentSwitcher`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `ContentSwitcherItem[]` | — | Array of switcher items (2–5) |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'sm' | Size of the switcher |
+| `border?` | `boolean` | false | Figma Border — outer container stroke when true. |
+| `placement?` | `'start' \| 'center' \| 'end'` | 'start' | Figma Placement — aligns the switcher track within a full-width parent. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. Arrow keys follow it (Left/Right swap in RTL). |
+| `value?` | `string` | — | Controlled selected value |
+| `defaultValue?` | `string` | — | Initial selected value (uncontrolled) — defaults to first item |
+| `onValueChange?` | `(value: string) => void` | — | Called with the selected item's value when selection changes |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the switcher
+- `placement`: `'start'` \| `'center'` \| `'end'` — Figma Placement — horizontal alignment of the switcher within its container.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. Arrow keys follow it (Left/Right swap in RTL).
+
+## 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-)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add content-switcher` (after `npx sdaia-ui@latest init`), then import `{ ContentSwitcher }` from `@/components/ui/ContentSwitcher`.
+- 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/date-picker.md

@@ -0,0 +1,115 @@
+# Date Picker
+
+## Metadata
+- Component: Date Picker
+- Slug: `date-picker`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add date-picker`
+- Import: `import { DatePicker } from '@/components/ui/DatePicker'`
+- Installed files: `DatePicker.tsx`, `DatePicker.types.ts`, `DatePicker.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/datepicker
+
+> **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 date-picker`. It copies the source into your components folder (`components/ui/DatePicker/`, under `src/` when the project has one); import it as `@/components/ui/DatePicker`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root element for RTL support. Unset inherits. |
+| `locale?` | `string` | — | BCP 47 locale of the built-in month / weekday names and date formats (digits stay Latin), e.g. `'ar'` or `'en-GB'`. `labels` overrides win. Defaults to `'ar'` when `dir="rtl"`, else `'en'`. Without `dir`, it follows the inherited language / direction: `'ar'` inside an Arabic (`lang="ar…"`) or RTL ancestor, else `'en'`. |
+| `type?` | `'default' \| 'withSidepanel'` | 'default' | Layout type — `'default'` (no sidepanel) or `'withSidepanel'`. Defaults to `'default'`. |
+| `single?` | `boolean` | false | Render a single calendar pane instead of two side-by-side panes. Works with either `type`. Defaults to `false`. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). Applies to both the desktop and mobile layouts. |
+| `calendar?` | `'hijri' \| 'hijri-gregorian' \| 'gregorian' \| 'gregorian-hijri'` | — | Calendar system and date-label order. Defaults to `'hijri'`. |
+| `mobile?` | `boolean` | — | Compact mobile layout — single calendar, stacked action row, preset as a select. |
+| `range?` | `boolean` | false | Enable range selection (start + end date). |
+| `value?` | `Date \| null` | — | Controlled single-date value. |
+| `rangeValue?` | `DateRange` | — | Controlled range value. |
+| `defaultValue?` | `Date \| null` | null | Uncontrolled initial single-date value. |
+| `defaultRangeValue?` | `DateRange` | { start: null, end: null } | Uncontrolled initial range value. |
+| `onChange?` | `(date: Date \| null) => void` | — | Fired when a date is picked (single mode). |
+| `onRangeChange?` | `(range: DateRange) => void` | — | Fired whenever the range changes (range mode). |
+| `onSubmit?` | `(value: DateRange) => void` | — | Fired when the Submit button is clicked. |
+| `onCancel?` | `() => void` | — | Fired when the Cancel button is clicked — and when Escape is pressed inside the picker. When the picker lives in a popup, close the popup here and move focus back to the element that opened it. |
+| `presets?` | `boolean \| DatePickerPreset[]` | — | Preset sidebar configuration. - `true` (default for `type="withSidepanel"`) — show all presets. - `false` — hide presets entirely. - `string[]` — show only the listed presets, in that order. When `type="default"`, presets default to `false` (no sidebar). |
+| `showDateInputs?` | `boolean` | — | Show the date-input fields at the bottom. Defaults to `true`. |
+| `showSecondMonth?` | `boolean` | — | Show the second calendar pane. Defaults to `!single` (two panes unless single). |
+| `minDate?` | `Date` | — | Minimum selectable date (inclusive). |
+| `maxDate?` | `Date` | — | Maximum selectable date (inclusive). |
+| `labels?` | `Partial<DatePickerLabels>` | — | Localised built-in strings. |
+| `presetFooter?` | `ReactNode` | — | Rendered after the preset list (advanced slot, e.g. custom preset). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `onSubmit`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root element for RTL support. Unset inherits.
+- `type`: `'default'` \| `'withSidepanel'` — Date picker layout type.
+  - `'default'`        — calendar(s) only, no preset sidebar.
+  - `'withSidepanel'`  — adds the preset sidebar (Today, Yesterday, …) on the inline-start edge.
+
+The previous `'single' | 'dual'` API has been collapsed into the `single`
+boolean prop — pass `single={true}` with either type to render one calendar
+pane instead of two.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the picker card.
+  - `'solid'` (default) — opaque card with the standard drop shadow.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Reads best placed over imagery or color.
+
+The visual is provided by the shared `.glass-surface` utility, so it is
+theme-aware (light / dark) and identical across every component that
+exposes a `surface` prop.
+- `calendar`: `'hijri'` \| `'hijri-gregorian'` \| `'gregorian'` \| `'gregorian-hijri'` — Calendar system and date-label order.
+
+The first calendar is the primary calendar: it controls the visible month,
+navigation, month/year menus, and primary date-cell label. The optional
+second calendar is rendered as supporting text.
+
+## Deprecated props
+Do not use in new code:
+- `showHijri`
+
+## Accessibility
+Built in (SDAIA review item A5) — verified by `tests/a11y/keyboard/date-picker.spec.ts` in the design system's test suite:
+- Each calendar is a `grid` → `row` → `gridcell` structure.
+- Each calendar is a single `Tab` stop (roving tabindex); arrow keys move between days.
+- Arabic locale (`locale="ar"`, `dir="rtl"` or an RTL parent) switches month names and built-in button / field strings to Arabic; `labels` overrides any string.
+
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-border-on-default-10)`
+- `var(--ds-color-chip-bg-neutral-default)`
+- `var(--ds-color-chip-bg-neutral-hovered)`
+- `var(--ds-color-form-datecell-bg-default)`
+- `var(--ds-color-form-datecell-bg-hovered)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add date-picker` (after `npx sdaia-ui@latest init`), then import `{ DatePicker }` from `@/components/ui/DatePicker`.
+- 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/floating-button.md

@@ -0,0 +1,100 @@
+# Floating Button
+
+## Metadata
+- Component: Floating Button
+- Slug: `floating-button`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add floating-button`
+- Import: `import { FloatingButton } from '@/components/ui/FloatingButton'`
+- Installed files: `FloatingButton.tsx`, `FloatingButton.types.ts`, `FloatingButton.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/floatingbutton
+
+> **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 floating-button`. It copies the source into your components folder (`components/ui/FloatingButton/`, under `src/` when the project has one); import it as `@/components/ui/FloatingButton`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction for RTL support. Leave unset to inherit. |
+| `variant?` | `'neutral' \| 'primary' \| 'secondary-solid'` | 'primary' | Visual style of the button |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the button |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). Overrides `variant` when set to `'glass'`. |
+| `disabled?` | `boolean` | false | Disables the button and prevents interaction |
+| `leadingIcon?` | `ReactNode` | — | Icon displayed before the button label (direction-aware) |
+| `trailingIcon?` | `ReactNode` | — | Icon displayed after the button label (direction-aware) |
+| `iconOnly?` | `boolean` | false | Renders the button as a square icon-only floating button — give it an `aria-label` |
+| `selected?` | `boolean` | false | Marks the button as selected (toggled on) |
+| `as?` | `ElementType` | — | Override the rendered HTML element |
+| `children?` | `ReactNode` | — | — |
+
+Also accepts standard `<button>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction for RTL support. Leave unset to inherit.
+- `variant`: `'neutral'` \| `'primary'` \| `'secondary-solid'` — Visual style of the floating button
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the floating button
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the floating button.
+  - `'solid'` (default) — opaque variant fill.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Reads best when the button 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. When set, it overrides `variant`.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## 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-bg-default)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-button-)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-button-bg-black-hovered)`
+- `var(--ds-color-button-bg-black-pressed)`
+- `var(--ds-color-button-bg-black-selected)`
+- `var(--ds-color-button-bg-neutral-default)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-button-bg-neutral-selected)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-button-bg-primary-hovered)`
+- `var(--ds-color-button-bg-primary-pressed)`
+- `var(--ds-color-button-bg-primary-selected)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-glass-shadow)`
+- `var(--ds-icon-)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-text-)`
+- `var(--ds-text-family-text)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+- `var(--ds-text-size-text-md)`
+- `var(--ds-text-size-text-sm)`
+- `var(--ds-text-size-text-xs)`
+- `var(--ds-text-weight-medium)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add floating-button` (after `npx sdaia-ui@latest init`), then import `{ FloatingButton }` from `@/components/ui/FloatingButton`.
+- 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/horizontal-tabs.md

@@ -0,0 +1,52 @@
+# Horizontal Tabs
+
+## Metadata
+- Component: Horizontal Tabs
+- Slug: `horizontal-tabs`
+- Category: Actions
+- Install: `npx sdaia-ui@latest add horizontal-tabs`
+- Import: `import { HorizontalTabs } from '@/components/ui/HorizontalTabs'`
+- Installed files: `HorizontalTabs.tsx`, `HorizontalTabs.types.ts`, `HorizontalTabs.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/horizontal-tabs
+
+> **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 horizontal-tabs`. It copies the source into your components folder (`components/ui/HorizontalTabs/`, under `src/` when the project has one); import it as `@/components/ui/HorizontalTabs`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `HorizontalTabItem[]` | — | Tabs to render. |
+| `type?` | `'primary' \| 'neutral' \| 'underline' \| 'shadow' \| 'outline'` | 'primary' | Visual type. |
+| `size?` | `TabSize` | 'md' | Size of every tab in the group. |
+| `value?` | `string` | — | Controlled selected value. |
+| `defaultValue?` | `string` | — | Uncontrolled initial value. |
+| `onValueChange?` | `(value: string) => void` | — | Selection change callback. |
+| `disabled?` | `boolean` | false | Disable the entire tab group. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. Arrow keys follow it (Left/Right swap in RTL). Inherits the ambient direction when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'primary'` \| `'neutral'` \| `'underline'` \| `'shadow'` \| `'outline'` — Container-level type. Determines both the wrapper styling and the
+inner `Tab` variant used for each item.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Arrow keys follow it
+(Left/Right swap in RTL). Inherits the ambient direction 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-emphasis-low)`
+- `var(--ds-color-border-default)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add horizontal-tabs` (after `npx sdaia-ui@latest init`), then import `{ HorizontalTabs }` from `@/components/ui/HorizontalTabs`.
+- 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.