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

Replace the style runtime contract with Material-centric theme and motion semantics.
Add a seed-color palette generator and map generated roles onto existing component tokens.
Collapse skin CSS to a single Material skin and retune shared component variables.
Update Storybook docs to demonstrate dynamic color, tonal surfaces, and the single motion language.
Promote DESIGN.md into the repository's official design system of record.
Push the showcase styling and motion layer until the docs feel closer to a Material launch demo.
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

3.1 KiB Raw Blame History