diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..224f9e3
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,11 @@
+# Design Notes
+
+## Settings view
+
+- Current status: implemented through a left-side drawer in `BoardsActivity` plus a modal preferences dialog in `SettingsDialogFragment`/`SettingsPreferencesFragment`.
+- The drawer opens from the toolbar navigation button and left-edge gesture, dims the content behind it, and is constrained to at most one third of the screen width.
+- The drawer shows the authenticated user profile data from `users/me`, lists available workspaces, highlights the active workspace, and refreshes boards after successful workspace switches.
+- Drawer data loading supports retry for recoverable errors and forces sign-out when unauthorized responses are detected.
+- The settings dialog is backed by AndroidX Preferences and includes Theme (Light/Dark/Follow System), Base URL, and API key fields.
+- Save-and-close validates URL and API key drafts, runs health-check verification for credential changes, applies settings immediately, and refreshes drawer/boards state when credentials change.
+- Logout remains available from the drawer with confirmation; it clears stored auth/session workspace state and returns to the login screen.