From 193994cadce2e6ba8476a00fa3762435beab8ee0 Mon Sep 17 00:00:00 2001
From: Muhammad Aiman <84276911+aimanmalib@users.noreply.github.com>
Date: Tue, 20 Oct 2026 09:46:31 +0000
Subject: [PATCH 1/4] feat(i18n): Bahasa Melayu + English language layer

All UI text now lives in src/i18n/messages/{en,ms}.ts. The `Messages`
type and a test both fail when a key is missing in either language, when
placeholders differ, or when the BM file uses common Indonesian words.

The first visit follows the browser language (ms -> BM). The choice is
stored in localStorage (wrapped in try/catch, in-memory fallback) and
mirrored to a cookie so the server renders the first paint in the same
language.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/i18n/I18nProvider.tsx   |  53 +++++++
 src/i18n/config.ts          |  51 +++++++
 src/i18n/errors.ts          |  12 ++
 src/i18n/locale-store.ts    |  96 +++++++++++++
 src/i18n/messages/en.ts     | 269 ++++++++++++++++++++++++++++++++++++
 src/i18n/messages/index.ts  |  46 ++++++
 src/i18n/messages/ms.ts     | 269 ++++++++++++++++++++++++++++++++++++
 src/i18n/messages/types.ts  |  13 ++
 src/i18n/server.ts          |   9 ++
 tests/i18n/locale.test.ts   |  69 +++++++++
 tests/i18n/messages.test.ts |  84 +++++++++++
 11 files changed, 971 insertions(+)
 create mode 100644 src/i18n/I18nProvider.tsx
 create mode 100644 src/i18n/config.ts
 create mode 100644 src/i18n/errors.ts
 create mode 100644 src/i18n/locale-store.ts
 create mode 100644 src/i18n/messages/en.ts
 create mode 100644 src/i18n/messages/index.ts
 create mode 100644 src/i18n/messages/ms.ts
 create mode 100644 src/i18n/messages/types.ts
 create mode 100644 src/i18n/server.ts
 create mode 100644 tests/i18n/locale.test.ts
 create mode 100644 tests/i18n/messages.test.ts

diff --git a/src/i18n/I18nProvider.tsx b/src/i18n/I18nProvider.tsx
new file mode 100644
index 0000000..02ac27f
--- /dev/null
+++ b/src/i18n/I18nProvider.tsx
@@ -0,0 +1,53 @@
+"use client";
+import { createContext, useCallback, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { useRouter } from "next/navigation";
+import { intlLocale, type Locale } from "./config";
+import { translate, type MessageKey, type TranslateParams } from "./messages";
+import { getClientLocale, setClientLocale, subscribeLocale, writeLocaleCookie } from "./locale-store";
+
+export interface I18nValue {
+  locale: Locale;
+  /** BCP 47 tag for Intl formatting. */
+  intl: string;
+  setLocale: (locale: Locale) => void;
+  t: (key: MessageKey, params?: TranslateParams) => string;
+}
+
+function makeValue(locale: Locale, setLocale: (l: Locale) => void): I18nValue {
+  return {
+    locale,
+    intl: intlLocale(locale),
+    setLocale,
+    t: (key, params) => translate(locale, key, params),
+  };
+}
+
+// Without a provider (unit tests, isolated components) everything renders in English.
+const I18nContext = createContext<I18nValue>(makeValue("en", () => undefined));
+
+export function I18nProvider({ initialLocale, children }: { initialLocale: Locale; children: React.ReactNode }) {
+  const router = useRouter();
+  // Server render and hydration use the locale the server picked; afterwards the browser's choice wins.
+  const locale = useSyncExternalStore(subscribeLocale, getClientLocale, () => initialLocale);
+
+  useEffect(() => {
+    document.documentElement.lang = locale;
+    writeLocaleCookie(locale);
+  }, [locale]);
+
+  const setLocale = useCallback(
+    (next: Locale) => {
+      setClientLocale(next);
+      // Re-render server parts (page title, <html lang>) with the new cookie.
+      router.refresh();
+    },
+    [router],
+  );
+
+  const value = useMemo(() => makeValue(locale, setLocale), [locale, setLocale]);
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+}
+
+export function useI18n(): I18nValue {
+  return useContext(I18nContext);
+}
diff --git a/src/i18n/config.ts b/src/i18n/config.ts
new file mode 100644
index 0000000..aeac0c3
--- /dev/null
+++ b/src/i18n/config.ts
@@ -0,0 +1,51 @@
+/**
+ * Locale settings shared by the server, the browser and the API routes.
+ * Pure data and pure functions: safe to import anywhere.
+ */
+export const LOCALES = ["en", "ms"] as const;
+export type Locale = (typeof LOCALES)[number];
+
+export const DEFAULT_LOCALE: Locale = "en";
+
+/** localStorage key that holds the visitor's chosen UI language. */
+export const LOCALE_STORAGE_KEY = "learnpath.locale.v1";
+/** Mirror of the choice, read by the server so the first paint is already in the right language. */
+export const LOCALE_COOKIE = "learnpath-locale";
+
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === "string" && (LOCALES as readonly string[]).includes(value);
+}
+
+/**
+ * Pick a locale from a list of browser language tags (navigator.languages or
+ * Accept-Language). Malay (`ms`, `ms-MY`, `zsm`) maps to BM; anything else is English.
+ */
+export function detectLocale(languages: readonly string[] | null | undefined): Locale {
+  for (const tag of languages ?? []) {
+    const base = tag.trim().toLowerCase().split(/[-_;]/)[0];
+    if (base === "ms" || base === "zsm") return "ms";
+    if (base === "en") return "en";
+  }
+  return DEFAULT_LOCALE;
+}
+
+/** Parse an Accept-Language header into tags ordered by q-value. */
+export function parseAcceptLanguage(header: string | null | undefined): string[] {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part, index) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+      const weight = q ? Number.parseFloat(q.slice(2)) : 1;
+      return { tag: tag.trim(), weight: Number.isFinite(weight) ? weight : 0, index };
+    })
+    .filter((x) => x.tag && x.weight > 0)
+    .sort((a, b) => b.weight - a.weight || a.index - b.index)
+    .map((x) => x.tag);
+}
+
+/** BCP 47 tag for Intl number/date formatting. */
+export function intlLocale(locale: Locale): string {
+  return locale === "ms" ? "ms-MY" : "en-MY";
+}
diff --git a/src/i18n/errors.ts b/src/i18n/errors.ts
new file mode 100644
index 0000000..b72974d
--- /dev/null
+++ b/src/i18n/errors.ts
@@ -0,0 +1,12 @@
+import type { MessageKey, TranslateParams } from "./messages";
+import { en } from "./messages/en";
+
+type T = (key: MessageKey, params?: TranslateParams) => string;
+
+/** Localised message for an API error code; unknown codes get the generic message. */
+export function errorMessage(t: T, code: string | undefined): string {
+  if (code && code !== "title" && code !== "openSettings" && Object.prototype.hasOwnProperty.call(en.errors, code)) {
+    return t(`errors.${code}` as MessageKey);
+  }
+  return t("errors.unknown");
+}
diff --git a/src/i18n/locale-store.ts b/src/i18n/locale-store.ts
new file mode 100644
index 0000000..dfadba9
--- /dev/null
+++ b/src/i18n/locale-store.ts
@@ -0,0 +1,96 @@
+/**
+ * Browser-side UI language.
+ *
+ * Source of truth: localStorage (`learnpath.locale.v1`). A cookie mirrors the
+ * choice so the server can render the first paint in the same language.
+ * Every storage access is wrapped in try/catch: storage can be blocked
+ * (private mode, site data disabled), and then the choice lives in memory for
+ * this tab only.
+ */
+import { LOCALE_COOKIE, LOCALE_STORAGE_KEY, detectLocale, isLocale, type Locale } from "./config";
+
+const CHANGED_EVENT = "learnpath:locale-changed";
+const ONE_YEAR = 60 * 60 * 24 * 365;
+
+let memoryLocale: Locale | null = null;
+
+export function readStoredLocale(): Locale | null {
+  try {
+    const value = typeof window === "undefined" ? null : window.localStorage.getItem(LOCALE_STORAGE_KEY);
+    return isLocale(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readCookieLocale(): Locale | null {
+  try {
+    if (typeof document === "undefined") return null;
+    const match = document.cookie.split("; ").find((c) => c.startsWith(`${LOCALE_COOKIE}=`));
+    const value = match?.slice(LOCALE_COOKIE.length + 1);
+    return isLocale(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Write the cookie the server reads. Harmless when cookies are blocked. */
+export function writeLocaleCookie(locale: Locale): void {
+  try {
+    if (typeof document === "undefined") return;
+    document.cookie = `${LOCALE_COOKIE}=${locale}; path=/; max-age=${ONE_YEAR}; samesite=lax`;
+  } catch {
+    // cookies blocked: the server falls back to Accept-Language
+  }
+}
+
+/** The language the UI should show right now in this browser. */
+export function getClientLocale(): Locale {
+  if (memoryLocale) return memoryLocale;
+  const stored = readStoredLocale();
+  if (stored) return stored;
+  const cookie = readCookieLocale();
+  if (cookie) return cookie;
+  if (typeof navigator === "undefined") return detectLocale([]);
+  return detectLocale(navigator.languages?.length ? navigator.languages : [navigator.language]);
+}
+
+/** Persist a choice. Returns false when localStorage refused it (the choice still applies to this tab). */
+export function setClientLocale(locale: Locale): boolean {
+  memoryLocale = locale;
+  let saved = false;
+  try {
+    window.localStorage.setItem(LOCALE_STORAGE_KEY, locale);
+    saved = true;
+  } catch {
+    saved = false;
+  }
+  writeLocaleCookie(locale);
+  try {
+    window.dispatchEvent(new Event(CHANGED_EVENT));
+  } catch {
+    // not in a browser
+  }
+  return saved;
+}
+
+export function subscribeLocale(onChange: () => void): () => void {
+  if (typeof window === "undefined") return () => undefined;
+  const onStorage = (e: StorageEvent) => {
+    if (e.key === LOCALE_STORAGE_KEY) {
+      memoryLocale = null;
+      onChange();
+    }
+  };
+  window.addEventListener(CHANGED_EVENT, onChange);
+  window.addEventListener("storage", onStorage);
+  return () => {
+    window.removeEventListener(CHANGED_EVENT, onChange);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+
+/** Test helper: forget the in-memory choice. */
+export function resetLocaleMemory(): void {
+  memoryLocale = null;
+}
diff --git a/src/i18n/messages/en.ts b/src/i18n/messages/en.ts
new file mode 100644
index 0000000..ed19635
--- /dev/null
+++ b/src/i18n/messages/en.ts
@@ -0,0 +1,269 @@
+/**
+ * English UI text. `ms.ts` must have exactly the same keys (enforced by the
+ * `Messages` type and by tests/i18n/messages.test.ts).
+ *
+ * Placeholders use {name}. Keep both languages' placeholders identical.
+ */
+export const en = {
+  meta: {
+    title: "LearnPath: quizzes, flashcards and learning roadmaps with AI",
+    description:
+      "Generate quizzes, flashcards and learning roadmaps for any topic with an OpenAI-compatible LLM. Bring your own API key. In English and Bahasa Melayu.",
+  },
+  common: {
+    appName: "LearnPath",
+    skipToContent: "Skip to content",
+    tryAgain: "Try again",
+    newTopic: "New topic",
+    close: "Close",
+    cancel: "Cancel",
+    save: "Save",
+    done: "Done",
+    next: "Next",
+    tokens: "{count} tokens",
+    sampleData: "Sample data",
+  },
+  nav: {
+    label: "Main navigation",
+    home: "Home",
+    quiz: "Quiz",
+    flashcards: "Flashcards",
+    roadmap: "Roadmap",
+    progress: "Progress",
+    concepts: "Concepts",
+  },
+  header: {
+    homeLink: "LearnPath home",
+    settings: "Settings",
+    statusServer: "Server key",
+    statusReady: "Ready",
+    statusNeedsKey: "Add API key",
+    language: "Language",
+    themeToDark: "Switch to dark theme",
+    themeToLight: "Switch to light theme",
+  },
+  language: {
+    en: "English",
+    ms: "Bahasa Melayu",
+    enShort: "EN",
+    msShort: "BM",
+  },
+  footer: {
+    source: "Source code on GitHub",
+    builtBy: "Built by {name}",
+    tagline: "Made in Malaysia",
+  },
+  home: {
+    eyebrow: "AI study companion",
+    title: "Turn any topic into a study plan you can practise.",
+    lead: "Type a topic. LearnPath asks the AI model you choose for a quiz, a flashcard deck or a step-by-step roadmap, in English or Bahasa Melayu.",
+    ctaQuiz: "Start a quiz",
+    ctaRoadmap: "Plan a roadmap",
+    featuresTitle: "What you can do",
+    quizTitle: "Quiz",
+    quizDesc: "Multiple-choice questions at the difficulty you pick, each with an explanation.",
+    flashcardsTitle: "Flashcards",
+    flashcardsDesc: "A deck to review, rated with the SM-2 spaced-repetition method.",
+    roadmapTitle: "Learning roadmap",
+    roadmapDesc: "A step-by-step plan from beginner to advanced, with time estimates.",
+    progressTitle: "Progress",
+    progressDesc: "Sessions, scores and token usage from this visit.",
+    conceptsTitle: "Concept map",
+    conceptsDesc: "A sample map of related concepts and mastery levels.",
+    howTitle: "How it works",
+    how1Title: "Pick a topic",
+    how1Desc: "Anything from Photosynthesis to SQL joins.",
+    how2Title: "The AI drafts it",
+    how2Desc: "Your chosen model writes questions, cards or steps in your language.",
+    how3Title: "Practise and review",
+    how3Desc: "Answer, flip and rate. Your progress for this visit appears on the Progress page.",
+    byokTitle: "Bring your own key",
+    byokDesc: "Use a key from OpenAI, OpenRouter, Groq, DeepSeek, Together AI, Mistral or Xiaomi MiMo. It stays in your browser. Self-hosted copies can also use Ollama, llama.cpp or any OpenAI-compatible endpoint.",
+    byokCta: "Open settings",
+    honestNote: "AI output can contain mistakes. Check important facts with your textbook or teacher.",
+  },
+  topicForm: {
+    topicLabel: "Topic",
+    examplesLabel: "Try",
+    example1: "Photosynthesis",
+    example2: "Fractions",
+    example3: "World War II",
+    example4: "SQL joins",
+    emptyTopic: "Enter a topic first.",
+  },
+  quiz: {
+    title: "Quiz",
+    description: "Multiple-choice questions on any topic, with an explanation for every answer.",
+    formTitle: "Create a quiz",
+    placeholder: "e.g. Photosynthesis, Fractions, React hooks",
+    difficulty: "Difficulty",
+    questionCount: "Questions",
+    generate: "Generate quiz",
+    loading: "Writing your quiz…",
+    loadingHint: "This can take up to a minute, depending on the model.",
+    questionOf: "Question {current} of {total}",
+    easy: "Easy",
+    medium: "Medium",
+    hard: "Hard",
+    explanation: "Explanation",
+    correct: "Correct",
+    incorrect: "Not quite",
+    correctAnswerWas: "The answer is {answer}.",
+    seeResults: "See results",
+    completeTitle: "Quiz complete",
+    scoreLine: "{correct} of {total} correct",
+    scoreGreat: "Excellent work. You know this topic well.",
+    scoreGood: "Good progress. Review the questions you missed.",
+    scoreLow: "A good start. Try the flashcards for this topic, then take the quiz again.",
+    reviewTitle: "Review",
+    yourAnswer: "Your answer: {answer}",
+    tryAnother: "Try another topic",
+    retake: "Retake this quiz",
+  },
+  flashcards: {
+    title: "Flashcards",
+    description: "Review a generated deck and rate each card. Ratings feed the SM-2 spaced-repetition schedule.",
+    formTitle: "Create a deck",
+    placeholder: "e.g. Photosynthesis, Cell biology, Data structures",
+    generate: "Generate flashcards",
+    loading: "Writing your flashcards…",
+    loadingHint: "This can take up to a minute, depending on the model.",
+    cardOf: "Card {current} of {total}",
+    tapToReveal: "Tap to show the answer",
+    answer: "Answer",
+    rateQuestion: "How well did you remember it?",
+    rateHard: "Hard",
+    rateGood: "Good",
+    rateEasy: "Easy",
+    completeTitle: "Deck reviewed",
+    completeDesc: "You reviewed {total} cards on {topic}.",
+    reviewAgain: "Review again",
+  },
+  roadmap: {
+    title: "Learning roadmap",
+    description: "A step-by-step plan for a topic at your level, with time estimates and key ideas for each step.",
+    formTitle: "Plan a roadmap",
+    placeholder: "e.g. Photosynthesis, Web development, Statistics",
+    level: "Level",
+    beginner: "Beginner",
+    intermediate: "Intermediate",
+    advanced: "Advanced",
+    generate: "Generate roadmap",
+    loading: "Planning your roadmap…",
+    loadingHint: "This can take up to a minute, depending on the model.",
+    stepsCount: "{count} steps",
+    statusCompleted: "Completed",
+    statusCurrent: "Current step",
+    statusUpcoming: "Upcoming",
+    stepLabel: "Step {number}",
+    markDone: "Mark as done",
+    allDone: "Roadmap complete. Well done.",
+    newRoadmap: "New roadmap",
+  },
+  progress: {
+    title: "Progress",
+    description: "Quizzes, flashcard decks and roadmaps you create during this visit. Nothing is saved after you close the tab.",
+    sessions: "Sessions",
+    studyTime: "Study time",
+    studyTimeValue: "{minutes} min",
+    tokens: "Tokens used",
+    weekly: "Activity in the last 7 days",
+    weeklyCaption: "Sessions per day",
+    byFeature: "Tokens by feature",
+    topics: "Topics",
+    topicLine: "{sessions} sessions · average score {score}%",
+    topicLineNoScore: "{sessions} sessions",
+    emptyTitle: "No sessions yet",
+    emptyDesc: "Generate a quiz, a flashcard deck or a roadmap and it will show up here.",
+    emptyCta: "Start a quiz",
+    featureQuiz: "Quiz",
+    featureFlashcards: "Flashcards",
+    featureRoadmap: "Roadmap",
+    featureConcepts: "Concept map",
+    featureChat: "Chat",
+  },
+  days: {
+    sun: "Sun",
+    mon: "Mon",
+    tue: "Tue",
+    wed: "Wed",
+    thu: "Thu",
+    fri: "Fri",
+    sat: "Sat",
+  },
+  concepts: {
+    title: "Concept map",
+    description: "How the main ideas of a subject connect, coloured by how well you know each one.",
+    mapTitle: "Programming fundamentals",
+    sampleNote: "This page shows fixed sample data. It is not generated from your sessions yet.",
+    legend: "Mastery",
+    strong: "Strong (80% and above)",
+    building: "Building (50–79%)",
+    weak: "Needs work (below 50%)",
+    linksTo: "Links to {list}",
+    variables: "Variables",
+    functions: "Functions",
+    dataTypes: "Data types",
+    controlFlow: "Control flow",
+    collections: "Collections",
+    oop: "Object-oriented programming",
+  },
+  chat: {
+    reasoning: "Reasoning",
+    you: "You",
+    model: "AI",
+  },
+  settings: {
+    title: "AI provider settings",
+    subtitle: "Bring your own API key to use the AI features.",
+    closeLabel: "Close settings",
+    serverMode: "This server has its own API key configured{detail}. There is nothing to set up here.",
+    provider: "Provider",
+    selfHostNote: "Self-hosted options need your own copy of LearnPath.",
+    baseUrl: "Base URL",
+    baseUrlDefault: "Leave empty to use {url}.",
+    baseUrlAny: "Any OpenAI-compatible endpoint, ending in /v1.",
+    model: "Model",
+    modelPlaceholder: "model name",
+    modelDefault: "Default for {provider}:",
+    useDefault: "use default",
+    apiKey: "API key",
+    optional: "(optional)",
+    keyPlaceholder: "Paste your key",
+    show: "Show",
+    hide: "Hide",
+    getKey: "Get an API key from {provider}",
+    privacyTitle: "Where your key goes",
+    privacyBody: "Your key is saved only in this browser. It is sent with each request through this app's API route to the provider you chose, and is never stored or logged on the server. Use a key with a spending limit, and press “Forget key” on a shared device.",
+    storageBlocked: "This browser blocked local storage, so the settings could not be saved (private mode?).",
+    keyForgotten: "Your key has been removed from this browser.",
+    forget: "Forget key",
+  },
+  errors: {
+    title: "That did not work",
+    openSettings: "Open settings",
+    unknown: "Something went wrong. Please try again.",
+    network: "Could not reach LearnPath's server. Check your connection.",
+    http_error: "The request failed. Please try again.",
+    empty_stream: "The server returned an empty stream.",
+    missing_key: "Add your API key in Settings to use this feature.",
+    invalid_provider: "That provider is not supported. Choose another one in Settings.",
+    provider_not_allowed: "This provider is only available when you run LearnPath yourself.",
+    custom_base_url_not_allowed: "This server only talks to the built-in providers. Custom base URLs are disabled.",
+    invalid_base_url: "The base URL is not valid. Check it in Settings.",
+    invalid_model: "The model name contains characters that are not allowed.",
+    invalid_key_format: "That API key does not look valid.",
+    invalid_request: "The request was not valid. Check your input and try again.",
+    server_misconfigured: "This server is not set up correctly. Contact its owner.",
+    provider_rejected_key: "The provider rejected your key. Check the API key and provider in Settings.",
+    provider_payment_required: "The provider says this account has no credit or billing set up.",
+    provider_rate_limited: "The provider is rate limiting this key or its quota is used up. Wait a moment and try again.",
+    provider_model_not_found: "The provider could not find that model. Check the model name in Settings.",
+    provider_bad_request: "The provider refused the request. The model name may be wrong for this provider.",
+    provider_unavailable: "The provider is having trouble right now. Try again later.",
+    provider_unreachable: "Could not reach the provider. Check the provider in Settings.",
+    provider_timeout: "The provider took too long to answer. Try again.",
+    unreadable_output: "The model replied, but not in a format LearnPath could read. Try again or pick a stronger model.",
+    server_error: "Something went wrong on the server. Please try again.",
+  },
+};
diff --git a/src/i18n/messages/index.ts b/src/i18n/messages/index.ts
new file mode 100644
index 0000000..6deb075
--- /dev/null
+++ b/src/i18n/messages/index.ts
@@ -0,0 +1,46 @@
+import type { Locale } from "../config";
+import { en } from "./en";
+import { ms } from "./ms";
+import type { MessageKey, Messages } from "./types";
+
+export type { MessageKey, Messages };
+
+export const MESSAGES: Record<Locale, Messages> = { en, ms };
+
+export type TranslateParams = Record<string, string | number>;
+
+/** Look up a dotted key. Returns the key itself when it does not exist (never throws). */
+export function lookup(messages: Messages, key: string): string | undefined {
+  let node: unknown = messages;
+  for (const part of key.split(".")) {
+    if (!node || typeof node !== "object") return undefined;
+    node = (node as Record<string, unknown>)[part];
+  }
+  return typeof node === "string" ? node : undefined;
+}
+
+/** Replace {name} placeholders. Unknown placeholders are left as they are. */
+export function interpolate(template: string, params?: TranslateParams): string {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : match,
+  );
+}
+
+export function translate(locale: Locale, key: MessageKey, params?: TranslateParams): string {
+  const text = lookup(MESSAGES[locale], key) ?? lookup(MESSAGES.en, key) ?? key;
+  return interpolate(text, params);
+}
+
+/** Flatten nested messages into dotted keys (used by tests and tooling). */
+export function flattenMessages(node: unknown, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+      const key = prefix ? `${prefix}.${k}` : k;
+      if (typeof v === "string") out[key] = v;
+      else Object.assign(out, flattenMessages(v, key));
+    }
+  }
+  return out;
+}
diff --git a/src/i18n/messages/ms.ts b/src/i18n/messages/ms.ts
new file mode 100644
index 0000000..58a5035
--- /dev/null
+++ b/src/i18n/messages/ms.ts
@@ -0,0 +1,269 @@
+/**
+ * Teks antara muka Bahasa Melayu (ejaan baku Malaysia, bukan Indonesia).
+ * Mesti mempunyai kunci yang sama dengan `en.ts`.
+ */
+import type { Messages } from "./types";
+
+export const ms: Messages = {
+  meta: {
+    title: "LearnPath: kuiz, kad imbas dan peta laluan pembelajaran dengan AI",
+    description:
+      "Jana kuiz, kad imbas dan peta laluan pembelajaran untuk apa-apa topik dengan LLM yang serasi OpenAI. Guna kunci API anda sendiri. Dalam Bahasa Melayu dan bahasa Inggeris.",
+  },
+  common: {
+    appName: "LearnPath",
+    skipToContent: "Langkau ke kandungan",
+    tryAgain: "Cuba lagi",
+    newTopic: "Topik baharu",
+    close: "Tutup",
+    cancel: "Batal",
+    save: "Simpan",
+    done: "Selesai",
+    next: "Seterusnya",
+    tokens: "{count} token",
+    sampleData: "Data contoh",
+  },
+  nav: {
+    label: "Navigasi utama",
+    home: "Utama",
+    quiz: "Kuiz",
+    flashcards: "Kad imbas",
+    roadmap: "Peta laluan",
+    progress: "Kemajuan",
+    concepts: "Konsep",
+  },
+  header: {
+    homeLink: "Laman utama LearnPath",
+    settings: "Tetapan",
+    statusServer: "Kunci pelayan",
+    statusReady: "Sedia",
+    statusNeedsKey: "Masukkan kunci API",
+    language: "Bahasa",
+    themeToDark: "Tukar ke tema gelap",
+    themeToLight: "Tukar ke tema cerah",
+  },
+  language: {
+    en: "English",
+    ms: "Bahasa Melayu",
+    enShort: "EN",
+    msShort: "BM",
+  },
+  footer: {
+    source: "Kod sumber di GitHub",
+    builtBy: "Dibina oleh {name}",
+    tagline: "Buatan Malaysia",
+  },
+  home: {
+    eyebrow: "Teman belajar berkuasa AI",
+    title: "Jadikan apa-apa topik pelan belajar yang boleh anda latih.",
+    lead: "Taip satu topik. LearnPath meminta model AI pilihan anda menyediakan kuiz, set kad imbas atau peta laluan langkah demi langkah, dalam Bahasa Melayu atau bahasa Inggeris.",
+    ctaQuiz: "Mula kuiz",
+    ctaRoadmap: "Rancang peta laluan",
+    featuresTitle: "Apa yang boleh anda buat",
+    quizTitle: "Kuiz",
+    quizDesc: "Soalan aneka pilihan pada tahap kesukaran yang anda pilih, setiap satu dengan penerangan.",
+    flashcardsTitle: "Kad imbas",
+    flashcardsDesc: "Set kad untuk diulang kaji, dinilai dengan kaedah ulangan berjarak SM-2.",
+    roadmapTitle: "Peta laluan pembelajaran",
+    roadmapDesc: "Pelan langkah demi langkah dari peringkat permulaan hingga lanjutan, dengan anggaran masa.",
+    progressTitle: "Kemajuan",
+    progressDesc: "Sesi, markah dan penggunaan token sepanjang lawatan ini.",
+    conceptsTitle: "Peta konsep",
+    conceptsDesc: "Peta contoh konsep yang berkait dan tahap penguasaannya.",
+    howTitle: "Cara ia berfungsi",
+    how1Title: "Pilih topik",
+    how1Desc: "Apa sahaja, daripada Fotosintesis hingga gabungan SQL.",
+    how2Title: "AI menyediakan draf",
+    how2Desc: "Model pilihan anda menulis soalan, kad atau langkah dalam bahasa anda.",
+    how3Title: "Latih dan ulang kaji",
+    how3Desc: "Jawab, balikkan kad dan beri penilaian. Kemajuan lawatan ini dipaparkan di halaman Kemajuan.",
+    byokTitle: "Guna kunci anda sendiri",
+    byokDesc: "Guna kunci daripada OpenAI, OpenRouter, Groq, DeepSeek, Together AI, Mistral atau Xiaomi MiMo. Kunci itu kekal dalam pelayar anda. Salinan yang dihos sendiri juga boleh menggunakan Ollama, llama.cpp atau mana-mana titik akhir yang serasi OpenAI.",
+    byokCta: "Buka tetapan",
+    honestNote: "Hasil AI mungkin mengandungi kesilapan. Semak fakta penting dengan buku teks atau guru anda.",
+  },
+  topicForm: {
+    topicLabel: "Topik",
+    examplesLabel: "Cuba",
+    example1: "Fotosintesis",
+    example2: "Pecahan",
+    example3: "Sejarah Kemerdekaan Malaysia",
+    example4: "Gabungan SQL",
+    emptyTopic: "Masukkan topik dahulu.",
+  },
+  quiz: {
+    title: "Kuiz",
+    description: "Soalan aneka pilihan untuk apa-apa topik, dengan penerangan bagi setiap jawapan.",
+    formTitle: "Sediakan kuiz",
+    placeholder: "cth. Fotosintesis, Pecahan, Sistem suria",
+    difficulty: "Tahap kesukaran",
+    questionCount: "Bilangan soalan",
+    generate: "Jana kuiz",
+    loading: "Sedang menulis kuiz anda…",
+    loadingHint: "Ini boleh mengambil masa sehingga seminit, bergantung pada model.",
+    questionOf: "Soalan {current} daripada {total}",
+    easy: "Mudah",
+    medium: "Sederhana",
+    hard: "Sukar",
+    explanation: "Penerangan",
+    correct: "Betul",
+    incorrect: "Kurang tepat",
+    correctAnswerWas: "Jawapannya ialah {answer}.",
+    seeResults: "Lihat keputusan",
+    completeTitle: "Kuiz selesai",
+    scoreLine: "{correct} daripada {total} betul",
+    scoreGreat: "Syabas. Anda menguasai topik ini dengan baik.",
+    scoreGood: "Kemajuan yang baik. Ulang kaji soalan yang anda tersilap.",
+    scoreLow: "Permulaan yang baik. Cuba kad imbas untuk topik ini, kemudian jawab kuiz sekali lagi.",
+    reviewTitle: "Semakan",
+    yourAnswer: "Jawapan anda: {answer}",
+    tryAnother: "Cuba topik lain",
+    retake: "Ulang kuiz ini",
+  },
+  flashcards: {
+    title: "Kad imbas",
+    description: "Ulang kaji set kad yang dijana dan nilai setiap kad. Penilaian anda digunakan oleh jadual ulangan berjarak SM-2.",
+    formTitle: "Sediakan set kad",
+    placeholder: "cth. Fotosintesis, Biologi sel, Struktur data",
+    generate: "Jana kad imbas",
+    loading: "Sedang menulis kad imbas anda…",
+    loadingHint: "Ini boleh mengambil masa sehingga seminit, bergantung pada model.",
+    cardOf: "Kad {current} daripada {total}",
+    tapToReveal: "Ketik untuk melihat jawapan",
+    answer: "Jawapan",
+    rateQuestion: "Sejauh mana anda ingat?",
+    rateHard: "Sukar",
+    rateGood: "Baik",
+    rateEasy: "Mudah",
+    completeTitle: "Set kad selesai diulang kaji",
+    completeDesc: "Anda telah mengulang kaji {total} kad tentang {topic}.",
+    reviewAgain: "Ulang kaji semula",
+  },
+  roadmap: {
+    title: "Peta laluan pembelajaran",
+    description: "Pelan langkah demi langkah untuk satu topik mengikut tahap anda, dengan anggaran masa dan idea utama bagi setiap langkah.",
+    formTitle: "Rancang peta laluan",
+    placeholder: "cth. Fotosintesis, Pembangunan web, Statistik",
+    level: "Tahap",
+    beginner: "Permulaan",
+    intermediate: "Pertengahan",
+    advanced: "Lanjutan",
+    generate: "Jana peta laluan",
+    loading: "Sedang merancang peta laluan anda…",
+    loadingHint: "Ini boleh mengambil masa sehingga seminit, bergantung pada model.",
+    stepsCount: "{count} langkah",
+    statusCompleted: "Selesai",
+    statusCurrent: "Langkah semasa",
+    statusUpcoming: "Akan datang",
+    stepLabel: "Langkah {number}",
+    markDone: "Tandakan selesai",
+    allDone: "Peta laluan selesai. Syabas.",
+    newRoadmap: "Peta laluan baharu",
+  },
+  progress: {
+    title: "Kemajuan",
+    description: "Kuiz, set kad imbas dan peta laluan yang anda hasilkan sepanjang lawatan ini. Tiada apa-apa disimpan selepas anda menutup tab.",
+    sessions: "Sesi",
+    studyTime: "Masa belajar",
+    studyTimeValue: "{minutes} min",
+    tokens: "Token digunakan",
+    weekly: "Aktiviti 7 hari lepas",
+    weeklyCaption: "Sesi sehari",
+    byFeature: "Token mengikut ciri",
+    topics: "Topik",
+    topicLine: "{sessions} sesi · purata markah {score}%",
+    topicLineNoScore: "{sessions} sesi",
+    emptyTitle: "Belum ada sesi",
+    emptyDesc: "Jana kuiz, set kad imbas atau peta laluan dan ia akan dipaparkan di sini.",
+    emptyCta: "Mula kuiz",
+    featureQuiz: "Kuiz",
+    featureFlashcards: "Kad imbas",
+    featureRoadmap: "Peta laluan",
+    featureConcepts: "Peta konsep",
+    featureChat: "Sembang",
+  },
+  days: {
+    sun: "Ahd",
+    mon: "Isn",
+    tue: "Sel",
+    wed: "Rab",
+    thu: "Kha",
+    fri: "Jum",
+    sat: "Sab",
+  },
+  concepts: {
+    title: "Peta konsep",
+    description: "Bagaimana idea utama sesuatu subjek saling berkait, diwarnakan mengikut tahap penguasaan anda.",
+    mapTitle: "Asas pengaturcaraan",
+    sampleNote: "Halaman ini memaparkan data contoh yang tetap. Ia belum dijana daripada sesi anda.",
+    legend: "Penguasaan",
+    strong: "Kukuh (80% ke atas)",
+    building: "Sedang dibina (50–79%)",
+    weak: "Perlu diperbaiki (bawah 50%)",
+    linksTo: "Berkait dengan {list}",
+    variables: "Pemboleh ubah",
+    functions: "Fungsi",
+    dataTypes: "Jenis data",
+    controlFlow: "Aliran kawalan",
+    collections: "Koleksi",
+    oop: "Pengaturcaraan berorientasikan objek",
+  },
+  chat: {
+    reasoning: "Penaakulan",
+    you: "Anda",
+    model: "AI",
+  },
+  settings: {
+    title: "Tetapan penyedia AI",
+    subtitle: "Guna kunci API anda sendiri untuk menggunakan ciri AI.",
+    closeLabel: "Tutup tetapan",
+    serverMode: "Pelayan ini sudah mempunyai kunci API sendiri{detail}. Tiada apa-apa yang perlu disediakan di sini.",
+    provider: "Penyedia",
+    selfHostNote: "Pilihan hos sendiri memerlukan salinan LearnPath anda sendiri.",
+    baseUrl: "URL asas",
+    baseUrlDefault: "Biarkan kosong untuk menggunakan {url}.",
+    baseUrlAny: "Mana-mana titik akhir yang serasi OpenAI, berakhir dengan /v1.",
+    model: "Model",
+    modelPlaceholder: "nama model",
+    modelDefault: "Lalai untuk {provider}:",
+    useDefault: "guna lalai",
+    apiKey: "Kunci API",
+    optional: "(pilihan)",
+    keyPlaceholder: "Tampal kunci anda",
+    show: "Tunjuk",
+    hide: "Sorok",
+    getKey: "Dapatkan kunci API daripada {provider}",
+    privacyTitle: "Ke mana kunci anda pergi",
+    privacyBody: "Kunci anda disimpan dalam pelayar ini sahaja. Ia dihantar bersama setiap permintaan melalui laluan API aplikasi ini kepada penyedia yang anda pilih, dan tidak pernah disimpan atau dilog pada pelayan. Guna kunci yang mempunyai had perbelanjaan, dan tekan “Lupakan kunci” pada peranti yang dikongsi.",
+    storageBlocked: "Pelayar ini menyekat storan setempat, jadi tetapan tidak dapat disimpan (mod peribadi?).",
+    keyForgotten: "Kunci anda telah dibuang daripada pelayar ini.",
+    forget: "Lupakan kunci",
+  },
+  errors: {
+    title: "Tidak berjaya",
+    openSettings: "Buka tetapan",
+    unknown: "Sesuatu tidak kena. Sila cuba lagi.",
+    network: "Tidak dapat menghubungi pelayan LearnPath. Semak sambungan internet anda.",
+    http_error: "Permintaan gagal. Sila cuba lagi.",
+    empty_stream: "Pelayan memulangkan strim kosong.",
+    missing_key: "Masukkan kunci API anda dalam Tetapan untuk menggunakan ciri ini.",
+    invalid_provider: "Penyedia itu tidak disokong. Pilih penyedia lain dalam Tetapan.",
+    provider_not_allowed: "Penyedia ini hanya tersedia apabila anda menjalankan LearnPath sendiri.",
+    custom_base_url_not_allowed: "Pelayan ini hanya berhubung dengan penyedia terbina dalam. URL asas tersuai dimatikan.",
+    invalid_base_url: "URL asas tidak sah. Semak dalam Tetapan.",
+    invalid_model: "Nama model mengandungi aksara yang tidak dibenarkan.",
+    invalid_key_format: "Kunci API itu nampaknya tidak sah.",
+    invalid_request: "Permintaan tidak sah. Semak input anda dan cuba lagi.",
+    server_misconfigured: "Pelayan ini belum dikonfigurasi dengan betul. Hubungi pemiliknya.",
+    provider_rejected_key: "Penyedia menolak kunci anda. Semak kunci API dan penyedia dalam Tetapan.",
+    provider_payment_required: "Penyedia menyatakan akaun ini tiada kredit atau pengebilan belum disediakan.",
+    provider_rate_limited: "Penyedia mengehadkan kadar permintaan untuk kunci ini atau kuotanya sudah habis. Tunggu sebentar dan cuba lagi.",
+    provider_model_not_found: "Penyedia tidak menjumpai model itu. Semak nama model dalam Tetapan.",
+    provider_bad_request: "Penyedia menolak permintaan ini. Nama model mungkin salah untuk penyedia ini.",
+    provider_unavailable: "Penyedia sedang menghadapi masalah. Cuba lagi sebentar nanti.",
+    provider_unreachable: "Tidak dapat menghubungi penyedia. Semak penyedia dalam Tetapan.",
+    provider_timeout: "Penyedia mengambil masa terlalu lama untuk menjawab. Cuba lagi.",
+    unreadable_output: "Model telah menjawab, tetapi dalam format yang tidak dapat dibaca oleh LearnPath. Cuba lagi atau pilih model yang lebih berkebolehan.",
+    server_error: "Berlaku ralat pada pelayan. Sila cuba lagi.",
+  },
+};
diff --git a/src/i18n/messages/types.ts b/src/i18n/messages/types.ts
new file mode 100644
index 0000000..773aa80
--- /dev/null
+++ b/src/i18n/messages/types.ts
@@ -0,0 +1,13 @@
+import type { en } from "./en";
+
+/** Same shape as the English messages, with every leaf widened to `string`. */
+type Widen<T> = { [K in keyof T]: T[K] extends string ? string : Widen<T[K]> };
+
+export type Messages = Widen<typeof en>;
+
+/** Every dotted key path that ends at a string, e.g. "quiz.generate". */
+export type MessageKey = Paths<Messages>;
+
+type Paths<T, P extends string = ""> = {
+  [K in keyof T & string]: T[K] extends string ? `${P}${K}` : Paths<T[K], `${P}${K}.`>;
+}[keyof T & string];
diff --git a/src/i18n/server.ts b/src/i18n/server.ts
new file mode 100644
index 0000000..93f0047
--- /dev/null
+++ b/src/i18n/server.ts
@@ -0,0 +1,9 @@
+import { cookies, headers } from "next/headers";
+import { LOCALE_COOKIE, detectLocale, isLocale, parseAcceptLanguage, type Locale } from "./config";
+
+/** Locale for the first server render: the visitor's saved choice, else their browser language. */
+export async function getRequestLocale(): Promise<Locale> {
+  const saved = (await cookies()).get(LOCALE_COOKIE)?.value;
+  if (isLocale(saved)) return saved;
+  return detectLocale(parseAcceptLanguage((await headers()).get("accept-language")));
+}
diff --git a/tests/i18n/locale.test.ts b/tests/i18n/locale.test.ts
new file mode 100644
index 0000000..d271ae3
--- /dev/null
+++ b/tests/i18n/locale.test.ts
@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { LOCALE_STORAGE_KEY, detectLocale, parseAcceptLanguage } from "@/i18n/config";
+import { getClientLocale, resetLocaleMemory, setClientLocale } from "@/i18n/locale-store";
+
+function setLanguages(langs: string[]) {
+  vi.spyOn(navigator, "languages", "get").mockReturnValue(langs);
+}
+
+describe("detectLocale", () => {
+  it("maps Malay tags to BM and everything else to English", () => {
+    expect(detectLocale(["ms-MY", "en"])).toBe("ms");
+    expect(detectLocale(["ms"])).toBe("ms");
+    expect(detectLocale(["en-GB", "ms"])).toBe("en");
+    expect(detectLocale(["zh-CN", "ms-MY"])).toBe("ms");
+    expect(detectLocale(["id-ID"])).toBe("en");
+    expect(detectLocale([])).toBe("en");
+  });
+
+  it("reads Accept-Language by q-value", () => {
+    expect(parseAcceptLanguage("en;q=0.5, ms-MY;q=0.9, zh")).toEqual(["zh", "ms-MY", "en"]);
+    expect(detectLocale(parseAcceptLanguage("en-US;q=0.4,ms;q=0.8"))).toBe("ms");
+    expect(parseAcceptLanguage(null)).toEqual([]);
+  });
+});
+
+describe("client locale store", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetLocaleMemory();
+    document.cookie = "learnpath-locale=; max-age=0; path=/";
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it("defaults to the browser language (ms → BM)", () => {
+    setLanguages(["ms-MY", "en-US"]);
+    expect(getClientLocale()).toBe("ms");
+  });
+
+  it("defaults to English for other browser languages", () => {
+    setLanguages(["fr-FR"]);
+    expect(getClientLocale()).toBe("en");
+  });
+
+  it("persists the choice in localStorage and mirrors it to a cookie", () => {
+    setLanguages(["en-US"]);
+    expect(setClientLocale("ms")).toBe(true);
+    expect(localStorage.getItem(LOCALE_STORAGE_KEY)).toBe("ms");
+    expect(document.cookie).toContain("learnpath-locale=ms");
+    resetLocaleMemory();
+    expect(getClientLocale()).toBe("ms");
+  });
+
+  it("still switches when localStorage throws (private mode)", () => {
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("QuotaExceededError");
+    });
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("SecurityError");
+    });
+    expect(setClientLocale("ms")).toBe(false);
+    expect(getClientLocale()).toBe("ms");
+  });
+
+  it("ignores garbage in storage", () => {
+    setLanguages(["en"]);
+    localStorage.setItem(LOCALE_STORAGE_KEY, "klingon");
+    expect(getClientLocale()).toBe("en");
+  });
+});
diff --git a/tests/i18n/messages.test.ts b/tests/i18n/messages.test.ts
new file mode 100644
index 0000000..b639ee9
--- /dev/null
+++ b/tests/i18n/messages.test.ts
@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { MESSAGES, flattenMessages, interpolate, translate } from "@/i18n/messages";
+import { LOCALES } from "@/i18n/config";
+
+const flat = Object.fromEntries(LOCALES.map((l) => [l, flattenMessages(MESSAGES[l])])) as Record<
+  (typeof LOCALES)[number],
+  Record<string, string>
+>;
+
+const placeholders = (s: string) => [...s.matchAll(/\{(\w+)\}/g)].map((m) => m[1]).sort();
+
+describe("language files", () => {
+  it("contain a meaningful number of keys", () => {
+    expect(Object.keys(flat.en).length).toBeGreaterThan(100);
+  });
+
+  for (const locale of LOCALES) {
+    for (const other of LOCALES) {
+      if (locale === other) continue;
+      it(`every ${locale} key exists in ${other}`, () => {
+        const missing = Object.keys(flat[locale]).filter((k) => !(k in flat[other]));
+        expect(missing).toEqual([]);
+      });
+    }
+
+    it(`${locale} has no empty strings`, () => {
+      const empty = Object.entries(flat[locale]).filter(([, v]) => !v.trim());
+      expect(empty).toEqual([]);
+    });
+  }
+
+  it("uses the same {placeholders} in both languages", () => {
+    const mismatched = Object.keys(flat.en).filter(
+      (k) => JSON.stringify(placeholders(flat.en[k])) !== JSON.stringify(placeholders(flat.ms[k] ?? "")),
+    );
+    expect(mismatched).toEqual([]);
+  });
+
+  it("BM text avoids common Indonesian words", () => {
+    // Malaysian standard alternatives: hantar, muat turun, ketika/semasa, kerana, mesti/perlu,
+    // wang, percuma, sila, berjaya, butang, tetapan, kata laluan, boleh, nombor, cuba.
+    const indonesian = [
+      "kirim", "unduh", "saat", "karena", "harus", "uang", "gratis", "silakan", "berhasil",
+      "tombol", "pengaturan", "sandi", "bisa", "nomor", "coba", "mencoba", "kamu", "aplikasinya",
+    ];
+    const hits: string[] = [];
+    for (const [key, text] of Object.entries(flat.ms)) {
+      for (const word of indonesian) {
+        if (new RegExp(`(^|[^\\p{L}])${word}([^\\p{L}]|$)`, "iu").test(text)) hits.push(`${key}: ${word}`);
+      }
+    }
+    expect(hits).toEqual([]);
+  });
+
+  it("BM strings are actually translated (not copied from English)", () => {
+    // Brand names, abbreviations and pure numbers may be identical.
+    const allowedSame = new Set(["common.appName", "language.en", "language.ms", "language.enShort", "language.msShort", "chat.model", "settings.model", "progress.studyTimeValue"]);
+    const same = Object.keys(flat.en).filter((k) => flat.en[k] === flat.ms[k] && !allowedSame.has(k));
+    expect(same).toEqual([]);
+  });
+});
+
+describe("translate()", () => {
+  it("returns the string for the locale and fills placeholders", () => {
+    expect(translate("en", "quiz.questionOf", { current: 2, total: 5 })).toBe("Question 2 of 5");
+    expect(translate("ms", "quiz.questionOf", { current: 2, total: 5 })).toBe("Soalan 2 daripada 5");
+  });
+
+  it("uses the agreed Malaysian terms", () => {
+    expect(translate("ms", "nav.flashcards")).toBe("Kad imbas");
+    expect(translate("ms", "nav.quiz")).toBe("Kuiz");
+    expect(translate("ms", "home.roadmapTitle")).toBe("Peta laluan pembelajaran");
+    expect(translate("ms", "header.settings")).toBe("Tetapan");
+    expect(translate("ms", "settings.apiKey")).toBe("Kunci API");
+  });
+
+  it("falls back to the key for an unknown key instead of throwing", () => {
+    expect(translate("ms", "nope.missing" as never)).toBe("nope.missing");
+  });
+
+  it("leaves unknown placeholders untouched", () => {
+    expect(interpolate("Hi {name} {other}", { name: "Aina" })).toBe("Hi Aina {other}");
+  });
+});

From 777cf2100411d3252fb510ae471f5e8a547f0e26 Mon Sep 17 00:00:00 2001
From: Muhammad Aiman <84276911+aimanmalib@users.noreply.github.com>
Date: Tue, 20 Oct 2026 09:46:31 +0000
Subject: [PATCH 2/4] feat(api): the model answers in the selected language

Every API call sends `language: "en" | "ms"`. Each route appends a
language instruction to its system prompt and a short reminder to the
user message. The BM instruction asks for standard Malaysian spelling and
names Indonesian words to avoid. Unknown values fall back to English.

Tests cover every route (quiz, flashcards, roadmap, chat, analyze) and the
browser client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/app/api/analyze/route.ts    |  7 ++--
 src/app/api/chat/route.ts       | 11 ++++--
 src/app/api/flashcards/route.ts |  6 ++--
 src/app/api/quiz/route.ts       |  6 ++--
 src/app/api/roadmap/route.ts    |  7 ++--
 src/hooks/useChat.ts            |  6 ++--
 src/lib/api-client.ts           | 20 +++++++++--
 src/lib/llm/language.ts         | 41 ++++++++++++++++++++++
 tests/api/routes.test.ts        | 62 +++++++++++++++++++++++++++++++++
 tests/lib/api-client.test.ts    | 30 ++++++++++++++++
 10 files changed, 178 insertions(+), 18 deletions(-)
 create mode 100644 src/lib/llm/language.ts
 create mode 100644 tests/lib/api-client.test.ts

diff --git a/src/app/api/analyze/route.ts b/src/app/api/analyze/route.ts
index 6dbd623..005119f 100644
--- a/src/app/api/analyze/route.ts
+++ b/src/app/api/analyze/route.ts
@@ -1,15 +1,16 @@
 import { NextResponse } from "next/server";
 import { chatCompletion } from "@/lib/llm/client";
 import { handleLlmRoute, textField } from "@/lib/llm/server";
+import { languageInstruction, languageReminder, outputLanguage } from "@/lib/llm/language";
 
 export async function POST(request: Request) {
   return handleLlmRoute(request, async ({ llm, body }) => {
     const topic = textField(body.topic, 200, "general");
     const sessions = Array.isArray(body.sessions) ? body.sessions.slice(-20) : [];
     const sessionSummary = JSON.stringify(sessions).slice(0, 8000);
+    const language = outputLanguage(body.language);
 
-    const systemPrompt =
-      "You are a learning analytics expert. Analyze study session data and provide insights and recommendations for improvement. Be specific and actionable.";
+    const systemPrompt = `You are a learning analytics expert. Analyze study session data and provide insights and recommendations for improvement. Be specific and actionable. ${languageInstruction(language)}`;
 
     const result = await chatCompletion(
       llm,
@@ -17,7 +18,7 @@ export async function POST(request: Request) {
         { role: "system", content: systemPrompt },
         {
           role: "user",
-          content: `Analyze these study sessions for topic ${JSON.stringify(topic)}: ${sessionSummary}. Provide: 1) Performance summary 2) Weak areas 3) Recommended next steps`,
+          content: `Analyze these study sessions for topic ${JSON.stringify(topic)}: ${sessionSummary}. Provide: 1) Performance summary 2) Weak areas 3) Recommended next steps. ${languageReminder(language)}`,
         },
       ],
       { temperature: 0.5, maxTokens: 2048 },
diff --git a/src/app/api/chat/route.ts b/src/app/api/chat/route.ts
index 946537b..5eb1f49 100644
--- a/src/app/api/chat/route.ts
+++ b/src/app/api/chat/route.ts
@@ -2,16 +2,21 @@ import { NextResponse } from "next/server";
 import { chatCompletion, chatCompletionStream, type ChatMessage } from "@/lib/llm/client";
 import { handleLlmRoute, textField } from "@/lib/llm/server";
 import { LlmError } from "@/lib/llm/errors";
+import { languageInstruction, outputLanguage } from "@/lib/llm/language";
 
 export async function POST(request: Request) {
   return handleLlmRoute(request, async ({ llm, body }) => {
     const message = textField(body.message, 8000);
     if (!message) throw new LlmError("invalid_request", "Message is empty.", 400);
     const systemPrompt = textField(body.systemPrompt, 4000);
+    const language = outputLanguage(body.language);
 
-    const messages: ChatMessage[] = [];
-    if (systemPrompt) messages.push({ role: "system", content: systemPrompt });
-    messages.push({ role: "user", content: message });
+    // The language instruction always goes first; a caller's system prompt follows it.
+    const system = [languageInstruction(language), systemPrompt].filter(Boolean).join("\n\n");
+    const messages: ChatMessage[] = [
+      { role: "system", content: system },
+      { role: "user", content: message },
+    ];
 
     if (body.stream === true) {
       const stream = await chatCompletionStream(llm, messages, { temperature: 0.7, maxTokens: 2048, timeoutMs: 120_000 });
diff --git a/src/app/api/flashcards/route.ts b/src/app/api/flashcards/route.ts
index 850361c..54e1518 100644
--- a/src/app/api/flashcards/route.ts
+++ b/src/app/api/flashcards/route.ts
@@ -2,15 +2,17 @@ import { NextResponse } from "next/server";
 import { chatCompletion } from "@/lib/llm/client";
 import { extractJson, handleLlmRoute, intField, textField, unreadable } from "@/lib/llm/server";
 import { LlmError } from "@/lib/llm/errors";
+import { languageInstruction, languageReminder, outputLanguage } from "@/lib/llm/language";
 
 export async function POST(request: Request) {
   return handleLlmRoute(request, async ({ llm, body }) => {
     const topic = textField(body.topic, 200);
     if (!topic) throw new LlmError("invalid_request", "Enter a topic first.", 400);
     const count = intField(body.count, 1, 20, 10);
+    const language = outputLanguage(body.language);
 
-    const systemPrompt = `Generate ${count} study flashcards about the user's topic. Return ONLY a valid JSON array, no prose.`;
-    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: [{"id":"fc1","front":"question or concept","back":"answer or definition"}]`;
+    const systemPrompt = `Generate ${count} study flashcards about the user's topic. Return ONLY a valid JSON array, no prose. ${languageInstruction(language)}`;
+    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: [{"id":"fc1","front":"question or concept","back":"answer or definition"}]. ${languageReminder(language)}`;
 
     const result = await chatCompletion(
       llm,
diff --git a/src/app/api/quiz/route.ts b/src/app/api/quiz/route.ts
index 996d6ce..5e1a103 100644
--- a/src/app/api/quiz/route.ts
+++ b/src/app/api/quiz/route.ts
@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { chatCompletion } from "@/lib/llm/client";
 import { extractJson, handleLlmRoute, intField, oneOf, textField, unreadable } from "@/lib/llm/server";
 import { LlmError } from "@/lib/llm/errors";
+import { languageInstruction, languageReminder, outputLanguage } from "@/lib/llm/language";
 
 const DIFFICULTIES = ["easy", "medium", "hard"] as const;
 
@@ -21,9 +22,10 @@ export async function POST(request: Request) {
     if (!topic) throw new LlmError("invalid_request", "Enter a topic first.", 400);
     const count = intField(body.count, 1, 10, 5);
     const difficulty = oneOf(body.difficulty, DIFFICULTIES, "medium");
+    const language = outputLanguage(body.language);
 
-    const systemPrompt = `You are LearnPath's quiz generator. Create ${count} multiple-choice questions about the user's topic at ${difficulty} difficulty. Each question must have exactly 4 options with one correct answer. Return ONLY a valid JSON array, no prose.`;
-    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: [{"id":"q1","question":"...","options":["A","B","C","D"],"correctIndex":0,"explanation":"..."}]`;
+    const systemPrompt = `You are LearnPath's quiz generator. Create ${count} multiple-choice questions about the user's topic at ${difficulty} difficulty. Each question must have exactly 4 options with one correct answer. Return ONLY a valid JSON array, no prose. ${languageInstruction(language)}`;
+    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: [{"id":"q1","question":"...","options":["A","B","C","D"],"correctIndex":0,"explanation":"..."}]. ${languageReminder(language)}`;
 
     const result = await chatCompletion(
       llm,
diff --git a/src/app/api/roadmap/route.ts b/src/app/api/roadmap/route.ts
index fe71ba9..30f1d36 100644
--- a/src/app/api/roadmap/route.ts
+++ b/src/app/api/roadmap/route.ts
@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { chatCompletion } from "@/lib/llm/client";
 import { extractJson, handleLlmRoute, oneOf, textField, unreadable } from "@/lib/llm/server";
 import { LlmError } from "@/lib/llm/errors";
+import { languageInstruction, languageReminder, outputLanguage } from "@/lib/llm/language";
 
 const LEVELS = ["beginner", "intermediate", "advanced"] as const;
 
@@ -10,9 +11,11 @@ export async function POST(request: Request) {
     const topic = textField(body.topic, 200);
     if (!topic) throw new LlmError("invalid_request", "Enter a topic first.", 400);
     const level = oneOf(body.level, LEVELS, "beginner");
+    const language = outputLanguage(body.language);
+    const exampleTime = language === "ms" ? "2 jam" : "2 hours";
 
-    const systemPrompt = `You are a learning path designer. Create a structured ${level}-level roadmap for the user's topic. Break it into clear steps with estimated times. Return ONLY valid JSON, no prose.`;
-    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: {"title":"...","steps":[{"id":"s1","title":"...","description":"...","estimatedTime":"2 hours","topics":["a","b"]}]}`;
+    const systemPrompt = `You are a learning path designer. Create a structured ${level}-level roadmap for the user's topic. Break it into clear steps with estimated times. Return ONLY valid JSON, no prose. ${languageInstruction(language)}`;
+    const userPrompt = `Topic: ${JSON.stringify(topic)}. Format: {"title":"...","steps":[{"id":"s1","title":"...","description":"...","estimatedTime":"${exampleTime}","topics":["a","b"]}]}. ${languageReminder(language)}`;
 
     const result = await chatCompletion(
       llm,
diff --git a/src/hooks/useChat.ts b/src/hooks/useChat.ts
index ce08cc2..94ab908 100644
--- a/src/hooks/useChat.ts
+++ b/src/hooks/useChat.ts
@@ -1,6 +1,6 @@
 "use client";
 import { useCallback, useState } from "react";
-import { ApiError, apiHeaders, openSettings, postJson, toApiError } from "@/lib/api-client";
+import { ApiError, apiHeaders, openSettings, postJson, toApiError, withLanguage } from "@/lib/api-client";
 import { parseSSEStream } from "@/lib/sse-parser";
 
 interface ChatState {
@@ -52,11 +52,11 @@ export function useChat() {
       const res = await fetch("/api/chat", {
         method: "POST",
         headers: apiHeaders(),
-        body: JSON.stringify({ message, systemPrompt, stream: true }),
+        body: JSON.stringify(withLanguage({ message, systemPrompt, stream: true })),
       });
       if (!res.ok) {
         const err = await toApiError(res);
-        if (err.code === "missing_key") openSettings(err.message);
+        if (err.code === "missing_key") openSettings(err.code);
         throw err;
       }
       if (!res.body) throw new ApiError("empty_stream", "The server returned an empty stream.", res.status);
diff --git a/src/lib/api-client.ts b/src/lib/api-client.ts
index 7a1583e..ef3973c 100644
--- a/src/lib/api-client.ts
+++ b/src/lib/api-client.ts
@@ -3,6 +3,8 @@
  * provider settings attached as headers.
  */
 import { loadSettings, settingsHeaders } from "./llm/settings";
+import { getClientLocale } from "@/i18n/locale-store";
+import type { Locale } from "@/i18n/config";
 
 export const OPEN_SETTINGS_EVENT = "learnpath:open-settings";
 
@@ -35,6 +37,10 @@ export class ApiError extends Error {
   }
 }
 
+/**
+ * Open the settings panel. `reason` is an error code (e.g. "missing_key");
+ * the panel shows the matching message in the visitor's language.
+ */
 export function openSettings(reason?: string): void {
   if (typeof window === "undefined") return;
   window.dispatchEvent(new CustomEvent(OPEN_SETTINGS_EVENT, { detail: { reason } }));
@@ -58,16 +64,24 @@ export function apiHeaders(): Record<string, string> {
   return { "Content-Type": "application/json", ...settingsHeaders(loadSettings()) };
 }
 
-export async function postJson<T>(path: string, body: unknown, fetchImpl: typeof fetch = fetch): Promise<T> {
+/**
+ * Request body with the UI language added, so the model answers in the
+ * language the visitor is reading. An explicit `language` in `body` wins.
+ */
+export function withLanguage<T extends object>(body: T, locale: Locale = getClientLocale()): T & { language: Locale } {
+  return { language: locale, ...body };
+}
+
+export async function postJson<T>(path: string, body: object, fetchImpl: typeof fetch = fetch): Promise<T> {
   let res: Response;
   try {
-    res = await fetchImpl(path, { method: "POST", headers: apiHeaders(), body: JSON.stringify(body) });
+    res = await fetchImpl(path, { method: "POST", headers: apiHeaders(), body: JSON.stringify(withLanguage(body)) });
   } catch {
     throw new ApiError("network", "Could not reach LearnPath's server. Check your connection.", 0);
   }
   if (!res.ok) {
     const err = await toApiError(res);
-    if (err.code === "missing_key") openSettings(err.message);
+    if (err.code === "missing_key") openSettings(err.code);
     throw err;
   }
   return (await res.json()) as T;
diff --git a/src/lib/llm/language.ts b/src/lib/llm/language.ts
new file mode 100644
index 0000000..d132a0b
--- /dev/null
+++ b/src/lib/llm/language.ts
@@ -0,0 +1,41 @@
+/**
+ * Output language for the model.
+ *
+ * Every API route reads `language` from the request body ("en" or "ms") and
+ * adds the instruction below to its prompts, so quizzes, flashcards and
+ * roadmaps come back in the language the visitor is reading.
+ *
+ * The Malay instruction asks for standard Malaysian spelling and lists common
+ * Indonesian words to avoid: models trained mostly on Indonesian web text
+ * drift into it otherwise.
+ */
+import { DEFAULT_LOCALE, isLocale, type Locale } from "@/i18n/config";
+
+export function outputLanguage(value: unknown): Locale {
+  return isLocale(value) ? value : DEFAULT_LOCALE;
+}
+
+export const LANGUAGE_NAMES: Record<Locale, string> = {
+  en: "English",
+  ms: "Bahasa Melayu (Malaysian Malay)",
+};
+
+const INSTRUCTIONS: Record<Locale, string> = {
+  en: "Write every piece of text meant for the learner in English.",
+  ms: [
+    "Write every piece of text meant for the learner in Bahasa Melayu as used in Malaysia, with standard Dewan Bahasa dan Pustaka spelling.",
+    "Do not use Indonesian words or spelling. For example write: kerana (not karena), hantar (not kirim), muat turun (not unduh), semasa or ketika (not saat), mesti or perlu (not harus), wang (not uang), percuma (not gratis), boleh (not bisa), berjaya (not berhasil), nombor (not nomor), cuba (not coba), sila (not silakan).",
+    "Keep standard scientific and technical terms that Malaysian textbooks use.",
+  ].join(" "),
+};
+
+/** Sentence appended to a system prompt. */
+export function languageInstruction(locale: Locale): string {
+  const keepJson = "If the answer is JSON, keep the JSON keys exactly as specified in English; only the values are written in the chosen language.";
+  return `${INSTRUCTIONS[locale]} ${keepJson}`;
+}
+
+/** Short reminder placed in the user message as well, for models that weigh system prompts lightly. */
+export function languageReminder(locale: Locale): string {
+  return `Answer language: ${LANGUAGE_NAMES[locale]}.`;
+}
diff --git a/tests/api/routes.test.ts b/tests/api/routes.test.ts
index debc56c..7a97bd6 100644
--- a/tests/api/routes.test.ts
+++ b/tests/api/routes.test.ts
@@ -186,3 +186,65 @@ describe("GET /api/llm-config", () => {
     expect(text).not.toContain(ENV_KEY);
   });
 });
+
+describe("output language reaches the model", () => {
+  const h = { "x-llm-key": HDR_KEY };
+
+  function sentMessages(): { role: string; content: string }[] {
+    return JSON.parse(fetchMock.mock.calls[0][1].body).messages;
+  }
+
+  const cases: [string, (r: Request) => Promise<Response>, Record<string, unknown>, string][] = [
+    ["quiz", quiz, { topic: "Fotosintesis" }, quizJson],
+    ["flashcards", flashcards, { topic: "Fotosintesis" }, '[{"front":"Q","back":"A"}]'],
+    ["roadmap", roadmap, { topic: "Fotosintesis" }, '{"title":"T","steps":[{"title":"S"}]}'],
+    ["chat", chat, { message: "Apa itu klorofil?" }, "ok"],
+    ["analyze", analyze, { topic: "Fotosintesis", sessions: [] }, "ok"],
+  ];
+
+  for (const [name, route, body, reply] of cases) {
+    it(`${name}: language "ms" asks for Malaysian Malay and warns against Indonesian`, async () => {
+      fetchMock.mockResolvedValue(completion(reply));
+      const res = await route(req({ ...body, language: "ms" }, h));
+      expect(res.status).toBe(200);
+      const messages = sentMessages();
+      const system = messages.find((m) => m.role === "system")?.content ?? "";
+      expect(system).toContain("Bahasa Melayu as used in Malaysia");
+      expect(system).toContain("Do not use Indonesian");
+      expect(system).toContain("kerana (not karena)");
+      expect(system).not.toContain("in English.");
+    });
+
+    it(`${name}: language "en" (and the default) asks for English`, async () => {
+      fetchMock.mockResolvedValue(completion(reply));
+      await route(req({ ...body, language: "en" }, h));
+      const system = sentMessages().find((m) => m.role === "system")?.content ?? "";
+      expect(system).toContain("meant for the learner in English");
+      expect(system).not.toContain("Bahasa Melayu");
+
+      fetchMock.mockClear();
+      fetchMock.mockResolvedValue(completion(reply));
+      await route(req({ ...body, language: "xx-unknown" }, h));
+      expect(sentMessages().find((m) => m.role === "system")?.content).toContain("in English");
+    });
+  }
+
+  it("repeats the language in the user message for generator routes", async () => {
+    await quiz(req({ topic: "Fotosintesis", language: "ms" }, h));
+    expect(sentMessages().find((m) => m.role === "user")?.content).toContain("Answer language: Bahasa Melayu (Malaysian Malay).");
+  });
+
+  it("chat keeps the caller's system prompt after the language instruction", async () => {
+    fetchMock.mockResolvedValue(completion("ok"));
+    await chat(req({ message: "hai", systemPrompt: "You are a tutor.", language: "ms" }, h));
+    const system = sentMessages()[0];
+    expect(system.role).toBe("system");
+    expect(system.content.indexOf("Bahasa Melayu")).toBeLessThan(system.content.indexOf("You are a tutor."));
+  });
+
+  it("roadmap's format example uses Malay time units in BM", async () => {
+    fetchMock.mockResolvedValue(completion('{"title":"T","steps":[{"title":"S"}]}'));
+    await roadmap(req({ topic: "Fotosintesis", language: "ms" }, h));
+    expect(sentMessages().find((m) => m.role === "user")?.content).toContain('"estimatedTime":"2 jam"');
+  });
+});
diff --git a/tests/lib/api-client.test.ts b/tests/lib/api-client.test.ts
new file mode 100644
index 0000000..422b812
--- /dev/null
+++ b/tests/lib/api-client.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { postJson, withLanguage } from "@/lib/api-client";
+import { resetLocaleMemory, setClientLocale } from "@/i18n/locale-store";
+
+function okFetch() {
+  return vi.fn().mockImplementation(async () => new Response("{}", { status: 200, headers: { "Content-Type": "application/json" } }));
+}
+
+describe("API client language", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetLocaleMemory();
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it("sends the selected UI language with every request", async () => {
+    setClientLocale("ms");
+    const fetchImpl = okFetch();
+    await postJson("/api/quiz", { topic: "Fotosintesis" }, fetchImpl);
+    expect(JSON.parse(fetchImpl.mock.calls[0][1].body)).toEqual({ topic: "Fotosintesis", language: "ms" });
+
+    setClientLocale("en");
+    await postJson("/api/roadmap", { topic: "Photosynthesis" }, fetchImpl);
+    expect(JSON.parse(fetchImpl.mock.calls[1][1].body).language).toBe("en");
+  });
+
+  it("lets an explicit language in the body win", () => {
+    expect(withLanguage({ language: "en" }, "ms")).toEqual({ language: "en" });
+  });
+});

From 8f9a8e1d92c4223e77a0b8d242775b3a4a6405ab Mon Sep 17 00:00:00 2001
From: Muhammad Aiman <84276911+aimanmalib@users.noreply.github.com>
Date: Tue, 20 Oct 2026 09:46:51 +0000
Subject: [PATCH 3/4] feat(ui): product-grade design system, light/dark themes,
 BM/EN screens

- Colour tokens in globals.css for light and dark (prefers-color-scheme
  plus a toggle that applies before first paint); Tailwind's default
  palette is switched off so every colour goes through a token. A test
  computes WCAG AA contrast for every text/background pair in both themes.
- Fixes the roadmap contrast bug: upcoming step numbers were white on
  light grey (1.2:1, Tailwind gray-200); they are now muted ink on the surface (7.7:1
  light, 8.2:1 dark).
- lucide-react icons instead of emoji, Inter + Fraunces via next/font,
  desktop nav plus a mobile bottom tab bar, BM | EN switch.
- Shared topic form with example topics, skeleton loading states,
  localised error notices with retry, empty states, focus styles,
  skip link, focus trap in the settings dialog (now portalled to body).
- Quiz: difficulty and length options, per-question feedback with the
  explanation, results with a review list. Flashcards: card grows with
  its text, end-of-deck summary. Roadmap: "Mark as done" moves the
  current step forward.
- A test fails on hard-coded words in JSX text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 package-lock.json                       |  16 +
 package.json                            |   1 +
 src/app/concepts/page.tsx               |  34 ++-
 src/app/flashcards/page.tsx             | 174 +++++++----
 src/app/globals.css                     | 379 +++++++++++++++++++++++-
 src/app/layout.tsx                      |  65 ++--
 src/app/page.tsx                        | 143 +++++++--
 src/app/progress/page.tsx               | 165 +++++++----
 src/app/quiz/page.tsx                   | 268 +++++++++++++----
 src/app/roadmap/page.tsx                | 126 +++++---
 src/components/AppHeader.tsx            |  93 ++++--
 src/components/ChatBubble.tsx           |  23 +-
 src/components/ConceptMap.tsx           |  67 +++--
 src/components/ErrorNotice.tsx          |  38 ++-
 src/components/FlashCard.tsx            |  45 +--
 src/components/GeneratingState.tsx      |  47 +++
 src/components/LanguageSwitch.tsx       |  32 ++
 src/components/LoadingSpinner.tsx       |  10 +-
 src/components/Logo.tsx                 |  19 ++
 src/components/MobileNav.tsx            |  47 +++
 src/components/ProgressChart.tsx        |  60 +++-
 src/components/QuizCard.tsx             | 124 +++++---
 src/components/RoadmapNode.tsx          | 106 ++++---
 src/components/SettingsDialog.tsx       | 189 +++++++-----
 src/components/SiteFooter.tsx           |  28 ++
 src/components/ThemeToggle.tsx          |  26 ++
 src/components/TokenUsageBar.tsx        |  11 +-
 src/components/TopicForm.tsx            |  88 ++++++
 src/components/ui/EmptyState.tsx        |  24 ++
 src/components/ui/PageHeader.tsx        |  25 ++
 src/components/ui/PageShell.tsx         |  19 ++
 src/components/ui/ProgressBar.tsx       |  15 +
 src/components/ui/SegmentedControl.tsx  |  45 +++
 src/lib/nav.ts                          |  25 ++
 src/lib/theme.ts                        |  78 +++++
 tests/components/ProgressChart.test.tsx |  11 +-
 tests/components/QuizCard.test.tsx      |   8 +-
 tests/components/RoadmapNode.test.tsx   |  25 +-
 tests/design/contrast.test.ts           |  65 ++++
 tests/i18n/no-hardcoded-text.test.ts    |  37 +++
 40 files changed, 2251 insertions(+), 550 deletions(-)
 create mode 100644 src/components/GeneratingState.tsx
 create mode 100644 src/components/LanguageSwitch.tsx
 create mode 100644 src/components/Logo.tsx
 create mode 100644 src/components/MobileNav.tsx
 create mode 100644 src/components/SiteFooter.tsx
 create mode 100644 src/components/ThemeToggle.tsx
 create mode 100644 src/components/TopicForm.tsx
 create mode 100644 src/components/ui/EmptyState.tsx
 create mode 100644 src/components/ui/PageHeader.tsx
 create mode 100644 src/components/ui/PageShell.tsx
 create mode 100644 src/components/ui/ProgressBar.tsx
 create mode 100644 src/components/ui/SegmentedControl.tsx
 create mode 100644 src/lib/nav.ts
 create mode 100644 src/lib/theme.ts
 create mode 100644 tests/design/contrast.test.ts
 create mode 100644 tests/i18n/no-hardcoded-text.test.ts

diff --git a/package-lock.json b/package-lock.json
index 2892026..e847d49 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,6 +9,7 @@
       "version": "1.1.0",
       "dependencies": {
         "clsx": "^2.1.1",
+        "lucide-react": "1.52.0",
         "next": "^16.4.2",
         "react": "^19.3.1",
         "react-dom": "^19.3.1",
@@ -6269,6 +6270,21 @@
         "yallist": "^3.0.2"
       }
     },
+    "node_modules/lucide-react": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.52.0.tgz",
+      "integrity": "sha512-TUgPtl5ZI9WgxOcbu4ckaC5B3l1qxPQrCMgb6OfUB9owx/OvSJfcf93SMgUWAxRw5/1XDfh9uI5F5iNGXCcGDQ==",
+      "license": "ISC",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/lz-string": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
diff --git a/package.json b/package.json
index 88a1b65..fd84816 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
   },
   "dependencies": {
     "clsx": "^2.1.1",
+    "lucide-react": "1.52.0",
     "next": "^16.4.2",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
diff --git a/src/app/concepts/page.tsx b/src/app/concepts/page.tsx
index 9cc81e8..4af8d55 100644
--- a/src/app/concepts/page.tsx
+++ b/src/app/concepts/page.tsx
@@ -1,23 +1,31 @@
 "use client";
+import { Info, Network } from "lucide-react";
 import { ConceptMap } from "@/components/ConceptMap";
+import { PageHeader } from "@/components/ui/PageHeader";
+import { PageShell } from "@/components/ui/PageShell";
+import { useI18n } from "@/i18n/I18nProvider";
+import type { MessageKey } from "@/i18n/messages";
 
-const sampleConcepts = [
-  { id: "1", label: "Variables", connections: ["2", "3"], mastery: 90 },
-  { id: "2", label: "Functions", connections: ["1", "4"], mastery: 75 },
-  { id: "3", label: "Data Types", connections: ["1", "5"], mastery: 85 },
-  { id: "4", label: "Control Flow", connections: ["2", "6"], mastery: 60 },
-  { id: "5", label: "Collections", connections: ["3", "6"], mastery: 45 },
-  { id: "6", label: "OOP", connections: ["4", "5"], mastery: 30 },
+/** Fixed sample data (labels come from the language files). */
+const SAMPLE: { id: string; label: MessageKey; connections: string[]; mastery: number }[] = [
+  { id: "1", label: "concepts.variables", connections: ["2", "3"], mastery: 90 },
+  { id: "2", label: "concepts.functions", connections: ["1", "4"], mastery: 75 },
+  { id: "3", label: "concepts.dataTypes", connections: ["1", "5"], mastery: 85 },
+  { id: "4", label: "concepts.controlFlow", connections: ["2", "6"], mastery: 60 },
+  { id: "5", label: "concepts.collections", connections: ["3", "6"], mastery: 45 },
+  { id: "6", label: "concepts.oop", connections: ["4", "5"], mastery: 30 },
 ];
 
 export default function ConceptsPage() {
+  const { t } = useI18n();
   return (
-    <main className="min-h-[70vh] px-4 py-6 sm:p-8 max-w-4xl mx-auto">
-      <h1 className="text-3xl font-bold mb-6">🧠 Concept Map</h1>
-      <ConceptMap concepts={sampleConcepts} title="Programming Fundamentals" />
-      <p className="text-sm text-gray-500 mt-4 text-center">
-        Sample data. The concept map is a static demo and is not generated from your sessions yet.
+    <PageShell>
+      <PageHeader icon={Network} title={t("concepts.title")} description={t("concepts.description")} />
+      <p className="mb-5 flex items-start gap-2 rounded-xl border border-line bg-surface-2 px-4 py-3 text-sm text-ink-muted">
+        <Info className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+        {t("concepts.sampleNote")}
       </p>
-    </main>
+      <ConceptMap concepts={SAMPLE.map((c) => ({ ...c, label: t(c.label) }))} title={t("concepts.mapTitle")} />
+    </PageShell>
   );
 }
diff --git a/src/app/flashcards/page.tsx b/src/app/flashcards/page.tsx
index 39ad1df..97ca381 100644
--- a/src/app/flashcards/page.tsx
+++ b/src/app/flashcards/page.tsx
@@ -1,24 +1,45 @@
 "use client";
-import { useCallback, useState } from "react";
+import { useState } from "react";
+import { GalleryVerticalEnd, RotateCcw } from "lucide-react";
 import { FlashCard } from "@/components/FlashCard";
-import { LoadingSpinner } from "@/components/LoadingSpinner";
 import { ErrorNotice } from "@/components/ErrorNotice";
+import { GeneratingState } from "@/components/GeneratingState";
+import { TopicForm } from "@/components/TopicForm";
+import { PageHeader } from "@/components/ui/PageHeader";
+import { PageShell } from "@/components/ui/PageShell";
+import { ProgressBar } from "@/components/ui/ProgressBar";
 import { useFlashcardStore, type Flashcard } from "@/store/flashcard-store";
 import type { QualityRating } from "@/lib/spaced-repetition";
 import { ApiError, postJson } from "@/lib/api-client";
 import { recordSession } from "@/lib/record-session";
+import { useI18n } from "@/i18n/I18nProvider";
+import type { MessageKey } from "@/i18n/messages";
+
+const RATINGS: { quality: QualityRating; label: MessageKey; className: string }[] = [
+  { quality: 1, label: "flashcards.rateHard", className: "border-danger/40 bg-danger-soft text-danger-ink" },
+  { quality: 3, label: "flashcards.rateGood", className: "border-accent/40 bg-warning-soft text-warning-ink" },
+  { quality: 5, label: "flashcards.rateEasy", className: "border-success/40 bg-success-soft text-success-ink" },
+];
+
+type Tally = Record<1 | 3 | 5, number>;
+const EMPTY_TALLY: Tally = { 1: 0, 3: 0, 5: 0 };
 
 export default function FlashcardsPage() {
-  const [topicInput, setTopicInput] = useState("");
+  const { t } = useI18n();
+  const store = useFlashcardStore();
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<ApiError | null>(null);
-  const store = useFlashcardStore();
+  const [lastTopic, setLastTopic] = useState("");
+  const [finished, setFinished] = useState(false);
+  const [tally, setTally] = useState<Tally>(EMPTY_TALLY);
 
-  const handleGenerate = useCallback(async () => {
-    const topic = topicInput.trim();
-    if (!topic || isLoading) return;
+  const generate = async (topic: string) => {
+    if (isLoading) return;
     setIsLoading(true);
     setError(null);
+    setLastTopic(topic);
+    setFinished(false);
+    setTally(EMPTY_TALLY);
     const started = Date.now();
     try {
       const data = await postJson<{ cards: Flashcard[]; tokens_used?: number }>("/api/flashcards", { topic, count: 10 });
@@ -29,82 +50,117 @@ export default function FlashcardsPage() {
     } finally {
       setIsLoading(false);
     }
-  }, [topicInput, isLoading, store]);
+  };
 
   const currentCard = store.cards[store.currentIndex];
-  const progress = store.getProgress();
+  const total = store.cards.length;
 
-  const rateAndNext = (quality: QualityRating) => {
+  const rateAndNext = (quality: 1 | 3 | 5) => {
     store.rate(quality);
-    store.next();
+    setTally((prev) => ({ ...prev, [quality]: prev[quality] + 1 }));
+    if (store.currentIndex >= total - 1) setFinished(true);
+    else store.next();
+  };
+
+  const newTopic = () => {
+    store.setCards([], "");
+    setFinished(false);
+  };
+
+  const reviewAgain = () => {
+    store.reset();
+    setTally(EMPTY_TALLY);
+    setFinished(false);
   };
 
   return (
-    <main className="min-h-[70vh] px-4 py-6 sm:p-8 max-w-4xl mx-auto">
-      <h1 className="text-3xl font-bold mb-6">🃏 Flashcards</h1>
+    <PageShell width="narrow">
+      <PageHeader icon={GalleryVerticalEnd} title={t("flashcards.title")} description={t("flashcards.description")} />
 
-      {store.cards.length === 0 && !isLoading && (
+      {total === 0 && !isLoading && (
         <>
-          <div className="bg-white rounded-xl shadow-sm p-6 max-w-md mx-auto">
-            <h2 className="font-semibold mb-4">Choose a topic</h2>
-            <input
-              type="text"
-              value={topicInput}
-              onChange={(e) => setTopicInput(e.target.value)}
-              placeholder="e.g., Data Structures, Biology..."
-              className="w-full px-4 py-2 border rounded-lg mb-4 text-base"
-              onKeyDown={(e) => e.key === "Enter" && handleGenerate()}
-            />
-            <button onClick={handleGenerate} className="w-full bg-emerald-500 text-white py-2 rounded-lg hover:bg-emerald-600">
-              Generate Flashcards
-            </button>
+          <TopicForm
+            title={t("flashcards.formTitle")}
+            placeholder={t("flashcards.placeholder")}
+            submitLabel={t("flashcards.generate")}
+            busy={isLoading}
+            defaultTopic={lastTopic}
+            onSubmit={generate}
+          />
+          <div className="mx-auto max-w-2xl">
+            <ErrorNotice error={error} onRetry={lastTopic ? () => generate(lastTopic) : undefined} />
           </div>
-          <ErrorNotice error={error} />
         </>
       )}
 
-      {isLoading && <LoadingSpinner size="lg" label="Generating flashcards..." />}
+      {isLoading && <GeneratingState shape="cards" label={t("flashcards.loading")} hint={t("flashcards.loadingHint")} />}
 
-      {currentCard && (
-        <div className="max-w-md mx-auto">
-          <p className="text-sm text-gray-500 mb-4 text-center">
-            {Math.min(progress.reviewed + 1, progress.total)} / {progress.total}
-          </p>
+      {currentCard && !finished && (
+        <div className="mx-auto max-w-2xl">
+          <div className="mb-4 flex items-center gap-3">
+            <p className="min-w-0 flex-1 text-sm font-medium text-ink-muted">
+              {t("flashcards.cardOf", { current: store.currentIndex + 1, total })}
+            </p>
+            <button type="button" onClick={newTopic} className="btn btn-ghost btn-sm">
+              {t("common.newTopic")}
+            </button>
+          </div>
+          <div className="mb-5">
+            <ProgressBar value={store.currentIndex} max={total} label={t("flashcards.cardOf", { current: store.currentIndex + 1, total })} />
+          </div>
           <FlashCard
+            key={currentCard.id}
             front={currentCard.front}
             back={currentCard.back}
             isFlipped={store.isFlipped}
             onFlip={store.flip}
             topic={currentCard.topic}
           />
-          {store.isFlipped && (
-            <div className="flex justify-center gap-2 mt-6">
-              {([1, 3, 5] as const).map((q) => (
-                <button
-                  key={q}
-                  onClick={() => rateAndNext(q)}
-                  className={`px-4 py-2 rounded-lg text-sm ${
-                    q === 1 ? "bg-red-100 text-red-700" : q === 3 ? "bg-yellow-100 text-yellow-700" : "bg-green-100 text-green-700"
-                  }`}
-                >
-                  {q === 1 ? "Hard" : q === 3 ? "Good" : "Easy"}
-                </button>
-              ))}
-            </div>
-          )}
-          <div className="mt-6 text-center">
-            <button
-              onClick={() => {
-                store.setCards([], "");
-                setTopicInput("");
-              }}
-              className="text-sm text-gray-500 underline hover:text-gray-700"
-            >
-              New topic
+          <div className="mt-6 min-h-[5.5rem]">
+            {store.isFlipped && (
+              <div role="group" aria-label={t("flashcards.rateQuestion")}>
+                <p className="mb-3 text-center text-sm font-medium text-ink-muted">{t("flashcards.rateQuestion")}</p>
+                <div className="grid grid-cols-3 gap-2">
+                  {RATINGS.map((r) => (
+                    <button
+                      key={r.quality}
+                      type="button"
+                      onClick={() => rateAndNext(r.quality as 1 | 3 | 5)}
+                      className={`btn border ${r.className} hover:brightness-95`}
+                    >
+                      {t(r.label)}
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+
+      {finished && (
+        <div className="card mx-auto max-w-2xl p-6 text-center sm:p-8">
+          <h2 className="font-display text-2xl font-semibold text-ink">{t("flashcards.completeTitle")}</h2>
+          <p className="mt-2 text-[0.9375rem] text-ink-muted">{t("flashcards.completeDesc", { total, topic: store.topic })}</p>
+          <dl className="mt-6 grid grid-cols-3 gap-2">
+            {RATINGS.map((r) => (
+              <div key={r.quality} className={`rounded-xl border px-2 py-3 ${r.className}`}>
+                <dt className="text-xs font-semibold">{t(r.label)}</dt>
+                <dd className="mt-1 font-display text-2xl font-semibold">{tally[r.quality as 1 | 3 | 5]}</dd>
+              </div>
+            ))}
+          </dl>
+          <div className="mt-6 flex flex-col gap-2 sm:flex-row sm:justify-center">
+            <button type="button" onClick={reviewAgain} className="btn btn-secondary">
+              <RotateCcw className="h-4 w-4" aria-hidden="true" />
+              {t("flashcards.reviewAgain")}
+            </button>
+            <button type="button" onClick={newTopic} className="btn btn-primary">
+              {t("common.newTopic")}
             </button>
           </div>
         </div>
       )}
-    </main>
+    </PageShell>
   );
 }
diff --git a/src/app/globals.css b/src/app/globals.css
index ab3d907..fd7cb30 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -1,19 +1,384 @@
-@import 'tailwindcss';
+@import "tailwindcss";
 
 /*
-  The default border color has changed to `currentcolor` in Tailwind CSS v4,
-  so we've added these compatibility styles to make sure everything still
-  looks the same as it did with Tailwind CSS v3.
+  LearnPath design tokens.
 
-  If we ever want to remove these styles, we need to add an explicit border
-  color utility to any element that depends on these defaults.
+  Every colour in the UI comes from the variables below; components use the
+  Tailwind utilities generated from them (bg-surface, text-ink-muted, ...).
+  Tailwind's default palette is switched off so a stray `text-gray-400`
+  cannot slip in and break dark mode or contrast.
+
+  Text/background pairs are checked for WCAG AA (4.5:1) in both themes.
+  Light is the default; dark applies when the system prefers it (and the
+  visitor has not picked light), or when the visitor picks dark.
 */
+
+:root {
+  color-scheme: light;
+  --canvas: #f6f6f2;
+  --surface: #ffffff;
+  --surface-2: #eeefe9;
+  --surface-raised: #ffffff;
+  --line: #e1e3dc;
+  --line-strong: #8f978f;
+  --ink: #16211e;
+  --ink-muted: #4a5651;
+  --ink-subtle: #5d6964;
+  --brand: #0c6b60;
+  --brand-hover: #0a564d;
+  --on-brand: #ffffff;
+  --brand-soft: #e1f0ec;
+  --brand-ink: #0a564d;
+  --accent: #b4540a;
+  --accent-soft: #fbeedb;
+  --accent-ink: #8a3f06;
+  --success: #1b7339;
+  --success-soft: #e3f2e8;
+  --success-ink: #165f2f;
+  --danger: #b42318;
+  --danger-soft: #fcebe9;
+  --danger-ink: #9a1d13;
+  --warning-soft: #fdf3dd;
+  --warning-ink: #7a4305;
+  --focus: #0c6b60;
+  --overlay: rgb(14 22 20 / 0.45);
+  --shadow-color: 150 10% 20%;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+    --canvas: #0d1312;
+    --surface: #141c1a;
+    --surface-2: #1b2522;
+    --surface-raised: #2b3834;
+    --line: #26322e;
+    --line-strong: #6b7a74;
+    --ink: #e7edea;
+    --ink-muted: #a8b5b0;
+    --ink-subtle: #93a29c;
+    --brand: #3cc2ad;
+    --brand-hover: #62d3c1;
+    --on-brand: #04201b;
+    --brand-soft: #11302a;
+    --brand-ink: #7fdccd;
+    --accent: #f0a640;
+    --accent-soft: #33240f;
+    --accent-ink: #f5c27a;
+    --success: #4cc27a;
+    --success-soft: #11291a;
+    --success-ink: #84d9a4;
+    --danger: #ef7466;
+    --danger-soft: #341614;
+    --danger-ink: #f6a097;
+    --warning-soft: #2f2410;
+    --warning-ink: #f1c46f;
+    --focus: #62d3c1;
+    --overlay: rgb(0 0 0 / 0.6);
+    --shadow-color: 0 0% 0%;
+  }
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --canvas: #0d1312;
+  --surface: #141c1a;
+  --surface-2: #1b2522;
+  --surface-raised: #2b3834;
+  --line: #26322e;
+  --line-strong: #6b7a74;
+  --ink: #e7edea;
+  --ink-muted: #a8b5b0;
+  --ink-subtle: #93a29c;
+  --brand: #3cc2ad;
+  --brand-hover: #62d3c1;
+  --on-brand: #04201b;
+  --brand-soft: #11302a;
+  --brand-ink: #7fdccd;
+  --accent: #f0a640;
+  --accent-soft: #33240f;
+  --accent-ink: #f5c27a;
+  --success: #4cc27a;
+  --success-soft: #11291a;
+  --success-ink: #84d9a4;
+  --danger: #ef7466;
+  --danger-soft: #341614;
+  --danger-ink: #f6a097;
+  --warning-soft: #2f2410;
+  --warning-ink: #f1c46f;
+  --focus: #62d3c1;
+  --overlay: rgb(0 0 0 / 0.6);
+  --shadow-color: 0 0% 0%;
+}
+
+@theme {
+  --color-*: initial;
+}
+
+@theme inline {
+  --color-white: #ffffff;
+  --color-canvas: var(--canvas);
+  --color-surface: var(--surface);
+  --color-surface-2: var(--surface-2);
+  --color-surface-raised: var(--surface-raised);
+  --color-line: var(--line);
+  --color-line-strong: var(--line-strong);
+  --color-ink: var(--ink);
+  --color-ink-muted: var(--ink-muted);
+  --color-ink-subtle: var(--ink-subtle);
+  --color-brand: var(--brand);
+  --color-brand-hover: var(--brand-hover);
+  --color-on-brand: var(--on-brand);
+  --color-brand-soft: var(--brand-soft);
+  --color-brand-ink: var(--brand-ink);
+  --color-accent: var(--accent);
+  --color-accent-soft: var(--accent-soft);
+  --color-accent-ink: var(--accent-ink);
+  --color-success: var(--success);
+  --color-success-soft: var(--success-soft);
+  --color-success-ink: var(--success-ink);
+  --color-danger: var(--danger);
+  --color-danger-soft: var(--danger-soft);
+  --color-danger-ink: var(--danger-ink);
+  --color-warning-soft: var(--warning-soft);
+  --color-warning-ink: var(--warning-ink);
+  --color-focus: var(--focus);
+
+  --font-sans: var(--font-inter), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-display: var(--font-fraunces), ui-serif, Georgia, "Times New Roman", serif;
+  --font-mono: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+
+  --text-display: clamp(2.125rem, 1.55rem + 2.6vw, 3.5rem);
+  --text-display--line-height: 1.08;
+  --text-display--letter-spacing: -0.02em;
+  --text-title: clamp(1.625rem, 1.35rem + 1.2vw, 2.25rem);
+  --text-title--line-height: 1.15;
+  --text-title--letter-spacing: -0.015em;
+
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.06), 0 1px 1px hsl(var(--shadow-color) / 0.04);
+  --shadow-raised: 0 10px 30px -12px hsl(var(--shadow-color) / 0.25), 0 2px 6px -2px hsl(var(--shadow-color) / 0.08);
+}
+
 @layer base {
   *,
   ::after,
   ::before,
   ::backdrop,
   ::file-selector-button {
-    border-color: var(--color-gray-200, currentcolor);
+    border-color: var(--line);
+  }
+
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+    overflow-x: clip;
+  }
+
+  body {
+    background: var(--canvas);
+    color: var(--ink);
+    font-family: var(--font-sans);
+    font-feature-settings: "cv11", "ss01";
+    -webkit-font-smoothing: antialiased;
+    overflow-x: clip;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+
+  ::selection {
+    background: var(--brand-soft);
+    color: var(--ink);
+  }
+
+  input::placeholder {
+    color: var(--ink-subtle);
+    opacity: 1;
+  }
+}
+
+@layer components {
+  .card {
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 1rem;
+    box-shadow: var(--shadow-card);
+  }
+
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    min-height: 2.75rem;
+    padding: 0.625rem 1.125rem;
+    border-radius: 0.75rem;
+    font-weight: 600;
+    font-size: 0.9375rem;
+    line-height: 1.25rem;
+    border: 1px solid transparent;
+    transition:
+      background-color 150ms ease,
+      border-color 150ms ease,
+      color 150ms ease,
+      box-shadow 150ms ease;
+    -webkit-tap-highlight-color: transparent;
+    cursor: pointer;
+  }
+  .btn:disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+  .btn-primary {
+    background: var(--brand);
+    color: var(--on-brand);
+    box-shadow: var(--shadow-card);
+  }
+  @media (hover: hover) {
+    .btn-primary:not(:disabled):hover {
+      background: var(--brand-hover);
+    }
+  }
+  .btn-secondary {
+    background: var(--surface);
+    color: var(--ink);
+    border-color: var(--line-strong);
   }
+  @media (hover: hover) {
+    .btn-secondary:not(:disabled):hover {
+      background: var(--surface-2);
+    }
+  }
+  .btn-ghost {
+    background: transparent;
+    color: var(--ink-muted);
+  }
+  @media (hover: hover) {
+    .btn-ghost:not(:disabled):hover {
+      background: var(--surface-2);
+      color: var(--ink);
+    }
+  }
+  .btn-sm {
+    min-height: 2.25rem;
+    padding: 0.375rem 0.75rem;
+    font-size: 0.875rem;
+    border-radius: 0.625rem;
+  }
+
+  .field {
+    width: 100%;
+    min-height: 2.875rem;
+    padding: 0.625rem 0.875rem;
+    border-radius: 0.75rem;
+    border: 1px solid var(--line-strong);
+    background: var(--surface);
+    color: var(--ink);
+    font-size: 1rem; /* 16px keeps iOS Safari from zooming on focus */
+    transition:
+      border-color 150ms ease,
+      box-shadow 150ms ease;
+  }
+  .field:focus {
+    outline: none;
+    border-color: var(--brand);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--brand) 25%, transparent);
+  }
+
+  select.field {
+    -webkit-appearance: none;
+    appearance: none;
+    padding-right: 2.5rem;
+    background-image: linear-gradient(45deg, transparent 50%, var(--ink-muted) 50%),
+      linear-gradient(135deg, var(--ink-muted) 50%, transparent 50%);
+    background-position:
+      calc(100% - 1.15rem) 50%,
+      calc(100% - 0.8rem) 50%;
+    background-size: 0.35rem 0.35rem;
+    background-repeat: no-repeat;
+  }
+
+  .label {
+    display: block;
+    margin-bottom: 0.375rem;
+    font-size: 0.875rem;
+    font-weight: 600;
+    color: var(--ink);
+  }
+
+  .eyebrow {
+    font-size: 0.75rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--brand-ink);
+  }
+
+  /* Shown only in the light or only in the dark theme (theme toggle icons). */
+  .only-dark {
+    display: none;
+  }
+  :root[data-theme="dark"] .only-dark {
+    display: inline-block;
+  }
+  :root[data-theme="dark"] .only-light {
+    display: none;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) .only-dark {
+      display: inline-block;
+    }
+    :root:not([data-theme="light"]) .only-light {
+      display: none;
+    }
+  }
+
+  .skeleton {
+    background: linear-gradient(90deg, var(--surface-2) 0%, var(--line) 50%, var(--surface-2) 100%);
+    background-size: 200% 100%;
+    animation: shimmer 1.4s ease-in-out infinite;
+    border-radius: 0.5rem;
+  }
+}
+
+@keyframes shimmer {
+  from {
+    background-position: 100% 0;
+  }
+  to {
+    background-position: -100% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  ::before,
+  ::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
+/* Flashcard flip. Prefixed backface-visibility for older WebKit. */
+.flip-scene {
+  perspective: 1200px;
+}
+.flip-card {
+  display: grid;
+  transform-style: preserve-3d;
+  transition: transform 500ms cubic-bezier(0.2, 0.7, 0.2, 1);
+}
+.flip-card[data-flipped="true"] {
+  transform: rotateY(180deg);
+}
+.flip-face {
+  grid-area: 1 / 1;
+  -webkit-backface-visibility: hidden;
+  backface-visibility: hidden;
+}
+.flip-back {
+  transform: rotateY(180deg);
 }
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index dc44e88..9f55ffa 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,27 +1,56 @@
-import type { Metadata } from "next";
+import type { Metadata, Viewport } from "next";
+import { Fraunces, Inter } from "next/font/google";
 import { AppHeader } from "@/components/AppHeader";
+import { MobileNav } from "@/components/MobileNav";
+import { SiteFooter } from "@/components/SiteFooter";
+import { I18nProvider } from "@/i18n/I18nProvider";
+import { translate } from "@/i18n/messages";
+import { getRequestLocale } from "@/i18n/server";
+import { THEME_INIT_SCRIPT } from "@/lib/theme";
 import "./globals.css";
 
-export const metadata: Metadata = {
-  title: "LearnPath — Adaptive Learning",
-  description: "AI-generated quizzes, flashcards and learning roadmaps with any OpenAI-compatible LLM. Bring your own API key.",
+const inter = Inter({ subsets: ["latin"], variable: "--font-inter", display: "swap" });
+const fraunces = Fraunces({
+  subsets: ["latin"],
+  variable: "--font-fraunces",
+  display: "swap",
+  axes: ["opsz", "SOFT"],
+});
+
+export async function generateMetadata(): Promise<Metadata> {
+  const locale = await getRequestLocale();
+  return {
+    title: translate(locale, "meta.title"),
+    description: translate(locale, "meta.description"),
+  };
+}
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  viewportFit: "cover",
+  themeColor: [
+    { media: "(prefers-color-scheme: light)", color: "#f6f6f2" },
+    { media: "(prefers-color-scheme: dark)", color: "#0d1312" },
+  ],
 };
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const locale = await getRequestLocale();
   return (
-    <html lang="en">
-      <body className="bg-gray-50 text-gray-900 antialiased">
-        <AppHeader />
-        {children}
-        <footer className="mx-auto max-w-4xl px-4 pb-8 pt-4 text-center text-xs text-gray-400 sm:px-8">
-          <a href="https://github.com/aimanmalib/learnpath" className="underline hover:text-gray-600">
-            Source on GitHub
-          </a>
-          {" · "}Built by{" "}
-          <a href="https://sasateguh.com" className="underline hover:text-gray-600">
-            Sasa Teguh
-          </a>
-        </footer>
+    <html lang={locale} className={`${inter.variable} ${fraunces.variable}`} suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
+      </head>
+      <body className="min-h-dvh">
+        <I18nProvider initialLocale={locale}>
+          <AppHeader />
+          <div className="pb-[calc(4.5rem+env(safe-area-inset-bottom))] md:pb-0">
+            {children}
+            <SiteFooter />
+          </div>
+          <MobileNav />
+        </I18nProvider>
       </body>
     </html>
   );
diff --git a/src/app/page.tsx b/src/app/page.tsx
index ea83fc9..7d35ad2 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,41 +1,122 @@
 "use client";
 import Link from "next/link";
+import { ArrowRight, Info, KeyRound } from "lucide-react";
+import { PageShell } from "@/components/ui/PageShell";
+import { useI18n } from "@/i18n/I18nProvider";
+import { openSettings } from "@/lib/api-client";
+import { NAV_ITEMS } from "@/lib/nav";
+import type { MessageKey } from "@/i18n/messages";
 
-const features = [
-  { href: "/quiz", icon: "📝", title: "Adaptive Quiz", desc: "AI-generated quizzes that adapt to your level" },
-  { href: "/flashcards", icon: "🃏", title: "Flashcards", desc: "Spaced repetition for long-term retention" },
-  { href: "/roadmap", icon: "🗺️", title: "Learning Roadmap", desc: "Personalized learning paths" },
-  { href: "/progress", icon: "📊", title: "Progress Tracker", desc: "Sessions from this visit, by topic" },
-  { href: "/concepts", icon: "🧠", title: "Concept Map", desc: "Explore knowledge connections (sample data)" },
+const FEATURES: { href: string; title: MessageKey; desc: MessageKey; sample?: boolean }[] = [
+  { href: "/quiz", title: "home.quizTitle", desc: "home.quizDesc" },
+  { href: "/flashcards", title: "home.flashcardsTitle", desc: "home.flashcardsDesc" },
+  { href: "/roadmap", title: "home.roadmapTitle", desc: "home.roadmapDesc" },
+  { href: "/progress", title: "home.progressTitle", desc: "home.progressDesc" },
+  { href: "/concepts", title: "home.conceptsTitle", desc: "home.conceptsDesc", sample: true },
 ];
 
+const STEPS: { title: MessageKey; desc: MessageKey }[] = [
+  { title: "home.how1Title", desc: "home.how1Desc" },
+  { title: "home.how2Title", desc: "home.how2Desc" },
+  { title: "home.how3Title", desc: "home.how3Desc" },
+];
+
+function iconFor(href: string) {
+  return NAV_ITEMS.find((item) => item.href === href)!.icon;
+}
+
 export default function Home() {
+  const { t } = useI18n();
+
   return (
-    <main className="min-h-[70vh] px-4 py-8 sm:p-8 max-w-4xl mx-auto">
-      <div className="text-center mb-12">
-        <h1 className="text-3xl sm:text-4xl font-bold mb-2">🎓 LearnPath</h1>
-        <p className="text-lg text-gray-600">Adaptive learning with any OpenAI-compatible LLM</p>
-        <p className="text-sm text-gray-400 mt-1">AI-driven quizzes, flashcards, and personalized roadmaps</p>
-      </div>
-
-      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-        {features.map((f) => (
-          <Link key={f.href} href={f.href}>
-            <div className="bg-white rounded-xl shadow-md hover:shadow-lg transition-shadow p-6 cursor-pointer">
-              <span className="text-3xl">{f.icon}</span>
-              <h2 className="text-lg font-semibold mt-3">{f.title}</h2>
-              <p className="text-sm text-gray-500 mt-1">{f.desc}</p>
+    <PageShell width="wide">
+      <section className="grid items-center gap-10 pb-12 pt-2 sm:pb-16 lg:grid-cols-[1.15fr_0.85fr] lg:gap-16 lg:pt-6">
+        <div>
+          <p className="eyebrow">{t("home.eyebrow")}</p>
+          <h1 className="mt-4 max-w-[18ch] font-display text-display font-semibold text-ink text-balance">{t("home.title")}</h1>
+          <p className="mt-5 max-w-xl text-[1.0625rem] leading-relaxed text-ink-muted">{t("home.lead")}</p>
+          <div className="mt-8 flex flex-col gap-3 sm:flex-row">
+            <Link href="/quiz" className="btn btn-primary">
+              {t("home.ctaQuiz")}
+              <ArrowRight className="h-4 w-4" aria-hidden="true" />
+            </Link>
+            <Link href="/roadmap" className="btn btn-secondary">
+              {t("home.ctaRoadmap")}
+            </Link>
+          </div>
+        </div>
+
+        <ol className="card relative p-6 sm:p-8" aria-label={t("home.howTitle")}>
+          <p className="mb-6 text-sm font-semibold text-ink-muted">{t("home.howTitle")}</p>
+          {STEPS.map((step, i) => (
+            <li key={step.title} className="relative flex gap-4 pb-7 last:pb-0">
+              {i < STEPS.length - 1 && (
+                <span aria-hidden="true" className="absolute left-[17px] top-10 bottom-1 w-px border-l-2 border-dashed border-line" />
+              )}
+              <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-brand text-sm font-bold text-on-brand">
+                {i + 1}
+              </span>
+              <div className="pt-1">
+                <p className="font-semibold text-ink">{t(step.title)}</p>
+                <p className="mt-1 text-sm leading-relaxed text-ink-muted">{t(step.desc)}</p>
+              </div>
+            </li>
+          ))}
+        </ol>
+      </section>
+
+      <section aria-labelledby="features-title">
+        <h2 id="features-title" className="font-display text-2xl font-semibold text-ink">
+          {t("home.featuresTitle")}
+        </h2>
+        <ul className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {FEATURES.map((f) => {
+            const Icon = iconFor(f.href);
+            return (
+              <li key={f.href}>
+                <Link
+                  href={f.href}
+                  className="card group flex h-full flex-col p-5 transition-[border-color,box-shadow] hover:border-brand/50 hover:shadow-raised sm:p-6"
+                >
+                  <div className="flex items-center justify-between">
+                    <span className="flex h-11 w-11 items-center justify-center rounded-xl bg-brand-soft text-brand-ink">
+                      <Icon className="h-[22px] w-[22px]" aria-hidden="true" />
+                    </span>
+                    {f.sample && (
+                      <span className="rounded-full bg-surface-2 px-2.5 py-1 text-xs font-medium text-ink-muted">
+                        {t("common.sampleData")}
+                      </span>
+                    )}
+                  </div>
+                  <h3 className="mt-4 text-lg font-semibold text-ink">{t(f.title)}</h3>
+                  <p className="mt-1.5 flex-1 text-sm leading-relaxed text-ink-muted">{t(f.desc)}</p>
+                  <ArrowRight
+                    className="mt-4 h-4 w-4 text-ink-subtle transition-transform group-hover:translate-x-1 group-hover:text-brand-ink"
+                    aria-hidden="true"
+                  />
+                </Link>
+              </li>
+            );
+          })}
+          <li className="sm:col-span-2 lg:col-span-1">
+            <div className="flex h-full flex-col rounded-2xl border border-dashed border-line-strong p-5 sm:p-6">
+              <span className="flex h-11 w-11 items-center justify-center rounded-xl bg-accent-soft text-accent-ink">
+                <KeyRound className="h-[22px] w-[22px]" aria-hidden="true" />
+              </span>
+              <h3 className="mt-4 text-lg font-semibold text-ink">{t("home.byokTitle")}</h3>
+              <p className="mt-1.5 flex-1 text-sm leading-relaxed text-ink-muted">{t("home.byokDesc")}</p>
+              <button type="button" onClick={() => openSettings()} className="btn btn-secondary btn-sm mt-4 self-start">
+                {t("home.byokCta")}
+              </button>
             </div>
-          </Link>
-        ))}
-      </div>
-
-      <div className="mt-12 text-center text-sm text-gray-500">
-        <p>
-          Bring your own API key: OpenAI, OpenRouter, Groq, DeepSeek, Together AI, Mistral or Xiaomi MiMo. Self-hosted
-          copies can also use Ollama, llama.cpp or any OpenAI-compatible endpoint.
-        </p>
-      </div>
-    </main>
+          </li>
+        </ul>
+      </section>
+
+      <p className="mt-10 flex items-start gap-2 text-sm text-ink-subtle">
+        <Info className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+        {t("home.honestNote")}
+      </p>
+    </PageShell>
   );
 }
diff --git a/src/app/progress/page.tsx b/src/app/progress/page.tsx
index 4917984..68b5791 100644
--- a/src/app/progress/page.tsx
+++ b/src/app/progress/page.tsx
@@ -1,80 +1,127 @@
 "use client";
+import Link from "next/link";
+import { ArrowRight, ChartColumn, Clock, Coins, Layers } from "lucide-react";
 import { ProgressChart } from "@/components/ProgressChart";
-import { useProgressStore } from "@/store/progress-store";
+import { EmptyState } from "@/components/ui/EmptyState";
+import { PageHeader } from "@/components/ui/PageHeader";
+import { PageShell } from "@/components/ui/PageShell";
+import { useProgressStore, type StudySession } from "@/store/progress-store";
+import { useI18n } from "@/i18n/I18nProvider";
+import type { MessageKey } from "@/i18n/messages";
+
+const DAY_KEYS: Record<string, MessageKey> = {
+  Sun: "days.sun",
+  Mon: "days.mon",
+  Tue: "days.tue",
+  Wed: "days.wed",
+  Thu: "days.thu",
+  Fri: "days.fri",
+  Sat: "days.sat",
+};
+
+const FEATURE_KEYS: Record<StudySession["feature"], MessageKey> = {
+  quiz: "progress.featureQuiz",
+  flashcards: "progress.featureFlashcards",
+  roadmap: "progress.featureRoadmap",
+  concepts: "progress.featureConcepts",
+  chat: "progress.featureChat",
+};
 
 export default function ProgressPage() {
+  const { t, intl } = useI18n();
   const store = useProgressStore();
   const topicProgress = store.getTopicProgress();
   const weeklyStats = store.getWeeklyStats();
-  const tokensByFeature = store.sessions.reduce<Record<string, number>>((acc, s) => {
+  const tokensByFeature = store.sessions.reduce<Partial<Record<StudySession["feature"], number>>>((acc, s) => {
     acc[s.feature] = (acc[s.feature] || 0) + s.tokensUsed;
     return acc;
   }, {});
+  const maxTokens = Math.max(1, ...Object.values(tokensByFeature).map((n) => n ?? 0));
+  const nf = new Intl.NumberFormat(intl);
+  const hasScore = (topic: string) => store.sessions.some((s) => s.topic === topic && s.score !== undefined);
 
-  return (
-    <main className="min-h-[70vh] px-4 py-6 sm:p-8 max-w-4xl mx-auto">
-      <h1 className="text-3xl font-bold mb-2">📊 Progress Dashboard</h1>
-      <p className="text-sm text-gray-500 mb-6">
-        Quizzes, flashcard sets and roadmaps you create during this visit. Nothing is saved after you close the tab.
-      </p>
+  const stats = [
+    { icon: Layers, label: t("progress.sessions"), value: nf.format(store.sessions.length) },
+    { icon: Clock, label: t("progress.studyTime"), value: t("progress.studyTimeValue", { minutes: nf.format(Math.round(store.totalStudyTime / 60000)) }) },
+    { icon: Coins, label: t("progress.tokens"), value: nf.format(store.totalTokens) },
+  ];
 
-      <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-8">
-        <div className="bg-white rounded-xl shadow-sm p-4 text-center">
-          <p className="text-2xl font-bold text-blue-500">{store.sessions.length}</p>
-          <p className="text-sm text-gray-500">Total Sessions</p>
-        </div>
-        <div className="bg-white rounded-xl shadow-sm p-4 text-center">
-          <p className="text-2xl font-bold text-green-500">
-            {Math.round(store.totalStudyTime / 60000)}m
-          </p>
-          <p className="text-sm text-gray-500">Study Time</p>
-        </div>
-        <div className="bg-white rounded-xl shadow-sm p-4 text-center">
-          <p className="text-2xl font-bold text-purple-500">
-            {(store.totalTokens / 1000).toFixed(1)}K
-          </p>
-          <p className="text-sm text-gray-500">Tokens Used</p>
-        </div>
-      </div>
+  return (
+    <PageShell>
+      <PageHeader icon={ChartColumn} title={t("progress.title")} description={t("progress.description")} />
 
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-        <ProgressChart
-          data={weeklyStats.map((s) => ({ label: s.day, value: s.sessions }))}
-          title="Weekly Activity"
+      {store.sessions.length === 0 ? (
+        <EmptyState
+          icon={ChartColumn}
+          title={t("progress.emptyTitle")}
+          description={t("progress.emptyDesc")}
+          action={
+            <Link href="/quiz" className="btn btn-primary">
+              {t("progress.emptyCta")}
+              <ArrowRight className="h-4 w-4" aria-hidden="true" />
+            </Link>
+          }
         />
+      ) : (
+        <>
+          <dl className="grid grid-cols-1 gap-3 sm:grid-cols-3 sm:gap-4">
+            {stats.map((s) => (
+              <div key={s.label} className="card flex items-center gap-4 p-5">
+                <span className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-brand-soft text-brand-ink">
+                  <s.icon className="h-5 w-5" aria-hidden="true" />
+                </span>
+                <div>
+                  <dt className="text-sm text-ink-muted">{s.label}</dt>
+                  <dd className="font-display text-2xl font-semibold tabular-nums text-ink">{s.value}</dd>
+                </div>
+              </div>
+            ))}
+          </dl>
+
+          <div className="mt-6 grid grid-cols-1 gap-4 md:grid-cols-2">
+            <ProgressChart
+              data={weeklyStats.map((s) => ({ label: t(DAY_KEYS[s.day] ?? "days.sun"), value: s.sessions }))}
+              title={t("progress.weekly")}
+              caption={t("progress.weeklyCaption")}
+            />
 
-        <div className="bg-white rounded-xl shadow-sm p-4">
-          <h3 className="text-sm font-semibold text-gray-700 mb-3">Tokens used by feature</h3>
-          {Object.keys(tokensByFeature).length === 0 ? (
-            <p className="text-sm text-gray-500">Nothing yet. Generate a quiz, flashcards or a roadmap to see usage here.</p>
-          ) : (
-            <ul className="space-y-2">
-              {Object.entries(tokensByFeature).map(([feature, tokens]) => (
-                <li key={feature} className="flex items-center justify-between text-sm">
-                  <span className="capitalize text-gray-600">{feature}</span>
-                  <span className="font-medium tabular-nums">{tokens.toLocaleString("en")}</span>
+            <section className="card p-5">
+              <h3 className="text-sm font-semibold text-ink">{t("progress.byFeature")}</h3>
+              <ul className="mt-5 space-y-4">
+                {Object.entries(tokensByFeature).map(([feature, tokens]) => (
+                  <li key={feature}>
+                    <div className="flex items-center justify-between text-sm">
+                      <span className="text-ink-muted">{t(FEATURE_KEYS[feature as StudySession["feature"]])}</span>
+                      <span className="font-semibold tabular-nums text-ink">{nf.format(tokens ?? 0)}</span>
+                    </div>
+                    <div className="mt-1.5 h-2 overflow-hidden rounded-full bg-surface-2" aria-hidden="true">
+                      <div className="h-full rounded-full bg-brand" style={{ width: `${((tokens ?? 0) / maxTokens) * 100}%` }} />
+                    </div>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          </div>
+
+          <section className="mt-8" aria-labelledby="topics-title">
+            <h2 id="topics-title" className="mb-4 font-display text-xl font-semibold text-ink">
+              {t("progress.topics")}
+            </h2>
+            <ul className="grid grid-cols-1 gap-3 md:grid-cols-2">
+              {Object.entries(topicProgress).map(([topic, data]) => (
+                <li key={topic} className="card p-4">
+                  <p className="font-semibold text-ink">{topic}</p>
+                  <p className="mt-0.5 text-sm text-ink-muted">
+                    {hasScore(topic)
+                      ? t("progress.topicLine", { sessions: data.sessions, score: data.avgScore })
+                      : t("progress.topicLineNoScore", { sessions: data.sessions })}
+                  </p>
                 </li>
               ))}
             </ul>
-          )}
-        </div>
-      </div>
-
-      {Object.keys(topicProgress).length > 0 && (
-        <div className="mt-8">
-          <h2 className="text-lg font-semibold mb-4">Topic Progress</h2>
-          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-            {Object.entries(topicProgress).map(([topic, data]) => (
-              <div key={topic} className="bg-white rounded-xl shadow-sm p-4">
-                <h3 className="font-medium">{topic}</h3>
-                <p className="text-sm text-gray-500">
-                  {data.sessions} sessions • Avg: {data.avgScore}%
-                </p>
-              </div>
-            ))}
-          </div>
-        </div>
+          </section>
+        </>
       )}
-    </main>
+    </PageShell>
   );
 }
diff --git a/src/app/quiz/page.tsx b/src/app/quiz/page.tsx
index c36003c..3504f37 100644
--- a/src/app/quiz/page.tsx
+++ b/src/app/quiz/page.tsx
@@ -1,22 +1,38 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
+import { clsx } from "clsx";
+import { ArrowRight, Check, ListChecks, RotateCcw, X } from "lucide-react";
 import { QuizCard } from "@/components/QuizCard";
-import { LoadingSpinner } from "@/components/LoadingSpinner";
 import { ErrorNotice } from "@/components/ErrorNotice";
+import { GeneratingState } from "@/components/GeneratingState";
+import { TopicForm } from "@/components/TopicForm";
+import { PageHeader } from "@/components/ui/PageHeader";
+import { PageShell } from "@/components/ui/PageShell";
+import { ProgressBar } from "@/components/ui/ProgressBar";
+import { SegmentedControl } from "@/components/ui/SegmentedControl";
 import { useQuizState } from "@/hooks/useQuizState";
 import { recordSession } from "@/lib/record-session";
+import { useI18n } from "@/i18n/I18nProvider";
+
+type Difficulty = "easy" | "medium" | "hard";
 
 export default function QuizPage() {
-  const [topicInput, setTopicInput] = useState("");
-  const [startedAt, setStartedAt] = useState(0);
+  const { t } = useI18n();
   const quiz = useQuizState();
+  const [difficulty, setDifficulty] = useState<Difficulty>("medium");
+  const [count, setCount] = useState(5);
+  const [selected, setSelected] = useState<number | undefined>();
+  const [startedAt, setStartedAt] = useState(0);
+  const [lastTopic, setLastTopic] = useState("");
   const recorded = useRef(false);
 
-  const handleGenerate = async () => {
-    if (!topicInput.trim() || quiz.isGenerating) return;
+  const generate = async (topic: string) => {
+    if (quiz.isGenerating) return;
     recorded.current = false;
+    setSelected(undefined);
+    setLastTopic(topic);
     setStartedAt(Date.now());
-    await quiz.generateQuiz(topicInput.trim());
+    await quiz.generateQuiz(topic, count, difficulty);
   };
 
   const score = quiz.getScore();
@@ -35,67 +51,217 @@ export default function QuizPage() {
   }, [quiz.isComplete, quiz.topic, quiz.tokensUsed, score.percentage, startedAt]);
 
   const currentQ = quiz.questions[quiz.currentQuestionIndex];
+  const answered = selected !== undefined;
+  const isLast = quiz.currentQuestionIndex === quiz.questions.length - 1;
+
+  const answer = (idx: number) => {
+    if (answered) return;
+    setSelected(idx);
+    quiz.answerQuestion(idx);
+  };
+
+  const next = () => {
+    setSelected(undefined);
+    quiz.nextQuestion();
+  };
+
+  const restart = () => {
+    quiz.reset();
+    setSelected(undefined);
+  };
+
+  const showForm = quiz.questions.length === 0 && !quiz.isGenerating;
 
   return (
-    <main className="min-h-[70vh] px-4 py-6 sm:p-8 max-w-4xl mx-auto">
-      <h1 className="text-3xl font-bold mb-6">📝 Adaptive Quiz</h1>
+    <PageShell width="narrow">
+      <PageHeader icon={ListChecks} title={t("quiz.title")} description={t("quiz.description")} />
 
-      {quiz.questions.length === 0 && !quiz.isGenerating && (
+      {showForm && (
         <>
-          <div className="bg-white rounded-xl shadow-sm p-6 max-w-md mx-auto">
-            <h2 className="font-semibold mb-4">Choose a topic</h2>
-            <input
-              type="text"
-              value={topicInput}
-              onChange={(e) => setTopicInput(e.target.value)}
-              placeholder="e.g., Machine Learning, React Hooks..."
-              className="w-full px-4 py-2 border rounded-lg mb-4 text-base"
-              onKeyDown={(e) => e.key === "Enter" && handleGenerate()}
+          <TopicForm
+            title={t("quiz.formTitle")}
+            placeholder={t("quiz.placeholder")}
+            submitLabel={t("quiz.generate")}
+            busy={quiz.isGenerating}
+            defaultTopic={lastTopic}
+            onSubmit={generate}
+          >
+            <SegmentedControl
+              label={t("quiz.difficulty")}
+              value={difficulty}
+              onChange={setDifficulty}
+              options={[
+                { value: "easy", label: t("quiz.easy") },
+                { value: "medium", label: t("quiz.medium") },
+                { value: "hard", label: t("quiz.hard") },
+              ]}
             />
-            <button
-              onClick={handleGenerate}
-              className="w-full bg-blue-500 text-white py-2 rounded-lg hover:bg-blue-600 transition"
-            >
-              Generate Quiz
-            </button>
+            <SegmentedControl
+              label={t("quiz.questionCount")}
+              value={count}
+              onChange={setCount}
+              options={[
+                { value: 5, label: "5" },
+                { value: 10, label: "10" },
+              ]}
+            />
+          </TopicForm>
+          <div className="mx-auto max-w-2xl">
+            <ErrorNotice error={quiz.generationError} onRetry={lastTopic ? () => generate(lastTopic) : undefined} />
           </div>
-          <ErrorNotice error={quiz.generationError} />
         </>
       )}
 
-      {quiz.isGenerating && (
-        <div className="text-center py-12">
-          <LoadingSpinner size="lg" label="Generating quiz..." />
+      {quiz.isGenerating && <GeneratingState shape="quiz" label={t("quiz.loading")} hint={t("quiz.loadingHint")} />}
+
+      {currentQ && !quiz.isComplete && (
+        <div className="mx-auto max-w-2xl">
+          <div className="mb-4 flex items-center gap-3">
+            <p className="min-w-0 flex-1 truncate text-sm font-semibold text-ink">{quiz.topic}</p>
+            <button type="button" onClick={restart} className="btn btn-ghost btn-sm">
+              {t("common.newTopic")}
+            </button>
+          </div>
+          <div className="mb-5">
+            <ProgressBar
+              value={quiz.currentQuestionIndex + (answered ? 1 : 0)}
+              max={quiz.questions.length}
+              label={t("quiz.questionOf", { current: quiz.currentQuestionIndex + 1, total: quiz.questions.length })}
+            />
+          </div>
+          <QuizCard
+            question={currentQ}
+            questionNumber={quiz.currentQuestionIndex + 1}
+            totalQuestions={quiz.questions.length}
+            onAnswer={answer}
+            selectedAnswer={selected}
+            showResult={answered}
+          />
+          {answered && (
+            <div className="mt-5 flex justify-end">
+              <button type="button" onClick={next} className="btn btn-primary w-full sm:w-auto" autoFocus>
+                {isLast ? t("quiz.seeResults") : t("common.next")}
+                <ArrowRight className="h-4 w-4" aria-hidden="true" />
+              </button>
+            </div>
+          )}
         </div>
       )}
 
-      {currentQ && !quiz.isComplete && (
-        <QuizCard
-          question={currentQ}
-          questionNumber={quiz.currentQuestionIndex + 1}
-          totalQuestions={quiz.questions.length}
-          onAnswer={quiz.answerAndNext}
+      {quiz.isComplete && (
+        <QuizResults
+          topic={quiz.topic}
+          correct={score.correct}
+          total={score.total}
+          percentage={score.percentage}
+          onRetake={() => {
+            quiz.setQuestions(quiz.questions, quiz.topic);
+            recorded.current = false;
+            setStartedAt(Date.now());
+          }}
+          onNewTopic={restart}
         />
       )}
+    </PageShell>
+  );
+}
 
-      {quiz.isComplete && (
-        <div className="bg-white rounded-xl shadow-sm p-6 max-w-md mx-auto text-center">
-          <h2 className="text-2xl font-bold mb-2">🎉 Quiz Complete!</h2>
-          <p className="text-4xl font-bold text-blue-500 my-4">{score.percentage}%</p>
-          <p className="text-gray-600">
-            {score.correct} / {score.total} correct
-          </p>
-          <button
-            onClick={() => {
-              quiz.reset();
-              setTopicInput("");
-            }}
-            className="mt-4 bg-gray-200 px-4 py-2 rounded-lg hover:bg-gray-300"
-          >
-            Try Another Topic
+function QuizResults({
+  topic,
+  correct,
+  total,
+  percentage,
+  onRetake,
+  onNewTopic,
+}: {
+  topic: string;
+  correct: number;
+  total: number;
+  percentage: number;
+  onRetake: () => void;
+  onNewTopic: () => void;
+}) {
+  const { t } = useI18n();
+  const quiz = useQuizState();
+  const verdict = percentage >= 80 ? "quiz.scoreGreat" : percentage >= 50 ? "quiz.scoreGood" : "quiz.scoreLow";
+  const radius = 52;
+  const circumference = 2 * Math.PI * radius;
+
+  return (
+    <div className="mx-auto max-w-2xl">
+      <section className="card flex flex-col items-center p-6 text-center sm:p-8" aria-labelledby="quiz-done">
+        <div className="relative h-36 w-36">
+          <svg viewBox="0 0 120 120" className="h-full w-full -rotate-90" aria-hidden="true">
+            <circle cx="60" cy="60" r={radius} fill="none" stroke="var(--surface-2)" strokeWidth="10" />
+            <circle
+              cx="60"
+              cy="60"
+              r={radius}
+              fill="none"
+              stroke="var(--brand)"
+              strokeWidth="10"
+              strokeLinecap="round"
+              strokeDasharray={circumference}
+              strokeDashoffset={circumference * (1 - percentage / 100)}
+            />
+          </svg>
+          <span className="absolute inset-0 flex items-center justify-center font-display text-4xl font-semibold text-ink">
+            {percentage}%
+          </span>
+        </div>
+        <h2 id="quiz-done" className="mt-5 font-display text-2xl font-semibold text-ink">
+          {t("quiz.completeTitle")}
+        </h2>
+        <p className="mt-1 text-sm font-medium text-ink-muted">
+          {topic} · {t("quiz.scoreLine", { correct, total })}
+        </p>
+        <p className="mt-3 max-w-md text-[0.9375rem] leading-relaxed text-ink-muted">{t(verdict)}</p>
+        <div className="mt-6 flex w-full flex-col gap-2 sm:w-auto sm:flex-row">
+          <button type="button" onClick={onRetake} className="btn btn-secondary">
+            <RotateCcw className="h-4 w-4" aria-hidden="true" />
+            {t("quiz.retake")}
+          </button>
+          <button type="button" onClick={onNewTopic} className="btn btn-primary">
+            {t("quiz.tryAnother")}
           </button>
         </div>
-      )}
-    </main>
+      </section>
+
+      <section className="mt-8" aria-labelledby="quiz-review">
+        <h3 id="quiz-review" className="mb-3 text-sm font-semibold uppercase tracking-wide text-ink-muted">
+          {t("quiz.reviewTitle")}
+        </h3>
+        <ol className="space-y-3">
+          {quiz.questions.map((q, i) => {
+            const attempt = quiz.attempts.find((a) => a.questionId === q.id);
+            const ok = !!attempt?.isCorrect;
+            return (
+              <li key={q.id} className="card flex gap-3 p-4">
+                <span
+                  className={clsx(
+                    "flex h-7 w-7 shrink-0 items-center justify-center rounded-full",
+                    ok ? "bg-success-soft text-success-ink" : "bg-danger-soft text-danger-ink",
+                  )}
+                >
+                  {ok ? <Check className="h-4 w-4" aria-label={t("quiz.correct")} /> : <X className="h-4 w-4" aria-label={t("quiz.incorrect")} />}
+                </span>
+                <div className="min-w-0 text-sm">
+                  <p className="font-medium text-ink">
+                    {i + 1}. {q.question}
+                  </p>
+                  <p className="mt-1 text-success-ink">
+                    <Check className="mr-1 inline h-3.5 w-3.5 align-[-2px]" aria-hidden="true" />
+                    {q.options[q.correctIndex]}
+                  </p>
+                  {!ok && attempt && (
+                    <p className="mt-0.5 text-ink-muted">{t("quiz.yourAnswer", { answer: q.options[attempt.selectedIndex] ?? "" })}</p>
+                  )}
+                </div>
+              </li>
+            );
+          })}
+        </ol>
+      </section>
+    </div>
   );
 }
diff --git a/src/app/roadmap/page.tsx b/src/app/roadmap/page.tsx
index f8505f8..4fb0bcf 100644
--- a/src/app/roadmap/page.tsx
+++ b/src/app/roadmap/page.tsx
@@ -1,24 +1,33 @@
 "use client";
 import { useState } from "react";
-import { RoadmapNode, RoadmapStep } from "@/components/RoadmapNode";
-import { LoadingSpinner } from "@/components/LoadingSpinner";
+import { PartyPopper, Route } from "lucide-react";
+import { RoadmapNode, type RoadmapStep } from "@/components/RoadmapNode";
 import { ErrorNotice } from "@/components/ErrorNotice";
+import { GeneratingState } from "@/components/GeneratingState";
+import { TopicForm } from "@/components/TopicForm";
+import { PageHeader } from "@/components/ui/PageHeader";
+import { PageShell } from "@/components/ui/PageShell";
+import { SegmentedControl } from "@/components/ui/SegmentedControl";
 import { ApiError, postJson } from "@/lib/api-client";
 import { recordSession } from "@/lib/record-session";
+import { useI18n } from "@/i18n/I18nProvider";
+
+type Level = "beginner" | "intermediate" | "advanced";
 
 export default function RoadmapPage() {
-  const [topicInput, setTopicInput] = useState("");
-  const [level, setLevel] = useState("beginner");
+  const { t } = useI18n();
+  const [level, setLevel] = useState<Level>("beginner");
   const [steps, setSteps] = useState<RoadmapStep[]>([]);
   const [title, setTitle] = useState("");
+  const [lastTopic, setLastTopic] = useState("");
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<ApiError | null>(null);
 
-  const handleGenerate = async () => {
-    const topic = topicInput.trim();
-    if (!topic || isLoading) return;
+  const generate = async (topic: string) => {
+    if (isLoading) return;
     setIsLoading(true);
     setError(null);
+    setLastTopic(topic);
     const started = Date.now();
     try {
       const data = await postJson<{ roadmap: { title: string; steps: RoadmapStep[] }; tokens_used?: number }>(
@@ -35,59 +44,92 @@ export default function RoadmapPage() {
     }
   };
 
+  const completeStep = (index: number) => {
+    setSteps((prev) =>
+      prev.map((s, i) => {
+        if (i === index) return { ...s, status: "completed" };
+        if (i === index + 1 && s.status === "upcoming") return { ...s, status: "current" };
+        return s;
+      }),
+    );
+  };
+
+  const done = steps.filter((s) => s.status === "completed").length;
+  const allDone = steps.length > 0 && done === steps.length;
+
   return (
-    <main className="min-h-[70vh] px-4 py-6 sm:p-8 max-w-3xl mx-auto">
-      <h1 className="text-3xl font-bold mb-6">🗺️ Learning Roadmap</h1>
+    <PageShell width="narrow">
+      <PageHeader icon={Route} title={t("roadmap.title")} description={t("roadmap.description")} />
 
       {steps.length === 0 && !isLoading && (
         <>
-          <div className="bg-white rounded-xl shadow-sm p-6 max-w-md mx-auto">
-            <input
-              type="text"
-              value={topicInput}
-              onChange={(e) => setTopicInput(e.target.value)}
-              onKeyDown={(e) => e.key === "Enter" && handleGenerate()}
-              placeholder="Topic to learn..."
-              className="w-full px-4 py-2 border rounded-lg mb-3 text-base"
-            />
-            <select
-              value={level}
-              onChange={(e) => setLevel(e.target.value)}
-              className="w-full px-4 py-2 border rounded-lg mb-4 bg-white text-base"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-            <button onClick={handleGenerate} className="w-full bg-purple-500 text-white py-2 rounded-lg hover:bg-purple-600">
-              Generate Roadmap
-            </button>
+          <TopicForm
+            title={t("roadmap.formTitle")}
+            placeholder={t("roadmap.placeholder")}
+            submitLabel={t("roadmap.generate")}
+            busy={isLoading}
+            defaultTopic={lastTopic}
+            onSubmit={generate}
+          >
+            <div className="sm:col-span-2">
+              <SegmentedControl
+                label={t("roadmap.level")}
+                value={level}
+                onChange={setLevel}
+                options={[
+                  { value: "beginner", label: t("roadmap.beginner") },
+                  { value: "intermediate", label: t("roadmap.intermediate") },
+                  { value: "advanced", label: t("roadmap.advanced") },
+                ]}
+              />
+            </div>
+          </TopicForm>
+          <div className="mx-auto max-w-2xl">
+            <ErrorNotice error={error} onRetry={lastTopic ? () => generate(lastTopic) : undefined} />
           </div>
-          <ErrorNotice error={error} />
         </>
       )}
 
-      {isLoading && <LoadingSpinner size="lg" label="Building your roadmap..." />}
+      {isLoading && <GeneratingState shape="roadmap" label={t("roadmap.loading")} hint={t("roadmap.loadingHint")} />}
 
       {steps.length > 0 && (
-        <div>
-          <h2 className="text-xl font-semibold mb-6">{title}</h2>
-          {steps.map((step, i) => (
-            <RoadmapNode key={step.id} step={step} index={i} isLast={i === steps.length - 1} />
-          ))}
-          <div className="mt-6 text-center">
+        <div className="mx-auto max-w-2xl">
+          <div className="mb-6 flex flex-wrap items-end justify-between gap-3">
+            <div className="min-w-0">
+              <p className="text-xs font-bold uppercase tracking-wider text-ink-subtle">
+                {t(`roadmap.${level}`)} · {t("roadmap.stepsCount", { count: steps.length })}
+              </p>
+              <h2 className="mt-1 font-display text-2xl font-semibold leading-tight text-ink">{title}</h2>
+            </div>
             <button
+              type="button"
               onClick={() => {
                 setSteps([]);
-                setTopicInput("");
               }}
-              className="text-sm text-gray-500 underline hover:text-gray-700"
+              className="btn btn-ghost btn-sm"
             >
-              New roadmap
+              {t("roadmap.newRoadmap")}
             </button>
           </div>
+          {allDone && (
+            <p role="status" className="mb-6 flex items-center gap-2 rounded-xl bg-success-soft px-4 py-3 text-sm font-semibold text-success-ink">
+              <PartyPopper className="h-4 w-4" aria-hidden="true" />
+              {t("roadmap.allDone")}
+            </p>
+          )}
+          <ol>
+            {steps.map((step, i) => (
+              <RoadmapNode
+                key={step.id}
+                step={step}
+                index={i}
+                isLast={i === steps.length - 1}
+                onComplete={() => completeStep(i)}
+              />
+            ))}
+          </ol>
         </div>
       )}
-    </main>
+    </PageShell>
   );
 }
diff --git a/src/components/AppHeader.tsx b/src/components/AppHeader.tsx
index ff41cc2..5b3817d 100644
--- a/src/components/AppHeader.tsx
+++ b/src/components/AppHeader.tsx
@@ -1,15 +1,25 @@
 "use client";
 import Link from "next/link";
+import { usePathname } from "next/navigation";
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { clsx } from "clsx";
+import { KeyRound } from "lucide-react";
 import { OPEN_SETTINGS_EVENT } from "@/lib/api-client";
 import { getProvider } from "@/lib/llm/providers";
 import { parseSettings, readRawSettings, subscribeSettings } from "@/lib/llm/settings";
+import { NAV_ITEMS, isActive } from "@/lib/nav";
+import { useI18n } from "@/i18n/I18nProvider";
+import { LanguageSwitch } from "./LanguageSwitch";
+import { LogoMark } from "./Logo";
 import { SettingsDialog, type ServerInfo } from "./SettingsDialog";
+import { ThemeToggle } from "./ThemeToggle";
 
 /** `undefined` during server render and hydration: settings not read yet. */
 const serverSnapshot = () => undefined;
 
 export function AppHeader() {
+  const { t } = useI18n();
+  const pathname = usePathname();
   const [open, setOpen] = useState(false);
   const [reason, setReason] = useState<string | undefined>();
   const [serverInfo, setServerInfo] = useState<ServerInfo | null>(null);
@@ -39,29 +49,72 @@ export function AppHeader() {
   const preset = getProvider(settings.provider);
   const serverMode = serverInfo?.mode === "server";
   const ready = serverMode || !!settings.apiKey || (!!preset && !preset.keyRequired);
-  const status = !loaded ? "" : serverMode ? "Server key" : ready ? preset?.label ?? "Ready" : "Add API key";
+  const status = !loaded
+    ? ""
+    : serverMode
+      ? t("header.statusServer")
+      : ready
+        ? (preset?.label ?? t("header.statusReady"))
+        : t("header.statusNeedsKey");
 
+  // No backdrop-filter on the header: it would become the containing block of the fixed settings dialog.
   return (
-    <header className="sticky top-0 z-40 border-b border-gray-200 bg-white">
-      <div className="mx-auto flex max-w-4xl items-center justify-between gap-3 px-4 py-3 sm:px-8">
-        <Link href="/" className="flex items-center gap-2 font-semibold">
-          <span aria-hidden="true">🎓</span> LearnPath
+    <header className="sticky top-0 z-40 border-b border-line bg-canvas">
+      <a
+        href="#main"
+        className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-3 focus:z-50 focus:rounded-lg focus:bg-surface focus:px-3 focus:py-2 focus:text-sm focus:font-semibold"
+      >
+        {t("common.skipToContent")}
+      </a>
+      <div className="mx-auto flex h-16 max-w-6xl items-center gap-3 px-4 sm:px-6">
+        <Link href="/" aria-label={t("header.homeLink")} className="flex shrink-0 items-center gap-2.5 rounded-lg">
+          <LogoMark />
+          <span className="font-display text-[1.25rem] font-semibold tracking-tight">{t("common.appName")}</span>
         </Link>
-        <button
-          type="button"
-          onClick={() => {
-            setReason(undefined);
-            setOpen(true);
-          }}
-          className="flex min-w-0 items-center gap-2 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-sm text-gray-700 shadow-sm hover:bg-gray-50"
-        >
-          <span
-            aria-hidden="true"
-            className={`h-2 w-2 shrink-0 rounded-full ${!loaded ? "bg-gray-300" : ready ? "bg-emerald-500" : "bg-amber-400"}`}
-          />
-          <span>Settings</span>
-          {status && <span className="hidden truncate text-gray-400 sm:inline">· {status}</span>}
-        </button>
+
+        <nav aria-label={t("nav.label")} className="ml-4 hidden items-center gap-1 md:flex">
+          {NAV_ITEMS.filter((item) => item.href !== "/").map((item) => {
+            const active = isActive(pathname, item.href);
+            return (
+              <Link
+                key={item.href}
+                href={item.href}
+                aria-current={active ? "page" : undefined}
+                className={clsx(
+                  "rounded-lg px-3 py-2 text-sm font-medium transition-colors",
+                  active ? "bg-brand-soft text-brand-ink" : "text-ink-muted hover:bg-surface-2 hover:text-ink",
+                )}
+              >
+                {t(item.label)}
+              </Link>
+            );
+          })}
+        </nav>
+
+        <div className="ml-auto flex items-center gap-1.5 sm:gap-2">
+          <LanguageSwitch />
+          <ThemeToggle />
+          <button
+            type="button"
+            onClick={() => {
+              setReason(undefined);
+              setOpen(true);
+            }}
+            aria-label={`${t("header.settings")}${status ? ` (${status})` : ""}`}
+            className="btn btn-secondary btn-sm relative h-9 min-w-9 px-2.5 sm:px-3"
+          >
+            <KeyRound className="h-4 w-4 shrink-0" aria-hidden="true" />
+            <span className="hidden sm:inline">{t("header.settings")}</span>
+            {status && <span className="hidden max-w-[10rem] truncate font-normal text-ink-muted lg:inline">· {status}</span>}
+            <span
+              aria-hidden="true"
+              className={clsx(
+                "absolute -right-0.5 -top-0.5 h-2.5 w-2.5 rounded-full ring-2 ring-canvas",
+                !loaded ? "bg-line-strong" : ready ? "bg-success" : "bg-accent",
+              )}
+            />
+          </button>
+        </div>
       </div>
       {open && <SettingsDialog reason={reason} initial={settings} serverInfo={serverInfo} onClose={close} />}
     </header>
diff --git a/src/components/ChatBubble.tsx b/src/components/ChatBubble.tsx
index 428176b..07f8c8e 100644
--- a/src/components/ChatBubble.tsx
+++ b/src/components/ChatBubble.tsx
@@ -1,5 +1,6 @@
 "use client";
 import { clsx } from "clsx";
+import { useI18n } from "@/i18n/I18nProvider";
 
 interface ChatBubbleProps {
   role: "user" | "assistant";
@@ -10,35 +11,37 @@ interface ChatBubbleProps {
 }
 
 export function ChatBubble({ role, content, reasoning, timestamp, tokensUsed }: ChatBubbleProps) {
+  const { t } = useI18n();
   const isUser = role === "user";
 
   return (
-    <div className={clsx("flex gap-3 mb-4", isUser ? "flex-row-reverse" : "flex-row")}>
+    <div className={clsx("mb-4 flex gap-3", isUser ? "flex-row-reverse" : "flex-row")}>
       <div
+        aria-hidden="true"
         className={clsx(
-          "w-8 h-8 rounded-full flex items-center justify-center text-sm font-bold shrink-0",
-          isUser ? "bg-blue-500 text-white" : "bg-emerald-500 text-white",
+          "flex h-8 w-8 shrink-0 items-center justify-center rounded-full text-xs font-bold",
+          isUser ? "bg-brand text-on-brand" : "bg-surface-2 text-ink",
         )}
       >
-        {isUser ? "U" : "M"}
+        {isUser ? t("chat.you").slice(0, 1) : t("chat.model")}
       </div>
       <div
         className={clsx(
           "max-w-[75%] rounded-2xl px-4 py-3",
-          isUser ? "bg-blue-500 text-white" : "bg-gray-100 text-gray-900",
+          isUser ? "bg-brand text-on-brand" : "border border-line bg-surface text-ink",
         )}
       >
-        <p className="text-sm whitespace-pre-wrap">{content}</p>
+        <p className="whitespace-pre-wrap text-sm">{content}</p>
         {reasoning && (
-          <details className="mt-2 text-xs opacity-70">
-            <summary className="cursor-pointer">Reasoning</summary>
+          <details className="mt-2 text-xs opacity-80">
+            <summary className="cursor-pointer">{t("chat.reasoning")}</summary>
             <p className="mt-1 italic">{reasoning}</p>
           </details>
         )}
         {(timestamp || tokensUsed) && (
-          <div className="mt-1 flex gap-2 text-xs opacity-50">
+          <div className="mt-1 flex gap-2 text-xs opacity-75">
             {timestamp && <span>{timestamp}</span>}
-            {tokensUsed && <span>{tokensUsed} tokens</span>}
+            {tokensUsed && <span>{t("common.tokens", { count: tokensUsed })}</span>}
           </div>
         )}
       </div>
diff --git a/src/components/ConceptMap.tsx b/src/components/ConceptMap.tsx
index fd8914c..ce1db2e 100644
--- a/src/components/ConceptMap.tsx
+++ b/src/components/ConceptMap.tsx
@@ -1,4 +1,7 @@
 "use client";
+import { clsx } from "clsx";
+import { CircleCheck, CircleDashed, CircleDot } from "lucide-react";
+import { useI18n } from "@/i18n/I18nProvider";
 
 interface Concept {
   id: string;
@@ -12,27 +15,53 @@ interface ConceptMapProps {
   title?: string;
 }
 
-export function ConceptMap({ concepts, title = "Concept Map" }: ConceptMapProps) {
-  const getMasteryColor = (mastery: number): string => {
-    if (mastery >= 80) return "bg-green-100 border-green-400 text-green-800";
-    if (mastery >= 50) return "bg-yellow-100 border-yellow-400 text-yellow-800";
-    return "bg-red-100 border-red-400 text-red-800";
-  };
+function band(mastery: number) {
+  if (mastery >= 80) return { key: "concepts.strong", icon: CircleCheck, chip: "bg-success-soft text-success-ink", bar: "bg-success" } as const;
+  if (mastery >= 50) return { key: "concepts.building", icon: CircleDot, chip: "bg-warning-soft text-warning-ink", bar: "bg-accent" } as const;
+  return { key: "concepts.weak", icon: CircleDashed, chip: "bg-danger-soft text-danger-ink", bar: "bg-danger" } as const;
+}
+
+export function ConceptMap({ concepts, title }: ConceptMapProps) {
+  const { t } = useI18n();
+  const byId = new Map(concepts.map((c) => [c.id, c.label]));
 
   return (
-    <div className="bg-white rounded-xl shadow-sm p-4">
-      <h3 className="text-sm font-semibold text-gray-700 mb-3">{title}</h3>
-      <div className="flex flex-wrap gap-2">
-        {concepts.map((concept) => (
-          <div
-            key={concept.id}
-            className={`px-3 py-2 rounded-lg border text-sm ${getMasteryColor(concept.mastery)}`}
-          >
-            <span className="font-medium">{concept.label}</span>
-            <span className="ml-2 text-xs opacity-70">{concept.mastery}%</span>
-          </div>
-        ))}
+    <section className="card p-5 sm:p-6">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <h2 className="text-lg font-semibold text-ink">{title ?? t("concepts.title")}</h2>
+        <ul className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-ink-muted" aria-label={t("concepts.legend")}>
+          {[90, 60, 30].map((m) => {
+            const b = band(m);
+            return (
+              <li key={m} className="inline-flex items-center gap-1.5">
+                <b.icon className={clsx("h-3.5 w-3.5", b.chip.split(" ")[1])} aria-hidden="true" />
+                {t(b.key)}
+              </li>
+            );
+          })}
+        </ul>
       </div>
-    </div>
+      <ul className="mt-5 grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+        {concepts.map((concept) => {
+          const b = band(concept.mastery);
+          const links = concept.connections.map((id) => byId.get(id)).filter(Boolean).join(", ");
+          return (
+            <li key={concept.id} className="rounded-xl border border-line bg-surface p-4">
+              <div className="flex items-start justify-between gap-3">
+                <span className="font-semibold leading-snug text-ink">{concept.label}</span>
+                <span className={clsx("inline-flex shrink-0 items-center gap-1 rounded-full px-2 py-0.5 text-xs font-semibold", b.chip)}>
+                  <b.icon className="h-3.5 w-3.5" aria-hidden="true" />
+                  {concept.mastery}%
+                </span>
+              </div>
+              <div className="mt-3 h-1.5 overflow-hidden rounded-full bg-surface-2" aria-hidden="true">
+                <div className={clsx("h-full rounded-full", b.bar)} style={{ width: `${concept.mastery}%` }} />
+              </div>
+              {links && <p className="mt-3 text-xs leading-relaxed text-ink-subtle">{t("concepts.linksTo", { list: links })}</p>}
+            </li>
+          );
+        })}
+      </ul>
+    </section>
   );
 }
diff --git a/src/components/ErrorNotice.tsx b/src/components/ErrorNotice.tsx
index 34da334..2991c7d 100644
--- a/src/components/ErrorNotice.tsx
+++ b/src/components/ErrorNotice.tsx
@@ -1,20 +1,34 @@
 "use client";
+import { CircleAlert, KeyRound } from "lucide-react";
 import { ApiError, openSettings } from "@/lib/api-client";
+import { useI18n } from "@/i18n/I18nProvider";
+import { errorMessage } from "@/i18n/errors";
 
-export function ErrorNotice({ error }: { error: ApiError | null }) {
+export function ErrorNotice({ error, onRetry }: { error: ApiError | null; onRetry?: () => void }) {
+  const { t } = useI18n();
   if (!error) return null;
   return (
-    <div role="alert" className="max-w-md mx-auto mt-4 rounded-xl border border-red-200 bg-red-50 p-4 text-sm text-red-800">
-      <p>{error.message}</p>
-      {error.fixableInSettings && (
-        <button
-          type="button"
-          onClick={() => openSettings()}
-          className="mt-3 rounded-lg bg-white px-3 py-1.5 font-medium text-red-700 shadow-sm ring-1 ring-red-200 hover:bg-red-100"
-        >
-          Open Settings
-        </button>
-      )}
+    <div role="alert" className="mt-4 flex gap-3 rounded-xl border border-danger/30 bg-danger-soft p-4 text-sm text-danger-ink">
+      <CircleAlert className="mt-0.5 h-5 w-5 shrink-0" aria-hidden="true" />
+      <div className="min-w-0">
+        <p className="font-semibold">{t("errors.title")}</p>
+        <p className="mt-0.5 leading-relaxed">{errorMessage(t, error.code)}</p>
+        {(error.fixableInSettings || onRetry) && (
+          <div className="mt-3 flex flex-wrap gap-2">
+            {error.fixableInSettings && (
+              <button type="button" onClick={() => openSettings()} className="btn btn-secondary btn-sm">
+                <KeyRound className="h-4 w-4" aria-hidden="true" />
+                {t("errors.openSettings")}
+              </button>
+            )}
+            {onRetry && !error.fixableInSettings && (
+              <button type="button" onClick={onRetry} className="btn btn-secondary btn-sm">
+                {t("common.tryAgain")}
+              </button>
+            )}
+          </div>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/src/components/FlashCard.tsx b/src/components/FlashCard.tsx
index 32d1878..afe766b 100644
--- a/src/components/FlashCard.tsx
+++ b/src/components/FlashCard.tsx
@@ -1,5 +1,6 @@
 "use client";
-import { clsx } from "clsx";
+import { RefreshCw } from "lucide-react";
+import { useI18n } from "@/i18n/I18nProvider";
 
 interface FlashCardProps {
   front: string;
@@ -9,13 +10,19 @@ interface FlashCardProps {
   topic?: string;
 }
 
+/**
+ * Both faces share one grid cell, so the card grows with the longer text
+ * instead of clipping it.
+ */
 export function FlashCard({ front, back, isFlipped, onFlip, topic }: FlashCardProps) {
+  const { t } = useI18n();
   return (
     <div
-      className="perspective-[1000px] cursor-pointer w-full max-w-md mx-auto"
+      className="flip-scene mx-auto w-full cursor-pointer select-none rounded-2xl"
       onClick={onFlip}
       role="button"
       tabIndex={0}
+      aria-pressed={isFlipped}
       onKeyDown={(e) => {
         if (e.key === " " || e.key === "Enter") {
           e.preventDefault();
@@ -23,26 +30,30 @@ export function FlashCard({ front, back, isFlipped, onFlip, topic }: FlashCardPr
         }
       }}
     >
-      <div
-        className={clsx(
-          "relative w-full min-h-[200px] transition-transform duration-500 transform-3d",
-          isFlipped && "rotate-y-180",
-        )}
-      >
-        {/* Front */}
-        <div className="absolute inset-0 backface-hidden bg-white rounded-xl shadow-lg p-6 flex flex-col items-center justify-center">
+      <div className="flip-card" data-flipped={isFlipped}>
+        <div
+          className="flip-face card relative flex min-h-64 flex-col items-center justify-center p-6 pt-12 text-center sm:min-h-72 sm:p-10"
+          aria-hidden={isFlipped}
+        >
           {topic && (
-            <span className="absolute top-3 right-3 text-xs bg-gray-100 px-2 py-1 rounded-sm">
+            <span className="absolute left-4 top-4 max-w-[70%] truncate rounded-full bg-surface-2 px-2.5 py-1 text-xs font-medium text-ink-muted">
               {topic}
             </span>
           )}
-          <p className="text-lg font-medium text-center">{front}</p>
-          <p className="text-sm text-gray-400 mt-4">Tap to reveal</p>
+          <p className="text-xl font-semibold leading-snug text-ink sm:text-2xl">{front}</p>
+          <p className="mt-6 inline-flex items-center gap-1.5 text-sm text-ink-subtle">
+            <RefreshCw className="h-3.5 w-3.5" aria-hidden="true" />
+            {t("flashcards.tapToReveal")}
+          </p>
         </div>
-
-        {/* Back */}
-        <div className="absolute inset-0 backface-hidden rotate-y-180 bg-emerald-50 rounded-xl shadow-lg p-6 flex items-center justify-center">
-          <p className="text-base text-center">{back}</p>
+        <div
+          className="flip-face flip-back relative flex min-h-64 flex-col items-center justify-center rounded-2xl border border-brand/40 bg-brand-soft p-6 pt-12 text-center shadow-card sm:min-h-72 sm:p-10"
+          aria-hidden={!isFlipped}
+        >
+          <span className="absolute left-4 top-4 text-xs font-bold uppercase tracking-wider text-brand-ink">
+            {t("flashcards.answer")}
+          </span>
+          <p className="text-base leading-relaxed text-ink sm:text-lg">{back}</p>
         </div>
       </div>
     </div>
diff --git a/src/components/GeneratingState.tsx b/src/components/GeneratingState.tsx
new file mode 100644
index 0000000..a992749
--- /dev/null
+++ b/src/components/GeneratingState.tsx
@@ -0,0 +1,47 @@
+"use client";
+import { LoadingSpinner } from "./LoadingSpinner";
+
+/** Loading state shown while the model writes: status text plus a skeleton of the result. */
+export function GeneratingState({ label, hint, shape }: { label: string; hint: string; shape: "quiz" | "cards" | "roadmap" }) {
+  return (
+    <div className="mx-auto max-w-2xl" aria-busy="true">
+      <div role="status" aria-live="polite" className="mb-6 flex items-center gap-3">
+        <LoadingSpinner size="sm" />
+        <div>
+          <p className="text-sm font-semibold text-ink">{label}</p>
+          <p className="text-xs text-ink-subtle">{hint}</p>
+        </div>
+      </div>
+      <div aria-hidden="true" className="card p-6">
+        {shape === "quiz" && (
+          <>
+            <div className="skeleton h-3 w-24" />
+            <div className="skeleton mt-5 h-5 w-4/5" />
+            <div className="skeleton mt-2 h-5 w-3/5" />
+            {[0, 1, 2, 3].map((i) => (
+              <div key={i} className="skeleton mt-4 h-12 w-full rounded-xl" />
+            ))}
+          </>
+        )}
+        {shape === "cards" && (
+          <div className="flex min-h-56 flex-col items-center justify-center gap-3">
+            <div className="skeleton h-5 w-3/4" />
+            <div className="skeleton h-5 w-1/2" />
+            <div className="skeleton mt-6 h-3 w-32" />
+          </div>
+        )}
+        {shape === "roadmap" &&
+          [0, 1, 2].map((i) => (
+            <div key={i} className="flex gap-4 pb-6 last:pb-0">
+              <div className="skeleton h-9 w-9 shrink-0 rounded-full" />
+              <div className="flex-1">
+                <div className="skeleton h-4 w-2/5" />
+                <div className="skeleton mt-2 h-3 w-full" />
+                <div className="skeleton mt-1.5 h-3 w-4/5" />
+              </div>
+            </div>
+          ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/LanguageSwitch.tsx b/src/components/LanguageSwitch.tsx
new file mode 100644
index 0000000..4d29e8e
--- /dev/null
+++ b/src/components/LanguageSwitch.tsx
@@ -0,0 +1,32 @@
+"use client";
+import { clsx } from "clsx";
+import { LOCALES } from "@/i18n/config";
+import { useI18n } from "@/i18n/I18nProvider";
+
+/** BM | EN segmented switch. Each option names its language in that language. */
+export function LanguageSwitch() {
+  const { locale, setLocale, t } = useI18n();
+  return (
+    <div role="group" aria-label={t("header.language")} className="flex rounded-lg border border-line bg-surface-2 p-0.5">
+      {LOCALES.map((l) => {
+        const active = l === locale;
+        return (
+          <button
+            key={l}
+            type="button"
+            lang={l}
+            aria-pressed={active}
+            aria-label={t(l === "ms" ? "language.ms" : "language.en")}
+            onClick={() => !active && setLocale(l)}
+            className={clsx(
+              "min-h-8 min-w-9 rounded-md px-2 text-xs font-bold tracking-wide transition-colors",
+              active ? "bg-surface-raised text-ink shadow-card" : "text-ink-muted hover:text-ink",
+            )}
+          >
+            {t(l === "ms" ? "language.msShort" : "language.enShort")}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/src/components/LoadingSpinner.tsx b/src/components/LoadingSpinner.tsx
index d7cef1c..f349c6f 100644
--- a/src/components/LoadingSpinner.tsx
+++ b/src/components/LoadingSpinner.tsx
@@ -7,17 +7,15 @@ interface LoadingSpinnerProps {
 }
 
 export function LoadingSpinner({ size = "md", label }: LoadingSpinnerProps) {
-  const sizes = { sm: "w-4 h-4", md: "w-8 h-8", lg: "w-12 h-12" };
+  const sizes = { sm: "h-5 w-5", md: "h-8 w-8", lg: "h-12 w-12" };
 
   return (
     <div className="flex flex-col items-center gap-2">
       <div
-        className={clsx(
-          "border-2 border-gray-200 border-t-blue-500 rounded-full animate-spin",
-          sizes[size],
-        )}
+        aria-hidden="true"
+        className={clsx("animate-spin rounded-full border-2 border-line border-t-brand", sizes[size])}
       />
-      {label && <span className="text-sm text-gray-500">{label}</span>}
+      {label && <span className="text-sm text-ink-muted">{label}</span>}
     </div>
   );
 }
diff --git a/src/components/Logo.tsx b/src/components/Logo.tsx
new file mode 100644
index 0000000..7bce8a2
--- /dev/null
+++ b/src/components/Logo.tsx
@@ -0,0 +1,19 @@
+/** LearnPath mark: a winding path from a starting point to a goal. */
+export function LogoMark({ className = "h-8 w-8" }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 32 32" className={className} aria-hidden="true" focusable="false">
+      <rect width="32" height="32" rx="9" fill="var(--brand)" />
+      <path
+        d="M9.5 23c0-4.2 2.6-6 6.5-6s6.5-1.8 6.5-6"
+        stroke="var(--on-brand)"
+        strokeWidth="2.4"
+        strokeLinecap="round"
+        strokeDasharray="0.1 4.2"
+        fill="none"
+      />
+      <circle cx="9.5" cy="23" r="2.7" fill="var(--on-brand)" />
+      <circle cx="22.5" cy="10" r="3.3" fill="var(--on-brand)" />
+      <circle cx="22.5" cy="10" r="1.4" fill="var(--brand)" />
+    </svg>
+  );
+}
diff --git a/src/components/MobileNav.tsx b/src/components/MobileNav.tsx
new file mode 100644
index 0000000..344af4a
--- /dev/null
+++ b/src/components/MobileNav.tsx
@@ -0,0 +1,47 @@
+"use client";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { clsx } from "clsx";
+import { NAV_ITEMS, isActive } from "@/lib/nav";
+import { useI18n } from "@/i18n/I18nProvider";
+
+/** Bottom tab bar on small screens. */
+export function MobileNav() {
+  const { t } = useI18n();
+  const pathname = usePathname();
+  return (
+    <nav
+      aria-label={t("nav.label")}
+      className="fixed inset-x-0 bottom-0 z-40 border-t border-line bg-surface pb-[env(safe-area-inset-bottom)] md:hidden"
+    >
+      <ul className="mx-auto grid max-w-md grid-cols-5">
+        {NAV_ITEMS.filter((item) => item.mobile).map((item) => {
+          const active = isActive(pathname, item.href);
+          const Icon = item.icon;
+          return (
+            <li key={item.href}>
+              <Link
+                href={item.href}
+                aria-current={active ? "page" : undefined}
+                className={clsx(
+                  "flex h-16 flex-col items-center justify-center gap-1 px-1 text-[11px] font-semibold leading-tight",
+                  active ? "text-brand-ink" : "text-ink-muted",
+                )}
+              >
+                <span
+                  className={clsx(
+                    "flex h-7 w-12 items-center justify-center rounded-full",
+                    active && "bg-brand-soft",
+                  )}
+                >
+                  <Icon className="h-[19px] w-[19px]" aria-hidden="true" strokeWidth={active ? 2.25 : 1.9} />
+                </span>
+                <span className="max-w-full truncate">{t(item.label)}</span>
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}
diff --git a/src/components/ProgressChart.tsx b/src/components/ProgressChart.tsx
index 4df4546..8ba0acd 100644
--- a/src/components/ProgressChart.tsx
+++ b/src/components/ProgressChart.tsx
@@ -3,32 +3,60 @@
 interface ProgressChartProps {
   data: { label: string; value: number; max?: number }[];
   title: string;
+  /** Short note under the title, e.g. the unit. */
+  caption?: string;
+  /** Mark colour; defaults to the brand token. */
   color?: string;
 }
 
-export function ProgressChart({ data, title, color = "#3b82f6" }: ProgressChartProps) {
+/**
+ * Single-series column chart. One hue, 4px rounded tops on a shared baseline,
+ * a tooltip per column (hover or keyboard focus) and a visually hidden table
+ * with the exact values for screen readers.
+ */
+export function ProgressChart({ data, title, caption, color = "var(--brand)" }: ProgressChartProps) {
   const maxVal = Math.max(...data.map((d) => d.max || d.value), 1);
 
   return (
-    <div className="bg-white rounded-xl shadow-sm p-4">
-      <h3 className="text-sm font-semibold text-gray-700 mb-3">{title}</h3>
-      <div className="space-y-2">
-        {data.map((item) => (
-          <div key={item.label} className="flex items-center gap-2">
-            <span className="text-xs text-gray-500 w-12 shrink-0">{item.label}</span>
-            <div className="flex-1 bg-gray-100 rounded-full h-4 overflow-hidden">
+    <figure className="card p-5">
+      <figcaption>
+        <h3 className="text-sm font-semibold text-ink">{title}</h3>
+        {caption && <p className="mt-0.5 text-xs text-ink-subtle">{caption}</p>}
+      </figcaption>
+      <div className="mt-5 flex h-36 items-end gap-2 border-b border-line" aria-hidden="true">
+        {data.map((item) => {
+          const pct = (item.value / maxVal) * 100;
+          return (
+            <div key={item.label} className="group relative flex h-full flex-1 items-end justify-center">
               <div
-                className="h-full rounded-full transition-all duration-500"
-                style={{
-                  width: `${(item.value / maxVal) * 100}%`,
-                  backgroundColor: color,
-                }}
+                className="w-full max-w-9 rounded-t-[4px] transition-[height] duration-500"
+                style={{ height: item.value > 0 ? `max(${pct}%, 4px)` : "0", backgroundColor: color }}
               />
+              <span className="pointer-events-none absolute -top-1 left-1/2 z-10 -translate-x-1/2 -translate-y-full whitespace-nowrap rounded-md bg-ink px-2 py-1 text-xs font-semibold text-canvas opacity-0 shadow-raised transition-opacity group-hover:opacity-100">
+                {item.label}: {item.value}
+              </span>
             </div>
-            <span className="text-xs font-medium w-8 text-right">{item.value}</span>
-          </div>
+          );
+        })}
+      </div>
+      <div className="mt-2 flex gap-2" aria-hidden="true">
+        {data.map((item) => (
+          <span key={item.label} className="flex-1 text-center text-xs text-ink-subtle">
+            {item.label}
+          </span>
         ))}
       </div>
-    </div>
+      <table className="sr-only">
+        <caption>{title}</caption>
+        <tbody>
+          {data.map((item) => (
+            <tr key={item.label}>
+              <th scope="row">{item.label}</th>
+              <td>{item.value}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </figure>
   );
 }
diff --git a/src/components/QuizCard.tsx b/src/components/QuizCard.tsx
index 9073314..35db61e 100644
--- a/src/components/QuizCard.tsx
+++ b/src/components/QuizCard.tsx
@@ -1,6 +1,8 @@
 "use client";
 import { clsx } from "clsx";
+import { Check, Lightbulb, X } from "lucide-react";
 import type { QuizQuestion } from "@/store/quiz-store";
+import { useI18n } from "@/i18n/I18nProvider";
 
 interface QuizCardProps {
   question: QuizQuestion;
@@ -11,62 +13,98 @@ interface QuizCardProps {
   showResult?: boolean;
 }
 
-export function QuizCard({
-  question,
-  questionNumber,
-  totalQuestions,
-  onAnswer,
-  selectedAnswer,
-  showResult,
-}: QuizCardProps) {
+const DIFFICULTY_STYLE = {
+  easy: "bg-success-soft text-success-ink",
+  medium: "bg-warning-soft text-warning-ink",
+  hard: "bg-danger-soft text-danger-ink",
+} as const;
+
+export function QuizCard({ question, questionNumber, totalQuestions, onAnswer, selectedAnswer, showResult }: QuizCardProps) {
+  const { t } = useI18n();
+  const answeredCorrectly = showResult && selectedAnswer === question.correctIndex;
+
   return (
-    <div className="bg-white rounded-xl shadow-lg p-6 max-w-2xl mx-auto">
-      <div className="flex justify-between items-center mb-4">
-        <span className="text-sm text-gray-500">
-          Question {questionNumber} of {totalQuestions}
+    <div className="card p-5 sm:p-7">
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-sm font-medium text-ink-muted">
+          {t("quiz.questionOf", { current: questionNumber, total: totalQuestions })}
         </span>
-        <span
-          className={clsx(
-            "px-2 py-1 rounded-sm text-xs font-medium",
-            question.difficulty === "easy" && "bg-green-100 text-green-700",
-            question.difficulty === "medium" && "bg-yellow-100 text-yellow-700",
-            question.difficulty === "hard" && "bg-red-100 text-red-700",
-          )}
-        >
-          {question.difficulty}
+        <span className={clsx("rounded-full px-2.5 py-1 text-xs font-semibold", DIFFICULTY_STYLE[question.difficulty])}>
+          {t(`quiz.${question.difficulty}`)}
         </span>
       </div>
 
-      <h3 className="text-lg font-semibold mb-4">{question.question}</h3>
+      <h2 className="mt-4 text-lg font-semibold leading-snug text-ink sm:text-xl">{question.question}</h2>
 
-      <div className="space-y-2">
+      <ul className="mt-5 space-y-2.5">
         {question.options.map((option, idx) => {
           const isSelected = selectedAnswer === idx;
           const isCorrect = idx === question.correctIndex;
-
+          const state = !showResult ? (isSelected ? "selected" : "idle") : isCorrect ? "correct" : isSelected ? "wrong" : "dim";
           return (
-            <button
-              key={idx}
-              onClick={() => !showResult && onAnswer(idx)}
-              disabled={showResult}
-              className={clsx(
-                "w-full text-left px-4 py-3 rounded-lg border transition-all",
-                !showResult && !isSelected && "border-gray-200 hover:border-blue-400 hover:bg-blue-50",
-                showResult && isCorrect && "border-green-500 bg-green-50",
-                showResult && isSelected && !isCorrect && "border-red-500 bg-red-50",
-                isSelected && !showResult && "border-blue-500 bg-blue-50",
-              )}
-            >
-              <span className="font-medium mr-2">{String.fromCharCode(65 + idx)}.</span>
-              {option}
-            </button>
+            <li key={idx}>
+              <button
+                type="button"
+                onClick={() => !showResult && onAnswer(idx)}
+                disabled={showResult}
+                aria-pressed={isSelected}
+                className={clsx(
+                  "flex w-full items-start gap-3 rounded-xl border px-4 py-3 text-left text-[0.9375rem] leading-snug transition-colors",
+                  state === "idle" && "border-line bg-surface hover:border-brand hover:bg-brand-soft/40",
+                  state === "selected" && "border-brand bg-brand-soft",
+                  state === "correct" && "border-success bg-success-soft text-success-ink",
+                  state === "wrong" && "border-danger bg-danger-soft text-danger-ink",
+                  state === "dim" && "border-line bg-surface text-ink-muted",
+                  showResult && "cursor-default",
+                )}
+              >
+                <span
+                  aria-hidden="true"
+                  className={clsx(
+                    "flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-xs font-bold",
+                    state === "correct"
+                      ? "bg-success text-on-brand"
+                      : state === "wrong"
+                        ? "bg-danger text-on-brand"
+                        : "bg-surface-2 text-ink-muted",
+                  )}
+                >
+                  {state === "correct" ? (
+                    <Check className="h-4 w-4" />
+                  ) : state === "wrong" ? (
+                    <X className="h-4 w-4" />
+                  ) : (
+                    String.fromCharCode(65 + idx)
+                  )}
+                </span>
+                <span className="pt-0.5">{option}</span>
+              </button>
+            </li>
           );
         })}
-      </div>
+      </ul>
 
-      {showResult && question.explanation && (
-        <div className="mt-4 p-3 bg-blue-50 rounded-lg text-sm text-blue-800">
-          <strong>Explanation:</strong> {question.explanation}
+      {showResult && (
+        <div role="status" aria-live="polite" className="mt-5 rounded-xl bg-surface-2 p-4 text-sm leading-relaxed">
+          {selectedAnswer !== undefined && (
+            <p className={clsx("mb-1.5 font-semibold", answeredCorrectly ? "text-success-ink" : "text-danger-ink")}>
+              {answeredCorrectly ? t("quiz.correct") : t("quiz.incorrect")}
+              {!answeredCorrectly && (
+                <span className="font-normal text-ink-muted">
+                  {" "}
+                  {t("quiz.correctAnswerWas", { answer: String.fromCharCode(65 + question.correctIndex) })}
+                </span>
+              )}
+            </p>
+          )}
+          {question.explanation && (
+            <p className="flex gap-2 text-ink-muted">
+              <Lightbulb className="mt-0.5 h-4 w-4 shrink-0 text-accent-ink" aria-hidden="true" />
+              <span>
+                <strong className="font-semibold text-ink">{t("quiz.explanation")}:</strong> {question.explanation}
+              </span>
+            </p>
+          )}
         </div>
       )}
     </div>
diff --git a/src/components/RoadmapNode.tsx b/src/components/RoadmapNode.tsx
index 7e70e69..9263250 100644
--- a/src/components/RoadmapNode.tsx
+++ b/src/components/RoadmapNode.tsx
@@ -1,5 +1,7 @@
 "use client";
 import { clsx } from "clsx";
+import { Check, Clock } from "lucide-react";
+import { useI18n } from "@/i18n/I18nProvider";
 
 export interface RoadmapStep {
   id: string;
@@ -14,61 +16,93 @@ interface RoadmapNodeProps {
   step: RoadmapStep;
   index: number;
   isLast: boolean;
+  /** Shown on the current step when given. */
+  onComplete?: () => void;
 }
 
-export function RoadmapNode({ step, index, isLast }: RoadmapNodeProps) {
-  const statusColors = {
-    completed: "bg-green-500 border-green-500",
-    current: "bg-blue-500 border-blue-500",
-    upcoming: "bg-gray-200 border-gray-300",
-  };
+const STATUS_LABEL = {
+  completed: "roadmap.statusCompleted",
+  current: "roadmap.statusCurrent",
+  upcoming: "roadmap.statusUpcoming",
+} as const;
+
+export function RoadmapNode({ step, index, isLast, onComplete }: RoadmapNodeProps) {
+  const { t } = useI18n();
+  const status = step.status;
 
   return (
-    <div className="flex gap-4">
+    <li className="relative flex gap-4 sm:gap-5">
       <div className="flex flex-col items-center">
-        <div
+        {/*
+          Every state keeps text contrast at AA: upcoming = muted ink on the
+          surface (was white on light grey), current = on-brand on brand,
+          completed = on-brand on success.
+        */}
+        <span
           className={clsx(
-            "w-10 h-10 rounded-full flex items-center justify-center text-white font-bold text-sm border-2",
-            statusColors[step.status],
+            "relative z-10 flex h-10 w-10 shrink-0 items-center justify-center rounded-full border-2 text-sm font-bold",
+            status === "completed" && "border-success bg-success text-on-brand",
+            status === "current" && "border-brand bg-brand text-on-brand ring-4 ring-brand-soft",
+            status === "upcoming" && "border-line-strong bg-surface text-ink-muted",
           )}
         >
-          {step.status === "completed" ? "✓" : index + 1}
-        </div>
+          {status === "completed" ? <Check className="h-5 w-5" strokeWidth={2.75} aria-hidden="true" /> : index + 1}
+          <span className="sr-only">
+            {t("roadmap.stepLabel", { number: index + 1 })}, {t(STATUS_LABEL[status])}
+          </span>
+        </span>
         {!isLast && (
-          <div
-            className={clsx(
-              "w-0.5 flex-1 min-h-[40px]",
-              step.status === "completed" ? "bg-green-300" : "bg-gray-200",
-            )}
+          <span
+            aria-hidden="true"
+            className={clsx("w-0.5 flex-1", status === "completed" ? "bg-success" : "bg-line")}
           />
         )}
       </div>
 
-      <div className="pb-8">
-        <h3
-          className={clsx(
-            "font-semibold",
-            step.status === "current" ? "text-blue-600" : "text-gray-900",
+      <div
+        className={clsx(
+          "mb-5 min-w-0 flex-1 rounded-2xl border p-4 sm:p-5",
+          status === "current" ? "border-brand/50 bg-surface shadow-raised" : "border-line bg-surface shadow-card",
+          isLast && "mb-0",
+        )}
+      >
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+          <span
+            className={clsx(
+              "text-xs font-bold uppercase tracking-wider",
+              status === "current" ? "text-brand-ink" : status === "completed" ? "text-success-ink" : "text-ink-subtle",
+            )}
+            aria-hidden="true"
+          >
+            {status === "upcoming" ? t("roadmap.stepLabel", { number: index + 1 }) : t(STATUS_LABEL[status])}
+          </span>
+          {step.estimatedTime && (
+            <span className="inline-flex items-center gap-1 text-xs text-ink-muted">
+              <Clock className="h-3.5 w-3.5" aria-hidden="true" />
+              {step.estimatedTime}
+            </span>
           )}
-        >
+        </div>
+        <h3 className={clsx("mt-1.5 text-base font-semibold leading-snug sm:text-lg", status === "completed" ? "text-ink-muted" : "text-ink")}>
           {step.title}
         </h3>
-        <p className="text-sm text-gray-600 mt-1">{step.description}</p>
-        {step.estimatedTime && (
-          <span className="text-xs text-gray-400 mt-1 block">
-            ⏱ {step.estimatedTime}
-          </span>
-        )}
+        {step.description && <p className="mt-1.5 text-sm leading-relaxed text-ink-muted">{step.description}</p>}
         {step.topics && step.topics.length > 0 && (
-          <div className="flex flex-wrap gap-1 mt-2">
-            {step.topics.map((t) => (
-              <span key={t} className="text-xs bg-gray-100 px-2 py-0.5 rounded-sm">
-                {t}
-              </span>
+          <ul className="mt-3 flex flex-wrap gap-1.5">
+            {step.topics.map((topic) => (
+              <li key={topic} className="rounded-lg bg-surface-2 px-2.5 py-1 text-xs font-medium text-ink-muted">
+                {topic}
+              </li>
             ))}
-          </div>
+          </ul>
+        )}
+        {status === "current" && onComplete && (
+          <button type="button" onClick={onComplete} className="btn btn-primary btn-sm mt-4">
+            <Check className="h-4 w-4" aria-hidden="true" />
+            {t("roadmap.markDone")}
+          </button>
         )}
       </div>
-    </div>
+    </li>
   );
 }
diff --git a/src/components/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index 9a993fb..ce3427d 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -1,7 +1,11 @@
 "use client";
 import { useEffect, useId, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Eye, EyeOff, ExternalLink, Info, ShieldCheck, X } from "lucide-react";
 import { PROVIDERS, getProvider } from "@/lib/llm/providers";
 import { clearSettings, defaultSettings, saveSettings, type LlmSettings } from "@/lib/llm/settings";
+import { useI18n } from "@/i18n/I18nProvider";
+import { errorMessage } from "@/i18n/errors";
 
 export interface ServerInfo {
   mode: "server" | "byo-key";
@@ -13,23 +17,49 @@ export interface ServerInfo {
 }
 
 interface SettingsDialogProps {
+  /** Error code that made the app open this panel (e.g. "missing_key"). */
   reason?: string;
   initial: LlmSettings;
   serverInfo: ServerInfo | null;
   onClose: () => void;
 }
 
-/** Rendered only while open, so the form starts from `initial` every time. */
+/**
+ * Rendered only while open, so the form starts from `initial` every time.
+ * Portalled to <body> so no ancestor's stacking context or filter can trap it.
+ */
 export function SettingsDialog({ reason, initial, serverInfo, onClose }: SettingsDialogProps) {
+  const { t } = useI18n();
   const [draft, setDraft] = useState<LlmSettings>(initial);
   const [showKey, setShowKey] = useState(false);
-  const [notice, setNotice] = useState<string | null>(null);
+  const [notice, setNotice] = useState<"storageBlocked" | "keyForgotten" | null>(null);
   const panelRef = useRef<HTMLDivElement>(null);
   const ids = useId();
 
-  // Escape closes; lock page scroll on <html> while open.
+  // Escape closes, Tab stays inside the panel, page scroll is locked on <html>,
+  // and focus returns to whatever opened the panel.
   useEffect(() => {
-    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    const opener = document.activeElement as HTMLElement | null;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onClose();
+        return;
+      }
+      if (e.key !== "Tab" || !panelRef.current) return;
+      const focusable = panelRef.current.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      );
+      if (focusable.length === 0) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (e.shiftKey && (document.activeElement === first || document.activeElement === panelRef.current)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
     window.addEventListener("keydown", onKey);
     const root = document.documentElement;
     const previous = root.style.overflow;
@@ -38,6 +68,7 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
     return () => {
       window.removeEventListener("keydown", onKey);
       root.style.overflow = previous;
+      opener?.focus?.();
     };
   }, [onClose]);
 
@@ -59,7 +90,7 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
       baseUrl: needsBaseUrl ? draft.baseUrl.trim() : "",
     };
     if (!saveSettings(cleaned)) {
-      setNotice("This browser blocked local storage, so the settings could not be saved (private mode?).");
+      setNotice("storageBlocked");
       return;
     }
     onClose();
@@ -68,12 +99,12 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
   const forget = () => {
     clearSettings();
     setDraft({ ...draft, apiKey: "" });
-    setNotice("Your key has been removed from this browser.");
+    setNotice("keyForgotten");
   };
 
-  return (
+  return createPortal(
     <div
-      className="fixed inset-0 z-50 flex items-end justify-center bg-gray-900/40 sm:items-center sm:p-4"
+      className="fixed inset-0 z-50 flex items-end justify-center bg-[var(--overlay)] sm:items-center sm:p-4"
       onMouseDown={(e) => e.target === e.currentTarget && onClose()}
     >
       <div
@@ -82,61 +113,62 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
         aria-modal="true"
         aria-labelledby={`${ids}-title`}
         tabIndex={-1}
-        className="max-h-[92dvh] w-full overflow-y-auto rounded-t-2xl bg-white p-5 shadow-xl outline-none sm:max-w-lg sm:rounded-xl sm:p-6"
+        className="max-h-[92dvh] w-full overflow-y-auto rounded-t-2xl border border-line bg-surface p-5 pb-[calc(1.25rem+env(safe-area-inset-bottom))] text-ink shadow-raised outline-none sm:max-w-lg sm:rounded-2xl sm:p-6"
       >
-        <div className="mb-4 flex items-start justify-between gap-4">
+        <div className="mb-5 flex items-start justify-between gap-4">
           <div>
-            <h2 id={`${ids}-title`} className="text-lg font-semibold">
-              AI provider settings
+            <h2 id={`${ids}-title`} className="font-display text-xl font-semibold">
+              {t("settings.title")}
             </h2>
-            <p className="mt-0.5 text-sm text-gray-500">Bring your own API key to use the AI features.</p>
+            <p className="mt-1 text-sm text-ink-muted">{t("settings.subtitle")}</p>
           </div>
-          <button
-            type="button"
-            onClick={onClose}
-            aria-label="Close settings"
-            className="-mr-1 rounded-lg p-1.5 text-gray-400 hover:bg-gray-100 hover:text-gray-600"
-          >
-            <svg viewBox="0 0 20 20" fill="currentColor" className="h-5 w-5" aria-hidden="true">
-              <path d="M6.28 5.22a.75.75 0 0 0-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 1 0 1.06 1.06L10 11.06l3.72 3.72a.75.75 0 1 0 1.06-1.06L11.06 10l3.72-3.72a.75.75 0 0 0-1.06-1.06L10 8.94 6.28 5.22Z" />
-            </svg>
+          <button type="button" onClick={onClose} aria-label={t("settings.closeLabel")} className="btn btn-ghost btn-sm -mr-1.5 h-9 w-9 p-0">
+            <X className="h-5 w-5" aria-hidden="true" />
           </button>
         </div>
 
         {reason && !serverMode && (
-          <p className="mb-4 rounded-lg border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-800">{reason}</p>
+          <p className="mb-4 flex gap-2 rounded-xl border border-accent/30 bg-warning-soft px-3 py-2.5 text-sm text-warning-ink">
+            <Info className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+            {errorMessage(t, reason)}
+          </p>
         )}
 
         {serverMode ? (
           <div className="space-y-4">
-            <p className="rounded-lg border border-blue-200 bg-blue-50 px-3 py-2 text-sm text-blue-800">
-              This server has its own API key configured
-              {serverInfo?.providerLabel ? ` (${serverInfo.providerLabel}${serverInfo.model ? `, ${serverInfo.model}` : ""})` : ""}.
-              There is nothing to set up here.
+            <p className="flex gap-2 rounded-xl border border-brand/30 bg-brand-soft px-3 py-2.5 text-sm text-brand-ink">
+              <ShieldCheck className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+              <span>
+                {t("settings.serverMode", {
+                  detail: serverInfo?.providerLabel
+                    ? ` (${serverInfo.providerLabel}${serverInfo.model ? `, ${serverInfo.model}` : ""})`
+                    : "",
+                })}
+              </span>
             </p>
             <div className="flex justify-end">
-              <button type="button" onClick={onClose} className="rounded-lg bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
-                Done
+              <button type="button" onClick={onClose} className="btn btn-primary">
+                {t("common.done")}
               </button>
             </div>
           </div>
         ) : (
           <form
-            className="space-y-4"
+            className="space-y-5"
             onSubmit={(e) => {
               e.preventDefault();
               save();
             }}
           >
             <div>
-              <label htmlFor={`${ids}-provider`} className="mb-1 block text-sm font-medium text-gray-700">
-                Provider
+              <label htmlFor={`${ids}-provider`} className="label">
+                {t("settings.provider")}
               </label>
               <select
                 id={`${ids}-provider`}
                 value={preset.id}
                 onChange={(e) => changeProvider(e.target.value)}
-                className="w-full rounded-lg border bg-white px-3 py-2 text-base"
+                className="field"
               >
                 {PROVIDERS.map((p) => (
                   <option key={p.id} value={p.id} disabled={p.selfHostOnly && !allowSelfHost}>
@@ -144,15 +176,13 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
                   </option>
                 ))}
               </select>
-              {!allowSelfHost && (
-                <p className="mt-1 text-xs text-gray-500">Self-hosted options need your own copy of LearnPath.</p>
-              )}
+              {!allowSelfHost && <p className="mt-1.5 text-xs text-ink-subtle">{t("settings.selfHostNote")}</p>}
             </div>
 
             {needsBaseUrl && (
               <div>
-                <label htmlFor={`${ids}-base`} className="mb-1 block text-sm font-medium text-gray-700">
-                  Base URL
+                <label htmlFor={`${ids}-base`} className="label">
+                  {t("settings.baseUrl")}
                 </label>
                 <input
                   id={`${ids}-base`}
@@ -163,41 +193,42 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
                   placeholder={preset.baseUrl || "https://your-server.example/v1"}
                   autoComplete="off"
                   spellCheck={false}
-                  className="w-full rounded-lg border px-3 py-2 text-base"
+                  className="field"
                 />
-                <p className="mt-1 text-xs text-gray-500">
-                  {preset.baseUrl ? `Leave empty to use ${preset.baseUrl}.` : "Any OpenAI-compatible endpoint, ending in /v1."}
+                <p className="mt-1.5 text-xs text-ink-subtle">
+                  {preset.baseUrl ? t("settings.baseUrlDefault", { url: preset.baseUrl }) : t("settings.baseUrlAny")}
                 </p>
               </div>
             )}
 
             <div>
-              <label htmlFor={`${ids}-model`} className="mb-1 block text-sm font-medium text-gray-700">
-                Model
+              <label htmlFor={`${ids}-model`} className="label">
+                {t("settings.model")}
               </label>
               <input
                 id={`${ids}-model`}
                 type="text"
                 value={draft.model}
                 onChange={(e) => setDraft({ ...draft, model: e.target.value })}
-                placeholder={preset.defaultModel || "model name"}
+                placeholder={preset.defaultModel || t("settings.modelPlaceholder")}
                 autoComplete="off"
                 autoCapitalize="off"
                 spellCheck={false}
-                className="w-full rounded-lg border px-3 py-2 font-mono text-base"
+                className="field font-mono"
               />
               {preset.defaultModel && (
-                <p className="mt-1 text-xs text-gray-500">
-                  Default for {preset.label}: <span className="font-mono">{preset.defaultModel}</span>
+                <p className="mt-1.5 text-xs text-ink-subtle">
+                  {t("settings.modelDefault", { provider: preset.label })}{" "}
+                  <span className="font-mono text-ink-muted">{preset.defaultModel}</span>
                   {draft.model.trim() !== preset.defaultModel && (
                     <>
                       {" · "}
                       <button
                         type="button"
-                        className="text-blue-600 underline"
+                        className="font-medium text-brand-ink underline underline-offset-2"
                         onClick={() => setDraft({ ...draft, model: preset.defaultModel })}
                       >
-                        use default
+                        {t("settings.useDefault")}
                       </button>
                     </>
                   )}
@@ -206,8 +237,9 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
             </div>
 
             <div>
-              <label htmlFor={`${ids}-key`} className="mb-1 block text-sm font-medium text-gray-700">
-                API key{!preset.keyRequired && <span className="font-normal text-gray-400"> (optional)</span>}
+              <label htmlFor={`${ids}-key`} className="label">
+                {t("settings.apiKey")}
+                {!preset.keyRequired && <span className="font-normal text-ink-subtle"> {t("settings.optional")}</span>}
               </label>
               <div className="flex gap-2">
                 <input
@@ -215,63 +247,68 @@ export function SettingsDialog({ reason, initial, serverInfo, onClose }: Setting
                   type={showKey ? "text" : "password"}
                   value={draft.apiKey}
                   onChange={(e) => setDraft({ ...draft, apiKey: e.target.value })}
-                  placeholder="Paste your key"
+                  placeholder={t("settings.keyPlaceholder")}
                   autoComplete="off"
                   autoCapitalize="off"
                   spellCheck={false}
-                  className="min-w-0 flex-1 rounded-lg border px-3 py-2 font-mono text-base"
+                  className="field min-w-0 flex-1 font-mono"
                 />
                 <button
                   type="button"
                   onClick={() => setShowKey((v) => !v)}
-                  className="shrink-0 rounded-lg border px-3 text-sm text-gray-600 hover:bg-gray-50"
+                  className="btn btn-secondary shrink-0 px-3"
                   aria-pressed={showKey}
                 >
-                  {showKey ? "Hide" : "Show"}
+                  {showKey ? <EyeOff className="h-4 w-4" aria-hidden="true" /> : <Eye className="h-4 w-4" aria-hidden="true" />}
+                  <span>{showKey ? t("settings.hide") : t("settings.show")}</span>
                 </button>
               </div>
               {preset.keysUrl && (
-                <p className="mt-1 text-xs text-gray-500">
-                  <a href={preset.keysUrl} target="_blank" rel="noopener noreferrer" className="text-blue-600 underline">
-                    Get an API key from {preset.label}
+                <p className="mt-1.5 text-xs">
+                  <a
+                    href={preset.keysUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="inline-flex items-center gap-1 font-medium text-brand-ink underline underline-offset-2"
+                  >
+                    {t("settings.getKey", { provider: preset.label })}
+                    <ExternalLink className="h-3 w-3" aria-hidden="true" />
                   </a>
                 </p>
               )}
             </div>
 
-            <div className="rounded-lg bg-gray-50 px-3 py-2.5 text-xs leading-relaxed text-gray-600">
-              <p className="mb-1 font-medium text-gray-700">Where your key goes</p>
-              Your key is saved only in this browser. It is sent with each request through this app&apos;s API route to
-              the provider you chose, and is never stored or logged on the server. Use a key with a spending limit, and
-              press &ldquo;Forget key&rdquo; on a shared device.
+            <div className="rounded-xl bg-surface-2 px-4 py-3 text-xs leading-relaxed text-ink-muted">
+              <p className="mb-1 flex items-center gap-1.5 font-semibold text-ink">
+                <ShieldCheck className="h-4 w-4 text-brand-ink" aria-hidden="true" />
+                {t("settings.privacyTitle")}
+              </p>
+              {t("settings.privacyBody")}
             </div>
 
             {notice && (
-              <p role="status" className="text-sm text-gray-700">
-                {notice}
+              <p role="status" className="text-sm text-ink">
+                {t(`settings.${notice}`)}
               </p>
             )}
 
             <div className="flex flex-wrap items-center justify-between gap-2 pt-1">
-              <button
-                type="button"
-                onClick={forget}
-                className="rounded-lg px-3 py-2 text-sm font-medium text-red-600 hover:bg-red-50"
-              >
-                Forget key
+              <button type="button" onClick={forget} className="btn btn-ghost btn-sm text-danger-ink hover:bg-danger-soft hover:text-danger-ink">
+                {t("settings.forget")}
               </button>
               <div className="flex gap-2">
-                <button type="button" onClick={onClose} className="rounded-lg bg-gray-100 px-4 py-2 hover:bg-gray-200">
-                  Cancel
+                <button type="button" onClick={onClose} className="btn btn-secondary">
+                  {t("common.cancel")}
                 </button>
-                <button type="submit" className="rounded-lg bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
-                  Save
+                <button type="submit" className="btn btn-primary">
+                  {t("common.save")}
                 </button>
               </div>
             </div>
           </form>
         )}
       </div>
-    </div>
+    </div>,
+    document.body,
   );
 }
diff --git a/src/components/SiteFooter.tsx b/src/components/SiteFooter.tsx
new file mode 100644
index 0000000..bc7be50
--- /dev/null
+++ b/src/components/SiteFooter.tsx
@@ -0,0 +1,28 @@
+"use client";
+import { useI18n } from "@/i18n/I18nProvider";
+
+export function SiteFooter() {
+  const { t } = useI18n();
+  const [builtBefore, builtAfter = ""] = t("footer.builtBy").split("{name}");
+  return (
+    <footer className="mx-auto mt-8 max-w-6xl px-4 pb-10 pt-6 sm:px-6">
+      <div className="flex flex-col items-center justify-between gap-2 border-t border-line pt-6 text-sm text-ink-subtle sm:flex-row">
+        <p>
+          {builtBefore}
+          <a href="https://sasateguh.com" className="font-medium text-ink-muted underline-offset-4 hover:text-ink hover:underline">
+            Sasa Teguh
+          </a>
+          {builtAfter}
+          {" · "}
+          {t("footer.tagline")}
+        </p>
+        <a
+          href="https://github.com/aimanmalib/learnpath"
+          className="font-medium text-ink-muted underline-offset-4 hover:text-ink hover:underline"
+        >
+          {t("footer.source")}
+        </a>
+      </div>
+    </footer>
+  );
+}
diff --git a/src/components/ThemeToggle.tsx b/src/components/ThemeToggle.tsx
new file mode 100644
index 0000000..7d96388
--- /dev/null
+++ b/src/components/ThemeToggle.tsx
@@ -0,0 +1,26 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { Moon, Sun } from "lucide-react";
+import { useI18n } from "@/i18n/I18nProvider";
+import { getEffectiveTheme, setTheme, subscribeTheme, type Theme } from "@/lib/theme";
+
+const serverTheme = (): Theme | null => null;
+
+export function ThemeToggle() {
+  const { t } = useI18n();
+  const theme = useSyncExternalStore(subscribeTheme, getEffectiveTheme, serverTheme);
+  const label = theme === "dark" ? t("header.themeToLight") : t("header.themeToDark");
+  return (
+    <button
+      type="button"
+      onClick={() => setTheme(getEffectiveTheme() === "dark" ? "light" : "dark")}
+      aria-label={label}
+      title={label}
+      className="btn btn-ghost btn-sm h-9 w-9 p-0"
+    >
+      {/* Icons switch with CSS so the first paint is already right. */}
+      <Moon className="only-light h-[18px] w-[18px]" aria-hidden="true" />
+      <Sun className="only-dark h-[18px] w-[18px]" aria-hidden="true" />
+    </button>
+  );
+}
diff --git a/src/components/TokenUsageBar.tsx b/src/components/TokenUsageBar.tsx
index bd596aa..a79f489 100644
--- a/src/components/TokenUsageBar.tsx
+++ b/src/components/TokenUsageBar.tsx
@@ -11,14 +11,11 @@ export function TokenUsageBar({ feature, current, daily }: TokenUsageBarProps) {
 
   return (
     <div className="flex items-center gap-3">
-      <span className="text-xs text-gray-500 w-20 capitalize">{feature}</span>
-      <div className="flex-1 bg-gray-100 rounded-full h-2 overflow-hidden">
-        <div
-          className="h-full bg-indigo-500 rounded-full transition-all"
-          style={{ width: `${percentage}%` }}
-        />
+      <span className="w-20 text-xs capitalize text-ink-muted">{feature}</span>
+      <div className="h-2 flex-1 overflow-hidden rounded-full bg-surface-2">
+        <div className="h-full rounded-full bg-brand transition-all" style={{ width: `${percentage}%` }} />
       </div>
-      <span className="text-xs text-gray-400 w-16 text-right">
+      <span className="w-16 text-right text-xs text-ink-subtle">
         {(current / 1000).toFixed(1)}K / {daily}M
       </span>
     </div>
diff --git a/src/components/TopicForm.tsx b/src/components/TopicForm.tsx
new file mode 100644
index 0000000..9ef5701
--- /dev/null
+++ b/src/components/TopicForm.tsx
@@ -0,0 +1,88 @@
+"use client";
+import { useId, useState } from "react";
+import { Sparkles } from "lucide-react";
+import { useI18n } from "@/i18n/I18nProvider";
+
+interface TopicFormProps {
+  title: string;
+  placeholder: string;
+  submitLabel: string;
+  busy?: boolean;
+  /** Pre-fill, e.g. the topic of a request that failed. */
+  defaultTopic?: string;
+  /** Extra options (difficulty, level, ...) shown under the topic field. */
+  children?: React.ReactNode;
+  onSubmit: (topic: string) => void;
+}
+
+const EXAMPLES = ["topicForm.example1", "topicForm.example2", "topicForm.example3", "topicForm.example4"] as const;
+
+/** Shared "choose a topic" card used by the quiz, flashcard and roadmap pages. */
+export function TopicForm({ title, placeholder, submitLabel, busy, defaultTopic = "", children, onSubmit }: TopicFormProps) {
+  const { t } = useI18n();
+  const id = useId();
+  const [topic, setTopic] = useState(defaultTopic);
+  const [touched, setTouched] = useState(false);
+  const empty = !topic.trim();
+
+  return (
+    <form
+      noValidate
+      className="card mx-auto max-w-2xl p-5 sm:p-7"
+      onSubmit={(e) => {
+        e.preventDefault();
+        setTouched(true);
+        if (!empty && !busy) onSubmit(topic.trim());
+      }}
+    >
+      <h2 className="text-lg font-semibold text-ink">{title}</h2>
+
+      <div className="mt-5">
+        <label htmlFor={`${id}-topic`} className="label">
+          {t("topicForm.topicLabel")}
+        </label>
+        <input
+          id={`${id}-topic`}
+          type="text"
+          value={topic}
+          maxLength={200}
+          onChange={(e) => setTopic(e.target.value)}
+          placeholder={placeholder}
+          autoComplete="off"
+          enterKeyHint="go"
+          aria-invalid={touched && empty}
+          aria-describedby={touched && empty ? `${id}-err` : undefined}
+          className="field"
+        />
+        {touched && empty && (
+          <p id={`${id}-err`} className="mt-1.5 text-sm font-medium text-danger-ink">
+            {t("topicForm.emptyTopic")}
+          </p>
+        )}
+        <div className="mt-3 flex flex-wrap items-center gap-2">
+          <span className="text-xs font-medium text-ink-subtle">{t("topicForm.examplesLabel")}:</span>
+          {EXAMPLES.map((key) => (
+            <button
+              key={key}
+              type="button"
+              onClick={() => {
+                setTopic(t(key));
+                setTouched(false);
+              }}
+              className="rounded-full border border-line bg-surface-2 px-3 py-1 text-xs font-medium text-ink-muted transition-colors hover:border-brand hover:text-brand-ink"
+            >
+              {t(key)}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {children && <div className="mt-6 grid gap-5 sm:grid-cols-2">{children}</div>}
+
+      <button type="submit" disabled={busy} className="btn btn-primary mt-7 w-full sm:w-auto">
+        <Sparkles className="h-4 w-4" aria-hidden="true" />
+        {submitLabel}
+      </button>
+    </form>
+  );
+}
diff --git a/src/components/ui/EmptyState.tsx b/src/components/ui/EmptyState.tsx
new file mode 100644
index 0000000..69b4b8b
--- /dev/null
+++ b/src/components/ui/EmptyState.tsx
@@ -0,0 +1,24 @@
+import type { LucideIcon } from "lucide-react";
+
+export function EmptyState({
+  icon: Icon,
+  title,
+  description,
+  action,
+}: {
+  icon: LucideIcon;
+  title: string;
+  description: string;
+  action?: React.ReactNode;
+}) {
+  return (
+    <div className="card flex flex-col items-center px-6 py-12 text-center">
+      <span className="flex h-12 w-12 items-center justify-center rounded-full bg-surface-2 text-ink-muted">
+        <Icon className="h-6 w-6" aria-hidden="true" />
+      </span>
+      <h2 className="mt-4 text-lg font-semibold text-ink">{title}</h2>
+      <p className="mt-1.5 max-w-sm text-sm leading-relaxed text-ink-muted">{description}</p>
+      {action && <div className="mt-6">{action}</div>}
+    </div>
+  );
+}
diff --git a/src/components/ui/PageHeader.tsx b/src/components/ui/PageHeader.tsx
new file mode 100644
index 0000000..2d082a1
--- /dev/null
+++ b/src/components/ui/PageHeader.tsx
@@ -0,0 +1,25 @@
+import type { LucideIcon } from "lucide-react";
+
+interface PageHeaderProps {
+  icon: LucideIcon;
+  title: string;
+  description?: string;
+  children?: React.ReactNode;
+}
+
+export function PageHeader({ icon: Icon, title, description, children }: PageHeaderProps) {
+  return (
+    <div className="mb-8 flex flex-col gap-4 sm:mb-10 sm:flex-row sm:items-end sm:justify-between">
+      <div className="flex min-w-0 items-start gap-4">
+        <span className="mt-1 flex h-11 w-11 shrink-0 items-center justify-center rounded-xl bg-brand-soft text-brand-ink">
+          <Icon className="h-[22px] w-[22px]" aria-hidden="true" />
+        </span>
+        <div className="min-w-0">
+          <h1 className="font-display text-title font-semibold text-ink">{title}</h1>
+          {description && <p className="mt-2 max-w-2xl text-[0.9375rem] leading-relaxed text-ink-muted">{description}</p>}
+        </div>
+      </div>
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/ui/PageShell.tsx b/src/components/ui/PageShell.tsx
new file mode 100644
index 0000000..ed49560
--- /dev/null
+++ b/src/components/ui/PageShell.tsx
@@ -0,0 +1,19 @@
+import { clsx } from "clsx";
+
+/** Page container. `id="main"` is the skip-link target. */
+export function PageShell({ children, width = "default" }: { children: React.ReactNode; width?: "default" | "narrow" | "wide" }) {
+  return (
+    <main
+      id="main"
+      tabIndex={-1}
+      className={clsx(
+        "mx-auto w-full px-4 pt-8 outline-none sm:px-6 sm:pt-12",
+        width === "narrow" && "max-w-2xl",
+        width === "default" && "max-w-4xl",
+        width === "wide" && "max-w-6xl",
+      )}
+    >
+      {children}
+    </main>
+  );
+}
diff --git a/src/components/ui/ProgressBar.tsx b/src/components/ui/ProgressBar.tsx
new file mode 100644
index 0000000..8d27615
--- /dev/null
+++ b/src/components/ui/ProgressBar.tsx
@@ -0,0 +1,15 @@
+export function ProgressBar({ value, max, label }: { value: number; max: number; label: string }) {
+  const pct = max > 0 ? Math.min(100, Math.max(0, (value / max) * 100)) : 0;
+  return (
+    <div
+      role="progressbar"
+      aria-label={label}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      aria-valuenow={value}
+      className="h-1.5 w-full overflow-hidden rounded-full bg-surface-2"
+    >
+      <div className="h-full rounded-full bg-brand transition-[width] duration-300" style={{ width: `${pct}%` }} />
+    </div>
+  );
+}
diff --git a/src/components/ui/SegmentedControl.tsx b/src/components/ui/SegmentedControl.tsx
new file mode 100644
index 0000000..edb0e0e
--- /dev/null
+++ b/src/components/ui/SegmentedControl.tsx
@@ -0,0 +1,45 @@
+"use client";
+import { useId } from "react";
+import { clsx } from "clsx";
+
+interface SegmentedControlProps<T extends string | number> {
+  label: string;
+  value: T;
+  options: readonly { value: T; label: string }[];
+  onChange: (value: T) => void;
+}
+
+/** Radio group styled as a segmented control. Arrow keys work natively. */
+export function SegmentedControl<T extends string | number>({ label, value, options, onChange }: SegmentedControlProps<T>) {
+  const name = useId();
+  return (
+    <fieldset className="min-w-0">
+      <legend className="label">{label}</legend>
+      <div className="grid auto-cols-fr grid-flow-col gap-1 rounded-xl border border-line bg-surface-2 p-1">
+        {options.map((opt) => {
+          const checked = opt.value === value;
+          return (
+            <label
+              key={String(opt.value)}
+              className={clsx(
+                "relative flex min-h-10 cursor-pointer items-center justify-center rounded-lg px-2 text-center text-sm font-semibold transition-colors",
+                "has-[:focus-visible]:outline-2 has-[:focus-visible]:outline-offset-1 has-[:focus-visible]:outline-focus",
+                checked ? "bg-surface-raised text-ink shadow-card" : "text-ink-muted hover:text-ink",
+              )}
+            >
+              <input
+                type="radio"
+                name={name}
+                value={String(opt.value)}
+                checked={checked}
+                onChange={() => onChange(opt.value)}
+                className="sr-only"
+              />
+              {opt.label}
+            </label>
+          );
+        })}
+      </div>
+    </fieldset>
+  );
+}
diff --git a/src/lib/nav.ts b/src/lib/nav.ts
new file mode 100644
index 0000000..654ea09
--- /dev/null
+++ b/src/lib/nav.ts
@@ -0,0 +1,25 @@
+import { ChartColumn, GalleryVerticalEnd, House, ListChecks, Network, Route, type LucideIcon } from "lucide-react";
+import type { MessageKey } from "@/i18n/messages";
+
+export interface NavItem {
+  href: string;
+  label: MessageKey;
+  icon: LucideIcon;
+  /** Shown in the mobile bottom bar (space for five). */
+  mobile: boolean;
+}
+
+/** One list for the desktop header, the mobile bar and the home page. */
+export const NAV_ITEMS: readonly NavItem[] = [
+  { href: "/", label: "nav.home", icon: House, mobile: true },
+  { href: "/quiz", label: "nav.quiz", icon: ListChecks, mobile: true },
+  { href: "/flashcards", label: "nav.flashcards", icon: GalleryVerticalEnd, mobile: true },
+  { href: "/roadmap", label: "nav.roadmap", icon: Route, mobile: true },
+  { href: "/progress", label: "nav.progress", icon: ChartColumn, mobile: true },
+  { href: "/concepts", label: "nav.concepts", icon: Network, mobile: false },
+];
+
+export function isActive(pathname: string | null, href: string): boolean {
+  if (!pathname) return false;
+  return href === "/" ? pathname === "/" : pathname === href || pathname.startsWith(`${href}/`);
+}
diff --git a/src/lib/theme.ts b/src/lib/theme.ts
new file mode 100644
index 0000000..07589e4
--- /dev/null
+++ b/src/lib/theme.ts
@@ -0,0 +1,78 @@
+/**
+ * Light/dark theme.
+ *
+ * With nothing stored the page follows `prefers-color-scheme` (pure CSS).
+ * A stored choice sets `data-theme` on <html>; the inline script below applies
+ * it before first paint so there is no flash. Choosing the theme the system
+ * already prefers clears the stored value, so the page follows the system again.
+ */
+export type Theme = "light" | "dark";
+
+export const THEME_STORAGE_KEY = "learnpath.theme.v1";
+const CHANGED_EVENT = "learnpath:theme-changed";
+
+/** Runs in <head> before the body renders. Kept tiny and dependency-free. */
+export const THEME_INIT_SCRIPT = `(function(){try{var t=localStorage.getItem(${JSON.stringify(
+  THEME_STORAGE_KEY,
+)});if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t);}catch(e){}})();`;
+
+function systemTheme(): Theme {
+  try {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  } catch {
+    return "light";
+  }
+}
+
+/** The theme currently on screen. */
+export function getEffectiveTheme(): Theme {
+  const attr = document.documentElement.getAttribute("data-theme");
+  return attr === "dark" || attr === "light" ? attr : systemTheme();
+}
+
+/**
+ * Apply a colour change in one frame: without this, elements with a colour
+ * transition (buttons, tabs) fade on their own schedule and the page is
+ * briefly half light, half dark.
+ */
+function withoutTransitions(apply: () => void): void {
+  const style = document.createElement("style");
+  style.textContent = "*,*::before,*::after{transition:none!important}";
+  document.head.appendChild(style);
+  apply();
+  void window.getComputedStyle(document.body).backgroundColor; // flush styles while transitions are off
+  window.requestAnimationFrame(() => window.requestAnimationFrame(() => style.remove()));
+}
+
+export function setTheme(theme: Theme): void {
+  withoutTransitions(() => applyTheme(theme));
+  window.dispatchEvent(new Event(CHANGED_EVENT));
+}
+
+function applyTheme(theme: Theme): void {
+  const root = document.documentElement;
+  const followSystem = theme === systemTheme();
+  try {
+    if (followSystem) window.localStorage.removeItem(THEME_STORAGE_KEY);
+    else window.localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    // storage blocked: the choice still applies to this page
+  }
+  if (followSystem) root.removeAttribute("data-theme");
+  else root.setAttribute("data-theme", theme);
+}
+
+export function subscribeTheme(onChange: () => void): () => void {
+  window.addEventListener(CHANGED_EVENT, onChange);
+  let media: MediaQueryList | null = null;
+  try {
+    media = window.matchMedia("(prefers-color-scheme: dark)");
+    media.addEventListener("change", onChange);
+  } catch {
+    media = null;
+  }
+  return () => {
+    window.removeEventListener(CHANGED_EVENT, onChange);
+    media?.removeEventListener("change", onChange);
+  };
+}
diff --git a/tests/components/ProgressChart.test.tsx b/tests/components/ProgressChart.test.tsx
index 398fee7..03b2241 100644
--- a/tests/components/ProgressChart.test.tsx
+++ b/tests/components/ProgressChart.test.tsx
@@ -5,13 +5,18 @@ import { ProgressChart } from "@/components/ProgressChart";
 describe("ProgressChart", () => {
   it("renders title", () => {
     render(<ProgressChart data={[{ label: "Mon", value: 5 }]} title="Weekly" />);
-    expect(screen.getByText("Weekly")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "Weekly" })).toBeInTheDocument();
   });
 
   it("renders data labels", () => {
     render(<ProgressChart data={[{ label: "Mon", value: 3 }, { label: "Tue", value: 5 }]} title="t" />);
-    expect(screen.getByText("Mon")).toBeInTheDocument();
-    expect(screen.getByText("Tue")).toBeInTheDocument();
+    expect(screen.getAllByText("Mon").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Tue").length).toBeGreaterThan(0);
+  });
+
+  it("has an accessible table with the exact values", () => {
+    render(<ProgressChart data={[{ label: "Mon", value: 3 }]} title="Weekly" />);
+    expect(screen.getByRole("table")).toHaveTextContent("Mon3");
   });
 
   it("renders values", () => {
diff --git a/tests/components/QuizCard.test.tsx b/tests/components/QuizCard.test.tsx
index f0b77dc..1b4bab3 100644
--- a/tests/components/QuizCard.test.tsx
+++ b/tests/components/QuizCard.test.tsx
@@ -31,6 +31,12 @@ describe("QuizCard", () => {
     expect(onAnswer).toHaveBeenCalledWith(1);
   });
 
+  it("marks a wrong answer and names the correct letter", () => {
+    render(<QuizCard question={question} questionNumber={1} totalQuestions={5} onAnswer={vi.fn()} selectedAnswer={0} showResult />);
+    expect(screen.getByText("Not quite")).toBeInTheDocument();
+    expect(screen.getByText(/The answer is B\./)).toBeInTheDocument();
+  });
+
   it("shows explanation when showResult", () => {
     render(<QuizCard question={question} questionNumber={1} totalQuestions={5} onAnswer={vi.fn()} showResult />);
     expect(screen.getByText(/Basic math/)).toBeInTheDocument();
@@ -38,6 +44,6 @@ describe("QuizCard", () => {
 
   it("shows difficulty badge", () => {
     render(<QuizCard question={question} questionNumber={1} totalQuestions={5} onAnswer={vi.fn()} />);
-    expect(screen.getByText("easy")).toBeInTheDocument();
+    expect(screen.getByText("Easy")).toBeInTheDocument();
   });
 });
diff --git a/tests/components/RoadmapNode.test.tsx b/tests/components/RoadmapNode.test.tsx
index 7c7629e..9139925 100644
--- a/tests/components/RoadmapNode.test.tsx
+++ b/tests/components/RoadmapNode.test.tsx
@@ -1,5 +1,5 @@
-import { describe, it, expect } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { RoadmapNode } from "@/components/RoadmapNode";
 
 describe("RoadmapNode", () => {
@@ -28,8 +28,25 @@ describe("RoadmapNode", () => {
     expect(screen.getByText(/2 hours/)).toBeInTheDocument();
   });
 
-  it("shows checkmark for completed", () => {
+  it("announces the completed state instead of the step number", () => {
     render(<RoadmapNode step={{ ...step, status: "completed" }} index={0} isLast={false} />);
-    expect(screen.getByText("✓")).toBeInTheDocument();
+    expect(screen.getByText("Step 1, Completed")).toBeInTheDocument();
+    expect(screen.queryByText("1")).not.toBeInTheDocument();
+  });
+
+  it("offers 'Mark as done' only on the current step", () => {
+    const onComplete = vi.fn();
+    const { rerender } = render(<RoadmapNode step={{ ...step, status: "current" }} index={1} isLast={false} onComplete={onComplete} />);
+    fireEvent.click(screen.getByRole("button", { name: "Mark as done" }));
+    expect(onComplete).toHaveBeenCalled();
+    rerender(<RoadmapNode step={step} index={1} isLast={false} onComplete={onComplete} />);
+    expect(screen.queryByRole("button", { name: "Mark as done" })).not.toBeInTheDocument();
+  });
+
+  it("gives upcoming steps readable (non-white) number text", () => {
+    render(<RoadmapNode step={step} index={2} isLast={false} />);
+    const badge = screen.getByText("3");
+    expect(badge.className).toContain("text-ink-muted");
+    expect(badge.className).not.toContain("text-white");
   });
 });
diff --git a/tests/design/contrast.test.ts b/tests/design/contrast.test.ts
new file mode 100644
index 0000000..f9dc1a5
--- /dev/null
+++ b/tests/design/contrast.test.ts
@@ -0,0 +1,65 @@
+// @vitest-environment node
+/**
+ * WCAG AA contrast for the design tokens, computed from globals.css itself so
+ * a colour change that breaks contrast fails CI.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const css = readFileSync(path.resolve(__dirname, "../../src/app/globals.css"), "utf8");
+
+function tokens(selector: RegExp): Record<string, string> {
+  const block = css.match(selector)?.[1] ?? "";
+  return Object.fromEntries([...block.matchAll(/--([\w-]+):\s*(#[0-9a-fA-F]{6})/g)].map((m) => [m[1], m[2].toLowerCase()]));
+}
+
+const light = tokens(/:root\s*\{([^}]*)\}/);
+const darkMedia = tokens(/:root:not\(\[data-theme="light"\]\)\s*\{([^}]*)\}/);
+const darkToggle = tokens(/:root\[data-theme="dark"\]\s*\{([^}]*)\}/);
+
+function luminance(hex: string): number {
+  const [r, g, b] = [1, 3, 5].map((i) => {
+    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// [text token, background token, minimum ratio]
+const TEXT_PAIRS: [string, string, number][] = [
+  ["ink", "canvas", 4.5], ["ink", "surface", 4.5], ["ink", "surface-2", 4.5], ["ink", "surface-raised", 4.5],
+  ["ink-muted", "canvas", 4.5], ["ink-muted", "surface", 4.5], ["ink-muted", "surface-2", 4.5],
+  ["ink-subtle", "canvas", 4.5], ["ink-subtle", "surface", 4.5], ["ink-subtle", "surface-2", 4.5],
+  ["on-brand", "brand", 4.5], ["on-brand", "brand-hover", 4.5], ["on-brand", "success", 4.5],
+  ["brand-ink", "brand-soft", 4.5], ["brand-ink", "surface", 4.5], ["brand-ink", "canvas", 4.5],
+  ["accent-ink", "accent-soft", 4.5], ["success-ink", "success-soft", 4.5], ["success-ink", "surface", 4.5],
+  ["danger-ink", "danger-soft", 4.5], ["danger-ink", "surface", 4.5], ["warning-ink", "warning-soft", 4.5],
+  ["canvas", "ink", 4.5],
+];
+// Non-text UI (WCAG 1.4.11): input borders, focus ring.
+const UI_PAIRS: [string, string, number][] = [
+  ["line-strong", "surface", 3], ["focus", "surface", 3], ["focus", "canvas", 3], ["brand", "surface", 3],
+];
+
+describe("design tokens", () => {
+  it("define the dark theme identically for the system setting and the toggle", () => {
+    expect(Object.keys(darkMedia).length).toBeGreaterThan(20);
+    expect(darkMedia).toEqual(darkToggle);
+  });
+
+  for (const [name, t] of [["light", light], ["dark", darkToggle]] as const) {
+    for (const [fg, bg, min] of [...TEXT_PAIRS, ...UI_PAIRS]) {
+      it(`${name}: ${fg} on ${bg} ≥ ${min}:1`, () => {
+        expect(t[fg], fg).toBeDefined();
+        expect(t[bg], bg).toBeDefined();
+        expect(contrast(t[fg], t[bg])).toBeGreaterThanOrEqual(min);
+      });
+    }
+  }
+});
diff --git a/tests/i18n/no-hardcoded-text.test.ts b/tests/i18n/no-hardcoded-text.test.ts
new file mode 100644
index 0000000..c41a110
--- /dev/null
+++ b/tests/i18n/no-hardcoded-text.test.ts
@@ -0,0 +1,37 @@
+// @vitest-environment node
+/**
+ * Guard against UI text typed straight into components: JSX text nodes in
+ * src/app and src/components must come from the language files.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(__dirname, "../../src");
+// Proper nouns that are the same in every language.
+const ALLOWED = new Set(["Sasa Teguh", "LearnPath"]);
+
+function files(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const full = path.join(dir, name);
+    if (statSync(full).isDirectory()) return files(full);
+    return full.endsWith(".tsx") ? [full] : [];
+  });
+}
+
+describe("components", () => {
+  it("contain no hard-coded user-visible words in JSX text", () => {
+    const offenders: string[] = [];
+    for (const file of [...files(path.join(ROOT, "app")), ...files(path.join(ROOT, "components"))]) {
+      const source = readFileSync(file, "utf8").replace(/\{\/\*[\s\S]*?\*\/\}/g, "");
+      for (const match of source.matchAll(/>([^<>{}]*[A-Za-z]{2,}[^<>{}]*)</g)) {
+        const text = match[1].trim();
+        if (!text || ALLOWED.has(text) || /^[\s=&|?:()!.,'"\w]*=>/.test(text)) continue;
+        // Skip TypeScript generics and comparisons that look like JSX text.
+        if (/[;=]|&&|\|\|/.test(text)) continue;
+        offenders.push(`${path.relative(ROOT, file)}: "${text}"`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

From 99a41bffc7a888ed57f281e8c60a7504dd9817f1 Mon Sep 17 00:00:00 2001
From: Muhammad Aiman <84276911+aimanmalib@users.noreply.github.com>
Date: Tue, 20 Oct 2026 09:46:51 +0000
Subject: [PATCH 4/4] docs: README for BM/EN support and themes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index f9b49cf..9f9b892 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 **Adaptive learning with any OpenAI-compatible LLM**
 
-> AI-generated quizzes, flashcards and learning roadmaps, with spaced repetition and a simple progress view.
+> AI-generated quizzes, flashcards and learning roadmaps, with spaced repetition and a simple progress view. In English and Bahasa Melayu.
 
 [![CI](https://github.com/aimanmalib/learnpath/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/learnpath/actions/workflows/ci.yml)
 [![Next.js 16](https://img.shields.io/badge/Next.js-16-black.svg)](https://nextjs.org/)
@@ -24,14 +24,22 @@ Every AI feature goes through one provider layer (`src/lib/llm/`) that speaks th
 | **Learning Roadmap** | Builds a step-by-step plan for a topic at beginner / intermediate / advanced level |
 | **Progress Tracker** | Shows the sessions, scores and token usage from your current visit (kept in memory, not saved) |
 | **Concept Map** | A static sample map of connected concepts (not generated by the LLM yet) |
+| **Bahasa Melayu + English** | Every screen in BM or English (switch in the top bar). The AI answers in the language you are reading |
+| **Light and dark themes** | Follows your device setting; the moon/sun button overrides it |
 
-There are also two API-only routes with no page yet: `POST /api/chat` (single message, optional streaming) and `POST /api/analyze` (study-session analysis).
+### Languages
+
+- All UI text lives in `src/i18n/messages/en.ts` and `ms.ts`. A test fails if a key exists in one language but not the other, if placeholders differ, or if the BM file contains common Indonesian words (`karena`, `harus`, `kirim`, ...).
+- The first visit uses your browser language (`ms`/`ms-MY` → BM, anything else → English). Your choice is saved in `localStorage` and mirrored to a cookie so the server renders the page in the same language.
+- Every API call sends `language: "en" | "ms"`. The server adds an instruction to the prompt to answer in that language; for BM it asks for standard Malaysian spelling (Dewan Bahasa dan Pustaka) and names Indonesian words to avoid. How well the model follows it depends on the model you choose.
+
+There are also two API-only routes with no page yet: `POST /api/chat` (single message, optional streaming) and `POST /api/analyze` (study-session analysis). Both accept the same optional `language` field.
 
 ## Bring your own key (how the demo works)
 
 The public demo has no server-side key. Each visitor uses their own:
 
-1. Click **Settings** in the top bar.
+1. Click **Settings** (**Tetapan** in BM, the key icon on phones) in the top bar.
 2. Pick a provider, keep the suggested model or type another, and paste your API key.
 3. Press **Save**. **Forget key** removes it again.
 
@@ -114,14 +122,15 @@ npm run build        # production build
 ## Architecture
 
 ```
-Browser (Next.js pages)
+Browser (Next.js pages, UI text from src/i18n/messages/{en,ms}.ts)
   │  Settings panel → localStorage (provider, model, key)
-  │  fetch /api/* with x-llm-provider / x-llm-model / x-llm-key
+  │  fetch /api/* with x-llm-provider / x-llm-model / x-llm-key, body includes language: "en" | "ms"
   ▼
 API routes  /api/quiz · /api/flashcards · /api/roadmap · /api/chat · /api/analyze
-  │  src/lib/llm/server.ts  resolve: server env key → else request headers → else 400
-  │                         allowlist of provider base URLs, max_tokens cap
-  │  src/lib/llm/client.ts  POST {baseUrl}/chat/completions, friendly upstream errors
+  │  src/lib/llm/server.ts    resolve: server env key → else request headers → else 400
+  │                           allowlist of provider base URLs, max_tokens cap
+  │  src/lib/llm/language.ts  "answer in English / Bahasa Melayu (Malaysia)" prompt instruction
+  │  src/lib/llm/client.ts    POST {baseUrl}/chat/completions, friendly upstream errors
   ▼
 OpenAI-compatible provider (OpenAI, OpenRouter, Groq, DeepSeek, Together, Mistral, MiMo, Ollama, …)
 ```
@@ -129,7 +138,8 @@ OpenAI-compatible provider (OpenAI, OpenRouter, Groq, DeepSeek, Together, Mistra
 ## Tech stack
 
 - Next.js 16 (App Router), React 19, TypeScript
-- Tailwind CSS 4
+- Tailwind CSS 4 with colour tokens (light + dark) in `src/app/globals.css`; a test checks WCAG AA contrast for every text/background pair
+- lucide-react icons, Inter + Fraunces (self-hosted by `next/font`)
 - Zustand (state)
 - SM-2 spaced repetition
 - Vitest + Testing Library