문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다.
"var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가
0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다.
그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰
사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가
없었다(12-02).
고른 방법:
- 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다.
입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와
순서는 그대로다.
- 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야
한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙
대로 대소문자를 구분한다.
- 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe
B5 우회, B12 오탐).
- oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS
키워드는 대소문자를 구분하지 않는다.
- ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다.
버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별
검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고,
순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의
--fixture 모드와 산출물 스키마는 바꾸지 않았다.
위험·한계:
- 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로
본다. 지금 CSS에는 없다.
- 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의,
outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg,
알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지
않는다.
- 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로
"기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다.
검증:
- RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts
11개 중 5개 실패. "does not count a longer token that starts with the
same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다.
나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석
안 독자.
- 고친 검사를 앞 커밋 전 CSS(402e1db)에 돌리면 "component token
--field-border is defined but no style reads it"으로 실패했다.
- GREEN: 같은 파일 11/11 통과. tests/unit 166파일 2364개 통과.
- 변이: 대비 기준 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건
통과로 바꾸면 규칙마다 실패 테스트가 하나 이상 깨졌다(7/11 실패).
- check:design-system PASS, --fixture는 기대대로 실패. tsc(app, node,
test) 통과, 바꾼 파일 eslint 통과, verify-documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01, 12-02
175 lines
6.0 KiB
TypeScript
175 lines
6.0 KiB
TypeScript
import { mkdir, readFile, readdir } from "node:fs/promises";
|
|
|
|
import { designSystemReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
|
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
|
import path from "node:path";
|
|
|
|
import { REQUIRED_COMPONENT_TOKENS, REQUIRED_PRIMITIVE_TOKENS, REQUIRED_SEMANTIC_TOKENS } from "../src/presentation/design-system/tokens/token-contract.ts";
|
|
import {
|
|
firstFontFamilyFailures,
|
|
focusContrastFailures,
|
|
hueMixFailures,
|
|
unreadTokenFailures,
|
|
} from "./lib/design-system-rules.ts";
|
|
import { readCustomProperties } from "./lib/oklch-contrast.ts";
|
|
|
|
const fixtureMode = process.argv.includes("--fixture");
|
|
const failures: string[] = [];
|
|
const tokenFiles = {
|
|
primitive: "src/presentation/design-system/tokens/primitive.css",
|
|
semantic: "src/presentation/design-system/tokens/semantic.css",
|
|
component: "src/presentation/design-system/tokens/component.css",
|
|
};
|
|
const tokenLayers: Array<readonly [string, string, readonly string[]]> = [
|
|
["primitive", tokenFiles.primitive, REQUIRED_PRIMITIVE_TOKENS],
|
|
["semantic", tokenFiles.semantic, REQUIRED_SEMANTIC_TOKENS],
|
|
["component", tokenFiles.component, REQUIRED_COMPONENT_TOKENS],
|
|
];
|
|
|
|
for (const [layer, file, tokens] of tokenLayers) {
|
|
const source = await readFile(file, "utf8");
|
|
for (const token of tokens) {
|
|
if (!source.includes(`${token}:`)) {
|
|
failures.push(`${layer} token is missing: ${token}`);
|
|
}
|
|
}
|
|
}
|
|
|
|
// theme.css only imports the files under styles/theme/, so check them all.
|
|
const styleFiles = (
|
|
await readdir("src/presentation/styles", { recursive: true })
|
|
)
|
|
.filter((file) => file.endsWith(".css"))
|
|
.map((file) => path.join("src/presentation/styles", file));
|
|
const cssSources = await Promise.all(
|
|
[...Object.values(tokenFiles), ...styleFiles].map(
|
|
async (file) => ({ file, source: await readFile(file, "utf8") }),
|
|
),
|
|
);
|
|
const definitions = new Set(
|
|
cssSources.flatMap(({ source }) =>
|
|
[...source.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1]),
|
|
),
|
|
);
|
|
for (const { file, source } of cssSources) {
|
|
for (const match of source.matchAll(/var\((--[a-z0-9-]+)/g)) {
|
|
if (!definitions.has(match[1])) {
|
|
failures.push(`${file} uses undefined token ${match[1]}`);
|
|
}
|
|
}
|
|
failures.push(...hueMixFailures({ file, source }));
|
|
}
|
|
|
|
const semanticSource = await readFile(tokenFiles.semantic, "utf8");
|
|
const darkSource =
|
|
semanticSource.match(/:root\[data-theme="dark"\]\s*\{([\s\S]*?)\n\}/)?.[1] ??
|
|
"";
|
|
for (const token of [
|
|
"--color-surface",
|
|
"--color-surface-muted",
|
|
"--color-surface-elevated",
|
|
"--color-content",
|
|
"--color-content-muted",
|
|
"--color-content-inverse",
|
|
"--color-border",
|
|
"--color-border-strong",
|
|
"--color-action",
|
|
"--color-action-hover",
|
|
"--color-action-pressed",
|
|
"--color-danger",
|
|
"--color-focus",
|
|
"--color-disabled-content",
|
|
"--color-disabled-surface",
|
|
]) {
|
|
if (!darkSource.includes(`${token}:`)) {
|
|
failures.push(`dark theme token is missing: ${token}`);
|
|
}
|
|
}
|
|
const lightProperties = new Map([
|
|
...readCustomProperties(await readFile(tokenFiles.primitive, "utf8")),
|
|
...readCustomProperties(semanticSource.split(':root[data-theme="dark"]')[0]),
|
|
]);
|
|
const darkProperties = new Map([
|
|
...lightProperties,
|
|
...readCustomProperties(darkSource),
|
|
]);
|
|
// Rule texts and reasons: scripts/lib/design-system-rules.ts.
|
|
failures.push(
|
|
...focusContrastFailures("light", lightProperties),
|
|
...focusContrastFailures("dark", darkProperties),
|
|
...unreadTokenFailures(
|
|
REQUIRED_COMPONENT_TOKENS,
|
|
cssSources.filter(({ file }) => file !== tokenFiles.component),
|
|
),
|
|
...firstFontFamilyFailures(lightProperties.get("--font-sans") ?? "", cssSources),
|
|
);
|
|
|
|
const componentSource = await readFile(tokenFiles.component, "utf8");
|
|
if (!componentSource.includes("@media (forced-colors: active)")) {
|
|
failures.push("forced-colors token fallback is missing");
|
|
}
|
|
|
|
async function listSourceFiles(directory: string): Promise<string[]> {
|
|
const result: string[] = [];
|
|
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
|
const target = path.join(directory, entry.name);
|
|
if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
|
|
else if (/\.(?:ts|tsx|mts|cts)$/.test(entry.name)) result.push(target);
|
|
}
|
|
return result;
|
|
}
|
|
|
|
const sources = fixtureMode
|
|
? await listSourceFiles("tests/fixtures/design-system/forbidden")
|
|
: await listSourceFiles("src");
|
|
for (const file of sources) {
|
|
const source = await readFile(file, "utf8");
|
|
// Icon vendor and design-system deep imports are graph rules in
|
|
// .dependency-cruiser.json (check:architecture), which also sees relative,
|
|
// dynamic and type imports (12-08, 12-10).
|
|
if (
|
|
/from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
|
|
) {
|
|
failures.push(`direct headless vendor import in ${file}`);
|
|
}
|
|
if (
|
|
!file.includes("src/presentation/design-system/tokens/") &&
|
|
/(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source)
|
|
) {
|
|
failures.push(`raw palette value in ${file}`);
|
|
}
|
|
if (
|
|
file.includes("tests/fixtures/design-system/forbidden") &&
|
|
source.includes("TOOLTIP_ONLY_REQUIRED_INFORMATION")
|
|
) {
|
|
failures.push(`tooltip-only required information in ${file}`);
|
|
}
|
|
}
|
|
|
|
const report = designSystemReportArtifactSchema.parse({
|
|
schemaVersion: 1,
|
|
mode: fixtureMode ? "negative-fixture" : "source",
|
|
checkedTokenCount:
|
|
REQUIRED_PRIMITIVE_TOKENS.length +
|
|
REQUIRED_SEMANTIC_TOKENS.length +
|
|
REQUIRED_COMPONENT_TOKENS.length,
|
|
failures,
|
|
passed: failures.length === 0,
|
|
});
|
|
await mkdir("artifacts/quality", { recursive: true });
|
|
await writeValidatedJsonArtifact({
|
|
path: fixtureMode
|
|
? "artifacts/quality/design-system-fixture.json"
|
|
: "artifacts/quality/design-system.json",
|
|
schema: designSystemReportArtifactSchema,
|
|
value: report,
|
|
});
|
|
|
|
if (failures.length > 0) {
|
|
process.stderr.write(`Design system contract failed:\n${failures.join("\n")}\n`);
|
|
process.exit(1);
|
|
}
|
|
process.stdout.write(
|
|
`Design system contract: ${report.checkedTokenCount} tokens and headless vendor boundary PASS\n`,
|
|
);
|