@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/form/autocomplete.md

@@ -0,0 +1,100 @@
+# Autocomplete
+
+## Metadata
+- Component: Autocomplete
+- Slug: `autocomplete`
+- Category: Form
+- Install: `npx sdaia-ui@latest add autocomplete`
+- Import: `import { Autocomplete } from '@/components/ui/Autocomplete'`
+- Installed files: `Autocomplete.tsx`, `Autocomplete.types.ts`, `Autocomplete.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/autocomplete
+
+> **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 autocomplete`. It copies the source into your components folder (`components/ui/Autocomplete/`, under `src/` when the project has one); import it as `@/components/ui/Autocomplete`. 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 of the field. Leave unset to inherit it from an ancestor. |
+| `size?` | `'large' \| 'medium'` | 'large' | Size variant. - `large` (default) — 40 px input height, text-text-md - `medium` — 36 px input height, text-text-sm |
+| `value?` | `string` | '' | Current text value of the input (controlled). The parent is responsible for filtering `suggestions` based on this value. |
+| `onChange?` | `(value: string) => void` | — | Called on every keystroke with the new input text. |
+| `onSelect?` | `(item: AutocompleteItem) => void` | — | Called when the user selects a suggestion or recent item from the dropdown (click, or Enter on the option reached with the arrow keys). The parent can then decide whether to update `value` to `item.label`. |
+| `suggestions?` | `AutocompleteItem[]` | [] | Suggestion items to display in the dropdown (typically filtered by the parent based on the current `value`). When empty, the Suggestions section is hidden. |
+| `recents?` | `AutocompleteItem[]` | [] | Recent search items to display in the dropdown. When empty, the Recents section is hidden. |
+| `placeholder?` | `string` | 'Search' | Placeholder text shown when the input is empty. Wins over `labels.placeholder`. |
+| `label?` | `string` | — | Field label rendered above the input (linked to it with `htmlFor`). |
+| `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 | Adds a required asterisk (*) after the label and marks the input as required. |
+| `validationBehavior?` | `'native' \| 'aria'` | 'native' | How `required` reaches the input. - `'native'` — the `required` attribute (browser validation on form submit). - `'aria'` — `aria-required="true"` only (no browser validation bubble). The visual asterisk is shown either way. |
+| `helperText?` | `string` | — | Helper text rendered below the input (linked with `aria-describedby`). |
+| `helperIcon?` | `boolean` | true | Whether to render the help-circle icon next to helper text. |
+| `disabled?` | `boolean` | false | Disables the input and prevents all interaction. |
+| `leadingIcon?` | `boolean` | true | Whether to show the leading search icon inside the input. |
+| `id?` | `string` | — | `id` for the `<input>` element — also used for `htmlFor` on the label. A unique id is generated when unset. |
+| `onClear?` | `() => void` | — | Called when the user clears the input via the × button. |
+| `labels?` | `Partial<AutocompleteLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `onSelect`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the field. Leave unset to inherit it from an ancestor.
+- `size`: `'large'` \| `'medium'` — Size of the Autocomplete input field
+- `validationBehavior`: `'native'` \| `'aria'` — How `required` reaches the input.
+- `'native'` — the `required` attribute (browser validation on form submit).
+- `'aria'` — `aria-required="true"` only (no browser validation bubble).
+The visual asterisk is shown either way.
+
+## Deprecated props
+Do not use in new code:
+- `suggestionsLabel` — Label shown above the Suggestions section in the dropdown.
+Wins over `labels.suggestions`.
+- `recentsLabel` — Label shown above the Recents section in the dropdown.
+Wins over `labels.recents`.
+
+## 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-muted)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-disabled)`
+- `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-helper)`
+- `var(--ds-color-form-field-text-label)`
+- `var(--ds-color-form-field-text-placeholder)`
+- `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-brand)`
+- `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-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add autocomplete` (after `npx sdaia-ui@latest init`), then import `{ Autocomplete }` from `@/components/ui/Autocomplete`.
+- 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/checkbox.md

@@ -0,0 +1,95 @@
+# Checkbox
+
+## Metadata
+- Component: Checkbox
+- Slug: `checkbox`
+- Category: Form
+- Install: `npx sdaia-ui@latest add checkbox`
+- Import: `import { Checkbox } from '@/components/ui/Checkbox'`
+- Installed files: `Checkbox.tsx`, `Checkbox.types.ts`, `Checkbox.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/checkbox
+
+> **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 checkbox`. It copies the source into your components folder (`components/ui/Checkbox/`, under `src/` when the project has one); import it as `@/components/ui/Checkbox`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label?` | `ReactNode` | — | Label displayed next to the checkbox |
+| `placement?` | `'start' \| 'end' \| 'top' \| 'bottom'` | 'start' | Where the checkbox sits relative to the label (Figma Placement). |
+| `indeterminate?` | `boolean` | false | Displays a dash instead of a check (for partial selection) |
+| `size?` | `'sm' \| 'md' \| 'lg'` | 'md' | Size of the checkbox |
+| `variant?` | `'primary' \| 'neutral'` | 'primary' | Visual style variant |
+| `error?` | `string` | — | Error message displayed below the checkbox. Sets `aria-invalid` and is linked via `aria-describedby`. |
+| `helperText?` | `string` | — | Helper text displayed below the label (or below the control when there is no label) |
+| `readOnly?` | `boolean` | false | Read-only state (Figma Read-Only). Shows static styling; value cannot be changed. |
+| `checked?` | `boolean` | — | Whether the checkbox is checked (controlled). Omit for an uncontrolled checkbox. |
+| `defaultChecked?` | `boolean` | — | Initial checked state for uncontrolled usage. Ignored when `checked` is supplied. |
+| `onCheckedChange?` | `(checked: boolean) => void` | — | Called with the new checked state when the user toggles the checkbox. Native `onChange` keeps working. |
+| `validationBehavior?` | `'native' \| 'aria'` | 'native' | How `required` is enforced. `'native'` sets the native `required` attribute (browser validation bubble on submit); `'aria'` renders `aria-required="true"` instead and leaves validation to you. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the checkbox and its label. Omit to inherit from the closest `dir` ancestor. |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`.
+
+## Options (allowed values)
+- `placement`: `'start'` \| `'end'` \| `'top'` \| `'bottom'` — Position of the checkbox relative to the label block (Figma Placement).
+- `size`: `'sm'` \| `'md'` \| `'lg'` — Size of the checkbox
+- `variant`: `'primary'` \| `'neutral'` — Visual style variant
+- `validationBehavior`: `'native'` \| `'aria'` — How `required` is enforced. `'native'` sets the native `required` attribute (browser validation
+bubble on submit); `'aria'` renders `aria-required="true"` instead and leaves validation to you.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the checkbox and its label. Omit to inherit from the closest `dir` ancestor.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+Built in (SDAIA review item A1) — verified by `tests/a11y/keyboard/mouse-toggles.spec.ts` in the design system's test suite:
+- A click on the box toggles it, also when there is no visible label.
+
+You must:
+- Without a visible label, pass `aria-label`.
+
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-disabled)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-button-bg-black-hovered)`
+- `var(--ds-color-button-bg-black-pressed)`
+- `var(--ds-color-button-bg-primary-hovered)`
+- `var(--ds-color-button-bg-primary-pressed)`
+- `var(--ds-color-control-border)`
+- `var(--ds-color-control-border-disabled)`
+- `var(--ds-color-control-neutral-checked)`
+- `var(--ds-color-control-neutral-hovered)`
+- `var(--ds-color-control-pressed)`
+- `var(--ds-color-control-primary-checked)`
+- `var(--ds-color-form-field-border-danger)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default-disabled)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-disabled)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-icon-lg)`
+- `var(--ds-icon-sm)`
+- `var(--ds-icon-xl)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-figma-xs)`
+- `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 checkbox` (after `npx sdaia-ui@latest init`), then import `{ Checkbox }` from `@/components/ui/Checkbox`.
+- 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/date-time-field.md

@@ -0,0 +1,63 @@
+# Date Time Field
+
+## Metadata
+- Component: Date Time Field
+- Slug: `date-time-field`
+- Category: Form
+- Install: `npx sdaia-ui@latest add date-time-field`
+- Import: `import { DateTimeField } from '@/components/ui/DateTimeField'`
+- Installed files: `DateField.tsx`, `DateTimeField.tsx`, `DateTimeField.types.ts`, `DateTimeField.variants.ts`, `date.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/date-time-field
+
+> **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-time-field`. It copies the source into your components folder (`components/ui/DateTimeField/`, under `src/` when the project has one); import it as `@/components/ui/DateTimeField`. 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. In RTL the date field sits at the start (right) and both fields mirror. Unset inherits. |
+| `legend?` | `string` | — | Name of the group, rendered as the fieldset's `<legend>` (visually hidden: the Figma field shows only the two field labels). Screen readers announce it when focus enters either field, e.g. "Appointment". |
+| `dateLabel?` | `string` | — | Label of the date field (Figma "Date"). |
+| `timeLabel?` | `string` | — | Label of the time field (Figma "Time"). |
+| `datePlaceholder?` | `string` | — | Placeholder of the date field, e.g. "DD MMM YYYY". |
+| `timePlaceholder?` | `string` | — | Placeholder of the time field, e.g. "HH:MM". |
+| `value?` | `DateTimeFieldValue` | — | Selected date and time (controlled). |
+| `defaultValue?` | `DateTimeFieldValue` | EMPTY | Initial date and time (uncontrolled). |
+| `onChange?` | `(value: DateTimeFieldValue, text: DateTimeFieldText) => void` | — | Fired when either part changes — typed or picked. A part is `null` when it is empty or its text is not valid; `text` holds both fields' text so you can tell the two apart and validate the pair. |
+| `helperText?` | `string` | — | Helper text shown once under the pair and linked to both fields. |
+| `error?` | `string` | — | Error for the pair (Figma State=Error). Both fields turn red; one message is shown under the pair, linked to both fields and announced. |
+| `required?` | `boolean` | false | Marks both fields as required (visual `*` + required on both inputs). |
+| `disabled?` | `boolean` | false | Disables both fields. |
+| `size?` | `TextInputSize` | — | Field size, passed to both Text Inputs. Unset: responsive (medium below 768px, large from 768px). |
+| `timeFormat?` | `TimeFormat` | '12-hour' | Clock format of the time field and its picker. |
+| `minuteStep?` | `number` | 5 | Minutes between options in the time picker. |
+| `timePickerTitle?` | `string` | — | Title of the time picker header. Omit to hide it. |
+| `calendar?` | `DatePickerCalendar` | 'gregorian' | Calendar of the date picker and of the date text. |
+| `locale?` | `string` | — | BCP 47 locale of the date text and the date picker (digits stay Latin). Defaults to `'ar'` when `dir="rtl"`, else `'en'`. |
+| `minDate?` | `Date` | — | Earliest selectable date. |
+| `maxDate?` | `Date` | — | Latest selectable date. |
+| `formatDate?` | `(date: Date) => string` | — | Formats a date for the field. Default: day, short month name and year in `locale` and `calendar` — "12 Oct 2026" / "12 أكتوبر 2026". |
+| `parseDate?` | `(text: string) => Date \| null` | — | Parses typed date text. Default (Gregorian): `2026-10-12`, `12/10/2026` (day first), `12 Oct 2026`, `12 October 2026`, `12 أكتوبر 2026`, and Arabic-Indic digits. With a Hijri `calendar`, pass your own parser to accept typed Hijri dates. |
+| `labels?` | `Partial<DateTimeFieldLabels>` | — | Localised built-in strings. |
+
+Also accepts standard `<element>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onChange`, `defaultValue`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. In RTL the date field sits at the start (right) and both fields mirror. Unset inherits.
+
+## 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 date-time-field` (after `npx sdaia-ui@latest init`), then import `{ DateTimeField }` from `@/components/ui/DateTimeField`.
+- 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/error-summary.md

@@ -0,0 +1,56 @@
+# Error Summary
+
+## Metadata
+- Component: Error Summary
+- Slug: `error-summary`
+- Category: Form
+- Install: `npx sdaia-ui@latest add error-summary`
+- Import: `import { ErrorSummary } from '@/components/ui/ErrorSummary'`
+- Installed files: `ErrorSummary.tsx`, `ErrorSummary.types.ts`, `ErrorSummary.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/error-summary
+
+> **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 error-summary`. It copies the source into your components folder (`components/ui/ErrorSummary/`, under `src/` when the project has one); import it as `@/components/ui/ErrorSummary`. 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 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | — | Calm, plain title (Figma `Title`), e.g. "There is a problem". Rendered as a heading that names the summary. |
+| `intro?` | `ReactNode` | — | Optional line under the title (Figma `Intro`), e.g. "Fix the following to continue:". Omit it to hide it. |
+| `errors` | `ErrorSummaryItem[]` | — | The problems, in the same order as the fields on the page (Figma `Items` 2 / 3 / 4 — any number works in code). Each item renders as a link to its field. |
+| `autoFocus?` | `boolean` | false | Moves keyboard focus to the summary when it mounts. Render the summary after a failed submit with `autoFocus`; when it stays mounted between submits, call `ref.current?.focus()` yourself instead. |
+| `headingLevel?` | `ErrorSummaryHeadingLevel` | 2 | Heading level of the title. |
+| `onErrorClick?` | `(error: ErrorSummaryItem, event: MouseEvent<HTMLAnchorElement>) => void` | — | Called when an item is activated, before focus moves to its field. Call `event.preventDefault()` to handle the navigation yourself. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the summary. Inherits from the document when omitted. Figma `RTL=True` maps to `dir="rtl"`. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`, `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the summary. Inherits from the document when omitted.
+Figma `RTL=True` maps to `dir="rtl"`.
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-danger-subtle)`
+- `var(--ds-color-border-danger-strong)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add error-summary` (after `npx sdaia-ui@latest init`), then import `{ ErrorSummary }` from `@/components/ui/ErrorSummary`.
+- 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/field-group.md

@@ -0,0 +1,57 @@
+# Field Group
+
+## Metadata
+- Component: Field Group
+- Slug: `field-group`
+- Category: Form
+- Install: `npx sdaia-ui@latest add field-group`
+- Import: `import { FieldGroup } from '@/components/ui/FieldGroup'`
+- Installed files: `FieldGroup.tsx`, `FieldGroup.types.ts`, `FieldGroup.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/field-group
+
+> **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 field-group`. It copies the source into your components folder (`components/ui/FieldGroup/`, under `src/` when the project has one); import it as `@/components/ui/FieldGroup`. 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 |
+| --- | --- | --- | --- |
+| `legend` | `ReactNode` | — | Short title of the group, rendered as the fieldset's `<legend>` (Figma `Legend`). It names the group for screen readers. |
+| `hint?` | `ReactNode` | — | Optional one-line explanation under the legend (Figma `Hint`). It is linked to the fieldset with `aria-describedby`. Omit it to hide the hint. |
+| `layout?` | `'vertical' \| 'horizontal'` | 'vertical' | Arrangement of the fields (Figma `Layout`). |
+| `variant?` | `'plain' \| 'bordered'` | 'plain' | Container style (Figma `Style`). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the group. Inherits from the document when omitted. Figma `RTL=True` maps to `dir="rtl"`. |
+| `children` | `ReactNode` | — | The fields of the group (Figma `Fields` slot): `TextInput`, `Select`, radio or checkbox groups… Each field keeps its own visible label. |
+
+Also accepts standard `<element>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `children`.
+
+## Options (allowed values)
+- `layout`: `'vertical'` \| `'horizontal'` — How the fields in the group are arranged (Figma `Layout`).
+- `vertical` — fields stacked under the legend (the default choice).
+- `horizontal` — two or three short, related fields share one row. The row
+  wraps to one field per line when the group is too narrow for them.
+- `variant`: `'plain'` \| `'bordered'` — Container style of the group (Figma `Style`).
+- `plain` — no container; the legend and fields sit on the page.
+- `bordered` — the group sits in its own bordered, padded container.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the group. Inherits from the document when omitted.
+Figma `RTL=True` maps to `dir="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-border-default)`
+- `var(--ds-color-form-field-text-helper)`
+- `var(--ds-color-text-default)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-xl)`
+- `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 field-group` (after `npx sdaia-ui@latest init`), then import `{ FieldGroup }` from `@/components/ui/FieldGroup`.
+- 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/file-uploader.md

@@ -0,0 +1,60 @@
+# File Upload
+
+## Metadata
+- Component: File Upload
+- Slug: `file-uploader`
+- Category: Form
+- Install: `npx sdaia-ui@latest add file-uploader`
+- Import: `import { FileUploader } from '@/components/ui/FileUploader'`
+- Installed files: `FileUploader.tsx`, `FileUploader.types.ts`, `FileUploader.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/file-upload
+
+> **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 file-uploader`. It copies the source into your components folder (`components/ui/FileUploader/`, under `src/` when the project has one); import it as `@/components/ui/FileUploader`. 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 |
+| --- | --- | --- | --- |
+| `dropZone?` | `Partial<FileUploadBaseProps>` | — | Props merged into the drop zone (`FileUploadBase`). Use `onBrowse` to open your own file UI (e.g. a hidden input in the parent); this component does not render `<input type="file" />`. |
+| `files?` | `FileUploaderFileEntry[]` | — | File rows below the drop zone. |
+| `listFooter?` | `ReactNode` | — | Optional custom list content when you do not use `files`. Rendered after `files` if both are set. |
+| `onFilesDropped?` | `(files: FileList) => void` | — | Called after files are dropped on the drop zone. |
+| `onRemoveFile?` | `(id: string) => void` | — | — |
+| `onRetryFile?` | `(id: string) => void` | — | Called with the file's `id` when its "Try again" action is activated. The 'Try again' action on a failed file renders only when this is set. |
+| `retryLabel?` | `ReactNode` | labels.retry ('Try again') | Default “Try again” label for error rows (overridable per `files[].retryLabel`). Wins over `labels.retry`. |
+| `dismissLabel?` | `string` | labels.dismiss ('Remove file') | Default `aria-label` for each row's remove button (overridable per `files[].dismissLabel`). Wins over `labels.dismiss`. |
+| `formatFileSize?` | `FileUploadItemBaseProps['formatFileSize']` | — | Byte formatter for the size line of every row. |
+| `formatUploadProgress?` | `FileUploadItemBaseProps['formatUploadProgress']` | — | Builds each row's size line, e.g. `(u, t) => \`${u} من ${t}\``. Wins over `labels.uploadProgress`. |
+| `labels?` | `Partial<FileUploaderLabels>` | — | Localised built-in strings, passed to the drop zone (`instruction`, `browse`) and to every file row (the rest). `dropZone.label` / `dropZone.browseLabel` / `dropZone.labels`, `retryLabel`, `dismissLabel` and the per-file copy win. |
+| `disabled?` | `boolean` | false | Disables drop zone and browse interaction. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction for the uploader, its drop zone and rows. Undefined inherits from an ancestor; set explicitly for documentation previews. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction for the uploader, its drop zone and rows. Undefined inherits
+from an ancestor; set explicitly for documentation previews.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+Built in (SDAIA review item A7) — verified by `axe scan (aria-progressbar-name) — audit-reports/a11y` in the design system's test suite:
+- Each upload progress bar has an accessible name.
+
+- 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-md)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add file-uploader` (after `npx sdaia-ui@latest init`), then import `{ FileUploader }` from `@/components/ui/FileUploader`.
+- 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/form-section.md

@@ -0,0 +1,58 @@
+# Form Section
+
+## Metadata
+- Component: Form Section
+- Slug: `form-section`
+- Category: Form
+- Install: `npx sdaia-ui@latest add form-section`
+- Import: `import { FormSection } from '@/components/ui/FormSection'`
+- Installed files: `FormSection.tsx`, `FormSection.types.ts`, `FormSection.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/form-section
+
+> **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 form-section`. It copies the source into your components folder (`components/ui/FormSection/`, under `src/` when the project has one); import it as `@/components/ui/FormSection`. 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 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | — | Section title (Figma `Title`), rendered as a real heading that names the section. |
+| `description?` | `ReactNode` | — | Optional one-sentence description under the title (Figma `Description`). Linked to the section with `aria-describedby`. Omit it to hide it. |
+| `layout?` | `'stacked' \| 'side-by-side'` | 'stacked' | Title placement (Figma `Layout`). |
+| `headingLevel?` | `FormSectionHeadingLevel` | 2 | Heading level of the title. Pick the level that fits the page outline (the page title is usually `h1`). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the section. Inherits from the document when omitted. Figma `RTL=True` maps to `dir="rtl"`. |
+| `children` | `ReactNode` | — | The fields of the section (Figma `Fields` slot): `FieldGroup`s, inputs or any form content. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`, `children`.
+
+## Options (allowed values)
+- `layout`: `'stacked'` \| `'side-by-side'` — Where the title sits relative to the fields (Figma `Layout`).
+- `stacked` — the title and description sit above the fields.
+- `side-by-side` — the title sits in a 280px column next to the fields
+  (start side: left in LTR, right in RTL). When the section is narrower than
+  40rem (640px) it falls back to the stacked layout, as the Figma usage note
+  asks ("Stacked below 1024px screens").
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the section. Inherits from the document when omitted.
+Figma `RTL=True` maps to `dir="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-border-muted)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-lg)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add form-section` (after `npx sdaia-ui@latest init`), then import `{ FormSection }` from `@/components/ui/FormSection`.
+- 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/number-input.md

@@ -0,0 +1,92 @@
+# Number Input
+
+## Metadata
+- Component: Number Input
+- Slug: `number-input`
+- Category: Form
+- Install: `npx sdaia-ui@latest add number-input`
+- Import: `import { NumberInput } from '@/components/ui/NumberInput'`
+- Installed files: `NumberInput.tsx`, `NumberInput.types.ts`, `NumberInput.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/number-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 number-input`. It copies the source into your components folder (`components/ui/NumberInput/`, under `src/` when the project has one); import it as `@/components/ui/NumberInput`. 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 displayed above the input. Rendered as a `<label>` associated with the `<input>` via `htmlFor`. |
+| `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. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the field. Unset inherits from the closest `dir` ancestor. The minus button sits on the start side, plus / arrow on the end side. |
+| `labels?` | `Partial<NumberInputLabels>` | — | Localised built-in strings (button names). |
+| `size?` | `'lg' \| 'md'` | 'lg' | Size tier. |
+| `style?` | `'solid' \| 'subtle'` | 'solid' | Visual fill style for the flanking +/− buttons. |
+| `spinner?` | `boolean` | false | When `true`, renders a single arrow (unfold-more) button on the end side instead of separate minus + plus buttons. The center input gains start-side border-radius. |
+| `value?` | `string \| number` | — | Controlled current value. Pass `''` to represent an empty/cleared field. |
+| `defaultValue?` | `string \| number` | — | Uncontrolled default value. |
+| `onChange?` | `(value: string) => void` | — | Called with the raw string value whenever the input changes (typing or button press). |
+| `min?` | `number` | — | Minimum numeric value. Respected by the decrement button — will not go below this value. |
+| `max?` | `number` | — | Maximum numeric value. Respected by the increment button — will not go above this value. |
+| `step?` | `number` | 1 | Step size for increment/decrement buttons. |
+| `error?` | `string` | — | Error message string. When non-empty: - input border turns red - helper text below turns red and shows this message - helper icon turns red Overrides `helperText`. |
+| `helperText?` | `string` | — | Helper text shown below the input. Replaced by `error` when error is set. |
+| `showHelperIcon?` | `boolean` | true | When `true`, shows the help-circle icon next to helper/error text. |
+| `disabled?` | `boolean` | false | Disables all interaction on the entire component. |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`, `type`, `onChange`, `style`.
+
+## Options (allowed values)
+- `validationBehavior`: `'native'` \| `'aria'` — Native `required` handling — see `NumberInputProps.validationBehavior`.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the field. Unset inherits from the closest `dir` ancestor.
+The minus button sits on the start side, plus / arrow on the end side.
+- `size`: `'lg'` \| `'md'` — Size tier — maps to Figma Large / Medium.
+
+- `'lg'` — Large (height ~40px for buttons, px-xl/py-md for input)
+- `'md'` — Medium (height ~32px for buttons, px-xl/py-sm for input)
+- `style`: `'solid'` \| `'subtle'` — Visual fill style for the prefix/suffix buttons.
+
+- `'solid'`  — neutral-fill background on +/− buttons
+- `'subtle'` — transparent buttons; fill appears only on hover/active
+
+## 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-border-disabled)`
+- `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-2xl)`
+- `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 number-input` (after `npx sdaia-ui@latest init`), then import `{ NumberInput }` from `@/components/ui/NumberInput`.
+- 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.