Files
arr/web/scripts/check-tokens.mjs
T
naps62-yolo 5a18facc4f
ci / web (push) Successful in 33s
e2e / e2e (push) Successful in 1m36s
ci / rust (push) Successful in 1m49s
ci / image (push) Successful in 2m36s
refactor(web): move the stylesheet into Tailwind utilities (#281)
2026-11-11 21:14:23 +00:00

178 lines
6.2 KiB
JavaScript

#!/usr/bin/env node
// Design-token gate (issue #45): components consume tokens from :root in
// web/src/style.css, never literal colour or spacing values.
//
// Every `var(--x)` must name a custom property something defines — a token in
// `:root`, a component-local one in the CSS, or one the TS sets with
// `setProperty` or a React `style` key — so a mistyped or deleted token fails
// here rather than silently falling back to the browser default.
//
// Tailwind's theme is reset to the tokens alone (style.css), so a utility can
// only produce a token value. The one way around that is an arbitrary value
// — `p-[3px]`, `bg-[#fff]` — and those are allowed only when they name a
// token: `p-[var(--space-2)]` or the `p-(--space-2)` shorthand.
//
// Allowed colour literals: inside a `:root` block (token definitions) and
// inside `@font-face`. Relative colour derived from a token —
// `oklch(from var(--x) …)` — counts as consuming the token and is allowed
// anywhere. Spacing properties (margin/padding/gap/inset) may only use
// var(), 0, auto and percentages; font-size only a --text-* token.
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative } from "node:path";
import process from "node:process";
const webRoot = new URL("..", import.meta.url).pathname;
const SKIP_DIRS = new Set(["node_modules", "dist", "api"]);
function walk(dir, out = []) {
for (const name of readdirSync(dir)) {
const path = join(dir, name);
if (statSync(path).isDirectory()) {
if (!SKIP_DIRS.has(name)) {
walk(path, out);
}
} else if (/\.(css|tsx?|html)$/.test(name)) {
out.push(path);
}
}
return out;
}
const COLOR_LITERAL = /#[0-9a-fA-F]{3,8}\b|\b(?:oklch|oklab|lab|lch|rgba?|hsla?|hwb|color)\(/;
// `_` is a space inside a Tailwind arbitrary value
const RELATIVE_FROM_TOKEN = /\b(?:oklch|oklab|lab|lch|rgb|hsl|hwb|color)\([\s_]*from[\s_]+var\(--/g;
const SPACING_PROP = /^(?:margin|padding|gap|row-gap|column-gap|inset)(?:-[a-z-]+)?$/;
const SPACING_VALUE = /^(?:var\(--[\w-]+\)|0|auto|-?[\d.]+%)$/;
const FONT_SIZE_VALUE = /^var\(--text-[\w-]+\)$/;
const errors = [];
function checkDeclaration(declaration, rel, line) {
// Relative-colour-from-token is token consumption, not a literal.
const neutral = declaration.replace(RELATIVE_FROM_TOKEN, "from-token(");
if (COLOR_LITERAL.test(neutral)) {
errors.push(`${rel}:${line}: literal colour — use a token from :root`);
}
const colon = declaration.indexOf(":");
if (colon === -1) {
return;
}
const property = declaration.slice(0, colon).trim();
const value = declaration.slice(colon + 1).trim();
if (property === "font-size") {
if (!FONT_SIZE_VALUE.test(value)) {
errors.push(`${rel}:${line}: literal font-size "${value}" — use a --text-* token`);
}
return;
}
if (!SPACING_PROP.test(property)) {
return;
}
const bad = value.split(/\s+/).filter((part) => part && !SPACING_VALUE.test(part));
if (bad.length > 0) {
errors.push(`${rel}:${line}: literal spacing "${bad.join(" ")}" — use a --space-* token`);
}
}
function checkCss(source, rel) {
const stripped = source.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "));
const blockStack = [];
let buffer = "";
let bufferLine = 1;
let line = 1;
for (const char of stripped) {
if (char === "\n") {
line += 1;
}
if (char === "{") {
blockStack.push(buffer.trim() || "(anonymous)");
buffer = "";
bufferLine = line;
} else if (char === ";" || char === "}") {
const declaration = buffer.trim();
const allowed = blockStack.some((sel) => /(^|,)\s*:root\b|@font-face/.test(sel));
if (declaration && !allowed) {
checkDeclaration(declaration, rel, bufferLine);
}
if (char === "}") {
blockStack.pop();
}
buffer = "";
bufferLine = line;
} else {
if (buffer.trim() === "") {
bufferLine = line;
}
buffer += char;
}
}
}
// a value, not a variant: `data-[tone=fault]:` selects, it does not style
const ARBITRARY = /(?:^|[\s"'`:])!?-?[a-z][\w-]*-\[([^\]\s]+)\](?!:)/g;
function checkPlain(source, rel) {
// Comments are prose, not styling — `checkCss` already ignores them, and
// without the same treatment here an issue reference like `#140` reads as a
// three-digit hex colour and fails the gate.
const stripped = source
.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "))
.replace(/\/\/.*$/gm, "");
stripped.split("\n").forEach((rawLine, index) => {
const neutral = rawLine.replace(RELATIVE_FROM_TOKEN, "from-token(");
if (COLOR_LITERAL.test(neutral)) {
errors.push(`${rel}:${index + 1}: literal colour outside the token block`);
}
for (const match of rawLine.matchAll(ARBITRARY)) {
if (!/^var\(--[\w-]+\)$/.test(match[1])) {
errors.push(`${rel}:${index + 1}: arbitrary utility value "[${match[1]}]" — use a token`);
}
}
});
}
const files = [join(webRoot, "index.html"), ...walk(join(webRoot, "src"))];
const sources = files.map((file) => ({
rel: relative(webRoot, file),
source: readFileSync(file, "utf8"),
}));
for (const { rel, source } of sources) {
if (rel.endsWith(".css")) {
checkCss(source, rel);
} else {
checkPlain(source, rel);
}
}
const defined = new Set();
for (const { source } of sources) {
for (const match of source.matchAll(/(--[\w-]+)\s*:/g)) {
defined.add(match[1]);
}
for (const match of source.matchAll(/setProperty\(\s*["'](--[\w-]+)["']/g)) {
defined.add(match[1]);
}
for (const match of source.matchAll(/["'](--[\w-]+)["']\s*:/g)) {
defined.add(match[1]);
}
}
for (const { rel, source } of sources) {
source.split("\n").forEach((line, index) => {
for (const match of line.matchAll(/var\(\s*(--[\w-]+)/g)) {
if (!defined.has(match[1])) {
errors.push(`${rel}:${index + 1}: unknown token ${match[1]} — nothing defines it`);
}
}
});
}
if (errors.length > 0) {
console.error("check-tokens: components must consume design tokens:\n");
for (const error of errors) {
console.error(` ${error}`);
}
process.exit(1);
}
console.log(`check-tokens: ${files.length} files clean`);