diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d824fe4..c4eaf01 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -136,6 +136,16 @@ MCP tool handlers ┘
 ### Tools (14)
 `list_notes`, `get_note`, `create_note`, `update_note`, `trash_note`, `restore_note`, `archive_note`, `unarchive_note`, `delete_note`, `search_notes`, `list_tags`, `pin_note`, `reorder_notes`, `upload_image`
 
+## Dark Mode
+
+Theme switching uses CSS variable overrides on the `<html>` element:
+
+- **CSS**: `[data-theme="dark"]` attribute on `<html>` overrides all `--bg-*`, `--text-*`, `--border-*`, and `--primary-*` variables defined in `src/app.css`
+- **Persistence**: preference stored as `theme` in the existing `userPreferences` key-value system (values: `"system"` | `"light"` | `"dark"`)
+- **FOUC prevention**: a blocking inline `<script>` in `app.html` reads the preference from localStorage and sets `data-theme` before any content renders
+- **Reactivity**: a `$effect` in the root `+layout.svelte` watches the theme store and updates `document.documentElement.dataset.theme` on change
+- **Note card colors**: `getNoteColor()` in `src/lib/utils/colors.ts` accepts a `dark` boolean and returns the appropriate color variant per theme
+
 ## File Organization
 
 ```
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index a656292..c1bc3bd 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -64,6 +64,12 @@
 - Fog, Storm, Dusk, Blossom, Clay, Chalk
 - Colors adapt to note theme
 
+### Dark Mode
+- Three-way theme toggle: System / Light / Dark (in Settings > Preferences)
+- Dark mode uses a warm parchment variant — retro aesthetic preserved in both themes
+- Respects system `prefers-color-scheme` preference by default
+- FOUC-free: theme applied before first paint via a blocking inline script
+
 ### Pin Notes
 - Pin important notes to always appear at top
 - Pinned section separated from unpinned notes