Design audit 1/4: Foundations (#124)

Design audit 1/4: foundations (tokens, motion system, touch, reduced motion)

Author: Programcode

.claude/skills/verify-debatelab/SKILL.md

@@ -172,6 +172,7 @@ It never touches `.verify/artifacts/` or `.verify/logs/`, and it is safe to run
 ## Gotchas
 
 - Live runs are slow: sparring and crossfire take several minutes each because the model must reason. Use `-g` to run one test while iterating.
+- Vite does not reload `tailwind.config.ts` on a running stack: new theme keys, variants and the `future` flags produce no CSS until `$H down && $H up`. Edits to `src/` and `src/index.css` apply on reload as usual.
 - The fake provider rejects prompts it doesn't recognize. If a prompt change makes a feature fail with a provider error, update `e2e/full-stack/fake-openrouter.mjs`. Don't mock around it.
 - Once, the fake-provider container was SIGKILLed about 20 seconds after `up`, and the cause was never found. Doctor catches this, and `drive` refuses to run until you `down && up`.
 - Demo-code users are Pro with a daily limit of 999. To test quota or tier paths, change `user_settings` through `admin` inside the recipe, as `e2e/full-stack/case-generation.spec.ts` does.

e2e/animation-polish.spec.ts

@@ -70,7 +70,8 @@ test('removes non-essential route and state movement for reduced motion', async
   const options = await openGenerateOptions(page);
 
   await expect(page.locator('[data-route-transition-ms]')).toHaveCount(0);
-  await expect.poll(() => options.evaluate((element) => getComputedStyle(element).transitionDuration)).toBe('0s');
+  // Reduced motion keeps gentle fades but nothing that moves: no transform, height or grid-row transitions.
+  await expect.poll(() => options.evaluate((element) => getComputedStyle(element).transitionProperty)).not.toMatch(/transform|grid-template-rows|height|all/);
   await expect.poll(() => page.evaluate(() => document.getAnimations().filter((animation) => animation.playState === 'running').length)).toBe(0);
   await page.screenshot({ path: testInfo.outputPath('reduced-empty-options.png'), fullPage: true });
 

index.html

@@ -13,7 +13,8 @@
     <meta name="author" content="DebateLab" />
     <meta name="robots" content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1" />
     <meta name="language" content="English" />
-    <meta name="theme-color" content="#0f172a" />
+    <meta name="theme-color" content="#f1f5f9" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#0f172a" media="(prefers-color-scheme: dark)" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <link rel="canonical" href="https://debate.pi-stack.org/" />
     <link rel="manifest" href="/manifest.webmanifest" />

plans/2026-10-09-design-audit.md

@@ -6,6 +6,7 @@ Every plan lives in this folder and opens with a `**Status:**` line; a plan list
 
 ## In progress
 
+- **Design audit.** UI audit against Emil Kowalski's Apple-design and motion skills: broken toast stacking, collapsed text-colour tokens, a global CSS layer that overrides the primitives, touch and reduced-motion gaps, wayfinding and undo. Shipping as a four-PR stack: Foundations, Shell, AI tools, Landing. Plan: [2026-10-09 design audit](2026-10-09-design-audit.md).
 - **Staging that tracks main.** Audit of staging, the VPS sync timer, the seed, and what to delete. Plan: [2026-10-03 staging loop](2026-10-03-staging-loop.md). Previews come from #95 and the staging spec fix from #100.
 
 ## Backlog

plans/README.md

@@ -9,7 +9,7 @@ export function OfflineIndicator() {
   if (!offline) return null;
 
   return (
-    <div className="fixed bottom-4 left-1/2 z-[60] flex -translate-x-1/2 items-center gap-2 rounded-full border bg-background/95 px-4 py-2 text-sm font-medium text-foreground shadow-lg backdrop-blur" role="status" aria-live="polite">
+    <div className="native-safe-fixed-bottom fixed left-1/2 z-[60] flex -translate-x-1/2 items-center gap-2 rounded-full border bg-background/95 px-4 py-2 text-sm font-medium text-foreground shadow-lg backdrop-blur" role="status" aria-live="polite">
       <WifiOff className="h-4 w-4 text-amber-500" />
       {t('offlineIndicator.label', 'Offline mode')}
     </div>

src/components/OfflineIndicator.tsx

@@ -1,25 +1,61 @@
 // src/components/ThemeProvider.tsx
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { useSettingsStore } from '@/lib/stores/settings-store';
 
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-    const theme = useSettingsStore((state) => state.theme);
+type ResolvedTheme = 'light' | 'dark';
 
-    useEffect(() => {
-        const root = window.document.documentElement;
+// Browser chrome colours, matching --background in each theme.
+const THEME_COLORS: Record<ResolvedTheme, string> = { light: '#f1f5f9', dark: '#0f172a' };
+
+function syncThemeColor(theme: 'light' | 'dark' | 'system', resolved: ResolvedTheme) {
+    document.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]').forEach((meta) => {
+        const media = meta.getAttribute('media') ?? '';
+        const own: ResolvedTheme = media.includes('dark') ? 'dark' : 'light';
+        // In system mode each meta keeps its own media colour; an explicit choice wins everywhere.
+        meta.content = THEME_COLORS[theme === 'system' ? own : resolved];
+    });
+}
 
-        // Remove existing theme classes
+function applyTheme(resolved: ResolvedTheme, animate: boolean) {
+    const root = window.document.documentElement;
+    const swap = () => {
         root.classList.remove('light', 'dark');
+        root.classList.add(resolved);
+    };
+
+    if (!animate || window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        swap();
+        return;
+    }
+
+    // One 200ms crossfade of the whole page instead of every surface easing at its own speed.
+    if (typeof document.startViewTransition === 'function') {
+        const transition = document.startViewTransition(swap);
+        // A newer switch skips this one's animation; the class swap still runs, so that's fine.
+        transition.ready.catch(() => {});
+        transition.finished.catch(() => {});
+        return;
+    }
+
+    // No View Transitions: switch in a single frame so nothing ripples.
+    root.classList.add('theme-switching');
+    swap();
+    requestAnimationFrame(() => requestAnimationFrame(() => root.classList.remove('theme-switching')));
+}
+
+const systemTheme = (): ResolvedTheme =>
+    window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+    const theme = useSettingsStore((state) => state.theme);
+    const mounted = useRef(false);
 
-        if (theme === 'system') {
-            // Check system preference
-            const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
-                ? 'dark'
-                : 'light';
-            root.classList.add(systemTheme);
-        } else {
-            root.classList.add(theme);
-        }
+    useEffect(() => {
+        const resolved = theme === 'system' ? systemTheme() : theme;
+        // theme-init.js already applied the stored theme before first paint.
+        applyTheme(resolved, mounted.current);
+        syncThemeColor(theme, resolved);
+        mounted.current = true;
     }, [theme]);
 
     // Listen for system theme changes when in 'system' mode
@@ -29,9 +65,7 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
         const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
 
         const handleChange = (e: MediaQueryListEvent) => {
-            const root = window.document.documentElement;
-            root.classList.remove('light', 'dark');
-            root.classList.add(e.matches ? 'dark' : 'light');
+            applyTheme(e.matches ? 'dark' : 'light', true);
         };
 
         mediaQuery.addEventListener('change', handleChange);
@@ -40,5 +74,3 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
 
     return <>{children}</>;
 }
-
-

src/components/ThemeProvider.tsx

@@ -99,7 +99,7 @@ const MessageBubble = React.memo(function MessageBubble({ message, onSave }: { m
           <Button
             variant="ghost"
             size="icon"
-            className="absolute -right-10 top-0 opacity-0 group-hover:opacity-100 transition-opacity h-8 w-8"
+            className="absolute -right-10 top-0 h-8 w-8 opacity-60 transition-opacity hover:opacity-100 focus-visible:opacity-100 group-hover:opacity-100"
             onClick={() => {
               const title = message.content.length > 30
                 ? `${message.content.slice(0, 30)}...`

src/components/features/ask/AskChat.tsx

@@ -118,7 +118,7 @@ export function AttackForm({ onSubmit, isLoading, importedCase, debateContext =
                 <SlidersHorizontal className="h-4 w-4" />
                 {t('attackForm.moreOptions')}
               </span>
-              <ChevronDown className={`h-4 w-4 transition-transform duration-300 ${optionsOpen ? 'rotate-180' : ''}`} />
+              <ChevronDown className={`h-4 w-4 transition-transform duration-150 ease-out-strong ${optionsOpen ? 'rotate-180' : ''}`} />
             </Button>
           </div>
 

src/components/features/attack/AttackForm.tsx

@@ -39,7 +39,7 @@ function WeaknessCard({ weakness }: { weakness: Weakness }) {
   const Icon = config.icon;
 
   return (
-    <div className={cn('rounded-lg border p-4 space-y-3 motion-list-item card-hover-glow', config.border, config.bg)}>
+    <div className={cn('rounded-lg border p-4 space-y-3 motion-list-item', config.border, config.bg)}>
       <div className="flex items-start justify-between gap-2">
         <div className="flex items-start gap-2">
           <Icon className={cn('h-5 w-5 mt-0.5', config.color)} />