eha-design-system-ai 0.3.0 → 0.5.0

package/README.md

@@ -1,62 +1,199 @@
 # eha-design-system-ai
 
-MCP server for the EHA Design System. It exposes components, design tokens, recipes, and brand-specific setup data to AI agents through the Model Context Protocol.
+AI compatibility layer for EHA Design System, enables LLMs to reliably generate UI components without hallucination.
 
-## Tools
+## What It Does
 
-| Tool | Description |
-|------|-------------|
-| `get_brand` | Returns brand setup (`ThemeProvider`, CSS import), brand color scales, and key brand differences |
-| `get_components` | Lists available DS components, optionally filtered by category or search |
-| `get_component` | Returns full component details (props, usage, notes, Figma aliases) |
-| `resolve_figma` | Maps Figma node names to DS components and flags missing items |
-| `get_tokens` | Returns token data by category, with optional brand-specific colors |
-| `get_recipe` | Returns recipe code by id, or lists recipes by category |
-| `get_rules` | Returns AI guardrails and do/don't implementation rules |
+Provides an MCP (Model Context Protocol) server that gives AI coding agents structured access to:
 
-## Setup
+- **Component definitions** — Props, variants, usage examples, and Figma node name mappings for all 23 EHA DS components + 2 full-page templates
+- **Multi-brand theming** — Full token sets for all 4 brands: `eha`, `etrac`, `lomis`, `reach`
+- **Figma resolution** — Map design node names to exact code components before generating any code
+- **Design tokens** — Colors, spacing, typography, border radius, shadows per brand
+- **Layout recipes** — Pre-built patterns for dashboards, forms, tables, drawers, modals
+- **Agent rules** — Constraints that prevent AI from inventing props or building custom implementations
 
-```bash
-npm install
-npm run build
-```
+---
 
-## Run Locally
+## Installation
 
 ```bash
-npm run start
+# Use directly with npx (no install needed)
+npx eha-design-system-ai
+
+# Or install in your project
+npm install --save-dev eha-design-system-ai
 ```
 
-## MCP Config (Local Build)
+---
+
+## Project Integration
+
+Add `.mcp.json` to your project root:
 
 ```json
 {
   "mcpServers": {
     "eha-design-system": {
-      "command": "node",
-      "args": ["/absolute/path/to/eha-ai/dist/mcp/server.js"]
+      "command": "npx",
+      "args": ["eha-design-system-ai"]
     }
   }
 }
 ```
 
-## MCP Config (Published Package)
+This is picked up automatically by Claude Code, opencode, Cursor, and other MCP-compatible agents.
+
+---
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_brand` | **Call first for branded projects.** Returns ThemeProvider setup, CSS import, and brand-specific colour tokens |
+| `get_components` | List all components, filter by category or search term |
+| `get_component` | Full props, usage, and common mistakes for a specific component |
+| `resolve_figma` | Map Figma node names to DS components, flag MISSING ones |
+| `get_tokens` | Design tokens — pass `brandId` for brand-specific colours |
+| `get_recipe` | Pre-built layout patterns for common page types |
+| `get_rules` | Agent rules, import conventions, and constraints |
+
+---
+
+## Multi-Brand Theming
+
+EHA Design System supports 4 brands. Each brand has its own colour token set and CSS stylesheet. Spacing, typography, border radius, shadows, and z-index are **identical across all brands**.
+
+
+### Setup (Two Steps)
+
+**Step 1 — Import the brand CSS at your app entry point (`main.tsx` or `App.tsx`):**
+
+```tsx
+// Choose your brand:
+import 'eha-design-system/styles/brands/eha.css';
+import 'eha-design-system/styles/brands/etrac.css';
+import 'eha-design-system/styles/brands/lomis.css';
+import 'eha-design-system/styles/brands/reach.css';
+```
+
+**Step 2 — Wrap your app root with `ThemeProvider`:**
+
+```tsx
+import { ThemeProvider } from 'eha-design-system';
+
+function App() {
+  return (
+    <ThemeProvider brandId="lomis">
+      <YourApp />
+    </ThemeProvider>
+  );
+}
+```
+
+---
+
+## Agent Workflow
+
+When given a Figma page, the agent should:
+
+1. Call `get_brand` with the target brand ID
+2. Call `get_rules` to load constraints
+3. Call `resolve_figma` with all Figma node names
+4. Get confirmation on any MISSING components
+5. Call `get_component` for each resolved component
+6. Optionally call `get_recipe` for page-level layout patterns
+7. Generate code using ONLY resolved components with correct brand setup
+
+---
+
+## Programmatic Usage
+
+```typescript
+import { getAllManifests, getComponentManifest, tokens, brandConfigs } from 'eha-design-system-ai';
+
+// Get all components
+const all = getAllManifests();
+
+// Get a specific component
+const button = getComponentManifest('Button');
+
+// Access default (eha) tokens
+console.log(tokens.colors.primary); // '#0090FC'
+
+// Access brand-specific config
+const lomis = brandConfigs.lomis;
+console.log(lomis.primary);         // '#0090FC'
+console.log(lomis.tertiary);        // '#1E3A5F'
+console.log(lomis.cssImport);       // "import 'eha-design-system/styles/brands/lomis.css'"
+
+const reach = brandConfigs.reach;
+console.log(reach.primary);         // '#522E1C'
+console.log(reach.keyDifferences);  // array of what makes reach different
+```
+
+---
+
+## Core Rules for Agents
+
+1. **Call `get_brand` first** when building for a specific brand
+2. **Import brand CSS before `ThemeProvider`** — order matters
+3. **Never hardcode brand colours** — use ThemeProvider CSS custom properties
+4. **All imports from `eha-design-system`** — never from `rsuite` directly
+5. **Button always uses `variant` prop** — `'primary' | 'secondary' | 'tertiary' | 'ghost'`
+6. **Missing components** → output `// MISSING: [Name] — not in EHA Design System`, do NOT build manually
+7. **For Login/Settings pages** → use `LoginTemplate` / `ProfileSettingsTemplate` first
+
+---
+
+## Available Components
+
+| Component | Category | Key Props |
+|-----------|----------|-----------|
+| Button | input | variant, size, isLoading, fullWidth |
+| Input | input | label, helperText, error, fullWidth |
+| SelectPicker | input | data, label, error, block |
+| Checkbox + CheckboxGroup | input | size, CheckboxGroup label |
+| Radio + RadioGroup | input | RadioGroup name, value |
+| DatePicker | input | label, helperText, error |
+| Table | display | data, autoHeight, Table.Column, Table.Pagination |
+| MetricCard | display | value, label, icon, variant, breakdown |
+| Avatar | display | src, circle, Avatar.Group |
+| Badge | display | content, color |
+| Tag | display | color, closable, Tag.Group |
+| Modal | feedback | open, onClose, size, sub-components |
+| Notification + useToaster | feedback | type, header |
+| Loader | feedback | size, content, center, backdrop |
+| Progress | feedback | Progress.Line, Progress.Circle |
+| Sidenav | navigation | expanded, items, logo, activeKey |
+| Tabs | navigation | defaultActiveKey, Tabs.Tab |
+| Breadcrumb | navigation | Breadcrumb.Item |
+| Steps | navigation | current, status, Steps.Item |
+| Dropdown | navigation | title, trigger, Dropdown.Item |
+| PageHeader | layout | title, subtitle, user, onAction |
+| Drawer | layout | open, placement, size, sub-components |
+| Accordion | layout | bordered, Accordion.Panel |
+
+## Full-Page Templates
+
+| Template | Use Case |
+|----------|----------|
+| `LoginTemplate` | Full login/auth page — split screen layout |
+| `ProfileSettingsTemplate` | Full profile settings page with sidebar |
+
+---
+
+## Peer Dependencies
 
 ```json
 {
-  "mcpServers": {
-    "eha-design-system": {
-      "command": "npx",
-      "args": ["eha-design-system-ai"]
-    }
-  }
+  "eha-design-system": ">=0.2.2",
+  "react": "^18.0.0 || ^19.0.0"
 }
 ```
 
-## Sync Version Marker From DS
+---
 
-```bash
-npm run sync
-```
+## License
 
-This updates the `eha-design-system@x.y.z` version reference in the token source file to match the installed package version.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eha-design-system-ai",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI compatibility layer for EHA Design System — enables LLMs to reliably generate UI without hallucination",
   "type": "module",
   "main": "./dist/index.cjs",