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

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

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)

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

Layout (7 components)

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

AI Input

AI Rendering & Explainability

AI Messages & Avatars

AI Actions & Layout

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

Data Display (8 components)

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: 'jane@example.com', 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>

Input & Forms (18+ components)

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)

Charts (17 components)

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

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.

Accessibility

Trinity targets WCAG 2.1 AA compliance. The system provides:

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

Token Coverage

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:

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

License

MIT