refactor(web): refine dashboard UI hierarchy

Improve shared component spacing, typography, controls, tables, feedback states, and accessibility. Simplify sidebar and explore navigation, consolidate dashboard actions and status ownership, and expand the onboarding experience.

Author: atulmgupta

web/src/__tests__/mobile.viewport.test.tsx

@@ -143,15 +143,15 @@ describe('mobile.viewport :: shared primitives at 375px', () => {
     });
   });
 
-  it('PageHeader stacks vertically on mobile, row on ≥ sm', () => {
+  it('PageHeader stacks vertically until the large-screen action layout', () => {
     patchMatchMedia(() => false);
     const { container } = render(
       <I18nextProvider i18n={i18n}>
         <PageHeader title="Charging" subtitle="14 sessions" actions={<button>Export</button>} />
       </I18nextProvider>,
     );
     // The flex container is the first descendant of the FadeIn wrapper.
-    const flex = container.querySelector('.flex.flex-col.sm\\:flex-row') as HTMLElement | null;
+    const flex = container.querySelector('.flex.flex-col.lg\\:flex-row') as HTMLElement | null;
     expect(flex).not.toBeNull();
     // Subtitle uses a readable text-sm size regardless of viewport (no
     // shrunken text-xs on mobile — PageHeader subtitles stay legible).

web/src/components/charts/ChartContainer.tsx

@@ -5,9 +5,7 @@ import { cn } from '@/lib/cn';
 import { Spinner } from '@/components/feedback/Spinner';
 import { EmptyState } from '@/components/feedback/EmptyState';
 import { SectionErrorBoundary } from '@/components/feedback/SectionErrorBoundary';
-import { Button } from '@/components/ui/Button';
-import { Text } from '@/components/ui/Typography';
-import { FullscreenButton } from '@/components/ui/FullscreenButton';
+import { Button, FullscreenButton, Heading, Text } from '@/components/ui';
 import { VisuallyHidden } from '@/components/a11y';
 import { useChartExport } from '@/hooks/useChartExport';
 import { downloadCSV, objectsToCSV, defaultExportFilename, type CsvCellValue } from '@/lib/csvExport';
@@ -363,7 +361,7 @@ export const ChartContainer = forwardRef<HTMLDivElement, ChartContainerProps>(
           // ignored the active theme entirely — on all 140 presets a chart
           // frame rendered generic white/near-black instead of the palette's
           // own surface, so charts never matched the panels beside them.
-          'group rounded-panel border border-[var(--panel-border)] bg-[var(--panel-bg)] p-4 shadow-panel',
+          'group rounded-panel border border-[var(--panel-border)] bg-[var(--panel-bg)] p-5 shadow-panel',
           // Tailwind preflight already removes default <figure> margins;
           // re-state `m-0` defensively so any consumer override of preflight
           // doesn't shift the chart vertical rhythm.
@@ -379,19 +377,13 @@ export const ChartContainer = forwardRef<HTMLDivElement, ChartContainerProps>(
           className,
         )}
       >
-        <div className="mb-4 flex items-start justify-between border-b border-[var(--border-subtle)] pb-3">
-          <div>
-            <Text
-              as="h3"
-              id={titleId}
-              size="sm"
-              weight="semibold"
-              color="primary"
-            >
+        <div className="mb-5 flex items-start justify-between gap-4 border-b border-[var(--border-subtle)] pb-4">
+          <div className="min-w-0">
+            <Heading level="panel" id={titleId}>
               {title}
-            </Text>
+            </Heading>
             {subtitle && (
-              <Text as="p" variant="caption">{subtitle}</Text>
+              <Text as="p" variant="caption" className="mt-1 leading-relaxed">{subtitle}</Text>
             )}
           </div>
           <div

web/src/components/data-display/MetricBar.tsx

@@ -17,20 +17,29 @@ import { fmtNumber } from '../../lib/numberFormat'
 export function MetricBar({ value, max, color, label, sublabel }: {
   value: number; max: number; color: string; label: string; sublabel?: string
 }) {
-  const pct = Math.min((value / max) * 100, 100)
+  const safeValue = Number.isFinite(value) ? value : 0
+  const safeMax = Number.isFinite(max) && max > 0 ? max : 0
+  const pct = safeMax > 0 ? Math.min(Math.max((safeValue / safeMax) * 100, 0), 100) : 0
+  const boundedValue = safeMax > 0 ? Math.min(Math.max(safeValue, 0), safeMax) : 0
   return (
-    <div>
-      <div className="flex items-center justify-between mb-1.5">
-        <span className="text-xs font-medium text-[var(--text-secondary)]">{label}</span>
-        <span className="text-xs font-mono" style={{ color }}>{sublabel ?? fmtNumber(value)}</span>
+    <div
+      role="progressbar"
+      aria-label={label}
+      aria-valuemin={0}
+      aria-valuemax={safeMax}
+      aria-valuenow={boundedValue}
+    >
+      <div className="mb-2 flex items-center justify-between gap-3">
+        <span className="text-sm font-medium text-[var(--text-secondary)]">{label}</span>
+        <span className="font-mono text-sm" style={{ color }}>{sublabel ?? fmtNumber(safeValue)}</span>
       </div>
-      <div className="h-2 rounded-full bg-[var(--surface-2)] overflow-hidden">
+      <div className="h-2.5 overflow-hidden rounded-pill bg-[var(--surface-2)]">
         <motion.div
-          className="h-full rounded-full"
+          className="h-full rounded-pill"
           initial={{ width: 0 }}
           animate={{ width: `${pct}%` }}
           transition={{ duration: 1, ease: [0.16, 1, 0.3, 1] }}
-          style={{ background: `linear-gradient(90deg, ${color}99, ${color})`, boxShadow: `0 0 8px ${color}40` }}
+          style={{ background: `linear-gradient(90deg, ${color}99, ${color})` }}
         />
       </div>
     </div>

web/src/components/data-display/MetricCard.tsx

@@ -2,8 +2,7 @@ import { type ReactNode } from 'react'
 import { useTranslation } from 'react-i18next'
 import { cn } from '../../lib/cn'
 import { type NeonColor, neonColorMap } from '../../lib/tokens'
-import { Card } from '../ui/Card'
-import { HelpTooltip, type HelpTooltipProps } from '../ui/HelpTooltip'
+import { Card, HelpTooltip, Text, type HelpTooltipProps } from '@/components/ui'
 import { Delta, type DeltaProps } from './Delta'
 
 /**
@@ -52,13 +51,17 @@ export function MetricCard({ label, value, icon, color = 'cyan', change, delta,
     <Card
       padding="none"
       data-role="metric-card"
-      className={cn('min-h-24 p-4', className)}
+      className={cn('min-h-28 p-5', className)}
     >
-      <div className="flex items-start justify-between gap-3">
+      <div className="flex items-start justify-between gap-4">
         <div className="min-w-0 flex-1">
-          <p
+          <Text
+            as="p"
+            size="sm"
+            weight="medium"
+            color="secondary"
             data-role="metric-label"
-            className="flex items-center gap-1 truncate text-xs font-medium leading-snug text-[var(--text-secondary)]"
+            className="flex items-center gap-1.5 truncate leading-snug"
           >
             <span className="truncate">{label}</span>
             {help && (
@@ -68,22 +71,26 @@ export function MetricCard({ label, value, icon, color = 'cyan', change, delta,
                 ariaLabel={help.ariaLabel ?? t('metricCard.moreInfoAbout', 'More info about {{label}}', { label })}
               />
             )}
-          </p>
-          <p
+          </Text>
+          <Text
+            as="p"
+            size="3xl"
+            weight="semibold"
+            color="primary"
             data-role="metric-value"
-            className="mt-3 text-2xl font-semibold leading-tight tracking-[-0.025em] text-[var(--text-primary)]"
+            className="mt-3 leading-tight tracking-[-0.025em] tabular-nums"
           >
             {value}
-          </p>
+          </Text>
           {subtitle && (
-            <p data-role="metric-subtitle" className="mt-1.5 truncate text-2xs text-[var(--text-muted)]">
+            <Text as="p" variant="caption" data-role="metric-subtitle" className="mt-1.5 truncate">
               {subtitle}
-            </p>
+            </Text>
           )}
           {change && !delta && (
-            <p className={cn('mt-1 text-2xs font-medium', change.positive ? 'text-emerald-300' : 'text-rose-300')}>
+            <Text as="p" size="xs" weight="medium" className={cn('mt-1.5', change.positive ? 'text-emerald-300' : 'text-rose-300')}>
               {change.positive ? '↑' : '↓'} {change.value}
-            </p>
+            </Text>
           )}
           {delta && (
             <div className="mt-1">
@@ -95,7 +102,7 @@ export function MetricCard({ label, value, icon, color = 'cyan', change, delta,
           <div
             data-role="metric-icon"
             data-color={color}
-            className="flex shrink-0 items-center justify-center rounded-shape-md border border-[var(--border-default)] bg-[var(--surface-2)] p-2"
+            className="flex shrink-0 items-center justify-center rounded-shape-lg border border-[var(--border-default)] bg-[var(--surface-2)] p-2.5 shadow-e1"
           >
             <div className={c.text}>{icon}</div>
           </div>

web/src/components/data-display/StatCard.test.tsx

@@ -51,7 +51,7 @@ describe('StatCard — core rendering', () => {
     const { container } = render(
       <StatCard label="X" value={1} className="col-span-2" />,
     );
-    expect(card(container)).toHaveClass('flex', 'flex-col', 'gap-1', 'col-span-2');
+    expect(card(container)).toHaveClass('flex', 'flex-col', 'gap-2', 'min-h-28', 'p-5', 'col-span-2');
   });
 });
 
@@ -117,7 +117,7 @@ describe('StatCard — trend', () => {
       />,
     );
     const row = screen.getByText('+12%').closest('div') as HTMLElement;
-    expect(row).toHaveClass('text-green-600');
+    expect(row).toHaveClass('text-emerald-700', 'dark:text-emerald-300');
     // Direction is conveyed by a word too, not colour alone (WCAG 1.4.1).
     expect(within(row).getByText('increased')).toBeInTheDocument();
     const glyph = within(row).getByText('↑');
@@ -133,7 +133,7 @@ describe('StatCard — trend', () => {
       />,
     );
     const row = screen.getByText('-8%').closest('div') as HTMLElement;
-    expect(row).toHaveClass('text-red-600');
+    expect(row).toHaveClass('text-rose-700', 'dark:text-rose-300');
     expect(within(row).getByText('decreased')).toBeInTheDocument();
     expect(within(row).getByText('↓')).toBeInTheDocument();
   });
@@ -159,8 +159,8 @@ describe('StatCard — trend', () => {
       />,
     );
     const row = screen.getByText('-5%').closest('div') as HTMLElement;
-    expect(row).toHaveClass('text-green-600');
-    expect(row).not.toHaveClass('text-red-600');
+    expect(row).toHaveClass('text-emerald-700', 'dark:text-emerald-300');
+    expect(row).not.toHaveClass('text-rose-700');
   });
 
   it('omits the trend row when no trend is supplied', () => {

web/src/components/data-display/StatCard.tsx

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Card } from '@/components/ui/Card';
+import { Card, MetricValue, Text } from '@/components/ui';
 import { Skeleton } from '@/components/feedback/Skeleton';
 import { cn } from '@/lib/cn';
 import { VisuallyHidden } from '@/components/a11y';
@@ -74,38 +74,44 @@ export function StatCard({ label, value, unit, icon, trend, sublabel, loading, c
         : t('statCard.trend.unchanged', 'no change');
 
   return (
-    <Card className={cn('flex flex-col gap-1', className)}>
-      <div className="flex items-center justify-between">
-        <span className="text-sm font-medium text-[var(--text-muted)]">{label}</span>
+    <Card className={cn('flex min-h-28 flex-col gap-2 p-5', className)}>
+      <div className="flex items-center justify-between gap-3">
+        <Text as="span" size="sm" weight="medium" color="secondary">{label}</Text>
         {icon ? (
-          <span aria-hidden="true" className="text-[var(--text-muted)]">
+          <span
+            aria-hidden="true"
+            className="rounded-shape-md border border-[var(--border-default)] bg-[var(--surface-2)] p-2 text-[var(--text-muted)]"
+          >
             {icon}
           </span>
         ) : null}
       </div>
       <div className="flex items-baseline gap-1">
-        <span className="text-2xl font-bold">{displayValue}</span>
+        <MetricValue>{displayValue}</MetricValue>
         {unit && valueIsPresent ? (
-          <span className="text-sm text-[var(--text-muted)]">{unit}</span>
+          <Text as="span" size="sm" color="muted">{unit}</Text>
         ) : null}
       </div>
       {trend ? (
-        <div
+        <Text
+          as="div"
+          size="xs"
+          weight="medium"
           className={cn(
-            'flex items-center gap-1 text-xs',
+            'flex items-center gap-1',
             trend.positive
-              ? 'text-green-600'
+              ? 'text-emerald-700 dark:text-emerald-300'
               : direction === 'flat'
                 ? 'text-[var(--text-muted)]'
-                : 'text-red-600',
+                : 'text-rose-700 dark:text-rose-300',
           )}
         >
           <span aria-hidden="true">{TREND_GLYPH[direction]}</span>
           <VisuallyHidden>{trendDescription}</VisuallyHidden>
           <span>{trend.value ?? ''}</span>
-        </div>
+        </Text>
       ) : null}
-      {sublabel ? <span className="text-xs text-[var(--text-muted)]">{sublabel}</span> : null}
+      {sublabel ? <Text as="span" variant="caption">{sublabel}</Text> : null}
     </Card>
   );
 }

web/src/components/feedback/AlertBanner.test.tsx

@@ -48,10 +48,10 @@ describe('AlertBanner', () => {
 
   it('maps each variant to theme-safe border, title, and body colours', () => {
     const cases: Array<[AlertVariant, RegExp, string, string, string, string]> = [
-      ['info', /border-neon-cyan/, 'text-cyan-800', 'dark:text-cyan-300', 'text-cyan-800', 'dark:text-cyan-200'],
-      ['success', /border-neon-green/, 'text-emerald-800', 'dark:text-emerald-300', 'text-emerald-800', 'dark:text-emerald-200'],
-      ['warning', /border-neon-amber/, 'text-amber-800', 'dark:text-amber-300', 'text-amber-800', 'dark:text-amber-200'],
-      ['danger', /border-neon-red/, 'text-rose-800', 'dark:text-rose-300', 'text-rose-800', 'dark:text-rose-200'],
+      ['info', /border-neon-cyan/, 'text-cyan-900', 'dark:text-cyan-200', 'text-cyan-800', 'dark:text-cyan-100'],
+      ['success', /border-neon-green/, 'text-emerald-900', 'dark:text-emerald-200', 'text-emerald-800', 'dark:text-emerald-100'],
+      ['warning', /border-neon-amber/, 'text-amber-900', 'dark:text-amber-200', 'text-amber-800', 'dark:text-amber-100'],
+      ['danger', /border-neon-red/, 'text-rose-900', 'dark:text-rose-200', 'text-rose-800', 'dark:text-rose-100'],
     ]
     for (const [variant, borderRe, lightTitle, darkTitle, lightBody, darkBody] of cases) {
       const { container, unmount } = render(

web/src/components/feedback/AlertBanner.tsx

@@ -1,6 +1,7 @@
 import { type ReactNode, type HTMLAttributes } from 'react'
 import { useTranslation } from 'react-i18next'
 import { cn } from '../../lib/cn'
+import { Button } from '@/components/ui'
 import { X } from 'lucide-react'
 
 export type AlertVariant = 'info' | 'success' | 'warning' | 'danger'
@@ -20,10 +21,10 @@ export interface AlertBannerProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 const alertVariantMap: Record<AlertVariant, { border: string; bg: string; text: string; titleText: string }> = {
-  info:    { border: 'border-neon-cyan/20',   bg: 'bg-neon-cyan/5',   text: 'text-cyan-800 dark:text-cyan-200',       titleText: 'text-cyan-800 dark:text-cyan-300' },
-  success: { border: 'border-neon-green/20',  bg: 'bg-neon-green/5',  text: 'text-emerald-800 dark:text-emerald-200', titleText: 'text-emerald-800 dark:text-emerald-300' },
-  warning: { border: 'border-neon-amber/20',  bg: 'bg-neon-amber/5',  text: 'text-amber-800 dark:text-amber-200',      titleText: 'text-amber-800 dark:text-amber-300' },
-  danger:  { border: 'border-neon-red/20',    bg: 'bg-neon-red/5',    text: 'text-rose-800 dark:text-rose-200',       titleText: 'text-rose-800 dark:text-rose-300' },
+  info:    { border: 'border-neon-cyan/25',   bg: 'bg-neon-cyan/10',  text: 'text-cyan-800 dark:text-cyan-100',       titleText: 'text-cyan-900 dark:text-cyan-200' },
+  success: { border: 'border-neon-green/25',  bg: 'bg-neon-green/10', text: 'text-emerald-800 dark:text-emerald-100', titleText: 'text-emerald-900 dark:text-emerald-200' },
+  warning: { border: 'border-neon-amber/25',  bg: 'bg-neon-amber/10', text: 'text-amber-800 dark:text-amber-100',      titleText: 'text-amber-900 dark:text-amber-200' },
+  danger:  { border: 'border-neon-red/25',    bg: 'bg-neon-red/10',   text: 'text-rose-800 dark:text-rose-100',       titleText: 'text-rose-900 dark:text-rose-200' },
 }
 
 /**
@@ -49,24 +50,26 @@ export function AlertBanner({ variant, title, children, onClose, icon, className
   const { t } = useTranslation()
   const v = alertVariantMap[variant] ?? alertVariantMap.info
   return (
-    <div className={cn('flex items-start gap-3 rounded-xl border p-4 backdrop-blur-sm', v.border, v.bg, className)} {...props}>
+    <div className={cn('flex items-start gap-3.5 rounded-panel border p-4 shadow-e1 backdrop-blur-sm', v.border, v.bg, className)} {...props}>
       {icon && <div className={cn('shrink-0 mt-0.5', v.titleText)} aria-hidden>{icon}</div>}
       <div className="flex-1 min-w-0">
-        {title && <p className={cn('text-sm font-medium', v.titleText)}>{title}</p>}
-        <div className={cn('text-xs', v.text, title && 'mt-0.5')}>{children}</div>
+        {title && <p className={cn('text-sm font-semibold', v.titleText)}>{title}</p>}
+        <div className={cn('text-sm leading-relaxed', v.text, title && 'mt-1')}>{children}</div>
       </div>
       {onClose && (
-        <button
+        <Button
           type="button"
+          variant="ghost"
+          size="sm"
           onClick={onClose}
           aria-label={closeLabel ?? t('common.dismiss', 'Dismiss')}
           className={cn(
-            'shrink-0 rounded-lg p-1.5 transition-colors hover:bg-[var(--surface-2)] focus:outline-none focus-visible:ring-2 focus-visible:ring-current',
+            'h-8 w-8 shrink-0 rounded-shape-md p-0 transition-colors hover:bg-[var(--surface-2)] focus-visible:ring-current',
             v.text,
           )}
         >
-          <X className="h-3.5 w-3.5" aria-hidden />
-        </button>
+          <X className="h-4 w-4" aria-hidden />
+        </Button>
       )}
     </div>
   )

web/src/components/feedback/EmptyState.tsx

@@ -18,29 +18,33 @@ interface EmptyStateProps {
 // shared Button constants rather than hand-copied, so the visual stays in
 // lock-step with the component library by construction — a re-skin of the
 // neutral variants now reaches this CTA automatically.
-const linkButtonClasses = cn(BUTTON_BASE, BUTTON_VARIANTS.secondary, 'h-8 px-3 text-xs');
+const linkButtonClasses = cn(BUTTON_BASE, BUTTON_VARIANTS.secondary, 'h-10 px-4 text-sm');
 
 export function EmptyState({ icon, title, message, action, actionTo, className }: EmptyStateProps) {
   return (
     <div
       role="status"
-      className={cn('flex flex-col items-center justify-center py-16 text-center', className)}
+      className={cn('flex flex-col items-center justify-center px-4 py-16 text-center', className)}
     >
-      {icon && <div className="mb-4 text-[var(--text-muted)]">{icon}</div>}
+      {icon && (
+        <div className="mb-5 rounded-shape-xl border border-[var(--border-default)] bg-[var(--surface-2)] p-3 text-[var(--theme-primary)] shadow-e1">
+          {icon}
+        </div>
+      )}
       {title && (
-        <Heading level="panel" className="mb-1">
+        <Heading level="panel" className="mb-2">
           {title}
         </Heading>
       )}
-      <Text variant="bodySm" as="p" className="mb-4 max-w-md">
+      <Text variant="bodySm" as="p" className="mb-6 max-w-lg leading-relaxed">
         {message}
       </Text>
       {actionTo ? (
         <Link to={actionTo.to} className={linkButtonClasses}>
           {actionTo.label}
         </Link>
       ) : action ? (
-        <CtaButton onClick={action.onClick} variant="secondary" size="sm">
+        <CtaButton onClick={action.onClick} variant="secondary" size="md">
           {action.label}
         </CtaButton>
       ) : null}