From 351e8d33917c49aecb1f7cb25d5b17b35c18d837 Mon Sep 17 00:00:00 2001
From: Abdullah Sultan <abdullahmsultan1@gmail.com>
Date: Thu, 6 Aug 2026 12:51:18 -0500
Subject: [PATCH] Make the site pass WCAG 2.2 AA, and publish an honest
 statement

The docs site had one skip link, on the landing page. Everything else -- the
docs shell, sign-in, sign-up, join, device, password reset, CLI login -- had
none, so a keyboard user tabbed the whole header on every page.

What was actually broken, beyond the skip links:

  * The sign-in and password-reset forms wrote their status and error messages
    into a <p hidden> and then unhid it. `hidden` takes the element out of the
    accessibility tree, so "Invalid login credentials" was announced to nobody.
    Both live regions now stay in the tree and are emptied instead, and a failed
    submit marks the fields aria-invalid pointing at the message.
  * Secondary text was #67676f on black: 3.5:1, at 12-14px. 48 elements on the
    landing page and 7 on every docs page failed 1.4.3. The two dim tokens are
    now 6:1. Input and button borders were 1.7:1 against their surface, under
    1.4.11's 3:1 for a control boundary; they take a new --control-line token.
  * The docs header is a bare row of six links with no mobile menu, so it ran
    260px off the side of a 320px viewport. It wraps now.
  * Standalone links -- the docs cards, "Next:", "Forgot your password?" -- were
    16-20px tall, under 2.5.8's 24px.
  * The hero's step strip was marked up as a tablist with no tabpanels and no
    arrow-key handling. It is a group of toggle buttons and now says so.
  * Code blocks scroll sideways with no way for a keyboard to reach the scroll.

docs/accessibility.md states the target (WCAG 2.2 AA), what was verified, and
eight limitations including the big one: this has not been driven with a screen
reader, so it does not claim full conformance.

apps/docs-site/src/a11y.test.ts runs axe-core over every page and over every
state the sign-in, join, and device pages render, and asserts the skip links
separately since axe has no rule for them. It runs under `pnpm test`.
---
 apps/docs-site/.gitignore                |   1 +
 apps/docs-site/auth/cli.html             |   3 +-
 apps/docs-site/auth/reset.html           |   3 +-
 apps/docs-site/auth/signin.html          |   3 +-
 apps/docs-site/auth/signup.html          |   3 +-
 apps/docs-site/auth/src/auth-form.js     |  32 ++--
 apps/docs-site/auth/src/reset.js         |  16 +-
 apps/docs-site/device.html               |   3 +-
 apps/docs-site/docs/cli.html             |  20 +--
 apps/docs-site/docs/index.html           |   7 +-
 apps/docs-site/docs/install.html         |  18 ++-
 apps/docs-site/docs/limitations.html     |   6 +-
 apps/docs-site/index.html                |  25 +--
 apps/docs-site/join.html                 |   3 +-
 apps/docs-site/scripts/generate-docs.mjs |  31 +++-
 apps/docs-site/src/a11y.test.ts          | 195 +++++++++++++++++++++++
 apps/docs-site/src/main.js               |   5 +-
 apps/docs-site/src/style.css             |  73 +++++++--
 apps/docs-site/vite.config.js            |   1 +
 docs/accessibility.md                    | 113 +++++++++++++
 package.json                             |  28 +++-
 pnpm-lock.yaml                           |   9 ++
 22 files changed, 514 insertions(+), 84 deletions(-)
 create mode 100644 apps/docs-site/src/a11y.test.ts
 create mode 100644 docs/accessibility.md

diff --git a/apps/docs-site/.gitignore b/apps/docs-site/.gitignore
index 8bba99b..eea9435 100644
--- a/apps/docs-site/.gitignore
+++ b/apps/docs-site/.gitignore
@@ -10,6 +10,7 @@ dist
 /docs/mcp-clients.html
 /docs/support.html
 /docs/terms.html
+/docs/accessibility.html
 /docs/refund-policy.html
 /public/docs/
 /public/llms.txt
diff --git a/apps/docs-site/auth/cli.html b/apps/docs-site/auth/cli.html
index 09c21bf..d7bd09d 100644
--- a/apps/docs-site/auth/cli.html
+++ b/apps/docs-site/auth/cli.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="auth"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="auth"></div></main>
   <script type="module" src="/auth/src/cli.js"></script>
 </body>
 </html>
diff --git a/apps/docs-site/auth/reset.html b/apps/docs-site/auth/reset.html
index d92fecd..85ac8c9 100644
--- a/apps/docs-site/auth/reset.html
+++ b/apps/docs-site/auth/reset.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="auth"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="auth"></div></main>
   <script type="module" src="/auth/src/reset.js"></script>
 </body>
 </html>
diff --git a/apps/docs-site/auth/signin.html b/apps/docs-site/auth/signin.html
index ce61ac5..d938a53 100644
--- a/apps/docs-site/auth/signin.html
+++ b/apps/docs-site/auth/signin.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="auth"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="auth"></div></main>
   <script type="module">
     import { mountAccountPage } from "/auth/src/account.js";
     void mountAccountPage("signin");
diff --git a/apps/docs-site/auth/signup.html b/apps/docs-site/auth/signup.html
index d46ee02..e142fba 100644
--- a/apps/docs-site/auth/signup.html
+++ b/apps/docs-site/auth/signup.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="auth"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="auth"></div></main>
   <script type="module">
     import { mountAccountPage } from "/auth/src/account.js";
     void mountAccountPage("signup");
diff --git a/apps/docs-site/auth/src/auth-form.js b/apps/docs-site/auth/src/auth-form.js
index a7a7e40..b1643e5 100644
--- a/apps/docs-site/auth/src/auth-form.js
+++ b/apps/docs-site/auth/src/auth-form.js
@@ -26,9 +26,9 @@ export function mountAuthForm(container, { mode = "signin", onSession }) {
     container.innerHTML = `
       <div class="auth-card">
         <a class="auth-brand" href="/">Crosscode</a>
-        <div class="auth-tabs">
-          <button type="button" data-mode="signin" class="${isSignup ? "" : "active"}">Sign in</button>
-          <button type="button" data-mode="signup" class="${isSignup ? "active" : ""}">Sign up</button>
+        <div class="auth-tabs" role="group" aria-label="Account">
+          <button type="button" data-mode="signin" aria-pressed="${isSignup ? "false" : "true"}" class="${isSignup ? "" : "active"}">Sign in</button>
+          <button type="button" data-mode="signup" aria-pressed="${isSignup ? "true" : "false"}" class="${isSignup ? "active" : ""}">Sign up</button>
         </div>
         <h1>${isSignup ? "Create your account" : "Welcome back"}</h1>
         <p class="auth-subtitle">
@@ -39,15 +39,20 @@ export function mountAuthForm(container, { mode = "signin", onSession }) {
         <form id="auth-form" class="stack">
           <label>
             Email
-            <input type="email" name="email" required autocomplete="email" />
+            <input type="email" name="email" required autocomplete="email" aria-describedby="auth-error" />
           </label>
           <label>
             Password
-            <input type="password" name="password" required minlength="6" autocomplete="${isSignup ? "new-password" : "current-password"}" />
+            <input type="password" name="password" required minlength="6" autocomplete="${isSignup ? "new-password" : "current-password"}" aria-describedby="auth-error" />
           </label>
           <button type="submit">${isSignup ? "Sign up" : "Sign in"}</button>
-          <p id="auth-status" class="muted" hidden></p>
-          <p id="auth-error" class="error" hidden></p>
+          <!-- Both stay in the DOM and empty rather than toggling the hidden attribute.
+               A live region a screen reader cannot see when the text arrives announces
+               nothing, and hidden takes the element out of the accessibility tree
+               entirely, so the old pattern wrote the message and then hid the only thing
+               that could have read it out. -->
+          <p id="auth-status" class="muted" role="status"></p>
+          <p id="auth-error" class="error" role="alert"></p>
         </form>
         <p class="auth-alt"><a href="/auth/reset.html">Forgot your password?</a></p>
         <div class="auth-divider"><span>or</span></div>
@@ -92,9 +97,12 @@ export function mountAuthForm(container, { mode = "signin", onSession }) {
       void handleSubmit();
     });
 
+    const inputs = [...form.querySelectorAll("input")];
+
     async function handleSubmit() {
-      errorEl.hidden = true;
-      statusEl.hidden = true;
+      errorEl.textContent = "";
+      statusEl.textContent = "";
+      for (const input of inputs) input.removeAttribute("aria-invalid");
       const formData = new FormData(form);
       const email = String(formData.get("email") ?? "");
       const password = String(formData.get("password") ?? "");
@@ -108,7 +116,6 @@ export function mountAuthForm(container, { mode = "signin", onSession }) {
             // Email confirmation is required before a session is issued; nothing more
             // to do here client-side until the user confirms and signs in.
             statusEl.textContent = "Check your email to confirm your account, then sign in.";
-            statusEl.hidden = false;
             return;
           }
           await createWorkspace(data.session.access_token, `${email}'s workspace`);
@@ -120,7 +127,10 @@ export function mountAuthForm(container, { mode = "signin", onSession }) {
         }
       } catch (error) {
         errorEl.textContent = error instanceof Error ? error.message : `${isSignup ? "Sign-up" : "Sign-in"} failed`;
-        errorEl.hidden = false;
+        // The service cannot say which field was wrong -- "invalid login credentials" is
+        // deliberately one answer for both -- so both are marked, and both point at the
+        // one message via aria-describedby.
+        for (const input of inputs) input.setAttribute("aria-invalid", "true");
       } finally {
         submitButton.disabled = false;
       }
diff --git a/apps/docs-site/auth/src/reset.js b/apps/docs-site/auth/src/reset.js
index 8847063..48ddc62 100644
--- a/apps/docs-site/auth/src/reset.js
+++ b/apps/docs-site/auth/src/reset.js
@@ -24,8 +24,8 @@ function renderRequestForm() {
           <input type="email" name="email" required autocomplete="email" />
         </label>
         <button type="submit">Send reset link</button>
-        <p id="auth-status" class="muted" hidden></p>
-        <p id="auth-error" class="error" hidden></p>
+        <p id="auth-status" class="muted" role="status"></p>
+        <p id="auth-error" class="error" role="alert"></p>
       </form>
       <p class="auth-alt"><a href="/auth/signin.html">Back to sign in</a></p>
     </div>
@@ -52,8 +52,8 @@ function renderUpdateForm() {
           <input type="password" name="password" required minlength="6" autocomplete="new-password" />
         </label>
         <button type="submit">Update password</button>
-        <p id="auth-status" class="muted" hidden></p>
-        <p id="auth-error" class="error" hidden></p>
+        <p id="auth-status" class="muted" role="status"></p>
+        <p id="auth-error" class="error" role="alert"></p>
       </form>
       <p class="auth-alt"><a href="/auth/signin.html">Back to sign in</a></p>
     </div>
@@ -75,15 +75,15 @@ function wire(submit) {
   form.addEventListener("submit", (event) => {
     event.preventDefault();
     void (async () => {
-      errorEl.hidden = true;
-      statusEl.hidden = true;
+      // Emptied rather than hidden: `hidden` drops the live region out of the
+      // accessibility tree, so a message written into a hidden one is announced to nobody.
+      errorEl.textContent = "";
+      statusEl.textContent = "";
       submitButton.disabled = true;
       try {
         statusEl.textContent = await submit(new FormData(form));
-        statusEl.hidden = false;
       } catch (error) {
         errorEl.textContent = error instanceof Error ? error.message : "Request failed";
-        errorEl.hidden = false;
       } finally {
         submitButton.disabled = false;
       }
diff --git a/apps/docs-site/device.html b/apps/docs-site/device.html
index 7fdcc3b..77ef7b2 100644
--- a/apps/docs-site/device.html
+++ b/apps/docs-site/device.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="device" class="auth-card"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="device" class="auth-card"></div></main>
   <script type="module">
     import { mountDevicePage } from "/src/device.js";
     void mountDevicePage(document.querySelector("#device"));
diff --git a/apps/docs-site/docs/cli.html b/apps/docs-site/docs/cli.html
index 71a1d27..cd45049 100644
--- a/apps/docs-site/docs/cli.html
+++ b/apps/docs-site/docs/cli.html
@@ -14,8 +14,10 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
+  <a class="skip-link" href="#main">Skip to content</a>
+
   <header class="site-header">
-    <nav>
+    <nav aria-label="Primary">
       <a class="brand" href="/">Crosscode</a>
       <a href="/docs/index.html">Docs</a>
       <a href="/docs/install.html">Install &amp; quickstart</a>
@@ -28,7 +30,7 @@
     </nav>
   </header>
 
-  <main class="docs-layout wide">
+  <main id="main" class="docs-layout wide">
     <nav class="docs-sidebar" aria-label="Docs navigation">
       <div>
         <div class="docs-sidebar-label">Start here</div>
@@ -99,7 +101,7 @@ <h2>crosscode start</h2>
         attaches the checkout to a project, starts the daemon, and installs the MCP server,
         the skill, and the pre-edit hooks for your coding agent.
       </p>
-      <pre><code>crosscode start
+      <pre tabindex="0"><code>crosscode start
 crosscode start --no-browser   # print the sign-in URL instead of opening a browser</code></pre>
       <p>
         Use <code>--no-browser</code> on a remote shell or in CI. Restart your agent afterwards
@@ -108,7 +110,7 @@ <h2>crosscode start</h2>
 
       <h2>crosscode invite</h2>
       <p>Prints a link that invites a teammate to this project. The link is the whole output.</p>
-      <pre><code>crosscode invite
+      <pre tabindex="0"><code>crosscode invite
 # https://www.getcrosscode.dev/join/7f3a9c2e</code></pre>
       <p>
         The join page checks the invitee actually has access to the repository before it hands
@@ -120,13 +122,13 @@ <h2>crosscode join &lt;code&gt;</h2>
         Redeems an invite code in this checkout, then sets it up exactly as <code>start</code>
         would. The code is a positional argument in the form printed by the join page.
       </p>
-      <pre><code>crosscode join CC-7F3A-9C2E
+      <pre tabindex="0"><code>crosscode join CC-7F3A-9C2E
 crosscode join CC-7F3A-9C2E --no-browser</code></pre>
 
       <h2>crosscode status</h2>
       <p>Shows what this checkout's daemon is doing.</p>
-      <pre><code>crosscode status --json</code></pre>
-      <pre><code>{
+      <pre tabindex="0"><code>crosscode status --json</code></pre>
+      <pre tabindex="0"><code>{
   "value": {
     "branch": "main",
     "connected": true,
@@ -147,7 +149,7 @@ <h2>crosscode stop</h2>
         Stops the daemon for this checkout. Syncing stops; nothing is uninstalled and nothing
         in your repository changes.
       </p>
-      <pre><code>crosscode stop</code></pre>
+      <pre tabindex="0"><code>crosscode stop</code></pre>
 
       <h2>Output envelope</h2>
       <p>
@@ -155,7 +157,7 @@ <h2>Output envelope</h2>
         with the failure shape, and an agent can branch on which key is present. Progress goes
         to stderr, so stdout stays a single parseable object.
       </p>
-      <pre><code>{"value": {"branch": "main", "connected": true, ...}}
+      <pre tabindex="0"><code>{"value": {"branch": "main", "connected": true, ...}}
 {"error": {"code": "NOT_A_GIT_REPOSITORY", "message": "Crosscode runs inside a Git repository", "hint": "cd into your project first."}}</code></pre>
       <p>
         Without <code>--json</code> the value is printed bare, because the envelope is only
diff --git a/apps/docs-site/docs/index.html b/apps/docs-site/docs/index.html
index 47c2d2d..be0785a 100644
--- a/apps/docs-site/docs/index.html
+++ b/apps/docs-site/docs/index.html
@@ -14,8 +14,10 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
+  <a class="skip-link" href="#main">Skip to content</a>
+
   <header class="site-header">
-    <nav>
+    <nav aria-label="Primary">
       <a class="brand" href="/">Crosscode</a>
       <a href="/docs/index.html">Docs</a>
       <a href="/docs/install.html">Install &amp; quickstart</a>
@@ -28,7 +30,7 @@
     </nav>
   </header>
 
-  <main class="docs-layout wide">
+  <main id="main" class="docs-layout wide">
     <nav class="docs-sidebar" aria-label="Docs navigation">
       <div>
         <div class="docs-sidebar-label">Start here</div>
@@ -77,6 +79,7 @@ <h1>Documentation</h1>
         UI, because there isn't one.
       </p>
 
+      <h2 class="visually-hidden">Documentation pages</h2>
       <div class="card-grid">
         <div class="card">
           <h3><a href="/docs/architecture.html">Architecture</a></h3>
diff --git a/apps/docs-site/docs/install.html b/apps/docs-site/docs/install.html
index ce1566a..878ca4b 100644
--- a/apps/docs-site/docs/install.html
+++ b/apps/docs-site/docs/install.html
@@ -14,8 +14,10 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
+  <a class="skip-link" href="#main">Skip to content</a>
+
   <header class="site-header">
-    <nav>
+    <nav aria-label="Primary">
       <a class="brand" href="/">Crosscode</a>
       <a href="/docs/index.html">Docs</a>
       <a href="/docs/install.html">Install &amp; quickstart</a>
@@ -28,7 +30,7 @@
     </nav>
   </header>
 
-  <main class="docs-layout wide">
+  <main id="main" class="docs-layout wide">
     <nav class="docs-sidebar" aria-label="Docs navigation">
       <div>
         <div class="docs-sidebar-label">Start here</div>
@@ -93,7 +95,7 @@ <h2>Prerequisites</h2>
       </ul>
 
       <h2>Install and start</h2>
-      <pre><code>npm install -g crosscode-cli
+      <pre tabindex="0"><code>npm install -g crosscode-cli
 cd your-repo
 crosscode start</code></pre>
 
@@ -116,12 +118,12 @@ <h2>Install and start</h2>
       </p>
 
       <h2>Bring in a teammate</h2>
-      <pre><code>crosscode invite</code></pre>
+      <pre tabindex="0"><code>crosscode invite</code></pre>
       <p>
         That prints a link. They open it, sign in with GitHub, and the page checks they
         actually have access to the repository before giving them two lines to paste:
       </p>
-      <pre><code>git clone git@github.com:acme/app.git &amp;&amp; cd app
+      <pre tabindex="0"><code>git clone git@github.com:acme/app.git &amp;&amp; cd app
 crosscode join CC-7F3A-9C2E</code></pre>
       <p>
         <code>join</code> redeems the code and then sets the checkout up exactly as
@@ -135,7 +137,7 @@ <h2>Day to day</h2>
         and a conflict goes to your coding agent rather than to you. The two remaining commands
         exist for when you want to look:
       </p>
-      <pre><code>crosscode status     # branch, connected, paused, who else is on this branch
+      <pre tabindex="0"><code>crosscode status     # branch, connected, paused, who else is on this branch
 crosscode stop       # stop syncing this checkout</code></pre>
 
       <h2>What syncs</h2>
@@ -149,7 +151,7 @@ <h2>What syncs</h2>
         Your commits, branches, index, stash, and remotes are never touched, and nothing here
         pushes. To undo anything Crosscode wrote:
       </p>
-      <pre><code>git checkout refs/crosscode/shadow -- &lt;path&gt;</code></pre>
+      <pre tabindex="0"><code>git checkout refs/crosscode/shadow -- &lt;path&gt;</code></pre>
 
       <h2>Hand the setup to your agent</h2>
       <p>
@@ -163,7 +165,7 @@ <h2>Hand the setup to your agent</h2>
 
       <h2>Running from a clone</h2>
       <p>For working on Crosscode itself, or for running the CLI before it is on npm:</p>
-      <pre><code>pnpm install
+      <pre tabindex="0"><code>pnpm install
 pnpm build          # typecheck + bundle
 pnpm test           # vitest
 pnpm crosscode -- status --json</code></pre>
diff --git a/apps/docs-site/docs/limitations.html b/apps/docs-site/docs/limitations.html
index 1c0e448..1a4b00f 100644
--- a/apps/docs-site/docs/limitations.html
+++ b/apps/docs-site/docs/limitations.html
@@ -14,8 +14,10 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
+  <a class="skip-link" href="#main">Skip to content</a>
+
   <header class="site-header">
-    <nav>
+    <nav aria-label="Primary">
       <a class="brand" href="/">Crosscode</a>
       <a href="/docs/index.html">Docs</a>
       <a href="/docs/install.html">Install &amp; quickstart</a>
@@ -28,7 +30,7 @@
     </nav>
   </header>
 
-  <main class="docs-layout wide">
+  <main id="main" class="docs-layout wide">
     <nav class="docs-sidebar" aria-label="Docs navigation">
       <div>
         <div class="docs-sidebar-label">Start here</div>
diff --git a/apps/docs-site/index.html b/apps/docs-site/index.html
index e906507..eeb99af 100644
--- a/apps/docs-site/index.html
+++ b/apps/docs-site/index.html
@@ -85,11 +85,11 @@ <h1 class="reveal">Your teammate's edit, already in your checkout</h1>
       <!-- The product, playing. -->
       <div class="wrap wrap-wide">
         <div class="stage reveal">
-          <div class="stage-tabs" role="tablist" aria-label="Steps in the loop">
-            <button type="button" role="tab" class="stage-tab" data-step-tab="1" aria-selected="false">Maya's agent writes</button>
-            <button type="button" role="tab" class="stage-tab" data-step-tab="2" aria-selected="false">Sent once it settles</button>
-            <button type="button" role="tab" class="stage-tab" data-step-tab="3" aria-selected="false">Applied to your tree</button>
-            <button type="button" role="tab" class="stage-tab" data-step-tab="4" aria-selected="false">Same lines? your agent</button>
+          <div class="stage-tabs" role="group" aria-label="Steps in the loop">
+            <button type="button" class="stage-tab" data-step-tab="1" aria-pressed="false" aria-controls="scene">Maya's agent writes</button>
+            <button type="button" class="stage-tab" data-step-tab="2" aria-pressed="false" aria-controls="scene">Sent once it settles</button>
+            <button type="button" class="stage-tab" data-step-tab="3" aria-pressed="false" aria-controls="scene">Applied to your tree</button>
+            <button type="button" class="stage-tab" data-step-tab="4" aria-pressed="false" aria-controls="scene">Same lines? your agent</button>
           </div>
 
           <div class="scene" id="scene" data-step="0">
@@ -103,7 +103,7 @@ <h1 class="reveal">Your teammate's edit, already in your checkout</h1>
                 </header>
                 <div class="panel-body">
                   <div class="file-head"><span class="file-name">services/payments/retry.ts</span><span class="file-state" data-state="editing">editing</span></div>
-                  <pre class="code"><code><span class="ln"><span class="c">// retry a failed capture with backoff</span></span>
+                  <pre class="code" tabindex="0"><code><span class="ln"><span class="c">// retry a failed capture with backoff</span></span>
 <span class="ln"><span class="k">export async function</span> <span class="f">retryCapture</span>(id: <span class="t">string</span>) {</span>
 <span class="ln add a1"><span class="s">+</span>  <span class="k">const</span> delays = [<span class="n">250</span>, <span class="n">1000</span>, <span class="n">4000</span>];</span>
 <span class="ln add a2"><span class="s">+</span>  <span class="k">for</span> (<span class="k">const</span> ms <span class="k">of</span> delays) {</span>
@@ -133,7 +133,7 @@ <h1 class="reveal">Your teammate's edit, already in your checkout</h1>
                 </header>
                 <div class="panel-body">
                   <div class="file-head"><span class="file-name">services/checkout/session.ts</span><span class="file-state" data-state="yours">yours, untouched</span></div>
-                  <pre class="code"><code><span class="ln"><span class="k">export function</span> <span class="f">startSession</span>(cart: <span class="t">Cart</span>) {</span><span class="ln">  <span class="k">const</span> total = <span class="f">sum</span>(cart.items);</span><span class="ln">  <span class="k">return</span> { id: <span class="f">uuid</span>(), total };</span><span class="ln">}</span></code></pre>
+                  <pre class="code" tabindex="0"><code><span class="ln"><span class="k">export function</span> <span class="f">startSession</span>(cart: <span class="t">Cart</span>) {</span><span class="ln">  <span class="k">const</span> total = <span class="f">sum</span>(cart.items);</span><span class="ln">  <span class="k">return</span> { id: <span class="f">uuid</span>(), total };</span><span class="ln">}</span></code></pre>
 
                   <div class="proposal">
                     <div class="proposal-head">
@@ -289,15 +289,15 @@ <h2>Free, with no paid plans yet</h2>
 
         <div class="plan-strip reveal">
           <div>
-            <h4>MIT licensed</h4>
+            <h3>MIT licensed</h3>
             <p>The CLI, daemon, and MCP server are yours to read, modify, and fork.</p>
           </div>
           <div>
-            <h4>No account beyond GitHub</h4>
+            <h3>No account beyond GitHub</h3>
             <p>The CLI signs in with GitHub, and an invite is checked against real repo access.</p>
           </div>
           <div>
-            <h4>Questions about a team</h4>
+            <h3>Questions about a team</h3>
             <p>Ask in the open. <a href="https://github.com/amsultan2010/crosscode/issues" rel="noopener">Open an issue</a>.</p>
           </div>
         </div>
@@ -322,7 +322,7 @@ <h2>One command, in the repo your team shares</h2>
             <span class="panel-path">run in your project</span>
             <button class="copy-btn" type="button" data-copy-target="install-command-text">Copy</button>
           </header>
-          <pre class="code"><code id="install-command-text">npm install -g crosscode-cli
+          <pre class="code" tabindex="0"><code id="install-command-text">npm install -g crosscode-cli
 cd your-repo
 crosscode start</code></pre>
         </div>
@@ -354,7 +354,7 @@ <h2>One command, in the repo your team shares</h2>
                 <span class="panel-path">paste into your coding agent</span>
                 <button class="copy-btn" type="button" data-copy-target="install-prompt-text">Copy prompt</button>
               </header>
-              <pre><code id="install-prompt-text">Set up Crosscode for this project. Crosscode syncs uncommitted working-tree files between
+              <pre tabindex="0"><code id="install-prompt-text">Set up Crosscode for this project. Crosscode syncs uncommitted working-tree files between
 my teammates' checkouts and mine in real time: they edit, my copy updates within seconds,
 and vice versa. It never touches commits, branches, or remotes. Do the following:
 
@@ -503,6 +503,7 @@ <h2>Trust</h2>
         <a href="/docs/limitations.html">Limitations</a>
         <a href="/docs/terms.html">Terms</a>
         <a href="/docs/support.html">Support</a>
+        <a href="/docs/accessibility.html">Accessibility</a>
       </nav>
       <nav class="footer-col" aria-label="More">
         <h2>More</h2>
diff --git a/apps/docs-site/join.html b/apps/docs-site/join.html
index 1f71ce3..72a961a 100644
--- a/apps/docs-site/join.html
+++ b/apps/docs-site/join.html
@@ -11,7 +11,8 @@
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
-  <main class="auth-shell"><div id="join"></div></main>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <main id="main" class="auth-shell"><div id="join"></div></main>
   <script type="module">
     import { mountJoinPage } from "/src/join.js";
     void mountJoinPage(document.querySelector("#join"));
diff --git a/apps/docs-site/scripts/generate-docs.mjs b/apps/docs-site/scripts/generate-docs.mjs
index b65cc09..b12f3ef 100644
--- a/apps/docs-site/scripts/generate-docs.mjs
+++ b/apps/docs-site/scripts/generate-docs.mjs
@@ -40,6 +40,14 @@ md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
   return defaultLinkOpen(tokens, idx, options, env, self);
 };
 
+// `pre` scrolls sideways (overflow-x: auto in style.css), and a scrollable region a
+// keyboard cannot reach is WCAG 2.1.1 -- the arrow keys need somewhere to land. Making
+// it focusable is the whole fix; a markdown code block has no name of its own to give it.
+for (const rule of ["fence", "code_block"]) {
+  const base = md.renderer.rules[rule];
+  md.renderer.rules[rule] = (...args) => base(...args).replace("<pre", '<pre tabindex="0"');
+}
+
 // Gives every heading a stable slug id (e.g. "## Available tools" -> "available-tools")
 // so other pages can deep-link with an anchor, matching common markdown-site behavior.
 md.core.ruler.push("heading_anchor_ids", (state) => {
@@ -97,7 +105,8 @@ const NAV_GROUPS = [
     label: "Support & legal",
     links: [
       { href: "/docs/support.html", label: "Support", key: "support" },
-      { href: "/docs/terms.html", label: "Terms of Service", key: "terms" }
+      { href: "/docs/terms.html", label: "Terms of Service", key: "terms" },
+      { href: "/docs/accessibility.html", label: "Accessibility", key: "accessibility" }
     ]
   }
 ];
@@ -159,6 +168,14 @@ const GENERATED_PAGES = [
     title: "Terms of Service",
     mdFile: "terms.md",
     htmlOut: "terms.html",
+    nextHref: "/docs/accessibility.html",
+    nextLabel: "Accessibility"
+  },
+  {
+    key: "accessibility",
+    title: "Accessibility",
+    mdFile: "accessibility.md",
+    htmlOut: "accessibility.html",
     nextHref: "/docs/index.html",
     nextLabel: "Docs overview"
   }
@@ -206,8 +223,10 @@ function renderPage({ title, activeKey, bodyHtml, mdHref, mdSourceRel, nextHref,
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 <body>
+  <a class="skip-link" href="#main">Skip to content</a>
+
   <header class="site-header">
-    <nav>
+    <nav aria-label="Primary">
       <a class="brand" href="/">Crosscode</a>
       <a href="/docs/index.html">Docs</a>
       <a href="/docs/install.html">Install &amp; quickstart</a>
@@ -220,7 +239,7 @@ function renderPage({ title, activeKey, bodyHtml, mdHref, mdSourceRel, nextHref,
     </nav>
   </header>
 
-  <main class="docs-layout wide">
+  <main id="main" class="docs-layout wide">
     <nav class="docs-sidebar" aria-label="Docs navigation">
 ${renderSidebar(activeKey)}
     </nav>
@@ -240,7 +259,7 @@ ${bodyHtml}
 
   <footer class="site-footer">
     <p>Crosscode: local-first Git coordination.</p>
-    <p><a href="/">Home</a> &middot; <a href="${GITHUB_REPO}" rel="noopener">View on GitHub</a></p>
+    <p><a href="/">Home</a> &middot; <a href="/docs/accessibility.html">Accessibility</a> &middot; <a href="${GITHUB_REPO}" rel="noopener">View on GitHub</a></p>
   </footer>
 </body>
 </html>
@@ -294,7 +313,9 @@ function syncInstallPrompt() {
 
   const indexPath = path.join(siteRoot, "index.html");
   const indexHtml = readFileSync(indexPath, "utf8");
-  const blockRe = /(<pre><code id="install-prompt-text">)[\s\S]*?(<\/code><\/pre>)/;
+  // `<pre` carries attributes now (tabindex, for keyboard access to the scroll), so the
+  // match cannot assume a bare tag.
+  const blockRe = /(<pre[^>]*><code id="install-prompt-text">)[\s\S]*?(<\/code><\/pre>)/;
   if (!blockRe.test(indexHtml)) {
     throw new Error('Could not find <pre><code id="install-prompt-text"> block in index.html');
   }
diff --git a/apps/docs-site/src/a11y.test.ts b/apps/docs-site/src/a11y.test.ts
new file mode 100644
index 0000000..5bdeca4
--- /dev/null
+++ b/apps/docs-site/src/a11y.test.ts
@@ -0,0 +1,195 @@
+// @vitest-environment jsdom
+//
+// Accessibility regression suite. The fixes in docs/accessibility.md decay within a month
+// without something that fails when they are undone, so this is that something.
+//
+// Two things it deliberately does:
+//
+//   * It runs axe against the *rendered* page, not the HTML file. The sign-in, join, and
+//     device pages ship a `<main>` containing one empty `<div>`; everything a person sees
+//     is built by JS. Scanning the file scans nothing.
+//   * It disables `color-contrast`. jsdom has no layout and does not apply the stylesheet,
+//     so axe cannot compute a single real contrast ratio here and would return every node
+//     as "incomplete". Contrast is checked in a real browser instead, against the colours
+//     the page actually composites, and docs/accessibility.md says so. The site has one
+//     theme -- dark, no light variant -- so that is one pass, not two.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import axe from "axe-core";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// Variable specifiers: these modules are plain JavaScript and the root tsconfig compiles
+// TypeScript only, so a literal specifier would be type-checked as a missing module.
+const JOIN = "./join.js";
+const DEVICE = "./device.js";
+const AUTH_FORM = "../auth/src/auth-form.js";
+
+type Renderer = (root: HTMLElement, state: { status: string; [key: string]: unknown }) => void;
+
+const WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "best-practice"];
+
+async function violationsFor(page: string, mount?: () => void | Promise<void>) {
+  const html = readFileSync(path.join(siteRoot, page), "utf8");
+  // Replaces the whole document, `<html lang>` and `<head>` included, so document-level
+  // rules (html-has-lang, page-has-heading-one, landmark rules) see the real page.
+  document.open();
+  document.write(html);
+  document.close();
+  await mount?.();
+
+  const results = await axe.run(document, {
+    runOnly: { type: "tag", values: WCAG_TAGS },
+    rules: { "color-contrast": { enabled: false } },
+    resultTypes: ["violations"]
+  });
+  return results.violations;
+}
+
+/** Names the rule and the offending markup, so a failure says what to fix. */
+function describeViolations(violations: axe.Result[]) {
+  return violations
+    .map((v) => `${v.id} (${v.impact}): ${v.help}\n${v.nodes.map((n) => `    ${n.html}`).join("\n")}`)
+    .join("\n");
+}
+
+async function expectClean(page: string, mount?: () => void | Promise<void>) {
+  const violations = await violationsFor(page, mount);
+  expect(describeViolations(violations)).toBe("");
+}
+
+beforeAll(() => {
+  // docs/*.html is generated and gitignored, so a clean checkout has none of it.
+  if (!existsSync(path.join(siteRoot, "docs/privacy.html"))) {
+    execFileSync("node", [path.join(siteRoot, "scripts/generate-docs.mjs")], { stdio: "inherit" });
+  }
+});
+
+describe("static pages", () => {
+  it("landing page has no axe violations", async () => {
+    await expectClean("index.html");
+  });
+
+  for (const page of ["docs/index.html", "docs/install.html", "docs/cli.html", "docs/limitations.html"]) {
+    it(`${page} has no axe violations`, async () => {
+      await expectClean(page);
+    });
+  }
+
+  // Generated pages share one template in scripts/generate-docs.mjs, so these two stand
+  // in for all of them -- and the accessibility statement is one of them, which means the
+  // page that claims conformance is itself under the check.
+  for (const page of ["docs/privacy.html", "docs/accessibility.html"]) {
+    it(`generated page ${page} has no axe violations`, async () => {
+      await expectClean(page);
+    });
+  }
+});
+
+describe("auth pages, as rendered", () => {
+  for (const mode of ["signin", "signup"] as const) {
+    it(`${mode} form has no axe violations`, async () => {
+      await expectClean(`auth/${mode}.html`, async () => {
+        const { mountAuthForm } = (await import(AUTH_FORM)) as {
+          mountAuthForm: (root: HTMLElement, options: { mode: string; onSession: () => void }) => void;
+        };
+        mountAuthForm(document.querySelector("#auth")!, { mode, onSession: () => {} });
+      });
+    });
+  }
+
+  // The submit error is the state a keyboard or screen-reader user is most likely to hit
+  // and the one most likely to be conveyed by colour alone, so it gets its own scan.
+  it("sign-in form with a visible error has no axe violations", async () => {
+    await expectClean("auth/signin.html", async () => {
+      const { mountAuthForm } = (await import(AUTH_FORM)) as {
+        mountAuthForm: (root: HTMLElement, options: { mode: string; onSession: () => void }) => void;
+      };
+      mountAuthForm(document.querySelector("#auth")!, { mode: "signin", onSession: () => {} });
+      document.querySelector<HTMLElement>("#auth-error")!.textContent = "Invalid login credentials";
+      for (const input of document.querySelectorAll("#auth-form input")) input.setAttribute("aria-invalid", "true");
+    });
+  });
+});
+
+describe("join page, every state", () => {
+  const states = [
+    { status: "signed-out" },
+    { status: "bad-link" },
+    { status: "expired" },
+    { status: "no-access" },
+    { status: "unreachable" },
+    { status: "ready", code: "CC-7F3A-9C2E", repo: "acme/app", cloneCommand: "git clone git@github.com:acme/app.git && cd app" }
+  ];
+
+  for (const state of states) {
+    it(`${state.status} has no axe violations`, async () => {
+      await expectClean("join.html", async () => {
+        const { renderJoin } = (await import(JOIN)) as { renderJoin: Renderer };
+        renderJoin(document.querySelector<HTMLElement>("#join")!, state);
+      });
+    });
+  }
+});
+
+describe("device page, every state", () => {
+  const states = [
+    { status: "signed-out" },
+    { status: "signed-out", staleSession: true },
+    { status: "ready", userCode: "" },
+    { status: "bad-code", userCode: "nope" },
+    { status: "expired", userCode: "WDJB-MJHT" },
+    { status: "used", userCode: "WDJB-MJHT" },
+    { status: "not-github", userCode: "WDJB-MJHT" },
+    { status: "unreachable", userCode: "WDJB-MJHT" },
+    { status: "bound" }
+  ];
+
+  for (const state of states) {
+    it(`${state.status}${state.staleSession ? " (stale session)" : ""} has no axe violations`, async () => {
+      await expectClean("device.html", async () => {
+        const { renderDevice } = (await import(DEVICE)) as { renderDevice: Renderer };
+        renderDevice(document.querySelector<HTMLElement>("#device")!, state);
+      });
+    });
+  }
+});
+
+// The skip link is the one fix that is trivial to lose when a page is copied from another,
+// and axe has no rule for it (bypass passes on any page with a landmark).
+describe("skip links", () => {
+  const pages = [
+    "index.html",
+    "join.html",
+    "device.html",
+    "docs/index.html",
+    "docs/install.html",
+    "docs/cli.html",
+    "docs/limitations.html",
+    "docs/privacy.html",
+    "docs/accessibility.html",
+    "auth/signin.html",
+    "auth/signup.html",
+    "auth/reset.html",
+    "auth/cli.html"
+  ];
+
+  for (const page of pages) {
+    it(`${page} has a skip link pointing at an element that exists`, () => {
+      const html = readFileSync(path.join(siteRoot, page), "utf8");
+      document.open();
+      document.write(html);
+      document.close();
+
+      const skip = document.querySelector<HTMLAnchorElement>("a.skip-link");
+      expect(skip, `${page} has no a.skip-link`).not.toBeNull();
+      expect(skip!.getAttribute("href")).toMatch(/^#\S+/);
+      const target = document.querySelector(skip!.getAttribute("href")!);
+      expect(target, `${page}: skip link target ${skip!.getAttribute("href")} does not exist`).not.toBeNull();
+    });
+  }
+});
diff --git a/apps/docs-site/src/main.js b/apps/docs-site/src/main.js
index 82d2d08..96bae0d 100644
--- a/apps/docs-site/src/main.js
+++ b/apps/docs-site/src/main.js
@@ -130,7 +130,10 @@ if (scene) {
     scene.dataset.step = String(step);
     const active = TAB_FOR_STEP[step];
     for (const tab of tabs) {
-      tab.setAttribute("aria-selected", String(Number(tab.dataset.stepTab) === active));
+      // aria-pressed, not aria-selected: the strip was marked up as a tablist but has
+      // no tabpanels and no arrow-key navigation, so it promised a widget it is not.
+      // It is a group of toggle buttons that drive one scene, and says so now.
+      tab.setAttribute("aria-pressed", String(Number(tab.dataset.stepTab) === active));
     }
   }
 
diff --git a/apps/docs-site/src/style.css b/apps/docs-site/src/style.css
index 351d031..a930787 100644
--- a/apps/docs-site/src/style.css
+++ b/apps/docs-site/src/style.css
@@ -19,9 +19,16 @@
   --bg-sunk: #08080a;
   --line: rgba(255, 255, 255, 0.09);
   --line-2: rgba(255, 255, 255, 0.2);
+  /* --line and --line-2 draw dividers and decorative edges, which WCAG 1.4.11 exempts.
+     --control-line draws the edge that *is* the control -- an input's box, a button's
+     outline -- and has to clear 3:1 against the surface behind it. On --bg-raise it is
+     about 4:1. Anything you can click or type into takes this one. */
+  --control-line: rgba(255, 255, 255, 0.42);
   --text: #ffffff;
   --text-2: #9d9da6;
-  --text-3: #67676f;
+  /* Was #67676f, which is 3.8:1 on black and fails 1.4.3 at the ~13-14px this token is
+     always used at. #8a8a92 is 6.1:1 on --bg and 5.7:1 on --bg-raise. */
+  --text-3: #8a8a92;
 
   /* White is the accent. Colour is reserved for things that mean something:
      a diff sign, a live dot. */
@@ -39,7 +46,9 @@
   --term-bg-2: #0e0e11;
   --term-line: rgba(255, 255, 255, 0.08);
   --term-text: #c9c9d1;
-  --term-dim: #6b6b73;
+  /* Was #6b6b73: 3.8:1 on --term-bg, and it carries real text (log lines, proposal
+     notes, code comments). #8c8c95 is 6.0:1. */
+  --term-dim: #8c8c95;
 
   --focus: var(--accent);
   --shadow-lg: 0 40px 90px -50px rgba(0, 0, 0, 1);
@@ -158,6 +167,33 @@ pre code {
 
 .skip-link:focus { top: 0; }
 
+/* For headings and labels that a sighted reader gets from layout and a screen
+   reader would otherwise never get at all. Not display:none, which would hide it
+   from both. */
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* WCAG 2.5.8 wants a 24px-tall target. A link sitting inside a sentence is exempt, which
+   covers most of this site's links; these are the standalone ones the audit measured
+   under 24px. Vertical padding rather than display:inline-block, so a long label can
+   still wrap at 320px. */
+.docs-next a,
+.auth-alt a,
+.card h3 a,
+.docs-sidebar-links a,
+.note > a:only-child {
+  padding-block: 0.25rem;
+}
+
 .wrap {
   width: 100%;
   max-width: var(--wrap);
@@ -219,7 +255,12 @@ pre code {
   padding: 0.72rem 1.5rem;
   display: flex;
   align-items: center;
-  gap: 1.4rem;
+  /* The docs shell has no mobile menu button -- its nav is a bare row of six links -- so
+     the row wraps rather than running 260px off the side of a 320px viewport, which is
+     WCAG 1.4.10. The landing nav is unaffected: below 60rem its links collapse into the
+     .nav-toggle dropdown and there is nothing left in the row to wrap. */
+  flex-wrap: wrap;
+  gap: 0.5rem 1.4rem;
   font-size: 0.9rem;
 }
 
@@ -254,7 +295,7 @@ pre code {
   align-items: center;
   gap: 0.5rem;
   background: none;
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   color: var(--text-2);
   font: inherit;
@@ -302,7 +343,7 @@ pre code {
   display: inline-flex;
   align-items: center;
   gap: 0.42rem;
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   padding: 0.32rem 0.78rem;
   text-decoration: none;
@@ -374,7 +415,7 @@ pre code {
 
 .btn-quiet {
   background: var(--bg-raise);
-  border-color: var(--line);
+  border-color: var(--control-line);
   color: var(--text);
 }
 
@@ -487,7 +528,7 @@ section.band { background: var(--bg-sunk); border-block: 1px solid var(--line);
 
 .copy-btn {
   background: var(--bg-raise);
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   color: var(--text-2);
   font: inherit;
@@ -518,7 +559,7 @@ section.band { background: var(--bg-sunk); border-block: 1px solid var(--line);
   justify-content: center;
   flex-wrap: wrap;
   gap: 0.25rem;
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   padding: 0.28rem;
   width: fit-content;
@@ -542,7 +583,7 @@ section.band { background: var(--bg-sunk); border-block: 1px solid var(--line);
 
 .stage-tab:hover { color: var(--text-2); }
 
-.stage-tab[aria-selected="true"] {
+.stage-tab[aria-pressed="true"] {
   background: rgba(255, 255, 255, 0.1);
   color: var(--text);
 }
@@ -551,7 +592,7 @@ section.band { background: var(--bg-sunk); border-block: 1px solid var(--line);
   display: block;
   margin: 1.5rem auto 0;
   background: none;
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   color: var(--text-3);
   font: inherit;
@@ -1095,7 +1136,9 @@ section.band { background: var(--bg-sunk); border-block: 1px solid var(--line);
   border-top: 1px solid var(--line);
 }
 
-.plan-strip h4 { margin-bottom: 0.4rem; }
+/* h3 rather than h4 so the heading level does not skip one under the section's h2;
+   the size stays what the h4 was. */
+.plan-strip h3 { font-size: 0.94rem; letter-spacing: -0.01em; margin-bottom: 0.4rem; }
 .plan-strip p { font-size: 0.87rem; color: var(--text-3); margin: 0; }
 
 /* --- install ------------------------------------------------------------- */
@@ -1475,7 +1518,7 @@ main:not(.docs-layout):not(#main) {
 
 .subtitle { font-size: 1.05rem; color: var(--text-2); max-width: var(--prose); }
 .cta { display: inline-flex; align-items: center; gap: 0.45rem; font-weight: 620; padding: 0.7rem 1.35rem; border-radius: 999px; background: var(--accent); color: var(--accent-fg); text-decoration: none; }
-.cta.secondary { background: transparent; color: var(--text); border: 1px solid var(--line-2); }
+.cta.secondary { background: transparent; color: var(--text); border: 1px solid var(--control-line); }
 .install-steps { font-size: 0.88rem; color: var(--text-3); margin-top: 1.4rem; }
 
 .terminal { border: 1px solid var(--term-line); border-radius: var(--radius); background: var(--term-bg); overflow: hidden; margin: 1.5rem 0; }
@@ -1554,7 +1597,7 @@ main:not(.docs-layout):not(#main) {
 .auth-tabs {
   display: flex;
   gap: 0.25rem;
-  border: 1px solid var(--line);
+  border: 1px solid var(--control-line);
   border-radius: 999px;
   padding: 0.25rem;
   margin-bottom: 1.5rem;
@@ -1599,7 +1642,7 @@ main:not(.docs-layout):not(#main) {
   font: inherit;
   font-size: 0.95rem;
   background: var(--bg-sunk);
-  border: 1px solid var(--line-2);
+  border: 1px solid var(--control-line);
   border-radius: var(--radius-sm);
   padding: 0.6rem 0.75rem;
   color: var(--text);
@@ -1669,7 +1712,7 @@ main:not(.docs-layout):not(#main) {
   font-size: 0.9rem;
   font-weight: 600;
   cursor: pointer;
-  border: 1px solid var(--line-2);
+  border: 1px solid var(--control-line);
   background: var(--bg-sunk);
   color: var(--text);
   border-radius: var(--radius-sm);
diff --git a/apps/docs-site/vite.config.js b/apps/docs-site/vite.config.js
index 04801a3..bca7f18 100644
--- a/apps/docs-site/vite.config.js
+++ b/apps/docs-site/vite.config.js
@@ -23,6 +23,7 @@ export default defineConfig({
         limitations: resolve(root, "docs/limitations.html"),
         support: resolve(root, "docs/support.html"),
         terms: resolve(root, "docs/terms.html"),
+        accessibility: resolve(root, "docs/accessibility.html"),
         signin: resolve(root, "auth/signin.html"),
         signup: resolve(root, "auth/signup.html"),
         passwordReset: resolve(root, "auth/reset.html"),
diff --git a/docs/accessibility.md b/docs/accessibility.md
new file mode 100644
index 0000000..5ca23e1
--- /dev/null
+++ b/docs/accessibility.md
@@ -0,0 +1,113 @@
+# Accessibility
+
+This statement covers **www.getcrosscode.dev** — the landing page, the docs, and the
+sign-in, join, and device pages. It does not cover the `crosscode` CLI, the daemon, or the
+MCP server, which are terminal programs and inherit whatever your terminal and screen
+reader already do.
+
+## The standard we aim at
+
+**WCAG 2.2, level AA.** That is what we test against and what we fix to.
+
+## Where we actually are
+
+**Partially conformant.** Every page passes the automated checks described below, and the
+checks we could run by hand pass too. We have not run this site with a screen reader end
+to end, so we cannot claim full conformance, and we are not going to claim it.
+
+What we have verified, on the landing page, all twelve docs pages, and the sign-in,
+sign-up, join, and device pages — in the case of the last four, in every state they can
+render, including their error states:
+
+- No `axe-core` violations at WCAG 2.2 AA, plus axe's best-practice rules, in a real
+  browser and in the test suite.
+- Every page on the site, including the password-reset and CLI-login pages, has a skip
+  link that points at its `<main>`. Every page scanned has one `<h1>` and heading levels
+  that do not skip.
+- All text meets 4.5:1 contrast (3:1 for large text) against the background actually
+  composited behind it. Interactive control borders — input boxes, button outlines —
+  meet 3:1.
+- No horizontal scrolling at a 320px-wide viewport, or at 200% zoom.
+- Every clickable target is at least 24×24px, except links sitting inside a sentence,
+  which WCAG exempts.
+- Tab order follows the document order. There are no positive `tabindex` values and no
+  focus traps. Focus is drawn as a 2px white outline, which is 21:1 against the page.
+- Form fields have real labels. Sign-in and password-reset errors are announced through a
+  live region rather than being written into a hidden element, and the fields are marked
+  `aria-invalid` when a submission fails. Errors are conveyed in words, not by colour.
+- The animated diagram on the landing page has a Pause button and stops entirely under
+  `prefers-reduced-motion`.
+
+## Known limitations
+
+These are real, and we would rather list them than let you find them.
+
+1. **No screen reader pass.** We checked the accessibility tree the browser exposes to
+   assistive technology, which is what a screen reader reads from, but we have not driven
+   the site with VoiceOver, NVDA, or JAWS from start to finish. Something can be correct
+   in the tree and still be awkward to hear.
+2. **No pass by a disabled user, and no third-party audit.** Everything below was done by
+   the person who wrote the site.
+3. **One theme.** The site is dark only. There is no light theme, and we have not tested
+   Windows High Contrast / `forced-colors` mode at all.
+4. **Code blocks have no name.** Wide code samples scroll sideways and are keyboard
+   focusable so you can scroll them with the arrow keys, but they announce as an unnamed
+   region rather than "code sample, bash".
+5. **The sign-in journey was tested as markup, not as a journey.** GitHub sign-in cannot
+   complete yet (see the [limitations page](/docs/limitations.html)), so the signed-in,
+   terminal-bound, and invite-accepted screens were audited as the markup those states
+   render, not by walking through them for real.
+6. **Automated testing finds a minority of problems.** `axe-core` detects perhaps a third
+   to a half of WCAG failures. Zero violations means zero violations of the rules it can
+   check, not zero problems.
+7. **Two pages were only checked structurally.** `/auth/reset.html` and `/auth/cli.html`
+   build themselves from scripts that need live credentials to run at all, so they were
+   checked for skip link, language, and title, and their form markup matches the sign-in
+   form that was scanned — but they have not been through `axe-core` as rendered.
+8. **We do not target level AAA**, and there is no plan to.
+
+## Tell us about a barrier
+
+Email **support@getcrosscode.dev**. Say what page you were on, what you were trying to
+do, and what you use — the browser, the screen reader, the magnification, whatever is
+relevant. A description of what went wrong is enough; you do not need to know which WCAG
+criterion it was.
+
+**What happens then:**
+
+- We acknowledge within **5 working days**.
+- If the barrier stops you installing Crosscode or signing in, we aim to fix it or give
+  you a working alternative within **30 days**, and tell you if that is going to slip.
+- Anything else goes on the list. We will tell you whether it is queued or declined, and
+  why, rather than leaving you without an answer.
+
+Crosscode is a one-person, pre-1.0 project. That is not an excuse for a barrier, but it is
+the reason the promise above is 5 days and 30 days rather than something faster.
+
+## How this was assessed
+
+- **Last assessed:** 6 August 2026.
+- **Assessed by:** {{PROVIDER_NAME}}, self-assessment.
+- **Automated tool:** `axe-core` 4.13, run at tags `wcag2a`, `wcag2aa`, `wcag21a`,
+  `wcag21aa`, `wcag22aa` and `best-practice`. Run two ways: in a real Chromium browser
+  against every built page, and in the repository's test suite (`apps/docs-site/src/a11y.test.ts`)
+  against every page and every state the sign-in, join, and device pages can render. The
+  suite runs on every `pnpm test`, so a regression fails the build rather than waiting for
+  the next audit.
+- **Manual checks:** contrast computed from the browser's own resolved colours against the
+  composited background, for every text node on every page; reflow at a 320px viewport and
+  at 200% zoom; target sizes measured from live layout; tab order and focus styling read
+  from the DOM and the stylesheet; the accessibility tree inspected on the sign-in, join,
+  and device pages.
+- **Not done:** screen reader testing, `forced-colors` testing, and any testing with
+  assistive technology other than the browser's own accessibility tree.
+
+The next assessment is due whenever the site's markup changes materially, and the
+regression suite runs in the meantime.
+
+## Before this takes effect
+
+Fill these in:
+
+- `{{PROVIDER_NAME}}` — the legal name of the individual who publishes Crosscode, used
+  above under "Assessed by".
diff --git a/package.json b/package.json
index 69485d4..f489cd0 100644
--- a/package.json
+++ b/package.json
@@ -3,17 +3,34 @@
   "version": "0.1.0",
   "description": "Real-time codebase sync between teammates. You edit a file, their checkout updates within seconds; same-line conflicts go to your own coding agent over MCP",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/amsultan2010/crosscode.git" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amsultan2010/crosscode.git"
+  },
   "homepage": "https://github.com/amsultan2010/crosscode#readme",
-  "bugs": { "url": "https://github.com/amsultan2010/crosscode/issues" },
-  "keywords": ["ai", "agents", "coding-agents", "mcp", "git", "collaboration", "coordination"],
+  "bugs": {
+    "url": "https://github.com/amsultan2010/crosscode/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "coding-agents",
+    "mcp",
+    "git",
+    "collaboration",
+    "coordination"
+  ],
   "type": "module",
   "bin": {
     "crosscode": "dist/cli.js",
     "crosscode-mcp": "dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c",
   "engines": {
     "node": ">=24"
@@ -53,6 +70,7 @@
     "@types/jsdom": "^28.0.3",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "axe-core": "^4.13.0",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.11.1",
     "jsdom": "^30.0.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aa15147..fd78d9c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -56,6 +56,9 @@ importers:
       '@vitest/coverage-v8':
         specifier: ^3.2.4
         version: 3.2.7(supports-color@7.2.0)(vitest@3.2.7(@types/node@24.13.3)(happy-dom@20.11.1)(jsdom@30.0.1)(supports-color@7.2.0)(tsx@4.23.1)(yaml@2.9.0))
+      axe-core:
+        specifier: ^4.13.0
+        version: 4.13.0
       esbuild:
         specifier: ^0.28.1
         version: 0.28.1
@@ -783,6 +786,10 @@ packages:
   ast-v8-to-istanbul@0.3.12:
     resolution: {integrity: sha512-BRRC8VRZY2R4Z4lFIL35MwNXmwVqBityvOIwETtsCSwvjl0IdgFsy9NhdaA6j74nUdtJJlIypeRhpDam19Wq3g==}
 
+  axe-core@4.13.0:
+    resolution: {integrity: sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==}
+    engines: {node: '>=4'}
+
   balanced-match@4.0.4:
     resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
     engines: {node: 18 || 20 || >=22}
@@ -2137,6 +2144,8 @@ snapshots:
       estree-walker: 3.0.3
       js-tokens: 10.0.0
 
+  axe-core@4.13.0: {}
+
   balanced-match@4.0.4: {}
 
   bidi-js@1.0.3: