From 98efd56d173cb86cc39e520273d869ab9a83aecd Mon Sep 17 00:00:00 2001
From: Seth <sbertal@yahooinc.com>
Date: Mon, 28 Sep 2026 17:06:25 -0700
Subject: [PATCH] fix(site): fix accessibility issues in the docs site

Lighthouse accessibility on the 12 docs pages goes from 57-90 to 93-100.
Everything still failing comes from Pure's own CSS, which is unchanged.

- Darken body text (#777 -> #666), subheads (#888 -> #666), links
  (#3b8bba -> #31739a) and the accent blue (#1f8dd6 -> #1a75b3) so they
  meet 4.5:1 on every background they sit on.
- Underline links in running text, and make callout links white.
- Use the a11y-light syntax highlighting theme for code blocks.
- Wrap page content in <main>; give the menu toggle aria-label,
  aria-controls and aria-expanded (kept in sync by ui.js).
- Make footer links at least 24px tall.
- Homepage: fix size chart and demo button contrast.
- Buttons page: darken the custom button example backgrounds.
- Forms page: label the read-only and rounded input examples.
- Tools page: move list descriptions inside their <li>s.

Fixes #1204

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 site/components/CodeBlock.js    |  4 ++--
 site/components/Menu.js         |  2 +-
 site/src/pages/buttons/index.js |  6 ++---
 site/src/pages/forms/index.js   |  4 ++--
 site/src/pages/styles.css       | 40 +++++++++++++++++++--------------
 site/src/pages/tools/index.js   |  6 ++---
 site/src/theme/Layout.js        |  4 ++--
 site/static/css/main.css        | 27 ++++++++++++++++------
 site/static/js/ui.js            |  2 ++
 9 files changed, 57 insertions(+), 38 deletions(-)

diff --git a/site/components/CodeBlock.js b/site/components/CodeBlock.js
index 44fbc8cd5..ce5136533 100644
--- a/site/components/CodeBlock.js
+++ b/site/components/CodeBlock.js
@@ -1,6 +1,6 @@
 import classnames from 'classnames';
 import SyntaxHighlighter from 'react-syntax-highlighter';
-import { docco } from 'react-syntax-highlighter/dist/esm/styles/hljs';
+import { a11yLight } from 'react-syntax-highlighter/dist/esm/styles/hljs';
 
 function CodeBlock({ children, language = 'html', full = false, wrap = false }) {
     var fullClass = classnames({ 'is-code-full': full });
@@ -8,7 +8,7 @@ function CodeBlock({ children, language = 'html', full = false, wrap = false })
     return (
         <div className={fullClass}>
             <div className={codeClass}>
-                <SyntaxHighlighter language={language} style={docco} wrapLongLines={full}>{children}</SyntaxHighlighter>
+                <SyntaxHighlighter language={language} style={a11yLight} wrapLongLines={full}>{children}</SyntaxHighlighter>
             </div>
         </div>
     );
diff --git a/site/components/Menu.js b/site/components/Menu.js
index 1896454ac..00a817902 100644
--- a/site/components/Menu.js
+++ b/site/components/Menu.js
@@ -3,7 +3,7 @@ import Link from '@docusaurus/Link';
 function Menu() {
     return (
         <>
-            <a href="#menu" id="menuLink" className="menu-link">
+            <a href="#menu" id="menuLink" className="menu-link" aria-label="Menu" aria-controls="menu" aria-expanded="false">
                 <span></span>
             </a>
             
diff --git a/site/src/pages/buttons/index.js b/site/src/pages/buttons/index.js
index 82d48219d..f03a1149b 100644
--- a/site/src/pages/buttons/index.js
+++ b/site/src/pages/buttons/index.js
@@ -83,16 +83,16 @@ function Buttons() {
                          text-shadow: 0 1px 1px rgba(0, 0, 0, 0.2);
                      }
                      .button-success {
-                         background: rgb(28, 184, 65); /* this is a green */
+                         background: rgb(21, 135, 48); /* this is a green */
                      }
                      .button-error {
                          background: rgb(202, 60, 60); /* this is a maroon */
                      }
                      .button-warning {
-                         background: rgb(223, 117, 20); /* this is an orange */
+                         background: rgb(180, 94, 16); /* this is an orange */
                      }
                      .button-secondary {
-                         background: rgb(66, 184, 221); /* this is a light blue */
+                         background: rgb(28, 126, 157); /* this is a blue */
                      }
                     `}} />
                         <button className="button-success pure-button">Success Button</button>
diff --git a/site/src/pages/forms/index.js b/site/src/pages/forms/index.js
index 4b2b81cfa..430f4f63a 100644
--- a/site/src/pages/forms/index.js
+++ b/site/src/pages/forms/index.js
@@ -256,7 +256,7 @@ function Forms() {
 
                 <Example>
                     <form className="pure-form">
-                        <input type="text" value="Readonly input here..." readOnly />
+                        <input type="text" value="Readonly input here..." aria-label="Read-only example" readOnly />
                     </form>
                 </Example>
 
@@ -268,7 +268,7 @@ function Forms() {
 
                 <Example>
                     <form className="pure-form">
-                        <input type="text" className="pure-input-rounded" />
+                        <input type="text" className="pure-input-rounded" aria-label="Search" />
                         <button type="submit" className="pure-button">Search</button>
                     </form>
                 </Example>
diff --git a/site/src/pages/styles.css b/site/src/pages/styles.css
index 58306b9a6..20bd662a7 100644
--- a/site/src/pages/styles.css
+++ b/site/src/pages/styles.css
@@ -52,9 +52,9 @@ a.button-secondary {
 }
 
 a.button-cta {
-  background: #1f8dd6;
+  background: #1a75b3;
   color: #fff;
-  border: 1px solid #1f8dd6;
+  border: 1px solid #1a75b3;
 }
 
 a.button-secondary {
@@ -91,40 +91,46 @@ a.size-chart-item {
 }
 
 .size-chart-base {
-  background: #1f8dd6;
+  background: #1a75b3;
 }
 .size-chart-base .size-chart-size {
-  color: rgb(103, 194, 240);
+  color: #fff;
 }
 
 .size-chart-grids {
   background: rgb(128, 88, 165);
 }
 .size-chart-grids .size-chart-size {
-  color: rgb(200, 131, 255);
+  color: #fff;
 }
 
 .size-chart-forms {
   background: #5eb95e;
 }
+/* Dark text on the lighter colors keeps the labels readable. */
+.size-chart-forms a.size-chart-item,
+.size-chart-menus a.size-chart-item,
+.size-chart-tables a.size-chart-item {
+  color: #222;
+}
 
 .size-chart-forms .size-chart-size {
-  color: rgb(161, 240, 137);
+  color: #222;
 }
 
 .size-chart-buttons {
-  background: #dd514c;
+  background: #d83933;
 }
 
 .size-chart-buttons .size-chart-size {
-  color: rgb(236, 164, 154);
+  color: #fff;
 }
 
 .size-chart-menus {
   background: rgb(250, 210, 50);
 }
 .size-chart-menus .size-chart-size {
-  color: rgb(255, 240, 134);
+  color: #222;
 }
 
 .size-chart-tables {
@@ -134,7 +140,7 @@ a.size-chart-item {
   margin-left: -0.5em;
 }
 .size-chart-tables .size-chart-size {
-  color: rgb(255, 190, 129);
+  color: #222;
 }
 
 .marketing {
@@ -176,12 +182,12 @@ a.size-chart-item {
 
 .button-a {
   background: #e1f2fa;
-  color: #5992aa;
+  color: #447184;
 }
 
 .button-b {
   background: #fcebbd;
-  color: #af9540;
+  color: #7b682d;
 }
 
 .button-c,
@@ -202,25 +208,25 @@ a.size-chart-item {
 }
 .button-d {
   background: #d3eda3;
-  color: #72962e;
+  color: #526c21;
 }
 
 .button-e {
   background: #f5ab9e;
-  color: #8c3a2b;
+  color: #7e3427;
 }
 .button-f {
   background: #ddaeff;
-  color: #8156a7;
+  color: #5f3f7b;
 }
 
 .button-g {
   background: #f57b00;
-  color: #ffca95;
+  color: #222;
 }
 
 .button-h {
-  background: #008ed4;
+  background: #007bb7;
   color: #fff;
 }
 .sample-button .button-h {
diff --git a/site/src/pages/tools/index.js b/site/src/pages/tools/index.js
index 1d47d6b50..1529228f8 100644
--- a/site/src/pages/tools/index.js
+++ b/site/src/pages/tools/index.js
@@ -26,10 +26,8 @@ function Tools() {
                 </p>
 
                 <ul>
-                    <li><code>getFile(name)</code></li>
-                &ndash; Retrieve contents of a Pure module file.
-                    <li><code>getFilePath(name)</code></li>
-                &ndash; Return full path to a Pure file.
+                    <li><code>getFile(name)</code> &ndash; Retrieve contents of a Pure module file.</li>
+                    <li><code>getFilePath(name)</code> &ndash; Return full path to a Pure file.</li>
                 </ul>
 
                 <SectionHeader heading="Installing Pure with Composer" />
diff --git a/site/src/theme/Layout.js b/site/src/theme/Layout.js
index 3bfc77928..c7d5528f9 100644
--- a/site/src/theme/Layout.js
+++ b/site/src/theme/Layout.js
@@ -86,10 +86,10 @@ function Layout(props) {
             </Head>
             <div id="layout">
                 <Menu />
-                <div id="main" className={(title || 'home').toLowerCase()}>
+                <main id="main" className={(title || 'home').toLowerCase()}>
                     {children}
                     <Footer siteConfig={siteConfig} />
-                </div>
+                </main>
             </div>
         </>
     );
diff --git a/site/static/css/main.css b/site/static/css/main.css
index 55aa57a85..4a6b92d50 100644
--- a/site/static/css/main.css
+++ b/site/static/css/main.css
@@ -26,7 +26,7 @@ html, button, input, select, textarea,
 body {
     min-width: 320px;
     background-color: #fff;
-    color: #777;
+    color: #666;
     line-height: 1.6;
 }
 
@@ -42,7 +42,7 @@ h4 {
 }
 
 a {
-    color: #3b8bba; /* block-background-text-normal */
+    color: #31739a; /* block-background-text-normal */
     text-decoration: none;
 }
 
@@ -50,6 +50,14 @@ a:visited {
     color: #265778; /* block-normal-text-normal */
 }
 
+/* Underline links in running text so they don't rely on color alone. */
+p a:not(.pure-button),
+li a:not(.pure-button):not(.pure-menu-link),
+td a:not(.pure-button),
+dd a {
+    text-decoration: underline;
+}
+
 dt {
     font-weight: bold;
 }
@@ -58,14 +66,14 @@ dd {
 }
 
 aside {
-    background: #1f8dd6; /* same color as selected state on site menu */
+    background: #1a75b3; /* same color as selected state on site menu */
     margin: 1em 0;
     padding: 0.3em 1em;
     border-radius: 3px;
     color: #fff;
 }
     aside a, aside a:visited {
-        color: rgb(169, 226, 255);
+        color: #fff;
     }
 
 
@@ -146,7 +154,7 @@ aside {
     .content .content-subhead {
         margin: 2em 0 1em 0;
         font-weight: 300;
-        color: #888;
+        color: #666;
         position: relative;
     }
 
@@ -261,6 +269,11 @@ code {
         padding: 0;
         margin-bottom: 0;
     }
+    /* Keep footer links at least 24px tall so they're easy to tap. */
+    .legal-links a {
+        display: inline-block;
+        min-height: 24px;
+    }
     .legal-copyright {
         margin-top: 0;
         margin-bottom: 0;
@@ -411,13 +424,13 @@ code {
     }
 
     #menu .pure-menu-item .active {
-        background: #1f8dd6;
+        background: #1a75b3;
         color: #fff;
     }
 
     #menu li.pure-menu-item .active:hover,
     #menu li.pure-menu-item .active:focus {
-        background: #1f8dd6;
+        background: #1a75b3;
     }
 
 
diff --git a/site/static/js/ui.js b/site/static/js/ui.js
index 628284ba6..0ba89e880 100644
--- a/site/static/js/ui.js
+++ b/site/static/js/ui.js
@@ -36,6 +36,8 @@
         toggleClass(elements.layout, active);
         toggleClass(elements.menu, active);
         toggleClass(elements.menuLink, active);
+        elements.menuLink.setAttribute('aria-expanded',
+            String(elements.menu.className.indexOf(active) !== -1));
     }
     
     function handleEvent(e) {