UI_OVERHAUL.md - cdnV2 -

UI_OVERHAUL.md (2890B)
      1 # UI overhaul
      2 
      3 Tracking document for the UI redesign. Scope is templates, CSS and JS; backend changes are limited to
      4 allow-listing the new static files in `app/main.py`.
      5 
      6 ## Findings that motivated this
      7 
      8 - `app/templates/index.html` was an 84 KB monolith rendering seven page types with ~800 lines of inline CSS
      9   and ~800 lines of inline JS, so every folder page shipped all of it.
     10 - Two CSS layers fought each other: legacy variables aliased onto `--ui-*`, overridden with `!important`.
     11   Breadcrumb styles were duplicated, and four other templates re-declared their own `:root`.
     12 - The file page had no preview.
     13 - Copy feedback was a 0.8 s border flash; upload errors used `alert()`; dialogs lacked roles, focus
     14   handling and Esc; no `<main>` or skip link.
     15 - `manifest.json` theme/background (`#000000`) disagreed with the page `theme-color`; `og:image` was relative.
     16 
     17 ## Constraint: instant folders
     18 
     19 Folder pages are built both by Jinja and by `static/fasttree.js` from `_listing.html` macros.
     20 `tests/test_fast_tree.py` asserts they are identical. Listing markup changes go through the macros and the
     21 placeholder contract only.
     22 
     23 ## Phases
     24 
     25 - [x] **1. Foundation** - shared `base.html`, CSS to `static/app.css`, JS to `static/app.js` (both cache-busted with a
     26       content hash), one token set, legacy aliases and `!important` hacks removed, `index.html` split into
     27       per-page `_page_*.html` partials, all five templates on one layout. The shared JS now loads on every page
     28       (before, `/documentation`, `/stats`, etc. had no breadcrumb JS on a direct load).
     29 - [x] **2. Design system** - tokens for surfaces/text/brand/status/file-types, light + dark + system with a persistent
     30       toggle (applied before first paint, no flash), brand blue accent with the logo's orange as a rare highlight.
     31 - [x] **3. Components** - navbar with a More menu, listing with colour-coded file-type icons and sorting, file page with
     32       previews (image/video/audio/PDF/text) + labelled link rows + embed snippets, upload queue, toasts, native
     33       `<dialog>` modals, tabs, empty/404 states.
     34       (Upload stays a single request per drop so multi-file drops keep their shared batch page; the queue shows
     35       per-file rows with one shared progress value.)
     36 - [x] **4. Polish** - axe-core audit clean (0 violations on 13 pages x light/dark x desktop/mobile), underlined in-text
     37       links, focusable scroll regions, contrast fixes, h1 on every page, manifest colours match the page, absolute
     38       `og:image`, README updated, `app.css`/`app.js` served gzipped (~22 KB total, cached).
     39       Not done: SRI on the Turbo script (can't verify the live CDN bytes from here; vendoring Turbo is the safer
     40       follow-up) and a configurable site name (needs a backend setting).
     41 
     42 ## Safety rule for previews
     43 
     44 Uploaded HTML/SVG is never rendered inline on the main origin. It is shown as source text only.