diff --git a/CHANGELOG.md b/CHANGELOG.md index 973f8cc..f4f2a5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,3 +23,5 @@ All notable changes to the public design kit surface are documented here. - Table-management docs clarified as theme-agnostic geometry/semantics contract. - Vapor shell CSS now supports reusable preset selection via `data-vapor-shell` and shared `--shell-*` tokens across default, auto-dark, and explicit `data-theme` modes. +- Demo/scaffold runtime now includes a deterministic vapor preset selection strategy: + `?vapor_shell` → `localStorage["vapor_shell"]` → markup default. diff --git a/bible/decisions/10-decisions.md b/bible/decisions/10-decisions.md index b8eb273..6c7c58a 100644 --- a/bible/decisions/10-decisions.md +++ b/bible/decisions/10-decisions.md @@ -138,7 +138,8 @@ header height and non-Vapor accent choices. **Decision:** Introduce reusable shell palette presets in `theme-vapor` with stable preset IDs and document them in `kit/patterns/theme-vapor/palette-catalog.md`. Presets are selected by `data-vapor-shell` on the root element and resolve shared shell tokens for light/dark backgrounds, -accent gradients, accent borders, and shell height. +accent gradients, accent borders, and shell height. Runtime selection precedence is standardized as +query `vapor_shell` → local storage key `vapor_shell` → markup default preset. **Consequences:** diff --git a/demo/web/static/js/app.js b/demo/web/static/js/app.js index eec7369..2a3e352 100644 --- a/demo/web/static/js/app.js +++ b/demo/web/static/js/app.js @@ -1,2 +1,66 @@ -document.documentElement.classList.add("js"); -document.documentElement.setAttribute("data-theme-mode", "auto"); +(() => { + const root = document.documentElement; + const storageKey = "vapor_shell"; + const queryKey = "vapor_shell"; + const fallbackPreset = "miami-sunset"; + const allowed = new Set([ + "miami-sunset", + "neon-grid", + "laser-flamingo", + "synth-lagoon", + "mall-soft", + "hologram-sky", + "peach-drive", + "ultraviolet-plaza", + "cyber-mint", + ]); + + const normalizePreset = (value) => { + const trimmed = (value || "").trim().toLowerCase(); + if (!trimmed || !allowed.has(trimmed)) { + return ""; + } + return trimmed; + }; + + const setPreset = (value) => { + const preset = normalizePreset(value); + if (!preset) { + return false; + } + root.setAttribute("data-vapor-shell", preset); + return true; + }; + + root.classList.add("js"); + root.setAttribute("data-theme-mode", "auto"); + + const url = new URL(window.location.href); + const fromQuery = normalizePreset(url.searchParams.get(queryKey)); + if (fromQuery) { + setPreset(fromQuery); + try { + window.localStorage.setItem(storageKey, fromQuery); + } catch (_err) { + // Keep behavior deterministic even when storage is blocked. + } + return; + } + + const fromMarkup = normalizePreset(root.getAttribute("data-vapor-shell")); + if (fromMarkup) { + return; + } + + try { + const fromStorage = normalizePreset(window.localStorage.getItem(storageKey)); + if (fromStorage) { + setPreset(fromStorage); + return; + } + } catch (_err) { + // Fallback handled below. + } + + setPreset(fallbackPreset); +})(); diff --git a/demo/web/templates/base.html b/demo/web/templates/base.html index 9b8483b..0166d5b 100644 --- a/demo/web/templates/base.html +++ b/demo/web/templates/base.html @@ -1,6 +1,6 @@ {{ define "demo_doc_start" }} - + diff --git a/kit/patterns/theme-vapor/notes.md b/kit/patterns/theme-vapor/notes.md index 9377c31..56a1990 100644 --- a/kit/patterns/theme-vapor/notes.md +++ b/kit/patterns/theme-vapor/notes.md @@ -17,6 +17,7 @@ This module is the active reusable theme source for design-code consumers. - Pattern contracts should reference shared behavior contracts and rely on this module for visual primitives. - When baseline visuals change, update this module first to keep downstream integration deterministic. - For shell color selection, use `palette-catalog.md` and set `data-vapor-shell` on ``. +- For runtime switching, the recommended query key is `vapor_shell` (same IDs as the catalog). - Keep host-specific brand overrides outside this module unless they are reusable presets. ## Boundary diff --git a/kit/patterns/theme-vapor/palette-catalog.md b/kit/patterns/theme-vapor/palette-catalog.md index 8a06546..b26b65c 100644 --- a/kit/patterns/theme-vapor/palette-catalog.md +++ b/kit/patterns/theme-vapor/palette-catalog.md @@ -14,6 +14,17 @@ Optional: host project can override shell height without changing preset IDs: :root { --shell-height: 72px; } ``` +## Selection Approach + +Recommended precedence for host integration: + +1. `?vapor_shell=` query parameter (preview/share links) +2. `localStorage["vapor_shell"]` (remembered user choice) +3. `` static default from server/templates +4. fallback preset: `miami-sunset` + +The scaffold and demo JavaScript implement this precedence. + ## Presets (Header + Accent) | Preset ID | Header core | Accent core | Default shell height | diff --git a/kit/scaffolds/go-nethttp-web/README.md b/kit/scaffolds/go-nethttp-web/README.md index ea0d4b0..f453812 100644 --- a/kit/scaffolds/go-nethttp-web/README.md +++ b/kit/scaffolds/go-nethttp-web/README.md @@ -8,3 +8,8 @@ Minimal starter skeleton for a Go web app using: This scaffold is intended as a starting point that host repositories can adapt. +Vapor shell preset integration is included: + +- default preset via `` +- runtime override via `?vapor_shell=` +- persisted selection via `localStorage["vapor_shell"]` diff --git a/kit/scaffolds/go-nethttp-web/web/static/js/app.js b/kit/scaffolds/go-nethttp-web/web/static/js/app.js index 7374376..716c6e7 100644 --- a/kit/scaffolds/go-nethttp-web/web/static/js/app.js +++ b/kit/scaffolds/go-nethttp-web/web/static/js/app.js @@ -1,2 +1,65 @@ -document.documentElement.classList.add("js"); +(() => { + const root = document.documentElement; + const storageKey = "vapor_shell"; + const queryKey = "vapor_shell"; + const fallbackPreset = "miami-sunset"; + const allowed = new Set([ + "miami-sunset", + "neon-grid", + "laser-flamingo", + "synth-lagoon", + "mall-soft", + "hologram-sky", + "peach-drive", + "ultraviolet-plaza", + "cyber-mint", + ]); + const normalizePreset = (value) => { + const trimmed = (value || "").trim().toLowerCase(); + if (!trimmed || !allowed.has(trimmed)) { + return ""; + } + return trimmed; + }; + + const setPreset = (value) => { + const preset = normalizePreset(value); + if (!preset) { + return false; + } + root.setAttribute("data-vapor-shell", preset); + return true; + }; + + root.classList.add("js"); + + const url = new URL(window.location.href); + const fromQuery = normalizePreset(url.searchParams.get(queryKey)); + if (fromQuery) { + setPreset(fromQuery); + try { + window.localStorage.setItem(storageKey, fromQuery); + } catch (_err) { + // Keep behavior deterministic even when storage is blocked. + } + return; + } + + const fromMarkup = normalizePreset(root.getAttribute("data-vapor-shell")); + if (fromMarkup) { + return; + } + + try { + const fromStorage = normalizePreset(window.localStorage.getItem(storageKey)); + if (fromStorage) { + setPreset(fromStorage); + return; + } + } catch (_err) { + // Fallback handled below. + } + + setPreset(fallbackPreset); +})(); diff --git a/kit/scaffolds/go-nethttp-web/web/templates/base.html b/kit/scaffolds/go-nethttp-web/web/templates/base.html index 0e00acc..2c8e412 100644 --- a/kit/scaffolds/go-nethttp-web/web/templates/base.html +++ b/kit/scaffolds/go-nethttp-web/web/templates/base.html @@ -1,6 +1,6 @@ {{ define "base.html" }} - + @@ -19,4 +19,3 @@ {{ end }} -