Apply the site-wide apple-design audit

The home header no longer hides on landing: the scroll entrance is
scoped to the brand, and the emerging veil moved to a pseudo-element
that animates opacity only, so the nav reads from first paint and
scrolling stops repainting background and shadow every frame. Body
type is 100%/1.6 so browser text-size settings apply, and the /about
specimen now describes the stack as it actually renders — no
font-face ships, so the system face is the real product, recorded in
lessons-learned. prefers-reduced-transparency and prefers-contrast
gain solid-chrome and defined-border fallbacks. Cards press down on
tap, header links carry ~43px tap targets via padding with
cancelling negative margins, search exposes combobox and listbox
semantics to match its keyboard behavior, and the runner chip's navy
is tokenized as --terminal-bg/--terminal-ink with swatches on
/about. The silent arrow-key dead-end at catalog edges stays by
design: feedback only where it earns its place.

Verified in headless Chromium at 1160, 390x844, and 844x390: the nav
renders at first paint on home at all three, and About's tap target
measures 43px tall ending inside the 390px viewport.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PJDjKbt3EyWPEThak9WQXp

Author: claude

CHANGELOG.md

@@ -26,6 +26,11 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 
 ### Changed
 
+- The home header stays visible on landing: the scroll-driven entrance now animates the brand and a compositor-friendly veil layer instead of hiding the whole header (which left the page with no visible nav at first paint).
+- Body type is `100%/1.6` instead of a fixed 16px, so browser text-size settings are respected; the `/about` type specimen now describes the stack as it actually renders (system face; FT Kunst Grotesk only where installed).
+- `prefers-reduced-transparency` and `prefers-contrast: more` get solid-chrome and defined-border fallbacks; cards press down on tap; header links carry full-height (~43px) tap targets via padding with cancelling negative margins.
+- The home search exposes combobox/listbox semantics (`aria-expanded`, `role="option"`) to match its existing keyboard behavior.
+- The runner output chip's navy is now tokenized (`--terminal-bg`/`--terminal-ink`) and appears in the `/about` design language.
 - Journeys now reference every example: `iterator-vs-iterable`, `classmethods-and-staticmethods`, `bound-and-unbound-methods`, `abstract-base-classes`, and `structured-data-shapes` joined their natural sections, with journey-outcome support lists updated.
 - Journey meta descriptions no longer claim gap placeholders; all previously declared gaps are filled.
 

docs/lessons-learned.md

@@ -140,5 +140,6 @@ git diff --check
 - **Copy that describes data state goes stale silently.** Journey meta descriptions still claimed "explicit placeholders for missing examples" long after the last gap placeholder was filled, and the gap-rendering UI suggested holes that no longer existed. Prose that asserts a property of the data ("all examples run," "placeholders mark gaps") should either be derived from the data or covered by a check; otherwise fixing the data falsifies the copy.
 - **Make targets that import the example loader must go through uv.** The loader executes example code that uses 3.12+ syntax (`type UserId = int`), so any script importing `src.app` breaks under an older system `python3` even though its shebang says `python3`. CI masks this by installing 3.13 as the default interpreter. Build steps that import the catalog (`build_search_index`, `build_social_cards`) run as `uv run --python 3.13 scripts/...` in the Makefile so local machines with an older `python3` behave like CI.
 - **Index notes text, not just titles, and normalize at build time.** The search index concatenates the slug words and every note line, lowercased at build time, so concept queries ("walrus", "GIL"-style vocabulary that titles avoid) hit the right example and the client never re-normalizes entry content. Exporting the ranking function from `search.js` lets a plain Node script (`make search-ranking-test`) assert ranking behaviour against the real generated index without a JS test framework.
+- **The brand faces are progressive enhancement; the system stack is the product.** FT Kunst Grotesk and Apercu Mono Pro lead the font stacks, but no `@font-face` ships (no web license), so nearly every visitor reads the system fallbacks. Body type is `100%/1.6` so browser text-size settings are respected. `/about` documents the stack as it actually renders — never describe the leading face as if everyone sees it.
 - **UI icons are a deliberate, minimal vocabulary.** The site's chrome is text-first; the only UI icons are the Lucide copy/check/x glyphs on the code-cell copy button, drawn as `currentColor` CSS masks so every token state (muted, hover, accent-on-copied, dark mode) flows through with no icon-specific color rules. Toolbar actions (Run, Reset, Copy link) stay text because no glyph says "copy a URL containing your edit" unambiguously. Any further icon must update this entry and justify itself the same way.
 - **The wide events already knew what learners do; nobody was asking.** `example.slug`, `code_edited`, `execution_ms`, turnstile outcome, and 404 paths were all in the observability payload before any analytics existed. `scripts/learner_report.py` is a pure consumer: it auto-detects the raw payload, `wrangler tail` envelope, and Workers Logs envelope per line, so exports from any source work unmodified. The most valuable section costs nothing to collect: recurring 404s under `/examples/` are direct demand for pages that do not exist.

public/search.ab0effeac6ce.js public/search.158bd7afa114.jspublic/search.ab0effeac6ce.js renamed to public/search.158bd7afa114.js

@@ -51,13 +51,16 @@ function wireSearch() {
   function hideResults() {
     results.hidden = true;
     results.replaceChildren();
+    input.setAttribute('aria-expanded', 'false');
   }
 
   // Result nodes are built with textContent so catalog fields can never
   // be parsed as markup.
   function resultNode(entry) {
     const item = document.createElement('li');
+    item.setAttribute('role', 'presentation');
     const link = document.createElement('a');
+    link.setAttribute('role', 'option');
     link.href = `/examples/${encodeURIComponent(entry.slug)}`;
     const title = document.createElement('strong');
     title.textContent = entry.title;
@@ -79,13 +82,15 @@ function wireSearch() {
         empty.textContent = 'No matching examples.';
         results.replaceChildren(empty);
         results.hidden = false;
+        input.setAttribute('aria-expanded', 'true');
       } else {
         hideResults();
       }
       return;
     }
     results.replaceChildren(...matches.map(resultNode));
     results.hidden = false;
+    input.setAttribute('aria-expanded', 'true');
   }
 
   input.addEventListener('focus', loadIndex, { once: true });

public/search.js

@@ -51,13 +51,16 @@ function wireSearch() {
   function hideResults() {
     results.hidden = true;
     results.replaceChildren();
+    input.setAttribute('aria-expanded', 'false');
   }
 
   // Result nodes are built with textContent so catalog fields can never
   // be parsed as markup.
   function resultNode(entry) {
     const item = document.createElement('li');
+    item.setAttribute('role', 'presentation');
     const link = document.createElement('a');
+    link.setAttribute('role', 'option');
     link.href = `/examples/${encodeURIComponent(entry.slug)}`;
     const title = document.createElement('strong');
     title.textContent = entry.title;
@@ -79,13 +82,15 @@ function wireSearch() {
         empty.textContent = 'No matching examples.';
         results.replaceChildren(empty);
         results.hidden = false;
+        input.setAttribute('aria-expanded', 'true');
       } else {
         hideResults();
       }
       return;
     }
     results.replaceChildren(...matches.map(resultNode));
     results.hidden = false;
+    input.setAttribute('aria-expanded', 'true');
   }
 
   input.addEventListener('focus', loadIndex, { once: true });

public/site.671f41b443f6.css public/site.5dd61ecc9509.csspublic/site.671f41b443f6.css renamed to public/site.5dd61ecc9509.css

@@ -1,7 +1,7 @@
-:root { color-scheme: light; --accent: #FF4801; --accent-hover: #FF7038; --accent-soft: rgba(255, 72, 1, 0.08); --text: #521000; --muted: rgba(82, 16, 0, 0.7); --page: #F5F1EB; --surface: #FFFBF5; --surface-2: #FFFDFB; --surface-3: #FEF7ED; --hairline: #EBD5C1; --hairline-soft: rgba(235, 213, 193, 0.5); --header-veil: rgba(245, 241, 235, 0.82); --header-veil-0: rgba(245, 241, 235, 0); --header-veil-solid: rgba(245, 241, 235, 0.95); --figure-paper: #F5F1EB; --space-1: .5rem; --space-2: .75rem; --space-3: 1rem; --space-4: 1.5rem; --space-5: 2rem; --space-6: 3rem; }
+:root { color-scheme: light; --accent: #FF4801; --accent-hover: #FF7038; --accent-soft: rgba(255, 72, 1, 0.08); --text: #521000; --muted: rgba(82, 16, 0, 0.7); --page: #F5F1EB; --surface: #FFFBF5; --surface-2: #FFFDFB; --surface-3: #FEF7ED; --hairline: #EBD5C1; --hairline-soft: rgba(235, 213, 193, 0.5); --header-veil: rgba(245, 241, 235, 0.82); --header-veil-0: rgba(245, 241, 235, 0); --header-veil-solid: rgba(245, 241, 235, 0.95); --figure-paper: #F5F1EB; --terminal-bg: #0b1020; --terminal-ink: #f9fafb; --space-1: .5rem; --space-2: .75rem; --space-3: 1rem; --space-4: 1.5rem; --space-5: 2rem; --space-6: 3rem; }
     * { box-sizing: border-box; }
     html { -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility; }
-    body { max-width: 1040px; margin: 0 auto; padding: var(--space-4); color: var(--text); font: 16px/1.6 FT Kunst Grotesk, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; background: radial-gradient(circle at top left, rgba(255, 72, 1, 0.10), transparent 34rem), var(--page); }
+    body { max-width: 1040px; margin: 0 auto; padding: var(--space-4); color: var(--text); font: 100%/1.6 FT Kunst Grotesk, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; background: radial-gradient(circle at top left, rgba(255, 72, 1, 0.10), transparent 34rem), var(--page); }
     header { position: sticky; top: 0; z-index: 2; margin: 0 calc(-1 * var(--space-4)) var(--space-5); padding: var(--space-2) var(--space-4); backdrop-filter: blur(16px); background: var(--header-veil); }
     .skip-link { position: absolute; left: -9999px; }
     .skip-link:focus { position: fixed; left: var(--space-3); top: var(--space-3); z-index: 10; padding: .6rem 1rem; border: 1px solid var(--accent); border-radius: .5rem; background: var(--surface); color: var(--text); }
@@ -13,7 +13,7 @@
     h1 { font-size: clamp(2.4rem, 4.5vw, 3.75rem); margin: 0 0 1rem; }
     h2 { margin-top: 0; }
     p, li { text-wrap: pretty; }
-    pre { overflow: auto; padding: 1rem; border-radius: 1rem; background: #0b1020; color: #f9fafb; box-shadow: 0 1px 1px rgba(0,0,0,.12), 0 12px 42px rgba(0,0,0,.18); }
+    pre { overflow: auto; padding: 1rem; border-radius: 1rem; background: var(--terminal-bg); color: var(--terminal-ink); box-shadow: 0 1px 1px rgba(0,0,0,.12), 0 12px 42px rgba(0,0,0,.18); }
     textarea { box-sizing: border-box; width: 100%; height: auto; min-height: 18rem; padding: 0; overflow: hidden; resize: vertical; border: 0; outline: 0; background: transparent; color: var(--text); font: 14px/1.5 Apercu Mono Pro, SF Mono, Fira Code, Consolas, monospace; tab-size: 4; transition-property: box-shadow; transition-duration: 150ms; transition-timing-function: cubic-bezier(0, 0, 0.2, 1); }
     textarea:focus { box-shadow: 0 0 0 3px rgba(255, 72, 1, 0.18); }
     .textarea-fallback[hidden] { display: none; }
@@ -28,9 +28,11 @@
     .cm-selectionBackground, .cm-focused .cm-selectionBackground { background: rgba(255, 72, 1, 0.18) !important; }
     code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-variant-numeric: tabular-nums; }
     .syntax-inline { padding: .08rem .25rem; border-radius: .25rem; background: var(--accent-soft); color: var(--text); font-size: .94em; }
-    .brand { font-weight: 800; }
+    /* Nav tap targets: block padding grows the hit area to ~43px while
+       the negative margin cancels the layout growth. */
+    .brand { font-weight: 800; padding-block: .55rem; margin-block: -.55rem; }
     .nav-links { display: flex; gap: .35rem; }
-    .nav-links a { padding: 0 .9rem; color: var(--muted); }
+    .nav-links a { padding: .55rem .9rem; margin-block: -.55rem; color: var(--muted); }
     .hero { overflow: hidden; border: 1px solid var(--hairline); border-radius: 1rem; padding: clamp(1.25rem, 3.5vw, 2.5rem); margin-bottom: 1.25rem; background: linear-gradient(135deg, var(--surface), var(--surface-3)); box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transform-origin: top left; }
     .hero h1 { font-size: clamp(2rem, 4vw, 3rem); margin-bottom: var(--space-3); transform-origin: top left; }
     .hero p { max-width: 60ch; color: var(--muted); font-size: 1rem; }
@@ -40,7 +42,13 @@
         .hero h1 { animation: hero-h1-morph linear forwards; animation-timeline: scroll(root); animation-range: 0 240px; }
         .hero p { animation: hero-p-fade linear forwards; animation-timeline: scroll(root); animation-range: 0 140px; }
         body:has(.hero) { padding-top: var(--space-2); }
-        body:has(.hero) header { opacity: 0; background: var(--header-veil-0); box-shadow: none; margin-bottom: var(--space-2); animation: header-emerge linear forwards; animation-timeline: scroll(root); animation-range: 40px 240px; }
+        /* The brand blurs in on scroll, but the header (and its nav)
+           stays readable from first paint — hiding the primary nav on
+           landing fails the "where can I go?" test. The emerging veil
+           lives on a pseudo-element and animates opacity only, which
+           the compositor can do without repainting every scroll frame. */
+        body:has(.hero) header { background: transparent; box-shadow: none; margin-bottom: var(--space-2); }
+        body:has(.hero) header::before { content: ""; position: absolute; inset: 0; z-index: -1; background: var(--header-veil-solid); box-shadow: 0 1px 8px rgba(82, 16, 0, 0.06); opacity: 0; animation: header-veil-emerge linear forwards; animation-timeline: scroll(root); animation-range: 40px 240px; }
         body:has(.hero) header .brand { filter: blur(4px); transform: scale(0.88); animation: brand-focus linear forwards; animation-timeline: scroll(root); animation-range: 80px 240px; }
       }
     }
@@ -56,8 +64,8 @@
     @keyframes brand-focus {
       to { filter: blur(0); transform: scale(1); }
     }
-    @keyframes header-emerge {
-      to { opacity: 1; background: var(--header-veil-solid); box-shadow: 0 1px 8px rgba(82, 16, 0, 0.06); }
+    @keyframes header-veil-emerge {
+      to { opacity: 1; }
     }
     .site-search { position: relative; max-width: 44rem; margin: 0 0 var(--space-5); }
     .site-search input { width: 100%; min-height: 44px; padding: .6rem 1rem; border: 1px solid var(--hairline); border-radius: .75rem; background: var(--surface-2); color: var(--text); font: inherit; transition: border-color 160ms cubic-bezier(0.2, 0, 0, 1), box-shadow 160ms cubic-bezier(0.2, 0, 0, 1); }
@@ -74,6 +82,7 @@
     .home-section .eyebrow { margin: 0 0 var(--space-2); }
     .card { display: block; min-height: 10rem; border: 1px solid var(--hairline); border-radius: .75rem; padding: var(--space-3); background: var(--surface-2); color: inherit; text-decoration: none; box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transition-property: transform, background-color, border-color; transition-duration: 200ms; transition-timing-function: cubic-bezier(0, 0, 0.2, 1); }
     .card:hover { transform: translateY(-2px); background: var(--surface-3); border-color: var(--accent); }
+    .card:active { transform: translateY(0) scale(0.99); }
     .card h2 { text-decoration: underline; text-decoration-color: var(--hairline); text-underline-offset: .18em; }
     .card:hover h2 { text-decoration-color: var(--accent); }
     .button { min-height: 40px; border: 1px solid var(--accent); border-radius: 9999px; padding: .72rem 1rem; background: var(--accent); color: white; cursor: pointer; font-weight: 650; box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transition-property: transform, opacity, border-style; transition-duration: 150ms; transition-timing-function: cubic-bezier(0.25, 0.46, 0.45, 0.94); }
@@ -234,3 +243,18 @@
       .button { color: #FFF7EF; }
       .shiki, .shiki span { color: var(--shiki-dark) !important; }
     }
+    /* Non-motion accessibility signals. Reduced motion is handled by
+       the transition kill switch and no-preference gates above; these
+       cover the other two: solid chrome when translucency is reduced,
+       defined borders and full-contrast prose when contrast is raised. */
+    @media (prefers-reduced-transparency: reduce) {
+      header, body:has(.hero) header { background: var(--page); backdrop-filter: none; box-shadow: 0 1px 0 var(--hairline); }
+      body:has(.hero) header::before { content: none; }
+      .search-results { background: var(--surface); }
+    }
+    @media (prefers-contrast: more) {
+      header, body:has(.hero) header { background: var(--page); backdrop-filter: none; box-shadow: 0 1px 0 var(--text); }
+      body:has(.hero) header::before { content: none; }
+      .card, .runner-panel, .site-search input, .copy-button, .tool-button { border-color: var(--text); }
+      .meta, .lp-prose p, .lesson-step p, .nav-links a { color: var(--text); }
+    }