# Material You Convergence

- Status: `completed`
- Owner: `codex`
- Date: `2026-03-23`

## Goal

Converge Cadence UI from a multi-skin showcase system into a single Material You inspired
design language with dynamic seed-color theming, tonal surfaces, large-radius component
defaults, and one consistent motion vocabulary plus a reduced/static accessibility override.

## Scope

- In scope:
  - replace the current `minimal / glass / pixel` skin contract with a single `material` skin
  - shift token defaults toward Material You roles and typography
  - introduce runtime dynamic color generation from a seed color
  - retune component surface variables around tonal containers instead of decorative skins
  - update Storybook preview and foundation stories away from multi-skin demos
  - update package and contract tests that exercise the public runtime styling API
  - promote `DESIGN.md` into the repository system of record
  - push the visual language further toward a showcase-grade Material presentation
- Out of scope:
  - full wallpaper extraction from host operating systems
  - dark theme parity for every token role in this first convergence slice
  - a full component-by-component redesign of every docs story

## Constraints

- Keep the existing package import structure working for `@ai-ui/ui` and `@ai-ui/tokens`.
- Preserve the reduced/static motion accessibility mode.
- Prefer aliasing and runtime helpers over a sweeping component API rewrite.
- Record the direction change explicitly instead of silently continuing the multi-skin RFC.

## Affected Surfaces

- `packages/tokens/src/*`
- `packages/ui/src/lib/*`
- `packages/ui/src/skins.css`
- `packages/ui/src/styles.css`
- `apps/docs/.storybook/preview.ts`
- `apps/docs/src/*.stories.tsx`
- `DESIGN.md`
- `AGENTS.md`
- `README.md`
- `tests/package-consumer/*`
- `docs/exec-plans/*`

## Plan

1. Replace the style runtime contract with Material-centric theme and motion semantics.
2. Add a seed-color palette generator and map generated roles onto existing component tokens.
3. Collapse skin CSS to a single Material skin and retune shared component variables.
4. Update Storybook docs to demonstrate dynamic color, tonal surfaces, and the single motion language.
5. Promote `DESIGN.md` into the repository's official design system of record.
6. Push the showcase styling and motion layer until the docs feel closer to a Material launch demo.
7. Run focused validation on package contracts, docs build, and consumer smoke.

## Validation

- `pnpm test`
- `pnpm typecheck`
- `pnpm build:docs`
- `pnpm test:package:consumer`

## Orchestration Task Sketch

- `T1`: token/runtime contract shift
- `T2`: shared component surface restyle
- `T3`: docs and consumer validation updates

## Status Log

- `2026-03-23 14:18` started convergence plan after product direction changed from multi-skin showcase to Material You
- `2026-03-23 16:15` promoted `DESIGN.md` to the active design-system source of truth and started a second-pass visual polish toward a more animated Material showcase
- `2026-03-23 16:58` completed the second-pass polish across tokens, shared skin variables, Storybook showcase pages, and package-consumer validation