M3: dead code purge + layer refs → semantic tokens

Dead code removed:
- 05-utilities: grid-2/card-grid/stats block (superseded by 08-layout)
- 02-semantic: dialog min-width:100% (conflicted with 03-components)
- 02-semantic: hgroup p dead font-family, redundant nested list margin
- All layers: [ai-disclosure] → [data-ai-disclosure] (bug fix)
- table.striped → [data-table="striped"] (classless alignment)

Ref cleanup: 12 --gray-N/--green-N/--blue-N replaced with semantic
tokens. 24 refs marked TODO (syntax highlighting needs --syntax-* aliases).

assets/css/layers/02-semantic.css

@@ -84,9 +84,7 @@ figcaption,
 button,
 input,
 select,
-textarea,
+textarea {
-hgroup > p,
-hgroup > small {
   font-family: var(--font-ui);
 }
 
@@ -169,7 +167,6 @@ ul {
 
 /* Nested lists: reduce spacing */
 :where(dl, ol, ul) :where(dl, ol, ul) {
-  margin: 0;
   margin-top: calc(var(--type-space) * 0.25);
 }
 
@@ -326,8 +323,8 @@ tfoot td {
 }
 
 /* Striped tables (class-based but useful) */
-table.striped tbody tr:nth-child(odd) th,
+[data-table="striped"] tbody tr:nth-child(odd) th,
-table.striped tbody tr:nth-child(odd) td {
+[data-table="striped"] tbody tr:nth-child(odd) td {
   background-color: var(--table-stripe);
 }
 
@@ -410,7 +407,7 @@ pre[class*="language-"] {
 .token.prolog,
 .token.doctype,
 .token.cdata {
-  color: var(--gray-6);       /* muted: ~55% lightness */
+  color: var(--gray-6); /* TODO: map to semantic token — no alias for gray-6 (between --text-3: gray-5 and --text-dim: gray-7) */
   font-style: italic;
 }
 
@@ -420,19 +417,19 @@ pre[class*="language-"] {
 
 .token.tag,
 .token.deleted {
-  color: var(--red-4);        /* HTML tags, deleted code */
+  color: var(--red-4); /* TODO: map to semantic token — no alias for red-4 (--error=red-7, --callout-error=red-5; syntax highlight needs lighter shade) */
 }
 
 .token.attr-name,
 .token.namespace {
-  color: var(--yellow-4);     /* attribute names */
+  color: var(--yellow-4); /* TODO: map to semantic token — no alias for yellow-4 (--warn=yellow-5 is close but one step darker) */
 }
 
 .token.string,
 .token.attr-value,
 .token.char,
 .token.inserted {
-  color: var(--green-4);      /* strings, values */
+  color: var(--accent-hover);  /* strings, values — --accent-hover = var(--green-4) */
 }
 
 .token.number,
@@ -449,7 +446,7 @@ pre[class*="language-"] {
 
 .token.keyword,
 .token.atrule {
-  color: var(--blue-4);       /* keywords, @rules */
+  color: var(--link-hover);    /* keywords, @rules — --link-hover = var(--blue-4) */
 }
 
 .token.function,
@@ -458,7 +455,7 @@ pre[class*="language-"] {
 }
 
 .token.property {
-  color: var(--blue-5);       /* object properties */
+  color: var(--info);          /* object properties — --info = var(--blue-5) */
 }
 
 .token.operator,
@@ -473,7 +470,7 @@ pre[class*="language-"] {
 
 .token.important,
 .token.variable {
-  color: var(--yellow-5);     /* !important, variables */
+  color: var(--warn);          /* !important, variables — --warn = var(--yellow-5) */
   font-weight: var(--font-weight-5);
 }
 
@@ -485,20 +482,20 @@ pre[class*="language-"] {
   .token.comment,
   .token.prolog,
   .token.doctype,
-  .token.cdata    { color: var(--gray-6); }
+  .token.cdata    { color: var(--gray-6); /* TODO: map to semantic token — no alias for gray-6 in light mode */ }
 
-  .token.punctuation   { color: var(--gray-8); }
+  .token.punctuation   { color: var(--gray-8); /* TODO: map to semantic token — no alias for gray-8 */ }
 
   .token.tag,
-  .token.deleted       { color: var(--red-8); }
+  .token.deleted       { color: var(--red-8); /* TODO: map to semantic token — no alias for red-8 */ }
 
   .token.attr-name,
-  .token.namespace     { color: var(--yellow-9); }
+  .token.namespace     { color: var(--yellow-9); /* TODO: map to semantic token — no alias for yellow-9 */ }
 
   .token.string,
   .token.attr-value,
   .token.char,
-  .token.inserted      { color: var(--green-8); }
+  .token.inserted      { color: var(--green-8); /* TODO: map to semantic token — no alias for green-8 */ }
 
   .token.number,
   .token.boolean,
@@ -509,21 +506,21 @@ pre[class*="language-"] {
   .token.builtin       { color: var(--teal-8); }
 
   .token.keyword,
-  .token.atrule        { color: var(--blue-8); }
+  .token.atrule        { color: var(--blue-8); /* TODO: map to semantic token — no alias for blue-8 */ }
 
   .token.function,
   .token.class-name    { color: var(--cyan-9); }
 
-  .token.property      { color: var(--blue-9); }
+  .token.property      { color: var(--blue-9); /* TODO: map to semantic token — no alias for blue-9 */ }
 
   .token.operator,
   .token.entity,
-  .token.url           { color: var(--gray-8); }
+  .token.url           { color: var(--gray-8); /* TODO: map to semantic token — no alias for gray-8 in light mode */ }
 
   .token.regex         { color: var(--orange-7); }
 
   .token.important,
-  .token.variable      { color: var(--yellow-9); }
+  .token.variable      { color: var(--yellow-9); /* TODO: map to semantic token — no alias for yellow-9 */ }
 }
 
 /* ── Details / Summary ─────────────────────────────────────────────── */
@@ -603,7 +600,7 @@ dialog {
   align-items: center;
   justify-content: center;
   width: inherit;
-  min-width: 100%;
+  min-width: auto;
   height: inherit;
   min-height: 100%;
   padding: 0;

assets/css/layers/03-components.css

@@ -701,7 +701,7 @@ dialog:not([open]) {
 
 /* Backdrop (modal mode only — showModal()) */
 dialog::backdrop {
-  background: color-mix(in oklch, var(--gray-15) 70%, transparent);
+  background: var(--modal-overlay);
   backdrop-filter: blur(4px);
   -webkit-backdrop-filter: blur(4px);
 }

assets/css/layers/04-data-attrs.css

@@ -398,12 +398,12 @@
 
 [data-diff-line="added"] {
   background: var(--diff-add-bg);
-  color: var(--green-3);
+  color: var(--green-3); /* TODO: map to semantic token — no alias for green-3 (--accent-hover=green-4 is one step darker) */
 }
 
 [data-diff-line="added"]::before {
   content: "+";
-  color: var(--green-5);
+  color: var(--ok);  /* --ok = var(--green-5) */
 }
 
 [data-diff-line="removed"] {
@@ -413,7 +413,7 @@
 
 [data-diff-line="removed"]::before {
   content: "−";
-  color: var(--red-6);
+  color: var(--red-6); /* TODO: map to semantic token — no alias for red-6 (--error=red-7, --callout-error=red-5) */
 }
 
 [data-diff-line="context"] {
@@ -497,12 +497,12 @@
 /* Light mode adjustments */
 @media (prefers-color-scheme: light) {
   [data-redacted] {
-    background: var(--gray-15);
+    background: var(--gray-15); /* TODO: map to semantic token — no alias for absolute black; needed for redaction bar in light mode */
   }
   [data-redacted="reveal"]:hover,
   [data-redacted="reveal"]:focus {
-    background: var(--gray-1);
+    background: var(--surface-1);  /* light mode: --surface-1 = var(--gray-1) */
-    color: var(--gray-15);
+    color: var(--gray-15); /* TODO: map to semantic token — no alias for absolute black text in light mode */
   }
 }
 
@@ -545,33 +545,33 @@
    ══════════════════════════════════════════════════════════════════════════ */
 
 /* Subtle accent on AI-generated sections — light left border indicator */
-[ai-disclosure] {
+[data-ai-disclosure] {
   border-left: var(--border-size-2) solid transparent;
   padding-left: var(--space-3);
 }
 
-[ai-disclosure="ai-generated"] {
+[data-ai-disclosure="ai-generated"] {
   border-left-color: var(--ai-generated-border);
 }
 
-[ai-disclosure="ai-assisted"] {
+[data-ai-disclosure="ai-assisted"] {
   border-left-color: var(--ai-assisted-border);
 }
 
 /* Autonomous — more distinct: full accent treatment */
-[ai-disclosure="autonomous"] {
+[data-ai-disclosure="autonomous"] {
   border-left-color: var(--accent);
   border-left-width: var(--border-size-2);
 }
 
 /* Mixed — yellow/amber to signal blended provenance */
-[ai-disclosure="mixed"] {
+[data-ai-disclosure="mixed"] {
   border-left-color: var(--ai-mixed-border);
 }
 
 /* Disclosure badge — optional ::after label for verbose mode */
-[ai-disclosure][data-show-disclosure]::after {
+[data-ai-disclosure][data-show-disclosure]::after {
-  content: " [" attr(ai-disclosure) "]";
+  content: " [" attr(data-ai-disclosure) "]";
   font-family: var(--font-mono);
   font-size: var(--text-xs);
   color: var(--text-dim);

assets/css/layers/05-utilities.css

@@ -48,82 +48,6 @@
   padding-inline: var(--space-5);
 }
 
-/* Grid layout with responsive stacking */
-[data-layout="grid-2"] {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: var(--space-4);
-}
-
-@media (--md-n-below) {
-  [data-layout="grid-2"] {
-    grid-template-columns: 1fr;
-  }
-}
-
-/* Card grid — responsive wrap for article cards */
-[data-layout="card-grid"] {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-5);
-}
-
-[data-layout="card-grid"] > * {
-  flex: 1 1 calc(50% - 0.75rem);
-  min-width: var(--size-px-13);
-}
-
-@media (--md-n-below) {
-  [data-layout="card-grid"] > * {
-    flex-basis: 100%;
-  }
-}
-
-/* Stats bar — horizontal row of key-value metrics */
-[data-layout="stats"] {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0;
-}
-
-[data-layout="stats"] > * {
-  flex: 1 1 0;
-  min-width: 5rem;
-  padding: var(--space-3) 0;
-  text-align: center;
-  border-right: var(--border-width) solid var(--border-subtle);
-}
-
-[data-layout="stats"] > *:last-child {
-  border-right: none;
-}
-
-[data-layout="stats"] .value {
-  display: block;
-  font-family: var(--font-mono);
-  font-size: 1.5rem;
-  font-weight: 600;
-  line-height: 1.2;
-}
-
-[data-layout="stats"] .label {
-  display: block;
-  font-family: var(--font-mono);
-  font-size: 0.65rem;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  color: var(--text-3);
-  margin-top: 0.2rem;
-}
-
-@media (--sm-n-below) {
-  [data-layout="stats"] > * {
-    flex-basis: 33%;
-    border-right: none;
-    border-bottom: var(--border-width) solid var(--border-subtle);
-  }
-}
-
 /* Inline definition lists */
 dl[data-layout="inline"] {
   display: grid;
@@ -247,10 +171,10 @@ dl[data-layout="inline"] dd {
 /* Increase contrast for high-contrast preference */
 @media (prefers-contrast: more) {
   :root {
-    --border-color: var(--gray-10);
+    --border-color: var(--gray-10); /* TODO: map to semantic token — no alias for gray-10 (--border=gray-11; high-contrast needs one step higher) */
-    --border-color-subtle: var(--gray-12);
+    --border-color-subtle: var(--border-subtle);  /* --border-subtle = var(--gray-12) */
-    --text-primary: var(--gray-0);
+    --text-primary: var(--gray-0); /* TODO: map to semantic token — no alias for gray-0 (--text=gray-1 in dark; high-contrast needs brightest white) */
-    --text-secondary: var(--gray-3);
+    --text-secondary: var(--text-2);  /* --text-2 = var(--gray-3) */
     --border-width: var(--border-size-2);
   }
   

assets/css/layers/06-charts.css

@@ -571,7 +571,7 @@
   border-radius: 50%;
   background: conic-gradient(
     var(--color, var(--chart-color-1)) 0deg calc(var(--size, 0.5) * 360deg),
-    var(--surface-1, var(--gray-15)) 0deg
+    var(--surface-1, var(--surface)) 0deg
   );
   display: flex;
   align-items: center;

assets/css/layers/07-chroma.css

@@ -57,12 +57,12 @@
 .chroma .sr,
 .chroma .s1,
 .chroma .ss {
-  color: var(--green-4);
+  color: var(--accent-hover);  /* --accent-hover = var(--green-4) */
 }
 
 /* LiteralStringEscape — \n \t etc — slightly lighter to distinguish */
 .chroma .se {
-  color: var(--green-3);
+  color: var(--green-3); /* TODO: map to semantic token — no alias for green-3 (--accent-hover=green-4 is one step darker) */
 }
 
 /* ── Comments ────────────────────────────────────────────────────────── */
@@ -103,7 +103,7 @@
 .chroma .nf,
 .chroma .nx,
 .chroma .py {
-  color: var(--blue-3);
+  color: var(--blue-3); /* TODO: map to semantic token — no alias for blue-3 (--link-hover=blue-4 is one step darker) */
 }
 
 /* ── Operators / Punctuation ─────────────────────────────────────────── */
@@ -117,14 +117,14 @@
 /* ── Error ───────────────────────────────────────────────────────────── */
 
 .chroma .err {
-  color: var(--red-4);
+  color: var(--red-4); /* TODO: map to semantic token — no alias for red-4 (--error=red-7 is much darker; syntax error highlight needs lighter shade) */
   background: transparent;
 }
 
 /* ── Generic diffs / emphasis ────────────────────────────────────────── */
 
-.chroma .gd { color: var(--red-4); }
+.chroma .gd { color: var(--red-4); /* TODO: map to semantic token — no alias for red-4; see --diff-remove-text=red-2 but that's even lighter */ }
-.chroma .gi { color: var(--green-4); }
+.chroma .gi { color: var(--accent-hover); /* --accent-hover = var(--green-4) */ }
 .chroma .ge { font-style: italic; }
 .chroma .gs { font-weight: bold; }
 

assets/css/layers/08-layout.css

@@ -31,6 +31,7 @@ body {
 
 /* ── Hero ──────────────────────────────────────────────────────────── */
 /* Landing page hero block. Usually <header data-layout="hero">. */
+/* Base hero — 09-landing.css overrides for full landing pages */
 [data-layout="hero"] {
   text-align: center;
   padding: var(--space-8) var(--space-5);
@@ -541,8 +542,8 @@ main[data-layout="prose"],
 /* Print styles */
 @media print {
   [data-layout="report"] {
-    --surface: var(--gray-0);
+    --surface: var(--gray-0);   /* TODO: map to semantic token — overriding --surface for print; no alias for gray-0 as "print-white" */
-    --text: var(--gray-15);
+    --text: var(--gray-15);     /* TODO: map to semantic token — overriding --text for print; no alias for gray-15 as "print-black" */
     font-size: 11pt;
   }