# Dark Mode & Visual Polish Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Replace the warm-paper light theme with a warm-dark "notebook at night" aesthetic — dark-only, no toggle, paper grain texture, dark terrain map tiles, typography polish. **Architecture:** Pure CSS token swap in `tokens.css` (all components update automatically), grain overlay via `body::after` SVG data URI in `style.css`, map tile URL swap in two Twig templates. No new dependencies, no JS changes, no structural changes. **Tech Stack:** CSS custom properties, inline SVG noise filter, Stadia Maps Alidade Smooth Dark tile CDN, Leaflet.js (already present) ## Global Constraints - All changes in `user/` — commit with `git -C user`, not main-repo git - Dark-only — no `prefers-color-scheme` media query, no light-mode fallback, no toggle - Existing token names in `tokens.css` must not change — only values swap - No new npm/JS dependencies - `make test-ui` must pass after every task (pre-existing P2 FilePond failure is acceptable) - Stadia Maps tile URL: `https://tiles.stadiamaps.com/tiles/alidade_smooth_dark/{z}/{x}/{y}{r}.png` - Stadia attribution (exact): `© Stadia Maps © OpenMapTiles © OpenStreetMap contributors` --- ### Task 1: Dark color tokens **Files:** - Modify: `user/themes/intotheeast/css/tokens.css` **Interfaces:** - Produces: CSS custom properties consumed by every component in `style.css` and Twig templates - [ ] **Step 1: Read the current tokens file** ```bash cat user/themes/intotheeast/css/tokens.css ``` Confirm these token names exist before editing: `--color-paper`, `--color-canvas`, `--color-ink`, `--color-ink-2`, `--color-ink-muted`, `--color-border`, `--color-border-soft`, `--color-accent`, `--color-accent-hover`, `--color-accent-light`, `--color-accent-on`. - [ ] **Step 2: Replace the color block in tokens.css** Replace the entire `:root` color block (from `--color-paper` through `--color-accent-on`) with: ```css /* ── Dark palette (warm notebook) ──────────────────────────────────────── */ --color-paper: #1A1814; /* page background — warm near-black */ --color-canvas: #22201B; /* card surfaces, form backgrounds */ --color-ink: #EDE8DF; /* primary text — warm cream */ --color-ink-2: #B8B0A4; /* body text — muted warm */ --color-ink-muted: #7A7268; /* labels, timestamps, captions */ --color-border: #2E2B25; /* standard dividers */ --color-border-soft: #252219; /* subtle dividers */ --color-accent: #2A8C73; /* teal — lightened for dark contrast */ --color-accent-hover: #236655; /* hover/pressed teal */ --color-accent-light: #1A2E29; /* pale teal tint backgrounds */ --color-accent-on: #FFFFFF; /* text on accent surfaces */ --color-surface-raised: #2A2720; /* elevated surfaces: tooltips, hover */ --color-ink-inverse: #17171A; /* text on accent-coloured buttons */ ``` Keep all non-color tokens (`--text-*`, `--leading-*`, `--space-*`, font variables, etc.) unchanged. - [ ] **Step 3: Verify no syntax errors** ```bash docker exec intotheeast_grav bash -c "cd /var/www/html && php bin/grav clearcache" && curl -s -o /dev/null -w "%{http_code}" http://localhost:8081/trips/japan-korea-2026/dailies ``` Expected: `200` - [ ] **Step 4: Visual smoke check** ```bash curl -s http://localhost:8081/trips/japan-korea-2026/dailies | grep -o 'color: var(--color-paper)' | head -3 ``` Not a definitive check — just confirm the page renders. Open a browser and verify the background is dark and text is cream. - [ ] **Step 5: Run test suite** ```bash make test-ui ``` Expected: 24/25 pass (P2 FilePond is pre-existing failure, all others pass). - [ ] **Step 6: Commit** ```bash git -C user add themes/intotheeast/css/tokens.css git -C user commit -m "feat: switch to warm-dark color tokens" ``` --- ### Task 2: Paper grain texture + hardcoded color fixes + typography **Files:** - Modify: `user/themes/intotheeast/css/style.css` **Interfaces:** - Consumes: dark color tokens from Task 1 - [ ] **Step 1: Find all hardcoded color literals in style.css** ```bash grep -n '#[0-9a-fA-F]\{3,6\}\|background: white\|background:#fff\|color: #\|background-color: #' user/themes/intotheeast/css/style.css ``` Make note of every hit — each one is a candidate to replace with a token. Exceptions: the CSS SVG data URI you are about to add (the noise filter hex values are part of the graphic, not UI colors). - [ ] **Step 2: Add paper grain texture to body** Find the `body` rule in `style.css`. It will look something like: ```css body { background-color: var(--color-paper); color: var(--color-ink); ... } ``` Add a `body::after` rule immediately after the `body` rule: ```css body::after { content: ''; position: fixed; inset: 0; pointer-events: none; z-index: 9998; opacity: 0.035; background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='200' height='200' filter='url(%23noise)' opacity='1'/%3E%3C/svg%3E"); background-repeat: repeat; background-size: 200px 200px; } ``` - [ ] **Step 3: Fix hardcoded login form colors** Find this rule (around line 497): ```css .login-form .button.secondary { background: #f0f0f0; color: #333; text-decoration: none; line-height: 44px; padding: 0 1rem; } ``` Replace with: ```css .login-form .button.secondary { background: var(--color-canvas); color: var(--color-ink); text-decoration: none; line-height: 44px; padding: 0 1rem; } ``` - [ ] **Step 4: Fix any other hardcoded colors found in Step 1** For each hardcoded literal found in Step 1 (excluding the data URI you added): - `#fff` / `white` → `var(--color-canvas)` (if a surface) or `var(--color-paper)` (if a page background) - `#333` / dark grays → `var(--color-ink)` or `var(--color-ink-2)` - `#eee` / light grays → `var(--color-border)` or `var(--color-border-soft)` - `#f0f0f0` / near-white → `var(--color-canvas)` Use judgment: if a hex is inside a gradient or SVG path data, leave it alone. - [ ] **Step 5: Typography — increase entry body paragraph spacing** Find: ```css .entry-body p { margin-bottom: 1.1em; font-size: var(--text-md); line-height: var(--leading-normal); color: var(--color-ink-2); } ``` Change `margin-bottom: 1.1em` to `margin-bottom: 1.4em`. - [ ] **Step 6: Typography — tighten h1/h2 tracking** Find the `h1` and `h2` rules. Any rule that applies `letter-spacing: -0.01em` to an `h1` or `h2` — change it to `-0.02em`. Do not touch h3/h4/h5/h6. - [ ] **Step 7: Stats page — tabular numbers** Find any CSS rule targeting stats numbers (look for `.stat-value`, `.stats-number`, or similar). Add `font-variant-numeric: tabular-nums` to it. If no such specific rule exists, search the template: ```bash grep -n 'stat\|number\|count' user/themes/intotheeast/templates/stats.html.twig | head -20 ``` Then add a targeted rule in style.css for whatever class wraps the numeric values. - [ ] **Step 8: Verify no syntax errors and visual check** ```bash docker exec intotheeast_grav bash -c "cd /var/www/html && php bin/grav clearcache" && curl -s -o /dev/null -w "%{http_code}" http://localhost:8081/trips/japan-korea-2026/dailies ``` Expected: `200`. Open browser — grain should be subtly visible on the dark background. - [ ] **Step 9: Run test suite** ```bash make test-ui ``` Expected: 24/25 (P2 pre-existing). - [ ] **Step 10: Commit** ```bash git -C user add themes/intotheeast/css/style.css git -C user commit -m "feat: add paper grain texture, fix hardcoded colors, improve typography" ``` --- ### Task 3: Dark terrain map tiles **Files:** - Modify: `user/themes/intotheeast/templates/map.html.twig` - Modify: `user/themes/intotheeast/templates/dailies.html.twig` **Interfaces:** - Consumes: Leaflet.js already loaded in both templates - Produces: Stadia Alidade Smooth Dark tiles replacing OpenStreetMap tiles in both map views - [ ] **Step 1: Read current tile setup in both templates** ```bash grep -n "tileLayer\|openstreetmap\|attribution\|stadia" user/themes/intotheeast/templates/map.html.twig user/themes/intotheeast/templates/dailies.html.twig ``` Confirm the current tile URL pattern (`{s}.tile.openstreetmap.org`) in both files. - [ ] **Step 2: Replace tile layer in map.html.twig** Find: ```javascript L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { attribution: '© OpenStreetMap contributors' }).addTo(map); ``` Replace with: ```javascript // TODO: add Stadia API key before launch — free dev use requires no key, production does L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth_dark/{z}/{x}/{y}{r}.png', { maxZoom: 20, attribution: '© Stadia Maps © OpenMapTiles © OpenStreetMap contributors' }).addTo(map); ``` - [ ] **Step 3: Replace tile layer in dailies.html.twig (mini-map)** Apply the identical tile swap to the mini-map `L.tileLayer` call in `dailies.html.twig`. Find the OpenStreetMap tile URL and replace it with the Stadia dark URL (same as Step 2, same attribution, same TODO comment). - [ ] **Step 4: Verify tiles load** ```bash curl -s -o /dev/null -w "%{http_code}" http://localhost:8081/trips/japan-korea-2026/map ``` Expected: `200`. Check the tile URL is in the HTML: ```bash curl -s http://localhost:8081/trips/japan-korea-2026/map | grep -o 'stadiamaps' ``` Expected: `stadiamaps` (appears in the tile URL). Open the map in a browser and confirm: - Dark terrain tiles render (not the default light OSM tiles) - GPX polyline is visible in teal on the dark background - Entry pins render correctly on top - Attribution footer is present - [ ] **Step 5: Check mini-map on dailies page** ```bash curl -s http://localhost:8081/trips/japan-korea-2026/dailies | grep -o 'stadiamaps' ``` Expected: `stadiamaps`. - [ ] **Step 6: Run test suite** ```bash make test-ui ``` Expected: 24/25 (P2 pre-existing). - [ ] **Step 7: Commit** ```bash git -C user add themes/intotheeast/templates/map.html.twig themes/intotheeast/templates/dailies.html.twig git -C user commit -m "feat: switch to Stadia Alidade Smooth Dark map tiles" ``` --- ## Final verification After all 3 tasks: 1. `make test-config && make test-post && make test-ui` — all pass 2. Visual check list (browser, not curl): - `/trips/japan-korea-2026/dailies` — dark warm background, cream text, grain visible, teal accents - `/trips/japan-korea-2026/map` — dark terrain tiles, teal GPX polyline, entry pins - `/trips/japan-korea-2026/dailies/` — dark canvas card, no white boxes - `/post` — form fields readable, no black-on-black inputs - `/trips/japan-korea-2026/stats` — numbers align (tabular-nums) 3. Final hardcoded-literal check: ```bash grep -n '#[0-9a-fA-F]\{3,6\}' user/themes/intotheeast/css/style.css | grep -v 'data:image' ``` All remaining hits should be either intentional (e.g. SVG path data) or documented.