Trinity Design System

Enterprise component platform built on MUI v9 for Trinity LifeSciences. Provides 100+ accessible React components, a 3-tier design token system, 35+ AI-specific components, 17 chart types, 18 custom hooks, and a CSS-only package for non-React consumers.

Table of Contents

• Key Capabilities
• Architecture
• Packages & Entry Points
• Installation
• Quick Start
• Component Catalog
  • Navigation
  • Layout
  • AI
  • Data Display
  • Input & Forms
  • Feedback
  • Charts
  • Icon System
• Hooks
• Accessibility
• Design Tokens
• Theme Presets
• CSS-Only Usage
• Storybook
• Development
• Documentation
• License

Key Capabilities

| Capability | Details | |---|---| | 100+ Components | Navigation, layout, AI, data display, inputs, feedback, charts | | 35+ AI Components | InsightEngine, ChatThread, ChainOfThought, voice input, explainability, sources, personas | | 17 Chart Types | Line, bar, area, pie, donut, scatter, bubble, radial, gauge, composed, sparkline | | 3-Tier Design Tokens | Base → Semantic → Component tokens with CSS variable output | | Dark Mode | Automatic light/dark themes with WCAG 2.1 AA color contrast | | 3 Theme Presets | CRM (compact), Portal (accessible), Analytics (data-viz) | | 18 Custom Hooks | Debounce, clipboard, breakpoints, focus trap, roving tabindex, and more | | TypeScript-First | 200+ exports with full type definitions | | CSS-Only Package | Angular, Vue, and static HTML support via CSS variables | | 80+ Brand Assets | Gradient icons, background images, logos | | Bundle Governance | Size-limit enforced: core ≤50KB, main ≤200KB | | Accessibility | axe-core testing, eslint-plugin-jsx-a11y, ARIA hooks, skip links, focus traps |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Design Tokens (tokens.ts)                │
│            Base → Semantic → Component (2,700 lines)         │
└──────────────┬──────────────────────────┬────────────────────┘
               │                          │
               ▼                          ▼
┌──────────────────────────┐  ┌─────────────────────────────────┐
│    MUI Theme Layer        │  │   CSS Variables Build            │
│  lightTheme / darkTheme   │  │   generate-css-from-tokens.ts    │
│  + 3 preset themes        │  │   trinity.css / trinity-base.css │
└──────────┬───────────────┘  └──────────┬──────────────────────┘
           │                             │
           ▼                             ▼
┌──────────────────────────┐  ┌─────────────────────────────────┐
│  @trinityui/design-system │  │ @trinityui/design-system-css     │
│  React + MUI Components   │  │ Angular / Vue / Static HTML      │
└──────────────────────────┘  └─────────────────────────────────┘

Packages & Entry Points

| Package / Import | Exports | Use Case | |---|---|---| | @trinityui/design-system | 200+ | Full API — all components, hooks, tokens, utilities | | @trinityui/design-system/essentials | 16 | Quick-start — theme + core components | | @trinityui/design-system/theme | ~10 | Theme utilities only (tree-shakeable) | | @trinityui/design-system/tokens | ~30 | Design tokens only (tree-shakeable) | | @trinityui/design-system/data-table | 3 | DataTable + AG Grid Enterprise license setup | | @trinityui/design-system/css | — | CSS file from the React package | | @trinityui/design-system-css | — | Standalone CSS-only package for non-React apps |

Installation

React package

pnpm add @trinityui/design-system react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled

Optional dependencies (install only if using these features):

pnpm add recharts              # Charts
pnpm add @mui/x-date-pickers dayjs  # DatePicker

CSS-only package

pnpm add @trinityui/design-system-css

Commercial licensing: For MUI, AG Grid, or Syncfusion license procurement/renewal, contact Arun Manoharan, Rahul Desai, or Sangeetha before production use.

Quick Start

1. Wrap your app with the theme

import { ThemeProvider, CssBaseline } from '@mui/material';
import { lightTheme } from '@trinityui/design-system';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider theme={lightTheme}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}

2. Import strategy

Use MUI for standard UI primitives. Use Trinity for domain-specific components, tokens, and hooks.

// MUI primitives
import { Button, Card, TextField } from '@mui/material';

// Trinity components
import { StatusIndicator, Toast, useToast } from '@trinityui/design-system';

3. Dark mode

import { lightTheme, darkTheme } from '@trinityui/design-system';

<ThemeProvider theme={isDarkMode ? darkTheme : lightTheme}>
  <CssBaseline />
  <App />
</ThemeProvider>

For the full getting-started guide, see docs/QUICK_START.md.

Component Catalog

Navigation (6 components)

| Component | Import | Description | |---|---|---| | TopNavHeader | @trinityui/design-system | Primary navigation header with search, client switcher, and user menu | | TopNavWithSidebar | @trinityui/design-system | Full layout with collapsible sidebar navigation | | Footer | @trinityui/design-system | Page footer — light and dark variants, compact 40px height | | SearchBar | @trinityui/design-system | Header search bar primitive with suggestion support | | ClientMenu | @trinityui/design-system | Client/tenant switcher dropdown | | AppsMenu | @trinityui/design-system | Application launcher grid menu |

Also exports: TrinityLogo, UserMenu, HeaderActions, and 14 navigation type definitions.

Layout (7 components)

| Component | Import | Description | |---|---|---| | AppLayout | @trinityui/design-system | Primary app shell — nav + content + optional AI panel | | PageHeader | @trinityui/design-system | Page header with breadcrumbs, title, and actions | | SplitPane | @trinityui/design-system | Resizable split view (horizontal/vertical) | | DockLayout | @trinityui/design-system | Dockable panel layout with configurable zones | | ResizablePanel | @trinityui/design-system | Standalone resizable side panel | | InsightEnginePanel | @trinityui/design-system | AI insight panel designed for AppLayout integration | | LandingPage | @trinityui/design-system | Pre-built landing page template |

Also exports: 3 page templates (DashboardTemplate, ListDetailTemplate, SettingsTemplate).

AI (35+ components)

The largest component category — a full suite for building AI-powered experiences.

AI Containers & Orchestration

| Component | Description | |---|---| | InsightEngine | Top-level AI experience orchestrator | | ChatThread | Scrollable conversation thread with message grouping | | ChatHeader | Chat view header with mode switching | | ChatHistoryList | Navigable list of past conversations |

AI Input

| Component | Description | |---|---| | InsightEngineInput | Primary AI query input with context awareness | | AIVoiceOverlay | Voice input overlay with transcription | | AIListeningIndicator | Animated listening state indicator | | PredictiveTextInput | AI-powered autocomplete text input (OpenAI-compatible) | | AIChatInput | Lightweight chat input primitive | | AIQuickReply | Quick-reply suggestion chips |

AI Rendering & Explainability

| Component | Description | |---|---| | AIResponseRenderer | Renders structured AI responses (text, tables, charts, actions) | | AITextBlock | Styled text block for AI output with streaming support | | AIChainOfThought | Multi-phase reasoning visualization (understand → plan → execute → output) | | AIExplainability | Confidence scores and explainability panel | | AISource / AISourcesSection / AISourcesPanel | Source citations — individual, grouped, and full panel views | | AIRelatedQuestions | Suggested follow-up questions |

AI Messages & Avatars

| Component | Description | |---|---| | AIMessage | AI-authored message bubble with actions | | UserMessage | User-authored message bubble | | AIChatMessage | Lightweight chat message primitive | | AIAvatar | AI bot avatar (animated) | | UserAvatar | User avatar for chat contexts | | AILabel | "AI-generated" badge/label (multiple sizes and variants) |

AI Actions & Layout

| Component | Description | |---|---| | AISuggestedAction / AICircularAction / AIActionsGroup | AI-suggested action buttons and groups | | AIContainer | Themed container for AI content | | AIExpandableSection | Collapsible section for AI detail panels | | AIPersonaCard | AI persona/agent identity card | | GradientText / GradientIconBadge | Visual flourishes for AI UI | | StatCard | KPI stat card for AI dashboards | | AIShimmer | Shimmer loading state for AI content | | AITypingIndicator | Animated typing indicator |

All AI components import from @trinityui/design-system. AI-specific design tokens available via aiTokens.

Data Display (8 components)

| Component | Import | Description | |---|---|---| | DataTable | @trinityui/design-system/data-table | AG Grid Enterprise powered — sorting, filtering, grouping, pivot, server-side row models | | SimpleTable | @trinityui/design-system | Lightweight table for simple data (no AG Grid dependency) | | DataCard | @trinityui/design-system | KPI/metric card with trend indicator and sparkline | | DiffViewer | @trinityui/design-system | Side-by-side or unified diff viewer | | Timeline | @trinityui/design-system | Vertical timeline with status indicators | | TreeView | @trinityui/design-system | Hierarchical tree view with expansion and selection | | TransferList | @trinityui/design-system | Dual-list transfer component with search and bulk actions | | StatusIndicator / StatusLegend | @trinityui/design-system | Unified status display (success/warning/error/info) + legend |

DataTable setup:

import { DataTable, setAgGridEnterpriseLicenseKey } from '@trinityui/design-system/data-table';

// Set license key once at app bootstrap
setAgGridEnterpriseLicenseKey('<YOUR_KEY>');

App Layout

AppLayout is the recommended shell for React applications that need Trinity branding, sidebar navigation, user context, and optional AI panel integration.

import * as React from 'react';
import HomeOutlinedIcon from '@mui/icons-material/HomeOutlined';
import BarChartIcon from '@mui/icons-material/BarChart';
import SettingsOutlinedIcon from '@mui/icons-material/SettingsOutlined';
import { AppLayout, type NavItem } from '@trinityui/design-system';

const navItems: NavItem[] = [
  { id: 'home', label: 'Home', icon: <HomeOutlinedIcon /> },
  { id: 'analytics', label: 'Analytics', icon: <BarChartIcon /> },
  { id: 'settings', label: 'Settings', icon: <SettingsOutlinedIcon /> },
];

export default function AppShell() {
  const [selectedNavItem, setSelectedNavItem] = React.useState('home');

  return (
    <AppLayout
      navStyle="sidebar"
      aiTrigger="none"
      companyName="Portfolio Console"
      navItems={navItems}
      selectedNavItem={selectedNavItem}
      onSelectedNavItemChange={setSelectedNavItem}
      user={{ name: 'Jane Doe', email: '[email protected]', initials: 'JD' }}
    >
      <main>Page content</main>
    </AppLayout>
  );
}

Optional header regions can be disabled when the consuming app owns those controls elsewhere:

<AppLayout
  navStyle="sidebar"
  showSearch={false}
  showClientSelector={false}
  showSidebarToggle={false}
>
  <main>Page content</main>
</AppLayout>

| Prop | Default | Description | |---|---:|---| | showSearch | true | Shows the desktop search field and mobile search action. | | showClientSelector | true | Shows the client selector dropdown in the header. | | showSidebarToggle | true | Shows the sidebar hamburger/collapse button in sidebar mode. |

Input & Forms (18+ components)

| Component | Import | Description | |---|---|---| | Autocomplete | @trinityui/design-system | Full-featured autocomplete — async loading, pagination, sortable chips, virtualization | | VirtualizedAutocomplete | @trinityui/design-system | Virtualized variant for large option lists | | Combobox | @trinityui/design-system | Accessible combobox with keyboard navigation | | SearchInput | @trinityui/design-system | Standalone search input with suggestion dropdown | | ClearableTextField | @trinityui/design-system | Text field with integrated clear button | | ChipsInput | @trinityui/design-system | Tag/chip entry input with validation | | MentionsInput | @trinityui/design-system | @mention-enabled text input | | FileUpload / UploadDropZone | @trinityui/design-system | Drag-and-drop file upload with progress | | CommandPalette | @trinityui/design-system | Cmd+K style command palette with fuzzy search | | FilterBar | @trinityui/design-system | Multi-filter toolbar with presets and saved filters | | NestedMenu | @trinityui/design-system | Multi-level nested menu | | Cron | @trinityui/design-system | Visual cron expression builder | | Carousel | @trinityui/design-system | Content carousel with transition effects | | Popper | @trinityui/design-system | Positioning utility component |

Form Utilities

import { FormProvider, useForm, useFormField } from '@trinityui/design-system';

// Built-in validators
import { required, email, minLength, maxLength, pattern, min, max, custom } from '@trinityui/design-system';

FormProvider gives you form state management with composable validation — no additional form library required.

Async Autocomplete Example

import { Autocomplete, type AutocompleteAsyncRequest } from '@trinityui/design-system';

const loadUsers = async ({ search, page, pageSize, signal }: AutocompleteAsyncRequest) => {
  const res = await fetch(`/api/users?q=${encodeURIComponent(search)}&page=${page}&pageSize=${pageSize}`, { signal });
  const data = await res.json();
  return { options: data.items, hasMore: data.hasMore, nextPage: page + 1 };
};

<Autocomplete
  name="users"
  label="Users"
  options={[]}
  multiple
  value={[]}
  onHandleChange={(next) => setUsers(next)}
  labelProperty="name"
  valueProperty="id"
  async={{ dataSource: loadUsers, paginate: true, pageSize: 25, debounceMs: 250 }}
/>

Predictive Text Input (OpenAI via Azure Function)

import { PredictiveTextInput, createOpenAIPredictor } from '@trinityui/design-system';

const predictor = createOpenAIPredictor({ endpoint: '/api/predictive-text', maxSuggestions: 5 });

<PredictiveTextInput label="Prompt" value={value} onChange={setValue} onPredict={predictor} />

See the Azure Function template for the backend.

Feedback (7 components)

| Component | Import | Description | |---|---|---| | Modal | @trinityui/design-system | Modal dialog with size variants and accessible focus management | | ConfirmDialog | @trinityui/design-system | Confirm/cancel dialog (also available via useConfirmDialog hook) | | ToastProvider / Toast | @trinityui/design-system | Toast notification system (wrap app in ToastProvider, trigger via useToast) | | IllustratedMessage | @trinityui/design-system | Empty state / error illustrated message | | Tour | @trinityui/design-system | Guided product tour with step-by-step highlights | | GoToTop | @trinityui/design-system | Scroll-to-top floating button |

Charts (17 components)

All charts are Recharts-based with Trinity theming applied automatically.

| Component | Description | |---|---| | LineChart | Line/time-series chart | | BarChart | Vertical/horizontal bar chart | | AreaChart | Filled area chart | | PieChart | Pie chart | | DonutChart | Donut variant | | ScatterChart | Scatter plot | | BubbleChart | Bubble chart | | RadialBarChart | Radial/polar bar chart | | GaugeChart | Gauge/meter chart | | ComposedChart | Mixed line + bar + area chart | | Sparkline | Inline mini chart for data cards | | ChartWrapper | Chart container with consistent sizing | | CustomTooltip / SimpleTooltip | Chart tooltip components | | CustomLegend / InteractiveLegend / PieLegend | Chart legend components |

All import from @trinityui/design-system. Full type definitions for DataPoint, SeriesConfig, AxisConfig, and chart-specific props.

Icon System

import { Icon, IconProvider } from '@trinityui/design-system';

// Wrap with IconProvider to set the active icon library
<IconProvider library="feather">
  <Icon name="check" size="md" />
</IconProvider>

Supports multiple icon libraries via IconProvider. Six intent-based sizes: inline (14px), xs (16px), sm (18px), md (20px), lg (24px), display (36px).

Hooks (18)

All hooks import from @trinityui/design-system.

| Hook | Description | |---|---| | useDebounce | Debounce a value by delay | | useDebouncedCallback | Returns a debounced callback function | | useClipboard | Copy text to clipboard with success feedback | | useLocalStorage | Persist state to localStorage with SSR safety | | useTrinityBreakpoints | Responsive flags: isMobile, isTablet, isDesktop, isLargeDesktop | | useToggle | Boolean toggle: [value, toggle, setValue] | | usePrevious | Access the previous render's value | | useOnClickOutside | Detect clicks outside a ref element | | useKeyPress | Detect a specific key press | | useInterval | Declarative setInterval with cleanup | | useFocusTrap | Trap keyboard focus within a container (accessibility) | | useReducedMotion | Detect prefers-reduced-motion user preference | | useAriaLive | Manage ARIA live region announcements for screen readers | | useRovingTabIndex | Arrow-key navigation for composite widgets | | useConfirmDialog | Imperatively open confirmation dialogs | | useToast | Show toast notifications (requires ToastProvider) | | useTrinityPalette | Access Trinity semantic palette from the current theme | | useFlowAutoLayout | Auto-layout for React Flow / XYFlow diagrams |

Accessibility

Trinity targets WCAG 2.1 AA compliance. The system provides:

| Feature | Details | |---|---| | Automated testing | vitest-axe (axe-core) a11y tests, dedicated test:a11y script | | Linting | eslint-plugin-jsx-a11y enforced across all components | | Storybook addon | @storybook/addon-a11y for interactive accessibility auditing | | ARIA hooks | useFocusTrap, useAriaLive, useRovingTabIndex, useReducedMotion | | Skip links | SkipLink component for keyboard-first navigation | | Accessible colors | accessibleCombinations — pre-validated WCAG AA text/background pairs | | Contrast utilities | getContrastRatio(), validateAccessibility(), meetsWCAG() | | Visual hiding | VisuallyHidden component for screen-reader-only content |

import { accessibleCombinations } from '@trinityui/design-system';

// Pre-validated WCAG AA pairs
<Box sx={{
  backgroundColor: accessibleCombinations.whiteOnNavy.bg,
  color: accessibleCombinations.whiteOnNavy.text,
}}>
  Guaranteed 4.5:1+ contrast ratio
</Box>

For the full accessibility guide and component checklist, see docs/ACCESSIBILITY.md and docs/COMPONENT_A11Y_CHECKLIST.md.

Design Tokens

Trinity uses a 3-tier token architecture (2,700+ lines) spanning colors, spacing, typography, shadows, motion, z-index, border radius, opacity, breakpoints, and effects.

Token Tiers

| Tier | Purpose | Example | |---|---|---| | Base | Raw primitive values | baseTokens.colors.navy[900] → #050742 | | Semantic | Contextual meaning | semanticTokens.colors.interactive.primary | | Component | Component-level defaults | componentTokens.card.borderRadius → 12px |

Token Coverage

| Category | What's included | |---|---| | Colors | 6 brand palettes (navy, purple, indigo, coral, azure, gray) with full shade ranges | | Semantic colors | Brand, text (11 variants), background (8), surface (7), border (6), interactive (5), status (4 × 3) | | Spacing | 20-step scale (0–32), component spacing, layout spacing with dimensions, density scale | | Typography | 10 sizes, 6 weights, 6 line heights, 6 letter spacings, semantic scales (display/heading/body/label) | | Border radius | 9-step scale (none → 9999px), semantic radius (button, input, card, modal, badge, avatar, chip, tooltip) | | Shadows | 8 levels + semantic (card, dropdown, modal, button, input), effect-based (surface, dialog, inset) | | Motion | 7 durations (fastest → slowest) + 7 easings (linear, bounce, elastic, etc.) | | Z-index | 7 numeric levels + 7 semantic (dropdown, sticky, modal, tooltip) | | Effects | Overlay, onDark states, focus rings, status indicators |

Usage

import { baseTokens, semanticTokens, componentTokens } from '@trinityui/design-system/tokens';

All tokens are also available as CSS variables:

var(--trinity-color-navy-900)     /* base */
var(--trinity-card-bg)            /* semantic */
var(--trinity-switch-track-height) /* component */

For token usage rules, see docs/TOKEN_USAGE_RULES.md.

Theme Presets

Three pre-configured theme presets for different product contexts:

| Preset | Light / Dark | Use Case | |---|---|---| | CRM | crmLightTheme / crmDarkTheme | Compact tables, dense forms, high information density | | Portal | portalLightTheme / portalDarkTheme | Large touch targets, accessible sizing, customer-facing | | Analytics | analyticsLightTheme / analyticsDarkTheme | Data visualization optimized, chart-friendly palette |

import { crmLightTheme, crmDarkTheme } from '@trinityui/design-system';

<ThemeProvider theme={isDarkMode ? crmDarkTheme : crmLightTheme}>
  <App />
</ThemeProvider>

You can also create custom presets with createTrinityThemePreset().

CSS-Only Usage

For Angular, Vue, or static HTML projects:

/* Option 1: package import */
@import '@trinityui/design-system-css';

/* Option 2: direct file path */
@import 'node_modules/@trinityui/design-system-css/dist/trinity.css';

<!-- Dark mode: add data-theme attribute -->
<html data-theme="dark">

All design tokens are exposed as --trinity-* CSS variables. See the CSS package README for the full variable reference.

Storybook

Interactive component documentation with live controls, dark mode toggle, and accessibility audits:

pnpm run start        # Opens at http://localhost:6006

93 stories covering every component with:

• Live prop controls and variant previews
• Dark mode toggle for all components
• Accessibility audit panel (axe-core integration)
• Code examples with copy-to-clipboard
• Autodocs — auto-generated API documentation from TypeScript types

Development

pnpm install          # Install dependencies
pnpm run start        # Storybook dev server (:6006)
pnpm run dev          # Vite dev server (:5173)
pnpm run build        # TypeScript + Vite production build
pnpm run test         # Run all tests
pnpm run test:a11y    # Run accessibility tests only
pnpm run lint         # ESLint
pnpm run lint:tokens  # Token usage rule validation
pnpm run size         # Check bundle size limits

Release and Publishing

• Push to main triggers publish workflows for both @trinityui/design-system and @trinityui/design-system-css
• Version is auto-bumped if the current version is already published
• CHANGELOG.md is generated during the release workflow

Documentation

| Document | Description | |---|---| | Quick Start | 5-minute getting-started guide | | Developer Guide | Comprehensive development reference | | Accessibility | WCAG 2.1 AA compliance guide | | Component A11y Checklist | Per-component accessibility requirements | | Token Usage Rules | When and how to use each token tier | | Storybook Standards | Story authoring conventions | | Testing Strategy | Unit, a11y, and visual regression testing | | MUI Compatibility | MUI version support matrix | | Integrating into Existing Apps | Migration guide for existing projects | | New App Setup | Starting a new project with Trinity | | Component Picker | Decision tree: which component to use | | Governance | Contribution process, RFC, and deprecation policy | | Migration | Version migration guides | | Contributing | How to contribute | | Changelog | Release history |

License

MIT