From a50ea9f0aec33359b2e816f0108ccbc3127e9aa0 Mon Sep 17 00:00:00 2001
From: Keith Solomon <ksolomon@gmail.com>
Date: Sun, 16 Aug 2026 14:08:22 -0500
Subject: [PATCH] fix(a11y): address axe color-contrast violations on dark
 surface

---
 styles/base/colors.css             |  6 ++++--
 styles/base/typography.css         |  8 ++++++++
 styles/blocks/buttons.css          | 13 +++++++++++++
 styles/blocks/core.css             | 13 ++++++++++---
 styles/components/post-list.css    |  6 ++++++
 styles/components/project-card.css |  2 +-
 styles/components/sidebar.css      |  7 +++++++
 7 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/styles/base/colors.css b/styles/base/colors.css
index abbfb7c..5b08035 100644
--- a/styles/base/colors.css
+++ b/styles/base/colors.css
@@ -29,8 +29,10 @@
   --color-secondary-800: color-mix(in oklch, var(--color-secondary) 80%, white);
   --color-secondary-900: color-mix(in oklch, var(--color-secondary) 90%, white);
 
-  --color-bodylinks: oklch(0.48 0.0789 211.58);
-  --color-footlinks: oklch(0.65 0.1104 212.2);
+  /* WCAG AA on --color-page-base (#100e0b): ~7:1 contrast, also visually
+   * distinct from surrounding --color-on-surface (#e3e1e9) for inline links. */
+  --color-bodylinks: oklch(0.68 0.16 250);
+  --color-footlinks: oklch(0.68 0.16 250);
 
   --color-light:     oklch(98.16% 0.0017 247.8);
   --color-dark:      oklch(34.51% 0.0133 248.2);
diff --git a/styles/base/typography.css b/styles/base/typography.css
index 8610aef..4dc603c 100644
--- a/styles/base/typography.css
+++ b/styles/base/typography.css
@@ -120,6 +120,14 @@ a, .link {
     &:hover { color: var(--color-primary); }
 }
 
+/* Inline links inside flowing text need an underline so they remain
+ * distinguishable from surrounding text without relying solely on color
+ * (WCAG 2.4.4 / axe link-in-text-block). */
+p a, li a, dd a, td a, blockquote a {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+}
+
 h1 a, .h1 a,
 h2 a, .h2 a,
 h3 a, .h3 a {
diff --git a/styles/blocks/buttons.css b/styles/blocks/buttons.css
index c48e360..5000e20 100644
--- a/styles/blocks/buttons.css
+++ b/styles/blocks/buttons.css
@@ -214,3 +214,16 @@ x-button:has(.button[data-button-width="full"]) { @apply w-full; }
 	color: var(--color-on-surface, #e3e1e9);
 	border-color: var(--color-outline-variant, #444651);
 }
+
+/* Outline button over the site-header's bg-secondary surface needs lighter text
+ * because --color-on-surface (#e3e1e9) on bg-secondary (#6e757f) is only 3.59:1.
+ * Pure white clears 4.5:1 against #6e757f; --color-on-primary (#05297a) is too
+ * dark and drops to 2.81:1, so we go to --color-white instead. */
+.site-header .button--outline {
+	color: var(--color-white, #ffffff);
+	border-color: var(--color-white, #ffffff);
+}
+.site-header .button--outline:hover {
+	color: var(--color-primary-87, #dce1ff);
+	border-color: var(--color-primary-87, #dce1ff);
+}
diff --git a/styles/blocks/core.css b/styles/blocks/core.css
index af75e9d..2050f8e 100644
--- a/styles/blocks/core.css
+++ b/styles/blocks/core.css
@@ -1,5 +1,12 @@
 .alignfull {
-  margin-left: calc(50% - 50vw);
-  margin-right: calc(50% - 50vw);
-  width: 100vw;
+	margin-left: calc(50% - 50vw);
+	margin-right: calc(50% - 50vw);
+	width: 100vw;
+}
+
+/* WP block buttons authored with vivid-cyan-blue backgrounds carry inline
+ * white text — that combo is only 3.33:1 and fails WCAG AA. Force dark text.
+ * !important needed because WP core ships .has-white-color with !important. */
+.wp-block-button__link.has-vivid-cyan-blue-background-color {
+	color: var(--color-page-base, #100e0b) !important;
 }
diff --git a/styles/components/post-list.css b/styles/components/post-list.css
index e32e448..c1fe04b 100644
--- a/styles/components/post-list.css
+++ b/styles/components/post-list.css
@@ -1,5 +1,11 @@
 /* Blog/post index listing styles */
 
+/* Category pill on dark page surface — needs higher contrast than the default
+ * --color-bodylinks (~3:1 against --color-page-base) for WCAG AA. */
+.post-list__category {
+	color: var(--color-primary-87, #dce1ff);
+}
+
 .post-list {
   /* Original styles, if needed
    * .post-list__posts {
diff --git a/styles/components/project-card.css b/styles/components/project-card.css
index 810d682..a489b56 100644
--- a/styles/components/project-card.css
+++ b/styles/components/project-card.css
@@ -333,7 +333,7 @@
 	margin: 0;
 }
 .home-recent__view-all {
-	color: var(--color-primary, #b6c4ff);
+	color: var(--color-primary-87, #dce1ff);
 	font-weight: 600;
 	text-decoration: none;
 }
diff --git a/styles/components/sidebar.css b/styles/components/sidebar.css
index 4c9dd72..e43b0c0 100644
--- a/styles/components/sidebar.css
+++ b/styles/components/sidebar.css
@@ -24,5 +24,12 @@
         }
       }
     }
+
+    /* Links inside sidebar widgets on dark page surface — bumped to --color-primary-87
+     * to clear WCAG AA (the inherited global --color-bodylinks is only ~3:1). */
+    a[data-type],
+    a[data-id] {
+      color: var(--color-primary-87, #dce1ff);
+    }
   }
 }