eha-design-system-ai

AI compatibility layer for EHA Design System, enables LLMs to reliably generate UI components without hallucination.

What It Does

Provides an MCP (Model Context Protocol) server that gives AI coding agents structured access to:

• 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

Installation

# 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

Project Integration

Add .mcp.json to your project root:

{
  "mcpServers": {
    "eha-design-system": {
      "command": "npx",
      "args": ["eha-design-system-ai"]
    }
  }
}

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 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 (or brand) for brand-specific colours | | get_recipe | Pre-built layout patterns for common page types | | get_specs | Design implementation specs and QA constraints (14 curated specs) | | get_rules | Agent rules, import conventions, and constraints |

Critical Consumer Setup (Must Apply First)

The design system does not bundle all required runtime styling dependencies. Install these in the consuming app:

npm install eha-design-system rsuite @emotion/react @emotion/styled @mui/icons-material rxjs

For Vite projects, add aliases to avoid export-map failures for style imports:

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'),
  },
}

Load Manrope in index.html and apply it globally:

<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" />

body {
  font-family: 'Manrope', system-ui, -apple-system, sans-serif;
}

In main.tsx, import order is mandatory:

import 'rsuite/dist/rsuite.min.css';
import 'eha-design-system/styles/brands/lomis.css';

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).

import 'rsuite/dist/rsuite.min.css';
import 'eha-design-system/styles/brands/lomis.css';

import { ThemeProvider } from 'eha-design-system';

function App() {
  return (
    <ThemeProvider brand="lomis">
      <YourApp />
    </ThemeProvider>
  );
}

Available brands: eha (default), etrac, lomis, reach.

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_specs for implementation constraints and QA checks
7. Optionally call get_recipe for page-level layout patterns
8. Generate code using ONLY resolved components with correct brand setup

Programmatic Usage

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'

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. 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

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, AccordionPanel |

Full-Page Templates

| Template | Use Case | |----------|----------| | LoginTemplate | Full login/auth page — split screen layout | | ProfileSettingsTemplate | Full profile settings page with sidebar |

Peer Dependencies

{
  "eha-design-system": ">=0.2.2",
  "react": "^18.0.0 || ^19.0.0"
}

License

MIT