@trinitydesign/design-system 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+All notable changes to the Trinity Design System will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-01-12
+
+### Changed
+
+#### Build Optimization (BREAKING)
+- **Package size reduced from 169MB to 261KB** (99.85% reduction)
+- Removed source maps from npm package
+- Optimized chunk splitting into logical groups (ai, charts, data, forms, navigation)
+- Externalized image assets from bundle
+
+#### Dependency Restructuring
+- Moved `@mui/icons-material` to peer dependencies (required)
+- Moved `@mui/x-data-grid` to optional peer dependencies
+- Moved `@mui/x-date-pickers` to optional peer dependencies
+- Moved `dayjs` to optional peer dependencies
+- Moved `recharts` to optional peer dependencies
+- Moved `tailwindcss`, `@tailwindcss/vite` to dev dependencies
+
+### Removed
+
+#### Breaking Changes
+- **Asset exports removed**: `gradientIcons`, `backgroundImages`, `brandGradients` no longer exported from main package (80MB of images were bloating the bundle)
+- **`@mui/x-date-pickers-pro`** removed (date range functionality now uses two standard `DatePicker` components)
+
+### Migration
+See [MIGRATION.md](./MIGRATION.md) for detailed upgrade instructions.
+
+---
+
+## [1.1.0] - 2025-01-XX
+
+### Added
+
+#### New Components (7)
+- **TreeView** - Hierarchical tree component with expand/collapse, multi-select, checkboxes, search filtering, and drag-drop support. Full ARIA tree semantics with keyboard navigation (Arrow keys, Home, End, Enter, Space).
+- **TransferList** - Dual-list selection component for transferring items between lists. Supports search, custom rendering, disabled items, and move-all controls.
+- **Combobox** - Enhanced multi-select autocomplete with creatable options, grouping, icons, and custom rendering. Built on MUI Autocomplete.
+- **SplitPane** - Resizable split panel layout with horizontal/vertical orientations, min/max constraints, and collapsible panels. Full ARIA separator with keyboard resize (Arrow keys, Shift+Arrow for large steps).
+- **RichTextEditor** - WYSIWYG editor with customizable toolbar, formatting (bold, italic, lists, headings), alignment, links, images, and fullscreen mode.
+- **DiffViewer** - Code/text diff viewer with side-by-side and unified view modes, syntax highlighting, line numbers, and word wrap.
+- **DockLayout** - VS Code-style dockable panel layout with tabbed zones, split layouts, drag-and-drop panels, and panel actions.
+
+#### Design Tokens
+- **Spacing half-values** - Added `0.5`, `1.5`, `2.5` to spacing scale for fine-grained layout control
+- **Animation easing tokens** - New reusable easing functions: `smooth`, `bounce`, `elastic`
+- **Surface status colors** - Semantic surface colors for success/warning/error/info states
+- **Brand variants** - 5 theme variants: `trinity`, `corporate`, `tech`, `nature`, `midnight`
+- **Dark mode improvements** - Enhanced contrast ratios meeting WCAG AA+ (4.5:1+)
+
+#### Storybook Documentation
+- 74 new stories across 7 components with interactive controls
+- All stories include `autodocs`, `argTypes`, and component descriptions
+- Full coverage of variants, states, and edge cases
+
+#### Documentation
+- **COMPOSITION_PATTERNS.md** - 8 real-world layout patterns demonstrating component composition:
+  - Dashboard Layout, Data Explorer, Settings Panel, File Browser
+  - Command Center, Content Editor, Code Review Interface, Admin Console
+
+### Changed
+- Improved accessibility for TreeView and SplitPane with full ARIA support
+- Enhanced keyboard navigation across complex components
+
+## [Unreleased]
+
+### Changed (Phase 3.3 & 3.4 - Color Token Normalization)
+
+- **Token Architecture Normalization** - Improved internal consistency without breaking changes
+  - AI component tokens (`aiHover`, `aiHoverDark`) now reference `baseTokens.colors.indigo` scale
+  - Charts sequential palette normalized to `baseTokens.colors.indigo[50-900]`
+  - Navigation components (`TopNavHeader`, `TopNavWithSidebar`) inline `#fff` → `brandColors.neutral.white`
+  - AI components (6 files) inline `#FFFFFF` → `brandColors.neutral.white`
+  - `IllustratedMessage` SVG colors centralized to `illustrationStatusColors` constant
+
+- **Intentional Color Decisions Documented**
+  - Charts categorical palette: Intentionally uses full brand spectrum for data visualization distinction
+  - DataTable header grays: Tuned for dense tabular readability (NOT from gray scale)
+  - Status illustration colors: Tailwind-standard (red-500, amber-500, emerald-500) for universal recognition
+
+### Added
+- **Accessibility Utilities** (`@trinity/design-system/accessibility`)
+  - `useFocusTrap` - Hook for trapping focus within modal dialogs
+  - `useReducedMotion` - Hook to detect user's reduced motion preference
+  - `useAriaLive` - Hook for managing ARIA live regions
+  - `useRovingTabIndex` - Hook for keyboard navigation in lists
+  - `SkipLink` - Component for skip-to-content functionality
+  - `VisuallyHidden` - Component for screen reader-only content
+
+- **Enhanced TypeScript Support**
+  - Added `TrinityTokens` interface with full token structure
+  - Created `useTrinityTokens()` hook for consuming tokens
+  - Added CSS variable export via `generateCSSVariables()`
+  - New `tokens.ts` module with typed design tokens
+
+- **Modular Component Architecture**
+  - Split `AI.tsx` into 9 focused modules under `components/AI/`
+  - Split `StatusIndicator.tsx` into 6 focused modules under `components/StatusIndicator/`
+  - Created shared navigation utilities under `components/navigation/`
+
+- **Improved Package Exports**
+  - Added tree-shaking support with `sideEffects` configuration
+  - New subpath exports: `/theme`, `/tokens`, `/components`, `/accessibility`, `/navigation`
+  - Individual component exports: `/components/AI`, `/components/StatusIndicator`, `/components/Icon`
+
+- **Testing Infrastructure**
+  - Added comprehensive tests for StatusIndicator components
+  - Added comprehensive tests for Icon component
+  - Added comprehensive tests for IllustratedMessage component
+  - Added tests for accessibility utilities
+
+### Changed
+- Refactored navigation components to share common hooks and styled components
+- Improved TypeScript strictness with proper type definitions
+- Enhanced dark mode support with better accessible color combinations
+
+### Fixed
+- Fixed `any` type usage in DataTable.stories.tsx
+- Fixed `any` type usage in Icons.stories.tsx
+- Fixed type errors in AI components (IconName, brandColors references)
+
+## [1.0.0] - 2024-01-XX
+
+### Added
+- Initial release of Trinity Design System
+- MUI v6/7-based component library
+- Light and dark theme support
+- Brand colors with accessible combinations
+- Core components:
+  - `TopNavHeader` - Top navigation header component
+  - `TopNavWithSidebar` - Navigation with collapsible sidebar
+  - `Layout` - Page layout wrapper
+  - `Icon` - Icon wrapper with multiple library support
+  - `IllustratedMessage` - Empty states with illustrations
+  - `StatusIndicator` - Status display components
+  - `AI` - AI-specific UI components
+- Storybook documentation with interactive examples
+- WCAG 2.1 AA accessibility compliance
+- Montserrat typography
+- Custom MUI component overrides (buttons, switches, inputs)
+
+### Design Tokens
+- Brand colors (Navy, Coral, Teal, White, Grays)
+- Accessible color combinations
+- Typography scale
+- Spacing scale
+- Border radius values
+- Shadow definitions
+- Breakpoints
+
+---
+
+## Migration Guides
+
+For detailed migration instructions, see [MIGRATION.md](./MIGRATION.md).
+
+## Release Types
+
+- **Major (X.0.0)**: Breaking changes requiring code updates
+- **Minor (0.X.0)**: New features, backward compatible
+- **Patch (0.0.X)**: Bug fixes, backward compatible

package/CONTRIBUTING.md

@@ -0,0 +1,394 @@
+# Contributing to Trinity Design System
+
+Thank you for your interest in contributing to the Trinity Design System! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Component Guidelines](#component-guidelines)
+- [Styling Guidelines](#styling-guidelines)
+- [Accessibility Requirements](#accessibility-requirements)
+- [Testing Requirements](#testing-requirements)
+- [Documentation](#documentation)
+- [Pull Request Process](#pull-request-process)
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for all contributors.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ 
+- npm 9+
+- Git
+
+### Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-org/trinity-design-system.git
+   cd trinity-design-system
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+4. Start Storybook:
+   ```bash
+   npm run storybook
+   ```
+
+## Development Workflow
+
+### Branch Naming
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation updates
+- `refactor/` - Code refactoring
+- `test/` - Test additions or updates
+
+Example: `feature/add-date-picker-component`
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting (no code change)
+- `refactor`: Code refactoring
+- `test`: Adding tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(Button): add loading state prop
+fix(StatusIndicator): correct color contrast for warning state
+docs(README): update installation instructions
+```
+
+## Component Guidelines
+
+### File Structure
+
+New components should follow this structure:
+
+```
+src/components/ComponentName/
+├── index.ts              # Barrel exports
+├── ComponentName.tsx     # Main component
+├── types.ts              # TypeScript types/interfaces
+├── styles.ts             # Styled components (if needed)
+└── utils.ts              # Helper functions (if needed)
+```
+
+### Component Template
+
+```tsx
+import React from 'react';
+import { Box, SxProps, Theme } from '@mui/material';
+
+export interface MyComponentProps {
+  /** Description of the prop */
+  variant?: 'primary' | 'secondary';
+  /** Additional custom styles */
+  sx?: SxProps<Theme>;
+  /** Component content */
+  children?: React.ReactNode;
+}
+
+/**
+ * MyComponent - Brief description of what the component does.
+ * 
+ * @example
+ * ```tsx
+ * <MyComponent variant="primary">Content</MyComponent>
+ * ```
+ */
+export const MyComponent: React.FC<MyComponentProps> = ({
+  variant = 'primary',
+  sx,
+  children,
+}) => {
+  return (
+    <Box
+      sx={{
+        // Component styles
+        ...sx,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+```
+
+### Export Components
+
+Add exports to `src/components/index.ts`:
+
+```typescript
+export * from './MyComponent';
+```
+
+## Styling Guidelines
+
+### Use Theme Tokens
+
+Always use theme tokens from `src/theme.ts`:
+
+```tsx
+// ✅ Good
+<Box sx={{ color: 'primary.main', borderRadius: 2 }}>
+
+// ❌ Avoid
+<Box sx={{ color: '#003366', borderRadius: '16px' }}>
+```
+
+### Accessible Color Combinations
+
+Use `accessibleCombinations` for text/background pairs:
+
+```tsx
+import { accessibleCombinations } from '../theme';
+
+<Box sx={{
+  backgroundColor: accessibleCombinations.whiteOnNavy.bg,
+  color: accessibleCombinations.whiteOnNavy.text,
+}}>
+```
+
+### Trinity-Specific Patterns
+
+- **Buttons**: Pill shape (`borderRadius: 100`), no elevation
+- **Cards/Containers**: 16px border radius (light), 8px (dark)
+- **Inputs**: 6px border radius for small inputs
+- **Typography**: Montserrat font, no uppercase buttons
+
+## Accessibility Requirements
+
+All components must meet **WCAG 2.1 AA** standards:
+
+### Minimum Requirements
+
+1. **Color Contrast**: 4.5:1 for normal text, 3:1 for large text
+2. **Keyboard Navigation**: All interactive elements must be keyboard accessible
+3. **Focus Indicators**: Visible focus states for all focusable elements
+4. **ARIA Labels**: Proper labels for screen readers
+5. **Reduced Motion**: Respect `prefers-reduced-motion` preference
+
+### Testing Accessibility
+
+```tsx
+// Use accessibility utilities
+import { useReducedMotion, VisuallyHidden } from '../accessibility';
+
+const MyComponent = () => {
+  const prefersReducedMotion = useReducedMotion();
+  
+  return (
+    <button>
+      <VisuallyHidden>Screen reader text</VisuallyHidden>
+      <Icon aria-hidden="true" />
+    </button>
+  );
+};
+```
+
+### Storybook Accessibility Addon
+
+Run accessibility audits in Storybook using the addon-a11y panel.
+
+## Testing Requirements
+
+### Test Structure
+
+```
+src/
+├── components/
+│   ├── __tests__/
+│   │   └── MyComponent.test.tsx
+│   └── MyComponent.tsx
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Test Template
+
+```tsx
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { MyComponent } from '../MyComponent';
+
+describe('MyComponent', () => {
+  it('should render with default props', () => {
+    render(<MyComponent>Content</MyComponent>);
+    expect(screen.getByText('Content')).toBeInTheDocument();
+  });
+
+  it('should handle click events', () => {
+    const onClick = vi.fn();
+    render(<MyComponent onClick={onClick}>Click me</MyComponent>);
+    
+    fireEvent.click(screen.getByText('Click me'));
+    expect(onClick).toHaveBeenCalled();
+  });
+
+  it('should apply custom styles', () => {
+    render(<MyComponent sx={{ color: 'red' }}>Styled</MyComponent>);
+    // Assert styles
+  });
+});
+```
+
+### Coverage Requirements
+
+- Minimum 80% code coverage for new components
+- All public APIs must have tests
+- Edge cases and error states should be tested
+
+## Documentation
+
+### Storybook Stories
+
+Every component needs a Storybook 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'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary'],
+      description: 'Visual variant',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'Default content',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Secondary variant',
+  },
+};
+```
+
+### JSDoc Comments
+
+All exported functions and components should have JSDoc comments:
+
+```tsx
+/**
+ * Calculates the accessible color for a given background.
+ * 
+ * @param backgroundColor - The background color in hex format
+ * @returns The appropriate text color for accessibility
+ * 
+ * @example
+ * ```tsx
+ * const textColor = getAccessibleColor('#003366');
+ * // Returns '#ffffff'
+ * ```
+ */
+export const getAccessibleColor = (backgroundColor: string): string => {
+  // Implementation
+};
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. ✅ Run `npm run lint` and fix any issues
+2. ✅ Run `npm test` and ensure all tests pass
+3. ✅ Run `npm run build` to verify build succeeds
+4. ✅ Update documentation if needed
+5. ✅ Add/update Storybook stories
+6. ✅ Update CHANGELOG.md with your changes
+
+### PR Template
+
+```markdown
+## Description
+Brief description of the changes.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] Storybook stories added/updated
+- [ ] CHANGELOG.md updated
+- [ ] Accessibility requirements met
+- [ ] Token compliance verified (`npm run lint:tokens`)
+- [ ] Any `eslint-disable` for colors references [INTENTIONAL_EXCEPTIONS.md](docs/INTENTIONAL_EXCEPTIONS.md)
+
+## Screenshots (if applicable)
+```
+
+### Review Process
+
+1. Create PR against `main` branch
+2. Request review from team members
+3. Address feedback and update PR
+4. Squash and merge when approved
+
+## Questions?
+
+If you have questions, feel free to:
+- Open a GitHub issue
+- Reach out to the design system team
+
+Thank you for contributing! 🎉