feat(ui): polish core component surfaces

2026-03-25 19:49:15 +08:00
parent eccaacece7
commit cc1509d2f6
64 changed files with 2707 additions and 353 deletions
@@ -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`