eha-design-system-ai 0.4.0 → 0.6.0

package/EHA_RULES.md

@@ -6,10 +6,47 @@ These rules apply to any AI agent using the `eha-design-system-ai` MCP server.
 
 1. All component imports from `eha-design-system` — never from `rsuite` directly
 2. Button always uses `variant` prop — `'primary' | 'secondary' | 'tertiary' | 'ghost'`
-3. `ThemeProvider` with the correct `brandId` prop always wraps the app root
-4. Missing components -> output comment, never build custom: `// MISSING: [Name] — not in EHA DS`
-5. Never hardcode brand colours — resolve via `brands[brandId].colorPrimitives.*`
-6. Logo assets must be static files at `/public/brands/[brand]/logo.svg` — never remote URLs
+3. `ThemeProvider` must use `brand`, never `brandId` (example: `<ThemeProvider brand="lomis">`)
+4. In `main.tsx`, import order is mandatory: `rsuite` CSS first, brand CSS second
+5. Sidenav item objects use `title`, never `label`
+6. Brand token access uses `brands[brand].colorPrimitives.*`, never `brands[brand].colors.*`
+7. Missing components -> output comment, never build custom: `// MISSING: [Name] — not in EHA DS`
+8. Never hardcode brand colours — resolve via `brands[brand].colorPrimitives.*`
+9. Logo assets must be static files at `/public/brands/[brand]/logo.svg` — never remote URLs
+
+## Required Setup Before UI Code
+
+Install these dependencies in consumer apps:
+
+```bash
+npm install eha-design-system rsuite @emotion/react @emotion/styled @mui/icons-material rxjs
+```
+
+For Vite projects, add aliases:
+
+```ts
+resolve: {
+  alias: {
+    'eha-design-system/styles': path.resolve(__dirname, 'node_modules/eha-design-system/styles'),
+    'rsuite/dist/rsuite.min.css': path.resolve(__dirname, 'node_modules/rsuite/dist/rsuite.min.css'),
+  },
+}
+```
+
+Main entry setup (order is critical):
+
+```tsx
+import 'rsuite/dist/rsuite.min.css';
+import 'eha-design-system/styles/brands/lomis.css';
+
+import { ThemeProvider } from 'eha-design-system';
+```
+
+Manrope font must be loaded in `index.html`, then applied globally:
+
+```css
+body { font-family: 'Manrope', system-ui, -apple-system, sans-serif; }
+```
 
 ## Brand Token Access
 

package/README.md

@@ -1,6 +1,6 @@
 # eha-design-system-ai
 
-AI compatibility layer for EHA Design System — enables LLMs to reliably generate UI components without hallucination.
+AI compatibility layer for EHA Design System, enables LLMs to reliably generate UI components without hallucination.
 
 ## What It Does
 
@@ -50,84 +50,84 @@ This is picked up automatically by Claude Code, opencode, Cursor, and other MCP-
 
 | Tool | Description |
 |------|-------------|
-| `get_brand` | **Call first for branded projects.** Returns ThemeProvider setup, CSS import, and brand-specific colour tokens |
+| `get_brand` | **Call first for branded projects.** Returns ThemeProvider setup 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_tokens` | Design tokens — pass `brandId` (or `brand`) 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
+## Critical Consumer Setup (Must Apply First)
+
+The design system does not bundle all required runtime styling dependencies. Install these in the consuming app:
 
-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**.
+```bash
+npm install eha-design-system rsuite @emotion/react @emotion/styled @mui/icons-material rxjs
+```
 
-### Available Brands
+For Vite projects, add aliases to avoid export-map failures for style imports:
+
+```ts
+import path from 'path';
+
+resolve: {
+  alias: {
+    'eha-design-system/styles': path.resolve(__dirname, 'node_modules/eha-design-system/styles'),
+    'rsuite/dist/rsuite.min.css': path.resolve(__dirname, 'node_modules/rsuite/dist/rsuite.min.css'),
+  },
+}
+```
 
-| Brand | Primary | Secondary | Tertiary | Use Case |
-|-------|---------|-----------|----------|----------|
-| `eha` | `#0090FC` | `#EBCB00` | `#003963` | Default — health programmes |
-| `etrac` | `#0090FC` | `#EBCB00` | `#003963` | Vaccination tracking |
-| `lomis` | `#0090FC` | `#EBCB00` | `#1E3A5F` | Logistics Management |
-| `reach` | `#522E1C` | `#E3C934` | `#003963` | Reach Data Portal |
+Load Manrope in `index.html` and apply it globally:
 
-> ⚠️ **Reach brand** has a significantly different visual identity — primary is **terracotta brown**, not blue. Links and interactive elements are also brown. Always use `ThemeProvider` and never hardcode colour values.
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
+```
 
-### Setup (Two Steps)
+```css
+body {
+  font-family: 'Manrope', system-ui, -apple-system, sans-serif;
+}
+```
 
-**Step 1 — Import the brand CSS at your app entry point (`main.tsx` or `App.tsx`):**
+In `main.tsx`, import order is mandatory:
 
 ```tsx
-// Choose your brand:
-import 'eha-design-system/styles/brands/eha.css';
-import 'eha-design-system/styles/brands/etrac.css';
+import 'rsuite/dist/rsuite.min.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`:**
+---
+
+## Multi-Brand Theming
+
+EHA Design System supports 4 brands. Each brand has its own colour token set. Spacing, typography, border radius, shadows, and z-index are **identical across all brands**.
+
+### Setup
+
+Wrap your app root with `ThemeProvider` and pass the `brand` prop (never `brandId`).
 
 ```tsx
+import 'rsuite/dist/rsuite.min.css';
+import 'eha-design-system/styles/brands/lomis.css';
+
 import { ThemeProvider } from 'eha-design-system';
 
 function App() {
   return (
-    <ThemeProvider brandId="lomis">
+    <ThemeProvider brand="lomis">
       <YourApp />
     </ThemeProvider>
   );
 }
 ```
 
-### Brand Colour Differences
-
-**eha / etrac** — identical palettes, differ in brand assets only:
-```
-primary:   #0090FC (blue)
-secondary: #EBCB00 (yellow)
-tertiary:  #003963 (dark navy)
-```
-
-**lomis** — different tertiary scale (navy blues):
-```
-primary:   #0090FC (blue)
-secondary: #EBCB00 (yellow)
-tertiary:  #1E3A5F (deep navy)
-tertiary scale: #EFF6FF → #1E3A5F (blue/indigo range)
-interactive.tertiary: #3B82F6
-```
-
-**reach** — completely different visual identity:
-```
-primary:   #522E1C (terracotta brown)
-secondary: #E3C934 (golden yellow)
-primary scale: earthy browns (#E4C2B1 → #311C11)
-links:     #422516 (brown, not blue)
-focus ring: #6F4C3A (dark brown)
-info colour: #6F4C3A / infoBg: #E4C2B1
-```
+Available brands: `eha` (default), `etrac`, `lomis`, `reach`.
 
 ---
 
@@ -163,7 +163,6 @@ console.log(tokens.colors.primary); // '#0090FC'
 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'
@@ -175,12 +174,16 @@ 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
+2. **Install setup dependencies in consumer app first** — `rsuite`, `@emotion/react`, `@emotion/styled`, `@mui/icons-material`, `rxjs`
+3. **All imports from `eha-design-system`** — never from `rsuite` directly
+4. **Button always uses `variant` prop** — `'primary' | 'secondary' | 'tertiary' | 'ghost'`
+5. **In `main.tsx`, import CSS in this order** — `rsuite` first, brand CSS second
+6. **ThemeProvider uses `brand` prop** — never `brandId`
+7. **Sidenav items use `title` key** — never `label`
+8. **Brand tokens use `brands[brand].colorPrimitives.*`** — never `brands[brand].colors.*`
+9. **Never hardcode brand colours** — use ThemeProvider + tokens
+10. **Missing components** → output `// MISSING: [Name] — not in EHA Design System`, do NOT build manually
+11. **For Login/Settings pages** → use `LoginTemplate` / `ProfileSettingsTemplate` first
 
 ---
 
@@ -210,7 +213,7 @@ console.log(reach.keyDifferences);  // array of what makes reach different
 | Dropdown | navigation | title, trigger, Dropdown.Item |
 | PageHeader | layout | title, subtitle, user, onAction |
 | Drawer | layout | open, placement, size, sub-components |
-| Accordion | layout | bordered, Accordion.Panel |
+| Accordion | layout | bordered, AccordionPanel |
 
 ## Full-Page Templates