@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/patterns/buttons-with-sdaia-touch.md

@@ -0,0 +1,34 @@
+# Sdaia Touch Buttons
+
+## Metadata
+- Component: Sdaia Touch Buttons
+- Slug: `buttons-with-sdaia-touch`
+- Category: Patterns
+- Install: `npx sdaia-ui@latest add buttons-with-sdaia-touch`
+- Import: `import { ButtonsWithSdaiaTouch } from '@/components/ui/ButtonsWithSdaiaTouch'`
+- Installed files: `ButtonHoverPattern.tsx`, `ButtonsWithSdaiaTouch.tsx`, `ButtonsWithSdaiaTouch.types.ts`, `ButtonsWithSdaiaTouch.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/sdaia-touch/sdaia-touch-buttons
+
+> **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 buttons-with-sdaia-touch`. It copies the source into your components folder (`components/ui/ButtonsWithSdaiaTouch/`, under `src/` when the project has one); import it as `@/components/ui/ButtonsWithSdaiaTouch`. 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
+This component takes no documented props beyond standard HTML attributes.
+
+## 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-button-bg-black-pressed)`
+- `var(--ds-color-button-bg-danger-primary-pressed)`
+- `var(--ds-color-button-bg-danger-secondary-hovered)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-button-bg-primary-pressed)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add buttons-with-sdaia-touch` (after `npx sdaia-ui@latest init`), then import `{ ButtonsWithSdaiaTouch }` from `@/components/ui/ButtonsWithSdaiaTouch`.
+- 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/patterns/sdaia-logo-animation.md

@@ -0,0 +1,35 @@
+# Sdaia Logo Animation
+
+## Metadata
+- Component: Sdaia Logo Animation
+- Slug: `sdaia-logo-animation`
+- Category: Patterns
+- Install: `npx sdaia-ui@latest add sdaia-logo-animation`
+- Import: `import { SdaiaLogoAnimation } from '@/components/ui/SdaiaLogoAnimation'`
+- Installed files: `BGSVG.tsx`, `SdaiaLogoAnimation.tsx`, `SdaiaLogoAnimation.types.ts`, `SdaiaLogoAnimation.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/sdaia-touch/logo-animation
+
+> **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 sdaia-logo-animation`. It copies the source into your components folder (`components/ui/SdaiaLogoAnimation/`, under `src/` when the project has one); import it as `@/components/ui/SdaiaLogoAnimation`. 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'` | — | Optional text direction for the wrapper. |
+| `width?` | `string \| number` | — | Number → px. String → any CSS length (`"70%"`, `"12rem"`, …). |
+| `height?` | `string \| number` | — | Number → px. String → `%`, `px`, `vh`, etc. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `width`, `height`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Optional text direction for the wrapper.
+
+## 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`).
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add sdaia-logo-animation` (after `npx sdaia-ui@latest init`), then import `{ SdaiaLogoAnimation }` from `@/components/ui/SdaiaLogoAnimation`.
+- 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/patterns/switch-with-sdaia-touch.md

@@ -0,0 +1,29 @@
+# Sdaia Touch Switch
+
+## Metadata
+- Component: Sdaia Touch Switch
+- Slug: `switch-with-sdaia-touch`
+- Category: Patterns
+- Install: `npx sdaia-ui@latest add switch-with-sdaia-touch`
+- Import: `import { SwitchWithSdaiaTouch } from '@/components/ui/SwitchWithSdaiaTouch'`
+- Installed files: `SwitchWithSdaiaTouch.tsx`, `SwitchWithSdaiaTouch.types.ts`, `SwitchWithSdaiaTouch.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/sdaia-touch/sdaia-touch-switch
+
+> **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 switch-with-sdaia-touch`. It copies the source into your components folder (`components/ui/SwitchWithSdaiaTouch/`, under `src/` when the project has one); import it as `@/components/ui/SwitchWithSdaiaTouch`. 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
+This component takes no documented props beyond standard HTML attributes.
+
+## 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-radius-full)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add switch-with-sdaia-touch` (after `npx sdaia-ui@latest init`), then import `{ SwitchWithSdaiaTouch }` from `@/components/ui/SwitchWithSdaiaTouch`.
+- 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/setup.md

@@ -0,0 +1,125 @@
+# SDAIA Design System — Project Setup Guide
+
+This matches the Installation guide on the docs site (https://ds.nacew.com/docs/installation) and `sdaia-ui` 1.11.0.
+
+> **HARD RULE — `sdaia-ui` is a CLI, not a runtime package.**
+> NEVER run `npm install sdaia-ui` and NEVER write `import … from 'sdaia-ui'`.
+> Run it with `npx sdaia-ui@latest …`: `init` once per project, then `add <name>` per component. The CLI copies each component's **source** into your project, and you import it from there.
+
+> **The installed files are yours.** Prefer props and composition over editing them, but you may change them. New releases never change them on their own: `npx sdaia-ui@latest diff` shows what changed upstream, and `npx sdaia-ui@latest update` applies it while **keeping files you edited** (it reports them; `--force` replaces them).
+
+## Supported setups
+
+- **Next.js** with the App Router or the Pages Router, with or without a `src/` folder.
+- **Vite + React** with TypeScript.
+
+Other frameworks are not supported yet.
+
+## Step 1 — Create a project (skip if you have one)
+
+Next.js (Node.js 20.9 or later). Keep TypeScript and the default `@/*` import alias; the App Router, Tailwind CSS and `src/` can be yes or no:
+
+```bash
+npx create-next-app@latest my-app
+cd my-app
+```
+
+Vite + React:
+
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm install
+```
+
+> Every later command runs in the **project root** (`my-app/`). Running `init` or `add` from a parent folder creates files in the wrong place.
+
+## Step 2 — Run `init`
+
+```bash
+npx sdaia-ui@latest init
+```
+
+`init` detects the setup and asks four questions, each pre-filled for your project (press Enter to accept, or run `init --yes` to accept them all):
+
+| Question | Default |
+| --- | --- |
+| Where should components be installed? | `src/components/ui` (or `components/ui` without `src/`) |
+| Where should utilities (cn.ts) be installed? | `src/lib` (or `lib`) |
+| Which CSS file is your global stylesheet? | Next.js App Router `app/globals.css` · Pages Router `styles/globals.css` · Vite `src/index.css` (under `src/` when the project has one) |
+| Which brand? | `sdaia-dga` (default). Others: `spectrum`, `canvas`, `dessert`, `dune`, `carbon` (`init --brand <name>`) |
+
+What `init` does:
+
+- Checks for Tailwind CSS v4 and offers to install it (components need v4).
+- Installs `@sdaia-ds/tokens` (pinned to the version the CLI was tested with), `@platformscode/icons`, `clsx`, `tailwind-merge`, `class-variance-authority` and the brand font (**IBM Plex Sans Arabic** for every brand, plus the brand's own font).
+- Adds the core styles to your global CSS: the tokens import, the type scale (`text-display-*`, `text-text-*`), the class-based `dark:` variant, and the responsive rules that switch sizes at **768px** (tablet) and **1280px** (desktop).
+- Imports the font files from the app entry: `app/layout.tsx` (App Router), `pages/_app.tsx` (Pages Router) or `src/main.tsx` (Vite).
+- Sets up the `@/` import alias (in Vite too), creates `cn` and saves the answers in `sdaia.config.json`.
+
+Do **not** add a Google Fonts `<link>` or a manual `@font-face`: `init` already installs and imports the font.
+
+## Step 3 — Add components
+
+```bash
+npx sdaia-ui@latest add button
+npx sdaia-ui@latest add button text-input card     # several at once
+npx sdaia-ui@latest add --all                       # every component
+```
+
+Use the slugs from `list_components` (the CLI also accepts the docs page names, e.g. `alerts`, `file-upload`, `datepicker`). `add` also installs the internal parts a component needs, its utility files (`sdaia-assets`, hooks) and any extra CSS it uses (glass surface, AI motion).
+
+## Step 4 — Import
+
+```tsx
+import { Button } from '@/components/ui/Button';
+import { TextInput } from '@/components/ui/TextInput';
+```
+
+The folder is the PascalCase component name. Without the `@/` alias, use a relative path to the same folder.
+
+## Step 5 — Arabic, dark mode and brands
+
+Set these on `<html>` so they apply before React renders:
+
+```html
+<html lang="ar" dir="rtl" class="theme-dark brand-spectrum">
+```
+
+- **Direction:** `lang="ar" dir="rtl"` for Arabic. Components follow the document direction; each also accepts `dir="rtl" | "ltr"` for a single subtree. Where to set it: `app/layout.tsx` (App Router), `<Html>` in `pages/_document.tsx` (Pages Router), `index.html` (Vite).
+- **Dark mode:** toggle the `theme-dark` class on `<html>`. It switches both the design tokens and Tailwind `dark:` styles. Use one theme per screen.
+- **Brand:** `sdaia-dga` needs no class. For another brand add the class `init` printed (`brand-spectrum`, `brand-canvas`, `brand-dessert`, `brand-dune`, `brand-carbon`). See `get_foundations` topic `theme`.
+
+## Step 6 — Icons
+
+Use `DgaIcon` with icon data from `@platformscode/icons` (installed by `init`). `DgaIcon` arrives with any component that uses icons; to use it on its own, run `npx sdaia-ui@latest add dga-icon`. It lives at `@/components/ui/DgaIcon`:
+
+```tsx
+import { DgaIcon } from '@/components/ui/DgaIcon';
+import { search01Stroke } from '@platformscode/icons';
+
+<span className="size-icon-sm">
+  <DgaIcon data={search01Stroke} />
+</span>
+```
+
+The SVG fills its parent; size it with a `size-icon-*` class: `xs` 12, `sm` 16, `lg` 20, `xl` 24, `2xl` 32, `3xl` 40 px (there is **no** `size-icon-md`). Directional icons flip in RTL with `<DgaIcon data={…} flipOnRtl />`. Rules and a name map: `get_foundations` topic `icon-usage`.
+
+Brand marks and bespoke glyphs (logos, flag, feedback emojis) come from `sdaia-assets`, which `add` installs at `@/components/ui/sdaia-assets` when a component needs it.
+
+## Step 7 — Keep components up to date
+
+```bash
+npx sdaia-ui@latest diff              # what changed upstream for your components
+npx sdaia-ui@latest update --all      # apply it; files you edited are kept
+npx sdaia-ui@latest update button --dry-run
+```
+
+Projects set up with `sdaia-ui` 1.6.6 or earlier kept no install record. Run once: `update --all --yes` (adds the font and core styles), review with `diff`, then `update --all --force` (replaces edited files — copy out changes you want to keep first).
+
+## Next
+
+- `list_components` / `search_components` — find a component slug.
+- `get_component_docs` — props, defaults, allowed values and accessibility for one component.
+- `get_foundations` — `theme`, `typography`, `responsive`, `rtl`, `accessibility`, `icon-usage`, token topics.
+- `get_tokens` — exact token values for custom layout around components.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@sdaia-ds/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.1",
+  "description": "MCP server for the SDAIA Design System — exposes accurate, source-derived component docs, design tokens, and setup guidance as tools for AI coding agents.",
+  "main": "dist/index.js",
+  "bin": {
+    "sdaia-ds-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "knowledge/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "tsx index.ts",
+    "generate": "tsx scripts/generate.ts",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "keywords": [
+    "mcp",
+    "sdaia",
+    "design-system",
+    "ai",
+    "copilot",
+    "tokens"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1"
+  },
+  "devDependencies": {
+    "@platformscode/icons": "0.0.11",
+    "@sdaia-ds/tokens": "2.0.3",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}