diff --git a/web/README.md b/web/README.md
index 72af476..a4e6bd6 100644
--- a/web/README.md
+++ b/web/README.md
@@ -74,6 +74,44 @@ dashboard; the grid and the sidebar dropdown both pick it up via the shared
`projects` store). Signed-out routes
(`/login`, `/verify-email`) render without the sidebar.
+## Styling
+
+`style.css` is one global stylesheet (no scoped/component styles) with a
+handful of conventions worth knowing before adding to it:
+
+- **Tokens** (`:root` custom properties): colours (`--bg`, `--surface`,
+ `--border`, `--text`, `--muted`, `--accent`(-text), `--error`, `--warn-bg`/
+ `-border`), a border-radius scale (`--radius-sm` 6px compact controls,
+ `--radius-md` 8px buttons/inputs, `--radius-lg` 10px tiles, `--radius-xl`
+ 12px panels, `--radius-pill`), and two opacity values (`--opacity-disabled`
+ 0.6, `--opacity-ghost` 0.5 for a dragged item's placeholder). Reach for one
+ of these before hand-writing a value that's really just "the same grey
+ border again" or "the same rounding as every other button."
+- **`.field`** is the one themed ``/`