Features

• 87 Components — 52 base MUI v7 wrappers, 9 chart types, 7 banking domain components, 19 conversational UI components
• 250+ Design Tokens — Colors, typography, spacing, elevation, and more as CSS custom properties with atomic dark mode
• Conversational UI System — 19 purpose-built components for AI copilot interfaces with streaming, chain-of-thought, confidence scoring, and source attribution
• Figma Integration — Code Connect mapping and MCP 2-pass design-to-code workflow
• WCAG 2.1 AA — Playwright + axe-core accessibility testing, semantic ARIA, keyboard navigation, focus management
• Self-Hosted Everything — Bundled WOFF2 fonts, zero CDN dependencies — built for banking environments with strict CSP and air-gapped networks
• AI-First Code Generation — Design intelligence rules ensure Claude Code, Cursor, and other agents produce token-compliant, design-system-aware code automatically

Environment Support

| Environment | Version | |-------------|---------| | React | 19+ | | TypeScript | 5.9+ | | MUI | v7 (@mui/material) | | MUI X | v8 (@mui/x-date-pickers) | | Vite | 8+ | | Node.js | 18+ | | Browsers | Chrome, Edge, Firefox, Safari (last 2 versions) |

Install

# npm
npm install @ishaan-productdesign/core-design-system \
  @mui/material@^7 @emotion/react @emotion/styled react@^19 react-dom@^19 \
  @mui/icons-material@^7

# Optional peer dependencies (install as needed)
npm install @mui/x-date-pickers@^8 date-fns@^4    # Date/time pickers
npm install recharts@^3                             # Charts
npm install react-markdown remark-gfm remark-math \ # CUI markdown
  rehype-highlight rehype-katex                     
npm install @xyflow/react                           # CUI flow diagrams

Quick Start

import '@ishaan-productdesign/core-design-system/styles/theme.css';
import '@ishaan-productdesign/core-design-system/styles/fonts.css';
import { MuiThemeProvider } from '@ishaan-productdesign/core-design-system/theme';
import { Button, TextField, Box } from '@ishaan-productdesign/core-design-system';
import SearchOutlinedIcon from '@mui/icons-material/SearchOutlined';

function App() {
  return (
    <MuiThemeProvider>
      <Box sx={{ p: 'var(--spacing-24)', bgcolor: 'var(--primary-hover-bg)' }}>
        <TextField label="Search" variant="filled" />
        <Button variant="contained" startIcon={<SearchOutlinedIcon />}>
          Search
        </Button>
      </Box>
    </MuiThemeProvider>
  );
}

All 250+ design tokens and font stacks are now active. Every component renders with consistent styling out of the box.

Import Paths

// Base components (52)
import { Button, TextField, Select, Dialog } from '@ishaan-productdesign/core-design-system';

// Chart components (9)
import { BarChart, PieChart, LineChart } from '@ishaan-productdesign/core-design-system/charts';

// Business components (7)
import { FrequencyPicker, PageHeading } from '@ishaan-productdesign/core-design-system/business';

// Theme provider + dark mode
import { MuiThemeProvider, useColorMode } from '@ishaan-productdesign/core-design-system/theme';

// Icons — always import directly for tree-shaking
import SearchOutlinedIcon from '@mui/icons-material/SearchOutlined';

CSS — import once in your app entry point:

import '@ishaan-productdesign/core-design-system/styles/theme.css';
import '@ishaan-productdesign/core-design-system/styles/fonts.css';

What's in the Box

| Category | Count | What you get | |----------|-------|--------------| | Base Components | 52 | Button, TextField, Select, Autocomplete, DataGrid, DatePicker, TimePicker, Dialog, Drawer, Tabs, Stepper, Card, Tooltip, Snackbar, and more — all as MUI v7 wrappers with CoreDS defaults | | Chart Components | 9 | BarChart, LineChart, AreaChart, PieChart, ScatterChart, RadarChart, HeatmapChart, GaugeChart, Sparkline — themed Recharts wrappers with zoom/pan support | | Business Components | 7 | FrequencyPicker, ExpandableNavItem, PageHeading, Uploader, KycDocumentUploadDialog, Forms, TestForm — banking domain components | | CUI Components | 19 | Chat shells, streaming responses, chain-of-thought reasoning, flow diagrams, markdown rendering, confidence scores, source citations | | Design Tokens | 250+ | Colors, typography, spacing, elevation, radius, inputs, sidebar, charts, CUI — all as CSS custom properties | | Fonts | 2 families | Utile (headings) + Work Sans (body) — bundled as WOFF2, zero external requests | | Dark Mode | Full | Toggle .dark class on <html> — all 250+ tokens swap atomically |

Component Catalog

Base Components (52)

| Component | Description | |-----------|-------------| | Box | Foundation layout container | | Stack | Flexbox wrapper (row/column) | | Grid | CSS Grid wrapper | | Container | Centered max-width wrapper | | Paper | Elevation surface container |

| Component | Description | |-----------|-------------| | Button | Primary action trigger (contained/outlined/text) | | IconButton | Icon-only action button | | Fab | Floating Action Button | | ButtonGroup | Grouped button set | | ToggleButton | Stateful toggle button | | ToggleButtonGroup | Toggle button group | | Link | Navigation anchor |

| Component | Description | |-----------|-------------| | TextField | Text/password/number/email input (filled variant default) | | Select | Dropdown select with search | | Autocomplete | Typeahead with filtering | | Checkbox | Boolean selector with label | | Radio | Single-option selector | | Switch | Toggle switch control | | Slider | Range slider with track marks | | Rating | Star/icon rating picker | | InputAdornment | Prefix/suffix for inputs | | DatePicker / TimePicker / DateTimePicker / DateRangePicker | MUI X v8 date/time pickers |

| Component | Description | |-----------|-------------| | Typography | Text with semantic variants (h1-h6, body1-2, button, caption, overline) | | Card / CardContent / CardHeader / CardMedia / CardActions / CardActionArea | Card container system | | Accordion / AccordionSummary / AccordionDetails / AccordionActions | Expandable sections | | Chip | Dismissible tag or action chip | | Avatar / AvatarGroup | User image with fallback | | Badge | Numeric/icon overlay | | Divider | Visual separator | | Table (DataGrid) | Advanced data table with sorting/filtering/grouping | | List / ListItem / ListItemButton / ListItemIcon / ListItemText | List components | | ImageList / ImageListItem / ImageListItemBar | Image grid |

| Component | Description | |-----------|-------------| | Alert / AlertTitle | Success/warning/error/info messages | | LinearProgress | Horizontal progress bar | | CircularProgress | Spinner/circular progress | | Skeleton | Content loading placeholder | | Snackbar / SnackbarContent | Toast notification | | Tooltip | Hover help text | | Backdrop | Scrim overlay |

| Component | Description | |-----------|-------------| | AppBar / Toolbar | Top navigation bar | | Tabs / Tab | Tabbed navigation | | Drawer | Side navigation panel | | Breadcrumbs | Navigation hierarchy | | Stepper / Step / StepLabel / StepContent | Step indicator | | Pagination | Page navigator | | BottomNavigation | Mobile bottom nav | | SpeedDial / SpeedDialAction | Floating action menu |

| Component | Description | |-----------|-------------| | Dialog / DialogTitle / DialogContent / DialogActions | Modal dialog | | Popover | Positioned floating panel | | Menu / MenuItem / MenuList | Context/dropdown menu |

| Component | Description | |-----------|-------------| | FormControl | Field wrapper with validation state | | FormControlLabel | Label + checkbox/radio/switch | | FormGroup | Checkbox/radio group wrapper | | FormLabel | Form section label | | FormHelperText | Error/hint text | | InputLabel | TextField/Select label |

Chart Components (9)

Themed Recharts wrappers with design system colors, responsive containers, tooltips, and optional zoom/pan.

| Chart | Description | Key Props | |-------|-------------|-----------| | BarChart | Vertical/horizontal bars, stacked | stacked, horizontal, barRadius | | LineChart | Single/multi-series lines | smooth, strokeWidth, zoom/pan | | AreaChart | Filled area, stackable | stacked, gradient fill | | PieChart | Pie or donut | innerRadius (0 = pie, >0 = donut) | | ScatterChart | Scatter plot with optional bubbles | bubbleSize per series | | RadarChart | Multi-axis spider chart | Per-series color | | GaugeChart | Semi-circular arc gauge | threshold, min, max | | HeatmapChart | Color-coded matrix | scale (viridis/cool/warm/plasma) | | Sparkline | Compact inline trend | type (line/bar), no axes |

15-color categorical palette via getChartColors(), themed axis/tooltip/legend styles, and three zoom hooks (useIndexZoom, useNumericZoom, useHeatmapZoom) with a reusable ZoomToolbar.

Business Components (7)

Domain-specific components solving real banking workflow problems.

| Component | Description | |-----------|-------------| | PageHeading | Page title + description + action slot | | ExpandableNavItem | Sidebar nav with disclosure triangle | | FrequencyPicker | Statement/payment scheduling (daily/weekly/monthly/custom with business-day logic) | | KycDocumentUploadDialog | KYC document upload with drag-drop, file validation, and progress | | Uploader | General file upload widget | | Forms | Form layout patterns and fieldset templates | | TestForm | Demo form combining multiple input types |

Conversational UI (CUI) — 19 Components

A complete conversational interface system for AI copilot experiences in financial services. Purpose-built with regulatory AI explainability in mind — confidence scoring, source attribution, and chain-of-thought transparency are design system features, not afterthoughts.

Shell Containers

| Shell | Width | Use Case | |-------|-------|----------| | CuiDemoShell | 380px (expandable) | Sidebar copilot panel | | CuiChatShell | 880px content | Full-width chat interface | | CuiShellSplitView | Chat + 340px panel | Chat with context panel |

Copilot Modes

| Mode | Token | Color | Purpose | |------|-------|-------|---------| | Default | --primary | Navy (#303B82) | General assistance | | Planning | --secondary | Purple (#8246AF) | Strategy & workflow | | Research | --accent-2 | Teal (#319e96) | Data investigation |

Message Lifecycle

idle -> typing (2s, CuiTypingDots)
     -> skeleton (2s, CuiTypingSkeleton)
     -> streaming (8ms/char, CuiStreamingResponse)
     -> complete (toolbar + sources)

Full Component List

| Component | Description | |-----------|-------------| | CuiChatShell | Full unified chat with landing state, streaming, token usage | | CuiDemoShell | Resizable sidebar wrapper with header + input bar | | CuiShellSplitView | Chat + sliding context panel | | CuiInputBar | Input with mode toggle, animated gradient border, file attach, stop button | | CuiMessageBubble | User/assistant bubble with metadata toolbar | | CuiStreamingResponse | Streaming lifecycle manager (hook + components) | | CuiMarkdownRenderer | react-markdown + remark-gfm + LaTeX + syntax highlighting | | CuiFlowDiagram | React Flow with Dagre auto-layout, 7 color variants | | CuiChainOfThought | Thinking steps display (pending/running/complete) | | CuiLandingState | Welcome screen + suggestion card grid | | CuiSources | Numbered citation pills with URLs | | CuiConfidenceScore | Confidence badge (high/medium/low) | | CuiDataVizToggle | Chart/table view switcher | | CuiDotIndicator | Status dot (thinking/writing/complete) | | CuiTypingDots | Bouncing dot animation | | CuiTypingSkeleton | Shimmer placeholder lines | | CuiGeneratedFile | File download/preview card | | CuiUserSettings | Copilot preferences panel | | CuiMessage | Shell-level message renderer |

CUI Typography Rule: 12px is the absolute ceiling for all CUI prose. Heading hierarchy uses weight (600 = primary, 500 = secondary), not size.

Design Token System

All styling uses CSS custom properties from theme.css. Never hardcode hex or rgba values — color-mix(in srgb, var(--token) NN%, ...) deriving from tokens is allowed.

Token Categories (250+)

| Category | Examples | Count | |----------|---------|-------| | Core Surfaces | --background, --foreground, --card, --popover | 8 | | Primary | --primary, --primary-dark, --primary-hover-bg, --primary-outlined-border | 8 | | Secondary | --secondary, --secondary-dark, --secondary-hover-bg | 6 | | Accent | --accent, --accent-2 (teal) + state overlays | 6 | | Destructive | --destructive, --destructive-dark, --destructive-hover-bg | 6 | | Semantic | --warning-*, --success-*, --info-* (base + dark/light + filled) | 12 | | Action Overlays | --action-hover, --action-selected, --action-focus | 5 | | Typography Sizes | --text-h1 (96px) through --text-caption (12px) | 17 | | Font Families | --font-heading (Utile), --font-body (Work Sans), --font-mono (Fira Code) | 3 | | Font Weights | --font-weight-light (300) through --font-weight-bold (700) | 5 | | Spacing | --spacing-0 through --spacing-112 | 23 | | Border Radius | --radius (4px), --radius-button (999px pill) | 3 | | Elevation | --elevation-sm, --elevation-2, --elevation-8 | 4 | | Inputs | --input-filled-bg, --input-filled-hover-bg | 7 | | Chart Colors | --chart-blue through --chart-error (15 categorical) | 20 | | CUI | --cui-bubble-user-bg, --cui-thinking-bg, --cui-panel-width | 25 | | Sidebar | --sidebar-bg, --sidebar-foreground, --sidebar-primary | 8 | | Breakpoints | --breakpoint-xs (444px) through --breakpoint-xl (1536px) | 5 |

Full reference: guidelines/design-tokens.md

Dark Mode

import { useColorMode } from '@ishaan-productdesign/core-design-system/theme';

function ThemeToggle() {
  const { mode, toggleColorMode } = useColorMode();
  return <button onClick={toggleColorMode}>Current: {mode}</button>;
}

Toggle .dark class on <html> — all CSS variables switch automatically. No prop changes needed on any component. Trading desks and monitoring dashboards benefit from dark mode as an ergonomic necessity, not cosmetic choice.

Why This Architecture

The Problem

AI coding agents generate perfectly functional React. But without design system context, every screen comes out differently — hardcoded colors, inconsistent spacing, random font choices across 200+ banking backoffice screens. The fix isn't more Figma specs. It's teaching the AI your design language at the code level.

The Solution

Two architectural invariants enforce consistency at write-time, not in code review:

1. Wrapper Layer — Every MUI component has a wrapper at src/components/[Name]/[Name].tsx. Wrappers are the only files that import from @mui/material. All consumer code imports from the barrel export. This creates a single point of customization and isolates from upstream breaking changes.

Consumer Code  -->  CoreDS Wrapper  -->  @mui/material
                    (tokens + defaults)

2. Token System — All visual properties are CSS custom properties in src/styles/theme.css. Dark mode adds .dark to <html> and all 250+ tokens swap atomically. Hardcoded hex/rgba never enters the codebase because the rules catch it at generation time.

The Compound Effect

| What | Why it matters for banking | |------|---------------------------| | Single source of truth | Figma variables, CSS tokens, and MUI theme are synchronized. Change one, propagate everywhere. | | Token enforcement at write-time | One hardcoded color across 200+ screens creates a theming landmine. Token enforcement prevents drift across teams and years of maintenance. | | Self-hosted fonts | Zero CDN dependencies. Critical for environments with strict CSP, air-gapped networks, or regulated infrastructure. | | Auditable design fidelity | Pixel diff percentages and Figma references create an audit trail from design to production. Regulatory UI consistency is verifiable, not assumed. | | Domain components | FrequencyPicker, DataGrid with export, DateRangePicker — these solve banking problems, not generic ones. | | AI transparency by default | Chain-of-thought, confidence scoring, and source citation are built into the CUI system. Regulatory AI explainability is a design system feature. |

Use Cases by Stakeholder

Rapid Prototyping from Requirements — Write "transaction history screen with date range filters, account select, and CSV export." The design system's DataGrid, DateRangePicker, Select, and Button assemble into a running prototype in minutes. Stakeholders see a clickable app grounded in production components, not a static wireframe.

Figma-to-Code Fidelity Tracking — Automated pixel-diff against Figma references produces quantified answers: "1.2% deviation — PASS" or "12% deviation — FAIL with diff overlay." Regulatory UI consistency is auditable.

Agent-First Banking Prototypes — The CUI system provides 19 pre-built components for copilot prototypes. A working KYC chatbot, loan status copilot, or transaction query assistant is assembled in hours. Confidence scores and source attribution demonstrate audit-readiness to compliance teams before deployment approval.

Accessibility Compliance Reporting — Automated WCAG 2.1 AA audits via Playwright + axe-core produce evidence-based compliance reports, replacing manual checklists.

Token-Enforced Consistency — Writing sx={{ color: '#303B82' }} is immediately flagged. The correct form is sx={{ color: 'var(--primary)' }}. Hard-coded values never enter the codebase.

DataGrid for Complex Banking Data — Transaction ledgers with sorting, filtering, column pinning, row grouping, and CSV/Excel export — pre-configured and themed. No raw MUI DataGrid setup.

FrequencyPicker for Statement Scheduling — Handles daily (every/business-days-only), weekly (interval + repeat days), monthly (interval + repeat days), and defined frequencies (last day of month/quarter/year). Fully controlled with draft/save/reset semantics.

Building Banking Copilot Interfaces — 19 CUI components cover the full conversation lifecycle. useStreamingResponse() manages typing, skeleton, streaming, and complete phases. 28 CUI-specific tokens ensure visual consistency.

Visual Regression in the Dev Loop — Playwright screenshots pixel-diff against Figma references. Catches a 6px padding regression that would push transaction table columns off-screen or break print layouts used for audit trails.

Figma-to-Code with 1:1 Fidelity — Share a Figma URL. MCP extracts specs and maps every value to a CSS variable. Automated pixel-diff confirms the match. Replaces the manual QA cycle of "screenshot > compare > file ticket > fix > repeat."

Code Connect: Bidirectional Mapping — Figma component instances map directly to codebase equivalents via .figma.tsx files. When get_design_context is called, the response includes the exact import to use. No Slack messages needed.

Push Code Screens Back to Figma — When a developer builds a screen that intentionally diverges from the original design, generate_figma_design rebuilds it in Figma using proper design system tokens — not screenshots pasted into frames. Design documentation reflects production state.

Conversation Design Pattern Library — 8 CUI documentation pages cover every pattern: onboarding, feedback and errors, inline data, thinking and reasoning, suggestions, session history, and mode switching. Validated against Gricean maxims and Microsoft Human-AI Guidelines.

Dark Mode Verification — All 250+ tokens have dark mode equivalents. Automated screenshots of both themes diff against their respective Figma references. Dark mode regressions that only surface at 2 AM are caught in the dev loop.

Figma Integration

CoreDS maintains bidirectional sync with Figma through three channels:

| Channel | Direction | How it works | |---------|-----------|-------------| | Code Connect | Figma -> Code | .figma.tsx files map Figma components to codebase. Published via npx figma connect publish. | | MCP Workflow | Code -> Figma | 2-pass protocol: Pass 1 (get_design_context) extracts visual screenshot + specs. Pass 2 (get_metadata) resolves unclear tokens. | | generate_figma_design | Code -> Figma | Captures live pages and rebuilds them in Figma using design system tokens. |

Config: figma.config.json | Workflow: guidelines/figma-workflow.md

Testing

E2E with Playwright

40+ test files covering every component, all chart types, dark mode, theming, layout, and accessibility.

npm run test:e2e              # Headless
npm run test:e2e:headed       # Interactive browser
npx playwright test button    # Single component
npx playwright test --debug   # Inspector

Coverage:

• Component tests — 1 per component, rendering + interaction + states
• Chart tests (8) — rendering, data binding, tooltips
• Integration tests — dark mode toggle, theming, responsive layout, typography
• Accessibility — @axe-core/playwright for WCAG 2.1 AA compliance

Config: playwright.config.ts — 60s timeout, 2 workers in CI, screenshots on failure, HTML reporter.

Smoke Tests

npm run test:smoke            # ESM import validation
npm run test:smoke:consumer   # External package import test

For AI Coding Agents

This section is for Claude Code, Cursor, and other AI coding tools generating code in this project.

| Rule | Details | |------|---------| | Imports | Always from @ishaan-productdesign/core-design-system, never @mui/material directly | | Colors | Use var(--token-name). Never hardcode hex or rgba. | | Icons | MUI Outlined icons only: SearchOutlinedIcon, not SearchIcon | | Form inputs | variant="filled" by default on TextField, Select, Autocomplete, DatePicker | | Spacing | Use var(--spacing-N) tokens, not raw pixel values | | Typography | var(--font-heading) for headings, var(--font-body) for body text | | sx prop | CSS variables work in MUI's sx: sx={{ color: 'var(--primary)' }} | | CUI typography | 12px max for all conversational UI prose |

What AI-aware code looks like:

// Without CoreDS intelligence — works, but doesn't match the design system
import { Button } from '@mui/material';
<Button sx={{ backgroundColor: '#303B82', borderRadius: '4px' }}>Save</Button>

// With CoreDS intelligence — uses your design language automatically
import { Button } from '@ishaan-productdesign/core-design-system';
<Button variant="contained" sx={{ bgcolor: 'var(--primary)', borderRadius: 'var(--radius)' }}>Save</Button>

Full rules: guidelines/Guidelines.md | API: guidelines/component-api.md

Project Context Layer

CoreDS uses graphify to maintain a live structural map of the codebase. A post-commit hook rebuilds the graph after every commit, so the map never goes stale.

| Artifact | What it contains | |----------|------------------| | graphify-out/graph.html | Interactive force-directed graph — 2,846 nodes, 3,089 edges, 691 communities | | graphify-out/GRAPH_REPORT.md | Audit report — god nodes, surprising connections, cohesion scores, honesty-tagged edges | | adr-context/ | 4 Architecture Decision Records — ADR-001 (wrapper layer), ADR-002 (CSS custom properties), ADR-003 (FilledInput specificity), ADR-004 (accessible field DOM) |

Query the graph: /graphify query "your question" · Full rebuild after docs/image changes: /graphify --update

Development

npm install              # Install dependencies
npm run dev              # Vite dev server (component docs site)
npm run build:dist       # Full build (ESM + CJS + types + assets)
npm run build:lib        # Library build only
npm run build:types      # TypeScript declarations only
npm run typecheck        # tsc --noEmit
npm run lint             # ESLint
npm run lint:fix         # ESLint with auto-fix

Package Exports

| Export path | Contents | |-------------|----------| | . | 52 base components | | ./charts | 9 chart components | | ./business | 7 business components | | ./theme | MuiThemeProvider + useColorMode | | ./styles/theme.css | 250+ CSS custom properties | | ./styles/fonts.css | Bundled Utile + Work Sans fonts |

Tech Stack

| Layer | Packages | |-------|----------| | Core | React 19 + TypeScript 5.9 + Vite 8 + MUI v7 + MUI X v8 | | Charts | Recharts 3 | | CUI | react-markdown + remark-gfm + remark-math, rehype-highlight + rehype-katex, @xyflow/react (React Flow) | | Fonts | Utile (heading), Work Sans (body), Fira Code (monospace) — WOFF2 bundled | | Quality | Playwright + @axe-core/playwright (E2E + a11y) | | Figma | @figma/code-connect (component mapping) | | Routing | react-router (not react-router-dom) |

Multi-Tool Workflow

Two sources push to main — always git pull before starting work:

| Source | What it does | How to identify | |--------|-------------|-----------------| | Claude Code / Cursor | Code generation via terminal or VS Code | Standard conventional commits | | Figma Code Connect | Publishes .figma.tsx mapping files | Via npx figma connect publish |

Project Structure

src/
  components/
    [52 base component folders]/    # MUI v7 wrappers
    business/
      conversational-ux/            # 19 CUI components + types
      FrequencyPicker/              # Business components
      PageHeading/
      KycDocumentUploadDialog/
      ...
    charts/                         # 9 chart wrappers + zoom hooks + utilities
  styles/
    theme.css                       # 250+ CSS custom properties (light + dark)
    fonts.css                       # Bundled WOFF2 font imports
  app/docs/pages/                   # Documentation site + CUI demo pages
guidelines/                         # Specification documents (Guidelines, Design, CUI-Blueprint, component-api, figma-workflow, sections, design-tokens)
adr-context/                # 4 ADRs (wrapper layer, CSS vars, FilledInput, accessible field DOM)
graphify-out/                       # Auto-updated project graph (graph.html, GRAPH_REPORT.md, graph.json)
e2e/                                # 40+ Playwright test files

Versioning

CoreDS follows Semantic Versioning. Breaking changes to component APIs, token names, or import paths will only occur in major releases with migration guides.

Contributing

This is an internal design system maintained by the Temenos Product UX team. To contribute:

1. Create a feature branch from main
2. Follow the coding rules in guidelines/Guidelines.md
3. Ensure all E2E tests pass: npm run test:e2e
4. Open a pull request — tests run automatically via GitHub Actions

Changelog

See Releases for version history.