Reconcile-the-brand-guide-and-the-editorial-palette

The brand guide added in #22 declared the navy and #F2F4F7 palette canonical
and said those tokens were the ones in use. That had not been true since the
editorial design system landed, and the theme alignment that followed spread
the parchment surfaces to the remaining pages, so the repository was carrying
two contradictory sources of truth.

Split the palette by the question each colour answers. Surfaces are the
editorial parchment and ink tokens, which is what actually ships on every
property including the four MkDocs subdomains. Marks and accents are the brand
guide's values, unchanged, so no icon needs regenerating.

That leaves one correction in each direction. The editorial system had invented
its own red and amber, and the hub bridge had retuned four semantic accents the
guide names explicitly; all six now use the documented hexes. In particular
--at-red becomes #B91C1C, the same red as the mark, so the site and the icons
no longer ship two reds close enough to read as a mistake.

Document the two legitimate exceptions, dark-scheme and code-surface
derivations and third-party logo colours, so the rule that an undocumented hex
does not belong stays enforceable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: imran-siddique

brand/BRAND.md

@@ -14,29 +14,79 @@ which is the handle rather than the wordmark. Prose uses AgenTrust.
 
 ## Palette
 
-These are the only approved brand colours. They are the tokens already defined
-in `index.html` and used across the site, the demos, and the extension pages.
+There are two layers, and they answer different questions. **Surface colours**
+say what the page is made of. **Mark and accent colours** say what carries the
+AgenTrust name. A mark never uses a surface colour and a surface never uses a
+mark colour, so the two lists cannot drift into each other again.
+
+The single source of truth is `design-system.css`, which every property loads
+from `agentrust-io.com`, including the four MkDocs subdomains. Change a value
+there and the whole family moves together. Do not redeclare these in a page.
+
+### Surfaces
+
+The site reads as printed matter: warm parchment, near-black ink, hairline
+rules. This is what ships on the hub, quickstart, demos, telemetry, the
+extension pages, and the docs sites.
 
 | Token | Hex | Use |
 |---|---|---|
-| `--navy` | `#15294B` | Primary. Mark background, headings, shield stroke. |
-| `--blue` | `#1B5EA0` | Gradient partner to navy, secondary accents. |
-| `--red` | `#B91C1C` | Accent only. The bar in the mark, and the single point of emphasis in a product glyph. |
-| `--body` | `#2E4057` | Body copy. |
-| `--muted` | `#6B7F94` | Secondary copy, captions. |
-| `--border` | `#D0D9E3` | Rules, card borders. |
-| `--bg` | `#F2F4F7` | Page background, light-variant mark background. |
-| `--surface` | `#FFFFFF` | Cards, light-variant mark highlight. |
-
-Semantic colours (`--green #1B7A4A`, `--amber #C17817`, `--orange #EA580C`,
-`--purple #6D28D9`) are for status and diagram meaning only. They are never
-brand colours and never appear in a mark.
+| `--at-paper` | `#F3F0E8` | Page background. |
+| `--at-paper-2` | `#E9E4D8` | Table headers, hover fills, secondary bands. |
+| `--at-white` | `#FFFEFA` | Cards, callouts, raised surfaces. |
+| `--at-ink` | `#171714` | Body copy, headings, footer background, code background. |
+| `--at-muted` | `#66645D` | Secondary copy, captions, inactive nav. |
+| `--at-line` | `rgba(23,23,20,.18)` | Rules, card borders, dividers. |
+
+The dark variant is defined once, under `[data-md-color-scheme="slate"]`, and
+inverts these same six tokens. Nothing else needs a dark rule.
+
+### Marks and accents
+
+| Token | Hex | Use |
+|---|---|---|
+| `--at-navy` | `#15294B` | Mark background, shield stroke, structural emphasis. |
+| `--blue` | `#1B5EA0` | Gradient partner to navy, links, secondary accents. |
+| `--at-red` | `#B91C1C` | Accent only. The bar in the mark, the single point of emphasis in a product glyph, section labels, active nav. |
+
+`--at-red` and the red in the mark files are the same hex on purpose. One red
+across the icons and the site, never two that are close enough to look like a
+mistake.
+
+### Semantic
+
+`--green #1B7A4A`, `--amber #C17817`, `--orange #EA580C`, `--purple #6D28D9`.
+Status and diagram meaning only: badges, product-card category accents, pass
+and fail states. They are never brand colours and never appear in a mark.
 
 **Do not use the MkDocs Material default purple.** The theme ships
 `#7c3aed`, `#0ea5e9`, `#5BD2BE`, `#8251EE`, and `#C661F7`. Four product icons
 were previously drawn in those colours, which is how the family drifted into
 two unrelated palettes that matched neither each other nor the site. If a hex
-is not in the table above, it does not belong in a mark.
+is not on this page, it does not belong in a mark.
+
+### Two exceptions
+
+`design-system.css` contains hexes that are not on this page, and both kinds
+are deliberate.
+
+**Derived tones.** The dark scheme and the code surfaces are derived from the
+six surface tokens: inverted paper and ink, plus the muted greens, sands, and
+reds that stay legible on a near-black code block. They are shades of the
+palette, not additions to it, and they live in one file. Do not hand-pick a new
+one in a page.
+
+**Third-party logos.** An adopter or partner card renders that organisation's
+own mark in that organisation's own colour. Those are their brand values, not
+ours, and they appear nowhere else. Never sample one into AgenTrust surfaces.
+
+### The older token names
+
+The hub still carries an inline stylesheet written against an earlier set of
+names: `--bg`, `--surface`, `--border`, `--body`, `--muted`, `--navy`, `--red`.
+`design-system.css` remaps those onto the tokens above in one block rather than
+rewriting five hundred lines of page CSS, so they resolve to the values here.
+Treat them as legacy aliases. New work uses the `--at-*` names.
 
 ## The mark system
 

design-system.css

@@ -10,7 +10,7 @@
   --at-muted: #66645d;
   --at-line: rgba(23, 23, 20, 0.18);
   --at-navy: #15294b;
-  --at-red: #c52233;
+  --at-red: #b91c1c;
   --at-white: #fffefa;
   --at-radius: 18px;
   --at-shadow: 0 18px 45px rgba(23, 23, 20, 0.08);
@@ -24,7 +24,7 @@
   --md-primary-fg-color: var(--at-paper);
   --md-primary-bg-color: var(--at-ink);
   --md-accent-fg-color: var(--at-red);
-  --md-typeset-a-color: #244f83;
+  --md-typeset-a-color: #1b5ea0;
   --md-default-bg-color: var(--at-paper);
   --md-default-fg-color: var(--at-ink);
   --md-default-fg-color--light: var(--at-muted);
@@ -222,9 +222,9 @@ body,
  * The hub still ships the older inline palette. Rather than rewrite 500 lines
  * of page CSS, remap those variables onto the editorial tokens once, here.
  * Every remaining var(--navy)/var(--blue)/... on the page resolves through it,
- * so the hub has one palette, not two. The five accents stay distinguishable
- * because the product cards use them to tell categories apart; they are just
- * retuned to print-ink values that sit on parchment.
+ * so the hub has one palette, not two. The semantic accents keep the exact
+ * hexes brand/BRAND.md documents: the product cards use them to tell
+ * categories apart, and they are status colours, not surface colours.
  */
 .agentrust-hub {
   --bg: var(--at-paper);
@@ -234,11 +234,11 @@ body,
   --muted: var(--at-muted);
   --navy: var(--at-navy);
   --red: var(--at-red);
-  --blue: #244f83;
-  --green: #1e6b4a;
-  --amber: var(--at-warn);
-  --purple: #5b3f7a;
-  --orange: #b05c1f;
+  --blue: #1b5ea0;
+  --green: #1b7a4a;
+  --amber: #c17817;
+  --purple: #6d28d9;
+  --orange: #ea580c;
 }
 
 /* Status badges: one parchment chip, the accent carried by the text alone */
@@ -316,7 +316,7 @@ body,
 }
 
 .agentrust-hub .hero-promo-text { color: var(--at-ink); }
-.agentrust-hub .hero-promo-tag { color: var(--at-red); background: rgba(197, 34, 51, 0.08); }
+.agentrust-hub .hero-promo-tag { color: var(--at-red); background: rgba(185, 28, 28, 0.08); }
 .agentrust-hub .hero-promo-link { border-radius: 999px; background: var(--at-ink); color: var(--at-paper); }
 
 .agentrust-hub .btn { border-radius: 999px; padding: 0.75rem 1.2rem; }
@@ -443,7 +443,7 @@ body,
 
 :root {
   --at-pass: #1b7a4a;
-  --at-warn: #a9691b;
+  --at-warn: #c17817;
   --at-code-bg: #171714;
   --at-code-fg: #e4e0d6;
   --at-code-dim: #9d998e;

supernav.js

@@ -77,7 +77,7 @@
     '#' + NAV_ID + ' a.active{',
     '  color:var(--at-ink,#171714);',
     '  font-weight:750;',
-    '  border-bottom-color:var(--at-red,#c52233);',
+    '  border-bottom-color:var(--at-red,#b91c1c);',
     '}',
     '#' + NAV_ID + ' .sep{',
     '  width:1px;',