diff --git a/ui/docs/README.md b/ui/docs/README.md
index 55947cc..44c00c4 100644
--- a/ui/docs/README.md
+++ b/ui/docs/README.md
@@ -9,6 +9,9 @@ lives in [`../PLAN.md`](../PLAN.md), the active web finalization in
## Foundation & platform
+- [design-system.md](design-system.md) — the design tokens (colour /
+ spacing / typography), the light/dark theming mechanism, and the
+ component migration conventions.
- [navigation.md](navigation.md) — routes, the sidebar tabs, and the
state-preservation rules across view/tab switches.
- [storage.md](storage.md) — the `KeyStore` and `Cache` abstractions and
diff --git a/ui/docs/design-system.md b/ui/docs/design-system.md
new file mode 100644
index 0000000..30ebe04
--- /dev/null
+++ b/ui/docs/design-system.md
@@ -0,0 +1,103 @@
+# Design system — tokens & theming
+
+The client's visual language lives in a single set of CSS custom
+properties (design tokens). Components reference the tokens
+(`var(--color-…)`, `var(--space-…)`) instead of literal hex/px, so a
+palette change is a one-file edit and the light and dark themes stay in
+lockstep.
+
+## Where the tokens live
+
+- [`src/lib/theme/tokens.css`](../frontend/src/lib/theme/tokens.css) —
+ every token. Theme-independent scales (spacing, radii, typography) sit
+ in `:root`; the colour/shadow palette is defined twice, once for dark
+ (`:root, :root[data-theme="dark"]`) and once for light
+ (`:root[data-theme="light"]`).
+- [`src/lib/theme/base.css`](../frontend/src/lib/theme/base.css) — a
+ small global baseline (document background, default text/typography, a
+ token-driven focus ring, selection colour). Everything else stays in
+ component-scoped `
+
%sveltekit.head%
diff --git a/ui/frontend/src/lib/header/account-menu.svelte b/ui/frontend/src/lib/header/account-menu.svelte
index 80bc601..b5173d4 100644
--- a/ui/frontend/src/lib/header/account-menu.svelte
+++ b/ui/frontend/src/lib/header/account-menu.svelte
@@ -7,8 +7,20 @@ Sessions and Theme) take over.
-->