@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/foundations/figma.md

@@ -0,0 +1,30 @@
+# SDAIA Figma Library and Code
+
+The **SDAIA Design System Figma library** is the design source for `sdaia-ui`. Code follows it: component sets, variants, states and sizes in Figma map to components, props and option values in code, and the Figma variables match the `@sdaia-ds/tokens` design tokens. Each component's docs page on https://ds.nacew.com links to its Figma component; ask the SDAIA design team for access to the library.
+
+## Mapping Figma to code
+
+| In Figma | In code |
+| --- | --- |
+| Component set (e.g. `Button`) | Component (`import { Button } from '@/components/ui/Button'`; `get_component_docs`) |
+| Variant property `Style`, `Size`, `Type` | Props with string options (`variant`, `size`, `type`, …) — the allowed values are listed under "Options" in `get_component_docs` |
+| Variant property `State` (Hover, Focused, Pressed) | Not a prop: the component renders it from user interaction |
+| `State = Disabled` / `Error` | The `disabled` / `error` props |
+| Color variables (`bg-default`, `text-paragraph`, …) | Semantic tokens `--ds-color-*` (`get_tokens` category `colors`) |
+| Spacing / Typography variables with Desktop, Tablet and Mobile modes | Responsive tokens that switch at 768px and 1280px (topic `responsive`) |
+| Text styles (`Display xs`, `Text md` …) | `text-display-*` / `text-text-*` utilities (topic `typography`) |
+| Brand modes | Brand classes on `<html>` (topic `theme`) |
+| Instances inside a component (Button, Badge, Checkbox …) | The same components composed inside the coded one |
+
+## When building from a Figma frame
+
+1. Identify each instance's component set and find it with `search_components`.
+2. Read its props and allowed values with `get_component_docs`; use the documented option values only.
+3. Use the Figma variable names to pick tokens (`get_tokens`); never copy hex values or pixel numbers from the inspector.
+4. Build layout around components with token-based spacing (`p-spacing-*`, `gap-spacing-*`) and make it fluid (topic `responsive`).
+5. For icons, find the glyph in `@platformscode/icons` (topic `icon-usage`); don't export SVGs from Figma for UI icons.
+
+## Known differences
+
+- Text at 14px / 20px line height renders about 0.7px higher in browsers than in Figma (font metrics). This is accepted; don't compensate with padding.
+- If a Figma component and its docs page disagree, the component's code (what `get_component_docs` shows) is what ships; report the difference to the design team.

package/knowledge/foundations/icon-usage.md

@@ -0,0 +1,114 @@
+# Icons — `@platformscode/icons` + `DgaIcon`
+
+> **Hard rule for AI:** Every functional UI icon MUST come from `@platformscode/icons` rendered with the CLI-installed `<DgaIcon />`.  
+> **Never** use emoji (☀️ 🌙 🔔), Unicode symbols, Lucide, Heroicons, Material Icons, inline `<svg>`, `sdaia-ui/icons`, or invented import names.  
+> **Never** pick random icons from the package (e.g. `pizza01Stroke`, `hamburger01Stroke`) for standard actions — use the mappings below.
+
+`npx sdaia-ui@latest init` installs the `@platformscode/icons` package. `DgaIcon` comes with any component that uses icons, or on its own with `npx sdaia-ui@latest add dga-icon` (it lives at `@/components/ui/DgaIcon`). Size: `size-icon-xs` 12 · `sm` 16 · `lg` 20 · `xl` 24 · `2xl` 32 · `3xl` 40 px — there is no `size-icon-md`. Directional icons take `flipOnRtl`.
+
+## Import pattern (always two imports)
+
+```tsx
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { search01Stroke, cancel01Stroke } from '@platformscode/icons';
+
+<DgaIcon data={search01Stroke} className="size-icon-sm" />
+```
+
+- **`DgaIcon`** — local component (wrapper). Path: `@/components/ui/DgaIcon`.
+- **Icon data** — named exports from `@platformscode/icons` (SVG path strings). Suffix is `Stroke` or `Solid`.
+- **Size** — `size-icon-xs` | `size-icon-sm` | `size-icon-lg` | `size-icon-xl` | `size-icon-2xl` | `size-icon-3xl` on the icon or its parent slot (see `get_foundations` topic `icons` for px values).
+- When a parent component (e.g. `Tab`, `Button` icon-only) already wraps `leadingIcon` in `size-icon-sm`, pass `<DgaIcon data={…} />` **without** duplicating size classes on the SVG.
+
+## What NOT to do
+
+| Wrong | Why |
+| --- | --- |
+| `{dark ? '☀️' : '🌙'}` in a theme toggle | Not DS icons; inconsistent with design system |
+| `import { Moon } from 'lucide-react'` | Wrong icon library |
+| `import { Pizza } from …` / `pizza01Stroke` for dark mode | Random package icon — use `darkModeStroke` / `moon02Stroke` / `sun01Stroke` |
+| `import … from 'sdaia-ui'` or `sdaia-ui/icons` | Deprecated — CLI copies source only |
+| Invented names like `closeIcon`, `BellIcon` as npm imports | Must be real exports: `cancel01Stroke`, `notification01Stroke`, … |
+| `<img src="…">` for toolbar / input affordances | Use `DgaIcon` + token |
+
+## Approved icon map (common UI)
+
+Use these **exact export names** from `@platformscode/icons`. Prefer **`Stroke`** in buttons, inputs, tabs, and navigation; use **`Solid`** when matching an installed component that already imports solids (e.g. `NotificationPopup`).
+
+| UI intent | Use this export | Notes |
+| --- | --- | --- |
+| Close / dismiss | `cancel01Stroke` | Used by `Notifications` close, `Filtration` chips |
+| Search | `search01Stroke` | Default search affordance |
+| Notifications / bell | `notification01Stroke` | Inbox, alerts |
+| Email / direct | `mail01Stroke` | Mail, direct messages |
+| Info / help | `informationCircleStroke` | Helper, tooltips |
+| Filter | `filterStroke` | Filter menus (`Filtration`) |
+| More / overflow menu | `moreVerticalStroke` | `Dropdown` trigger |
+| Chevron / expand | `arrowDown01Stroke`, `arrowRight01Stroke` | Menus, nav |
+| Settings | `settings01Stroke` or `settings02Stroke` | Verify name exists before import |
+| **Dark mode (show moon)** | `darkModeStroke` or `moon02Stroke` | Theme toggle when switching **to** dark |
+| **Light mode (show sun)** | `sun01Stroke` or `sun02Stroke` | Theme toggle when switching **to** light |
+| Success (toast/popup) | `tick02Solid` | `NotificationPopup` success |
+| Error | `cancel01Solid` or `alert02Solid` | Match popup type |
+| Warning / alert | `alert02Stroke` or `notification02Solid` | Alerts, notification popup |
+
+> If unsure whether a name exists, only use icons listed in this table or copied from `get_component_docs` for the target component. Do not guess food, weather, or entertainment icons.
+
+## Dark / light mode toggle (icons + theme class)
+
+Theme is **`document.documentElement.classList.toggle('theme-dark', isDark)`** — see `get_foundations` topic `theme`.  
+Icons for the toggle button:
+
+```tsx
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { darkModeStroke, sun01Stroke } from '@platformscode/icons';
+import { Button } from '@/components/ui/Button';
+
+// When currently light → show moon/dark affordance; when dark → show sun
+<Button
+  variant="transparent"
+  size="md"
+  iconOnly
+  aria-label={dark ? 'Switch to light mode' : 'Switch to dark mode'}
+  leadingIcon={
+    <DgaIcon data={dark ? sun01Stroke : darkModeStroke} className="size-icon-sm" />
+  }
+  onClick={() => setDark((value) => !value)}
+/>
+```
+
+Optional: `moon02Stroke` instead of `darkModeStroke`. **Do not** use `pizza01Stroke`, emoji, or unrelated icons.
+
+## Passing icons into DS components
+
+```tsx
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { mail01Stroke, informationCircleStroke } from '@platformscode/icons';
+
+<TextInput
+  prefix={<DgaIcon data={mail01Stroke} className="size-icon-sm" />}
+  suffix={<DgaIcon data={informationCircleStroke} className="size-icon-sm" />}
+/>
+
+<Button leadingIcon={<DgaIcon data={search01Stroke} className="size-icon-sm" />}>Search</Button>
+```
+
+For `HorizontalTabItem.leadingIcon`, `Select.leadingIcon`, `Button.leadingIcon`, etc., see each component's `get_component_docs` entry.
+
+## Logos and illustrations (not `DgaIcon`)
+
+Brand logos, feedback emojis, PDF/file illustrations → **`sdaia-assets`** (installed by `init`), not `@platformscode/icons`.
+
+```tsx
+import { SdaiaLogo } from '@/components/sdaia-assets';
+```
+
+## MCP tools
+
+| Need | Tool |
+| --- | --- |
+| Setup + init | `setup_project` (Step 8) |
+| Icon sizes (tokens) | `get_foundations` → `icons` |
+| This mapping | `get_foundations` → `icon-usage` |
+| Theme class | `get_foundations` → `theme` |
+| Icons a component uses | `get_component_docs` → `<slug>` |

package/knowledge/foundations/icons.md

@@ -0,0 +1,16 @@
+# Icon Sizes
+
+Icon sizing tokens. Use the built-in `size-icon-*` utility classes on `<DgaIcon>` rather than hardcoded sizes.
+
+> Resolve any token live with the `get_tokens` tool.
+
+## Icon Sizes
+
+| Token | CSS variable | Light | Dark | Description |
+| --- | --- | --- | --- | --- |
+| `icon-xs` | `var(--ds-icon-xs)` | `12px` | — | Tiny icon (12px). Inline with caption text, dense table cells, status dots. Pair with text-xs. |
+| `icon-sm` | `var(--ds-icon-sm)` | `16px` | — | Default UI icon (16px). Inline with body text, button leading icons, form field affixes. Most common — start here. |
+| `icon-lg` | `var(--ds-icon-lg)` | `20px` | — | Medium icon (20px). Navigation icons, toolbar buttons, list item leading icons. |
+| `icon-xl` | `var(--ds-icon-xl)` | `24px` | — | Large icon (24px). Section headers, primary action buttons, app bar icons. |
+| `icon-2xl` | `var(--ds-icon-2xl)` | `32px` | — | Extra-large icon (32px). Empty state illustrations, feature cards, prominent actions. |
+| `icon-3xl` | `var(--ds-icon-3xl)` | `40px` | — | Largest icon (40px). Hero sections, onboarding flows, marketing pages. |

package/knowledge/foundations/motion.md

@@ -0,0 +1,39 @@
+# Motion
+
+Motion duration and easing tokens for transitions and animations.
+
+> Resolve any token live with the `get_tokens` tool.
+
+## Easing
+
+| Token | CSS variable | Light | Dark | Description |
+| --- | --- | --- | --- | --- |
+| `motion-easing-linear` | `var(--ds-motion-easing-linear)` | `cubic-bezier(0, 0, 1, 1)` | — | Constant rate (linear). Use for progress bars, loaders. Avoid for natural movement. |
+| `motion-easing-standard` | `var(--ds-motion-easing-standard)` | `cubic-bezier(0.2, 0, 0, 1)` | — | Default smooth easing. Most UI transitions: state changes, fades, simple movement. |
+| `motion-easing-decelerate` | `var(--ds-motion-easing-decelerate)` | `cubic-bezier(0, 0, 0.2, 1)` | — | Ease-out. Elements entering the screen, slowing as they arrive. Modals opening, drawers sliding in. |
+| `motion-easing-accelerate` | `var(--ds-motion-easing-accelerate)` | `cubic-bezier(0.4, 0, 1, 1)` | — | Ease-in. Elements leaving the screen, speeding up as they exit. Modals closing, dismissed items. |
+| `motion-easing-emphasized` | `var(--ds-motion-easing-emphasized)` | `cubic-bezier(0.2, 0, 0, 1.2)` | — | Pronounced curve for elements demanding attention. Important state changes, hero animations. |
+| `motion-feedback-easing` | `var(--ds-motion-feedback-easing)` | `cubic-bezier(0.2, 0, 0, 1)` | — | Easing for interaction feedback. Standard quick response curve. |
+| `motion-enter-easing` | `var(--ds-motion-enter-easing)` | `cubic-bezier(0, 0, 0.2, 1)` | — | Easing for elements entering view. Decelerates as they settle into final position. |
+| `motion-exit-easing` | `var(--ds-motion-exit-easing)` | `cubic-bezier(0.4, 0, 1, 1)` | — | Easing for elements leaving view. Accelerates as they exit. |
+| `motion-expand-easing` | `var(--ds-motion-expand-easing)` | `cubic-bezier(0.2, 0, 0, 1)` | — | Easing for spatial expansion/collapse. Smooth standard curve. |
+| `motion-transition-easing` | `var(--ds-motion-transition-easing)` | `cubic-bezier(0.2, 0, 0, 1)` | — | Easing for general transitions. Standard smooth curve. |
+| `motion-emphasis-easing` | `var(--ds-motion-emphasis-easing)` | `cubic-bezier(0.2, 0, 0, 1.2)` | — | Pronounced easing curve for emphasis animations. Use sparingly to maintain impact. |
+| `motion-loop-easing` | `var(--ds-motion-loop-easing)` | `cubic-bezier(0, 0, 1, 1)` | — | Easing for looping animations. Linear or smooth depending on visual style. |
+| `motion-feedback-duration` | `var(--ds-motion-feedback-duration)` | `150ms` | — | Duration for interaction feedback (button press, tap response). Default 150ms / Reduced 100ms. |
+| `motion-enter-duration` | `var(--ds-motion-enter-duration)` | `250ms` | — | Duration for elements entering view (modals opening, items appearing). Default 250ms / Reduced 100ms. |
+| `motion-exit-duration` | `var(--ds-motion-exit-duration)` | `150ms` | — | Duration for elements leaving view (modals closing, items dismissing). Default 200ms / Reduced 100ms. |
+| `motion-expand-duration` | `var(--ds-motion-expand-duration)` | `350ms` | — | Duration for size changes (accordion expand, panel resize). Default 350ms / Reduced 0ms. |
+| `motion-transition-duration` | `var(--ds-motion-transition-duration)` | `250ms` | — | Duration for general state transitions (theme flip, color change). Default 250ms / Reduced 100ms. |
+| `motion-emphasis-duration` | `var(--ds-motion-emphasis-duration)` | `350ms` | — | Duration for attention-grabbing animations (notifications, callouts). Default 350ms / Reduced 0ms. |
+| `motion-loop-duration` | `var(--ds-motion-loop-duration)` | `500ms` | — | Duration for looping animations (loaders, spinners, pulse effects). Default 1500ms / Reduced 0ms (loops disabled). |
+
+## Duration
+
+| Token | CSS variable | Light | Dark | Description |
+| --- | --- | --- | --- | --- |
+| `motion-duration-instant` | `var(--ds-motion-duration-instant)` | `0ms` | — | Zero delay (0ms). State changes that should feel immediate: tooltips on desktop, badge count updates. |
+| `motion-duration-fast` | `var(--ds-motion-duration-fast)` | `150ms` | — | Fast micro-interactions (150ms default / 100ms reduced). Hover, focus, press, ripple effects. |
+| `motion-duration-base` | `var(--ds-motion-duration-base)` | `250ms` | — | Standard transitions (250ms default / 100ms reduced). Modal enter, toast, tab swap, simple fades. |
+| `motion-duration-moderate` | `var(--ds-motion-duration-moderate)` | `350ms` | — | Spatial transitions (350ms default / 0ms reduced). Accordion expand, dropdown open, drawer slide. Reduced removes spatial motion entirely. |
+| `motion-duration-slow` | `var(--ds-motion-duration-slow)` | `500ms` | — | Long transitions (500ms default / 0ms reduced). Full-screen overlays, page transitions, complex choreography. |

package/knowledge/foundations/radius.md

@@ -0,0 +1,17 @@
+# Radius
+
+Border-radius scale tokens.
+
+> Resolve any token live with the `get_tokens` tool.
+
+## Border Radius
+
+| Token | CSS variable | Light | Dark | Description |
+| --- | --- | --- | --- | --- |
+| `radius-none` | `var(--ds-radius-none)` | `0px` | — | Zero corner radius. For full-bleed sections, dividers, sharp edges. All radius modes: 0px. |
+| `radius-xxs` | `var(--ds-radius-xxs)` | `2px` | — | Minimal corner radius for hairline elements: input outlines, small chips. Standard 2px / Square 0 / Rounded 4px. |
+| `radius-xs` | `var(--ds-radius-xs)` | `6px` | — | Small corner radius for compact controls: chips, tags, badges. Standard 4px / Square 0 / Rounded 8px. |
+| `radius-m` | `var(--ds-radius-m)` | `8px` | — | Default UI radius for buttons, inputs, form fields, small cards. Most common — start here. Standard 8px / Square 0 / Rounded 12px. |
+| `radius-l` | `var(--ds-radius-l)` | `16px` | — | Medium-large radius for cards, modals, popovers, content surfaces. Standard 16px / Square 0 / Rounded 24px. |
+| `radius-xl` | `var(--ds-radius-xl)` | `24px` | — | Large radius for hero sections, feature cards, large content blocks. Standard 24px / Square 0 / Rounded 32px. |
+| `radius-full` | `var(--ds-radius-full)` | `9999px` | — | Fully rounded — pill shapes, avatars, circular indicators, badges. Always 9999px regardless of radius mode. |

package/knowledge/foundations/responsive.md

@@ -0,0 +1,64 @@
+# SDAIA Responsive Behaviour
+
+SDAIA UI is one set of components that adapts to the screen (responsive web: desktop first, tablet fully supported, phone for key tasks). Spacing and type tokens switch automatically between desktop, tablet and phone values, and components reflow to the width they are given. Docs: https://ds.nacew.com/foundations/responsive
+
+## Breakpoints
+
+Three system breakpoints, the same in Figma, the tokens and the CSS `init` installs:
+
+| Tier | Viewport width | Tailwind prefix where it starts |
+| --- | --- | --- |
+| Mobile | under 768px | (default) |
+| Tablet | 768px – 1279px | `md:` |
+| Desktop | 1280px and up | `xl:` |
+
+`sm:` (640), `lg:` (1024) and `2xl:` (1536) are only for fine-tuning a layout inside a tier; tokens don't change there.
+
+```ts
+const isTabletUp = window.matchMedia('(min-width: 768px)').matches;
+const isDesktop = window.matchMedia('(min-width: 1280px)').matches;
+```
+
+## What switches automatically
+
+The CSS from `npx sdaia-ui@latest init` is mobile first: mobile values are the defaults and media queries at 768px and 1280px switch to tablet and desktop. **Spacing, font sizes and line heights** change; icon sizes, radii, border widths and colours don't. Every component and every utility built on the tokens (`p-spacing-xl`, `gap-spacing-2xl`, `text-text-md`, …) follows the screen width with no extra class.
+
+Type scale (size · line height, desktop / tablet / mobile, px):
+
+| Utility | Size | Line height |
+| --- | --- | --- |
+| `text-display-2xl` | 72 / 56 / 48 | 90 / 72 / 64 |
+| `text-display-xl` | 60 / 48 / 40 | 72 / 64 / 56 |
+| `text-display-lg` | 48 / 36 / 32 | 60 / 48 / 40 |
+| `text-display-md` | 36 / 30 / 24 | 44 / 40 / 32 |
+| `text-display-sm` | 30 / 24 / 20 | 38 / 32 / 28 |
+| `text-display-xs` | 24 / 20 / 18 | 32 / 28 / 24 |
+| `text-text-xl` | 20 / 18 / 16 | 30 / 26 / 24 |
+| `text-text-lg` | 18 / 16 / 14 | 28 / 24 / 20 |
+| `text-text-md` | 16 / 14 / 12 | 24 / 20 / 18 |
+| `text-text-sm` | 14 / 12 / 10 | 20 / 16 / 14 |
+| `text-text-xs` | 12 / 10 / 8 | 18 / 14 / 12 |
+| `text-text-2xs` | 12 / 8 / 8 | 18 / 12 / 10 |
+
+Spacing steps (`spacing-xxs` … `spacing-11xl`) also step down on tablet and phone; the exact values depend on the brand. Look them up with `get_tokens` (category `spacing`) and always use the token, never the number.
+
+## Rules for generated layouts
+
+- **Don't** add your own mobile step-downs on top of the tokens (`text-sm md:text-md`, `p-4 md:p-6` for component internals): the tokens already step down.
+- **Don't** add `viewport-mobile` / `viewport-tablet` classes yourself.
+- Build page layouts with fluid primitives: `w-full`, `max-w-*`, `min-w-0`, `flex-wrap`, CSS grid with `md:` / `xl:` column changes. Avoid fixed widths and `min-width` on wrappers.
+- Everything must work at a **360px** viewport without horizontal page scroll, and at 200% zoom.
+- AppShell, PageTemplate and Stepper switch layout by **their own width** (container queries), so they adapt inside a narrow column too; FormSection's side-by-side layout wraps when there is no room. Give these a container that spans the available width.
+
+```tsx
+<main className="mx-auto w-full max-w-[1216px] px-4 md:px-8">
+  <div className="grid grid-cols-4 gap-4 md:grid-cols-6 md:gap-8 xl:grid-cols-12 xl:gap-6">
+    <section className="col-span-4 md:col-span-6 xl:col-span-8">…</section>
+    <aside className="col-span-4 md:col-span-6 xl:col-span-4">…</aside>
+  </div>
+</main>
+```
+
+## Where the interaction changes
+
+Navigation (NavHeader / NavBar switch to their compact layout below 768px), tables, dialogs and pickers have their own small-screen behaviour built in. Each component's docs page has a "Responsive behavior" section; use the component as is rather than building a separate mobile version.

package/knowledge/foundations/rtl.md

@@ -0,0 +1,106 @@
+# SDAIA RTL (Right-to-Left) Layout Guide
+
+The SDAIA Design System is built RTL-first — it was designed for Arabic-language products.
+Every component ships with an LTR/RTL preview toggle on its documentation page.
+
+## Setting document direction
+
+### Full RTL document (Arabic UI)
+
+```html
+<html lang="ar" dir="rtl">
+```
+
+Set **both** `dir` (mirrors the layout) and `lang` (Arabic screen-reader voice and Arabic CSS rules). Where: `app/layout.tsx` (Next.js App Router), `<Html>` in `pages/_document.tsx` (Pages Router), `index.html` (Vite).
+
+### Conditional direction (locale-aware)
+
+```tsx
+const locale = 'ar'; // or 'en'
+document.documentElement.setAttribute('dir', locale === 'ar' ? 'rtl' : 'ltr');
+document.documentElement.setAttribute('lang', locale);
+```
+
+## Per-component direction prop
+
+Components follow the document direction. Each also accepts `dir?: 'ltr' | 'rtl'` on its root to override it for one subtree (some older components also accept a boolean `rtl`, kept as a deprecated alias — use `dir`). Components with built-in text (Date Picker, Pagination) switch their own strings to Arabic for an RTL / Arabic context; others take translated strings through `labels`.
+
+```tsx
+<Card dir="rtl">...</Card>   // Force RTL regardless of document dir
+<CodeSnippet dir="ltr" />    // Keep code LTR inside an RTL page
+```
+
+## CSS logical properties
+
+Always use CSS logical properties instead of physical ones so layout flips automatically with `dir`:
+
+| Avoid (physical)        | Use instead (logical)              |
+|-------------------------|------------------------------------|
+| `margin-left`           | `margin-inline-start`              |
+| `margin-right`          | `margin-inline-end`                |
+| `padding-left`          | `padding-inline-start`             |
+| `padding-right`         | `padding-inline-end`               |
+| `border-left`           | `border-inline-start`              |
+| `border-right`          | `border-inline-end`                |
+| `left: 0`               | `inset-inline-start: 0`            |
+| `right: 0`              | `inset-inline-end: 0`              |
+| `text-align: left`      | `text-align: start`                |
+| `text-align: right`     | `text-align: end`                  |
+| `flex-direction: row`   | (already logical — no change)      |
+
+```css
+/* Correct — flips automatically in RTL */
+.card {
+  padding-inline-start: var(--ds-spacing-md);
+  border-inline-end: 1px solid var(--ds-color-border-default);
+}
+```
+
+## IBM Plex Sans Arabic rendering
+
+`npx sdaia-ui@latest init` installs IBM Plex Sans Arabic and the body already uses it through `--ds-text-family-text`, for Arabic and Latin text alike. No separate Arabic font stack is needed (topic `typography`).
+
+## Icons
+
+Directional icons (arrows, chevrons, back / forward) mirror in RTL with `<DgaIcon data={arrowRight01Stroke} flipOnRtl />`. Don't add `rtl:-scale-x-100` by hand, and don't flip non-directional icons (search, settings, check).
+
+## LTR islands inside RTL documents
+
+Some content must remain LTR regardless of document direction:
+
+```tsx
+{/* Code blocks */}
+<pre dir="ltr"><code>{snippet}</code></pre>
+
+{/* URLs and email addresses */}
+<span dir="ltr">https://example.com</span>
+
+{/* Numeric data (phone numbers, IDs) */}
+<span dir="ltr">+966 50 000 0000</span>
+```
+
+## Tailwind RTL utilities
+
+With Tailwind v4 (installed by `sdaia-ui init`), use logical utilities:
+
+```html
+<!-- Logical padding (RTL-safe) -->
+<div class="ps-4 pe-2">...</div>   <!-- ps = padding-inline-start, pe = end -->
+
+<!-- RTL-conditional utilities -->
+<div class="ms-auto rtl:me-auto rtl:ms-0">...</div>
+```
+
+## Testing RTL
+
+1. Add `dir="rtl"` temporarily to `<html>` in DevTools
+2. Verify layout mirrors correctly without horizontal overflow
+3. Check icon directions (arrows, chevrons) — SDAIA icons are direction-aware
+4. Confirm text alignment follows reading direction
+
+## Common mistakes
+
+- Using `margin-left` / `padding-right` instead of logical equivalents
+- Hardcoding `text-align: left` — use `text-align: start`
+- Forcing `dir="ltr"` on the whole document when building an Arabic product
+- Forgetting `dir="ltr"` on code snippets and URLs inside an RTL page

package/knowledge/foundations/spacing.md

@@ -0,0 +1,27 @@
+# Spacing
+
+Spacing scale tokens. Use Tailwind `p-spacing-*` / `gap-spacing-*` utilities backed by these CSS variables.
+
+> Resolve any token live with the `get_tokens` tool.
+
+## Global
+
+| Token | CSS variable | Light | Dark | Description |
+| --- | --- | --- | --- | --- |
+| `spacing-3xl` | `var(--ds-spacing-3xl)` | `24px` | — | Spacious — section padding, between major content blocks. Desktop 32px. |
+| `spacing-xl` | `var(--ds-spacing-xl)` | `16px` | — | Standard spacing — button horizontal padding, form group gaps. Desktop 16px. |
+| `spacing-lg` | `var(--ds-spacing-lg)` | `12px` | — | Medium spacing — between related controls in a row, button padding vertical. Desktop 12px. |
+| `spacing-9xl` | `var(--ds-spacing-9xl)` | `96px` | — | Maximum content separation in hero/marketing layouts. Desktop 128px. |
+| `spacing-sm` | `var(--ds-spacing-sm)` | `6px` | — | Small spacing — tight icon-text gaps, compact form labels. Desktop 6px / Tablet/Mobile shrink. |
+| `spacing-md` | `var(--ds-spacing-md)` | `8px` | — | Default tight spacing — icon-to-label inside buttons, form field internal gaps. Desktop 8px. Most common small-spacing token. |
+| `spacing-xs` | `var(--ds-spacing-xs)` | `4px` | — | Very tight spacing — chip internal padding, dense menu items. Desktop 4px / Tablet/Mobile shrink. |
+| `spacing-6xl` | `var(--ds-spacing-6xl)` | `48px` | — | Hero section padding, generous content areas. Desktop 64px. |
+| `spacing-11xl` | `var(--ds-spacing-11xl)` | `160px` | — | Largest spacing token — full-screen hero margins, marketing landing pages. Desktop 192px. |
+| `spacing-10xl` | `var(--ds-spacing-10xl)` | `128px` | — | Extra-large layout spacing for marketing pages. Desktop 160px. |
+| `spacing-8xl` | `var(--ds-spacing-8xl)` | `80px` | — | Major section dividers, full-page spacing. Desktop 96px. |
+| `spacing-none` | `var(--ds-spacing-none)` | `0px` | — | No spacing (0px). Use to remove default gaps in flex/grid containers. |
+| `spacing-5xl` | `var(--ds-spacing-5xl)` | `40px` | — | Large section dividers, hero margins. Desktop 48px. |
+| `spacing-4xl` | `var(--ds-spacing-4xl)` | `32px` | — | Page margin spacing. Desktop 40px. |
+| `spacing-2xl` | `var(--ds-spacing-2xl)` | `20px` | — | Comfortable spacing — card internal padding, between cards in a list. Desktop 24px. |
+| `spacing-7xl` | `var(--ds-spacing-7xl)` | `64px` | — | Very large hero spacing, prominent feature blocks. Desktop 80px. |
+| `spacing-xxs` | `var(--ds-spacing-xxs)` | `2px` | — | Tightest spacing — between tightly-coupled elements: icon-text gap in dense controls. Desktop 2px / Tablet/Mobile shrink. |

package/knowledge/foundations/theme.md

@@ -0,0 +1,115 @@
+# SDAIA Theme Guide — dark mode and brands
+
+## Brands
+
+`sdaia-ui` ships six brands. They share every component and behaviour; a brand changes the palette, the font and some spacing and radii. Pick the brand at `init` (`npx sdaia-ui@latest init --brand <name>`, which also installs its font) and put its class on `<html>`:
+
+| Brand | Class on `<html>` | Font (Latin) |
+| --- | --- | --- |
+| `sdaia-dga` (default) | none | IBM Plex Sans Arabic |
+| `spectrum` | `brand-spectrum` | Inter |
+| `canvas` | `brand-canvas` | system font (SF Pro on Apple devices) |
+| `dessert` | `brand-dessert` | Roboto |
+| `dune` | `brand-dune` | Assistant |
+| `carbon` | `brand-carbon` | Inter (display), Roboto Mono (text) |
+
+Arabic text always renders in **IBM Plex Sans Arabic**, the official SDAIA typeface: `init` installs it for every brand and the other brands fall back to it for Arabic glyphs.
+
+```html
+<html>                                   <!-- sdaia-dga, light -->
+<html class="theme-dark">                <!-- sdaia-dga, dark -->
+<html class="brand-spectrum theme-dark"> <!-- spectrum, dark -->
+```
+
+> **Default to `sdaia-dga`** (no class) unless the user names another brand. Always use semantic tokens (`--ds-color-*`, `bg-*`, `text-*` utilities) so the brand and the theme resolve automatically. Never hardcode a palette hex. There is no `brand-private` class.
+
+## How theming works
+
+The SDAIA design system uses **class-based** theming — not `prefers-color-scheme` media queries.
+All semantic color tokens (`--ds-color-bg-*`, `--ds-color-text-*`, `--ds-color-border-*`) are
+defined for light mode by default and overridden when `.theme-dark` is present on `<html>`.
+
+`npx sdaia-ui@latest init` adds a class-based `dark:` variant to your global CSS, so Tailwind `dark:` utilities and the design tokens both follow `theme-dark` on `<html>`. Don't replace it with a `prefers-color-scheme` media query.
+
+> **Never hardcode hex colors.** Always use `var(--ds-color-*)` tokens so dark mode works automatically.
+
+## Enabling dark mode
+
+### 1 — Prevent flash on page load (FOUC fix)
+
+Add this inline script to `index.html` before `</head>`:
+
+```html
+<script>
+  (function() {
+    const stored = window.localStorage.getItem('theme');
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const isDark = stored ? stored === 'dark' : prefersDark;
+    document.documentElement.classList.toggle('theme-dark', isDark);
+  })();
+</script>
+```
+
+### 2 — React toggle hook
+
+```tsx
+const [dark, setDark] = useState(() =>
+  document.documentElement.classList.contains('theme-dark')
+);
+
+useEffect(() => {
+  document.documentElement.classList.toggle('theme-dark', dark);
+  window.localStorage.setItem('theme', dark ? 'dark' : 'light');
+}, [dark]);
+```
+
+Use this as the **only** theme toggle path. Do not add or remove a separate `dark` class, and do not keep another theme flag elsewhere in the app shell.
+
+### 3 — Toggle button (DS icons — not emoji)
+
+Use `@platformscode/icons` + `DgaIcon` — see `get_foundations` topic **`icon-usage`**. **Never** use ☀️/🌙 emoji or unrelated icons (e.g. `pizza01Stroke`).
+
+```tsx
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { darkModeStroke, sun01Stroke } from '@platformscode/icons';
+import { Button } from '@/components/ui/Button';
+
+<Button
+  variant="transparent"
+  size="md"
+  iconOnly
+  aria-label={dark ? 'Switch to light mode' : 'Switch to dark mode'}
+  leadingIcon={
+    <DgaIcon data={dark ? sun01Stroke : darkModeStroke} className="size-icon-sm" />
+  }
+  onClick={() => setDark((value) => !value)}
+/>
+```
+
+## Key semantic tokens
+
+Surfaces: `--ds-color-bg-canvas` (page), `--ds-color-bg-default` (cards, fields), `--ds-color-bg-raised` (popovers, menus). Text: `--ds-color-text-display` (headings), `--ds-color-text-paragraph` (body), `--ds-color-text-paragraph-muted` (secondary). Borders: `--ds-color-border-default`, focus `--ds-color-border-focus`. Look up exact light and dark values with `get_tokens`; use the variables, never the values.
+
+## Common mistakes
+
+- Hardcoding hex values (`color: #08060d`) — they ignore `.theme-dark`
+- Using `background-color: white` instead of `var(--ds-color-bg-default)`
+- Removing or editing the `@custom-variant dark` rule that `init` added
+- Building the page shell with hardcoded light classes such as `bg-white`, `text-black`, or `border-gray-200` while DS components use dark-aware tokens
+- Copying one component example labeled dark and another labeled light into the same screen without deciding the root theme first
+- Forgetting the flash-prevention inline script (causes FOUC on first paint in dark OS)
+- Setting dark mode via `prefers-color-scheme` CSS only — DS tokens do not respond to media queries
+- Toggling `.theme-dark` and a separate `dark` class independently
+
+## Why mixed dark and light UIs happen
+
+This usually means the app shell and the DS components are not using the same theme contract.
+
+- DS components often style themselves from semantic tokens, so they respond when `.theme-dark` exists on `<html>`.
+- Custom wrappers, sections, cards, and page backgrounds generated by the LLM often use hardcoded Tailwind colors like `bg-white`, `text-slate-900`, or `border-gray-200`, which stay light even in dark mode.
+- The reverse also happens: a dark custom shell can wrap light-mode components if the root `.theme-dark` class was never applied.
+
+To keep a consistent result, always theme both layers:
+
+- App shell: use DS tokens such as `var(--ds-color-bg-canvas)`, `var(--ds-color-bg-default)`, `var(--ds-color-text-default)`, and `var(--ds-color-border-default)`.
+- Components: let the installed DS components keep their built-in token-based styles.