fix(sites): Phase 2 polish — a11y to 100, header overflow, invert bug, stale refs

Docs: whole-site .dark invert bug fixed (partial :global selector miscompiled
to a bare .dark rule — invert now unscoped-scoped to the credit mark only);
role=main on the home layout; section eyebrows become real h2s; search
placeholder and agents-band flag contrast to AA; mobile home nav goes carbon;
pre-footer gap tightened; stale FamilyFooter comment updated. Playground:
header fits one row at every width >=1024 (NAV collapses to overflow <1600);
CodeMirror content gets an accessible name; tabs get real tablist/tab/
tabpanel roles with aria-selected; README updated for the styles/ split.
Both sites ship a robots.txt. Lighthouse: docs home and playground both
100/100/100 (a11y/BP/SEO); hero CLS 0.01.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ChanMeng666

docs-site/.vitepress/config.ts

@@ -188,8 +188,9 @@ export default defineConfig({
     ],
     socialLinks: [{ icon: "github", link: "https://github.com/chanmeng666/archlang" }],
     search: { provider: "local" },
-    // The site-wide footer is rendered by FamilyFooter.vue (layout-bottom slot),
-    // which carries the MIT/copyright line plus the brand-family ecosystem links.
-    // Omitting the built-in `footer` here avoids a duplicate footer.
+    // The site-wide footer is rendered by TitleBlockFooter.vue (layout-bottom slot),
+    // a drawing title block carrying the project/license/issued cells plus the
+    // brand-family ecosystem links. Omitting the built-in `footer` here avoids a
+    // duplicate footer.
   },
 });

docs-site/.vitepress/theme/Layout.vue

@@ -2,11 +2,22 @@
 // Wraps the VitePress default Layout to inject the brand-family pieces through
 // official slots: the "Compile Boundary" hero above the homepage body
 // (home-hero-before) and the title-block footer site-wide (layout-bottom).
+import { onMounted } from "vue";
 import DefaultTheme from "vitepress/theme";
 import CompileSeam from "./CompileSeam.vue";
 import TitleBlockFooter from "./TitleBlockFooter.vue";
 
 const { Layout } = DefaultTheme;
+
+// The `layout: home` page renders no <main> landmark (VitePress uses a bare
+// #VPContent > .VPHome). Mark .VPHome as the main landmark so the page has
+// exactly one — but only if the page doesn't already expose a main (inner
+// doc pages do), so we never create a duplicate. Client-only; harmless on
+// hydrate since it mutates an existing element's attribute after mount.
+onMounted(() => {
+  if (document.querySelector('main, [role="main"]')) return;
+  document.querySelector(".VPHome")?.setAttribute("role", "main");
+});
 </script>
 
 <template>

docs-site/.vitepress/theme/SheetGrid.vue

@@ -64,7 +64,7 @@ const row2: Sheet[] = [
     <div class="dimdiv" role="presentation">
       <span class="dimdiv__tick" />
       <span class="dimdiv__line" />
-      <span class="dimdiv__label">Features · Sheets A-101 — A-105</span>
+      <h2 class="dimdiv__label">Features · Sheets A-101 — A-105</h2>
       <span class="dimdiv__line" />
       <span class="dimdiv__tick" />
     </div>
@@ -138,10 +138,17 @@ const row2: Sheet[] = [
 }
 .dimdiv__label {
   flex: none;
+  /* It IS the section's h2 (heading order: hero h1 → this → card h3s), styled as
+     a dimension-line label. Reset the .vp-doc h2 box so the drawing detail is
+     visually unchanged. */
+  margin: 0;
+  border: 0;
+  padding: 0;
   font-family: var(--font-display);
   font-variation-settings: "wdth" 86;
   font-weight: 600;
   font-size: 11px;
+  line-height: 1;
   letter-spacing: 0.13em;
   text-transform: uppercase;
   color: var(--ink-muted);

docs-site/.vitepress/theme/TitleBlockFooter.vue

@@ -161,9 +161,6 @@ const ECOSYSTEM = [
 .cell__credit img {
   display: block;
 }
-:global(.dark) .cell__credit img {
-  filter: invert(1);
-}
 .cell__links {
   display: flex;
   flex-wrap: wrap;
@@ -180,3 +177,13 @@ const ECOSYSTEM = [
   color: var(--redline-ink);
 }
 </style>
+
+<style>
+/* Unscoped on purpose: partial `:global(.dark) descendant` selectors are
+   miscompiled by the SFC compiler into a bare `.dark` rule (which inverted
+   the whole site). The credit mark is the one raster that needs inverting
+   on mylar. */
+.dark .cell__credit img {
+  filter: invert(1);
+}
+</style>

docs-site/.vitepress/theme/doc-pages.css

@@ -445,11 +445,22 @@ html:not(.dark) .vp-doc .vp-code span {
   color: var(--redline-ink);
 }
 
-.DocSearch-Button {
+/* Paper-world search trigger — everywhere EXCEPT the home page's carbon
+   `.home.top` bar, which paints its own source-world ghost trigger in home.css.
+   Scoped off `.home.top` (instead of an even louder !important there) so the
+   carbon bar's search doesn't read as a white block over the hero, at any width. */
+.VPNavBar:not(.home.top) .DocSearch-Button {
   border-radius: 3px !important;
   border: 1px solid var(--hairline) !important;
   background: var(--paper-panel) !important;
 }
+/* On the paper bar the placeholder + hotkey hint must be paper-world ink, not the
+   source-world --src-muted (#98a0ac → only 2.5:1 on --paper-panel). --ink-muted
+   is 5.4:1 AA. (The carbon .home.top bar keeps --src-muted via home.css.) */
+.VPNavBar:not(.home.top) .DocSearch-Button .DocSearch-Button-Placeholder,
+.VPNavBar:not(.home.top) .DocSearch-Button .DocSearch-Button-Key {
+  color: var(--ink-muted) !important;
+}
 
 /* ============================================================================
    10 · PREV/NEXT FOOTER · EDIT LINK · LAST UPDATED

docs-site/.vitepress/theme/home.css

@@ -67,6 +67,42 @@
   color: var(--src-muted);
 }
 
+/* Mobile nav (<768px): the search trigger and the hamburger share the carbon
+   `.home.top` bar. The .DocSearch-Button rules above give the trigger its
+   source-world ghost look (the paper-world fill lives in doc-pages.css, scoped
+   off `.home.top`). The remaining mobile-only piece is the hamburger's three
+   bars, which default to the paper world's dark ink (--vp-c-text-1) and are
+   near-invisible on carbon — re-tint them to the source world. */
+.VPNavBar.home.top .DocSearch-Button:hover .DocSearch-Search-Icon {
+  background-color: var(--src-fg);
+}
+.VPNavBar.home.top .VPNavBarHamburger .top,
+.VPNavBar.home.top .VPNavBarHamburger .middle,
+.VPNavBar.home.top .VPNavBarHamburger .bottom {
+  background-color: var(--src-fg);
+}
+.VPNavBar.home.top .VPNavBarHamburger:hover .top,
+.VPNavBar.home.top .VPNavBarHamburger:hover .middle,
+.VPNavBar.home.top .VPNavBarHamburger:hover .bottom {
+  background-color: var(--plum-bright);
+}
+
+/* ═══ Landing bottom — deliberate footer gap ═══════════════════════════════
+   The last landing section is the carbon "agents" band; VitePress's default
+   `.VPHome` margin-bottom (96/128px) then drops the title-block footer, which
+   over a dark band reads as a pale void. Tighten it to a deliberate ~112px so
+   the footer follows the band as an intended step, not empty paper.
+   (Selector carries `.VPContent.is-home` so it outranks VitePress's scoped
+   `.VPHome[data-v-…]` default of 96/128px.) */
+.VPContent.is-home .VPHome {
+  margin-bottom: 96px;
+}
+@media (min-width: 768px) {
+  .VPContent.is-home .VPHome {
+    margin-bottom: 112px;
+  }
+}
+
 /* ═══ Landing sections — full bleed ════════════════════════════════════════
    The section components render inside `.vp-doc.container` (max-width + padding).
    Pull them out to the full viewport width with VitePress's own `--vp-offset`
@@ -146,7 +182,11 @@
   user-select: none;
 }
 .vp-doc .agents__flag {
-  color: var(--redline);
+  /* On-carbon redline: a FIXED lightened redline (the band is carbon in both
+     light and dark, so --redline — which flips per mode and is only AA on paper —
+     can't be used). #f0705f on carbon-2 (#171b23) = 5.9:1, well past AA for this
+     micro-label, and stays redline-family (distinct from the plum keys). */
+  color: #f0705f;
 }
 .vp-doc .agents__key {
   color: var(--plum-bright);

docs-site/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

playground/README.md

@@ -42,12 +42,14 @@ The playground is TypeScript; every module below is `.ts` except the generated g
 | `preview.ts` / `pan-zoom.ts` | SVG preview + circulation Paths overlay; CSS-transform pan/zoom/fit controller |
 | `interact.ts` | hover-room tooltip + click-to-source (`data-span`) |
 | `actions.ts` | header actions: **Format**, **Repair furniture**, **Embed**, copy-link |
+| `llm-prompt.ts` | builds the **Copy for LLM** payload (source + `describe()` facts + diagnostics) |
 | `embed.ts` / `viewer.ts` | Embed-snippet builder; the chrome-less `embed.html` viewer runtime |
 | `facts-strip.ts` / `describe-panel.ts` / `lint-panel.ts` / `diagnostics-panel.ts` | the `describe()`/`lint()` fact & diagnostic panels |
 | `share.ts` | `#z=` deflate-raw permalink encode/decode (reads legacy `#src=`) |
 | `raster-export.ts` | copy/download SVG · PNG · DXF · PDF |
 | `snapshots.ts` / `storage.ts` | named snapshot history UI + defensive `localStorage` helpers |
-| `examples.ts`, `flowing-lines.ts`, `escape.ts`, `style.css` | example plans, brand animation, HTML-escape helper, styles |
+| `examples.ts`, `escape.ts` | example plans, HTML-escape helper |
+| `styles/*.css` | the shell's styles, split by concern: `tokens.css` (the shared "Compile Boundary" brand tokens, byte-identical with the docs site), `chrome.css` (carbon source-world header + the compile-seam divider), `editor.css`, `panels.css` (sheet-world output panels), `embed.css` (the chrome-less viewer) |
 
 ## Run
 

playground/index.html

@@ -74,7 +74,7 @@
       </div>
       <div class="spacer"></div>
       <!-- brand-family navigation: quiet text links (no boxes), right-aligned.
-           Collapses into the "⋯" disclosure below <1024px (CSS-only). -->
+           Collapses into the "⋯" disclosure below <1600px (CSS-only). -->
       <nav class="tb-nav" aria-label="Related sites">
         <a href="https://archlang-docs.vercel.app" target="_blank" rel="noopener">Docs ↗</a>
         <a href="https://archlang-docs.vercel.app/spec" target="_blank" rel="noopener">Spec</a>
@@ -101,13 +101,13 @@ <h2 class="src-tab">SOURCE.ARCH</h2>
         <h2>
           <span class="dot" id="status"></span><span id="statusText">ready</span>
           <span class="grow"></span>
-          <span class="tabs" role="tablist">
-            <button class="tab active" data-tab="preview" type="button">Preview</button>
-            <button class="tab" data-tab="describe" type="button">Describe</button>
-            <button class="tab" data-tab="lint" type="button">Lint</button>
+          <span class="tabs" role="tablist" aria-label="Output view">
+            <button class="tab active" id="tab-preview" data-tab="preview" type="button" role="tab" aria-selected="true" aria-controls="preview">Preview</button>
+            <button class="tab" id="tab-describe" data-tab="describe" type="button" role="tab" aria-selected="false" aria-controls="describe">Describe</button>
+            <button class="tab" id="tab-lint" data-tab="lint" type="button" role="tab" aria-selected="false" aria-controls="lint">Lint</button>
           </span>
         </h2>
-        <div id="preview" class="tabview active" role="tabpanel">
+        <div id="preview" class="tabview active" role="tabpanel" aria-labelledby="tab-preview">
           <div class="pz-viewport">
             <div class="pz-stage"></div>
             <div class="pz-toolbar">
@@ -124,8 +124,8 @@ <h2>
           </div>
           <div id="facts" class="facts" aria-label="Plan facts"></div>
         </div>
-        <div id="describe" class="tabview" role="tabpanel"></div>
-        <div id="lint" class="tabview" role="tabpanel">
+        <div id="describe" class="tabview" role="tabpanel" aria-labelledby="tab-describe"></div>
+        <div id="lint" class="tabview" role="tabpanel" aria-labelledby="tab-lint">
           <div class="lint-controls">
             <label for="lintProfile">Profile</label>
             <select id="lintProfile" aria-label="Lint profile"></select>

playground/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /