netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(blocks): restore legacy values with token-gap markers

Browse Source 
Tasks 10 and 11 documented that the first attempt pointed raw values at
the nearest --step-* / palette token. That is a silent redesign: --step-1
is 15px where source uses 14px, var(--muted) is #697b89 where source uses
#9eabb4, and so on. The brief says the site must look exactly as it did.

check-tokens.mjs (synced from main) now waives findings whose own line or
the line above carries 'token-gap: <reason>; owner design-system-keeper'.
Marked values are printed every run as a visible debt queue for
design-system-keeper; the marker needs a real reason or it does not count.

Restored to the exact legacy values:

  FleetDiagram   captain-eyebrow 10px, captain h2 clamp(24,3vw,38),
                 arrow 30px, workers parent #41596b seam,
                 worker-card span color #9eabb4 + font 10px,
                 worker-card strong 16px
  HandoffTable   thead 10px, tbody th 14px, td 13px
  PhasePanel     phase-tab 10px, phase-meta 10px, panel h3 clamp(24,3vw,38)
  RouteTable     head 10px, strong 14px, small 12px
  SkillPackage   label 10px + #ffffff40 borders, row 12px code (no weight)
  WorktreeMap    border 1px solid #41596b, span 9px, strong 14px,
                 small color #9eabb4 (root and branch)

Values that already matched a token (captain/worker code at --step-0=11px,
the panel code, all the layout/spacing values, colours that did match)
are untouched.

gate passes; 19 marked token-gaps await design-system-keeper; no raw
hex or px font-size is unmarked.

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-09-05 07:25:38 +00:00
parent d7820edb04
commit ba56f7a0c9
7 changed files with 117 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/scripts/check-tokens.mjs
+64 -20
View File
@@ -3,6 +3,23 @@
// the token layer. A rule nobody checks is a suggestion — wire this into
// `pnpm run verify`.
//
// ESCAPE HATCH — `token-gap:`. Some legacy values have no token yet, and only
// `design-system-keeper` may add one. Without an escape, an agent told both
// "keep the site identical" and "get the gate green" has to break one of them,
// and tasks 10 and 11 both broke the first: `#e5eeeb` became `var(--paper)`,
// diff-added green became `var(--accent)` purple. Substituting a near-miss
// token is a silent redesign; it is worse than a raw value, because the raw
// value is at least honest about what it is.
//
// So: mark the line, keep the true value, stay green.
//
// /* token-gap: no --step-* covers 12px; owner design-system-keeper */
// font-size: 12px;
//
// Marked values are counted and listed on every run — they are a visible debt
// queue, not a way to make the finding disappear. The marker needs a reason;
// a bare `token-gap:` does not count.
//
// Usage: node .agents/scripts/check-tokens.mjs [srcDir]
import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -24,35 +41,62 @@ const targets = ARGS.length
: walk('src');
const findings = [];
const gaps = [];
// A finding is waived when its own line, or the line above it, carries a
// `token-gap:` marker with a reason after the colon.
const MARKER = /token-gap:([^\n]*)/;
// The reason is what is left after the marker once the comment terminator and
// punctuation are stripped. `/* token-gap: */` is not a reason.
const reason = (line) => {
const found = MARKER.exec(line ?? '');
if (!found) return null;
const text = found[1]
.replace(/\*\/\s*$/, '')
.replace(/[\s*/]+$/, '')
.trim();
return /[a-z0-9]/i.test(text) ? [null, text] : null;
};
const waiver = (lines, index) =>
reason(lines[index]) || (index > 0 ? reason(lines[index - 1]) : null);
for (const path of targets) {
if (!['.astro', '.css'].includes(extname(path))) continue;
if (TOKEN_FILES.some((allowed) => path.endsWith(allowed))) continue;
readFileSync(path, 'utf8')
.split('\n')
.forEach((line, index) => {
const at = `${path}:${index + 1}`;
const lines = readFileSync(path, 'utf8').split('\n');
lines.forEach((line, index) => {
const at = `${path}:${index + 1}`;
const waived = waiver(lines, index);
const record = (finding) => {
if (waived) gaps.push(`${at}: ${finding.slice(at.length + 2)} [${waived[1]}]`);
else findings.push(finding);
};
// Raw hex — the drifted-palette failure mode this whole layer exists to stop.
const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
if (hex) findings.push(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
// Raw hex — the drifted-palette failure mode this whole layer exists to stop.
const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
if (hex) record(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
// rgb()/hsl() literals are the same problem wearing a different hat.
if (/\b(rgba?|hsla?)\(\s*\d/.test(line))
findings.push(`${at}: raw colour function — use a token`);
// rgb()/hsl() literals are the same problem wearing a different hat.
if (/\b(rgba?|hsla?)\(\s*\d/.test(line)) record(`${at}: raw colour function — use a token`);
// Hard-coded font sizes bypass the type scale.
const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
if (fontSize) findings.push(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
// Hard-coded font sizes bypass the type scale.
const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
if (fontSize) record(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
// Ad-hoc breakpoints are how sixteen of them accumulated last time.
const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
findings.push(
`${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
);
});
// Ad-hoc breakpoints are how sixteen of them accumulated last time.
const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
record(
`${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
);
});
}
if (gaps.length) {
console.log(`token check: ${gaps.length} marked token-gap(s) awaiting design-system-keeper:\n`);
gaps.forEach((gap) => console.log(` ${gap}`));
console.log('');
}
if (findings.length) {