ui: dashboard design-system refactor tracking

[icebear0828]

Context

The dashboard has a clear visual identity, now documented in DESIGN.md: compact operations UI, neutral slate surfaces, GitHub-like dark mode, emerald primary actions, thin borders, small radii, and low elevation. The next step is to turn that design language into maintainable implementation instead of repeated per-page Tailwind class strings.

This is the tracking issue for the UI refactor.

Work plan

• ui: establish contrast-safe dashboard design tokens #497
• ui: add shared dashboard primitives for controls and surfaces #498
• ui: migrate dashboard shell and account workflows to shared primitives #499
• ui: migrate settings and API configuration panels to shared primitives #500
• ui: migrate usage, logs, errors, and proxy pages to shared primitives #501
• test: add dashboard design-system regression coverage #502

Acceptance criteria

• Dashboard tokens are contrast-safe and preserve the current product identity.
• Repeated controls and surfaces are implemented through shared primitives.
• Header/account workflows, settings/API panels, usage/logs/errors/proxy pages are migrated.
• Light/dark behavior is consistent across all migrated pages.
• Regression coverage exists for tokens, primitive variants, and high-risk UI semantics.
• No TypeScript any is introduced.

Verification

• npm test passes.
• npm run build passes.
• Browser verification at localhost:8080 covers overview, accounts, API keys, proxies, usage stats, logs, errors, and settings in light and dark mode.

Notes

This is a design-system consolidation, not a page redesign. Keep the UI dense, quiet, and operational.

[icebear0828]

Dashboard Design-System Refactor Plan

Overview

This plan turns the dashboard visual direction captured in DESIGN.md into maintainable UI implementation. The goal is not a redesign: keep the product dense, operational, neutral, and fast to scan. The work should consolidate scattered Tailwind class strings into semantic tokens and shared primitives, then migrate pages in small, testable slices.

Tracking issue: #503

Constraints

• Target branch is dev.
• TypeScript must not introduce any, including as any, : any, or <any>.
• Changed UI behavior requires tests before it is considered done.
• Frontend/style changes require build output verification and browser confirmation.
• External-service E2E is not required unless a slice changes SDK/API behavior. This refactor should not.
• Preserve domain semantics, especially usage history/window values. Do not replace history data with cumulative summary values to make UI numbers look better.

Architecture Decisions

• Use DESIGN.md as the visual intent source, but prefer WCAG-safe variants when an existing documented color pair is below AA.
• Keep Tailwind as the styling engine. Add semantic tokens and typed UI primitives instead of introducing a new component library.
• Put shared dashboard primitives under web/src/components/ui/ so page components can migrate incrementally.
• Prefer small, composable primitives: Button, IconButton, Card, Panel, Input, Select, StatusBadge, ProgressBar, and Tabs.
• Keep data fetching and page state in existing page/components. The primitive layer should be presentational and typed.
• Land this as multiple PRs mapped to issues, not one large visual rewrite.

Phase 0: Baseline

Task 0.1: Carry DESIGN.md Into The Refactor Branch

Description: Add the self-contained design system document to this branch so implementation work has a stable local reference.

Acceptance criteria:

• DESIGN.md exists at repo root.
• npx @google/design.md lint DESIGN.md has zero errors.
• Known contrast warnings are treated as implementation work for ui: establish contrast-safe dashboard design tokens #497, not as blockers to keeping the document faithful to the current UI.

Verification:

• npx @google/design.md lint DESIGN.md

Dependencies: None

Files likely touched:

• DESIGN.md

Estimated scope: XS

Task 0.2: Capture Current UI Baseline

Description: Record current light/dark behavior before changing tokens or primitives.

Acceptance criteria:

• Overview, Accounts, Usage Stats, Settings, Logs, Errors, and Proxy tabs are manually checked in light and dark mode.
• Any existing visual defects that are out of scope are noted instead of silently fixed.

Verification:

• npm run build
• Browser check at localhost:8080

Dependencies: None

Files likely touched: None

Estimated scope: XS

Phase 1: Contrast-Safe Tokens (#497)

Task 1.1: Define Semantic Theme Tokens

Description: Replace scattered hard-coded UI color intent with semantic light/dark tokens for surfaces, text, borders, primary, success, warning, danger, info, avatars, and charts.

Acceptance criteria:

• Light/dark tokens exist for main surfaces, panel surfaces, borders, primary action, selected state, status colors, chart colors, and muted text.
• Existing dashboard visual identity remains operational and compact.
• Primary/action/status foreground-background pairs meet WCAG AA for their actual text sizes or are adjusted to safe variants.

Verification:

• Add/update CSS/token tests for key selectors and light/dark differences.
• npm test
• npm run build

Dependencies: Phase 0

Files likely touched:

• web/src/index.css
• web/tailwind.config.ts
• web/src/**/*.test.tsx

Estimated scope: M

Task 1.2: Apply Tokens To Existing Hotspots

Description: Apply semantic tokens to the highest-risk contrast hotspots without changing layout structure.

Acceptance criteria:

• Primary buttons, active tabs/chips, success badges, warning badges, danger badges, and avatars use contrast-safe token combinations.
• Dark-mode equivalents remain visually aligned with the current GitHub-like palette.

Verification:

• npm test
• npm run build
• Browser check: Header, account cards, usage filters, settings controls in light/dark mode.

Dependencies: Task 1.1

Files likely touched:

• web/src/App.tsx
• web/src/components/Header.tsx
• web/src/components/AccountCard.tsx
• web/src/pages/UsageStats.tsx
• web/src/components/*Settings*.tsx

Estimated scope: M

Checkpoint: Token Foundation

• ui: establish contrast-safe dashboard design tokens #497 acceptance criteria satisfied.
• No broad component migration yet.
• Browser confirms visual identity did not drift.

Phase 2: Shared Primitives (#498)

Task 2.1: Add Primitive Infrastructure

Description: Create a small typed component layer for repeated dashboard atoms and variants.

Acceptance criteria:

• Button, IconButton, Card, Panel, Input, Select, StatusBadge, ProgressBar, and Tabs exist or equivalent narrowly scoped primitives exist.
• Primitive props are typed with unions and concrete types.
• No primitive fetches data or owns page behavior.

Verification:

• Add focused tests for variant rendering/class behavior.
• npm test
• npm run build

Dependencies: Phase 1

Files likely touched:

• web/src/components/ui/*.tsx
• web/src/components/ui/*.test.tsx

Estimated scope: M

Task 2.2: Migrate CopyButton-Compatible Variants

Description: Align copy and icon-only controls with the primitive layer while preserving existing clipboard fallback behavior.

Acceptance criteria:

• Copy controls can use shared button/icon styling.
• navigator.clipboard fallback behavior is unchanged.
• Label and icon variants still render correctly.

Verification:

• Existing clipboard/copy tests pass, or add focused tests if none cover touched behavior.
• npm test

Dependencies: Task 2.1

Files likely touched:

• web/src/components/CopyButton.tsx
• shared/utils/clipboard.ts only if tests expose a real issue.

Estimated scope: S

Checkpoint: Primitive Foundation

• ui: add shared dashboard primitives for controls and surfaces #498 acceptance criteria satisfied.
• Primitive APIs are stable enough for page migration.
• No page migration has mixed in unrelated behavior changes.

Phase 3: Shell And Account Workflows (#499)

Task 3.1: Migrate Dashboard Shell

Description: Migrate sticky header, top tabs, footer-adjacent shell actions, and login gate surfaces to shared primitives.

Acceptance criteria:

• Header buttons, status pill, update controls, language/theme controls, add-account CTA, and tabs use shared primitives.
• Login card keeps the same behavior and visual hierarchy.
• Electron macOS draggable header rules remain intact.

Verification:

• Add/update tests for tab active state and login gate if touched.
• npm test
• npm run build
• Browser check: overview shell in light/dark mode.

Dependencies: Phase 2

Files likely touched:

• web/src/App.tsx
• web/src/components/Header.tsx
• web/src/components/Footer.tsx
• web/src/index.css

Estimated scope: M

Task 3.2: Migrate Account Cards And Lists

Description: Migrate account card surfaces, status badges, toggles, proxy select, quota bars, icon actions, toolbars, selection, and import/export controls.

Acceptance criteria:

• Account list/card layout remains dense and responsive.
• Status, quota, toggle, proxy assignment, label editing, refresh, import/export, and delete behavior are unchanged.
• Narrow screens do not overflow.

Verification:

• Update web/src/components/AccountList.test.tsx and add focused tests for migrated interactions if needed.
• npm test
• npm run build
• Browser check: Overview and Manage Accounts tabs in light/dark mode.

Dependencies: Task 3.1

Files likely touched:

• web/src/components/AccountCard.tsx
• web/src/components/AccountList.tsx
• web/src/components/AccountImportExport.tsx
• web/src/components/AccountBulkActions.tsx
• web/src/components/AccountTable.tsx
• web/src/pages/AccountManagement.tsx

Estimated scope: M

Checkpoint: Account Slice

• ui: migrate dashboard shell and account workflows to shared primitives #499 acceptance criteria satisfied.
• Account workflows are manually verified.
• Consider opening a PR for ui: establish contrast-safe dashboard design tokens #497-ui: migrate dashboard shell and account workflows to shared primitives #499 if diff size is already large.

Phase 4: Settings And API Configuration (#500)

Task 4.1: Migrate Settings Panels And Form Controls

Description: Migrate collapsible panels, labels, inputs, selects, checkboxes, disabled states, save/reset controls, and helper text.

Acceptance criteria:

• General, Logs, Quota, Rotation, API Key, and Ollama settings panels share panel/form primitives.
• Form values, save behavior, dirty state, disabled state, and validation remain unchanged.

Verification:

• Add/update tests for touched settings interactions.
• npm test
• npm run build

Dependencies: Phase 2

Files likely touched:

• web/src/components/GeneralSettings.tsx
• web/src/components/LogsSettings.tsx
• web/src/components/QuotaSettings.tsx
• web/src/components/RotationSettings.tsx
• web/src/components/SettingsPanel.tsx
• web/src/components/OllamaBridgeSettings.tsx

Estimated scope: M

Task 4.2: Migrate API Config, SDK Setup, And Code Examples

Description: Migrate API configuration panels, model/effort/speed controls, Anthropic setup rows, copy actions, code tabs, and code blocks.

Acceptance criteria:

• Technical fields remain monospace and compact.
• Code blocks are readable in light/dark mode.
• Model selection and copy behavior are unchanged.

Verification:

• Add/update focused tests where page behavior is touched.
• npm test
• npm run build
• Browser check: Settings tab in light/dark mode.

Dependencies: Task 4.1

Files likely touched:

• web/src/components/ApiConfig.tsx
• web/src/components/AnthropicSetup.tsx
• web/src/components/CodeExamples.tsx
• web/src/components/TestConnection.tsx

Estimated scope: M

Checkpoint: Settings Slice

• ui: migrate settings and API configuration panels to shared primitives #500 acceptance criteria satisfied.
• Settings/API workflows are manually verified.
• Open a separate PR if account slice was already shipped.

Phase 5: Operational Data Pages (#501)

Task 5.1: Migrate Usage Stats And Charts

Description: Migrate usage summary cards, range/granularity chips, chart container surfaces, legends, loading states, and empty states.

Acceptance criteria:

• History-window cards still use history/window data.
• Summary cards that intentionally use cumulative summary remain labeled and implemented that way.
• Chart colors match DESIGN.md and stay readable in light/dark mode.

Verification:

• Update web/src/pages/__tests__/usage-stats.test.tsx.
• npm test
• npm run build
• Browser check: Usage Stats tab in light/dark mode.

Dependencies: Phase 2

Files likely touched:

• web/src/pages/UsageStats.tsx
• web/src/components/UsageChart.tsx
• shared/hooks/use-usage-stats.ts only if tests expose a real issue.

Estimated scope: M

Task 5.2: Migrate Logs And Errors

Description: Migrate log table/detail panels, filters, pagination, error group cards, unread badges, raw details, empty states, and clear/mark actions.

Acceptance criteria:

• Logs and errors share card, badge, button, and code/detail primitives.
• Unread state remains clear without relying only on color.
• Raw details remain readable and scroll-safe.

Verification:

• Update web/src/pages/__tests__/logs.test.tsx and add ErrorsPage tests if needed.
• npm test
• npm run build
• Browser check: Logs and Errors tabs in light/dark mode.

Dependencies: Phase 2

Files likely touched:

• web/src/pages/LogsPage.tsx
• web/src/pages/ErrorsPage.tsx

Estimated scope: M

Task 5.3: Migrate Proxy Pages

Description: Migrate proxy pool cards, import/add forms, proxy list items, health badges, actions, and proxy settings page shell.

Acceptance criteria:

• Add/import/edit/delete/check proxy behaviors are unchanged.
• Long proxy URLs and narrow layouts remain overflow-safe.
• Health state colors are consistent with status tokens.

Verification:

• Add/update focused proxy UI tests if behavior is touched.
• npm test
• npm run build
• Browser check: Proxies tab in light/dark mode.

Dependencies: Phase 2

Files likely touched:

• web/src/components/ProxyPool.tsx
• web/src/components/ProxyGroupList.tsx
• web/src/pages/ProxySettings.tsx

Estimated scope: M

Checkpoint: Operational Pages

• ui: migrate usage, logs, errors, and proxy pages to shared primitives #501 acceptance criteria satisfied.
• All dashboard tabs are manually checked.
• Split PRs by page family if diff size grows too large.

Phase 6: Regression Coverage And Final Hardening (#502)

Task 6.1: Add Theme And Contrast Regression Tests

Description: Add tests that protect theme token output and high-risk foreground/background pairs.

Acceptance criteria:

• Tests verify important light/dark tokens exist and differ where intended.
• Tests cover primary, selected, success, warning, danger, avatar, and muted text pairs.
• Tests are deterministic and do not depend on browser-only APIs unless jsdom supports them.

Verification:

• npm test
• npm run build

Dependencies: Phases 1-5

Files likely touched:

• web/src/**/*.test.tsx
• web/src/**/*.test.ts

Estimated scope: S

Task 6.2: Full Browser Pass

Description: Verify the complete dashboard after all migrations.

Acceptance criteria:

• Overview, Accounts, API Keys, Proxies, Usage Stats, Logs, Errors, and Settings are checked in light and dark mode.
• No overlapping controls, clipped text, or broken responsive wrapping are observed.
• No console errors from migrated UI paths.

Verification:

• npm test
• npm run build
• Browser check at localhost:8080

Dependencies: Task 6.1

Files likely touched: None unless defects are found.

Estimated scope: S

PR Strategy

Prefer four or five PRs:

1. docs/ui-design-system-baseline: add DESIGN.md and this plan.
2. ui/dashboard-theme-tokens: ui: establish contrast-safe dashboard design tokens #497.
3. ui/dashboard-primitives: ui: add shared dashboard primitives for controls and surfaces #498.
4. ui/dashboard-shell-accounts: ui: migrate dashboard shell and account workflows to shared primitives #499.
5. ui/dashboard-settings-data-pages: ui: migrate settings and API configuration panels to shared primitives #500 and ui: migrate usage, logs, errors, and proxy pages to shared primitives #501, split further if large.
6. test/dashboard-design-regressions: test: add dashboard design-system regression coverage #502, can be folded into each PR if it stays small.

Each PR should target dev, include tests, and include manual browser notes.

Risks And Mitigations

Risk	Impact	Mitigation
Large diff hides behavior changes	High	Keep primitive and page migrations in separate PRs; add tests before migration
UI semantics drift during visual cleanup	High	Preserve data hooks and labels; specifically guard usage history/window tests
Dark mode regressions	Medium	Add token tests and browser-check every slice in both modes
Primitive API becomes too generic	Medium	Keep variants narrow and based on current dashboard use cases
Contrast-safe colors feel off-brand	Medium	Adjust within emerald/slate identity; compare against current rendered UI
Responsive overflow in dense toolbars	Medium	Keep flex-wrap patterns and manually verify narrow widths

Open Questions

• Should the final implementation enforce contrast in tests with a small helper, or only test known token pairs?
• Should DESIGN.md be updated after ui: establish contrast-safe dashboard design tokens #497 to reflect contrast-safe final tokens, or should it remain a faithful snapshot of the pre-refactor UI?
• Should API Keys migrate with account workflows (ui: migrate dashboard shell and account workflows to shared primitives #499) or settings/API panels (ui: migrate settings and API configuration panels to shared primitives #500)? It uses account-like list surfaces but API-config semantics.

[icebear0828]

Progress update: first dashboard design-system slice is in PR #506 and closes #497.\n\nCompleted:\n- DESIGN.md added at project root.\n- Contrast-safe semantic tokens added for primary/action/status/avatar pairs.\n- Repeated UI states/buttons migrated across overview/accounts/proxy/usage/logs/errors/settings components.\n- Mobile tab overflow found in browser pass and fixed.\n- Web tests/build/design-md lint/browser verification recorded in PR.\n\nNew blocker tracked separately: #505 for the existing root npm test failure in update-scripts-path.

[icebear0828]

Update: PR #506 now includes the extended dashboard browser smoke pass.

Additional finding from the full matrix: #/logs had page-level horizontal overflow on 390px mobile in light/dark. Fixed in 9099e85 by stacking the logs list/details panes on mobile and putting the log table inside an internal horizontal scroll container. Added a LogsPage regression test.

Current validation on PR #506:

• 32 / 32 browser smoke cases passed across 8 dashboard pages × desktop/mobile × light/dark.
• Console errors: 0; runtime exceptions: 0; page-level horizontal overflow: 0.
• cd web && npx vitest run passed.
• npx vitest run tests/unit/web/theme.test.ts passed.
• npm run build passed.

Full root npm test remains blocked by unrelated #505.