diff --git a/docs/README.md b/docs/README.md
index 358a516..68ee436 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -50,6 +50,13 @@ The Mintlify GitHub App posts its own `Mintlify Deployment` check, but that one
 reports `skipped` on pull requests: it runs on the deploy branch only. It is not
 a pre-merge guarantee, which is what the two commands above are for.
 
+`mint a11y` is deliberately not gated. In `docs.json` the accent keys name the
+colour, not the mode — `light` is the accent used *in dark mode* and `dark` the
+one used in light mode — so do not "fix" them by matching key to mode; that is
+how they came to be swapped. The two real pairings pass AA (7.82:1 and 6.34:1),
+but the command also measures `dark` against the dark background, a pairing that
+never renders, so it cannot reach exit 0 whatever the assignment.
+
 Every normative claim in `spec/` should be true of the reference
 implementation, or say plainly where it is not — see the *Status of This
 Document* section in [`spec/overview.mdx`](spec/overview.mdx). A specification
diff --git a/docs/docs.json b/docs/docs.json
index ab8d33a..a6dc4cf 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -4,8 +4,8 @@
   "theme": "aspen",
   "colors": {
     "primary": "#8B4513",
-    "light": "#8B4513",
-    "dark": "#D4A574"
+    "light": "#D4A574",
+    "dark": "#8B4513"
   },
   "navbar": {
     "links": [