docs/dashboard-refinement.md

Dashboard refinement — 13 September 2026

This update refines the existing Nexus application. It preserves all eight dashboard views and the existing FastAPI API contracts. It does not turn the dashboard into a marketing landing page.

Components and design system

• frontend/app/tokens.css centralizes neutral surfaces, semantic colors, typography, spacing, radii, shadows, focus rings, and motion.
• globals.css replaces the old stylesheet with organized component rules and explicit responsive breakpoints. It does not layer another override patch over the old design. Tailwind excludes test fixtures from class detection.
• layout.tsx uses locally served Geist and Geist Mono variable fonts, with their license included. It also improves page descriptions, social metadata, theme color, and mobile viewport configuration.
• ui.tsx provides shared headings, badges, provider status, capability chips, switches, loading placeholders, copy feedback, and accessible dialogs.
• Playground, request tables, documentation, and charts have their own modules. Chart code loads separately from the initial application entry.
• The only API helper change is display formatting: timestamps explicitly use UTC. Fixed illustrative demo dates avoid static-export/client timestamp differences. Live data still comes from the authenticated API.

Page improvements

View	Changes
Overview	Compact operational summary; clearer metrics; removed decorative sparklines; full-width recent requests for configured workspaces; onboarding only when no providers are connected.
Providers	Neutral provider avatars, readable connection details, icon-and-text health states, consistent actions. Editing retains a priority of zero and never repopulates saved credentials.
Model explorer	Search, collapsible mobile filters, every known supported capability shown, clearer pricing and availability, accessible favorite/configure/copy controls.
Playground	Collapsible route settings, real switches, collapsed system instruction, prominent Send action, compact empty response, streamed output, useful HTTP error messages and retry. Existing provider pins and retry semantics are retained.
API keys	Compact guidance instead of a large decorative key panel; no repeated warning panels; clear expiry/status; existing one-time reveal and revocation flow.
Request logs	Readable status and latency, complete mobile card rows, accessible detail actions, fallback attempt history, existing CSV export endpoint.
Usage	Consistent chart surfaces and labels, existing date ranges, pricing coverage and unknown-value handling; CSV links retain selected days.
Documentation	Clearer integration steps and code blocks; endpoint snippets wait for the actual host origin.

Responsive behavior

Width	Implemented layout	Automated coverage
360, 390, 430 px	48 px top bar; navigation drawer; stacked data cards; single-column forms; collapsed Playground settings; bottom-sheet dialogs.	React settings disclosure and mobile drawer behavior tested; rendered geometry not verified.
768 px	Drawer navigation; two-column statistics; single-column Playground with expandable settings.	Settings disclosure tested; rendered geometry not verified.
1024 px	240 px sidebar; two-column statistics; Playground settings open beside composition.	Settings disclosure tested; rendered geometry not verified.
1280, 1440, 1920 px	Persistent sidebar; four-column statistics; content width capped; charts and routing panels arranged side by side.	Settings disclosure tested; rendered geometry not verified.

Tables retain their data and accessible actions when presented as mobile card rows. Long identifiers have wrapping or local table scrolling. Phone dialogs respond to Visual Viewport changes, support safe-area padding, and retain scrollable content with visible action areas.

Accessibility

• Native navigation links, active-page state, a skip link, labeled controls, pressed/checked states, and consistent focus indicators.
• Mobile navigation contains keyboard focus, closes on Escape, makes background content inert, and restores focus on close.
• Native dialogs have accessible names, scroll locking, close controls, and focus restoration. Their native focus containment still needs real-browser verification.
• Validation connects field errors to inputs. Request errors use alerts; progress and notifications use live status messages. Color is accompanied by text/icons.
• Reduced-motion preferences disable decorative movement.
• Automated contrast calculations pass the 4.5:1 AA text threshold for the shared text/semantic colors against all four neutral surfaces and primary-button text. These calculations do not replace a full rendered contrast audit.

Verification

• npm test: 49 passing tests covering all views, navigation, mobile drawer focus, auth login/registration/logout, custom provider validation, provider actions, model settings/favorites, keys, CSV links, logs/details, analytics requests, empty/error states, clipboard, streaming, fragmented UTF-8/SSE, retry, and cancellation.
• Automated axe DOM checks pass on all eight views. Color-contrast checks run separately against tokens because JSDOM cannot measure browser pixels.
• npm run typecheck: passed.
• npm run build: passed with Next.js static export.
• Backend regression suite: 56 passed, including routing/fallback, streaming, provider isolation, encrypted credentials, CSRF, CSV/usage, and OpenAI client compatibility.
• GitHub checks now run the frontend tests. The existing backend dependency installation is split into hashed runtime and editable development installs so pip can execute the checks.
• Dockerfile, Compose configuration, deploy/, backend source, runtime scripts, environment examples, and Next.js static-export configuration are unchanged.

Tests use mocked network responses only in the test directory. The shipped dashboard retains its real API requests, and demo requests continue to require sign-in before contacting providers.

Recommendations deliberately not followed

• Kept native selects instead of building custom listboxes: they preserve existing keyboard and mobile picker behavior.
• Retained the login form's 12-character minimum because the current backend validates that minimum on login as well as registration. The login placeholder was corrected.
• Did not fabricate historical metric deltas or sparkline data. Charts retain the existing reported analytics.
• Did not add a command palette, extra decorative animation, a new routing architecture, or a replacement hosting service.

Remaining verification

The available browser inspected the original live site, but its security policy blocked local previews. Consequently this change has not completed visual screenshot QA, real-device keyboard testing, page-overflow measurements, Lighthouse/Core Web Vitals measurement, or WebScore.ai scoring. The width tests above exercise React behavior, not CSS layout.

After reviewing and deploying these files to the existing Hugging Face Space, verify all eight views at the listed widths. Check Android Chrome and iOS Safari with the keyboard open, long names/IDs, dialog focus/scrolling, chart rendering, and horizontal overflow. Then run a fresh WebScore audit on the deployed URL. 85%+ is a target, not a verified result. No provider credentials were used for paid requests during this UI work.