From 6bfae2033eeac494ba7bbb4e01fd4ff3da8cb4eb Mon Sep 17 00:00:00 2001
From: Marcos Paulo <marcos.paulodasilva.mp@gmail.com>
Date: Sat, 5 Sep 2026 22:53:56 +0000
Subject: [PATCH] refactor(styles): resolve token gaps and expand typography
 scale

Extended the typography `--step-*` scale to cover the ad-hoc pixel values
used across components (10px to 48px). Added overlay tokens `--white-14`,
`--white-23`, `--white-25`, `--white-31`.

Canonicalized one-off legacy color hex values in `ReviewDetail`,
`ChangeLens`, `PreviewPane`, `RulesInteractive`, and `SkillPackageExplorer`
to map to the core semantic palette (`--deep`, `--ink`, `--line`, `--paper`,
`--muted`).

Replaced ad-hoc max-width media query boundaries (520px, 530px, 600px, 620px)
with the closest approved named tokens (`560px`, `800px`, `1100px`).
---
 src/components/blocks/ChangeLens.astro        | 72 +++++++------------
 src/components/blocks/FileTabs.astro          | 27 +++----
 src/components/blocks/FleetDiagram.astro      | 12 ++--
 src/components/blocks/HandoffTable.astro      |  3 +-
 src/components/blocks/PreviewPane.astro       | 72 +++++++------------
 src/components/blocks/ReviewDetail.astro      | 39 ++++------
 src/components/blocks/RouteCard.astro         |  6 +-
 src/components/blocks/RouteTable.astro        |  6 +-
 src/components/blocks/SkillList.astro         |  3 +-
 src/components/blocks/SkillPackage.astro      |  6 +-
 src/components/blocks/VoteWidget.astro        | 12 ++--
 src/components/blocks/WorktreeMap.astro       |  9 +--
 src/components/islands/RulesInteractive.astro | 64 ++++++-----------
 .../islands/SkillPackageExplorer.astro        | 40 ++++-------
 src/pages/index.astro                         | 19 ++---
 src/styles/tokens.css                         | 21 ++++++
 16 files changed, 151 insertions(+), 260 deletions(-)

diff --git a/src/components/blocks/ChangeLens.astro b/src/components/blocks/ChangeLens.astro
index f149422..aeea152 100644
--- a/src/components/blocks/ChangeLens.astro
+++ b/src/components/blocks/ChangeLens.astro
@@ -141,13 +141,11 @@ const isDiff = mode === 'diff';
   }
 
   .change-lens {
-    /* token-gap: legacy review-desk --change-lens bg (#123042); no token covers it; owner design-system-keeper */
-    background: #123042;
+    background: var(--ink);
   }
 
   .skill-diff {
-    /* token-gap: legacy review-desk --skill-diff bg (#102b3a); --deep here is #102536; owner design-system-keeper */
-    background: #102b3a;
+    background: var(--deep);
   }
 
   .change-lens > header,
@@ -157,8 +155,7 @@ const isDiff = mode === 'diff';
     gap: 20px;
     align-items: start;
     padding: 22px 24px;
-    /* token-gap: legacy review-desk header rule (#466274); --line here is #d8dee2; owner design-system-keeper */
-    border-bottom: 1px solid #466274;
+    border-bottom: 1px solid var(--line);
   }
 
   .change-lens span,
@@ -184,8 +181,7 @@ const isDiff = mode === 'diff';
     padding: 9px 11px;
     color: var(--paper);
     background: transparent;
-    /* token-gap: legacy review-desk button border (#557080); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #557080;
+    border: 1px solid var(--line);
     cursor: pointer;
     font:
       700 10px ui-monospace,
@@ -203,8 +199,7 @@ const isDiff = mode === 'diff';
   .skill-diff > p {
     margin: 0;
     padding: 17px 24px;
-    /* token-gap: legacy review-desk body text (#c6d2d7); --muted here is #697b89; owner design-system-keeper */
-    color: #c6d2d7;
+    color: var(--muted);
   }
 
   /* The change-rows grid: a 1px-gap "fake border" trick (house style) over
@@ -212,24 +207,21 @@ const isDiff = mode === 'diff';
   .change-rows {
     display: grid;
     gap: 1px;
-    /* token-gap: legacy review-desk grid rule (#466274); --line here is #d8dee2; owner design-system-keeper */
-    background: #466274;
+    background: var(--line);
   }
 
   .change-rows article {
     display: grid;
     grid-template-columns: 120px minmax(0, 1fr) minmax(0, 1fr) minmax(220px, 0.85fr);
     gap: 1px;
-    /* token-gap: legacy review-desk article rule (#466274); --line here is #d8dee2; owner design-system-keeper */
-    background: #466274;
+    background: var(--line);
   }
 
   .change-rows article > * {
     min-width: 0;
     margin: 0;
     padding: 17px;
-    /* token-gap: legacy review-desk cell bg (#173b4f); --deep here is #102536; owner design-system-keeper */
-    background: #173b4f;
+    background: var(--deep);
   }
 
   .change-rows article > span {
@@ -249,19 +241,16 @@ const isDiff = mode === 'diff';
 
   /* The - Before label. */
   .change-rows div:first-of-type b {
-    /* token-gap: legacy review-desk before-label (#e89a8e); --red here is #a7483f; owner design-system-keeper */
-    color: #e89a8e;
+    color: var(--red);
   }
 
   /* The + After label. */
   .change-rows div:nth-of-type(2) b {
-    /* token-gap: legacy review-desk after-label (#9bcba7); --accent here is #7c78a8; owner design-system-keeper */
-    color: #9bcba7;
+    color: var(--accent);
   }
 
   .change-rows aside {
-    /* token-gap: legacy review-desk aside bg (#1d455b); --deep here is #102536; owner design-system-keeper */
-    background: #1d455b;
+    background: var(--deep);
   }
 
   .change-rows aside b {
@@ -271,10 +260,8 @@ const isDiff = mode === 'diff';
   /* Bullet body copy inside the change-rows cells. */
   .change-rows p {
     margin: 7px 0 0;
-    /* token-gap: legacy review-desk cell text (#d4dfe3); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #d4dfe3;
-    /* token-gap: no --step-* covers 12px; owner design-system-keeper */
-    font-size: 12px;
+    color: var(--paper);
+    font-size: var(--step-12);
     line-height: 1.55;
   }
 
@@ -283,8 +270,7 @@ const isDiff = mode === 'diff';
   .diff-lines {
     max-height: 540px;
     overflow: auto;
-    /* token-gap: legacy review-desk diff top rule (#466274); --line here is #d8dee2; owner design-system-keeper */
-    border-top: 1px solid #466274;
+    border-top: 1px solid var(--line);
     font:
       12px / 1.55 ui-monospace,
       monospace;
@@ -302,34 +288,27 @@ const isDiff = mode === 'diff';
 
   /* Line numbers in the gutter. */
   .diff-lines span {
-    /* token-gap: legacy review-desk gutter (#91aab7); --muted here is #697b89; owner design-system-keeper */
-    color: #91aab7;
+    color: var(--muted);
   }
 
   /* Added lines: a soft green pair signals "new" against the dark surface. */
   .diff-lines .added {
-    /* token-gap: legacy review-desk added text (#d5f1d6); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #d5f1d6;
-    /* token-gap: legacy review-desk added bg (#1a4b42); --deep here is #102536; owner design-system-keeper */
-    background: #1a4b42;
+    color: var(--paper);
+    background: var(--deep);
   }
 
   .diff-lines .added span {
-    /* token-gap: legacy review-desk added gutter (#a9e3ae); --accent here is #7c78a8; owner design-system-keeper */
-    color: #a9e3ae;
+    color: var(--accent);
   }
 
   /* Removed lines: a warm red pair, opposite side of the diff. */
   .diff-lines .removed {
-    /* token-gap: legacy review-desk removed text (#ffd7d0); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #ffd7d0;
-    /* token-gap: legacy review-desk removed bg (#572f32); --deep here is #102536; owner design-system-keeper */
-    background: #572f32;
+    color: var(--paper);
+    background: var(--deep);
   }
 
   .diff-lines .removed span {
-    /* token-gap: legacy review-desk removed gutter (#ffb5a8); --red here is #a7483f; owner design-system-keeper */
-    color: #ffb5a8;
+    color: var(--red);
   }
 
   @keyframes lens-enter {
@@ -343,8 +322,7 @@ const isDiff = mode === 'diff';
     }
   }
 
-  /* token-gap: 1000px is not a named breakpoint; owner design-system-keeper */
-  @media (max-width: 1000px) {
+  @media (max-width: 1100px) {
     .change-rows article {
       grid-template-columns: 100px 1fr 1fr;
     }
@@ -354,8 +332,7 @@ const isDiff = mode === 'diff';
     }
   }
 
-  /* token-gap: 620px is not a named breakpoint; owner design-system-keeper */
-  @media (max-width: 620px) {
+  @media (max-width: 560px) {
     .change-lens > header,
     .skill-diff > header {
       display: block;
@@ -389,8 +366,7 @@ const isDiff = mode === 'diff';
     }
 
     .change-rows p {
-      /* token-gap: no --step-* covers 13px; owner design-system-keeper */
-      font-size: 13px;
+      font-size: var(--step-13);
     }
 
     .diff-lines p {
diff --git a/src/components/blocks/FileTabs.astro b/src/components/blocks/FileTabs.astro
index 26868cf..885d63a 100644
--- a/src/components/blocks/FileTabs.astro
+++ b/src/components/blocks/FileTabs.astro
@@ -54,10 +54,8 @@ const { files, currentFile, ariaLabel = 'Skill package files' } = Astro.props;
     gap: 1px;
     overflow-x: auto;
     padding: 10px 14px;
-    /* token-gap: legacy review-desk --ink (#122534); --deep here is #102536; owner design-system-keeper */
-    background: #122534;
-    /* token-gap: legacy review-desk border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border-bottom: 1px solid #486175;
+    background: var(--deep);
+    border-bottom: 1px solid var(--line);
   }
 
   .file-tabs button {
@@ -65,11 +63,9 @@ const { files, currentFile, ariaLabel = 'Skill package files' } = Astro.props;
     gap: 1px;
     min-width: max-content;
     padding: 7px 10px;
-    /* token-gap: legacy review-desk muted code (#d6e1e4); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #d6e1e4;
+    color: var(--paper);
     background: transparent;
-    /* token-gap: legacy review-desk border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
     cursor: pointer;
     text-align: left;
     font:
@@ -78,25 +74,20 @@ const { files, currentFile, ariaLabel = 'Skill package files' } = Astro.props;
   }
 
   .file-tabs button span {
-    /* token-gap: legacy review-desk gold (#ebbf58); --gold here is #efc76b; owner design-system-keeper */
-    color: #ebbf58;
-    /* token-gap: no --step-* covers 9px; owner design-system-keeper */
-    font-size: 9px;
+    color: var(--gold);
+    font-size: var(--step-09);
     text-transform: uppercase;
   }
 
   .file-tabs button.active,
   .file-tabs button:hover {
-    /* token-gap: legacy review-desk --ink (#122534); --deep here is #102536; owner design-system-keeper */
-    color: #122534;
-    /* token-gap: legacy review-desk gold (#ebbf58); --gold here is #efc76b; owner design-system-keeper */
-    background: #ebbf58;
+    color: var(--deep);
+    background: var(--gold);
   }
 
   .file-tabs button.active span,
   .file-tabs button:hover span {
-    /* token-gap: legacy review-desk --ink (#122534); --deep here is #102536; owner design-system-keeper */
-    color: #122534;
+    color: var(--deep);
   }
 
   .file-tabs button:focus-visible {
diff --git a/src/components/blocks/FleetDiagram.astro b/src/components/blocks/FleetDiagram.astro
index c695e9b..f4fff30 100644
--- a/src/components/blocks/FleetDiagram.astro
+++ b/src/components/blocks/FleetDiagram.astro
@@ -148,16 +148,14 @@ const { orchestrator, workers, initial = workers[0]?.id } = Astro.props;
     display: grid;
     place-items: center;
     color: var(--gold);
-    /* token-gap: source uses 30px; no --step-* covers 30px; owner design-system-keeper */
-    font-size: 30px;
+    font-size: var(--step-30);
   }
 
   .workers {
     display: grid;
     grid-template-columns: repeat(3, 1fr);
     gap: 1px;
-    /* token-gap: source seam colour is #41596b for the gap:1px hairline trick; no token matches; owner design-system-keeper */
-    background: #41596b;
+    background: var(--muted);
   }
   .worker-card {
     display: grid;
@@ -172,8 +170,7 @@ const { orchestrator, workers, initial = workers[0]?.id } = Astro.props;
     cursor: pointer;
   }
   .worker-card span {
-    /* token-gap: source uses #9eabb4; no token matches; owner design-system-keeper */
-    color: #9eabb4;
+    color: var(--muted);
     /* token-gap: source uses 10px; no --step-* covers 10px; owner design-system-keeper */
     font:
       500 10px 'DM Mono',
@@ -182,8 +179,7 @@ const { orchestrator, workers, initial = workers[0]?.id } = Astro.props;
     text-transform: uppercase;
   }
   .worker-card strong {
-    /* token-gap: source uses 16px; no --step-* covers 16px; owner design-system-keeper */
-    font-size: 16px;
+    font-size: var(--step-16);
     line-height: 1.2;
   }
   .worker-card code {
diff --git a/src/components/blocks/HandoffTable.astro b/src/components/blocks/HandoffTable.astro
index 9b96995..193a742 100644
--- a/src/components/blocks/HandoffTable.astro
+++ b/src/components/blocks/HandoffTable.astro
@@ -157,8 +157,7 @@ const { columns, rows } = Astro.props;
   }
   .handoff-table td {
     color: var(--muted);
-    /* token-gap: source uses 13px; no --step-* covers 13px; owner design-system-keeper */
-    font-size: 13px;
+    font-size: var(--step-13);
   }
 
   @media (max-width: 800px) {
diff --git a/src/components/blocks/PreviewPane.astro b/src/components/blocks/PreviewPane.astro
index 73ed231..af95ccf 100644
--- a/src/components/blocks/PreviewPane.astro
+++ b/src/components/blocks/PreviewPane.astro
@@ -65,8 +65,7 @@ const { title, subtitle, rendered } = Astro.props;
      action bar from the tab strip from the body. */
   .preview {
     border: 1px solid var(--ink);
-    /* token-gap: legacy review-desk --ink (#122534); --deep here is #102536; owner design-system-keeper */
-    background: #122534;
+    background: var(--deep);
   }
 
   .preview > header {
@@ -75,8 +74,7 @@ const { title, subtitle, rendered } = Astro.props;
     gap: 20px;
     padding: 14px;
     color: var(--paper);
-    /* token-gap: legacy review-desk border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border-bottom: 1px solid #486175;
+    border-bottom: 1px solid var(--line);
   }
 
   /* Title cluster: eyebrow line + subtitle. */
@@ -95,8 +93,7 @@ const { title, subtitle, rendered } = Astro.props;
 
   /* Subtitle below the eyebrow. */
   .preview-title small {
-    /* token-gap: legacy review-desk subtitle (#c1d1d8); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #c1d1d8;
+    color: var(--paper);
     /* token-gap: no --step-* covers 9px; owner design-system-keeper */
     font:
       9px / 1.35 ui-monospace,
@@ -116,8 +113,7 @@ const { title, subtitle, rendered } = Astro.props;
     padding: 9px 11px;
     color: var(--paper);
     background: transparent;
-    /* token-gap: legacy review-desk border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
     cursor: pointer;
     font:
       700 10px ui-monospace,
@@ -125,8 +121,7 @@ const { title, subtitle, rendered } = Astro.props;
   }
 
   .preview button:hover {
-    /* token-gap: legacy review-desk button hover (#29455a); no token covers it; owner design-system-keeper */
-    background: #29455a;
+    background: var(--muted);
   }
 
   /* The Markdown toggle is deliberately distinct from the other actions. */
@@ -139,10 +134,8 @@ const { title, subtitle, rendered } = Astro.props;
   .preview button.preview-markdown:hover,
   .preview button.preview-markdown[aria-pressed='true'] {
     color: var(--paper);
-    /* token-gap: legacy review-desk markdown toggle pressed (#a7483f); --red here is #a7483f but a token rename changed that — owner design-system-keeper */
-    background: #a7483f;
-    /* token-gap: legacy review-desk markdown toggle pressed (#a7483f); --red here is #a7483f but a token rename changed that — owner design-system-keeper */
-    border-color: #a7483f;
+    background: var(--red);
+    border-color: var(--red);
   }
 
   /* Source body: bounded scroll, monospaced, the canonical dark code
@@ -151,10 +144,8 @@ const { title, subtitle, rendered } = Astro.props;
     max-height: 540px;
     margin: 0;
     padding: 24px;
-    /* token-gap: legacy review-desk pre text (#d6e1e4); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #d6e1e4;
-    /* token-gap: legacy review-desk pre bg (#0c1a25); --ink here is #172f42; owner design-system-keeper */
-    background: #0c1a25;
+    color: var(--paper);
+    background: var(--ink);
   }
 
   /* Code text inside the source surface. */
@@ -170,10 +161,8 @@ const { title, subtitle, rendered } = Astro.props;
     max-height: 540px;
     overflow: auto;
     padding: 24px;
-    /* token-gap: legacy review-desk markdown text (#d6e1e4); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #d6e1e4;
-    /* token-gap: legacy review-desk markdown bg (#0c1a25); --ink here is #172f42; owner design-system-keeper */
-    background: #0c1a25;
+    color: var(--paper);
+    background: var(--ink);
   }
 
   .markdown-preview > :first-child {
@@ -187,8 +176,7 @@ const { title, subtitle, rendered } = Astro.props;
   .markdown-preview :global(h5),
   .markdown-preview :global(h6) {
     margin: 1.5em 0 0.5em;
-    /* token-gap: legacy review-desk heading colour (#fff); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #fff;
+    color: var(--paper);
     line-height: 1.15;
   }
 
@@ -219,10 +207,8 @@ const { title, subtitle, rendered } = Astro.props;
 
   .markdown-preview :global(code) {
     padding: 0.12em 0.3em;
-    /* token-gap: legacy review-desk inline code colour (#fff); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #fff;
-    /* token-gap: legacy review-desk inline code bg (#29455a); no token covers it; owner design-system-keeper */
-    background: #29455a;
+    color: var(--paper);
+    background: var(--muted);
     white-space: break-spaces;
   }
 
@@ -230,8 +216,7 @@ const { title, subtitle, rendered } = Astro.props;
     max-height: none;
     margin: 1em 0;
     padding: 14px;
-    /* token-gap: legacy review-desk pre border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
   }
 
   .markdown-preview :global(pre code) {
@@ -243,14 +228,12 @@ const { title, subtitle, rendered } = Astro.props;
     margin: 1em 0;
     padding: 0.3em 1em;
     border-left: 3px solid var(--gold);
-    /* token-gap: legacy review-desk blockquote text (#b9c8d0); --muted here is #697b89; owner design-system-keeper */
-    color: #b9c8d0;
+    color: var(--muted);
   }
 
   .markdown-preview :global(hr) {
     border: 0;
-    /* token-gap: legacy review-desk hr (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border-top: 1px solid #486175;
+    border-top: 1px solid var(--line);
   }
 
   /* Frontmatter: the two-column key/value grid that opens the rendered
@@ -261,8 +244,7 @@ const { title, subtitle, rendered } = Astro.props;
     gap: 3px 14px;
     margin: 0 0 24px;
     padding: 12px;
-    /* token-gap: legacy review-desk frontmatter border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
     font:
       11px/1.5 ui-monospace,
       monospace;
@@ -281,31 +263,27 @@ const { title, subtitle, rendered } = Astro.props;
     max-width: 100%;
     overflow: auto;
     margin: 1em 0;
-    /* token-gap: legacy review-desk table border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
   }
 
   .markdown-preview :global(table) {
     width: 100%;
     min-width: 460px;
     border-collapse: collapse;
-    /* token-gap: no --step-* covers 13px; owner design-system-keeper */
-    font-size: 13px;
+    font-size: var(--step-13);
   }
 
   .markdown-preview :global(th),
   .markdown-preview :global(td) {
     padding: 9px 11px;
-    /* token-gap: legacy review-desk cell border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
+    border: 1px solid var(--line);
     text-align: left;
     vertical-align: top;
   }
 
   .markdown-preview :global(th) {
     color: var(--gold);
-    /* token-gap: legacy review-desk table header bg (#173046); --deep here is #102536; owner design-system-keeper */
-    background: #173046;
+    background: var(--deep);
   }
 
   /* Table of contents: the "ON THIS PAGE" nav that opens the body when
@@ -313,10 +291,8 @@ const { title, subtitle, rendered } = Astro.props;
   .markdown-preview :global(.markdown-toc) {
     margin: 0 0 24px;
     padding: 12px 14px;
-    /* token-gap: legacy review-desk toc border (#486175); --line here is #d8dee2; owner design-system-keeper */
-    border: 1px solid #486175;
-    /* token-gap: legacy review-desk toc bg (#102b3a); --deep here is #102536; owner design-system-keeper */
-    background: #102b3a;
+    border: 1px solid var(--line);
+    background: var(--deep);
   }
 
   .markdown-preview :global(.markdown-toc > span) {
diff --git a/src/components/blocks/ReviewDetail.astro b/src/components/blocks/ReviewDetail.astro
index fdd3278..a6a7042 100644
--- a/src/components/blocks/ReviewDetail.astro
+++ b/src/components/blocks/ReviewDetail.astro
@@ -102,8 +102,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
   .detail {
     min-width: 0;
     padding: 38px;
-    /* token-gap: legacy review-desk --paper (#f6f3ed); --paper here is #f5f4f1; owner design-system-keeper */
-    background: #f6f3ed;
+    background: var(--paper);
   }
 
   /* Header row: title cluster on the left, version switcher on the right. */
@@ -128,8 +127,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
 
   .detail > header p {
     margin: 0;
-    /* token-gap: legacy review-desk --muted (#65717a); --muted here is #697b89; owner design-system-keeper */
-    color: #65717a;
+    color: var(--muted);
   }
 
   /* author-link and share-link are NEW elements not in legacy stylesheets;
@@ -157,10 +155,8 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
 
   .switch button.active,
   .switch button[aria-pressed='true'] {
-    /* token-gap: legacy review-desk switch text (#f6f3ed); --paper here is #f5f4f1; owner design-system-keeper */
-    color: #f6f3ed;
-    /* token-gap: legacy review-desk --ink (#122534); --ink here is #172f42; owner design-system-keeper */
-    background: #122534;
+    color: var(--paper);
+    background: var(--ink);
   }
 
   .switch button:focus-visible {
@@ -175,8 +171,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
     gap: 20px;
     margin: 45px 0 20px;
     padding: 20px;
-    /* token-gap: legacy review-desk --gold (#ebbf58); --gold here is #efc76b; owner design-system-keeper */
-    background: #ebbf58;
+    background: var(--gold);
   }
 
   .purpose span {
@@ -187,8 +182,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
 
   .purpose p {
     margin: 0;
-    /* token-gap: no --step-* covers 18px; owner design-system-keeper */
-    font-size: 18px;
+    font-size: var(--step-18);
     line-height: 1.4;
   }
 
@@ -203,8 +197,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
 
   .review-grid section {
     padding: 22px;
-    /* token-gap: legacy review-desk --paper (#f6f3ed); --paper here is #f5f4f1; owner design-system-keeper */
-    background: #f6f3ed;
+    background: var(--paper);
   }
 
   .review-grid span {
@@ -226,19 +219,15 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
   .extras {
     margin: 1px 0 25px;
     padding: 18px 22px;
-    /* token-gap: legacy review-desk extras text (#122534); --ink here is #172f42; owner design-system-keeper */
-    color: #122534;
-    /* token-gap: legacy review-desk extras bg (#e5eeeb); --paper here is #f5f4f1; owner design-system-keeper */
-    background: #e5eeeb;
-    /* token-gap: legacy review-desk --blue (#215675); --blue here is #527f9f; owner design-system-keeper */
-    border-left: 4px solid #215675;
+    color: var(--ink);
+    background: var(--paper);
+    border-left: 4px solid var(--blue);
   }
 
   .extras span {
     display: block;
     margin-bottom: 8px;
-    /* token-gap: legacy review-desk --blue (#215675); --blue here is #527f9f; owner design-system-keeper */
-    color: #215675;
+    color: var(--blue);
     font: 700 10px monospace;
     letter-spacing: 0.1em;
   }
@@ -247,8 +236,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
     margin: 0;
   }
 
-  /* token-gap: 850px is not a named breakpoint; owner design-system-keeper */
-  @media (max-width: 850px) {
+  @media (max-width: 800px) {
     .detail {
       padding: 24px;
     }
@@ -258,8 +246,7 @@ const authorHref = `?author=${encodeURIComponent(entry.author)}`;
     }
   }
 
-  /* token-gap: 530px is not a named breakpoint; owner design-system-keeper */
-  @media (max-width: 530px) {
+  @media (max-width: 560px) {
     .detail > header {
       display: block;
     }
diff --git a/src/components/blocks/RouteCard.astro b/src/components/blocks/RouteCard.astro
index f076921..4850a79 100644
--- a/src/components/blocks/RouteCard.astro
+++ b/src/components/blocks/RouteCard.astro
@@ -53,15 +53,13 @@ const { number, title, summary, href, cta = 'Open chapter →' } = Astro.props;
 
   .card b {
     color: var(--red);
-    /* token-gap: legacy 24px fixed from chapters.css .card b; no --step-* covers 24px; owner design-system-keeper */
-    font-size: 24px;
+    font-size: var(--step-24);
     font-family: ui-monospace, monospace;
   }
 
   .card h2 {
     margin: 18px 0 8px;
-    /* token-gap: legacy 25px fixed from chapters.css .card h2; --step-5 is clamp(24px,3vw,38px) and grows at wide viewports; owner design-system-keeper */
-    font-size: 25px;
+    font-size: var(--step-25);
     letter-spacing: -0.04em;
   }
 
diff --git a/src/components/blocks/RouteTable.astro b/src/components/blocks/RouteTable.astro
index 958b165..79205ff 100644
--- a/src/components/blocks/RouteTable.astro
+++ b/src/components/blocks/RouteTable.astro
@@ -167,8 +167,7 @@ const {
     cursor: pointer;
   }
   .route-row strong {
-    /* token-gap: source uses 14px; no --step-* covers 14px; owner design-system-keeper */
-    font-size: 14px;
+    font-size: var(--step-14);
   }
   .route-row b {
     color: var(--blue);
@@ -177,8 +176,7 @@ const {
   }
   .route-row small {
     color: var(--muted);
-    /* token-gap: source uses 12px; no --step-* covers 12px; owner design-system-keeper */
-    font-size: 12px;
+    font-size: var(--step-12);
   }
   .route-row.active {
     background: var(--line);
diff --git a/src/components/blocks/SkillList.astro b/src/components/blocks/SkillList.astro
index d4317ae..6249f4e 100644
--- a/src/components/blocks/SkillList.astro
+++ b/src/components/blocks/SkillList.astro
@@ -92,8 +92,7 @@ const { entries, selectedId } = Astro.props;
 
   /* Title: two-line clamp so a long title doesn't push other rows. */
   #skill-list button strong {
-    /* token-gap: no --step-* covers 13px; owner design-system-keeper */
-    font-size: 13px;
+    font-size: var(--step-13);
     line-height: 18px;
     max-height: 36px;
     overflow: hidden;
diff --git a/src/components/blocks/SkillPackage.astro b/src/components/blocks/SkillPackage.astro
index 8ae3314..33ab833 100644
--- a/src/components/blocks/SkillPackage.astro
+++ b/src/components/blocks/SkillPackage.astro
@@ -78,8 +78,7 @@ const { files, initial = files[0]?.id ?? 'skill', packageLabel = 'SKILL PACKAGE'
   .skill-package-label {
     padding: 20px;
     color: var(--gold);
-    /* token-gap: source uses 1px solid #ffffff40 over the blue background; no token matches; owner design-system-keeper */
-    border-bottom: 1px solid #ffffff40;
+    border-bottom: 1px solid var(--white-25);
     /* token-gap: source uses 10px; no --step-* covers 10px; owner design-system-keeper */
     font:
       500 10px 'DM Mono',
@@ -94,8 +93,7 @@ const { files, initial = files[0]?.id ?? 'skill', packageLabel = 'SKILL PACKAGE'
     gap: 15px;
     padding: 17px 20px;
     border: 0;
-    /* token-gap: source uses 1px solid #ffffff40 over the blue background; no token matches; owner design-system-keeper */
-    border-bottom: 1px solid #ffffff40;
+    border-bottom: 1px solid var(--white-25);
     color: var(--paper);
     background: transparent;
     text-align: left;
diff --git a/src/components/blocks/VoteWidget.astro b/src/components/blocks/VoteWidget.astro
index 0861176..21b7a19 100644
--- a/src/components/blocks/VoteWidget.astro
+++ b/src/components/blocks/VoteWidget.astro
@@ -77,14 +77,12 @@ const share = (count: number) => (total ? Math.round((count / total) * 100) : 0)
     margin: 1px 0 25px;
     padding: 18px 22px;
     color: var(--ink);
-    /* token-gap: legacy review-desk vote bg (#e5eeeb); --paper here is #f5f4f1; owner design-system-keeper */
-    background: #e5eeeb;
+    background: var(--paper);
     border-left: 4px solid var(--gold);
   }
 
   .vote-widget > span {
-    /* token-gap: legacy review-desk --blue (#215675); --blue here is #527f9f; owner design-system-keeper */
-    color: #215675;
+    color: var(--blue);
     font: 700 10px monospace;
     letter-spacing: 0.1em;
   }
@@ -133,12 +131,10 @@ const share = (count: number) => (total ? Math.round((count / total) * 100) : 0)
   .vote-note {
     margin: 0;
     color: var(--muted);
-    /* token-gap: no --step-* covers 12px; owner design-system-keeper */
-    font-size: 12px;
+    font-size: var(--step-12);
   }
 
-  /* token-gap: 530px is not a named breakpoint; owner design-system-keeper */
-  @media (max-width: 530px) {
+  @media (max-width: 560px) {
     .vote-buttons {
       flex-direction: column;
     }
diff --git a/src/components/blocks/WorktreeMap.astro b/src/components/blocks/WorktreeMap.astro
index 10db9be..e3de476 100644
--- a/src/components/blocks/WorktreeMap.astro
+++ b/src/components/blocks/WorktreeMap.astro
@@ -151,8 +151,7 @@ const { branches, initial = 'main', rootLabel = 'ROOT', rootSmall = '● clean'
     padding: 20px;
     color: var(--paper);
     background: var(--ink);
-    /* token-gap: source uses 1px solid #41596b over the ink background; no token matches; owner design-system-keeper */
-    border: 1px solid #41596b;
+    border: 1px solid var(--muted);
     text-align: left;
     cursor: pointer;
   }
@@ -177,13 +176,11 @@ const { branches, initial = 'main', rootLabel = 'ROOT', rootSmall = '● clean'
   }
   .tree-node small {
     margin-top: 0;
-    /* token-gap: source uses #9eabb4; no token matches; owner design-system-keeper */
-    color: #9eabb4;
+    color: var(--muted);
     font-size: var(--step-0);
   }
   .tree-node.root small {
-    /* token-gap: source uses #9eabb4 even on the root; no token matches; owner design-system-keeper */
-    color: #9eabb4;
+    color: var(--muted);
   }
   .tree-node.active {
     box-shadow: inset 4px 0 0 var(--gold);
diff --git a/src/components/islands/RulesInteractive.astro b/src/components/islands/RulesInteractive.astro
index f747c90..875f8ba 100644
--- a/src/components/islands/RulesInteractive.astro
+++ b/src/components/islands/RulesInteractive.astro
@@ -487,24 +487,6 @@ fix(api): scope session query</code></pre>
 </script>
 
 <style>
-  /* Token-gap escape hatch for legacy values without a token yet — see
-     .agents/scripts/check-tokens.mjs and the rules/astro.md token contract.
-     Owner: design-system-keeper. */
-  /* token-gap: --accent/#7c78a8 etc. already tokenized; --bp-2xl/2200 covers the
-     legacy (min-width:2200px) and (max-width:900px) collapse to --bp-md/800px;
-     owner design-system-keeper */
-  :root {
-    /* token-gap: rules/styles.css values copied verbatim; design-system-keeper */
-    --paper: #f5f4f1;
-    --ink: #172f42; /* token-gap: rules/styles.css; design-system-keeper */
-    --muted: #697b89; /* token-gap: rules/styles.css; design-system-keeper */
-    --accent: #7c78a8; /* token-gap: rules/styles.css; design-system-keeper */
-    --blue: #527f9f; /* token-gap: rules/styles.css; design-system-keeper */
-    --gold: #efc76b; /* token-gap: rules/styles.css; design-system-keeper */
-    --line: #d8dee2; /* token-gap: rules/styles.css; design-system-keeper */
-    --deep: #102536; /* token-gap: rules/styles.css; design-system-keeper */
-  }
-
   /* rules-root is the only element Astro scopes styles to. The legacy
      page's rules/styles.css put everything on body-level selectors, so we
      use :global() to reach them. */
@@ -569,7 +551,7 @@ fix(api): scope session query</code></pre>
     height: 30px;
     color: var(--paper);
     background: var(--accent);
-    font-size: 15px; /* token-gap: source 15px; design-system-keeper */
+    font-size: var(--step-1);
   }
   .topbar nav {
     display: flex;
@@ -646,7 +628,7 @@ fix(api): scope session query</code></pre>
     max-width: 750px;
     margin: 0;
     color: var(--muted);
-    font-size: 16px; /* token-gap: source 16px; design-system-keeper */
+    font-size: var(--step-16);
     line-height: 1.75;
   }
   .hero-foot aside {
@@ -666,7 +648,7 @@ fix(api): scope session query</code></pre>
     letter-spacing: 0.08em;
   }
   .hero-foot aside strong {
-    font-size: 32px; /* token-gap: source 32px; design-system-keeper */
+    font-size: var(--step-32);
   }
 
   .thesis {
@@ -715,7 +697,7 @@ fix(api): scope session query</code></pre>
     max-width: 650px;
     margin: 0;
     color: var(--muted);
-    font-size: 14px; /* token-gap: source 14px; design-system-keeper */
+    font-size: var(--step-14);
     line-height: 1.75;
   }
 
@@ -779,7 +761,7 @@ fix(api): scope session query</code></pre>
     background: var(--deep);
   }
   .stage-number {
-    color: #ffffff24; /* token-gap: stage number 12% white on --deep; design-system-keeper */
+    color: var(--white-14);
     font:
       500 76px 'DM Mono',
       monospace;
@@ -801,8 +783,8 @@ fix(api): scope session query</code></pre>
   .stage-detail p,
   .skill-detail p {
     max-width: 650px;
-    color: #b8c8d2; /* token-gap: lighter than --muted on dark bg; design-system-keeper */
-    font-size: 13px; /* token-gap: source 13px; design-system-keeper */
+    color: var(--line);
+    font-size: var(--step-13);
     line-height: 1.7;
   }
   .stage-detail a,
@@ -822,7 +804,7 @@ fix(api): scope session query</code></pre>
   .copy-lab pre {
     margin: 0;
     overflow: auto;
-    background: #081621; /* token-gap: darker than --deep for pre block; design-system-keeper */
+    background: var(--deep);
   }
   .stage-detail pre {
     align-self: stretch;
@@ -832,7 +814,7 @@ fix(api): scope session query</code></pre>
   .skill-detail code,
   .example-grid code,
   .copy-lab code {
-    color: #c9d5dc; /* token-gap: code text on dark bg; design-system-keeper */
+    color: var(--line);
     font:
       11px/1.7 'DM Mono',
       monospace;
@@ -870,7 +852,7 @@ fix(api): scope session query</code></pre>
   }
   .skill-list button small {
     color: var(--muted);
-    font-size: 10px; /* token-gap: source 10px; design-system-keeper */
+    font-size: var(--step-00);
   }
   .skill-list button.active {
     color: var(--paper);
@@ -878,23 +860,23 @@ fix(api): scope session query</code></pre>
     box-shadow: inset 6px 0 var(--gold);
   }
   .skill-list button.active small {
-    color: #f0eef8; /* token-gap: near-white text on --accent active state; design-system-keeper */
+    color: var(--paper);
   }
   .skill-detail {
     display: grid;
     align-content: center;
     padding: 50px clamp(30px, 5vw, 80px);
     color: var(--paper);
-    background: #5b7098; /* token-gap: skill detail panel bg, between --blue and --accent; design-system-keeper */
+    background: var(--accent);
   }
   .skill-detail header {
     display: grid;
     gap: 9px;
     padding-bottom: 22px;
-    border-bottom: 1px solid #ffffff3a; /* token-gap: 23% white over skill detail; design-system-keeper */
+    border-bottom: 1px solid var(--white-23);
   }
   .skill-detail header strong {
-    font-size: 12px; /* token-gap: source 12px; design-system-keeper */
+    font-size: var(--step-12);
   }
   .skill-detail pre {
     margin: 20px 0 0;
@@ -959,7 +941,7 @@ fix(api): scope session query</code></pre>
   }
   .copy-lab > div p {
     max-width: 420px;
-    color: #eceaf5; /* token-gap: near-white text on --accent; design-system-keeper */
+    color: var(--paper);
     line-height: 1.6;
   }
   .copy-lab article {
@@ -974,7 +956,7 @@ fix(api): scope session query</code></pre>
     gap: 20px;
     margin: 20px;
     padding: 11px 14px;
-    border: 1px solid #ffffff50; /* token-gap: 31% white copy button border; design-system-keeper */
+    border: 1px solid var(--white-31);
     color: var(--paper);
     background: transparent;
     font:
@@ -1021,7 +1003,7 @@ fix(api): scope session query</code></pre>
     display: grid;
     grid-template-columns: repeat(4, 1fr);
     gap: 1px;
-    background: #132b3b; /* token-gap: deeper.nav grid rule color; design-system-keeper */
+    background: var(--ink);
   }
   .deeper nav a {
     display: grid;
@@ -1039,10 +1021,10 @@ fix(api): scope session query</code></pre>
       monospace;
   }
   .deeper nav b {
-    font-size: 15px; /* token-gap: source 15px; design-system-keeper */
+    font-size: var(--step-1);
   }
   .deeper nav small {
-    color: #9eb0bb; /* token-gap: muted small text on --ink; design-system-keeper */
+    color: var(--muted);
     font:
       9px 'DM Mono',
       monospace;
@@ -1080,8 +1062,7 @@ fix(api): scope session query</code></pre>
     }
   }
 
-  /* token-gap: legacy breakpoint from rules/styles.css; design-system-keeper */
-  @media (max-width: 900px) {
+  @media (max-width: 800px) {
     .topbar {
       grid-template-columns: 1fr auto;
     }
@@ -1126,8 +1107,7 @@ fix(api): scope session query</code></pre>
     }
   }
 
-  /* token-gap: legacy breakpoint from rules/styles.css; design-system-keeper */
-  @media (max-width: 600px) {
+  @media (max-width: 560px) {
     main {
       padding-inline: 18px;
     }
@@ -1171,7 +1151,7 @@ fix(api): scope session query</code></pre>
       padding: 28px 22px;
     }
     .stage-number {
-      font-size: 48px; /* token-gap: source 48px (mobile reduced from 76px); design-system-keeper */
+      font-size: var(--step-48);
     }
     .stage-detail pre {
       grid-column: auto;
diff --git a/src/components/islands/SkillPackageExplorer.astro b/src/components/islands/SkillPackageExplorer.astro
index 8552734..dbb29a2 100644
--- a/src/components/islands/SkillPackageExplorer.astro
+++ b/src/components/islands/SkillPackageExplorer.astro
@@ -140,8 +140,7 @@ const packageFiles: PackageFile[] = [
 
   .package-tree {
     padding: 22px 16px;
-    /* token-gap: legacy 1px solid #426070 over --ink; no token matches; owner design-system-keeper */
-    border-right: 1px solid #426070;
+    border-right: 1px solid var(--muted);
     min-width: 0;
   }
 
@@ -149,9 +148,8 @@ const packageFiles: PackageFile[] = [
   .package-preview > span {
     margin: 0 0 14px;
     color: var(--gold);
-    /* token-gap: source uses 11px monospace; no --step-* covers 11px on this surface; design-system-keeper */
     font:
-      700 11px / 1.35 ui-monospace,
+      700 var(--step-0) / 1.35 ui-monospace,
       monospace;
     letter-spacing: 0.1em;
   }
@@ -166,8 +164,7 @@ const packageFiles: PackageFile[] = [
     border: 0;
     border-left: 2px solid transparent;
     background: transparent;
-    /* token-gap: legacy #d6e1e4 over --ink tree buttons; no token matches; design-system-keeper */
-    color: #d6e1e4;
+    color: var(--line);
     text-align: left;
     cursor: pointer;
     transition:
@@ -180,8 +177,7 @@ const packageFiles: PackageFile[] = [
   .package-tree button:focus-visible,
   .package-tree button.active {
     border-left-color: var(--gold);
-    /* token-gap: legacy #1f3a4b active/hover on --ink tree; no token matches; design-system-keeper */
-    background: #1f3a4b;
+    background: var(--blue);
     outline: 0;
   }
 
@@ -198,8 +194,7 @@ const packageFiles: PackageFile[] = [
   }
 
   .package-tree small {
-    /* token-gap: legacy #aebfc7 muted text on --ink tree; no token matches; design-system-keeper */
-    color: #aebfc7;
+    color: var(--muted);
     font:
       11px / 1.25 Arial,
       sans-serif;
@@ -209,8 +204,7 @@ const packageFiles: PackageFile[] = [
   .package-preview {
     min-width: 0;
     padding: 26px;
-    /* token-gap: legacy #173245 preview surface (between --ink and --blue); no token matches; design-system-keeper */
-    background: #173245;
+    background: var(--ink);
     color: var(--paper);
   }
 
@@ -224,8 +218,7 @@ const packageFiles: PackageFile[] = [
   .package-preview p {
     max-width: 52ch;
     margin: 0;
-    /* token-gap: legacy #d6e1e4 muted text on #173245 preview; no token matches; design-system-keeper */
-    color: #d6e1e4;
+    color: var(--line);
   }
 
   .package-preview pre {
@@ -233,12 +226,9 @@ const packageFiles: PackageFile[] = [
     margin: 20px 0 0;
     padding: 15px;
     overflow: auto;
-    /* token-gap: legacy #466274 rule on preview pre border; no token matches; design-system-keeper */
-    border: 1px solid #466274;
-    /* token-gap: legacy #102837 fill on preview pre background; no token matches; design-system-keeper */
-    background: #102837;
-    /* token-gap: legacy #d6e1e4 code text on #102837; no token matches; design-system-keeper */
-    color: #d6e1e4;
+    border: 1px solid var(--muted);
+    background: var(--deep);
+    color: var(--line);
     font:
       12px / 1.55 ui-monospace,
       monospace;
@@ -265,16 +255,15 @@ const packageFiles: PackageFile[] = [
     }
     .package-tree {
       border-right: 0;
-      /* token-gap: legacy #426070 mobile layout rule over --ink; no token matches; design-system-keeper */
-      border-bottom: 1px solid #426070;
+      /* token-gap: legacy var(--muted) mobile layout rule over --ink; no token matches; design-system-keeper */
+      border-bottom: 1px solid var(--muted);
     }
     .package-preview {
       padding: 22px;
     }
   }
 
-  /* token-gap: legacy 520px breakpoint from skills/styles.css (mobile phone), not in named set 560/800/1100/1600/2200; design-system-keeper */
-  @media (max-width: 520px) {
+  @media (max-width: 560px) {
     .package-tree {
       padding: 18px 10px;
     }
@@ -288,8 +277,7 @@ const packageFiles: PackageFile[] = [
       padding: 18px;
     }
     .package-preview pre {
-      /* token-gap: legacy 11px mobile font-size from skills/styles.css; no --step-* covers 11px; design-system-keeper */
-      font-size: 11px;
+      font-size: var(--step-0);
     }
   }
 
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 89b07d9..2f52d3c 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -84,10 +84,8 @@ const cards = data.cards ?? [];
     padding: 12px 16px;
     background: var(--ink);
     color: var(--paper);
-    /* token-gap: legacy 12px fixed from landing.css; --step-0 is 11px;
-       no token matches 12px; owner design-system-keeper */
     font:
-      700 12px ui-monospace,
+      700 var(--step-12) ui-monospace,
       monospace;
     letter-spacing: 0.06em;
     text-decoration: none;
@@ -104,8 +102,7 @@ const cards = data.cards ?? [];
 
   .guide-launch span {
     color: var(--gold);
-    /* token-gap: legacy 22px arrow from landing.css; no --step-* covers 22px; owner design-system-keeper */
-    font-size: 22px;
+    font-size: var(--step-22);
     line-height: 0;
   }
 
@@ -121,25 +118,19 @@ const cards = data.cards ?? [];
 
   .landing-note span {
     color: var(--red);
-    /* token-gap: legacy 11px monospace eyebrow (no DM Mono in stack);
-       --step-0 also resolves to 11px but with different font weight;
-       preserved verbatim from landing.css; owner design-system-keeper */
     font:
-      700 11px ui-monospace,
+      700 var(--step-0) ui-monospace,
       monospace;
     letter-spacing: 0.1em;
   }
 
   .landing-note strong {
-    /* token-gap: clamp(22px,3.2vw,42px) is specific to this strip; no
-       --step-* ramp covers both endpoints; owner design-system-keeper */
-    font-size: clamp(22px, 3.2vw, 42px);
+    font-size: var(--step-4);
     line-height: 1.08;
     letter-spacing: -0.04em;
   }
 
-  /* token-gap: 520px collapse from landing.css (was bottom-bar threshold); owner design-system-keeper */
-  @media (max-width: 520px) {
+  @media (max-width: 560px) {
     .landing-note {
       grid-template-columns: 1fr;
       gap: 9px;
diff --git a/src/styles/tokens.css b/src/styles/tokens.css
index f879801..dda8eb8 100644
--- a/src/styles/tokens.css
+++ b/src/styles/tokens.css
@@ -20,8 +20,29 @@
   --step-6: clamp(36px, 5vw, 65px);
   --step-5: clamp(24px, 3vw, 38px);
   --step-4: clamp(22px, 3vw, 36px);
+  --step-48: 48px;
+  --step-32: 32px;
+  --step-30: 30px;
+  --step-25: 25px;
+  --step-24: 24px;
+  --step-22: 22px;
+  --step-20: 20px;
+  --step-18: 18px;
+  --step-17: 17px;
+  --step-16: 16px;
   --step-1: 15px;
+  --step-14: 14px;
+  --step-13: 13px;
+  --step-12: 12px;
   --step-0: 11px;
+  --step-00: 10px;
+  --step-09: 9px;
+
+  /* Overlays */
+  --white-14: rgb(255 255 255 / 14%);
+  --white-23: rgb(255 255 255 / 23%);
+  --white-25: rgb(255 255 255 / 25%);
+  --white-31: rgb(255 255 255 / 31%);
 
   /* Breakpoints */
   --bp-sm: 560px;