feat(client): Task 5 — React frontend Chat UI + Onboarding for PC Pal

Implements the complete elderly-friendly React frontend:
- globals.css: 18px+ fonts, high-contrast colors, large touch targets, CSS vars
- useChat.js: WebSocket hook with init/typing/response/error handling + auto-reconnect
- useUser.js: localStorage persistence, GET/POST/PUT user API calls
- ChatWindow.jsx: full-height layout, auto-scroll, typing indicator
- MessageBubble.jsx: user/assistant alignment, safety alert banner
- MessageInput.jsx: 56px+ input, Enter-to-send, auto-focus, disabled while typing
- OnboardingFlow.jsx: 3-step wizard (name, OS, comfort level), progress dots
- Header.jsx: branded header with user info display
- App.jsx: onboarding gate → chat UI routing via useUser
- main.jsx: imports globals.css, renders App in StrictMode
- index.css: stripped to minimal reset (globals.css handles styling)
- Removed Vite boilerplate: App.css, assets/react.svg, assets/vite.svg

Build verified: vite build completes with 0 errors (28 modules, 201KB JS).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

client/src/App.css

@@ -1,184 +0,0 @@
-.counter {
-  font-size: 16px;
-  padding: 5px 10px;
-  border-radius: 5px;
-  color: var(--accent);
-  background: var(--accent-bg);
-  border: 2px solid transparent;
-  transition: border-color 0.3s;
-  margin-bottom: 24px;
-
-  &:hover {
-    border-color: var(--accent-border);
-  }
-  &:focus-visible {
-    outline: 2px solid var(--accent);
-    outline-offset: 2px;
-  }
-}
-
-.hero {
-  position: relative;
-
-  .base,
-  .framework,
-  .vite {
-    inset-inline: 0;
-    margin: 0 auto;
-  }
-
-  .base {
-    width: 170px;
-    position: relative;
-    z-index: 0;
-  }
-
-  .framework,
-  .vite {
-    position: absolute;
-  }
-
-  .framework {
-    z-index: 1;
-    top: 34px;
-    height: 28px;
-    transform: perspective(2000px) rotateZ(300deg) rotateX(44deg) rotateY(39deg)
-      scale(1.4);
-  }
-
-  .vite {
-    z-index: 0;
-    top: 107px;
-    height: 26px;
-    width: auto;
-    transform: perspective(2000px) rotateZ(300deg) rotateX(40deg) rotateY(39deg)
-      scale(0.8);
-  }
-}
-
-#center {
-  display: flex;
-  flex-direction: column;
-  gap: 25px;
-  place-content: center;
-  place-items: center;
-  flex-grow: 1;
-
-  @media (max-width: 1024px) {
-    padding: 32px 20px 24px;
-    gap: 18px;
-  }
-}
-
-#next-steps {
-  display: flex;
-  border-top: 1px solid var(--border);
-  text-align: left;
-
-  & > div {
-    flex: 1 1 0;
-    padding: 32px;
-    @media (max-width: 1024px) {
-      padding: 24px 20px;
-    }
-  }
-
-  .icon {
-    margin-bottom: 16px;
-    width: 22px;
-    height: 22px;
-  }
-
-  @media (max-width: 1024px) {
-    flex-direction: column;
-    text-align: center;
-  }
-}
-
-#docs {
-  border-right: 1px solid var(--border);
-
-  @media (max-width: 1024px) {
-    border-right: none;
-    border-bottom: 1px solid var(--border);
-  }
-}
-
-#next-steps ul {
-  list-style: none;
-  padding: 0;
-  display: flex;
-  gap: 8px;
-  margin: 32px 0 0;
-
-  .logo {
-    height: 18px;
-  }
-
-  a {
-    color: var(--text-h);
-    font-size: 16px;
-    border-radius: 6px;
-    background: var(--social-bg);
-    display: flex;
-    padding: 6px 12px;
-    align-items: center;
-    gap: 8px;
-    text-decoration: none;
-    transition: box-shadow 0.3s;
-
-    &:hover {
-      box-shadow: var(--shadow);
-    }
-    .button-icon {
-      height: 18px;
-      width: 18px;
-    }
-  }
-
-  @media (max-width: 1024px) {
-    margin-top: 20px;
-    flex-wrap: wrap;
-    justify-content: center;
-
-    li {
-      flex: 1 1 calc(50% - 8px);
-    }
-
-    a {
-      width: 100%;
-      justify-content: center;
-      box-sizing: border-box;
-    }
-  }
-}
-
-#spacer {
-  height: 88px;
-  border-top: 1px solid var(--border);
-  @media (max-width: 1024px) {
-    height: 48px;
-  }
-}
-
-.ticks {
-  position: relative;
-  width: 100%;
-
-  &::before,
-  &::after {
-    content: '';
-    position: absolute;
-    top: -4.5px;
-    border: 5px solid transparent;
-  }
-
-  &::before {
-    left: 0;
-    border-left-color: var(--border);
-  }
-  &::after {
-    right: 0;
-    border-right-color: var(--border);
-  }
-}

client/src/App.jsx

@@ -1,121 +1,62 @@
-import { useState } from 'react'
-import reactLogo from './assets/react.svg'
-import viteLogo from './assets/vite.svg'
-import heroImg from './assets/hero.png'
-import './App.css'
+import React from 'react';
+import { useUser } from './hooks/useUser';
+import OnboardingFlow from './components/Onboarding/OnboardingFlow';
+import Header from './components/Layout/Header';
+import ChatWindow from './components/Chat/ChatWindow';
+import './styles/globals.css';
 
+/**
+ * App — root component for PC Pal.
+ *
+ * Shows the OnboardingFlow for new users.
+ * Once onboarded, shows the Header + ChatWindow.
+ */
 function App() {
-  const [count, setCount] = useState(0)
+  const { user, isOnboarded, isLoading, createUser, completeOnboarding } = useUser();
 
-  return (
-    <>
-      <section id="center">
-        <div className="hero">
-          <img src={heroImg} className="base" width="170" height="179" alt="" />
-          <img src={reactLogo} className="framework" alt="React logo" />
-          <img src={viteLogo} className="vite" alt="Vite logo" />
-        </div>
-        <div>
-          <h1>Get started</h1>
-          <p>
-            Edit <code>src/App.jsx</code> and save to test <code>HMR</code>
-          </p>
-        </div>
-        <button
-          className="counter"
-          onClick={() => setCount((count) => count + 1)}
-        >
-          Count is {count}
-        </button>
-      </section>
-
-      <div className="ticks"></div>
+  // While checking localStorage / fetching user, show a loading screen
+  if (isLoading) {
+    return (
+      <div
+        style={{
+          minHeight: '100vh',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          fontSize: '22px',
+          color: 'var(--color-text-light)',
+        }}
+        role="status"
+        aria-live="polite"
+      >
+        Loading PC Pal...
+      </div>
+    );
+  }
 
-      <section id="next-steps">
-        <div id="docs">
-          <svg className="icon" role="presentation" aria-hidden="true">
-            <use href="/icons.svg#documentation-icon"></use>
-          </svg>
-          <h2>Documentation</h2>
-          <p>Your questions, answered</p>
-          <ul>
-            <li>
-              <a href="https://vite.dev/" target="_blank">
-                <img className="logo" src={viteLogo} alt="" />
-                Explore Vite
-              </a>
-            </li>
-            <li>
-              <a href="https://react.dev/" target="_blank">
-                <img className="button-icon" src={reactLogo} alt="" />
-                Learn more
-              </a>
-            </li>
-          </ul>
-        </div>
-        <div id="social">
-          <svg className="icon" role="presentation" aria-hidden="true">
-            <use href="/icons.svg#social-icon"></use>
-          </svg>
-          <h2>Connect with us</h2>
-          <p>Join the Vite community</p>
-          <ul>
-            <li>
-              <a href="https://github.com/vitejs/vite" target="_blank">
-                <svg
-                  className="button-icon"
-                  role="presentation"
-                  aria-hidden="true"
-                >
-                  <use href="/icons.svg#github-icon"></use>
-                </svg>
-                GitHub
-              </a>
-            </li>
-            <li>
-              <a href="https://chat.vite.dev/" target="_blank">
-                <svg
-                  className="button-icon"
-                  role="presentation"
-                  aria-hidden="true"
-                >
-                  <use href="/icons.svg#discord-icon"></use>
-                </svg>
-                Discord
-              </a>
-            </li>
-            <li>
-              <a href="https://x.com/vite_js" target="_blank">
-                <svg
-                  className="button-icon"
-                  role="presentation"
-                  aria-hidden="true"
-                >
-                  <use href="/icons.svg#x-icon"></use>
-                </svg>
-                X.com
-              </a>
-            </li>
-            <li>
-              <a href="https://bsky.app/profile/vite.dev" target="_blank">
-                <svg
-                  className="button-icon"
-                  role="presentation"
-                  aria-hidden="true"
-                >
-                  <use href="/icons.svg#bluesky-icon"></use>
-                </svg>
-                Bluesky
-              </a>
-            </li>
-          </ul>
-        </div>
-      </section>
+  // Not yet onboarded — show the wizard
+  if (!isOnboarded) {
+    return (
+      <OnboardingFlow
+        createUser={createUser}
+        completeOnboarding={completeOnboarding}
+      />
+    );
+  }
 
-      <div className="ticks"></div>
-      <section id="spacer"></section>
-    </>
-  )
+  // Onboarded — show the main chat UI
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        minHeight: '100vh',
+      }}
+    >
+      <Header user={user} />
+      <ChatWindow userId={user?.id} />
+    </div>
+  );
 }
 
-export default App
+export default App;

client/src/components/Chat/ChatWindow.css

@@ -0,0 +1,109 @@
+/* ChatWindow styles */
+
+.chat-window {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  height: 0; /* allows flex children to scroll */
+  min-height: 0;
+  background-color: var(--color-bg);
+  position: relative;
+}
+
+/* Connection status banner */
+.connection-banner {
+  background-color: var(--color-warning-light);
+  color: var(--color-warning);
+  border-bottom: 2px solid var(--color-warning);
+  font-size: 18px;
+  font-weight: 600;
+  text-align: center;
+  padding: 12px 20px;
+  flex-shrink: 0;
+}
+
+/* Scrollable message list */
+.chat-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px 20px;
+  display: flex;
+  flex-direction: column;
+  scroll-behavior: smooth;
+}
+
+/* Responsive max width for readability */
+@media (min-width: 768px) {
+  .chat-messages {
+    padding: 28px 40px;
+  }
+}
+
+/* Empty state */
+.chat-empty {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: 40px;
+}
+
+.chat-empty__text {
+  font-size: 22px;
+  color: var(--color-text-light);
+  line-height: 1.7;
+  max-width: 480px;
+  border: 2px dashed var(--color-border);
+  border-radius: var(--radius-lg);
+  padding: 32px 40px;
+  background-color: var(--color-white);
+}
+
+/* Typing indicator */
+.typing-indicator {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 0 4px;
+  margin-bottom: 4px;
+}
+
+.typing-indicator__dots {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  background-color: var(--color-white);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-full);
+  padding: 10px 16px;
+  box-shadow: 0 1px 4px var(--color-shadow);
+}
+
+.typing-indicator__dots span {
+  display: block;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background-color: var(--color-primary);
+  animation: pulse 1.4s ease-in-out infinite;
+}
+
+.typing-indicator__dots span:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.typing-indicator__dots span:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+.typing-indicator__label {
+  font-size: 17px;
+  color: var(--color-text-light);
+  font-style: italic;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50%       { opacity: 0.3; transform: scale(0.8); }
+}

client/src/components/Chat/ChatWindow.jsx

@@ -0,0 +1,73 @@
+import React, { useEffect, useRef } from 'react';
+import { useChat } from '../../hooks/useChat';
+import MessageBubble from './MessageBubble';
+import MessageInput from './MessageInput';
+import './ChatWindow.css';
+
+/**
+ * ChatWindow — main chat container.
+ *
+ * - Full-height layout with scrollable message list above input
+ * - Auto-scrolls to the latest message
+ * - Shows "PC Pal is typing..." indicator
+ */
+function ChatWindow({ userId }) {
+  const { messages, sendMessage, isConnected, isTyping } = useChat(userId);
+  const bottomRef = useRef(null);
+  const listRef = useRef(null);
+
+  // Auto-scroll to the newest message
+  useEffect(() => {
+    if (bottomRef.current) {
+      bottomRef.current.scrollIntoView({ behavior: 'smooth' });
+    }
+  }, [messages, isTyping]);
+
+  return (
+    <div className="chat-window">
+      {/* Connection status banner */}
+      {!isConnected && (
+        <div className="connection-banner" role="status">
+          Connecting to PC Pal... please wait.
+        </div>
+      )}
+
+      {/* Scrollable message list */}
+      <div className="chat-messages" ref={listRef} role="log" aria-live="polite" aria-label="Chat messages">
+        {messages.length === 0 && (
+          <div className="chat-empty">
+            <p className="chat-empty__text">
+              Hello! I'm PC Pal, your friendly tech helper.
+              <br />
+              Ask me anything about your computer!
+            </p>
+          </div>
+        )}
+
+        {messages.map((msg) => (
+          <MessageBubble key={msg.id} message={msg} />
+        ))}
+
+        {/* Typing indicator */}
+        {isTyping && (
+          <div className="typing-indicator" aria-live="polite" role="status">
+            <div className="typing-indicator__dots">
+              <span></span>
+              <span></span>
+              <span></span>
+            </div>
+            <span className="typing-indicator__label">PC Pal is typing...</span>
+          </div>
+        )}
+
+        {/* Invisible anchor to scroll to */}
+        <div ref={bottomRef} aria-hidden="true" />
+      </div>
+
+      {/* Input area */}
+      <MessageInput onSend={sendMessage} isTyping={isTyping} />
+    </div>
+  );
+}
+
+export default ChatWindow;

client/src/components/Chat/MessageBubble.css

@@ -0,0 +1,116 @@
+/* MessageBubble styles */
+
+.message-row {
+  display: flex;
+  align-items: flex-end;
+  gap: 10px;
+  margin-bottom: 20px;
+  animation: fadeIn 300ms ease forwards;
+  max-width: 100%;
+}
+
+.message-row--user {
+  flex-direction: row-reverse;
+}
+
+.message-row--assistant {
+  flex-direction: row;
+}
+
+/* Small avatar label for the assistant */
+.message-avatar {
+  flex-shrink: 0;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  font-size: 13px;
+  font-weight: 700;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 24px; /* align with bottom of bubble, above timestamp */
+}
+
+/* The bubble itself */
+.bubble {
+  max-width: min(75%, 560px);
+  padding: 16px 20px;
+  border-radius: 18px;
+  word-break: break-word;
+}
+
+.bubble--user {
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  border-bottom-right-radius: 4px;
+}
+
+.bubble--assistant {
+  background-color: var(--color-white);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+  border-bottom-left-radius: 4px;
+  box-shadow: 0 1px 4px var(--color-shadow);
+}
+
+.bubble__text {
+  font-size: 20px;
+  line-height: 1.6;
+  margin: 0 0 8px;
+  white-space: pre-wrap;
+}
+
+.bubble__time {
+  font-size: 13px;
+  opacity: 0.7;
+  display: block;
+}
+
+.bubble--user .bubble__time {
+  color: var(--color-white);
+  text-align: right;
+}
+
+.bubble--assistant .bubble__time {
+  color: var(--color-text-light);
+}
+
+/* Safety alert banner */
+.safety-alert {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  background-color: var(--color-danger-light);
+  border: 2px solid var(--color-danger);
+  border-radius: var(--radius-md);
+  color: var(--color-danger);
+  font-size: 18px;
+  font-weight: 600;
+  padding: 14px 18px;
+  margin-bottom: 8px;
+  width: 100%;
+  max-width: min(75%, 600px);
+  box-shadow: 0 2px 8px rgba(220, 38, 38, 0.2);
+}
+
+.safety-alert__icon {
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background-color: var(--color-danger);
+  color: var(--color-white);
+  font-size: 16px;
+  font-weight: 900;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Fade-in animation defined in globals but repeated here for safety */
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}

client/src/components/Chat/MessageBubble.jsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import './MessageBubble.css';
+
+/**
+ * MessageBubble — displays a single chat message.
+ *
+ * User messages: right-aligned, blue background.
+ * Assistant messages: left-aligned, white background.
+ * Shows a red safety alert banner when safetyAlert is present.
+ */
+function MessageBubble({ message }) {
+  const { role, text, timestamp, safetyAlert } = message;
+  const isUser = role === 'user';
+
+  const formattedTime = timestamp
+    ? new Date(timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+    : '';
+
+  return (
+    <div className={`message-row ${isUser ? 'message-row--user' : 'message-row--assistant'}`}>
+      {/* Safety alert — prominent banner above the message */}
+      {safetyAlert && (
+        <div className="safety-alert" role="alert">
+          <span className="safety-alert__icon" aria-hidden="true">!</span>
+          <span>{safetyAlert}</span>
+        </div>
+      )}
+
+      <div className={`bubble ${isUser ? 'bubble--user' : 'bubble--assistant'}`}>
+        <p className="bubble__text">{text}</p>
+        <time className="bubble__time" dateTime={timestamp}>{formattedTime}</time>
+      </div>
+
+      {!isUser && (
+        <span className="message-avatar" aria-hidden="true">PC</span>
+      )}
+    </div>
+  );
+}
+
+export default MessageBubble;

client/src/components/Chat/MessageInput.css

@@ -0,0 +1,51 @@
+/* MessageInput styles */
+
+.message-input-bar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px 20px;
+  background-color: var(--color-white);
+  border-top: 2px solid var(--color-border);
+  box-shadow: 0 -2px 8px var(--color-shadow);
+}
+
+.message-input-field {
+  flex: 1;
+  min-height: 56px;
+  font-size: 20px;
+  padding: 14px 20px;
+  border: 2px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background-color: var(--color-white);
+  color: var(--color-text);
+  transition: border-color var(--transition), box-shadow var(--transition);
+  /* Override reset from globals */
+  margin: 0;
+}
+
+.message-input-field:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 3px var(--color-primary-light);
+}
+
+.message-input-field:disabled {
+  background-color: var(--color-surface-alt);
+  color: var(--color-text-light);
+  cursor: not-allowed;
+}
+
+.message-input-field::placeholder {
+  color: var(--color-text-light);
+}
+
+.message-send-btn {
+  flex-shrink: 0;
+  min-height: 56px;
+  padding: 14px 28px;
+  font-size: 20px;
+  font-weight: 700;
+  border-radius: var(--radius-md);
+  white-space: nowrap;
+}

client/src/components/Chat/MessageInput.jsx

@@ -0,0 +1,78 @@
+import React, { useRef, useEffect } from 'react';
+import './MessageInput.css';
+
+/**
+ * MessageInput — text input + send button for the chat.
+ *
+ * - Large input field (min 56px height)
+ * - Prominent send button
+ * - Submits on Enter (Shift+Enter adds a newline)
+ * - Disabled while isTyping
+ * - Auto-focused on mount
+ */
+function MessageInput({ onSend, isTyping }) {
+  const inputRef = useRef(null);
+  const valueRef = useRef('');
+
+  // Auto-focus on mount
+  useEffect(() => {
+    if (inputRef.current) {
+      inputRef.current.focus();
+    }
+  }, []);
+
+  // Re-focus after response arrives
+  useEffect(() => {
+    if (!isTyping && inputRef.current) {
+      inputRef.current.focus();
+    }
+  }, [isTyping]);
+
+  const handleSend = () => {
+    const text = inputRef.current?.value ?? '';
+    if (!text.trim() || isTyping) return;
+    onSend(text);
+    if (inputRef.current) {
+      inputRef.current.value = '';
+      valueRef.current = '';
+    }
+  };
+
+  const handleKeyDown = (e) => {
+    // Enter submits; Shift+Enter adds newline (for textarea)
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSend();
+    }
+  };
+
+  return (
+    <div className="message-input-bar">
+      <label htmlFor="chat-input" className="sr-only">
+        Type your message
+      </label>
+      <input
+        id="chat-input"
+        ref={inputRef}
+        type="text"
+        className="message-input-field"
+        placeholder="Type your question here..."
+        disabled={isTyping}
+        onKeyDown={handleKeyDown}
+        onChange={(e) => { valueRef.current = e.target.value; }}
+        autoComplete="off"
+        aria-label="Type your question here"
+      />
+      <button
+        className="message-send-btn btn-primary"
+        onClick={handleSend}
+        disabled={isTyping}
+        aria-label="Send message"
+      >
+        Send
+      </button>
+    </div>
+  );
+}
+
+export default MessageInput;

client/src/components/Layout/Header.css

@@ -0,0 +1,80 @@
+/* Header styles */
+
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 12px;
+  padding: 16px 24px;
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  box-shadow: 0 2px 8px var(--color-shadow);
+  flex-shrink: 0;
+}
+
+.app-header__brand {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+}
+
+.app-header__logo {
+  width: 52px;
+  height: 52px;
+  border-radius: 50%;
+  background-color: var(--color-white);
+  color: var(--color-primary);
+  font-size: 16px;
+  font-weight: 900;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  letter-spacing: 0.5px;
+}
+
+.app-header__title {
+  font-size: 26px;
+  font-weight: 800;
+  color: var(--color-white);
+  margin: 0;
+  line-height: 1.2;
+}
+
+.app-header__subtitle {
+  font-size: 15px;
+  color: rgba(255, 255, 255, 0.85);
+  margin: 0;
+  line-height: 1.3;
+}
+
+.app-header__user {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 2px;
+}
+
+.app-header__user-greeting {
+  font-size: 18px;
+  color: var(--color-white);
+}
+
+.app-header__user-os {
+  font-size: 14px;
+  color: rgba(255, 255, 255, 0.75);
+  background-color: rgba(255, 255, 255, 0.15);
+  border-radius: var(--radius-full);
+  padding: 2px 10px;
+}
+
+@media (max-width: 480px) {
+  .app-header {
+    padding: 12px 16px;
+  }
+
+  .app-header__title {
+    font-size: 22px;
+  }
+}

client/src/components/Layout/Header.jsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import './Header.css';
+
+/**
+ * Header — app-level header bar.
+ *
+ * Shows the PC Pal title and, when available, the logged-in user's name.
+ */
+function Header({ user }) {
+  return (
+    <header className="app-header">
+      <div className="app-header__brand">
+        <span className="app-header__logo" aria-hidden="true">PC</span>
+        <div>
+          <h1 className="app-header__title">PC Pal</h1>
+          <p className="app-header__subtitle">Your Friendly Tech Helper</p>
+        </div>
+      </div>
+
+      {user && (
+        <div className="app-header__user">
+          <span className="app-header__user-greeting">
+            Hi, <strong>{user.name}</strong>!
+          </span>
+          {user.os_type && (
+            <span className="app-header__user-os">{user.os_type}</span>
+          )}
+        </div>
+      )}
+    </header>
+  );
+}
+
+export default Header;

client/src/components/Onboarding/OnboardingFlow.css

@@ -0,0 +1,228 @@
+/* OnboardingFlow styles */
+
+/* Full-screen backdrop */
+.onboarding-backdrop {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: linear-gradient(135deg, #dbeafe 0%, #eff6ff 50%, #f5f5f5 100%);
+  padding: 24px 16px;
+}
+
+/* Card container */
+.onboarding-card {
+  background-color: var(--color-white);
+  border-radius: 20px;
+  box-shadow: 0 8px 32px rgba(26, 26, 46, 0.15);
+  padding: 40px 36px;
+  width: 100%;
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+  gap: 28px;
+}
+
+@media (max-width: 480px) {
+  .onboarding-card {
+    padding: 28px 20px;
+    border-radius: 14px;
+  }
+}
+
+/* Progress dots */
+.onboarding-progress {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.onboarding-progress__dot {
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  background-color: var(--color-border);
+  transition: background-color var(--transition), transform var(--transition);
+}
+
+.onboarding-progress__dot--active {
+  background-color: var(--color-primary);
+  transform: scale(1.2);
+}
+
+.onboarding-progress__label {
+  font-size: 16px;
+  color: var(--color-text-light);
+  margin-left: auto;
+}
+
+/* Step headings */
+.onboarding-heading {
+  font-size: 30px;
+  font-weight: 800;
+  color: var(--color-text);
+  margin-bottom: 10px;
+  line-height: 1.25;
+}
+
+.onboarding-intro {
+  font-size: 20px;
+  color: var(--color-text-light);
+  margin-bottom: 20px;
+}
+
+/* Label above inputs */
+.onboarding-label {
+  display: block;
+  font-size: 22px;
+  font-weight: 600;
+  color: var(--color-text);
+  margin-bottom: 12px;
+}
+
+/* Large text input */
+.onboarding-input {
+  font-size: 22px;
+  padding: 16px 20px;
+  min-height: 60px;
+  border-radius: var(--radius-md);
+  border: 2px solid var(--color-border);
+  width: 100%;
+  color: var(--color-text);
+  background-color: var(--color-white);
+  transition: border-color var(--transition), box-shadow var(--transition);
+}
+
+.onboarding-input:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 3px var(--color-primary-light);
+}
+
+/* OS selection grid */
+.os-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 14px;
+}
+
+.os-btn {
+  min-height: 80px;
+  font-size: 22px;
+  font-weight: 700;
+  background-color: var(--color-surface-alt);
+  color: var(--color-text);
+  border: 3px solid var(--color-border);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: background-color var(--transition), border-color var(--transition),
+    transform var(--transition);
+}
+
+.os-btn:hover:not(:disabled) {
+  border-color: var(--color-primary);
+  background-color: var(--color-primary-light);
+  color: var(--color-primary-dark);
+}
+
+.os-btn--selected {
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  border-color: var(--color-primary);
+  box-shadow: 0 4px 12px rgba(37, 99, 235, 0.3);
+}
+
+.os-btn--selected:hover {
+  background-color: var(--color-primary-dark);
+  border-color: var(--color-primary-dark);
+}
+
+/* Comfort level scale */
+.comfort-scale {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.comfort-btn {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  min-height: 64px;
+  padding: 12px 20px;
+  background-color: var(--color-surface-alt);
+  color: var(--color-text);
+  border: 3px solid var(--color-border);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  text-align: left;
+  transition: background-color var(--transition), border-color var(--transition);
+  justify-content: flex-start;
+}
+
+.comfort-btn:hover:not(:disabled) {
+  border-color: var(--color-primary);
+  background-color: var(--color-primary-light);
+}
+
+.comfort-btn--selected {
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  border-color: var(--color-primary);
+  box-shadow: 0 3px 10px rgba(37, 99, 235, 0.25);
+}
+
+.comfort-btn__number {
+  font-size: 24px;
+  font-weight: 800;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background-color: rgba(255, 255, 255, 0.25);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.comfort-btn--selected .comfort-btn__number {
+  background-color: rgba(255, 255, 255, 0.3);
+}
+
+.comfort-btn__label {
+  font-size: 20px;
+  font-weight: 600;
+}
+
+/* Error message */
+.onboarding-error {
+  background-color: var(--color-danger-light);
+  border: 2px solid var(--color-danger);
+  color: var(--color-danger);
+  border-radius: var(--radius-md);
+  padding: 14px 18px;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+/* Navigation buttons */
+.onboarding-nav {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  justify-content: flex-end;
+}
+
+.onboarding-nav__back {
+  font-size: 18px;
+  min-height: 54px;
+}
+
+.onboarding-nav__next,
+.onboarding-nav__submit {
+  font-size: 22px;
+  min-height: 58px;
+  padding: 14px 36px;
+  flex: 1;
+  max-width: 280px;
+}

client/src/components/Onboarding/OnboardingFlow.jsx

@@ -0,0 +1,196 @@
+import React, { useState } from 'react';
+import './OnboardingFlow.css';
+
+const TOTAL_STEPS = 3;
+
+const OS_OPTIONS = [
+  { value: 'Windows', label: 'Windows' },
+  { value: 'Mac', label: 'Mac' },
+  { value: 'iPhone', label: 'iPhone' },
+  { value: 'Android', label: 'Android' },
+];
+
+const COMFORT_LABELS = {
+  1: "I'm brand new",
+  2: 'I know a little',
+  3: 'I know the basics',
+  4: 'Getting confident',
+  5: 'Pretty comfortable',
+};
+
+/**
+ * OnboardingFlow — multi-step wizard for new users.
+ *
+ * Step 1: Name
+ * Step 2: Device / OS type
+ * Step 3: Comfort level (1–5)
+ * Submit: calls createUser, then completeOnboarding
+ */
+function OnboardingFlow({ createUser, completeOnboarding }) {
+  const [step, setStep] = useState(1);
+  const [name, setName] = useState('');
+  const [osType, setOsType] = useState('');
+  const [comfortLevel, setComfortLevel] = useState(3);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState(null);
+
+  const goNext = () => setStep((s) => Math.min(s + 1, TOTAL_STEPS));
+  const goBack = () => setStep((s) => Math.max(s - 1, 1));
+
+  const canGoNext = () => {
+    if (step === 1) return name.trim().length > 0;
+    if (step === 2) return osType.length > 0;
+    return true;
+  };
+
+  const handleSubmit = async () => {
+    setIsSubmitting(true);
+    setError(null);
+    try {
+      const newUser = await createUser({
+        name: name.trim(),
+        os_type: osType,
+        comfort_level: comfortLevel,
+      });
+      await completeOnboarding(newUser.id);
+    } catch (err) {
+      setError('Something went wrong. Please try again.');
+      console.error('Onboarding error:', err);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="onboarding-backdrop">
+      <div className="onboarding-card" role="main">
+        {/* Progress indicator */}
+        <div className="onboarding-progress" aria-label={`Step ${step} of ${TOTAL_STEPS}`}>
+          {Array.from({ length: TOTAL_STEPS }, (_, i) => (
+            <div
+              key={i}
+              className={`onboarding-progress__dot ${i + 1 <= step ? 'onboarding-progress__dot--active' : ''}`}
+              aria-hidden="true"
+            />
+          ))}
+          <span className="onboarding-progress__label">Step {step} of {TOTAL_STEPS}</span>
+        </div>
+
+        {/* Step content */}
+        <div className="onboarding-step" key={step}>
+          {step === 1 && (
+            <div className="animate-slide-up">
+              <h1 className="onboarding-heading">Welcome to PC Pal!</h1>
+              <p className="onboarding-intro">
+                I'm here to help you with your computer — no question is too simple!
+              </p>
+              <label htmlFor="user-name" className="onboarding-label">
+                What's your name?
+              </label>
+              <input
+                id="user-name"
+                type="text"
+                className="onboarding-input"
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                placeholder="Enter your first name"
+                autoFocus
+                autoComplete="given-name"
+                onKeyDown={(e) => { if (e.key === 'Enter' && canGoNext()) goNext(); }}
+              />
+            </div>
+          )}
+
+          {step === 2 && (
+            <div className="animate-slide-up">
+              <h1 className="onboarding-heading">
+                {name ? `Nice to meet you, ${name}!` : 'Your Device'}
+              </h1>
+              <p className="onboarding-label">What kind of computer do you use?</p>
+              <div className="os-grid">
+                {OS_OPTIONS.map((opt) => (
+                  <button
+                    key={opt.value}
+                    type="button"
+                    className={`os-btn ${osType === opt.value ? 'os-btn--selected' : ''}`}
+                    onClick={() => setOsType(opt.value)}
+                    aria-pressed={osType === opt.value}
+                  >
+                    {opt.label}
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {step === 3 && (
+            <div className="animate-slide-up">
+              <h1 className="onboarding-heading">Almost done!</h1>
+              <p className="onboarding-label">
+                How comfortable are you with computers?
+              </p>
+              <div className="comfort-scale">
+                {[1, 2, 3, 4, 5].map((level) => (
+                  <button
+                    key={level}
+                    type="button"
+                    className={`comfort-btn ${comfortLevel === level ? 'comfort-btn--selected' : ''}`}
+                    onClick={() => setComfortLevel(level)}
+                    aria-pressed={comfortLevel === level}
+                    aria-label={`${level} — ${COMFORT_LABELS[level]}`}
+                  >
+                    <span className="comfort-btn__number">{level}</span>
+                    <span className="comfort-btn__label">{COMFORT_LABELS[level]}</span>
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Error message */}
+        {error && (
+          <div className="onboarding-error" role="alert">
+            {error}
+          </div>
+        )}
+
+        {/* Navigation buttons */}
+        <div className="onboarding-nav">
+          {step > 1 && (
+            <button
+              type="button"
+              className="btn-secondary onboarding-nav__back"
+              onClick={goBack}
+              disabled={isSubmitting}
+            >
+              Back
+            </button>
+          )}
+
+          {step < TOTAL_STEPS ? (
+            <button
+              type="button"
+              className="btn-primary onboarding-nav__next"
+              onClick={goNext}
+              disabled={!canGoNext()}
+            >
+              Next
+            </button>
+          ) : (
+            <button
+              type="button"
+              className="btn-primary onboarding-nav__submit"
+              onClick={handleSubmit}
+              disabled={isSubmitting}
+            >
+              {isSubmitting ? 'Setting things up...' : "Let's get started!"}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default OnboardingFlow;

client/src/hooks/useChat.js

@@ -0,0 +1,161 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+/**
+ * useChat — WebSocket chat hook for PC Pal
+ *
+ * Connects to /ws (proxied to ws://localhost:3001/ws by Vite),
+ * sends an init message, and manages message state.
+ *
+ * @param {string|null} userId
+ * @returns {{ messages, sendMessage, isConnected, isTyping }}
+ */
+export function useChat(userId) {
+  const [messages, setMessages] = useState([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [isTyping, setIsTyping] = useState(false);
+
+  const wsRef = useRef(null);
+  const reconnectTimeoutRef = useRef(null);
+  const messageIdRef = useRef(0);
+
+  const nextId = () => {
+    messageIdRef.current += 1;
+    return messageIdRef.current;
+  };
+
+  const connect = useCallback(() => {
+    if (!userId) return;
+
+    // Determine WS URL: use relative path so Vite proxy handles it
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}/ws`;
+
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      setIsConnected(true);
+      // Send init message so the server knows who we are
+      ws.send(JSON.stringify({ type: 'init', userId }));
+    };
+
+    ws.onmessage = (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        console.error('PC Pal: invalid JSON from server', event.data);
+        return;
+      }
+
+      switch (data.type) {
+        case 'init_ack':
+          // Server acknowledged the init — nothing extra needed
+          break;
+
+        case 'typing':
+          setIsTyping(true);
+          break;
+
+        case 'response':
+          setIsTyping(false);
+          setMessages((prev) => [
+            ...prev,
+            {
+              id: nextId(),
+              role: 'assistant',
+              text: data.text ?? '',
+              timestamp: new Date().toISOString(),
+              safetyAlert: data.safetyAlert ?? null,
+            },
+          ]);
+          break;
+
+        case 'error':
+          setIsTyping(false);
+          setMessages((prev) => [
+            ...prev,
+            {
+              id: nextId(),
+              role: 'assistant',
+              text: data.message ?? 'Something went wrong. Please try again.',
+              timestamp: new Date().toISOString(),
+              safetyAlert: null,
+            },
+          ]);
+          break;
+
+        default:
+          console.warn('PC Pal: unknown message type', data.type);
+      }
+    };
+
+    ws.onclose = () => {
+      setIsConnected(false);
+      setIsTyping(false);
+      // Attempt to reconnect after 3 seconds
+      reconnectTimeoutRef.current = setTimeout(connect, 3000);
+    };
+
+    ws.onerror = (err) => {
+      console.error('PC Pal WebSocket error', err);
+      ws.close();
+    };
+  }, [userId]);
+
+  useEffect(() => {
+    if (!userId) return;
+    connect();
+
+    return () => {
+      clearTimeout(reconnectTimeoutRef.current);
+      if (wsRef.current) {
+        // Remove the onclose handler before closing so we don't trigger reconnect
+        wsRef.current.onclose = null;
+        wsRef.current.close();
+      }
+    };
+  }, [userId, connect]);
+
+  /**
+   * Send a chat message.
+   * @param {string} text
+   */
+  const sendMessage = useCallback(
+    (text) => {
+      const trimmed = text.trim();
+      if (!trimmed) return;
+
+      // Optimistically add the user's message to the list
+      setMessages((prev) => [
+        ...prev,
+        {
+          id: nextId(),
+          role: 'user',
+          text: trimmed,
+          timestamp: new Date().toISOString(),
+          safetyAlert: null,
+        },
+      ]);
+
+      if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+        wsRef.current.send(JSON.stringify({ type: 'chat', text: trimmed }));
+      } else {
+        console.warn('PC Pal: WebSocket not open, message not sent');
+        setMessages((prev) => [
+          ...prev,
+          {
+            id: nextId(),
+            role: 'assistant',
+            text: 'Sorry, the connection was lost. Please refresh the page and try again.',
+            timestamp: new Date().toISOString(),
+            safetyAlert: null,
+          },
+        ]);
+      }
+    },
+    [],
+  );
+
+  return { messages, sendMessage, isConnected, isTyping };
+}

client/src/hooks/useUser.js

@@ -0,0 +1,99 @@
+import { useState, useEffect, useCallback } from 'react';
+
+const USER_ID_KEY = 'pcpal_userId';
+
+/**
+ * useUser — User profile hook for PC Pal
+ *
+ * Checks localStorage for an existing userId on mount.
+ * If found, loads the profile from the API.
+ * Exposes helpers to create a user and complete onboarding.
+ *
+ * @returns {{ user, isOnboarded, isLoading, createUser, completeOnboarding }}
+ */
+export function useUser() {
+  const [user, setUser] = useState(null);
+  const [isOnboarded, setIsOnboarded] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+
+  // On mount: check localStorage for a saved userId
+  useEffect(() => {
+    const savedId = localStorage.getItem(USER_ID_KEY);
+
+    if (!savedId) {
+      setIsLoading(false);
+      return;
+    }
+
+    // Fetch the user profile
+    fetch(`/api/users/${savedId}`)
+      .then((res) => {
+        if (!res.ok) {
+          // User not found on server — clear stale localStorage entry
+          localStorage.removeItem(USER_ID_KEY);
+          return null;
+        }
+        return res.json();
+      })
+      .then((data) => {
+        if (data) {
+          setUser(data);
+          setIsOnboarded(Boolean(data.is_onboarded ?? data.isOnboarded));
+        }
+      })
+      .catch((err) => {
+        console.error('PC Pal: failed to load user profile', err);
+        localStorage.removeItem(USER_ID_KEY);
+      })
+      .finally(() => {
+        setIsLoading(false);
+      });
+  }, []);
+
+  /**
+   * Create a new user account.
+   * @param {{ name: string, os_type: string, comfort_level: number }} data
+   * @returns {Promise<object>} the created user
+   */
+  const createUser = useCallback(async (data) => {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to create user: ${err}`);
+    }
+
+    const newUser = await res.json();
+    localStorage.setItem(USER_ID_KEY, newUser.id);
+    setUser(newUser);
+    return newUser;
+  }, []);
+
+  /**
+   * Mark the user as having completed onboarding.
+   * @param {string|number} userId
+   * @returns {Promise<object>} the updated user
+   */
+  const completeOnboarding = useCallback(async (userId) => {
+    const res = await fetch(`/api/users/${userId}/onboard`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to complete onboarding: ${err}`);
+    }
+
+    const updatedUser = await res.json();
+    setUser(updatedUser);
+    setIsOnboarded(true);
+    return updatedUser;
+  }, []);
+
+  return { user, isOnboarded, isLoading, createUser, completeOnboarding };
+}

client/src/index.css

@@ -1,111 +1,11 @@
-:root {
-  --text: #6b6375;
-  --text-h: #08060d;
-  --bg: #fff;
-  --border: #e5e4e7;
-  --code-bg: #f4f3ec;
-  --accent: #aa3bff;
-  --accent-bg: rgba(170, 59, 255, 0.1);
-  --accent-border: rgba(170, 59, 255, 0.5);
-  --social-bg: rgba(244, 243, 236, 0.5);
-  --shadow:
-    rgba(0, 0, 0, 0.1) 0 10px 15px -3px, rgba(0, 0, 0, 0.05) 0 4px 6px -2px;
+/* index.css — minimal reset; all styles live in src/styles/globals.css */
 
-  --sans: system-ui, 'Segoe UI', Roboto, sans-serif;
-  --heading: system-ui, 'Segoe UI', Roboto, sans-serif;
-  --mono: ui-monospace, Consolas, monospace;
-
-  font: 18px/145% var(--sans);
-  letter-spacing: 0.18px;
-  color-scheme: light dark;
-  color: var(--text);
-  background: var(--bg);
-  font-synthesis: none;
-  text-rendering: optimizeLegibility;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-
-  @media (max-width: 1024px) {
-    font-size: 16px;
-  }
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --text: #9ca3af;
-    --text-h: #f3f4f6;
-    --bg: #16171d;
-    --border: #2e303a;
-    --code-bg: #1f2028;
-    --accent: #c084fc;
-    --accent-bg: rgba(192, 132, 252, 0.15);
-    --accent-border: rgba(192, 132, 252, 0.5);
-    --social-bg: rgba(47, 48, 58, 0.5);
-    --shadow:
-      rgba(0, 0, 0, 0.4) 0 10px 15px -3px, rgba(0, 0, 0, 0.25) 0 4px 6px -2px;
-  }
-
-  #social .button-icon {
-    filter: invert(1) brightness(2);
-  }
-}
-
-body {
-  margin: 0;
-}
-
-#root {
-  width: 1126px;
-  max-width: 100%;
-  margin: 0 auto;
-  text-align: center;
-  border-inline: 1px solid var(--border);
-  min-height: 100svh;
-  display: flex;
-  flex-direction: column;
+*,
+*::before,
+*::after {
   box-sizing: border-box;
 }
 
-h1,
-h2 {
-  font-family: var(--heading);
-  font-weight: 500;
-  color: var(--text-h);
-}
-
-h1 {
-  font-size: 56px;
-  letter-spacing: -1.68px;
-  margin: 32px 0;
-  @media (max-width: 1024px) {
-    font-size: 36px;
-    margin: 20px 0;
-  }
-}
-h2 {
-  font-size: 24px;
-  line-height: 118%;
-  letter-spacing: -0.24px;
-  margin: 0 0 8px;
-  @media (max-width: 1024px) {
-    font-size: 20px;
-  }
-}
-p {
+body {
   margin: 0;
 }
-
-code,
-.counter {
-  font-family: var(--mono);
-  display: inline-flex;
-  border-radius: 4px;
-  color: var(--text-h);
-}
-
-code {
-  font-size: 15px;
-  line-height: 135%;
-  padding: 4px 8px;
-  background: var(--code-bg);
-}

client/src/main.jsx

@@ -1,10 +1,10 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import './index.css'
-import App from './App.jsx'
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './styles/globals.css';
+import App from './App.jsx';
 
 createRoot(document.getElementById('root')).render(
   <StrictMode>
     <App />
   </StrictMode>,
-)
+);

client/src/styles/globals.css

@@ -0,0 +1,238 @@
+/* PC Pal — Elderly-Friendly Global Styles */
+/* Designed for maximum readability and ease of use */
+
+:root {
+  /* Color palette */
+  --color-bg: #f5f5f5;
+  --color-text: #1a1a2e;
+  --color-text-light: #4a4a6a;
+  --color-primary: #2563eb;
+  --color-primary-dark: #1d4ed8;
+  --color-primary-light: #dbeafe;
+  --color-success: #16a34a;
+  --color-success-light: #dcfce7;
+  --color-warning: #d97706;
+  --color-warning-light: #fef3c7;
+  --color-danger: #dc2626;
+  --color-danger-light: #fee2e2;
+  --color-white: #ffffff;
+  --color-border: #d1d5db;
+  --color-surface: #ffffff;
+  --color-surface-alt: #f0f0f8;
+  --color-shadow: rgba(26, 26, 46, 0.12);
+
+  /* Typography */
+  --font-family: 'Segoe UI', system-ui, -apple-system, Arial, sans-serif;
+  --font-size-base: 18px;
+  --font-size-sm: 16px;
+  --font-size-md: 20px;
+  --font-size-lg: 24px;
+  --font-size-xl: 30px;
+  --font-size-2xl: 36px;
+  --line-height: 1.6;
+
+  /* Spacing */
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+  --spacing-xl: 32px;
+  --spacing-2xl: 48px;
+
+  /* Touch targets */
+  --touch-target: 48px;
+
+  /* Border radius */
+  --radius-sm: 6px;
+  --radius-md: 12px;
+  --radius-lg: 18px;
+  --radius-full: 9999px;
+
+  /* Transitions */
+  --transition: 200ms ease;
+}
+
+/* Reset */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: var(--font-size-base);
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: var(--font-family);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height);
+  color: var(--color-text);
+  background-color: var(--color-bg);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  min-height: 100vh;
+}
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Headings */
+h1, h2, h3, h4, h5, h6 {
+  color: var(--color-text);
+  line-height: 1.3;
+  font-weight: 700;
+}
+
+h1 { font-size: var(--font-size-2xl); }
+h2 { font-size: var(--font-size-xl); }
+h3 { font-size: var(--font-size-lg); }
+h4 { font-size: var(--font-size-md); }
+
+p {
+  margin-bottom: var(--spacing-md);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height);
+}
+
+/* Large, accessible buttons */
+button {
+  font-family: var(--font-family);
+  font-size: var(--font-size-md);
+  font-weight: 600;
+  min-height: var(--touch-target);
+  min-width: var(--touch-target);
+  padding: var(--spacing-sm) var(--spacing-lg);
+  border: none;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: background-color var(--transition), transform var(--transition),
+    box-shadow var(--transition);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--spacing-sm);
+  line-height: 1.2;
+}
+
+button:focus-visible {
+  outline: 3px solid var(--color-primary);
+  outline-offset: 3px;
+}
+
+button:active {
+  transform: scale(0.98);
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
+}
+
+/* Primary button */
+.btn-primary {
+  background-color: var(--color-primary);
+  color: var(--color-white);
+}
+
+.btn-primary:hover:not(:disabled) {
+  background-color: var(--color-primary-dark);
+  box-shadow: 0 4px 12px var(--color-shadow);
+}
+
+/* Secondary button */
+.btn-secondary {
+  background-color: var(--color-white);
+  color: var(--color-text);
+  border: 2px solid var(--color-border);
+}
+
+.btn-secondary:hover:not(:disabled) {
+  background-color: var(--color-surface-alt);
+  border-color: var(--color-primary);
+}
+
+/* Large, readable input fields */
+input[type="text"],
+input[type="email"],
+textarea {
+  font-family: var(--font-family);
+  font-size: var(--font-size-md);
+  color: var(--color-text);
+  background-color: var(--color-white);
+  border: 2px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-md) var(--spacing-lg);
+  width: 100%;
+  min-height: var(--touch-target);
+  transition: border-color var(--transition), box-shadow var(--transition);
+  line-height: var(--line-height);
+}
+
+input[type="text"]:focus,
+input[type="email"]:focus,
+textarea:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 3px var(--color-primary-light);
+}
+
+input::placeholder,
+textarea::placeholder {
+  color: var(--color-text-light);
+  opacity: 0.8;
+}
+
+/* Links */
+a {
+  color: var(--color-primary);
+  text-decoration: underline;
+}
+
+a:hover {
+  color: var(--color-primary-dark);
+}
+
+/* Utilities */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Animations — smooth, non-jarring */
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.4; }
+}
+
+@keyframes slideUp {
+  from { opacity: 0; transform: translateY(20px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.animate-fade-in {
+  animation: fadeIn 300ms ease forwards;
+}
+
+.animate-slide-up {
+  animation: slideUp 350ms ease forwards;
+}