kurihada/cadence-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ui): polish core component surfaces

Browse Source
This commit is contained in:
kurihada
2026-03-25 19:49:15 +08:00
parent eccaacece7
commit cc1509d2f6
64 changed files with 2707 additions and 353 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/exec-plans/2026-03-25-component-polish-pass.md
+89
View File
@@ -0,0 +1,89 @@
# Component Polish Pass
- Status: `completed`
- Owner: `codex`
- Date: `2026-03-25`
## Goal
Run a focused polish pass across six existing component surfaces so the current Material runtime
direction feels more intentional in high-traffic docs and product-like stories. The goal is not to
add new APIs. The goal is to tighten hierarchy, depth, and interaction feedback while keeping the
existing contract stable.
## Scope
- In scope:
- refine `StatCard` hierarchy, default interaction treatment, and delta emphasis
- refine `DataTable` row, header, toolbar, and selection presentation
- refine `EmptyState` composition, especially the `split` layout media and narrative weight
- refine `Command`, `Combobox`, and `Select` list item selection and active-state treatment
- refine `MetricCard` cohesion across media, footer, and CTA regions
- refine base `Card` interactive behavior so general business cards feel less static
- update the closest Storybook stories and tests where behavior or reviewability changes
- Out of scope:
- adding new component families or expanding public props beyond what the current contract needs
- introducing a second motion language or non-token visual escape hatches
- broad scene rewrites outside the stories that best demonstrate the updated behavior
## Constraints
- Follow the active visual and motion direction in `DESIGN.md`.
- Preserve reduced-motion safety and the current component contract.
- Keep write scopes isolated so six workers can operate in parallel without conflicting.
- Keep shared integration surfaces on the main thread where practical.
- Do not revert or overwrite unrelated in-progress repo changes.
## Affected Surfaces
- `packages/ui/src/components/card*`
- `packages/ui/src/components/stat-card*`
- `packages/ui/src/components/data-table*`
- `packages/ui/src/components/empty-state*`
- `packages/ui/src/components/command*`
- `packages/ui/src/components/combobox*`
- `packages/ui/src/components/select*`
- `packages/ui/src/components/metric-card*`
- `apps/docs/src/components/card.stories.tsx`
- `apps/docs/src/components/stat-card.stories.tsx`
- `apps/docs/src/components/data-table.stories.tsx`
- `apps/docs/src/components/empty-state.stories.tsx`
- `apps/docs/src/components/command.stories.tsx`
- `apps/docs/src/components/combobox.stories.tsx`
- `apps/docs/src/components/select.stories.tsx`
- `apps/docs/src/components/metric-card.stories.tsx`
- `docs/exec-plans`
## Plan
1. Write and commit an execution plan for the six-slice polish pass so delegation stays resumable.
2. Dispatch six isolated implementation workers, one per polish slice, each owning its component,
nearby stories, and nearby tests only.
3. Review worker diffs in the main thread, resolve any cross-slice visual inconsistencies, and keep
shared integration concerns centralized.
4. Run the narrowest useful harness and component validation suites, then fix any regressions in the
main thread.
5. Summarize what changed, what was validated, and any remaining gaps.
## Validation
- `pnpm harness:validate:component`
- `pnpm harness:validate:docs`
- `pnpm harness:validate:changed`
## Orchestration Task Sketch
- `T1`: polish `StatCard`
- `T2`: polish `DataTable`
- `T3`: polish `EmptyState`
- `T4`: polish `Command`, `Combobox`, and `Select`
- `T5`: polish `MetricCard`
- `T6`: polish base `Card`
- `T7 -> T1,T2,T3,T4,T5,T6`: integrate worker results and run focused validation
## Status Log
- `2026-03-25 16:26` started the six-slice polish pass after reviewing the current design language, component implementations, and representative Storybook stories
- `2026-03-25 16:29` wrote the execution plan and prepared six isolated worker slices plus a main-thread integration pass
- `2026-03-25 16:38` completed the delegated `Card`, `StatCard`, `EmptyState`, `MetricCard`, `Command/Combobox/Select`, and `DataTable` slices and reviewed the combined result set in the main thread
- `2026-03-25 16:41` validated the combined changes with targeted Vitest coverage (`card`, `stat-card`, `empty-state`, `metric-card`, `command`, `combobox`, `select`, `data-table`), `pnpm build:docs`, `pnpm --filter @ai-ui/ui exec tsc --noEmit`, and `pnpm --dir apps/docs exec tsc --noEmit`
docs/exec-plans/2026-03-25-foundation-and-pattern-motion-pass.md
+82
View File
@@ -0,0 +1,82 @@
# Foundation And Pattern Motion Pass
- Status: `completed`
- Owner: `codex`
- Date: `2026-03-25`
## Goal
Run a focused third-pass polish on four remaining motion gaps: overly busy `DataTable` chrome,
under-animated foundation surfaces, static-feeling workspace patterns, and missing docs/test
coverage for `StatCard` / `MetricCard` motion behavior.
## Scope
- In scope:
- reduce excess hover lift around `DataTable` selection, search, and pagination chrome while
preserving row hover and sort-state feedback
- add restrained component-specific polish to `Alert`, `Avatar`, and `Badge`
- bring `PageHeader`, `AppShell`, and `PageFooter` closer to the existing pattern motion quality
bar set by `SidebarNav`
- add dedicated motion stories and targeted regression tests for `StatCard` and `MetricCard`
- Out of scope:
- adding new animation dependencies
- broad visual redesign unrelated to motion and interaction feedback
- touching unrelated in-progress component work
## Constraints
- Respect `DESIGN.md` and keep one calm, spatial motion language.
- Keep write scopes isolated so workers do not collide.
- Preserve existing public APIs unless a very small compatibility-safe addition is justified.
- Do not revert unrelated work already present in the dirty worktree.
## Ownership
- Main thread:
- plan, review, integration, and validation
- Worker 1:
- `packages/ui/src/components/data-table*`
- `apps/docs/src/components/data-table.stories.tsx`
- Worker 2:
- `packages/ui/src/components/alert*`
- `packages/ui/src/components/avatar*`
- `packages/ui/src/components/badge*`
- nearest owned stories/tests if needed
- Worker 3:
- `packages/ui/src/patterns/page-header*`
- `packages/ui/src/patterns/app-shell*`
- `packages/ui/src/patterns/page-footer*`
- nearest owned stories/tests if needed
- Worker 4:
- `packages/ui/src/components/stat-card*`
- `packages/ui/src/components/metric-card*`
- `apps/docs/src/components/stat-card.stories.tsx`
- `apps/docs/src/components/metric-card.stories.tsx`
## Plan
1. Write the execution plan and confirm the four disjoint ownership slices.
2. Dispatch four workers with isolated write scopes and keep main-thread ownership limited to
review, integration, and validation.
3. Review the returned slices, fix any integration gaps, and avoid broad shared-file churn.
4. Run focused tests and typechecks for the affected components and docs surfaces.
## Validation
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/data-table.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/alert.test.tsx packages/ui/src/components/avatar.test.tsx packages/ui/src/components/badge.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/stat-card.test.tsx packages/ui/src/components/metric-card.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/patterns/page-header.test.tsx packages/ui/src/patterns/app-shell.test.tsx packages/ui/src/patterns/page-footer.test.tsx`
- `pnpm --filter @ai-ui/ui exec tsc --noEmit`
- `pnpm --dir apps/docs exec tsc --noEmit`
## Status Log
- `2026-03-25 17:27` started the pass after the previous motion review identified remaining polish
gaps in `DataTable`, foundation surfaces, workspace patterns, and motion-story/test coverage
- `2026-03-25 17:28` wrote the execution plan and dispatched four isolated workers for
`DataTable`, foundation components, workspace patterns, and KPI-card coverage
- `2026-03-25 17:33` reviewed and accepted all four returned slices, then validated the combined
result set with focused Vitest coverage plus `pnpm --filter @ai-ui/ui exec tsc --noEmit` and
`pnpm --dir apps/docs exec tsc --noEmit`
docs/exec-plans/2026-03-25-motion-accessibility-and-selection-pass.md
+93
View File
@@ -0,0 +1,93 @@
# Motion Accessibility And Selection Pass
- Status: `completed`
- Owner: `codex`
- Date: `2026-03-25`
## Goal
Polish the remaining low-level interaction motion gaps called out in the motion review, with an
emphasis on reduced-motion correctness, selection-state feedback, and bringing lower-tier
components closer to the established `Command` / `Combobox` / `Tabs` motion quality bar.
## Scope
- In scope:
- add explicit reduced-motion handling for continuous loader animation surfaces
- soften `Checkbox` and `RadioGroup` selection feedback with short scale/fade indicator motion
- give `Tooltip` a light rise to match the rest of the overlay family
- reduce layout-heavy motion where it is currently doing too much work in `Accordion`,
`Sparkbar`, and `Progress`
- polish `Select` list motion so it feels closer to `Combobox` and `Command`
- update focused tests and stories when the behavior contract changes
- Out of scope:
- introducing new animation dependencies
- expanding public APIs unless a small compatibility-safe prop is justified
- broad visual restyling unrelated to motion or reduced-motion behavior
## Constraints
- Respect `DESIGN.md` and keep one calm, spatial motion language.
- Treat `packages/ui/src/components/progress*` as main-thread-owned because reduced-motion and
motion-refinement requirements both land there.
- Do not revert or overwrite unrelated in-progress repo changes.
- Preserve static-motion behavior through `data-motion="static"` and make OS-level reduced motion
behave equivalently for continuous animation surfaces.
## Ownership
- Main thread:
- `packages/ui/src/components/progress*`
- final review, integration, and validation
- Worker 1:
- `packages/ui/src/components/spinner.tsx`
- `packages/ui/src/components/skeleton.tsx`
- nearest tests/stories if needed
- Worker 2:
- `packages/ui/src/components/checkbox*`
- `packages/ui/src/components/radio-group*`
- nearest tests/stories if needed
- Worker 3:
- `packages/ui/src/components/tooltip*`
- nearest tests/stories if needed
- Worker 4:
- `packages/ui/src/components/accordion*`
- `packages/ui/src/components/sparkbar*`
- nearest tests/stories if needed
- Worker 5:
- `packages/ui/src/components/select*`
- nearest tests/stories if needed
## Plan
1. Write the execution plan and keep `Progress` under main-thread ownership.
2. Dispatch five isolated workers for loaders, selection controls, tooltip, accordion/sparkbar,
and select.
3. Implement `Progress` reduced-motion and motion refinements locally.
4. Review and integrate the worker slices, then fix any shared token or contract issues.
5. Run focused tests for the changed surfaces and a narrow typecheck/docs pass if needed.
## Validation
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/progress.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/checkbox.test.tsx packages/ui/src/components/radio-group.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/tooltip.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/accordion.test.tsx packages/ui/src/components/sparkbar.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/select.test.tsx`
- `pnpm --filter @ai-ui/ui exec tsc --noEmit`
## Status Log
- `2026-03-25 17:18` started the focused pass after motion review identified reduced-motion gaps,
low-fidelity selection feedback, and one remaining `Select` polish gap
- `2026-03-25 17:19` wrote the execution plan, kept `progress.*` under main-thread ownership, and
dispatched five isolated workers for loaders, selection controls, tooltip, accordion/sparkbar,
and select
- `2026-03-25 17:22` landed the main-thread `Progress` refactor: reduced-motion detection now
collapses indeterminate animation, the linear bar scales with `transform` instead of animating
layout width, and segmented indeterminate progress falls back to a static partial fill when
motion is reduced
- `2026-03-25 17:24` reviewed and accepted worker slices for loaders, selection controls, tooltip,
accordion/sparkbar, and select polish
- `2026-03-25 17:25` validated the combined result set with focused component tests plus
`pnpm --filter @ai-ui/ui exec tsc --noEmit` and `pnpm --dir apps/docs exec tsc --noEmit`
docs/exec-plans/2026-03-25-motion-polish-pass.md
+89
View File
@@ -0,0 +1,89 @@
# Motion Polish Pass
- Status: `completed`
- Owner: `codex`
- Date: `2026-03-25`
## Goal
Run a second polish pass focused on interaction motion across six existing component surfaces. The
goal is to add the missing sense of staged, spatial feedback described in `DESIGN.md` without
introducing a second motion language, widening public APIs unnecessarily, or making the system feel
busy.
## Scope
- In scope:
- add polished active-guide, tooltip, and marker motion to `Chart`
- add a one-time sweep and value count-up feel to `Gauge`
- add shared active-pill motion to `Tabs` and `SegmentedControl`
- add lighter interaction transitions to the newly polished `DataTable`
- add subtle media float/breathe and CTA stagger to `EmptyState`
- add active-row glide, list crossfade, and softer loading treatment to `Command` and `Combobox`
- update the nearest stories and tests when behavior changes need review or coverage
- Out of scope:
- introducing new animation dependencies
- changing shared token files unless the main thread explicitly decides it is necessary
- turning core surfaces into ambient animation showcases
## Constraints
- Respect reduced motion and the repo's current Material-runtime design direction.
- Favor `transform`, `opacity`, `box-shadow`, and state-driven transitions over layout-heavy motion.
- Keep each worker on an isolated write scope.
- Preserve existing public component contracts unless a small compatibility-safe extension is
justified.
- Do not revert or overwrite unrelated in-progress repo changes.
## Affected Surfaces
- `packages/ui/src/components/chart*`
- `packages/ui/src/components/gauge*`
- `packages/ui/src/components/tabs*`
- `packages/ui/src/components/segmented-control*`
- `packages/ui/src/components/data-table*`
- `packages/ui/src/components/empty-state*`
- `packages/ui/src/components/command*`
- `packages/ui/src/components/combobox*`
- `apps/docs/src/components/chart.stories.tsx`
- `apps/docs/src/components/gauge.stories.tsx`
- `apps/docs/src/components/tabs.stories.tsx`
- `apps/docs/src/components/segmented-control.stories.tsx`
- `apps/docs/src/components/data-table.stories.tsx`
- `apps/docs/src/components/empty-state.stories.tsx`
- `apps/docs/src/components/command.stories.tsx`
- `apps/docs/src/components/combobox.stories.tsx`
- `docs/exec-plans`
## Plan
1. Write a dedicated execution plan for the motion pass so the second round of work is resumable.
2. Dispatch six isolated workers, each owning one motion slice and its closest tests/docs.
3. Review the combined result set in the main thread and fix any compatibility or API-semantics
issues before broader validation.
4. Run focused component, typecheck, and docs validation on the combined motion changes.
5. Record results, remaining risks, and any intentionally deferred motion refinements.
## Validation
- `pnpm --filter @ai-ui/ui exec vitest run <owned test files>`
- `pnpm --filter @ai-ui/ui exec tsc --noEmit`
- `pnpm --dir apps/docs exec tsc --noEmit`
- `pnpm build:docs`
## Orchestration Task Sketch
- `T1`: polish `Chart` motion
- `T2`: polish `Gauge` motion
- `T3`: polish `Tabs` and `SegmentedControl` motion
- `T4`: polish `DataTable` motion
- `T5`: polish `EmptyState` motion
- `T6`: polish `Command` and `Combobox` motion
- `T7 -> T1,T2,T3,T4,T5,T6`: integrate results and validate
## Status Log
- `2026-03-25 16:45` started the motion-focused second pass after confirming the current component state from the first visual polish round
- `2026-03-25 16:47` wrote the motion pass plan and prepared six isolated worker slices with main-thread integration reserved for compatibility fixes and validation
- `2026-03-25 16:59` all six motion slices returned from delegated workers: `Chart`, `Gauge`, `Tabs/SegmentedControl`, `DataTable`, `EmptyState`, and `Command/Combobox`
- `2026-03-25 17:00` validated the combined result set with targeted Vitest coverage, `pnpm --filter @ai-ui/ui exec tsc --noEmit`, `pnpm --dir apps/docs exec tsc --noEmit`, and `pnpm build:docs`
docs/exec-plans/2026-03-25-progress-patterns.md
+60
View File
@@ -0,0 +1,60 @@
# Progress Patterns
- Status: `completed`
- Owner: `Codex`
- Date: `2026-03-25`
## Goal
Extend `Progress` beyond the default linear fill so the component can also render segmented
dashboard-style progress bars like the operational cost reduction example, without splitting the
API into separate one-off components.
## Scope
- In scope:
- add a structural `pattern` dimension to `Progress`
- support a segmented dashboard meter mode
- keep the existing linear pattern untouched as the default
- update tests, exports, and Storybook docs
- Out of scope:
- radial gauge visuals
- introducing a separate `Gauge` component
- modifying unrelated dashboard story drafts
## Constraints
- Keep `variant` reserved for semantic color intent.
- Preserve the existing ARIA progressbar behavior.
- Expose stable slots and `data-*` hooks for the segmented structure.
- Stay within the current Cadence UI tonal and motion language.
## Affected Surfaces
- `packages/ui/src/components/progress.tsx`
- `packages/ui/src/components/progress.variants.ts`
- `packages/ui/src/components/progress.test.tsx`
- `packages/ui/src/skins.css`
- `packages/ui/src/index.ts`
- `apps/docs/src/components/progress.stories.tsx`
## Plan
1. Add a `pattern` API for `linear` and `segmented` progress structures.
2. Implement segmented rendering with stable slots and deterministic filled-state logic.
3. Refresh docs so the segmented meter is shown in a realistic dashboard context.
4. Run targeted validation for the package and docs surfaces.
## Validation
- `pnpm --filter @ai-ui/ui typecheck`
- `pnpm --filter @ai-ui/ui test -- --run packages/ui/src/components/progress.test.tsx`
- `pnpm harness:validate:docs`
## Status Log
- `2026-03-25 17:58` Confirmed the existing Progress API is linear-only and inspected the local revenue dashboard draft for the target segmented visual language.
- `2026-03-25 18:10` Added a `pattern` dimension with segmented rendering, repeated segment slots, and progress-specific skin tokens for dashboard meters.
- `2026-03-25 18:14` Updated Storybook docs and package exports to document and expose the segmented mode.
- `2026-03-25 18:18` Verified `pnpm --filter @ai-ui/ui typecheck`, `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/progress.test.tsx --config ../../vitest.config.ts`, and targeted `eslint` on the changed files.
- `2026-03-25 18:19` `pnpm harness:validate:docs` is currently blocked by an unrelated local Storybook draft: `apps/docs/src/components/metric-card.stories.tsx` imports `MetricCard` from `@ai-ui/ui`, but that export is not present in the built package yet.
docs/exec-plans/2026-03-25-progress-refresh.md
+57
View File
@@ -0,0 +1,57 @@
# Progress Refresh
- Status: `completed`
- Owner: `Codex`
- Date: `2026-03-25`
## Goal
Bring `Progress` closer to the active Cadence UI visual language so it reads like a tonal system
component instead of a generic utility bar, while keeping the existing API and accessibility
contract intact.
## Scope
- In scope:
- refresh the `Progress` track and indicator styling
- add progress-specific skin tokens in `packages/ui/src/skins.css`
- update Storybook stories so the new anatomy, state, and motion behavior are reviewable
- keep unit coverage aligned with the component contract
- Out of scope:
- adding labels, percentages, or new public props
- changing exports or introducing new dependencies
## Constraints
- Preserve the current `Progress` API surface (`size`, `tone`, `variant`, `value`, `max`).
- Keep the stable `data-slot` and `data-state` hooks.
- Use existing token roles and motion primitives instead of hardcoded one-off colors.
- Keep indeterminate behavior usable under static/reduced motion.
## Affected Surfaces
- `packages/ui/src/components/progress.tsx`
- `packages/ui/src/components/progress.variants.ts`
- `packages/ui/src/components/progress.test.tsx`
- `packages/ui/src/skins.css`
- `apps/docs/src/components/progress.stories.tsx`
## Plan
1. Add progress skin tokens for track depth, highlight, and indicator gloss.
2. Rework the component styling around those tokens without changing the public props.
3. Refresh docs stories to show the component in more intentional, reviewable product contexts.
4. Run the narrowest harness suites that cover the changed component and docs surfaces.
## Validation
- `pnpm harness:validate:component`
- `pnpm harness:validate:docs`
## Status Log
- `2026-03-25 17:20` Read system-of-record files and inspected the current Progress source, tests, and stories.
- `2026-03-25 17:25` Started implementation for the visual refresh and docs alignment.
- `2026-03-25 17:42` Added progress skin tokens, refreshed the track and indicator styling, and rewrote the Storybook review surface.
- `2026-03-25 17:48` Verified `pnpm --filter @ai-ui/ui typecheck`, `pnpm --filter @ai-ui/ui test -- --run packages/ui/src/components/progress.test.tsx`, and `pnpm harness:validate:docs`.
- `2026-03-25 17:49` `pnpm harness:validate:component` still fails on pre-existing type errors in `apps/docs/src/revenue-dashboard.stories.tsx`, unrelated to the Progress work.