@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/form/text-area.md

@@ -0,0 +1,90 @@
+# Text Area
+
+## Metadata
+- Component: Text Area
+- Slug: `text-area`
+- Category: Form
+- Install: `npx sdaia-ui@latest add text-area`
+- Import: `import { TextArea } from '@/components/ui/TextArea'`
+- Installed files: `TextArea.tsx`, `TextArea.types.ts`, `TextArea.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/textarea
+
+> **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 text-area`. It copies the source into your components folder (`components/ui/TextArea/`, under `src/` when the project has one); import it as `@/components/ui/TextArea`. 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 `<label>` is linked to the textarea via `htmlFor` / `id`
+(the passed `id`, or an auto-generated one). Helper / error text is linked via
+`aria-describedby`; any `aria-describedby` you pass (e.g. the id of a character
+counter) is kept and merged in front of it.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction — applied to the root wrapper. Unset inherits from the page. |
+| `label?` | `ReactNode` | — | Label displayed above the textarea. When omitted, pass `aria-label` / `aria-labelledby`. |
+| `labelHelp?` | `ReactNode` | — | Extra content rendered right after the label, e.g. a `<HelpIcon>`. It sits in the label row but OUTSIDE the `<label>` element, so its own accessible name (e.g. "Help") is not added to the field's name. |
+| `validationBehavior?` | `'native' \| 'aria'` | 'native' | How `required` is applied to the native textarea. - `'native'`: the native `required` attribute (browser validation bubble on submit). - `'aria'`: `aria-required="true"` only — no browser bubble; validate in your own code. The visual `*` after the label shows in both modes. |
+| `helperText?` | `string` | — | Helper text displayed below the textarea — linked via `aria-describedby` |
+| `error?` | `string` | — | Error message — replaces helperText, switches to destructive style, sets `aria-invalid="true"` and is announced when it appears. |
+| `destructive?` | `boolean` | false | Applies destructive (red) border and helper text styling; also sets `aria-invalid="true"` |
+| `showButton?` | `boolean` | false | Shows a button below the textarea (rendered only when `buttonLabel` is set) |
+| `buttonLabel?` | `string` | — | Label of the button shown by `showButton`. No default — pass your own (localised) text. |
+| `onButtonClick?` | `() => void` | — | Callback when the button is clicked |
+| `fullWidth?` | `boolean` | false | Makes the component take full width |
+
+Also accepts standard `<textarea>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root wrapper. Unset inherits from the page.
+- `validationBehavior`: `'native'` \| `'aria'` — Native `required` handling — see `TextAreaProps.validationBehavior`.
+
+## Accessibility
+Built in (SDAIA review item A2) — verified by `tests/a11y/keyboard/text-fields.spec.ts` in the design system's test suite:
+- The textarea is named by its visible `label`.
+- The destructive (error) state sets `aria-invalid` and keeps the helper text described.
+
+You must:
+- Always pass `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-muted)`
+- `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-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-family-text)`
+- `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 text-area` (after `npx sdaia-ui@latest init`), then import `{ TextArea }` from `@/components/ui/TextArea`.
+- 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/form/text-input.md

@@ -0,0 +1,132 @@
+# Text Input
+
+## Metadata
+- Component: Text Input
+- Slug: `text-input`
+- Category: Form
+- Install: `npx sdaia-ui@latest add text-input`
+- Import: `import { TextInput } from '@/components/ui/TextInput'`
+- Installed files: `TextInput.tsx`, `TextInput.types.ts`, `TextInput.variants.ts`, `TextInputTag.tsx`, `TextInputTag.types.ts`, `index.ts`, `resolveTextInputSize.ts`
+- Docs: https://ds.nacew.com/components/text-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 text-input`. It copies the source into your components folder (`components/ui/TextInput/`, under `src/` when the project has one); import it as `@/components/ui/TextInput`. 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 wrapper. Unset inherits from the page. |
+| `label?` | `string` | — | Label text displayed above the input. Rendered as a `<label>` linked to the input via `htmlFor` / `id` (the passed `id`, or an auto-generated one). When omitted, pass `aria-label` or `aria-labelledby` so the field still has a name. |
+| `labelHelp?` | `ReactNode` | — | Extra content rendered right after the label text, e.g. a `<HelpIcon>`. It sits in the label row but OUTSIDE the `<label>` element, so its own accessible name (e.g. "Help") is not added to the field's name. |
+| `validationBehavior?` | `'native' \| 'aria'` | 'native' | How `required` is applied to the native input. - `'native'`: the native `required` attribute (browser validation bubble on submit). - `'aria'`: `aria-required="true"` only — no browser bubble; validate in your own code. The visual `*` after the label shows in both modes. |
+| `helperText?` | `string` | — | Helper text displayed below the input — linked via `aria-describedby` |
+| `error?` | `string` | — | Error message — replaces helperText, turns the input red, sets `aria-invalid="true"` and is linked via `aria-describedby`. |
+| `invalid?` | `boolean` | false | Shows the error styling and sets `aria-invalid="true"` WITHOUT rendering a message. Use it when the message lives elsewhere, e.g. one shared error under a group of fields that each point to it with `aria-describedby`. `error` implies it. |
+| `size?` | `'medium' \| 'large'` | — | Trigger size (Figma Size). Unset: responsive — medium below the system tablet breakpoint (768px), large from 768px. |
+| `variant?` | `'default' \| 'search-box' \| 'leading-dropdown' \| 'trailing-dropdown' \| 'leading-text' \| 'trailing-button' \| 'input-button'` | 'default' | Structural variant of the input — determines layout and built-in adornments |
+| `prefix?` | `ReactNode` | — | Content rendered before the input field (icon, text, dropdown) |
+| `suffix?` | `ReactNode` | — | Content rendered after the input field (icon, button, text) |
+| `prefixBordered?` | `boolean` | false | Whether the prefix has a visual separator border on its end edge |
+| `suffixBordered?` | `boolean` | false | Whether the suffix has a visual separator border on its start edge |
+| `clearable?` | `boolean` | false | Shows a clear button when the input has a value |
+| `onClear?` | `() => void` | — | Callback fired when the clear button is clicked |
+| `tags?` | `TagItem[]` | — | Tag chips rendered inside the input container (for multi-value variant) |
+| `onTagRemove?` | `(id: string) => void` | — | Callback fired when a tag's remove button is clicked |
+| `labels?` | `Partial<TextInputLabels>` | — | Localised built-in strings (clear button, tag remove buttons). |
+| `fullWidth?` | `boolean` | false | Makes the input take the full width of its container |
+| `leadingDropdownLabel?` | `string` | — | leading-dropdown: label text shown in the left dropdown panel |
+| `onLeadingDropdownClick?` | `() => void` | — | leading-dropdown: callback when left dropdown panel is clicked |
+| `leadingDropdownAriaLabel?` | `string` | — | leading-dropdown: accessible name for the dropdown panel button (e.g. "Country code, +966") |
+| `trailingDropdownLabel?` | `string` | — | trailing-dropdown: label text shown in the right dropdown panel |
+| `onTrailingDropdownClick?` | `() => void` | — | trailing-dropdown: callback when right dropdown panel is clicked |
+| `trailingDropdownAriaLabel?` | `string` | — | trailing-dropdown: accessible name for the dropdown panel button (e.g. "Currency, SAR") |
+| `leadingText?` | `string` | — | leading-text: static text shown in the left text panel (e.g. "http://") |
+| `trailingButtonLabel?` | `string` | — | trailing-button: label for the attached right action button (e.g. "Copy") |
+| `trailingButtonIcon?` | `ReactNode` | — | trailing-button: icon rendered inside the attached right action button |
+| `onTrailingButtonClick?` | `() => void` | — | trailing-button: callback when the attached right action button is clicked |
+| `trailingButtonAriaLabel?` | `string` | — | trailing-button: accessible name for the attached action button. Required when the button shows only `trailingButtonIcon` (no `trailingButtonLabel`). |
+| `actionButtonLabel?` | `string` | — | input-button: label for the detached primary action button |
+| `onActionButtonClick?` | `() => void` | — | input-button: callback when the detached primary action button is clicked |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`, `prefix`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root wrapper. Unset inherits from the page.
+- `validationBehavior`: `'native'` \| `'aria'` — Native `required` handling — see `TextInputProps.validationBehavior`.
+- `size`: `'medium'` \| `'large'` — Figma Size: Medium | Large only.
+- `variant`: `'default'` \| `'search-box'` \| `'leading-dropdown'` \| `'trailing-dropdown'` \| `'leading-text'` \| `'trailing-button'` \| `'input-button'` — Structural variant of the input — maps to Figma component set "Type" property.
+Named `variant` in code to avoid conflict with the native HTML `type` attribute.
+- default: plain input with optional prefix/suffix slots
+- search-box: leading search icon + trailing mic icon
+- leading-dropdown: attached left panel with a selectable label + chevron
+- trailing-dropdown: attached right panel with a selectable label + chevron
+- leading-text: attached left static text panel (e.g. "http://")
+- trailing-button: attached right action button (e.g. "Copy")
+- input-button: standalone input + a separate detached primary action Button
+
+## Deprecated props
+Do not use in new code:
+- `clearButtonLabel` — Accessible name for the icon-only clear button. Wins over `labels.clear`.
+- `tagRemoveLabel` — Builds the accessible name of each tag's remove button. Wins over `labels.removeTag`.
+
+## Accessibility
+Built in (SDAIA review item A1) — verified by `tests/a11y/keyboard/text-fields.spec.ts` in the design system's test suite:
+- The input is named by its visible `label` (`<label for>`).
+- Error state sets `aria-invalid` and describes the field with the error text (`aria-describedby`).
+- Helper text is linked with `aria-describedby`.
+- Icon-only inline buttons (clear, show password) have accessible names.
+
+You must:
+- Always pass `label`.
+
+- 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-muted)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-disabled)`
+- `var(--ds-color-border-muted)`
+- `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)`
+- `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-default)`
+- `var(--ds-color-text-disabled)`
+- `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-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-family-text)`
+- `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 text-input` (after `npx sdaia-ui@latest init`), then import `{ TextInput }` from `@/components/ui/TextInput`.
+- 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/form/time-input.md

@@ -0,0 +1,44 @@
+# Time Input
+
+## Metadata
+- Component: Time Input
+- Slug: `time-input`
+- Category: Form
+- Install: `npx sdaia-ui@latest add time-input`
+- Import: `import { TimeInput } from '@/components/ui/TimeInput'`
+- Installed files: `TimeInput.tsx`, `TimeInput.types.ts`, `TimeInput.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/time-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 time-input`. It copies the source into your components folder (`components/ui/TimeInput/`, under `src/` when the project has one); import it as `@/components/ui/TimeInput`. 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?` | `TimeValue \| null` | — | Selected time (controlled). The field shows it formatted for `format` (`09:30 AM` / `14:30`). `null` = empty. While the user types, the text is kept as typed and `onChange` reports the parsed time. |
+| `defaultValue?` | `TimeValue \| null` | null | Initial time (uncontrolled). |
+| `defaultInputValue?` | `string` | — | Initial field text, used instead of `value` / `defaultValue` on the first render — e.g. to restore a draft the user typed (which may not be a valid time yet). |
+| `onChange?` | `(time: TimeValue \| null, text: string) => void` | — | Fired when the user types or applies a time from the picker. `time` is the parsed value — `null` when the field is empty or the text is not a valid time (e.g. `25:00`), so you can show an error — and `text` is the field's text. |
+| `format?` | `TimeFormat` | '12-hour' | Clock format of the field text and of the picker (Time Picker `Format`). |
+| `minuteStep?` | `number` | 5 | Minutes between options in the picker's minute column. |
+| `pickerTitle?` | `string` | — | Title in the picker header (Time Picker `Title`). Omit to hide it. |
+| `pickerFooter?` | `boolean` | true | Show the picker's Cancel / Apply footer (Time Picker `Footer`). Without it, picking applies at once. |
+| `open?` | `boolean` | — | Whether the picker is open (controlled). |
+| `defaultOpen?` | `boolean` | false | Initial open state (uncontrolled). |
+| `onOpenChange?` | `(open: boolean) => void` | — | Fired when the picker opens or closes. |
+| `labels?` | `Partial<TimeInputLabels>` | — | Localised built-in strings (picker columns, AM / PM, buttons). |
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add time-input` (after `npx sdaia-ui@latest init`), then import `{ TimeInput }` from `@/components/ui/TimeInput`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- 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/time-picker.md

@@ -0,0 +1,73 @@
+# Time Picker
+
+## Metadata
+- Component: Time Picker
+- Slug: `time-picker`
+- Category: Form
+- Install: `npx sdaia-ui@latest add time-picker`
+- Import: `import { TimePicker } from '@/components/ui/TimePicker'`
+- Installed files: `TimePicker.tsx`, `TimePicker.types.ts`, `TimePicker.variants.ts`, `index.ts`, `time.ts`
+- Docs: https://ds.nacew.com/components/time-picker
+
+> **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 time-picker`. It copies the source into your components folder (`components/ui/TimePicker/`, under `src/` when the project has one); import it as `@/components/ui/TimePicker`. 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. The columns mirror in RTL; digits stay Latin. Unset inherits. |
+| `format?` | `'12-hour' \| '24-hour'` | '12-hour' | Clock format (Figma `Format`). |
+| `value?` | `TimeValue \| null` | — | Selected time (controlled). `null` means nothing is selected yet. |
+| `defaultValue?` | `TimeValue \| null` | null | Initial selected time (uncontrolled). |
+| `onChange?` | `(value: TimeValue) => void` | — | Fired on every selection in a column, with the complete time. |
+| `onApply?` | `(value: TimeValue) => void` | — | Fired by the Apply button and by Enter on an option, with the selected time. |
+| `onCancel?` | `() => void` | — | Fired by the Cancel button and by Escape inside the picker. In a popup, close it here and move focus back to the field that opened it. |
+| `title?` | `string` | — | Header title (Figma `Title` + `Title EN/AR`), e.g. "Select time". Omit to hide it in tight layouts; the selected time stays in the header. |
+| `footer?` | `boolean` | true | Show the Cancel / Apply footer (Figma `Footer`). Without it, every selection applies at once through `onChange`. |
+| `minuteStep?` | `number` | 5 | Minutes between options in the minute column. |
+| `autoFocus?` | `boolean` | false | Move focus to the selected hour when the picker mounts (e.g. opened from the keyboard). |
+| `labels?` | `Partial<TimePickerLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `title`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction — applied to the root. The columns mirror in RTL; digits stay Latin. Unset inherits.
+- `format`: `'12-hour'` \| `'24-hour'` — Clock format — Figma `Format`.
+- `'12-hour'`: hour (01–12), minute and AM / PM columns.
+- `'24-hour'`: hour (00–23) and minute columns. Use it on operational,
+  audit and reporting screens.
+
+## 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-raised)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-form-option-bg-hover)`
+- `var(--ds-color-text-brand)`
+- `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-radius-xs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-family-text)`
+- `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 time-picker` (after `npx sdaia-ui@latest init`), then import `{ TimePicker }` from `@/components/ui/TimePicker`.
+- 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/foundations/accessibility.md

@@ -0,0 +1,97 @@
+# SDAIA Accessibility Guide
+
+Mirrors the docs site's Accessibility page (https://ds.nacew.com/foundations/accessibility). SDAIA UI targets **WCAG 2.1 level AA**. The components handle roles, keyboard support, focus and labels; a page is only accessible when its content and the way components are combined are accessible too.
+
+Everything under "What the components do for you" is checked by the design system's own test suite: every component demo is scanned with axe in the light and dark themes and in right-to-left, and keyboard tests (`tests/a11y/keyboard/*.spec.ts`) cover Select, Modal, Date Picker, Switch and the text fields. `get_component_docs` shows the verified behaviour of each of these components and the spec that checks it.
+
+## What the components do for you
+
+| Component | Built-in behaviour |
+| --- | --- |
+| Text Input, Text Area | The label is linked to the field. Helper and error text are linked with `aria-describedby`. Errors set `aria-invalid` and are announced. The required asterisk is hidden from screen readers; the field itself is marked required. |
+| Select | WAI-ARIA select-only combobox with a listbox. Arrow keys, Home, End, Page Up and Page Down move through options; Enter and Space select; Escape closes without changing the value; typing jumps to a matching option. In multi-select, each chip has a named remove button. |
+| Modal | `role="dialog"` with `aria-modal`, named by its `title`. Focus moves into the dialog, Tab and Shift+Tab stay inside it, Escape closes it (`closeOnEscape`, default `true`) and focus returns to the element that opened it. The page behind does not scroll. |
+| Date Picker | The month is a grid (`grid` → `row` → `gridcell`) and a single Tab stop. Arrow keys move by day and week, Home and End go to the start and end of the week, Page Up and Page Down change the month (with Shift, the year). Today is marked with `aria-current`, and month changes are announced. Arabic locale gives Arabic month names and built-in strings. |
+| Checkbox, Radio Button, Switch | Native inputs, so they work with the keyboard and with forms. Switch uses `role="switch"` and its off track meets 3:1 contrast. A click on the box, circle or track works even without a visible label. |
+| Progress Bar, Progress Circle, File Uploader | `role="progressbar"` with the current value. File Uploader names each progress bar with the file name and status. |
+| Chip, Filtration, Help Icon | No nested interactive controls. The help trigger has a name (default "Help") and its tooltip closes with Escape. |
+| DgaIcon | Hidden from screen readers unless you give it a `title`. |
+
+## What you still need to do
+
+- Give every field a visible `label`. A placeholder is not a label.
+- Give icon-only buttons an `aria-label`. Button does not add one for you.
+- Give Progress Bar and Progress Circle a name with `aria-label` or `aria-labelledby` when there is no visible label next to them (Progress Bar's `label` prop only sets where the percentage is shown).
+- Give every Modal a `title`, even a short one, so the dialog has a name.
+- Use one `h1` per page and keep heading levels in order.
+- Write meaningful link and button text, and alternative text for images.
+- Pass `labels` to translate the built-in names of buttons and regions. Many components have a `labels` prop (for example Select, Date Picker, File Uploader, Table, the media players and the charts). Without it, those names are in English (Date Picker and Pagination switch to Arabic by themselves for an Arabic locale).
+
+```tsx
+<TextInput
+  label="National ID"
+  helperText="10 digits, starting with 1 or 2"
+  error={idError}            // linked with aria-describedby, sets aria-invalid
+  required                   // native required by default
+  validationBehavior="aria"  // or: announce required without blocking submit
+/>
+```
+
+## Colour contrast
+
+| Content | Minimum contrast |
+| --- | --- |
+| Body text and labels | 4.5:1 |
+| Large text (24px, or 18.66px bold, and up) | 3:1 |
+| Icons, input borders, focus rings and other UI parts you need to see | 3:1 |
+| Disabled controls and decorative elements | No minimum, but don't hide information in them |
+
+- Use the semantic colour tokens (`text-*`, `bg-*`, `border-*`; `get_tokens`). They are tuned to meet these ratios in the light and dark themes and in every brand.
+- Never hardcode hex colours; custom values bypass the tested pairings.
+- Don't use colour alone to show a state. Errors also have an icon and a message; selected items also have a check or a weight change.
+
+## Keyboard
+
+- Everything you can do with a mouse must work with a keyboard: Tab and Shift+Tab to move, Enter or Space to activate, Escape to close.
+- Keep the DOM order the same as the visual order, so Tab follows the reading order in both directions.
+- Don't set a positive `tabIndex`. Use `tabIndex={0}` only on custom controls that need it.
+- Inside composite widgets (Select, Date Picker, Tabs, Radio groups) arrow keys move within the widget and Tab leaves it.
+- In right-to-left layouts, Left and Right arrows follow the reading direction.
+
+## Focus
+
+- Components show a 2px focus ring in the brand border colour, offset from the control, for keyboard focus only (`:focus-visible`). For custom controls use `--ds-color-border-focus`.
+- Never remove the focus ring without a visible replacement.
+- After an action, move focus somewhere sensible: into a dialog that opens, back to the trigger when it closes, to the errors after a failed submit (render Error Summary with `autoFocus`; each of its links moves focus to its field).
+
+## Screen readers
+
+- Use native elements first: `<button>` for actions, `<a href>` for navigation, `<input>` for data. Never a clickable `<div>`.
+- Error messages are announced when they appear. Don't add another live region for the same message.
+- Hide purely decorative images and icons; name everything else.
+- Set the page language: `lang="ar"` for Arabic pages, `lang="en"` for English.
+
+## Motion
+
+Animated components respect `prefers-reduced-motion`. In your own code wrap animations in `motion-safe:` or remove them with `motion-reduce:`; don't auto-play movement longer than 5 seconds without a pause control; never flash more than three times a second.
+
+## Themes and direction
+
+Accessibility must hold in every combination. Switch them on `<html>`: `class="theme-dark"` for dark, `dir="rtl" lang="ar"` for Arabic (set both: `dir` mirrors the layout, `lang` gives screen readers the Arabic voice). See topics `theme` and `rtl`.
+
+## Zoom and screen size
+
+- Pages must work at 200% browser zoom and at a 320px-wide viewport (WCAG reflow) without losing content or scrolling in two directions.
+- Touch targets at least 24 × 24px, and 44 × 44px for the main actions on phones.
+- See topic `responsive` for the breakpoints.
+
+## Testing checklist
+
+- [ ] Tab through the page: every control is reachable, in order, with a visible focus ring.
+- [ ] Every field, button and icon-only control has a name.
+- [ ] Errors are announced and linked to their field.
+- [ ] axe (or Lighthouse) shows no violations.
+- [ ] Text and UI contrast pass in the light and dark themes.
+- [ ] The page works in Arabic with `dir="rtl"` and `lang="ar"`.
+- [ ] The page works at 200% zoom and with reduced motion on.
+- [ ] Checked with a screen reader (VoiceOver, NVDA or TalkBack).