Files
novalon-website/scripts/check-visual-grammar.mjs
T
zhangxiang 81daedbea1 feat(tokens): 视觉语法收口到对标实测——圆角 0–4 记档、彩色阴影退役、卡片去 lift
依据是实测而非口味。Bain & Company(archive 快照 2026-08-31, 1600×846)与
Porsche Consulting(live 国际站)的 getComputedStyle 抽样收敛到同一条:
**两家全站 border-radius 均为 0**,且面/字色近乎单色
(Bain 字色仅 #000/#FFF/#CC0000/#767676;Porsche 面色 #FFF/#000/#D6001D/#F2F2F2,
红出现 4 次且全部是按钮底、无一次是阴影或背景)。本仓此前的「中度软化」
3→32px 八档 + 三枚品牌红阴影 + 卡片 hover 抬升,三件全是对标没有的语法。

本轮按「借语法、不借色相」执行:保留 #C41E3A 色相与朱砂条,只收口形状与层次。

圆角
- --radius-xs/sm 3/6→0、md/lg 8/12→2、xl/2xl/3xl 18/24/32→4,新增 --radius-cta: 0
- **--radius-full 保持 9999 不动**:它承载真圆(avatar/switch/slider/radio-group/
  progress/scroll-area/skeleton),一并归零会把所有旋钮与头像方角化。这条是
  check:grammar R2/R9 的正向守卫 —— 刻意做成「仪器坏了它仍要失败」的那一维
- --badge-radius 由 var(--radius-full) 改指 var(--radius-cta)(实测该令牌零消费者,
  留档不复用,删除动作留给死码族 DEC-P-2 统一处理)
- button.tsx 的 sm/default/lg/xl 走 rounded-cta,icon 档保持 rounded-full(功能形状)

彩色阴影
- --shadow-brand / --shadow-brand-hover / --shadow-glow 三枚退役(实测前两者仅 2 处、
  后者 0 处消费者),消费方回落中性档
- 同批发现并修掉一处暖化漏网:阴影基色仍是冷墨 rgba(10,14,20,α)=#0A0E14,
  而暖墨 #141210 早已落地 —— globals.css 16 处 + 业务 2 处。check:token-twins 抓不到它,
  因为阴影是字面量 rgba、没有 -rgb 孪生兄弟可对照

卡片
- .bain-card hover 去 translateY(-4px) 与阴影增长,改为 hairline→rule + 底色微移
- --card-shadow-hover / --card-transition 随之退役(前者仅 :hover 消费、后者零消费者)

新增信息线令牌 --color-border-rule #8A8377
hover 边框是「告诉用户这个可交互」的信息,按品牌 P4 三档拆分不能用界灰 #C3BDB1
(实测对卡底仅 1.78,不达非文本 3:1)。#8A8377 由我自己算:对白 3.75、对纸 #FBF9F5
3.57、对暗底 #141210 4.89 —— 两主题都过 3:1,且 -rgb 孪生已同步(44/44)。

动效
- 补 --transition-hover: 150ms 并接进 Tailwind duration 档。动效四原则 CONTEXT.md:76
  早就写了 hover 150ms,仓库从来没有这个档(BRAND-MANUAL §6 冲突 C-1)。
  抬升与光晕去掉后 hover 成了唯一的可交互提示,没档可用等于语法自相矛盾
- cta-button 的 transition-all duration-200(裸字面量)一并改为 transition-colors duration-hover

CTA 两轨(实测尺寸之间取值:Bain 20/32+14px、Porsche 13/24+16px → px-7 py-3.5 + text-sm/500)
- 实心/描边两轨都直角;不做 text-transform(中文无大小写)、不补字距(Bain 实测
  letterSpacing: normal,它的大写感来自全大写本身)
- 箭头只保留在 inline 文字链轨:两家按钮实测都是纯文字
- 描边轨静止边框用 border-border-rule,不用 ink/20(≈1.54 不达 3:1)
- 改动半径实测:63 处 <CTAButton> 调用,其中 36 处不写 variant ⇒ 落默认 primary,
  24 处 secondary、3 处 dark、0 处 inline

新闸 npm run check:grammar(9 条规则)+ check:grammar:selftest(9/9 双向自证)
- 闸只看代码:扫描前统一剥注释。不剥的话,解释「为什么退出 rounded-full」的文档注释
  本身会被判红,于是只剩两条出路 —— 改措辞去绕闸(应试,闸就此失去解释力)或把闸调瞎
- 每条规则报分母;分母为 0 ⇒ exit 2 判「未能度量」,不算通过
- 退出码分档 0/1/2,避免闸自身崩溃与判红共用 exit 1 而吞掉同批已算好的打印

顺带删死码 hero-section-v2.tsx(200 行、单一导出、全站零生产引用,仅被自己的 3 个测试
dynamic import)+ 那 3 个测试。留测试会让死码继续占覆盖率分母,并被误读成「有活在跑」。

KNOWN-RED: test:visual —— 全局令牌改动没有"爆炸半径"可言,页面级 130 张基线预期全部churn。
按计划 §10 只在 #3–#9 落地后一次性重捕(需 AUTH-VISUAL 单独授权),不按笔重写以免归因失效。

门禁实测:type-check EXIT=0 · check:grammar 9/9 · check:grammar:selftest 9/9 ·
check:token-twins 44/44 · check:contrast 44/44 · check:brand-token 0 违规 ·
check:motion 23→22(--transition-* 采集数 6→7,假红已消)· 全量 jest 143 套件 / 1769 例通过
2026-10-16 20:02:11 +08:00

265 lines
15 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env node
// 视觉语法闸:把「对标实测出来的语法」钉成机器判据。
//
// 为什么要有它(实测,非口味):
// Bain & Company(archive 快照 2026-08-31,1600×846)与 Porsche Consulting(live 国际站)
// 两家 getComputedStyle 抽样结果是同一条:**全站 border-radius 为 0**,且面/字色近乎单色
// (Bain 字色仅 #000/#FFF/#CC0000/#767676;Porsche 仅 #000/#FFF/#B6B5BA,面色 #FFF/#000/#D6001D/#F2F2F2)。
// 本仓此前是 --radius-xs..3xl = 3..32px + 三枚彩色阴影(--shadow-brand/-brand-hover/-glow)
// + .bain-card 的 translateY(-4px) hover 抬升 —— 即「软边 + 彩晕 + 抬升」三件全是对标没有的。
// 2026-06-29 的 ADR-0004 把「关键数字超大字号 + 品牌色」当成 Bain 心法,实测 Bain 的成果数字是
// 40px / 字重 500 / 纯黑,故该判据已被证伪;语法层由本闸接管。
//
// 判据设计上的两条自律:
// 1) --radius-full 必须**保持** 9999px。rounded-full 在本仓承载真圆(avatar/switch/slider/
// radio-group/progress/scroll-area/skeleton),把它一并归零会方角化所有旋钮与头像 ——
// 这是「语法收口」最容易犯的自伤,所以单独一条正向守卫。
// 2) 每条规则都报分母。**分母为 0 = 判据没有目标 = 未能度量(exit 2),不算通过。**
//
// 退出码分档(避免「闸自身崩溃」与「判红」共用 exit 1,那会吞掉同批已算好的打印):
// 0 成立 / 1 预期红(真违规)/ 2 未能度量(文件缺失、解析目标为 0)
import { readFileSync, existsSync, readdirSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
const CSS = path.join(ROOT, "src/app/globals.css");
// R4 管的「编辑类 CTA 表面」。button.tsx **不在**这里 —— 它的 icon 档与涟漪点是功能性的圆,
// 由 R9 双向管(文字档必须直角、icon 档必须保持圆)。
const CTA_SURFACES = [
"src/components/ui/cta-button.tsx",
"src/components/ui/badge.tsx",
];
const BUTTON_FILE = "src/components/ui/button.tsx";
// ---- 源码遍历(只用 node 内置,避开第三方)----
function walk(dir, out = []) {
let ents;
try { ents = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
for (const e of ents) {
if (e.name === "node_modules" || e.name === ".git" || e.name === "dist") continue;
const p = path.join(dir, e.name);
if (e.isDirectory()) walk(p, out);
else if (/\.(tsx?|css)$/.test(e.name)) out.push(p);
}
return out;
}
// ---- 剥注释 ----
// 必要性(本轮真实踩到):不剥的话,解释「为什么退出 rounded-full」的文档注释本身会被判红,
// 于是只剩两条出路 —— 要么改措辞去绕闸(应试,闸就此失去解释力),要么把闸调瞎。
// 正确做法是让闸只看代码。CSS 与 TS/TSX 各自的注释语法分别处理。
function stripComments(src, { line = false } = {}) {
// 块注释:整段替换成**等量换行**,否则后面的行号会集体上移,
// 闸报出来的 L### 就指不到真正的那一行(判据不可行动 = 半个假绿)。
let out = src.replace(/\/\*[\s\S]*?\*\//g, (m) => "\n".repeat((m.match(/\n/g) || []).length));
if (line) out = out.replace(/(^|[^:'"`\\])\/\/[^\n]*/g, "$1");
return out;
}
// ---- 解析 :root 里的 --radius-*(按 selector 块配对,同 check-token-twins 的教训:
// 跨块配对会把明暗两套主题误当成一对)----
function parseRadii(text) {
const lines = text.split("\n");
const blocks = [];
let cur = null;
for (let i = 0; i < lines.length; i++) {
const st = lines[i].trim();
if (st.endsWith("{") && !st.startsWith("@")) { cur = {}; blocks.push(cur); continue; }
if (st === "}") { cur = null; continue; }
if (!cur) continue;
const m = /^\s*(--radius-[a-z0-9]+)\s*:\s*([-\d.]+)(px|rem|em|%)?\s*;/.exec(lines[i]);
if (m) cur[m[1]] = { raw: `${m[2]}${m[3] || "px"}`, value: Number.parseFloat(m[2]), unit: m[3] || "px", line: i + 1 };
}
// :root 取第一个块(globals.css 的 :root 在最前)
const rootBlock = blocks.find((b) => Object.keys(b).some((k) => k.startsWith("--radius-"))) || {};
return { blocks: blocks.length, radii: rootBlock };
}
// ---- 规则实现 ----
const results = [];
function rule({ id, name, denominator, red, note }) {
results.push({ id, name, denominator, red, note });
}
function checkGrammar(rawText, rawFiles) {
// 闸只看代码:统一先剥注释,再交给各条规则
const text = stripComments(rawText);
const files = new Map([...rawFiles].map(([k, v]) => [k, stripComments(v, { line: true })]));
const { radii } = parseRadii(text);
const names = Object.keys(radii);
// R1 radius 记档:除 full / cta 外,一律 0–4px
const register = names.filter((n) => n !== "--radius-full" && n !== "--radius-cta");
const r1Red = [];
for (const n of register) {
const v = radii[n];
// rem/em/% 一律视为未收口(本仓 html{font-size} 随断点变 16/17/18,rem 圆角等于不可预测)
if (v.unit !== "px") r1Red.push(`${n} = ${v.raw} (L${v.line}) 非 px —— rem 圆角随断点漂移`);
else if (v.value > 4) r1Red.push(`${n} = ${v.raw} (L${v.line}) > 4px,超出 0–4 记档`);
}
rule({ id: "R1", name: "radius 记档 0–4px", denominator: register.length, red: r1Red });
// R2 --radius-full 必须活着且仍是真圆(正向守卫,防「一并归零」的自伤)
const full = radii["--radius-full"];
const r2Red = [];
if (!full) r2Red.push("--radius-full 不存在 —— 会方角化 avatar/switch/slider/radio/progress/scroll-area/skeleton");
else if (full.value < 9999) r2Red.push(`--radius-full = ${full.raw} < 9999px —— 真圆承载被破坏`);
rule({ id: "R2", name: "--radius-full 仍为真圆(负对照维度)", denominator: 1, red: r2Red });
// R3 --radius-cta 必须存在且为 0
const cta = radii["--radius-cta"];
const r3Red = [];
if (!cta) r3Red.push("--radius-cta 不存在 —— 两轨 CTA 无专用直角档");
else if (cta.value !== 0) r3Red.push(`--radius-cta = ${cta.raw} ≠ 0px —— CTA 未直角化`);
rule({ id: "R3", name: "--radius-cta 存在且为 0", denominator: 1, red: r3Red });
// R4 编辑类 CTA 表面不得再用 rounded-full(胶囊是本轮要退出的语法)
// 注意范围**只含** cta-button 与 badge:button.tsx 的 icon 档与涟漪点是「功能性的圆」,
// 由 R9 单独管,硬塞进 R4 会逼着把圆形控件也方角化(那正是 R2 要防的自伤)。
const r4Red = [];
let r4Den = 0;
for (const rel of CTA_SURFACES) {
const f = files.get(rel);
if (f === undefined) { r4Red.push(`${rel} 读不到 —— 判据失去目标`); continue; }
const hits = (f.match(/rounded-full/g) || []).length;
r4Den += 1;
if (hits > 0) r4Red.push(`${rel} 有 ${hits} 处 rounded-full(应走 rounded-cta)`);
}
rule({ id: "R4", name: "CTA/badge 表面零 rounded-full", denominator: r4Den, red: r4Red });
// R5 彩色阴影:令牌不得仍在 :root 里定义(对标两家的面全是无彩阴影或无阴影)
const colorShadowTokens = ["--shadow-brand", "--shadow-brand-hover", "--shadow-glow"]
.filter((t) => new RegExp(`^\\s*${t}\\s*:`, "m").test(text));
const r5Red = colorShadowTokens.map((t) => `${t} 仍定义于 globals.css —— 彩色阴影是对标没有的语法`);
rule({ id: "R5", name: "彩色阴影令牌已退役", denominator: 3, red: r5Red });
// R6 .bain-card:hover 不得有位移抬升(两家 hover 只改 hairline→rule,不 lift)
const cardHover = /\.bain-card:hover\s*\{([^}]*)\}/s.exec(text);
const r6Den = cardHover ? 1 : 0;
const r6Red = [];
if (!cardHover) r6Red.push("找不到 .bain-card:hover 块 —— 无法判定 lift 是否已去");
else if (/translate[3d]?Y|transform\s*:/.test(cardHover[1])) r6Red.push(".bain-card:hover 仍有 transform/translateY 抬升");
rule({ id: "R6", name: ".bain-card hover 无位移抬升", denominator: r6Den, red: r6Red });
// R7 弱口径防护:彩色阴影即使令牌删了,工具类引用也不能残留在业务代码
const r7Red = [];
let r7Den = 0;
for (const [rel, f] of files) {
if (rel === "src/app/globals.css") continue;
const hits = (f.match(/\bshadow-(brand-hover|brand|glow)\b/g) || []).length;
if (hits > 0) { r7Den += 1; r7Red.push(`${rel} 仍消费彩色阴影 ${hits} 处`); }
}
rule({ id: "R7", name: "业务代码零彩色阴影消费", denominator: r7Den, red: r7Red, note: "分母为「仍在消费的文件数」,0 = 已清零(成立),非「未度量」" });
// R8 组件级圆角令牌必须落进记档 —— R4 只扫工具类,会漏掉 --badge-radius: var(--radius-full)
// 这类「走令牌而不是走 class」的路径(本轮实测确实漏了 badge,故补此条)。
// 例外:--avatar-radius 承载真圆,必须指向 --radius-full。
const CIRCLE_TOKENS = new Set(["--avatar-radius"]);
const compTokens = [...text.matchAll(/^\s*(--[a-z0-9-]*(?:radius)[a-z0-9-]*)\s*:\s*([^;]+);/gm)]
.map((m) => ({ name: m[1], value: m[2].trim() }))
.filter((t) => t.name !== "--radius-xs" && !/^--radius-/.test(t.name));
const r8Red = [];
for (const t of compTokens) {
const ref = /var\(\s*(--radius-[a-z0-9]+)\s*\)/.exec(t.value);
const lit = /^[-\d.]+(px|rem|em|%)?$/.test(t.value) ? t.value : null;
if (ref) {
const target = ref[1];
if (CIRCLE_TOKENS.has(t.name)) {
if (target !== "--radius-full") r8Red.push(`${t.name} = var(${target}) —— 真圆承载被改走,应指回 --radius-full`);
} else if (target === "--radius-full") {
r8Red.push(`${t.name} = var(--radius-full) —— 胶囊语法未退出,应指 var(--radius-cta)`);
}
} else if (lit && /px$/.test(lit) && Number.parseFloat(lit) > 4 && !CIRCLE_TOKENS.has(t.name)) {
r8Red.push(`${t.name} = ${lit} > 4px,超出记档`);
} else if (!ref && !lit) {
r8Red.push(`${t.name} = "${t.value}" —— 既非记档字面量也非 var() 引用,无法判定`);
}
}
rule({ id: "R8", name: "组件级圆角令牌落进记档(补 R4 的令牌路径盲区)", denominator: compTokens.length, red: r8Red });
// R9 button.tsx 尺寸档:文字按钮走 rounded-cta,icon 档**必须**保持 rounded-full。
// 这一条同时是正例与反例:文字档出现胶囊 ⇒ 判红;icon 档被一起归零 ⇒ 也判红
// (圆形图标钮是功能形状,与 avatar/开关钮同类,不该被"语法收口"顺手带走)。
const btn = files.get(BUTTON_FILE);
const r9Red = [];
let r9Den = 0;
if (btn === undefined) {
r9Red.push(`${BUTTON_FILE} 读不到 —— 判据失去目标`);
} else {
const sizeBlock = /size:\s*\{([\s\S]*?)\n\s*\},/.exec(btn);
if (!sizeBlock) {
r9Red.push("找不到 button.tsx 的 size 变体块 —— 无法判定,不算通过");
} else {
const body = sizeBlock[1];
for (const key of ["sm", "default", "lg", "xl"]) {
const m = new RegExp(`^\\s*${key}:\\s*'([^']*)'`, "m").exec(body);
if (!m) { r9Red.push(`size.${key} 未找到 —— 判据失去目标`); continue; }
r9Den += 1;
if (/rounded-full/.test(m[1])) r9Red.push(`size.${key} 仍是 rounded-full(应走 rounded-cta):${m[1]}`);
else if (!/rounded-cta/.test(m[1])) r9Red.push(`size.${key} 未声明 rounded-cta:${m[1]}`);
}
const icon = /^\s*icon:\s*'([^']*)'/m.exec(body);
if (!icon) r9Red.push("size.icon 未找到 —— 无法确认圆形控件未被方角化");
else {
r9Den += 1;
if (!/rounded-full/.test(icon[1])) r9Red.push(`size.icon 丢了 rounded-full —— 圆形图标钮被方角化(功能形状,非装饰圆角):${icon[1]}`);
}
}
}
rule({ id: "R9", name: "按钮尺寸档直角、icon 档保持圆(双向)", denominator: r9Den, red: r9Red });
return results;
}
// ---- 自证(负例):喂一批明知违规的样本,不判红就宣布上面全部不作数 ----
function selftest() {
const bad = `:root {\n --radius-xs: 3px;\n --radius-sm: 6px;\n --radius-full: 0px;\n --shadow-brand: 0 6px 24px rgba(196,30,58,.22);\n --badge-radius: var(--radius-full);\n}\n.bain-card:hover { transform: translateY(-4px); }\n`;
const files = new Map([
["src/app/globals.css", bad],
["src/components/ui/cta-button.tsx", 'className="rounded-full"'],
// R9 双向都要被抓到:文字档仍是胶囊 **且** icon 档被方角化
["src/components/ui/button.tsx", "shadow-brand\n size: {\n sm: 'h-9 rounded-full px-3',\n default: 'h-11 rounded-full px-5',\n lg: 'h-12 rounded-cta px-6',\n xl: 'h-14 rounded-cta px-8',\n icon: 'h-11 w-11 rounded-cta',\n },"],
["src/components/ui/badge.tsx", 'className="rounded-full"'],
["src/app/(marketing)/x.tsx", 'className="shadow-brand-hover"'],
]);
const r = checkGrammar(bad, files);
const redIds = r.filter((x) => x.red.length > 0).map((x) => x.id);
const expect = ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9"];
const missing = expect.filter((id) => !redIds.includes(id));
console.log("自证(负例必须全部被抓红):");
console.log(` 被抓红 ${redIds.join(",") || "(无)"}`);
if (missing.length) {
console.log(` ✗ 未被抓到:${missing.join(",")} ⇒ 这些规则没有约束力,上面所有绿灯都不作数`);
return 1;
}
console.log(` ✓ ${expect.length}/${expect.length} 条规则对已知违规均判红`);
return 0;
}
function main() {
if (process.argv.includes("--selftest")) process.exit(selftest());
if (!existsSync(CSS)) { console.log(`未能度量:${CSS} 不存在`); process.exit(2); }
const text = readFileSync(CSS, "utf8");
const files = new Map();
for (const p of walk(path.join(ROOT, "src"))) files.set(path.relative(ROOT, p), readFileSync(p, "utf8"));
const r = checkGrammar(text, files);
const unmeasurable = r.filter((x) => x.denominator === 0 && x.id !== "R7");
const red = r.filter((x) => x.red.length > 0);
console.log("视觉语法对账(Bain 2026-08-31 快照 + Porsche live 实测语法)");
for (const x of r) console.log(` ${x.red.length ? "✗" : "✓"} ${x.id} ${x.name}|分母 ${x.denominator}|违规 ${x.red.length}${x.note ? `|${x.note}` : ""}`);
if (unmeasurable.length) {
console.log(`\n未能度量:${unmeasurable.map((x) => x.id).join(",")} 分母为 0 —— 判据没有目标,不算通过`);
process.exit(2);
}
for (const x of red) for (const m of x.red) console.log(" ✗ " + x.id + " " + m);
if (red.length) { console.log(`\n不成立:${red.length} 条规则违规`); process.exit(1); }
console.log(`\n成立:${r.length}/${r.length} 条语法判据通过`);
}
main();