jekyll-theme-zer0 1.28.0 → 1.29.0

data/_data/backlog.yml

@@ -62,8 +62,8 @@
 
 meta:
   title: "zer0-mistakes Backlog"
-  updated: 2026-06-29
-  next_id: 34
+  updated: 2026-08-18
+  next_id: 46
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -916,3 +916,357 @@ tasks:
     links: { issue: 302, pr: null, roadmap: null }
     created: 2026-07-12
     updated: 2026-07-16
+
+  - id: T-035
+    title: "Adopt --zer0-radius-* and display-size tokens across the remaining Sass partials"
+    status: open
+    priority: P2
+    area: feat
+    risk: low
+    effort: M
+    source: issue
+    route: theme-ui
+    summary: >-
+      The design-system alignment PR #389 (ZER0-081) introduced --zer0-radius-* and
+      --zer0-text-display-* tokens and adopted them in the partials the Claude
+      Design system names (callout, landing, ui-enhancements). Hardcoded radii
+      remain in _navbar.scss (~15 sites), notebooks.scss, code-copy.scss,
+      _docs-code-examples.scss, and others; hero .display-4 mobile overrides in
+      _ui-enhancements.scss (2rem and 1.75rem blocks — the two @media blocks
+      overlap, later wins) predate the fluid clamp tokens. Sweep them onto the
+      tokens value-preservingly where values match the scale, and reconcile the
+      duplicate hero override blocks; anything intentionally off-scale keeps a
+      literal plus a comment.
+    acceptance:
+      - "No border-radius literal in _sass/** that duplicates a --zer0-radius-* value (grep-clean or commented as intentional)."
+      - "Hero display sizing states one rule set; duplicate @media blocks reconciled."
+      - "scripts/design-system-check.rb still green; compiled CSS visually identical (evidence or skip-evidence rationale)."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-14
+    updated: 2026-08-14
+
+  # --- UI/UX fix list intake (hand-written review, 2026-08-18) ----------------
+
+  - id: T-036
+    title: "Remove hover transforms that cause pointer-edge flicker in the navbar"
+    status: open
+    priority: P1
+    area: feat
+    risk: standard
+    effort: S
+    source: user
+    route: theme-ui
+    summary: >-
+      .nav-link:hover, .nav-search-button:hover and .nav-settings-button:hover in
+      _sass/core/_navbar.scss apply transform: translateY(-1px) (icons scale 1.1,
+      chevron :hover::after translateY(2px)), so the element moves out from under
+      a pointer parked on its edge, hover exits, it returns — infinite flicker.
+      Delete every transform from :hover rules (keep background/color
+      transitions; a pressed cue may use :active translateY(1px) only) and audit
+      _sass/components/_ui-enhancements.scss and card hover styles for the same
+      pattern.
+    acceptance:
+      - "No transform in any :hover rule under _sass/ (grep for translateY/scale in hover context returns nothing)."
+      - "Pointer parked on the top edge of any nav item or utility button does not flicker."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-037
+    title: "Navbar width recovery: two clean label tiers, merged chevron, centered grid, no subtitle"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      Top nav is cramped and truncates labels ("Quicksta…"). Keep per-item icons
+      at every tier but only two states — icon + full label (wide container) and
+      the existing icon-only tier (narrow) — removing the intermediate ellipsized
+      state (_includes/navigation/navbar.html + _sass/core/_navbar.scss container
+      queries). Merge each dropdown's separate 22-24px chevron button into the
+      parent link's padding box (position:absolute overlay, shared hover
+      background on the li, button kept for a11y). Use grid-template-columns:
+      1fr auto 1fr on .navbar-main so the menu stays optically centered. Retire
+      the navbar subtitle (_includes/core/branding.html — home hero only).
+      Clarify the three toggles: labeled "Menu" text button below lg, gear moves
+      into the unified drawer on mobile so only two toggles coexist.
+    acceptance:
+      - "At 1024px and 1280px with 5 nav items every label is fully visible or the whole row is icon-only — no ellipses anywhere."
+      - "Dropdown chevron shares the parent row's hover zone; no dead zone between link and chevron."
+      - "Navbar carries logo + title only; subtitle appears on the home hero."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-038
+    title: "Language switcher: icon-only trigger and a compact, positive menu"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: S
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/components/language-toggle.html: drop the EN text span and the
+      Bootstrap caret (38-40px square icon button; title + aria-label carry the
+      name). In the menu, mark the current language with a check icon + tint
+      (not .active primary fill); keep untranslated languages clickable
+      (navigate to source page, set zer0-lang); mark machine translations with a
+      small "auto" chip; replace per-row "(Not yet translated)" with one
+      footnote line under a divider; menu width <= 220px.
+    acceptance:
+      - "Menu shows no disabled rows; widest row <= 220px; current language visually distinct without primary fill."
+      - "Trigger is icon-only at all widths with an accessible name."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-039
+    title: "Eliminate page-transition layout shift (fixed-nav offset, scrollbar gutter, server-rendered slots)"
+    status: open
+    priority: P1
+    area: perf
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      Navigation between pages visibly bounces. Define --zer0-nav-height in
+      :root, derive body padding-top and every sticky offset (admin.html's
+      top: 5rem, TOC, sidebars) and scroll-margin-top from it (no JS
+      measurement). Add html { scrollbar-gutter: stable }. Render banner/nanobar
+      slots server-side with fixed height (nanobar 3px strip always present;
+      setup banner via Liquid when site_needs_setup, not JS insert). Verify
+      explicit width/height on content images and font-display: swap + preload
+      for bootstrap-icons woff2. Progressive enhancement: @view-transition
+      { navigation: auto } with a 120ms root fade.
+    acceptance:
+      - "Lighthouse CLS < 0.02 on landing, docs, and admin pages."
+      - "No visible reflow when navigating between short and long pages (scrollbar gutter stable)."
+      - "All sticky offsets derive from --zer0-nav-height (no hardcoded top: 5rem)."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-040
+    title: "Setup wizard: live YAML preview, vertical stepper, draft persistence, stable panel height, inline validation"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/setup/wizard.html + assets/js/setup-wizard.js: replace the
+      step-5-only <pre> with a persistent sticky preview panel regenerated on
+      every input (copy/download always enabled); replace nav-pills tabs with a
+      left vertical stepper showing done/active/upcoming state (steps unlock on
+      validation, Back always allowed, remove the "N% complete" math); persist
+      the draft to localStorage under zer0-setup-draft (debounced 300ms, restore
+      on load, "Draft saved" chip, clear on download); give the panel container
+      a min-height equal to the tallest step so Back/Next never move vertically;
+      validate email/URL on blur with is-invalid + message and list unfilled
+      recommended fields as warnings on the Review step.
+    acceptance:
+      - "YAML preview visible and live at lg+; Back/Next buttons never shift vertically between steps."
+      - "Reload mid-wizard restores the draft; invalid email/URL flagged on blur."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-041
+    title: "Admin layout: actions reachable on mobile, grouped sidebar, shared sticky offset, single heading"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      _layouts/admin.html + _includes/navigation/admin-nav.html: the
+      admin_actions wrapper is d-none d-md-flex so actions are unreachable on
+      phones — render the first action as a visible button at all widths with
+      the rest in a "..." dropdown. Group sidebar items under small-caps headers
+      (Configure / System / Links) via a group: key in
+      _data/navigation/admin.yml; counts as plain numerals, statuses as colored
+      dot + word; active item = tint + semibold, not solid primary fill. Replace
+      style="top: 5rem" with top: calc(var(--zer0-nav-height) + 1rem) (depends
+      on T-039). Keep the "Administration" heading in the offcanvas header only.
+    acceptance:
+      - "Every admin action reachable at 375px width."
+      - "Sidebar grouped; no solid-primary active fill; sticky offset uses the shared variable."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+    depends_on: [T-039]
+
+  - id: T-042
+    title: "Skin contrast sweep: AA link params, tertiary meta text, per-skin badge/button audit"
+    status: open
+    priority: P1
+    area: a11y
+    risk: standard
+    effort: M
+    source: user
+    route: a11y
+    summary: >-
+      _sass/theme/_skins.scss: several skins omit the zer0-skin-palette mixin's
+      $link-light/$link-dark params and fall back to $brand/$accent, which fail
+      4.5:1 (yellow/orange/cyan brands on white, saturated brands on #212529) —
+      pass explicit AA-checked values for every skin with a comment table of
+      measured ratios. text-body-tertiary on 11-12px meta text (admin header
+      "Updated…", wizard hints) falls below AA — use --bs-secondary-color at
+      small sizes, tertiary only >= 16px. Audit .btn-primary text per skin
+      (auto-switch to dark text when brand luminance > 0.55 via color-contrast()
+      or a precomputed token).
+    acceptance:
+      - "axe/Lighthouse contrast passes on light + dark for all skins."
+      - "Every skin passes explicit link colors; measured-ratio table committed as comments."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-043
+    title: "Mermaid diagrams: render-in-place (no CLS), token-driven theming, figure shell, flash-free theme switch"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: L
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/components/mermaid.html: the hidden pre > code is replaced by a
+      min-height:100px div that grows to 300-500px on render, shifting the page —
+      render in place with the placeholder inheriting the code block's height
+      and animate the swap. Delete the ~20 !important SVG overrides that fight
+      JS themeVariables (forced white text breaks colored nodes; light mode uses
+      #007bff vs site primary #0d6efd; skins don't affect diagrams) — build
+      themeVariables at init from live tokens (getComputedStyle on --bs-primary
+      / --bs-body-bg / --bs-border-color / --bs-body-color), re-run on
+      data-bs-theme AND data-theme-skin change. Wrap each diagram in a
+      figure.mermaid-figure with type chip, optional title, copy-source /
+      download-SVG / fullscreen toolbar (reuse the code-copy button pattern) and
+      figcaption. On theme switch render the new SVG off-DOM and cross-fade
+      120ms (instant under prefers-reduced-motion). Builds on T-039.
+    acceptance:
+      - "CLS contribution from a page with 3 diagrams < 0.01."
+      - "No !important SVG overrides remain; diagrams follow theme AND skin tokens live."
+      - "Theme switch shows no blank flash."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+    depends_on: [T-039]
+
+  - id: T-044
+    title: "Playwright suite aborts: duplicate openDialog declaration in accessibility.spec.js"
+    status: done
+    priority: P1
+    area: tests
+    risk: low
+    effort: S
+    source: issue
+    route: test-author
+    summary: >-
+      test/visual/core/accessibility.spec.js declares `async function
+      openDialog` twice — at line 172 (page, selector) and again at line 425
+      (page, selector, kind), the latter added by 98fd6f9 (#387) without
+      removing the former. Two function declarations of the same name in one
+      module scope is a SyntaxError, so Playwright fails to parse the file and
+      the WHOLE run aborts before any test executes: "Identifier 'openDialog'
+      has already been declared. (425:15)". This takes down the critical and
+      smoke tiers together, on every branch, and has been red on main since
+      2026-08-14. Discovered during #414, whose own new spec
+      (test/visual/features/recipes.spec.js) therefore cannot run in CI. The
+      three-argument version is a strict superset — with `kind` undefined it
+      resolves to Ctor='Modal' and 'shown.bs.modal', exactly what the
+      two-argument one does — so deleting the earlier declaration (lines
+      165-184, comment included) is behaviour-preserving.
+    acceptance:
+      - "test/visual/core/accessibility.spec.js parses; `npx playwright test --project=critical` runs to completion."
+      - "Only one openDialog declaration remains, and its callers all still pass."
+      - "No behavioural change to the modal/offcanvas a11y tests."
+    links: { issue: 416, pr: null, roadmap: null }
+    created: 2026-08-23
+    updated: 2026-08-23
+
+  - id: T-045
+    title: "Homepage snapshot baselines were regenerated without the 1967px drift being diagnosed"
+    status: open
+    priority: P2
+    area: tests
+    risk: low
+    effort: S
+    source: issue
+    route: test-author
+    summary: >-
+      The Visual Snapshots tier fails all 9 `Theme skins > homepage visual
+      snapshot` cases with the SAME diff — 1967 pixels (ratio 0.01) — against
+      test/visual/snapshots/features/appearance-snapshot.spec.js-snapshots/homepage-*-snapshots-linux.png,
+      well over the maxDiffPixels 150 budget. The count being identical across
+      air/aqua/contrast/dark/dirt/neon/mint/plum/sunrise points at one shared,
+      skin-independent region rather than a palette regression. Verified during
+      #414 that it is NOT that PR's doing: building origin/main and the PR
+      branch and screenshotting the homepage at the spec's own 1280x720
+      viewport produced BYTE-IDENTICAL PNGs (same md5), so the branch renders
+      the homepage exactly as main does and the drift is between the committed
+      baselines and what main itself now renders. Note while investigating:
+      _includes/components/theme-info.html renders a minute-resolution build
+      stamp, site.time | date "%b %d, %H:%M" — it currently sits in a collapsed
+      offcanvas (measured 0x0, not in the viewport) so it is not the cause
+      today, but it is a live non-determinism hazard the moment that panel is
+      shown by default, and worth masking regardless. UPDATE 2026-08-23: #413
+      regenerated all 9 baselines when it merged, so the check is green again —
+      resolved by re-blessing rather than by diagnosis, which is what the first
+      acceptance criterion was meant to prevent. Diffing the old vs new CI
+      baselines (homepage-air, 2596f866 vs e488c4c) puts the whole 5016px delta
+      in two bands: y21-41 (a wide navbar strip, 4688px) and y626 (328px).
+      page-views does render on the homepage so part of that is legitimately
+      #413, but a navbar strip is not where a view-count badge belongs.
+      Separating the two needs the diff artifact from a pre-#413 failing run,
+      which has rolled off. What remains is confirming the y21-41 band is
+      accounted for. UPDATE 2026-08-25: the y21-41 band is the navbar
+      reflowing, and the reason it RECURS is structural — a path-filter gap.
+      ci.yml's `styling` filter (which gates the snapshots job) lists only code
+      paths; `_data/**` appears solely under `content`, which gates no visual
+      job. So #419's nav item changed the chrome of every page with Visual
+      Snapshots SKIPPED on both the PR and the main push, and the drift
+      surfaced on #420, an unrelated PR. The y626 band is now UNRECOVERABLE:
+      both artifact uploads use 14-day retention (ci.yml, nightly-extended.yml)
+      and every pre-#413 failing run is past that window. Recording that rather
+      than leaving it open — no evidence survives to diagnose it from.
+    acceptance:
+      - "_data/** (or at minimum _data/navigation/**) is covered by the `styling` filter in ci.yml, so a nav/chrome data change runs Visual Snapshots instead of skipping it."
+      - "A CI guard pins that coverage, so the gap cannot silently reopen (lint-workflows.yml)."
+      - "A PR touching only _data/navigation/main.yml runs Visual Snapshots — demonstrated on the checks list, not asserted."
+      - "Visual Snapshots passes on main and on a fresh branch with no source changes."
+      - "Any genuinely time- or build-varying content inside the snapshot region is masked or stubbed, so the tier cannot drift again."
+      - "No baseline PNG is regenerated as part of this work; any diff is diagnosed in the PR before it is blessed."
+      - "The y626 band is explained, or recorded as unrecoverable with the reason. (Recorded: artifacts past 14-day retention.)"
+    links: { issue: 417, pr: null, roadmap: null }
+    created: 2026-08-23
+    updated: 2026-08-25

data/_data/consumers.yml

@@ -62,10 +62,18 @@ consumers:
     dispatch: false
     risk: >-
       Unpinned. Every push to this theme's main reaches production with no gate
-      and no rollback. Shadows ~55 theme files (5 layouts, 34 includes, 8 JS, 6
-      CSS, 2 plugins) — the largest override surface in the fleet, including
-      ~75 lines of !important CSS working around the stacking bug fixed in #338.
-      Recommend pinning and joining the fan-out.
+      and no rollback — that part is the real exposure. Recommend pinning and
+      joining the fan-out. NOTE: this entry previously claimed it "shadows ~55
+      theme files … ~75 lines of !important CSS working around #338", which
+      audit-consumer does not support. Only 2 files actually shadow a theme
+      file (_includes/content/giscus.html, assets/js/particles-source.js); the
+      other ~52 are it-journey's own quest-system layouts and includes that
+      share no filename with anything in this theme, so they carry no drift
+      risk at all. The !important CSS is real but is 31 lines in
+      assets/css/user-overrides.css — this theme's own documented extension
+      hook, enabled by `user_overrides: true`, not a shadow — and no fix
+      numbered #338 could be substantiated in that repo. Keep this field
+      derived from audit-consumer output, not hand-maintained estimates.
     pins:
       - file: _config.yml
         kind: remote_theme
@@ -145,3 +153,100 @@ consumers:
       - file: _data/hub.yml
         kind: hub_registry
         note: "line 39 (pages.theme_repo) — re-roll members after bumping"
+
+  # ---------------------------------------------------------------------------
+  # The four entries below were missing entirely until the 2026-08 fleet audit.
+  # Unregistered consumers are invisible to propagate.rb in BOTH directions: no
+  # release dispatch reaches them, and they never appear in the weekly drift
+  # report — so their pins can rot indefinitely with nothing to notice. That is
+  # exactly what happened to zer0-pages, which sat three minors behind on a gem
+  # constraint that already permitted the current release.
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/zer0-pages
+    mode: gem
+    site: https://bamr87.github.io/zer0-pages/
+    dispatch: true
+    note: >-
+      Dual Obsidian-vault / Jekyll repo. Two things make it unlike every other
+      consumer. (1) It sets `source: pages`, so the whole themable tree lives
+      under pages/ — audit-consumer follows `source:` for this reason; auditing
+      the repo root reports a falsely clean result. (2) It is gem mode with no
+      remote_theme anywhere, so NOTHING is picked up automatically: the
+      scheduled bump is its only path to a new version.
+    risk: >-
+      Gemfile.lock resolved 1.25.0 while the Gemfile constraint (~> 1.25)
+      already permitted 1.28.0 — stale purely because nothing was nudging it.
+      Keeps two deliberate include forks, declared in its .theme-overrides.yml.
+    pins:
+      - file: Gemfile
+        kind: gem_constraint
+        note: 'line 11 — `gem "jekyll-theme-zer0", "~> 1.25"`'
+      - file: Gemfile.lock
+        kind: resolved_lockfile
+        note: "line 86 — re-lock with `bundle lock --update jekyll-theme-zer0`"
+      - file: _config.yml
+        kind: theme_name
+        note: "line 29 — `theme: jekyll-theme-zer0`; activates the gem, no version of its own"
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/irony-works
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/irony-works/
+    dispatch: false
+    note: >-
+      Vault + Node engine; engine/scripts/transplant.mjs converts vault/ into
+      the _entries/ collection before Jekyll runs. Has NO Gemfile at all — it
+      builds via actions/jekyll-build-pages (the github-pages image), so it can
+      only ever be tracked as remote_theme_floating; there is no gem constraint
+      surface for a bump to rewrite.
+    risk: >-
+      Unpinned, and with no local preview path a contributor cannot see a theme
+      break before pushing. Keeps three deliberate overrides, declared in its
+      .theme-overrides.yml.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 4, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/wargames
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/wargames/
+    dispatch: false
+    note: >-
+      Content-only vendored mirror of the OverTheWire challenges. Zero local
+      theme files — one of the cleanest consumers in the fleet. Its _config.yml
+      uses column-aligned YAML (`remote_theme             : "..."`), the style
+      that used to defeat audit-consumer's mode detection.
+    risk: >-
+      Unpinned, and its only build runs on push to main (jekyll-gh-pages.yml),
+      so a break ships before anyone sees it.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 44, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/zer0-pages-remote
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/zer0-pages-remote/
+    dispatch: false
+    note: >-
+      The minimal reference consumer: _config.yml + Gemfile + index.md, no
+      local theme files and no _data at all, still showing the onboarding
+      wizard by design. Useful as the canary for what a stock remote_theme
+      consumer gets with zero customisation — if the theme breaks a bare site,
+      it breaks here first.
+    private: true
+    risk: >-
+      Unpinned. Low stakes (a demo, not a content site), but it has already
+      caught one real integration break: PR #8 fixed a Liquid `include_cached`
+      failure caused by a Gemfile plugin missing from the safe-mode whitelist.
+      This repo is PRIVATE, so an unauthenticated `propagate.rb` run reports it
+      "unreachable" rather than reading its pin — drift reporting needs a token
+      here even though it is read-only. CI already supplies one; a bare local
+      run will not.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 12, no tag — floats main

data/_data/features.yml

@@ -1037,6 +1037,7 @@ features:
       - "Client-side JSON search index"
       - "Bootstrap modal interface"
       - "Keyboard shortcut (/) activation"
+      - "Cmd/Ctrl+K shortcut with visible navbar affordance — a / kbd chip on the search button (design-system navbar pattern), hover titles with platform-aware Cmd-K/Ctrl+K, aria-keyshortcuts, and shortcut hints on the sidebar (b) and TOC (t) toggles"
       - "Real-time search results"
       - "Accessible search input"
       - "No external dependency (Algolia removed v1.5.1)"
@@ -2256,3 +2257,159 @@ features:
       - "Immersive sidebar-free reading surface: storybook serif, responsive type scale, drop cap, plate styling for bare markdown images"
       - "illustrations: front matter renders a collapsed prompt colophon — the same list drives OpenAI image generation on consumer sites (drsai)"
       - "Demo book The Tales of Zer0 ships with the theme; reference platform: bamr87/drsai with Dodge & Reena as the test book"
+
+  - id: ZER0-081
+    title: "Claude Design System Round-Trip"
+    description: "Design-token layer aligned with the zer0-mistakes Claude Design project: corner-radius, logo-palette, and display-size tokens join _sass/tokens/; a git mirror of the design project lives under _design-system/ (plain-CSS tokens, React component specs from buttons to FABs to post cards to skeletons, foundation cards, website UI kit); and a CI parity check fails when theme and mirror drift"
+    implemented: true
+    version: "1.29.0"
+    link: "/"
+    docs: "https://github.com/bamr87/zer0-mistakes/blob/main/docs/ui/design-system.md"
+    tags: [design-system, tokens, sass, ai, tooling]
+    date: 2026-08-14
+    provenance:
+      introduced_in: "1.29.0"
+      pr: 389
+      commit: "7fc2fe02"
+      issue: null
+    tests:
+      - "test/visual/core/styling.spec.js"
+      - "scripts/design-system-check.rb"
+    references:
+      styles:
+        - "_sass/tokens/_radius.scss"
+        - "_sass/tokens/_index.scss"
+      scripts:
+        - "scripts/design-system-check.rb"
+      design:
+        - "_design-system/components/"
+        - "_design-system/guidelines/"
+        - "_design-system/tokens/"
+      docs: "docs/ui/design-system.md"
+    features:
+      - "--zer0-radius-* corner radii, --zer0-logo-* brand palette, and --zer0-text-display-* fluid hero sizes declared once and consumed by callouts, landing cards, nav, and focus rings"
+      - "_design-system/ mirrors the claude.ai/design project (id e75121c0-9210-42d1-ade3-2c8af9111cbe) so interfaces can be designed in Claude Design and folded back into the theme — contract in _design-system/SYNC.md"
+      - "scripts/design-system-check.rb (core test suite) resolves var() alias chains and fails CI on token drift, plus flags fallback-less var(--zer0-*) references that are never declared"
+      - "Component specs ship the theme's primitives as React twins — Button, Badge, Fab/FabStack, Card, FeatureCard, PostCard, Callout, Skeleton, Input — with foundation cards for colors, type, spacing, motion, layers, and brand (PR 391)"
+      - "No webfonts, Bootstrap-first, seven skins, light+dark — the imported system and the theme now state one identical visual contract"
+
+  - id: ZER0-082
+    title: "Live Design System Pages"
+    description: "The design system published on the site itself: _design-system/ is force-included in the Jekyll build so tokens, styles.css, specimen cards, and component sources get real URLs under /_design-system/, and a /design/ hub page renders the foundation specimens in live iframes, catalogs the component twins, and links the Claude Design page canvas covering all 24 layouts"
+    implemented: true
+    version: "1.29.0"
+    link: "/design/"
+    docs: "https://github.com/bamr87/zer0-mistakes/blob/main/docs/ui/design-system.md"
+    tags: [design-system, tokens, pages, navigation, ui]
+    date: 2026-08-14
+    provenance:
+      introduced_in: "1.29.0"
+      pr: 392
+      commit: "6ac9f77d"
+      issue: null
+    tests:
+      - "test/visual/features/design-hub.spec.js"
+    references:
+      pages:
+        - "pages/_about/design.md"
+      data:
+        - "_data/navigation/main.yml"
+      tests:
+        - "test/visual/features/design-hub.spec.js"
+      config: "_config.yml"
+    features:
+      - "Publishing is one config line — include: [_design-system] — so the mirror's plain-CSS tokens double as a hosted stylesheet any prototype can link"
+      - "/design/ foundations gallery renders the actual specimen cards in iframes against the published tokens — living documentation, never screenshots"
+      - "Component-twin catalog links every React spec (.jsx/.d.ts/.prompt.md) served raw from the mirror; interactive rendering stays in Claude Design"
+      - "Page canvas: every layout, nav pattern, and chrome surface recreated as a Claude Design presentation, linked from the hub with a screen-to-repo-file map"
+
+  # ============================================================================
+  # READER ENGAGEMENT (v1.29+)
+  # ============================================================================
+
+  - id: ZER0-083
+    title: "Page View Counter"
+    description: "Per-page view tracking with the count shown in the article meta row — a local-first provider that needs no server, or an HTTP counter endpoint, both gated by DNT, GPC, and consent"
+    implemented: true
+    version: "1.29.0"
+    link: "/"
+    docs: "https://github.com/bamr87/zer0-mistakes/blob/main/docs/features/page-views.md"
+    tags: [analytics, privacy, engagement, metrics, ui]
+    date: 2026-08-23
+    provenance:
+      introduced_in: "1.29.0"
+      pr: 413
+      commit: "6ca4961b"
+      issue: null
+    tests:
+      - "test/visual/features/page-views.spec.js"
+    references:
+      layouts:
+        - "_layouts/article.html"
+      includes:
+        - "_includes/components/page-views.html"
+        - "_includes/components/page-views-init.html"
+        - "_includes/core/head.html"
+      scripts:
+        - "assets/js/page-views.js"
+      styles:
+        - "_sass/components/_page-views.scss"
+      tests:
+        - "test/visual/features/page-views.spec.js"
+      config: "_config.yml"
+      docs: "docs/features/page-views.md"
+    features:
+      - "Two providers: 'local' (default) keeps counts in the visitor's localStorage — no server, no network, GitHub-Pages safe; 'remote' reads a counter endpoint the site owns ({path} substitution, configurable method, dotted count_key)"
+      - "Privacy gates mirror the posthog block (DNT, Global Privacy Control, optional cookie-consent 'analytics' tie-in) and suppress RECORDING only — a view blocked pending consent is recorded when consent arrives"
+      - "dedupe: session counts one view per page per browser session, so a reload cannot inflate the number"
+      - "The badge ships hidden and is revealed only once a count exists — no '0 views' flash — and carries its own leading separator so a hidden badge leaves no dangling bullet in the meta row"
+      - "Every storage touch is probed and wrapped: private mode, blocked cookies, a corrupt payload, or an exceeded quota degrade to 'no count' instead of throwing"
+      - "window.zer0PageViews (get/all/refresh/reset) plus a 'zer0:page-views' CustomEvent let a site build on the count without polling"
+  - id: ZER0-084
+    title: "Cookbook & Recipes Collection"
+    description: "A `recipes` collection whose structured front matter (ingredients, steps, yield, times, ratio_basis) renders as a working recipe page: a fact bar, a serving scaler, an ingredient checklist, a numbered method, a build-time baker's-percentage table, and schema.org Recipe JSON-LD — with client-side scaling and US/metric conversion (volume↔weight via an ingredient density table) layered on as progressive enhancement"
+    implemented: true
+    version: "1.29.0"
+    link: "/recipes/"
+    docs: "/docs/features/cookbook-collection/"
+    tags: [recipes, cookbook, collections, layouts, unit-conversion, structured-data]
+    date: 2026-08-23
+    provenance:
+      introduced_in: "1.29.0"
+      pr: null
+      commit: "45354f34"
+      issue: null
+    tests:
+      - "test/test_core.sh"
+    references:
+      layouts:
+        - "_layouts/recipe.html"
+        - "_layouts/cookbook.html"
+      includes:
+        - "_includes/components/recipe-index.html"
+        - "_includes/components/recipe-card.html"
+        - "_includes/components/recipe-meta.html"
+        - "_includes/components/recipe-scaler.html"
+        - "_includes/components/recipe-ingredients.html"
+        - "_includes/components/recipe-steps.html"
+        - "_includes/components/recipe-ratio.html"
+        - "_includes/components/recipe-nutrition.html"
+        - "_includes/components/recipe-qty.html"
+        - "_includes/components/recipe-temp.html"
+        - "_includes/components/recipe-grams.html"
+        - "_includes/components/recipe-duration.html"
+      styles: ["_sass/components/_recipe.scss"]
+      scripts: ["assets/js/recipe-scaler.js"]
+      data:
+        - "_data/recipe_courses.yml"
+        - "_data/ingredient_densities.yml"
+      pages:
+        - "pages/_recipes/index.md"
+        - "pages/_docs/features/cookbook-collection.md"
+      config: "_config.yml"
+    components:
+      - "Serving scaler — stepper, ½×/1×/2×/3× presets, ?servings= and ?scale= links, per-recipe scale remembered in localStorage"
+      - "Unit switch — as written / metric / US, rewriting quantities, units and oven temperatures in place"
+      - "Volume↔weight conversion driven by _data/ingredient_densities.yml, overridable per ingredient with grams_per_cup"
+      - "Baker's-percentage ratio table computed at build time, so percentages are correct with JavaScript disabled"
+      - "Progressive enhancement: quantities render as authored by Jekyll; the control bar stays hidden until the script reveals it"