feat(web): design tokens, Tailwind config, base components (TEC-3057)

- Add chart palette, motion, and z-index CSS vars to globals.css
- Replace custom theme-provider with next-themes (dark default)
- Extend tailwind.config.ts with heading fonts, spacing (row-compact,
  row-roomy, sidebar), chart colors, elevation shadows, glow shadows,
  transition timing, pill border-radius, z-index scale
- Update tick-flash animations to match design token spec (480ms)
- Add prefers-reduced-motion support for all animations
- Create base design-system components:
  Surface, SurfaceElevated, Divider, DensityProvider/useDensity,
  Numeric (VND/percent/compact formatting), Signal (up/down/neutral pill)
- Add dev-only /dev/tokens showcase route (404 in production)
- Update theme-provider tests to match next-themes integration

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/web/components/design-system/density-provider.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { createContext, useCallback, useContext, useEffect, useState } from 'react';
+
+export type DensityMode = 'compact' | 'regular' | 'roomy';
+
+interface DensityContextValue {
+  density: DensityMode;
+  setDensity: (mode: DensityMode) => void;
+}
+
+const STORAGE_KEY = 'goodgo.density';
+
+const DensityContext = createContext<DensityContextValue>({
+  density: 'regular',
+  setDensity: () => {},
+});
+
+export function useDensity() {
+  return useContext(DensityContext);
+}
+
+/** Row height in Tailwind spacing tokens per density mode. */
+export const DENSITY_ROW_HEIGHT: Record<DensityMode, string> = {
+  compact: 'h-row-compact',    // 32px
+  regular: 'h-row',            // 36px
+  roomy: 'h-row-roomy',        // 44px
+};
+
+/** Cell padding classes per density mode. */
+export const DENSITY_CELL_PADDING: Record<DensityMode, string> = {
+  compact: 'px-2 py-1',        // 4px 8px
+  regular: 'px-2.5 py-1.5',    // 6px 10px
+  roomy: 'px-3 py-2.5',        // 10px 12px
+};
+
+/** Data font size per density mode. */
+export const DENSITY_DATA_FONT: Record<DensityMode, string> = {
+  compact: 'text-data-sm',
+  regular: 'text-data-md',
+  roomy: 'text-data-md',
+};
+
+export function DensityProvider({
+  defaultDensity = 'regular',
+  children,
+}: {
+  defaultDensity?: DensityMode;
+  children: React.ReactNode;
+}) {
+  const [density, setDensityState] = useState<DensityMode>(defaultDensity);
+
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY) as DensityMode | null;
+    if (stored === 'compact' || stored === 'regular' || stored === 'roomy') {
+      setDensityState(stored);
+    }
+  }, []);
+
+  const setDensity = useCallback((mode: DensityMode) => {
+    setDensityState(mode);
+    localStorage.setItem(STORAGE_KEY, mode);
+  }, []);
+
+  return (
+    <DensityContext.Provider value={{ density, setDensity }}>
+      {children}
+    </DensityContext.Provider>
+  );
+}

apps/web/components/design-system/divider.tsx

@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils';
+
+export interface DividerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Use border-strong variant for headers/section separators. */
+  strong?: boolean;
+  /** Orientation. Default horizontal. */
+  orientation?: 'horizontal' | 'vertical';
+}
+
+export function Divider({
+  strong = false,
+  orientation = 'horizontal',
+  className,
+  ...props
+}: DividerProps) {
+  return (
+    <div
+      role="separator"
+      aria-orientation={orientation}
+      className={cn(
+        strong ? 'bg-border-strong' : 'bg-border',
+        orientation === 'horizontal' ? 'h-px w-full' : 'h-full w-px',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

apps/web/components/design-system/index.ts

@@ -18,3 +18,34 @@ export type { DashboardLayoutProps } from './dashboard-layout';
 
 export { TickerStrip } from './ticker-strip';
 export type { TickerStripProps, TickerItem } from './ticker-strip';
+
+export { Badge } from './badge';
+export type { BadgeProps } from './badge';
+
+export { StatusChip } from './status-chip';
+export type { StatusChipProps, PropertyStatus } from './status-chip';
+
+export { DensityToggle } from './density-toggle';
+export type { DensityToggleProps } from './density-toggle';
+
+export { EmptyState } from './empty-state';
+export type { EmptyStateProps } from './empty-state';
+
+export { Skeleton } from './skeleton';
+export type { SkeletonProps } from './skeleton';
+
+export { KpiCard } from './kpi-card';
+export type { KpiCardProps } from './kpi-card';
+
+export { Surface, SurfaceElevated } from './surface';
+export { Divider } from './divider';
+export type { DividerProps } from './divider';
+
+export { DensityProvider, useDensity, DENSITY_ROW_HEIGHT, DENSITY_CELL_PADDING, DENSITY_DATA_FONT } from './density-provider';
+export type { DensityMode } from './density-provider';
+
+export { Numeric } from './numeric';
+export type { NumericProps } from './numeric';
+
+export { Signal } from './signal';
+export type { SignalDirection, SignalProps } from './signal';

apps/web/components/design-system/numeric.tsx

@@ -0,0 +1,64 @@
+import { cn } from '@/lib/utils';
+
+export interface NumericProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** The numeric value to display. */
+  value: number;
+  /** Format style. Default 'vnd'. */
+  format?: 'vnd' | 'percent' | 'decimal' | 'compact';
+  /** Number of fraction digits for percent/decimal. Default 1 for percent, 0 for vnd. */
+  fractionDigits?: number;
+}
+
+const vndFormatter = new Intl.NumberFormat('vi-VN', {
+  style: 'currency',
+  currency: 'VND',
+  maximumFractionDigits: 0,
+});
+
+const compactFormatter = new Intl.NumberFormat('vi-VN', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+});
+
+function formatValue(
+  value: number,
+  format: NumericProps['format'],
+  fractionDigits?: number,
+): string {
+  switch (format) {
+    case 'percent':
+      return `${value >= 0 ? '+' : ''}${value.toFixed(fractionDigits ?? 1)}%`;
+    case 'decimal':
+      return new Intl.NumberFormat('vi-VN', {
+        minimumFractionDigits: fractionDigits ?? 0,
+        maximumFractionDigits: fractionDigits ?? 2,
+      }).format(value);
+    case 'compact':
+      return compactFormatter.format(value);
+    case 'vnd':
+    default:
+      return vndFormatter.format(value);
+  }
+}
+
+/**
+ * Numeric display — right-aligned, tabular-nums, formatted for VND/percent.
+ * Automatically sets `data-numeric` for global tabular-nums styling.
+ */
+export function Numeric({
+  value,
+  format = 'vnd',
+  fractionDigits,
+  className,
+  ...props
+}: NumericProps) {
+  return (
+    <span
+      data-numeric
+      className={cn('text-right font-mono tabular-nums', className)}
+      {...props}
+    >
+      {formatValue(value, format, fractionDigits)}
+    </span>
+  );
+}

apps/web/components/design-system/signal.tsx

@@ -0,0 +1,46 @@
+import { ArrowDown, ArrowUp, Minus } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+export type SignalDirection = 'up' | 'down' | 'neutral';
+
+export interface SignalProps {
+  /** Direction of the signal. */
+  direction: SignalDirection;
+  /** Text label shown inside the pill. */
+  label?: string;
+  /** Additional class names. */
+  className?: string;
+}
+
+const directionStyles: Record<SignalDirection, string> = {
+  up: 'bg-signal-up/10 text-signal-up',
+  down: 'bg-signal-down/10 text-signal-down',
+  neutral: 'bg-signal-neutral/10 text-signal-neutral',
+};
+
+const icons: Record<SignalDirection, React.ElementType> = {
+  up: ArrowUp,
+  down: ArrowDown,
+  neutral: Minus,
+};
+
+/**
+ * Signal pill — shows direction (up/down/neutral) with arrow icon and optional label.
+ * Uses `--signal-*` design tokens.
+ */
+export function Signal({ direction, label, className }: SignalProps) {
+  const Icon = icons[direction];
+
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1 rounded-pill px-2 py-0.5 text-xs font-medium',
+        directionStyles[direction],
+        className,
+      )}
+    >
+      <Icon className="h-3 w-3" aria-hidden="true" />
+      {label && <span>{label}</span>}
+    </span>
+  );
+}

apps/web/components/design-system/surface.tsx

@@ -0,0 +1,30 @@
+import { cn } from '@/lib/utils';
+
+/** Flat surface — uses `--background` (app bg). */
+export function Surface({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('rounded-lg bg-background text-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+/** Elevated surface — uses `--background-elevated` with shadow-elevation-1. */
+export function SurfaceElevated({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        'rounded-lg bg-background-elevated text-foreground shadow-elevation-1',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

apps/web/components/providers/__tests__/theme-provider.spec.tsx

@@ -3,35 +3,23 @@ import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
 import { ThemeProvider, useTheme } from '../theme-provider';
 
-// Provide a working localStorage mock for this test file
-const localStorageMock = (() => {
-  let store: Record<string, string> = {};
-  return {
-    getItem: vi.fn((key: string) => store[key] ?? null),
-    setItem: vi.fn((key: string, value: string) => { store[key] = value; }),
-    removeItem: vi.fn((key: string) => { delete store[key]; }),
-    clear: vi.fn(() => { store = {}; }),
-    get length() { return Object.keys(store).length; },
-    key: vi.fn((index: number) => Object.keys(store)[index] ?? null),
-  };
-})();
+// Mock next-themes
+const mockSetTheme = vi.fn();
+let mockTheme = 'dark';
+let mockResolvedTheme = 'dark';
 
-Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true });
-
-// Mock window.matchMedia (not implemented in jsdom)
-Object.defineProperty(window, 'matchMedia', {
-  writable: true,
-  value: vi.fn().mockImplementation((query: string) => ({
-    matches: false,
-    media: query,
-    onchange: null,
-    addListener: vi.fn(),
-    removeListener: vi.fn(),
-    addEventListener: vi.fn(),
-    removeEventListener: vi.fn(),
-    dispatchEvent: vi.fn(),
-  })),
-});
+vi.mock('next-themes', () => ({
+  ThemeProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  useTheme: () => ({
+    theme: mockTheme,
+    resolvedTheme: mockResolvedTheme,
+    setTheme: (t: string) => {
+      mockSetTheme(t);
+      mockTheme = t;
+      mockResolvedTheme = t;
+    },
+  }),
+}));
 
 // Test consumer component
 function ThemeConsumer() {
@@ -46,8 +34,8 @@ function ThemeConsumer() {
 
 describe('ThemeProvider', () => {
   beforeEach(() => {
-    document.documentElement.classList.remove('dark');
-    localStorageMock.clear();
+    mockTheme = 'dark';
+    mockResolvedTheme = 'dark';
     vi.clearAllMocks();
   });
 
@@ -60,54 +48,7 @@ describe('ThemeProvider', () => {
     expect(screen.getByText('Child content')).toBeInTheDocument();
   });
 
-  it('defaults to light theme', () => {
-    render(
-      <ThemeProvider>
-        <ThemeConsumer />
-      </ThemeProvider>,
-    );
-    expect(screen.getByTestId('theme')).toHaveTextContent('light');
-  });
-
-  it('toggles theme to dark', async () => {
-    const user = userEvent.setup();
-    render(
-      <ThemeProvider>
-        <ThemeConsumer />
-      </ThemeProvider>,
-    );
-
-    await user.click(screen.getByText('Toggle'));
-    expect(screen.getByTestId('theme')).toHaveTextContent('dark');
-  });
-
-  it('toggles theme back to light', async () => {
-    const user = userEvent.setup();
-    render(
-      <ThemeProvider>
-        <ThemeConsumer />
-      </ThemeProvider>,
-    );
-
-    await user.click(screen.getByText('Toggle'));
-    await user.click(screen.getByText('Toggle'));
-    expect(screen.getByTestId('theme')).toHaveTextContent('light');
-  });
-
-  it('persists theme to localStorage', async () => {
-    const user = userEvent.setup();
-    render(
-      <ThemeProvider>
-        <ThemeConsumer />
-      </ThemeProvider>,
-    );
-
-    await user.click(screen.getByText('Toggle'));
-    expect(localStorageMock.setItem).toHaveBeenCalledWith('goodgo-theme', 'dark');
-  });
-
-  it('loads stored theme from localStorage', () => {
-    localStorageMock.getItem.mockReturnValueOnce('dark');
+  it('defaults to dark theme', () => {
     render(
       <ThemeProvider>
         <ThemeConsumer />
@@ -115,11 +56,37 @@ describe('ThemeProvider', () => {
     );
     expect(screen.getByTestId('theme')).toHaveTextContent('dark');
   });
+
+  it('toggles theme to light', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeProvider>
+        <ThemeConsumer />
+      </ThemeProvider>,
+    );
+
+    await user.click(screen.getByText('Toggle'));
+    expect(mockSetTheme).toHaveBeenCalledWith('light');
+  });
+
+  it('toggles theme back to dark', async () => {
+    mockTheme = 'light';
+    mockResolvedTheme = 'light';
+    const user = userEvent.setup();
+    render(
+      <ThemeProvider>
+        <ThemeConsumer />
+      </ThemeProvider>,
+    );
+
+    await user.click(screen.getByText('Toggle'));
+    expect(mockSetTheme).toHaveBeenCalledWith('dark');
+  });
 });
 
 describe('useTheme', () => {
-  it('returns default values outside provider', () => {
+  it('returns dark as default outside provider', () => {
     render(<ThemeConsumer />);
-    expect(screen.getByTestId('theme')).toHaveTextContent('light');
+    expect(screen.getByTestId('theme')).toHaveTextContent('dark');
   });
 });

apps/web/components/providers/theme-provider.tsx

@@ -1,51 +1,31 @@
 'use client';
 
-import { createContext, useCallback, useContext, useEffect, useState } from 'react';
-
-type Theme = 'light' | 'dark';
-
-interface ThemeContextValue {
-  theme: Theme;
-  toggleTheme: () => void;
-}
-
-const ThemeContext = createContext<ThemeContextValue>({
-  theme: 'light',
-  toggleTheme: () => {},
-});
-
-export function useTheme() {
-  return useContext(ThemeContext);
-}
-
-const STORAGE_KEY = 'goodgo-theme';
+import { ThemeProvider as NextThemesProvider, useTheme as useNextTheme } from 'next-themes';
 
 export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<Theme>('light');
-
-  useEffect(() => {
-    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
-    if (stored === 'dark' || stored === 'light') {
-      setTheme(stored);
-      document.documentElement.classList.toggle('dark', stored === 'dark');
-    } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
-      setTheme('dark');
-      document.documentElement.classList.add('dark');
-    }
-  }, []);
-
-  const toggleTheme = useCallback(() => {
-    setTheme((prev) => {
-      const next = prev === 'light' ? 'dark' : 'light';
-      localStorage.setItem(STORAGE_KEY, next);
-      document.documentElement.classList.toggle('dark', next === 'dark');
-      return next;
-    });
-  }, []);
-
   return (
-    <ThemeContext.Provider value={{ theme, toggleTheme }}>
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="dark"
+      storageKey="goodgo-theme"
+      enableSystem={false}
+    >
       {children}
-    </ThemeContext.Provider>
+    </NextThemesProvider>
   );
 }
+
+/**
+ * Backward-compatible useTheme hook.
+ * Returns `theme` ('light' | 'dark') and `toggleTheme`.
+ */
+export function useTheme() {
+  const { theme, setTheme, resolvedTheme } = useNextTheme();
+  const current = (resolvedTheme ?? theme ?? 'dark') as 'light' | 'dark';
+
+  const toggleTheme = () => {
+    setTheme(current === 'dark' ? 'light' : 'dark');
+  };
+
+  return { theme: current, toggleTheme };
+}