diff --git a/packages/git-ui/UX-COLOR.md b/packages/git-ui/UX-COLOR.md
new file mode 100644
index 0000000..5084261
--- /dev/null
+++ b/packages/git-ui/UX-COLOR.md
@@ -0,0 +1,41 @@
+# Colour, so every theme reads the same
+
+A theme is a set of tokens. A component that reaches for a raw colour, or for
+the accent to mean "important", reads well in the theme it was built against
+and muddy in the next. Two rules keep every theme consistent by construction.
+
+## Surfaces are an elevation ladder
+
+Four neutral surfaces, ordered. In dark themes each step is lighter than the
+one below, because a shadow does not read on dark and lightness carries depth.
+Use a surface by its rung, never by eye, and never with an alpha (`bg-muted/40`
+composites against whatever is behind it and shifts per theme).
+
+| rung | token | for |
+| --- | --- | --- |
+| base | `bg-background` | the page |
+| raised | `bg-card` | a card or panel that floats above the page |
+| band | `bg-muted` | a header, a gutter, a chip, a recessed strip |
+| interaction | `bg-accent` | a hover or a selected row, never a static fill |
+
+`accent` is a surface here, the brightest neutral, distinct from the semantic
+accent below. A selected row is `bg-accent`; a link is not.
+
+## Semantic colours mean one thing
+
+Reserved for their meaning, never for generic emphasis.
+
+| token | means | example |
+| --- | --- | --- |
+| `key` | a link, a selected or focused thing, neutral information | a branch link, the active tab, a comment verdict |
+| `success` | a positive state | an approval, a passing check |
+| `destructive` | a blocking or destructive state | a requested change, a failing check, a delete |
+| `foreground` / `muted-foreground` / `faint` | ordinary text, in three weights | a label, a caption, a timestamp |
+
+A verdict wears its meaning wherever it is shown: approve is `success`, a
+requested change is `destructive`, a plain comment is `key`. The review buttons,
+the timeline mark and the diff thread all read from one map (`verdictLook`), so
+the three hues never drift apart.
+
+A label is not a link. A branch name in a header is `text-foreground` on a
+`bg-muted` chip, not `text-key`; the accent is what a reader clicks.
diff --git a/packages/git-ui/src/components/molecules/check-disclosure.jsx b/packages/git-ui/src/components/molecules/check-disclosure.jsx
index ef44ea1..23c2210 100644
--- a/packages/git-ui/src/components/molecules/check-disclosure.jsx
+++ b/packages/git-ui/src/components/molecules/check-disclosure.jsx
@@ -38,7 +38,7 @@ export function CheckDisclosure({ runner, check, runHref }) {
         )}
       </div>
       {open && (
-        <div className="border-border border-t bg-muted/40">
+        <div className="border-border border-t bg-muted">
           {steps.length > 0 && <CheckSteps steps={steps} />}
           {/* A log opened beside its neighbours is capped, so one long run
               does not push the rest of them off the page. */}
diff --git a/packages/git-ui/src/components/molecules/diff-file.jsx b/packages/git-ui/src/components/molecules/diff-file.jsx
index d913bc0..cf09204 100644
--- a/packages/git-ui/src/components/molecules/diff-file.jsx
+++ b/packages/git-ui/src/components/molecules/diff-file.jsx
@@ -352,7 +352,7 @@ export function DiffFile({ file, ref, comments, spans, onComment }) {
                       {here.length > 0 && (
                         <div
                           id={`comment-${file.path}-${key}`}
-                          className="flex flex-col gap-2 border-border border-y bg-muted/40 px-3 py-2.5 whitespace-normal"
+                          className="flex flex-col gap-2 border-border border-y bg-muted px-3 py-2.5 whitespace-normal"
                         >
                           {here.map((comment) => {
                             const said = verdictLook(comment.verdict);
@@ -403,7 +403,7 @@ export function DiffFile({ file, ref, comments, spans, onComment }) {
                       )}
 
                       {composing?.key === key && (
-                        <div className="border-border border-y bg-muted/40 px-3 py-2.5 whitespace-normal">
+                        <div className="border-border border-y bg-muted px-3 py-2.5 whitespace-normal">
                           <textarea
                             value={note}
                             onChange={(event) => setNote(event.target.value)}
diff --git a/packages/git-ui/src/components/molecules/package-card.jsx b/packages/git-ui/src/components/molecules/package-card.jsx
index 9a49143..857e413 100644
--- a/packages/git-ui/src/components/molecules/package-card.jsx
+++ b/packages/git-ui/src/components/molecules/package-card.jsx
@@ -66,7 +66,7 @@ export function PackageCard({ pkg }) {
             {count} {count === 1 ? noun : `${noun}s`}
           </button>
           {open && (
-            <div className="max-h-72 overflow-y-auto border-border border-t bg-muted/40 py-1">
+            <div className="max-h-72 overflow-y-auto border-border border-t bg-muted py-1">
               {pkg.releases.map((release) => (
                 <ReleaseRow key={release.name} release={release} />
               ))}
diff --git a/packages/git-ui/src/components/molecules/pull-header.jsx b/packages/git-ui/src/components/molecules/pull-header.jsx
index 24e0d66..0699d04 100644
--- a/packages/git-ui/src/components/molecules/pull-header.jsx
+++ b/packages/git-ui/src/components/molecules/pull-header.jsx
@@ -92,11 +92,11 @@ export function PullHeader({ pull, defaultBranch }) {
           </span>{' '}
           into
         </span>
-        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[12px] text-key">
+        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[12px] text-foreground">
           {defaultBranch}
         </code>
         <span>from</span>
-        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[12px] text-key">
+        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[12px] text-foreground">
           {pull.branch}
         </code>
         {/* What the sentence above cannot say, because each is a fact about
diff --git a/packages/git-ui/src/components/molecules/review-composer.jsx b/packages/git-ui/src/components/molecules/review-composer.jsx
index 37706f5..61fc7c1 100644
--- a/packages/git-ui/src/components/molecules/review-composer.jsx
+++ b/packages/git-ui/src/components/molecules/review-composer.jsx
@@ -7,11 +7,31 @@ import { MarkdownField } from '#/components/molecules/markdown-field.jsx';
 import { publishReview } from '#/lib/publish.js';
 import { useSession } from '#/lib/session.jsx';
 
-/** The three verdicts a review record carries, in the order offered. */
+/**
+ * The three verdicts a review record carries, in the order offered, each
+ * with the colour it means: a positive one reads success, a blocking one
+ * reads danger, and a plain one reads in the accent a neutral mark takes.
+ * The same three hues the verdict wears everywhere else it is shown.
+ */
 const VERDICTS = [
-  { verdict: 'approve', label: 'Approve', Icon: CheckIcon },
-  { verdict: 'changesRequested', label: 'Request changes', Icon: XIcon },
-  { verdict: 'comment', label: 'Comment', Icon: MessageSquareIcon },
+  {
+    verdict: 'approve',
+    label: 'Approve',
+    Icon: CheckIcon,
+    active: 'border-success/40 bg-success/10 text-success',
+  },
+  {
+    verdict: 'changesRequested',
+    label: 'Request changes',
+    Icon: XIcon,
+    active: 'border-destructive/40 bg-destructive/10 text-destructive',
+  },
+  {
+    verdict: 'comment',
+    label: 'Comment',
+    Icon: MessageSquareIcon,
+    active: 'border-key/40 bg-key/10 text-key',
+  },
 ];
 
 /**
@@ -83,7 +103,7 @@ export function ReviewComposer({ repo, sha, author, refName }) {
               key={option.verdict}
               className={`flex cursor-pointer items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-[12.5px] ${
                 verdict === option.verdict
-                  ? 'border-key/40 bg-key/10 text-key'
+                  ? option.active
                   : 'border-input text-muted-foreground hover:text-foreground'
               }`}
             >