@trinityui/design-system 1.0.0

package/MIGRATION.md

@@ -0,0 +1,347 @@
+# Trinity Design System - Migration Guide
+
+This document outlines breaking changes and migration paths for the Trinity Design System.
+
+---
+
+## v1.2.0 - Build Optimization (Breaking Change)
+
+### Overview
+
+The npm package has been optimized from **169MB to 261KB** (99.85% reduction) by:
+- Removing inlined image assets from the bundle
+- Restructuring dependencies as peer dependencies
+- Optimizing chunk splitting
+
+### Breaking Changes
+
+#### 1. Asset Exports Removed
+
+The following exports are **no longer available** from the main package:
+
+```typescript
+// ❌ No longer works
+import { gradientIcons, backgroundImages, brandGradients } from '@trinity/design-system';
+```
+
+**Migration:** If you need Trinity brand assets:
+1. Copy from `node_modules/@trinity/design-system/src/assets/` to your public folder
+2. Import directly in your source (your bundler will handle them)
+3. Use a CDN for production
+
+Type definitions are still exported:
+```typescript
+// ✅ Still works
+import type { GradientIconName, BackgroundCategory } from '@trinity/design-system';
+```
+
+#### 2. New Peer Dependencies
+
+The following are now **peer dependencies** (install separately):
+
+| Dependency | Required | Notes |
+|------------|----------|-------|
+| `@mui/icons-material` | **Yes** | Previously bundled |
+| `@mui/x-data-grid` | Optional | Only for DataTable |
+| `@mui/x-date-pickers` | Optional | Only for DatePicker |
+| `dayjs` | Optional | Only for DatePicker |
+| `recharts` | Optional | Only for Charts |
+
+**Migration:**
+```bash
+# Required
+npm install @mui/icons-material
+
+# Optional (if using these components)
+npm install @mui/x-data-grid @mui/x-date-pickers dayjs recharts
+```
+
+#### 3. Removed Dependencies
+
+- `@mui/x-date-pickers-pro` - No longer used; date range functionality now uses two standard `DatePicker` components
+
+---
+
+## Phase 3.3 & 3.4 - Color Token Normalization
+
+### Overview
+
+Phase 3.3 and 3.4 normalized internal color references to improve token consistency. **No breaking API changes** were introduced, and visual output is unchanged.
+
+### Consumer Impact: **No Action Required**
+
+All changes are internal refactors. If you're consuming Trinity components normally:
+- ✅ No import changes needed
+- ✅ No prop changes needed
+- ✅ No theme override adjustments needed
+- ✅ Visual appearance is identical
+
+### What Changed Internally
+
+#### 1. Normalized Token References
+
+These inline hex values were replaced with canonical token references:
+
+| Location | Before | After |
+|----------|--------|-------|
+| `aiTokens.aiHover` | `'#E8E0F4'` | `baseTokens.colors.indigo[100]` |
+| `aiTokens.aiHoverDark` | `'#3D2E5C'` | `baseTokens.colors.indigo[900]` |
+| Charts sequential palette | `'#EDE9FE'` through `'#3730A3'` | `baseTokens.colors.indigo[50-900]` |
+| Navigation `alpha('#fff', x)` | `'#fff'` literal | `brandColors.neutral.white` |
+| AI components `'#FFFFFF'` | Hex literal | `brandColors.neutral.white` |
+
+#### 2. Intentional Palette Extensions (NOT Normalized)
+
+These colors intentionally differ from base tokens for functional reasons:
+
+**Charts Categorical Palette** - Uses full brand spectrum for maximum data distinction:
+```typescript
+// Intentionally uses multiple brand color families
+categorical: [
+  brandColors.primary.navy,    // Navy for primary series
+  brandColors.accent.coral,    // Coral for contrast
+  brandColors.accent.teal,     // Teal for tertiary
+  brandColors.secondary.purple, // Purple for additional series
+  // ... additional distinct colors
+]
+```
+
+**Status Illustration Colors** - Tailwind-standard colors for universal recognition:
+```typescript
+// In IllustratedMessage.tsx - NOT from brand palette
+const illustrationStatusColors = {
+  error: { main: '#EF4444', light: '#FEE2E2' },   // red-500
+  warning: { main: '#F59E0B', light: '#FEF3C7' }, // amber-500
+  success: { main: '#10B981', light: '#D1FAE5' }, // emerald-500
+};
+```
+
+#### 3. Intentional Structural Overrides (NOT Normalized)
+
+**DataTable Header Grays** - Tuned for dense tabular readability:
+```typescript
+// In DataTable/tokens.ts - intentionally differs from baseTokens.gray
+header: {
+  background: '#F3F4F6',  // NOT gray[100] = '#F4F4F5'
+  borderColor: '#D1D5DB', // NOT gray[300] = '#D4D4D8'
+}
+```
+
+These values were specifically chosen for optimal contrast in data-dense table contexts and are documented inline.
+
+### Commits
+
+- `4544c91` - refactor(tokens): normalize AI and Charts color references (phase 3.3)
+- `d58e2ec` - refactor(ui): centralize non-tokenized semantic colors (phase 3.4)
+
+---
+
+## Version 1.1.0
+
+### New Features
+
+#### 1. Comprehensive Token Type System
+
+All token layers now have complete TypeScript interfaces:
+
+```typescript
+import type {
+  TrinityTokens,
+  TrinityBaseTokens,
+  TrinitySemanticTokens,
+  TrinityComponentTokens,
+  TrinityDarkModeTokens,
+} from '@trinity/design-system';
+```
+
+#### 2. Auto-generated CSS Variables
+
+New utilities to automatically generate CSS custom properties from all tokens:
+
+```typescript
+import { 
+  generateCssVariables,
+  generateDarkModeCssVariables,
+  injectTrinityCssVariables,
+  injectDarkModeCssVariables 
+} from '@trinity/design-system';
+
+// Inject all variables into :root
+injectTrinityCssVariables();
+
+// Also inject dark mode variables (responds to prefers-color-scheme)
+injectDarkModeCssVariables();
+```
+
+Available CSS variables follow the pattern:
+- Colors: `--trinity-color-{palette}-{shade}` (e.g., `--trinity-color-navy-900`)
+- Spacing: `--trinity-spacing-{size}` (e.g., `--trinity-spacing-4`)
+- Font sizes: `--trinity-font-size-{size}` (e.g., `--trinity-font-size-base`)
+- Border radius: `--trinity-radius-{size}` (e.g., `--trinity-radius-md`)
+- Shadows: `--trinity-shadow-{size}` (e.g., `--trinity-shadow-md`)
+- Semantic tokens: `--trinity-semantic-{category}-{name}`
+- Component tokens: `--trinity-component-{component}-{property}`
+
+#### 3. useTrinityTokens Hook
+
+New React hook for accessing tokens with theme awareness:
+
+```typescript
+import { useTrinityTokens } from '@trinity/design-system';
+
+function MyComponent() {
+  const { 
+    base,
+    semantic,
+    component,
+    mode,
+    isDarkMode,
+    spacing,
+    spacingCss,
+    radius,
+    shadow,
+    getColor,
+    getSemanticColor 
+  } = useTrinityTokens();
+
+  return (
+    <Box sx={{
+      backgroundColor: getColor(
+        semantic.colors.background.primary,
+        darkMode.colors.background.primary
+      ),
+      padding: spacingCss(4), // '16px'
+      borderRadius: radius('md'), // 6
+      boxShadow: shadow('md'),
+    }} />
+  );
+}
+```
+
+#### 4. Enhanced Dark Mode Tokens
+
+Dark mode tokens now include complete overrides for:
+- Interactive states (hover, active, focus, disabled)
+- Status colors (error, warning, success, info)
+
+```typescript
+import { darkModeTokens } from '@trinity/design-system';
+
+// New dark mode interactive colors
+darkModeTokens.colors.interactive.hover
+darkModeTokens.colors.interactive.focus
+
+// New dark mode status colors
+darkModeTokens.colors.status.error.text
+darkModeTokens.colors.status.error.background
+```
+
+### Breaking Changes
+
+#### Token Types
+
+The `TrinityTokens` interface now uses specific types instead of `any`:
+
+**Before:**
+```typescript
+export interface TrinityTokens {
+  base: TrinityBaseTokens;
+  semantic: any;
+  component: any;
+  darkMode: any;
+}
+```
+
+**After:**
+```typescript
+export interface TrinityTokens {
+  base: TrinityBaseTokens;
+  semantic: TrinitySemanticTokens;
+  component: TrinityComponentTokens;
+  darkMode: TrinityDarkModeTokens;
+}
+```
+
+**Migration:** Update any code that relied on loose typing of semantic, component, or darkMode tokens.
+
+#### CSS Variable Names
+
+The `injectTrinityCssVariables` function now generates comprehensive CSS variables instead of just a few key ones.
+
+**Before:**
+- Limited variables like `--trinity-primary`, `--trinity-spacing-md`
+
+**After:**
+- Full variable system: `--trinity-color-navy-900`, `--trinity-spacing-4`, etc.
+
+**Migration:** Update any CSS that referenced the old variable names:
+
+| Old Variable | New Variable |
+|-------------|--------------|
+| `--trinity-primary` | `--trinity-color-navy-900` |
+| `--trinity-secondary` | `--trinity-color-purple-700` |
+| `--trinity-coral` | `--trinity-color-coral-800` |
+| `--trinity-spacing-md` | `--trinity-spacing-4` |
+| `--trinity-radius-lg` | `--trinity-radius-lg` (unchanged) |
+
+### New Exports
+
+The following are now exported from the main entry point:
+
+```typescript
+// Types
+export type {
+  TrinityTokens,
+  TrinityBaseTokens,
+  TrinitySemanticTokens,
+  TrinityComponentTokens,
+  TrinityDarkModeTokens,
+  TrinityColorShades,
+  TrinityBaseColors,
+  TrinitySpacing,
+  TrinityFontSize,
+  TrinityFontWeight,
+  TrinityBorderRadius,
+  TrinityShadows,
+  TrinitySemanticColors,
+  TrinityTypographyStyle,
+  TrinityButtonTokens,
+  TrinityInputTokens,
+  TrinityCardTokens,
+  TrinityNavigationTokens,
+  UseTrinityTokensResult,
+};
+
+// Utilities
+export {
+  generateCssVariables,
+  generateDarkModeCssVariables,
+  injectTrinityCssVariables,
+  injectDarkModeCssVariables,
+  useTrinityTokens,
+};
+```
+
+### Recommended Upgrade Steps
+
+1. **Update imports** to use the new main entry point if needed:
+   ```typescript
+   // New unified import
+   import { tokens, useTrinityTokens, injectTrinityCssVariables } from '@trinity/design-system';
+   ```
+
+2. **Update CSS variable references** to use the new naming convention.
+
+3. **Add type annotations** where you were previously using `any` with token objects.
+
+4. **Consider using `useTrinityTokens`** hook for theme-aware token access in React components.
+
+5. **Run tests** to ensure token values haven't changed unexpectedly.
+
+### Deprecations
+
+None in this release.
+
+### Questions or Issues?
+
+If you encounter any issues during migration, please open an issue on the GitHub repository.

package/README.md

@@ -0,0 +1,298 @@
+# Trinity Design System
+
+MUI v6/7 with Trinity branding. WCAG 2.1 AA accessible.
+
+```bash
+npm install @trinity/design-system @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+## Setup (One Time)
+
+```tsx
+// App.tsx
+import { ThemeProvider, CssBaseline } from '@mui/material';
+import { lightTheme } from '@trinity/design-system';
+
+function App() {
+  return (
+    <ThemeProvider theme={lightTheme}>
+      <CssBaseline />
+      <YourApp />
+    </ThemeProvider>
+  );
+}
+```
+
+**That's it.** All MUI components now have Trinity styling.
+
+---
+
+## The Golden Rule
+
+> **Use MUI for everything.** Trinity just gives you a theme + a few custom components.
+
+### ✅ Use MUI (99% of your code)
+
+```tsx
+import { Button, Card, TextField, Typography, Chip } from '@mui/material';
+```
+
+These are already styled by Trinity's theme. No extra imports needed.
+
+### ✅ Use Trinity (only for these)
+
+```tsx
+import { 
+  StatusIndicator,    // Status badges (success/warning/error)
+  Modal,              // Accessible modal dialogs
+  Toast, useToast,    // Notifications
+  FileUpload,         // Drag-and-drop upload
+  SimpleTable,        // Basic table (no dependencies)
+  DataCard,           // KPI/metric cards
+} from '@trinity/design-system';
+```
+
+### Quick Reference
+
+| Need | Import From |
+|------|-------------|
+| Button, Card, TextField, etc. | `@mui/material` |
+| Status badge | `StatusIndicator` from Trinity |
+| Modal dialog | `Modal` from Trinity |
+| Toast notification | `Toast` from Trinity |
+| Simple table | `SimpleTable` from Trinity |
+| Advanced data grid | `@mui/x-data-grid` (optional dep) |
+| Charts | `recharts` (optional dep) |
+
+---
+
+## Entry Points
+
+| Import | What You Get |
+|--------|--------------|
+| `/essentials` | **Start here.** Theme + 10 components (16 exports) |
+| Main | Full API (100+ exports) |
+| `/theme` | Theme utilities only |
+| `/tokens` | Design tokens only |
+| `/css` | CSS variables (no React) |
+
+```tsx
+// Recommended for most projects
+import { lightTheme, StatusIndicator, Modal } from '@trinity/design-system/essentials';
+
+// Full API when needed
+import { TopNavHeader, InsightEngine, DataTable } from '@trinity/design-system';
+```
+
+---
+
+## Dark Mode
+
+```tsx
+import { lightTheme, darkTheme } from '@trinity/design-system';
+
+const theme = isDarkMode ? darkTheme : lightTheme;
+```
+
+---
+
+## CSS-Only Theme (No React)
+
+For projects **without React** (static HTML, Vue, Angular, vanilla JS), use the CSS file directly.
+
+📄 **[View CSS Source](src/styles/trinity.css)**
+
+### When to Use CSS-Only
+
+| Use Case | Solution |
+|----------|----------|
+| React + MUI app | Use `lightTheme` / `darkTheme` (JS) |
+| Static HTML site | Use CSS file |
+| Vue / Angular / Svelte | Use CSS file |
+| WordPress / PHP | Use CSS file |
+| Email templates | Use CSS file |
+
+### Setup
+
+```html
+<!-- Option 1: Link directly -->
+<link rel="stylesheet" href="node_modules/@trinity/design-system/dist/trinity.css" />
+
+<!-- Option 2: Copy to your project -->
+<link rel="stylesheet" href="/css/trinity.css" />
+```
+
+```css
+/* Option 3: Import in your CSS/SCSS */
+@import '@trinity/design-system/css';
+```
+
+### Usage
+
+```css
+/* Use Trinity variables in your styles */
+.card {
+  background: var(--trinity-surface);
+  border: 1px solid var(--trinity-border);
+  border-radius: var(--trinity-radius-lg);
+  padding: var(--trinity-space-4);
+  box-shadow: var(--trinity-shadow-md);
+  font-family: var(--trinity-font-family);
+}
+
+.button-primary {
+  background: var(--trinity-coral);
+  color: var(--trinity-white);
+  border-radius: var(--trinity-radius-pill);
+  padding: var(--trinity-space-2) var(--trinity-space-4);
+}
+
+.status-success {
+  color: var(--trinity-success);
+  background: var(--trinity-success-bg);
+}
+```
+
+### Dark Mode
+
+```html
+<!-- Add attribute to enable dark mode -->
+<html data-theme="dark">
+```
+
+```js
+// Toggle with JavaScript
+document.documentElement.setAttribute('data-theme', 'dark');
+```
+
+### Available Variables
+
+| Category | Examples |
+|----------|----------|
+| Brand | `--trinity-navy`, `--trinity-coral`, `--trinity-purple`, `--trinity-azure` |
+| Semantic | `--trinity-text`, `--trinity-background`, `--trinity-surface`, `--trinity-border` |
+| Status | `--trinity-success`, `--trinity-warning`, `--trinity-error`, `--trinity-info` |
+| Spacing | `--trinity-space-1` through `--trinity-space-16` |
+| Radius | `--trinity-radius-sm`, `--trinity-radius-md`, `--trinity-radius-lg`, `--trinity-radius-pill` |
+| Typography | `--trinity-font-family`, `--trinity-text-sm`, `--trinity-font-bold` |
+| Shadows | `--trinity-shadow-sm`, `--trinity-shadow-md`, `--trinity-shadow-lg` |
+
+---
+
+## Optional Dependencies
+
+Only install if you need these features:
+
+```bash
+npm install @mui/x-data-grid  # For DataTable component
+npm install recharts          # For Charts components
+```
+
+> 💡 Use `SimpleTable` for basic tables — no extra deps needed.
+
+---
+
+## Development
+
+```bash
+npm run storybook    # Component docs at localhost:6006
+npm run dev          # Dev server at localhost:5173
+npm run build        # Production build
+npm run test         # Run tests
+npm run lint         # Lint code
+```
+
+---
+
+## Developer Quick Start
+
+### 1. Clone & Install
+
+```bash
+git clone git@github.com:Trinity-UI-Components/trinity-design-system.git
+cd trinity-design-system
+npm install
+```
+
+### 2. Run Storybook
+
+```bash
+npm run storybook
+```
+
+Open http://localhost:6006 to see all components with live examples.
+
+### 3. Project Structure
+
+```
+src/
+├── components/       # All components
+├── theme.ts          # MUI theme (lightTheme, darkTheme)
+├── tokens.ts         # Design tokens
+├── essentials.ts     # Simplified entry point
+├── index.ts          # Full public API
+└── stories/          # Storybook stories
+```
+
+### 4. Create a New Component
+
+```tsx
+// src/components/MyComponent/MyComponent.tsx
+import { Box } from '@mui/material';
+import { semanticTokens } from '../../tokens';
+
+export interface MyComponentProps {
+  label: string;
+}
+
+export const MyComponent = ({ label }: MyComponentProps) => (
+  <Box sx={{ color: semanticTokens.text.primary }}>
+    {label}
+  </Box>
+);
+
+// src/components/MyComponent/index.ts
+export { MyComponent } from './MyComponent';
+export type { MyComponentProps } from './MyComponent';
+```
+
+### 5. Add a Story
+
+```tsx
+// src/stories/MyComponent.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { MyComponent } from '../components/MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: 'Hello World' },
+};
+```
+
+### 6. Export from Public API
+
+```tsx
+// src/index.ts
+export { MyComponent } from './components/MyComponent';
+export type { MyComponentProps } from './components/MyComponent';
+```
+
+---
+
+## Links
+
+- [Storybook](http://localhost:6006) — Interactive component demos
+- [Quick Start Guide](./docs/QUICK_START.md)
+- [Developer Guide](./docs/DEVELOPER_GUIDE.md)
+
+---
+
+MIT License • Built with [MUI](https://mui.com) + [Vite](https://vite.dev)