@trinityui/design-system 2.1.3 → 2.2.1

package/MIGRATION.md

@@ -4,6 +4,124 @@ This document outlines breaking changes and migration paths for the Trinity Desi
 
 ---
 
+## `@trinityui/design-system-css` v2.5.0 — CSS is now token-generated
+
+**Non-breaking for the 602 variable names shipped in v2.4.x.** Every CSS variable that existed in the hand-maintained `trinity.css` is still present, at the same name, with the same or WCAG-improved value.
+
+### What changed
+
+The `dist/trinity.css` shipped in `@trinityui/design-system-css` is now **generated from `src/tokens.ts`** via `scripts/generate-css-from-tokens.ts`. The previous hand-maintained `src/styles/trinity.css` is retired (kept as `trinity.css.legacy` in the repo for one release as a reference).
+
+### What you get as a consumer
+
+1. **Brand / semantic colors** are always current. Token changes in `tokens.ts` (including the v2.2 WCAG contrast updates — see the v3.0 section below) now reach CSS-only consumers automatically.
+2. **New tokens added in TS land in CSS on next release**. For example, v2.2 added `--trinity-on-dark-hover` (rgba 15% white) and `--trinity-on-dark-strong-emphasis` (rgba 90% white) — both now available via the CSS package.
+3. **CI-gated drift check** (`scripts/check-token-drift.ts`) prevents future drift between `tokens.ts` and the generated CSS.
+
+### Updated values (applied automatically on upgrade)
+
+| Variable | v2.4.x | v2.5.0 | Why |
+|---|---|---|---|
+| `--trinity-text-disabled` (light) | `#D4D4D8` | `#6B7280` | WCAG AA (1.9:1 → 4.83:1) |
+| `--trinity-text-link` | `#27AAE1` | `#0E62CA` | WCAG AA (~2.5:1 → ~5.9:1) |
+| `--trinity-status-success-text` | `#16A34A` | `#15803D` | WCAG AA (3.3:1 → 4.6:1) |
+| `--trinity-status-warning-text` | `#D97706` | `#B45309` | WCAG AA (2.6:1 → 4.8:1) |
+| `--trinity-status-info-text` | `#27AAE1` | `#0E62CA` | Consistency with text-link |
+| `--trinity-border-default` | `#E5E7EB` | `#D4D4D8` | Token system update |
+| `--trinity-border-subtle` | `#F4F4F5` | `#E5E7EB` | Token system update |
+| `--trinity-border-strong` | `#9CA3AF` | `#6B7280` | WCAG 1.4.11 (3:1 for UI) |
+
+### New variables in v2.5.0
+
+- `--trinity-on-dark-hover: rgba(255, 255, 255, 0.15)` — interactive hover on dark surfaces
+- `--trinity-on-dark-strong-emphasis: rgba(255, 255, 255, 0.9)` — pressed/active state on dark
+
+### Rollback
+
+If a consumer hits unexpected visual regressions:
+- Pin to `@trinityui/design-system-css@2.4.1` in `package.json`
+- Or override the specific variable locally, e.g. `--trinity-text-link: #27AAE1` in your app CSS
+
+### For contributors
+
+Edit tokens in `src/tokens.ts`, then regenerate:
+
+```bash
+pnpm build:css:sync    # regenerates src/styles/trinity-generated.css
+npx tsx scripts/check-token-drift.ts  # CI gate
+```
+
+The hand-maintained `src/styles/trinity.css.legacy` is kept one release as a reference but is not built or shipped. It will be removed in v2.6.
+
+---
+
+## v3.0.0 — Planned removals (deprecations sunset)
+
+The following already-deprecated exports will be removed in **v3.0.0 (target: Q4 2026)**. All have drop-in replacements today, and each emits a dev-mode console warning on first render so accidental usage surfaces immediately.
+
+### Deprecation summary
+
+| Removed in v3.0 | Replace with | Why |
+|---|---|---|
+| `OverflowToolTip` (capital T) | `OverflowTooltip` | Casing aligned with component filename; the alias is a runtime wrapper emitting a dev warning. |
+| `QueryInput`, `QueryInputProps` | `InsightEngineInput`, `InsightEngineInputProps` | `InsightEngineInput` is the canonical AI entry surface. |
+| `AIChatMessage`, `AIChatInput`, `AITypingIndicator`, `AIQuickReply` | `AIMessage`, `ChatThread`, `AIShimmer`, `AISuggestedAction` | Consolidated AI chat primitives; richer block rendering, `aria-live` streaming support, better accessibility. |
+| `AIChatMessageProps`, `AIChatInputProps`, `AITypingIndicatorProps`, `AIQuickReplyProps`, `MessageRole` | Prop types from `AIMessage` / `ChatThread` / `AIResponseRenderer` | — |
+| `AIFabLayout` | `AppLayout` with `navStyle="topnav"` + `aiTrigger="fab"` | Single unified layout API; removes duplicate FAB-wrapper component. |
+| `VirtualizedAutocomplete`, `VirtualizedAutocompleteProps`, `VirtualizedAutocompleteHandle` | `Autocomplete`, `AutocompleteProps`, `AutocompleteHandle` | MUI's built-in virtualization covers both paths; dedicated export is redundant. |
+
+### Migration snippets
+
+```tsx
+// Before (deprecated)
+import {
+  OverflowToolTip, QueryInput, AIChatMessage, AIChatInput,
+  AITypingIndicator, AIQuickReply, AIFabLayout, VirtualizedAutocomplete,
+} from '@trinityui/design-system';
+
+// After
+import {
+  OverflowTooltip, InsightEngineInput, AIMessage, ChatThread,
+  AIShimmer, AISuggestedAction, AppLayout, Autocomplete,
+} from '@trinityui/design-system';
+
+// AIFabLayout → AppLayout
+<AppLayout navStyle="topnav" aiTrigger="fab">{children}</AppLayout>
+
+// AIChatMessage → AIMessage (richer API)
+<AIMessage response={response} streaming={isStreaming} />
+```
+
+### Deprecation signals
+
+Three overlapping warning channels so accidental usage can't slip through:
+
+1. **IDE hint** — every deprecated export has a `@deprecated` JSDoc tag. Your IDE strikes through the name on hover and in autocomplete.
+2. **TypeScript warning** — the same JSDoc tag triggers `ts(6385)` "'X' is deprecated" in tsc output.
+3. **Runtime console warning** — in development builds only, each deprecated component emits one `console.warn` per session on first render. Production builds strip the warning.
+
+If you're an end-user consuming Trinity via a framework that hides deprecation warnings, check your console in `NODE_ENV=development` mode before upgrading to v3.0.
+
+### Accessibility token updates (non-breaking default, visual change)
+
+Neutral tokens:
+- `semanticTokens.colors.text.disabled` moved from `gray[300]` (1.9:1 on white — failed WCAG AA) to `gray[500]` (4.83:1). Disabled text will render darker.
+- `semanticTokens.colors.border.default` moved from `gray[200]` to `gray[300]` for improved perceptibility.
+- `semanticTokens.colors.border.subtle` moved from `gray[100]` to `gray[200]`. Still decorative; see `docs/TOKEN_USAGE_RULES.md`.
+- `semanticTokens.colors.border.strong` moved from `gray[400]` to `gray[500]` so it meets WCAG 1.4.11 (3:1) for interactive component boundaries.
+
+Brand-color tokens (Option A from `docs/BRAND_COLOR_CONTRAST_PROPOSAL.md`):
+- `semanticTokens.colors.text.link` moved from `azure[500]` `#27AAE1` (~2.5:1) to `azure[900]` `#0E62CA` (~5.9:1).
+- `semanticTokens.colors.text.success` and `semanticTokens.colors.status.success.text` moved from `#16A34A` (3.3:1) to `#15803D` (~4.6:1).
+- `semanticTokens.colors.text.warning` and `semanticTokens.colors.status.warning.text` moved from `#D97706` (2.6:1) to `#B45309` (~4.8:1).
+- `semanticTokens.colors.status.info.text` moved from `azure[500]` to `azure[900]` for consistency with `text.link`.
+
+Expect deeper saturation on inline links, success/warning messages, alert text, and toast body copy. If consumer code relied on the brighter brand values, pin them via explicit hex or `baseTokens.colors.azure[500]` at the call site.
+
+If consumer code relied on the exact prior colors, pin them via `baseTokens.colors.gray[N]` at the call site.
+
+---
+
 ## v1.2.0 - Build Optimization (Breaking Change)
 
 ### Overview