remarque-tokens 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
 
+## 0.6.1 — 2026-07-21
+
+### Fixed
+Three audit/parser bugs from real-world adoption (#67, found by tsundoku):
+- Body-less at-statements (`@import`, `@charset`) preceding a block no
+  longer pollute its prelude and misclassify it as an at-rule — palette
+  files may begin with imports.
+- Selector classification accepts qualified root forms (`html:root`,
+  `html[data-theme="dark"]`, `body.dark`, …) instead of exact strings.
+- `--src` scans now strip HTML `<!-- -->` comments (line-numbers
+  preserved) like CSS comments, ending issue-number false positives in
+  .astro/.svelte markup.
+
+Two new convention fixtures (leading-import, qualified-selectors) lock
+the fixes in CI. Consumers can drop their documented workarounds.
+
+## 0.6.0 — 2026-07-20
+
+### Added
+- **`--weight-display`** (palette tier, theme-conditional): display faces
+  render at 400 in light mode and 500 in dark — light-on-dark text is
+  optically thinner (halation), and high-contrast serif hairlines were
+  disappearing at display sizes on dark backgrounds (#59).
+  `.text-display`/`.text-title` consume it with a 400 fallback, so
+  palettes that don't define it are unaffected.
+- **The remarque mark** (`.remarque-endmark` in prose.css): the system's
+  namesake made visible — a small muted fleuron closing every essay.
+  One per essay, aria-hidden, deliberately outside the latin subsets so
+  it falls to the serif fallback stack.
+
 ## 0.5.1 — 2026-07-20
 
 Two `remarque-audit` fixes found by the flagship site's adoption (its

package/REMARQUE.md

@@ -222,6 +222,48 @@ Agents reviewing PRs should reject changes that violate any line above without e
 
 ---
 
+## Lineage: Butterick's Five Rules
+
+Remarque's core values descend from Matthew Butterick's [*Typography in
+Ten Minutes*](https://practicaltypography.com/typography-in-ten-minutes.html)
+(an acknowledged inspiration). The mapping, including where and why we
+deviate — values below are asserted against `tokens.json` in CI:
+
+| Butterick rule | His guidance | Remarque | Status |
+|---|---|---|---|
+| 1. Body text first | Typographic quality is determined largely by body text | AGENT_RULES.md Build Order steps 1–4 are tokens → typography → shell → prose, before any component | Aligned by construction |
+| 2. Point size | 15–25 px on the web | `--text-body: 1.0625rem` (17px); lead paragraphs `--text-body-lg: 1.1875rem` (19px) | Aligned |
+| 3. Line spacing | 120–145% of point size | `--leading-body: 1.75` (175%) | **Deliberate deviation** — see below |
+| 4. Line length | 45–90 characters per line | `--content-reading: 46rem` ≈ 70 ch at 17px Inter; the measure-compensation table targets 66–72 ch for every approved body face | Aligned |
+| 5. Font choice | Professional fonts, never default system faces | Newsreader (Production Type), Inter (Rasmus Andersson), JetBrains Mono — professionally designed, self-hosted | Aligned in spirit: these are free but professional-grade faces; Butterick's stricter preference is paid fonts |
+
+### The line-spacing deviation, argued
+
+Remarque's 175% body leading sits **outside Butterick's 120–145% range,
+at the airy extreme of quality web practice (commonly 150–165%)**. We
+own that plainly rather than argue it away. The reasons it is a
+deliberate identity choice, not an oversight:
+
+1. **Leading scales with measure.** Classic guidance ties looser leading
+   to longer lines; Remarque's ~70 ch measure sits in the upper-middle
+   of Butterick's own 45–90 ch range, and screen prose at 17px benefits
+   from more air than his print-derived band.
+2. **Token-hierarchy coherence.** Literal conformance (≤145%) would put
+   body leading *below* `--leading-meta: 1.5` — which is pinned by the
+   USWDS/WCAG floors this spec also adopts. Body text reading tighter
+   than caption text is not a hierarchy this system will ship.
+3. **Identity.** "Generous — this is what makes prose readable" predates
+   this audit; the spacious register is part of what makes a Remarque
+   page recognizable (see Signature Moves).
+
+The trade-off is real: 1.75 spends more vertical space and reads calmer
+and slower than 1.5–1.65. Sites wanting Butterick-tighter rhythm are
+choosing a different identity — that is a fork, and an honorable one,
+but it is not Remarque. (Ratified 3–0 by design-review panel, 2026-07-20,
+over the alternative of changing the token.)
+
+---
+
 ## Decision Order
 
 When multiple design options are possible, choose in this order:
@@ -324,7 +366,8 @@ The homepage or entry point. Sets the tone.
 
 These are the repeatable visual tells that make a Remarque site recognizable:
 
-- Serif hero/page titles (Newsreader at display scale)
+- The remarque mark: a small muted fleuron closing every essay (`.remarque-endmark`) — the namesake made visible, one per essay, never decorated further
+- Serif hero/page titles (Newsreader at display scale; display weight bumps one step in dark mode to keep serif hairlines alive)
 - Mono metadata rows beneath titles
 - Constrained body width with generous margins
 - Subtle `1px` section dividers using `--color-border`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "engines": {
     "node": ">=18"
   },

package/prose.css

@@ -137,3 +137,29 @@
   margin-top: var(--space-2);
 }
 
+
+/* ─── The Remarque Mark ─────────────────────────────────── */
+/*
+ * The system's namesake, made visible: a small mark closing every
+ * essay, the way a printer's fleuron ends a chapter. Quiet by rule —
+ * muted color, meta scale, one per essay, nothing else on its line.
+ *
+ * Markup (aria-hidden — it is punctuation, not content):
+ *   <div class="remarque-endmark" aria-hidden="true"></div>
+ * placed after the last element inside .remarque-prose.
+ *
+ * The fleuron (U+2766) is outside the latin font subsets by design;
+ * it intentionally falls through to the serif fallback stack.
+ */
+
+.remarque-endmark {
+  text-align: center;
+  margin-top: var(--space-7);
+}
+
+.remarque-endmark::after {
+  content: "\2766";
+  font-family: var(--font-display);
+  font-size: var(--text-body);
+  color: var(--color-muted);
+}

package/scripts/audit.mjs

@@ -165,6 +165,7 @@ for (const file of walk(SRC)) {
   // prose like "(issue #324)" in a comment trips the hex-color regex.
   const text = readFileSync(file, 'utf8')
     .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '))
     .replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + ' '.repeat(m.length - p1.length));
   const lines = text.split('\n');
   lines.forEach((line, i) => {

package/scripts/lib/css-tokens.mjs

@@ -16,7 +16,10 @@ export function extractBlocks(css) {
     while (i < text.length) {
       const open = text.indexOf('{', i);
       if (open === -1) break;
-      const prelude = text.slice(i, open).trim().replace(/^[;\s]+/, '');
+      // Body-less at-statements (@import 'x'; @charset ...;) preceding a block
+      // would otherwise pollute its prelude and misclassify it as an at-rule
+      // (#67): keep only the segment after the last ';'.
+      const prelude = text.slice(i, open).split(';').pop().trim();
       let depth = 1, j = open + 1;
       while (j < text.length && depth > 0) {
         if (text[j] === '{') depth++;
@@ -49,12 +52,15 @@ export function declsOf(blocks, filterFn) {
    dark block in the class convention) as light. */
 const parts = (prelude) => prelude.split(',').map((s) => s.trim());
 
+const DARKISH = /(\.dark\b|\[data-theme="dark"\])/;
+const ROOTISH = /^(:root|html|body)\b/;
 export const isLightRoot = (b) =>
-  b.context === '' && parts(b.prelude).some((s) => s === ':root' || s === ':root.light' || s === '[data-theme="light"]');
+  b.context === '' && parts(b.prelude).some((s) =>
+    (ROOTISH.test(s) && !DARKISH.test(s)) || s === '[data-theme="light"]');
 
 /* Dark: media-query :root, the canonical [data-theme="dark"], or the
    class-convention :root.dark / html.dark (compatibility bridge). */
 export const isDarkBlock = (b) =>
   (b.context.includes('prefers-color-scheme') && b.context.includes('dark') &&
-    parts(b.prelude).some((s) => s === ':root')) ||
-  parts(b.prelude).some((s) => s === '[data-theme="dark"]' || s === ':root.dark' || s === 'html.dark' || s === '.dark');
+    parts(b.prelude).some((s) => ROOTISH.test(s) && !DARKISH.test(s))) ||
+  parts(b.prelude).some((s) => DARKISH.test(s) && (ROOTISH.test(s) || s.startsWith('.') || s.startsWith('[')));

package/tokens-core.css

@@ -130,7 +130,7 @@ html {
   font-size: var(--text-display);
   line-height: var(--leading-display);
   letter-spacing: var(--tracking-display);
-  font-weight: var(--weight-regular);
+  font-weight: var(--weight-display, var(--weight-regular));
 }
 
 .text-title {
@@ -138,7 +138,7 @@ html {
   font-size: var(--text-title);
   line-height: var(--leading-title);
   letter-spacing: var(--tracking-title);
-  font-weight: var(--weight-regular);
+  font-weight: var(--weight-display, var(--weight-regular));
 }
 
 .text-section {

package/tokens-palette.css

@@ -34,6 +34,12 @@
   /* Reading measure — tuned to the body font (see REMARQUE.md measure table).
      46rem ≈ 70 characters per line at 17px Inter. */
   --content-reading: 46rem;
+
+  /* Display weight — palette-tier because it is theme-conditional:
+     light-on-dark text renders optically thinner (halation), so dark
+     mode bumps display faces one step to keep serif hairlines alive.
+     (issue #59) */
+  --weight-display: 400;
 }
 
 /* ─── Color: Light theme (default) ──────────────────────── */
@@ -89,6 +95,7 @@
     --color-bg:          oklch(0.16 0.01 80);     /* warm charcoal, not black */
     --color-bg-subtle:   oklch(0.19 0.01 80);
     --color-fg:          oklch(0.90 0.005 80);    /* soft white, not pure */
+    --weight-display: 500;                        /* compensate thin serif hairlines on dark */
     --color-fg-muted:    oklch(0.70 0.01 80);    /* 7.26:1 bg (AAA) */
     --color-muted:       oklch(0.60 0.01 80);    /* 4.92:1 bg / 4.68:1 surface (AA with margin) */
     --color-border:      oklch(0.25 0.005 80);   /* decorative only — see light-theme note */
@@ -116,6 +123,7 @@
    light-dark(), which obsoletes both selectors. */
 [data-theme="dark"],
 :root.dark {
+  --weight-display: 500;
   --color-bg:          oklch(0.16 0.01 80);
   --color-bg-subtle:   oklch(0.19 0.01 80);
   --color-fg:          oklch(0.90 0.005 80);

package/tokens.json

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.5.1",
+      "version": "0.6.1",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
@@ -236,6 +236,15 @@
         }
       }
     },
+    "weight-display": {
+      "$type": "fontWeight",
+      "light": {
+        "$value": 400
+      },
+      "dark": {
+        "$value": 500
+      }
+    },
     "color-bg": {
       "$type": "color",
       "light": {