docs: verify and refactor documentation to match current codebase

docs/CSS.md

@@ -1,21 +1,33 @@
 # CSS Architecture
 
-## File Structure
+## Source files (`app/public/assets/css/`)
 
-- **variables.css** — all CSS custom properties (single source of truth for every color/token)
-- **common.css** — reset, header/nav, search bar, accessibility utilities (loaded on all pages)
-- **main.css** — home page
-- **search.css** — search/directory page
-- **tfe.css** — individual thesis page
-- **apropos.css** — about + licence pages
-- **system.css** — admin system dashboard
-- **admin.css** — admin section (loaded alongside `common.css` on every admin page)
-- **modern-normalize.min.css** — third-party reset (minified, do not edit)
+- **`variables.css`** — all CSS custom properties (colors, spacing, sizing tokens)
+- **`colors.css`** — colour tokens (referenced by `variables.css`)
+- **`reset.css`** / **`modern-normalize.min.css`** — resets
+- **`base.css`** — base element styles
+- **`common.css`** — shared components (header/nav, search bar, accessibility, buttons)
+- **`typography.css`** — type scale
+- **`utilities.css`** — utility classes and spacing tokens
+- **`style.css`** — main public entry point (via `@import` chain)
+- Page-specific: **`public.css`** (home), **`tfe.css`**, **`repertoire.css`**, **`content-page.css`** (about/licences), **`system.css`** (admin system dashboard), **`file-access.css`**, **`admin.css`** (admin section)
+- Form: **`form-base.css`** + **`form-admin.css`** (plus FilePond vendor CSS)
+
+## Build / bundling
+
+Source CSS is **bundled and minified** by `scripts/build-css.mjs` (lightningcss)
+into `app/public/assets/dist/*.min.css`:
+
+- `base.min.css` — resolves the `@import` chain in `style.css` into one file (eliminates ~17 sequential imports)
+- `admin.min.css` — minified `admin.css`
+- `form.min.css` — `form-base.css` + `form-admin.css` + FilePond vendor CSS
+- plus individual `.min.css` for the page-specific files
+
+Run with `just build-css` / `just dev-build`. Never commit hand-edits into
+`dist/` — they are generated.
 
 ## Rules
 
-- Every color value lives in `variables.css` as a CSS custom property.
-- No hardcoded hex, rgb(), or rgba() in any other file.
-- All files `@import url("./variables.css")` at the top.
+- Colour values live in `variables.css`/`colors.css` as custom properties; avoid hardcoding hex/rgb in other files.
 - Admin and public share the same token names — no separate admin theme.
-- No dark-mode media query. System page uses the same light tokens as the rest of the admin section.
+- `modern-normalize.min.css` and FilePond vendor CSS are third-party (minified — do not edit).