@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/form/otp-input.md

@@ -0,0 +1,83 @@
+# OTP Input
+
+## Metadata
+- Component: OTP Input
+- Slug: `otp-input`
+- Category: Form
+- Install: `npx sdaia-ui@latest add otp-input`
+- Import: `import { OtpInput } from '@/components/ui/OtpInput'`
+- Installed files: `OtpInput.tsx`, `OtpInput.types.ts`, `OtpInput.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/otp-input
+
+> **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 otp-input`. It copies the source into your components folder (`components/ui/OtpInput/`, under `src/` when the project has one); import it as `@/components/ui/OtpInput`. 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. The label, helper and Resend row mirror in RTL; the digit boxes always stay left to right. |
+| `length?` | `OtpInputLength` | 4 | Number of digit boxes (Figma `Length`). |
+| `value?` | `string` | — | Code entered so far (controlled), digits only. |
+| `defaultValue?` | `string` | '' | Initial code (uncontrolled). |
+| `onChange?` | `(value: string) => void` | — | Fired on every change with the digits entered so far. |
+| `onComplete?` | `(value: string) => void` | — | Fired once every box holds a digit, with the full code. |
+| `label?` | `string` | — | Label above the boxes (Figma `Label EN/AR`). Names the group. |
+| `helperText?` | `string` | — | Helper text under the boxes (Figma `Helper` + `Helper Text EN/AR`). |
+| `error?` | `string` | — | Error message (Figma `Error Message EN/AR`). Replaces the helper text, turns the boxes red, sets `aria-invalid` and is announced. Say what went wrong and what to do. |
+| `disabled?` | `boolean` | false | Disables every box and the Resend action (Figma State=Disabled). |
+| `required?` | `boolean` | false | Marks the code as required (`aria-required` on every box). |
+| `autoFocus?` | `boolean` | false | Focus the first empty box on mount. |
+| `name?` | `string` | — | Name of a hidden input that carries the code in a native form submit. Omit it when the form reads `value` itself. |
+| `resendQuestion?` | `string` | — | Question before the Resend action (Figma `Resend Question EN/AR`), e.g. "Didn't get a code?". |
+| `onResend?` | `() => void` | — | Shows the Resend action (Figma `Resend`) as a link-styled button and fires when it is pressed. Pass `resendHref` instead to navigate. |
+| `resendHref?` | `string` | — | Shows the Resend action as a link to this URL. |
+| `resendDisabled?` | `boolean` | false | Disables only the Resend action, e.g. during a cool-down. |
+| `labels?` | `Partial<OtpInputLabels>` | — | Localised built-in strings (digit names, Resend text). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. The label, helper and Resend row mirror in RTL; the digit boxes always stay left to right.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-border-disabled)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-form-field-bg-default)`
+- `var(--ds-color-form-field-border-danger)`
+- `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-field-text-filled)`
+- `var(--ds-color-form-field-text-label)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-family-display)`
+- `var(--ds-text-family-text)`
+- `var(--ds-text-leading-line-heights-display-xs)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add otp-input` (after `npx sdaia-ui@latest init`), then import `{ OtpInput }` from `@/components/ui/OtpInput`.
+- 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/form/password-input.md

@@ -0,0 +1,49 @@
+# Password Input
+
+## Metadata
+- Component: Password Input
+- Slug: `password-input`
+- Category: Form
+- Install: `npx sdaia-ui@latest add password-input`
+- Import: `import { PasswordInput } from '@/components/ui/PasswordInput'`
+- Installed files: `PasswordInput.tsx`, `PasswordInput.types.ts`, `PasswordInput.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/password-input
+
+> **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 password-input`. It copies the source into your components folder (`components/ui/PasswordInput/`, under `src/` when the project has one); import it as `@/components/ui/PasswordInput`. 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 |
+| --- | --- | --- | --- |
+| `visibility?` | `'hidden' \| 'shown'` | — | Whether the value is masked or readable (Figma `Visibility`). Controlled when set; pair it with `onVisibilityChange`. |
+| `defaultVisibility?` | `'hidden' \| 'shown'` | 'hidden' | Initial visibility when uncontrolled. Keep the value hidden by default: the user reveals it on demand. |
+| `onVisibilityChange?` | `(visibility: PasswordInputVisibility) => void` | — | Fired when the eye toggle is pressed, with the new visibility. |
+| `autoComplete?` | `string` | 'current-password' | Native `autocomplete`. Use `'current-password'` on sign-in forms and `'new-password'` when the user creates or changes a password. |
+| `labels?` | `Partial<PasswordInputLabels>` | — | Localised built-in strings (the eye toggle's accessible name). |
+
+## Options (allowed values)
+- `visibility`: `'hidden'` \| `'shown'` — Whether the password is masked (`'hidden'`) or readable (`'shown'`).
+Maps to the Figma `Visibility` axis (Hidden / Shown).
+- `defaultVisibility`: `'hidden'` \| `'shown'` — Whether the password is masked (`'hidden'`) or readable (`'shown'`).
+Maps to the Figma `Visibility` axis (Hidden / Shown).
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add password-input` (after `npx sdaia-ui@latest init`), then import `{ PasswordInput }` from `@/components/ui/PasswordInput`.
+- 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/form/range-slider.md

@@ -0,0 +1,71 @@
+# Range Slider
+
+## Metadata
+- Component: Range Slider
+- Slug: `range-slider`
+- Category: Form
+- Install: `npx sdaia-ui@latest add range-slider`
+- Import: `import { RangeSlider } from '@/components/ui/RangeSlider'`
+- Installed files: `RangeSlider.tsx`, `RangeSlider.types.ts`, `RangeSlider.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/range-slider
+
+> **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 range-slider`. It copies the source into your components folder (`components/ui/RangeSlider/`, under `src/` when the project has one); import it as `@/components/ui/RangeSlider`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value?` | `RangeSliderValue` | — | Current [start, end] value. Controlled when provided. |
+| `defaultValue?` | `RangeSliderValue` | [20, 80] | Initial [start, end] for uncontrolled usage. Default: [20, 80] |
+| `onChange?` | `(value: RangeSliderValue) => void` | — | Called with new [start, end] when either thumb moves |
+| `min?` | `number` | 0 | Minimum bound. Default: 0 |
+| `max?` | `number` | 100 | Maximum bound. Default: 100 |
+| `step?` | `number` | 1 | Step increment. Default: 1 |
+| `label?` | `'inline' \| 'bottom' \| 'top-floating' \| 'bottom-floating' \| 'none'` | 'inline' | Label position variant. Default: 'inline' |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the slider. Unset inherits from the closest `dir` ancestor. In RTL the track fills from the right and the arrow keys follow the visual direction. |
+| `leadingIcon?` | `boolean` | false | Show info icon at the leading end |
+| `trailingIcon?` | `boolean` | false | Show info icon at the trailing end |
+| `disabled?` | `boolean` | false | Disabled state |
+| `formatValue?` | `(value: number) => string` | — | Custom formatter for displayed values (min/max labels, bubbles, and the thumbs' `aria-valuetext`). Default: v => `${v}%` |
+| `labels?` | `Partial<RangeSliderLabels>` | — | Localised built-in strings (thumb names). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `dir`.
+
+## Options (allowed values)
+- `label`: `'inline'` \| `'bottom'` \| `'top-floating'` \| `'bottom-floating'` \| `'none'` — Label position variant. Default: 'inline'
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the slider. Unset inherits from the closest `dir` ancestor.
+In RTL the track fills from the right and the arrow keys follow the visual direction.
+
+## Deprecated props
+Do not use in new code:
+- `direction`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-border-on-default)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-display)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xs)`
+- `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 range-slider` (after `npx sdaia-ui@latest init`), then import `{ RangeSlider }` from `@/components/ui/RangeSlider`.
+- 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/form/rich-text-editor.md

@@ -0,0 +1,106 @@
+# Rich Text Editor
+
+## Metadata
+- Component: Rich Text Editor
+- Slug: `rich-text-editor`
+- Category: Form
+- Install: `npx sdaia-ui@latest add rich-text-editor`
+- Import: `import { RichTextEditor } from '@/components/ui/RichTextEditor'`
+- Installed files: `RichTextEditor.tsx`, `RichTextEditor.types.ts`, `RichTextEditor.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/rich-text-editor
+
+> **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 rich-text-editor`. It copies the source into your components folder (`components/ui/RichTextEditor/`, under `src/` when the project has one); import it as `@/components/ui/RichTextEditor`. 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?` | `'default' \| 'text-selected' \| 'input'` | 'default' | Visual type. - `default` (default) — full formatting toolbar + content-editable area - `text-selected` — compact floating toolbar shown when text is selected - `input` — self-contained input field with bottom quick-action bar and optional expanded toolbar |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the editor (toolbar order, panels, placeholder). Unset inherits from the document / nearest `dir` ancestor. |
+| `labels?` | `Partial<RichTextEditorLabels>` | — | Localised built-in strings (aria labels, menu options, placeholders…). |
+| `mobile?` | `boolean` | false | Render in mobile layout. - `default` type: collapses to a 2-row toolbar (undo/redo + selectors on row 1, collapsed format groups on row 2). |
+| `expand?` | `boolean` | false | Show expanded formatting toolbar above the content area. Only applies when `type="input"`. |
+| `isBold?` | `boolean` | false | Whether the Bold action is currently active (toggled). |
+| `isItalic?` | `boolean` | false | Whether the Italic action is currently active (toggled). |
+| `isUnderline?` | `boolean` | false | Whether the Underline action is currently active (toggled). |
+| `alignment?` | `'left' \| 'center' \| 'right'` | — | Currently active text alignment. |
+| `textStyle?` | `string` | — | Initially selected text style: a built-in option label (English or the localised `labels` value, e.g. `"Heading 1"`) or its tag (`"p"`, `"h1"`…). |
+| `textStyleOptions?` | `string[]` | — | Available text style options. |
+| `fontSize?` | `string` | — | Initially selected font size label (e.g. `"16"`). |
+| `fontSizeOptions?` | `string[]` | — | Available font size options. |
+| `onTextStyleChange?` | `(value: string) => void` | — | Called with the (localised) option label when the user selects a text style. |
+| `onFontSizeChange?` | `(value: string) => void` | — | Called when the user selects a font size option. |
+| `onUndo?` | `() => void` | — | Called when the Undo button is pressed. |
+| `onRedo?` | `() => void` | — | Called when the Redo button is pressed. |
+| `onBold?` | `() => void` | — | Called when the Bold button is pressed. |
+| `onItalic?` | `() => void` | — | Called when the Italic button is pressed. |
+| `onUnderline?` | `() => void` | — | Called when the Underline button is pressed. |
+| `onAlign?` | `(alignment: TextAlignment) => void` | — | Called when an alignment button is pressed. |
+| `onColor?` | `() => void` | — | Called whenever a colour from the colour picker is applied. |
+| `onLink?` | `() => void` | — | Called when the Link button is pressed (`text-selected`) or a link is inserted. |
+| `onImage?` | `() => void` | — | Called when the Image button is pressed. |
+| `onAI?` | `() => void` | — | Called when the AI button is pressed. |
+| `value?` | `string` | — | Initial HTML content of the editable region (`default` and `input` types). Read once on mount; listen to `onChange` for later edits. |
+| `placeholder?` | `string` | 'Type here…' (`default` type) / 'You can write here…' (`input` type) | Placeholder text of the editable region. Wins over `labels.placeholder` / `labels.inputPlaceholder`. |
+| `onChange?` | `(value: string) => void` | — | Called on every edit with the editor's new HTML. |
+| `onAddContent?` | `() => void` | — | Called when the `+` (add content) button is pressed. |
+| `onFormatText?` | `() => void` | — | Called when a text style is applied from the Aa (format text) menu. |
+| `onEmoji?` | `() => void` | — | Called when the emoji button is pressed. |
+| `onMention?` | `() => void` | — | Called when the `@` mention button is pressed. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `dir`.
+
+## Options (allowed values)
+- `type`: `'default'` \| `'text-selected'` \| `'input'` — Which visual mode the component renders in
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the editor (toolbar order, panels, placeholder).
+Unset inherits from the document / nearest `dir` ancestor.
+- `alignment`: `'left'` \| `'center'` \| `'right'` — Text alignment option
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-form-field-bg-default)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-form-field-border-hovered)`
+- `var(--ds-color-form-field-text-filled)`
+- `var(--ds-color-form-field-text-placeholder)`
+- `var(--ds-color-form-option-bg-hover)`
+- `var(--ds-color-form-option-bg-pressed)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-primitive-neutral-400)`
+- `var(--ds-color-text-default)`
+- `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-xs)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add rich-text-editor` (after `npx sdaia-ui@latest init`), then import `{ RichTextEditor }` from `@/components/ui/RichTextEditor`.
+- 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/form/select.md

@@ -0,0 +1,113 @@
+# Select
+
+## Metadata
+- Component: Select
+- Slug: `select`
+- Category: Form
+- Install: `npx sdaia-ui@latest add select`
+- Import: `import { Select } from '@/components/ui/Select'`
+- Installed files: `Select.tsx`, `Select.types.ts`, `Select.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/select
+
+> **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 select`. It copies the source into your components folder (`components/ui/Select/`, under `src/` when the project has one); import it as `@/components/ui/Select`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Description
+Accessibility: the trigger is a WAI-ARIA `role="combobox"` labelled by `label`
+(via `aria-labelledby`) and described by helper / error text. `aria-label`,
+`aria-labelledby` and `aria-describedby` passed here are forwarded to the
+combobox (not the wrapper) — use `aria-label` when there is no visible label.
+All other HTML attributes go to the outer wrapper `<div>`.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the field. Leave unset to inherit it from an ancestor. |
+| `size?` | `'large' \| 'medium'` | 'large' | Trigger size. - `'large'`  — 40 px inner height, `py-spacing-md` padding - `'medium'` — 36 px inner height, `py-spacing-sm` padding |
+| `leadingItem?` | `'none' \| 'icon' \| 'dot' \| 'checkbox' \| 'avatar'` | 'none' | Figma Leading Item — element before the value in trigger and menu items. |
+| `options?` | `SelectOption[]` | [] | List of selectable options |
+| `value?` | `string \| string[]` | — | Controlled selected value(s). - Single: `string` - Multi (`multiple={true}`): `string[]` |
+| `onChange?` | `(value: string \| string[]) => void` | — | Called when the selection changes |
+| `multiple?` | `boolean` | false | Enable multi-select mode. When true, `value` should be `string[]`, selected items are shown as Chips in the trigger, and the dropdown stays open after each selection. |
+| `placeholder?` | `string` | 'Select option' | Placeholder text shown when nothing is selected. Wins over `labels.placeholder`. |
+| `label?` | `string` | — | Label rendered above the trigger |
+| `labelHelp?` | `ReactNode` | — | Content rendered right after the label text, outside the `<label>` element (e.g. a `HelpIcon`), so its own accessible name is not part of the field's. |
+| `required?` | `boolean` | false | Show the required asterisk next to the label and set `aria-required="true"` |
+| `helperText?` | `string` | — | Helper text shown below the trigger |
+| `error?` | `string` | — | Error message — shown in red below the trigger. Takes precedence over `helperText`, applies a red border, sets `aria-invalid="true"` and is announced when it appears. |
+| `disabled?` | `boolean` | false | Disables the entire field |
+| `leadingIcon?` | `ReactNode` | — | Icon node displayed when `leading='icon'`. Rendered at 20 × 20 px in both the trigger and the dropdown items. |
+| `avatarSrc?` | `string` | the default `SaudiAvatar` from sdaia-assets | Default avatar image URL used in the trigger when `leading='avatar'` and no option is selected (or the selected option has no `avatar`). |
+| `id?` | `string` | — | HTML id for the combobox trigger (the label, listbox and options derive their ids from it) |
+| `labels?` | `Partial<SelectLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the field. Leave unset to inherit it from an ancestor.
+- `size`: `'large'` \| `'medium'` — Height / padding variant for the trigger
+- `leadingItem`: `'none'` \| `'icon'` \| `'dot'` \| `'checkbox'` \| `'avatar'` — Figma Leading Item variant — what appears before the selected value in the trigger
+and in each dropdown option.
+- `'none'`     — Leading Item=None
+- `'icon'`     — Leading Item=Icon; pass `leadingIcon`
+- `'dot'`      — Leading Item=Dot (status dot)
+- `'checkbox'` — Leading Item=Checkbox (multi-select; checkboxes in list)
+- `'avatar'`   — Leading Item=Avatar; per-option `avatar` or `avatarSrc`
+
+## Deprecated props
+Do not use in new code:
+- `leading` — Same as `leadingItem` (legacy name); `leadingItem` wins when both are set.
+
+## Accessibility
+Built in (SDAIA review item A3) — verified by `tests/a11y/keyboard/select.spec.ts` in the design system's test suite:
+- The trigger is a WAI-ARIA select-only `combobox`, named by the visible `label`.
+- `Enter` opens the list, arrow keys move the active option, `Enter` selects it.
+- `Escape` closes the list without changing the value.
+
+You must:
+- Always pass `label` (use a visually hidden label only when the design has none).
+
+- 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-muted)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-form-field-bg-default)`
+- `var(--ds-color-form-field-border-danger)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-form-field-border-hovered)`
+- `var(--ds-color-form-field-text-filled)`
+- `var(--ds-color-form-field-text-helper)`
+- `var(--ds-color-form-field-text-label)`
+- `var(--ds-color-form-field-text-placeholder)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-icon-default-disabled)`
+- `var(--ds-color-primitive-neutral-400)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-family-text)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add select` (after `npx sdaia-ui@latest init`), then import `{ Select }` from `@/components/ui/Select`.
+- 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/form/signature.md

@@ -0,0 +1,83 @@
+# Signature
+
+## Metadata
+- Component: Signature
+- Slug: `signature`
+- Category: Form
+- Install: `npx sdaia-ui@latest add signature`
+- Import: `import { Signature } from '@/components/ui/Signature'`
+- Installed files: `Signature.tsx`, `Signature.types.ts`, `Signature.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/signature
+
+> **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 signature`. It copies the source into your components folder (`components/ui/Signature/`, under `src/` when the project has one); import it as `@/components/ui/Signature`. 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?` | `'draw' \| 'text' \| 'upload'` | — | Controlled active tab. Pair with `onTypeChange`. When omitted use `defaultType`. |
+| `defaultType?` | `'draw' \| 'text' \| 'upload'` | 'draw' | Uncontrolled initial tab. |
+| `onTypeChange?` | `(type: SignatureType) => void` | — | Called when the user switches tabs. |
+| `helperText?` | `string` | — | Helper / disclaimer text shown below the signature area (e.g. "By signing this document, I certify…"). Nothing is rendered when omitted. It also describes the accept button (`aria-describedby`). |
+| `showHelperText?` | `boolean` | true | Whether the helper text is visible. |
+| `showOptions?` | `boolean` | true | Whether the draw / text options toolbar (color, size, background) is shown. |
+| `showTabs?` | `boolean` | true | Whether the tabs row is shown. |
+| `cancelLabel?` | `string` | — | Label for the secondary (cancel) action. Wins over `labels.cancel`. |
+| `acceptLabel?` | `string` | — | Label for the primary (accept) action. Wins over `labels.accept`. |
+| `onCancel?` | `() => void` | — | Called when Cancel is clicked. |
+| `onAccept?` | `(data?: string \| File) => void` | — | Called when Accept and Sign is clicked. Receives the captured data: draw   → base64 PNG string (transparent background, device-pixel resolution). Strokes drawn with the theme-default ink are exported in black so the image stays readable on a white document even when signed in dark mode; strokes in a picked colour keep that colour. text   → the typed signature string upload → the File object |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the card. Unset inherits from the document. |
+| `maxFileSize?` | `number` | DEFAULT_MAX_FILE_SIZE | Largest file (bytes) the upload tab accepts. A larger file is rejected and `labels.fileTooLarge` is shown; `onAccept` never receives it. |
+| `labels?` | `Partial<SignatureLabels>` | — | Localised built-in strings. |
+| `className?` | `string` | — | — |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `dir`.
+
+## Options (allowed values)
+- `type`: `'draw'` \| `'text'` \| `'upload'` — Which signature capture method is active.
+Maps to the Figma "Type" property.
+- `defaultType`: `'draw'` \| `'text'` \| `'upload'` — Which signature capture method is active.
+Maps to the Figma "Type" property.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the card. 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-bg-emphasis-low)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-form-field-text-filled)`
+- `var(--ds-color-form-field-text-helper)`
+- `var(--ds-color-form-field-text-placeholder)`
+- `var(--ds-color-form-option-bg-hover)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-primitive-neutral-400)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-6xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `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 signature` (after `npx sdaia-ui@latest init`), then import `{ Signature }` from `@/components/ui/Signature`.
+- 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/form/slider.md

@@ -0,0 +1,66 @@
+# Slider
+
+## Metadata
+- Component: Slider
+- Slug: `slider`
+- Category: Form
+- Install: `npx sdaia-ui@latest add slider`
+- Import: `import { Slider } from '@/components/ui/Slider'`
+- Installed files: `Slider.tsx`, `Slider.types.ts`, `Slider.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/slider
+
+> **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 slider`. It copies the source into your components folder (`components/ui/Slider/`, under `src/` when the project has one); import it as `@/components/ui/Slider`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value?` | `number` | — | Current value (0–100). Controlled when provided. |
+| `defaultValue?` | `number` | 50 | Initial value for uncontrolled usage (0–100). Default: 50 |
+| `onChange?` | `(value: number) => void` | — | Called with the new value when the user moves the thumb |
+| `label?` | `'inline' \| 'bottom' \| 'top-floating' \| 'bottom-floating' \| 'none'` | 'inline' | Label position variant |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the slider. Unset inherits from the closest `dir` ancestor. |
+| `leadingIcon?` | `boolean` | false | Show info icon at the leading end |
+| `trailingIcon?` | `boolean` | false | Show info icon at the trailing end |
+| `formatValue?` | `(value: number) => string` | — | Custom label formatter for the current value. Also used for the input's `aria-valuetext` and the floating bubble. When provided in `inline` mode, both the leading and trailing label slots display the formatted value instead of the raw "0%" / "value%" defaults. E.g. `(v) => v < 50 ? 'Small' : 'Medium'` |
+| `disabled?` | `boolean` | false | Disabled state |
+| `labels?` | `Partial<SliderLabels>` | — | Localised built-in strings (input name, min / max labels). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `dir`.
+
+## Options (allowed values)
+- `label`: `'inline'` \| `'bottom'` \| `'top-floating'` \| `'bottom-floating'` \| `'none'` — Label position variant
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the slider. Unset inherits from the closest `dir` ancestor.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-low)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-border-on-default)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-display)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xs)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-size-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add slider` (after `npx sdaia-ui@latest init`), then import `{ Slider }` from `@/components/ui/Slider`.
+- 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.