diff --git a/.okf/architecture/css-pipeline.md b/.okf/architecture/css-pipeline.md index a5c2ec8c6..178d9b6d8 100644 --- a/.okf/architecture/css-pipeline.md +++ b/.okf/architecture/css-pipeline.md @@ -28,6 +28,34 @@ gzip first-visit per page). Any size/perf claim must be validated on **compiled + gzip per-page payload**, never raw source line counts — see [css-maintainability-plan](/workflows/css-maintainability-plan.md). +# Token layer: `foundations/css-variables.css` + +The one file every page can rely on. It loads **inline site-wide** via the +`navigation` bundle, so a token defined here resolves in all 19 bundles — +which is precisely why promoting a colour into it is the unlock for any +site-wide recolour, and why a page-scoped `:root` block reaches only that +page's bundles. + +Since 2608 Phase 1a.1 (2026-08-20) it holds the **light Rescue Room palette** +(ADR-0003): `--ink-900/700/500/300`, `--line`, `--surface{,-raised,-sunken,-ink}`, +`--ruby-{700,100,050}`, alongside the pre-existing `--color-ruby` and the +`--color-obsidian*` dark family (one dark band per page; cover art; the +vibe-code-rescue campaign page). + +**The zero-delta promotion pattern.** Moving tokens into this file is done in +its own commit, with the old names kept as aliases (`--rr-x: var(--x)`) and +identical values, so nothing renders differently and no baseline moves. That +turns the *next* commit — deleting a token and repointing its consumers — into +a value change rather than a rename, so its diff is about colour roles only. +Verified in 1a.1 by computed-value checks in the browser plus 53 screenshots +compared with zero churn. + +**Deprecation in progress:** `--color-primary` (`#1a8cff`) is named "primary" +but appears in no brand definition; it and the late-cascade `#0066d6` anchor +rule are deleted in Phase 1a.2/1a.3. Until then, three page files carry scoped +`!important` workarounds against that rule — retiring all of them is the +phase's success signal. + # Legacy liability: FL-Builder export CSS A large portion of shipped CSS (~75K lines at audit time) is diff --git a/.okf/architecture/index.md b/.okf/architecture/index.md index 4ce266c53..46de3c54b 100644 --- a/.okf/architecture/index.md +++ b/.okf/architecture/index.md @@ -1,7 +1,7 @@ # Architecture * [Hugo Site](hugo-site.md) - Hugo static site setup, theme, build/test commands -* [CSS Build Pipeline](css-pipeline.md) - PostCSS + per-bundle PurgeCSS, FL-Builder legacy CSS +* [CSS Build Pipeline](css-pipeline.md) - PostCSS + per-bundle PurgeCSS, the site-wide token layer and its zero-delta promotion pattern, FL-Builder legacy CSS * [Blog Index / Listing Page](blog-list-page.md) - index AND tag-page templates, the shared row/filter/CTA partials, blog-list CSS bundle, and the term-kind / date-fallback traps * [Blog Cover Image Pipeline](cover-image-pipeline.md) - JetVelocity cover generation, og:image vs thumbnail rendering, and the responsive mobileWidth/mobileSizes params list covers need * [Enhanced SEO Meta Tags](seo-meta-tags.md) - per-section title/description generation partial diff --git a/.okf/log.md b/.okf/log.md index 00b658dfc..61f0bd2ce 100644 --- a/.okf/log.md +++ b/.okf/log.md @@ -2357,3 +2357,20 @@ Phase 1a written up (20.02) with the surface measured rather than estimated: !important workarounds across four files that exist ONLY until that anchor rule dies. Success signal for the phase is exactly that - if all 55 can't go, the replacement isn't right yet. + +## 2026-08-20 - Token layer documented; Phase 1a.1 promoted the light palette + +The css-pipeline concept had no token layer at all - a real gap, since +`foundations/css-variables.css` is the one file loaded inline in every bundle +and is therefore the only place a site-wide colour change can start. Phase +1a.1 made that concrete by promoting the light Rescue Room palette there +(ADR-0003 resolved LIGHT), so the concept now documents the file, its +contents, and the pattern worth reusing: + +**Zero-delta promotion.** Move tokens in their own commit, keep the old names +as aliases with identical values, verify nothing renders differently - then +the NEXT commit, which deletes a token and repoints consumers, is a value +change rather than a rename, and its diff is about colour roles only. 1a.1 +verified this rather than assuming it: computed values checked in the browser, +53 screenshots compared, zero baseline churn, course suite green (it shares +single-post.css, so the dedup had to leave it untouched). diff --git a/themes/beaver/assets/css/foundations/css-variables.css b/themes/beaver/assets/css/foundations/css-variables.css index de3106219..6909d2d6e 100644 --- a/themes/beaver/assets/css/foundations/css-variables.css +++ b/themes/beaver/assets/css/foundations/css-variables.css @@ -48,4 +48,49 @@ --color-ruby-hover: #e04a42; --color-on-dark: #dfe2eb; --color-label-dark: #8f97a8; + + /* ================================================================== + Rescue Room light palette — promoted here 2026-08-20 (2608 Phase 1a.1) + from the three blog page files that scoped them under an `rr-` prefix + (single-post.css, pages/blog-single.css, pages/blog-list.css). + Palette resolved LIGHT in ADR-0003; this file loads inline site-wide + via the `navigation` bundle, so defining them here is what makes them + available to the other 17 bundles in 1a.2-1a.4. + + ZERO-DELTA BY CONSTRUCTION: the values are identical to the `rr-` + definitions being replaced, and the `rr-` names are kept below as + aliases, so every existing consumer resolves to exactly the same + colour. Nothing should move in a screenshot. That is the point — + it turns the 1a.2 deletion into a value change rather than a rename. + ================================================================== */ + + /* Ink: warm neutral ramp. Replaces the cool --color-dark #121212 / + --color-muted #969798 pair as those consumers migrate in 1a.2. */ + --ink-900: #14110f; /* headings, primary text */ + --ink-700: #3d3733; /* body */ + --ink-500: #6b625c; /* secondary, captions, meta */ + --ink-300: #a49b94; /* disabled, placeholder */ + --line: #e7e1d9; /* hairlines — the only border colour */ + + /* Light surfaces. The dark counterpart is the existing + --color-obsidian* family; one dark band per page (ADR-0003). */ + --surface: #ffffff; + --surface-raised: #faf7f3; /* warm, not the cool #f5f6f7 it replaces */ + --surface-sunken: #f2ece4; + --surface-ink: #14110f; /* the single dark band */ + + /* Ruby tints. --color-ruby #cc342d (5.1:1 on white, AA both + directions) and --color-ruby-hover already exist above. */ + --ruby-700: #9e2620; /* pressed / text-on-light where AA needs more */ + --ruby-100: #fbeae8; /* tint background */ + --ruby-050: #fdf5f4; /* hero blush (course page, campaign heroes) */ + + /* Aliases: the blog shipped against these names. Kept so 1a.1 renders + identically; DELETE in 1a.4 once the three page files consume the + canonical names. */ + --rr-ink-900: var(--ink-900); + --rr-ink-700: var(--ink-700); + --rr-ink-500: var(--ink-500); + --rr-line: var(--line); + --rr-surface-raised: var(--surface-raised); } diff --git a/themes/beaver/assets/css/single-post.css b/themes/beaver/assets/css/single-post.css index efc662ea8..0757b3b00 100644 --- a/themes/beaver/assets/css/single-post.css +++ b/themes/beaver/assets/css/single-post.css @@ -418,17 +418,14 @@ /* ================================================================== Rescue Room shared pieces (moved from pages/blog-list.css 2026-08-20). single-post.css is a member of the blog-list, blog-single and - course-single bundles, so these serve all three surfaces from one - definition site. Tokens: SCOPED on purpose (blog-first, 20.01 plan) - - promote to foundations/css-variables.css in Phase 1a, then delete. + course-single bundles, so these serve all three surfaces. + + The token :root block that lived here was PROMOTED to + foundations/css-variables.css in Phase 1a.1 (2026-08-20) - that file + loads inline site-wide, so the other 17 bundles can now resolve them + too. The `rr-` names survive there as aliases; the consumers below + move to the canonical names in 1a.4. ================================================================== */ -:root { - --rr-ink-900: #14110f; - --rr-ink-700: #3d3733; - --rr-ink-500: #6b625c; - --rr-line: #e7e1d9; - --rr-surface-raised: #faf7f3; -} /* Audit CTA band - blog index (before pagination) and post pages (after tags). Rendered by partials/blog/cta-band.html. */