fix(design-system): 디자인 검사가 기능 CSS·gradient·인라인 style의 날 값을 잡는다
`check:design-system`이 잡지 못하는 길이 다섯 남았다(1101/12-03, 지금 위반
없음). gradient의 색상각 보간(`linear-gradient(in oklch, …)`)은 UI-02가
`color-mix`만 봐서 지난다. TSX 인라인 `color-mix`도 그렇다. 기능 폴더의 CSS는
아예 읽지 않는다. style sheet에서 `:root`로 토큰을 다시 정의해도, focus ring을
`outline-offset: 0`으로 그려 UI-01의 대비 계산 밖으로 내보내도 지난다. 그리고
primitive의 `className`·`style`이 범위 없이 열려 있어 화면이 primitive 위에
`style={{ color: "red", padding: 13 }}`을 얹어도 막는 것이 없다(04-14).
고른 방법: UI-02 정규식이 gradient의 색 공간까지 보고 TS·TSX 소스에도 돈다.
토큰 파일 밖 CSS는 `src/` 아래 전부를 읽고, 날 색·토큰 재정의·offset 0
focus ring을 거절한다. 04-14는 결정(2026-11-12, 총괄: 공개 props는 두고
검사를 더한다)대로 TSX `style={{ … }}`의 손 색(키워드·`var()` 말고)과 손
간격·글자·반경·층·그림자 값을 거절한다. `className`·`style`의 범위(배치용)를
`docs/styling/design-tokens.md`에 적고, fe-design-system 스킬의 「검사가 안
보는 것」 문장을 새 범위에 맞췄다. 거절 fixture `raw-inline-style.tsx`를
더했다. 버린 대안: primitive 공개 props에서 `style`을 빼기(배럴 표면 BREAKING).
위험·한계: 다운스트림이 기능 CSS나 인라인 style에 날 값을 두었으면 다음
동기화에서 그 줄이 이름과 함께 실패한다. 문자열로 조립한 class와 Tailwind
임의 값은 여전히 보지 않는다.
검증: 규칙 단위 시험, check-design-system 연결 시험(기능 폴더 probe CSS),
`check:design-system:fixture`(FE-GATE-029)는 desktop에서 돌려 PR 본문에 적는다.
Refs: 1101/12-03, 1112/04-14
This commit is contained in:
@@ -30,7 +30,7 @@ paths:
|
||||
|
||||
## 함정
|
||||
|
||||
1. `check:design-system`이 통과했으니 토큰만 썼다고 본다. 날 색 검사는 `src`의 TS·TSX에서 `#hex`·`oklch(`·`rgb(`만 찾는다. `hsl()`, 색 이름(`red`), 날 px 간격은 안 본다. 토큰 파일 밖 CSS(`src/presentation/styles/**`)는 없는 토큰 참조와 혼합 색 공간만 보고 날 색은 안 본다. 기능 폴더 CSS는 아예 안 본다. 리뷰가 잡는다. — `scripts/check-design-system.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 4.1절 「토큰 CSS 검사 규칙」
|
||||
1. `check:design-system`이 통과했으니 토큰만 썼다고 본다. TS·TSX에서는 `#hex`·`oklch(`·`rgb(`와 `style={{ … }}`의 손 색·간격만 찾는다. 문자열로 조립한 class, Tailwind 임의 값(`text-[…]`), `hsl()`·색 이름을 담은 다른 문자열은 안 본다. CSS는 `src` 아래 전부를 보고 UI-06이 간격·글자·반경·층·그림자의 날 값을 거절하지만, 너비·높이·위치·opacity는 보지 않는다. 리뷰가 잡는다. — `scripts/check-design-system.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 4.1절 「토큰 CSS 검사 규칙」
|
||||
2. tooltip에만 필요한 정보를 둔다. 검사기의 tooltip 규칙은 음성 fixture에서만 돌고 실제 소스는 보지 않는다. — `scripts/check-design-system.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 6.1절 10번
|
||||
3. 포커스 대비 토큰을 `color-mix()`·알파·키워드로 만든다. 3:1 계산은 불투명한 `oklch()`로 끝나는 토큰만 하고 나머지는 실패한다. `color-mix()`는 `in oklab`만 쓴다. — `docs/styling/design-tokens.md` UI-01·UI-02
|
||||
4. 다크 테마 재정의를 빠뜨리거나 light 전용 패널·글자색을 박는다. 핵심 역할 토큰은 `:root[data-theme="dark"]`에 모두 있어야 하고, `component.css`에 forced-colors 대체가 있어야 한다. — `docs/styling/design-tokens.md`, `scripts/check-design-system.ts`
|
||||
|
||||
@@ -44,7 +44,14 @@ component별 값에 연결한다.
|
||||
같은 검사는 다음도 요구한다: `token-contract.ts`의 토큰 이름, 핵심 semantic
|
||||
역할의 어두운 테마 덮어쓰기, `component.css`의 forced-colors fallback, 토큰 파일
|
||||
밖에서 가공하지 않은 팔레트 값을 쓰지 않을 것, headless 라이브러리를 직접
|
||||
import하지 않을 것.
|
||||
import하지 않을 것. 토큰 파일 밖의 CSS는 `src/` 아래 전부(기능 폴더 포함)를 보고,
|
||||
날 색을 쓰거나 토큰을 다시 정의하거나 focus ring을 `outline-offset: 0`으로
|
||||
그리면 실패한다. gradient의 색 공간도 UI-02를 따른다.
|
||||
|
||||
primitive의 `className`·`style`은 배치용이다: 그리드 위치, 바깥 여백, 너비 같은
|
||||
것. 색과 간격·글자·반경·층·그림자는 variant와 토큰으로 정한다. TSX의
|
||||
`style={{ … }}`에 이런 값을 손으로 쓰면 검사가 실패한다(`var(--…)`를 읽는 것은
|
||||
된다).
|
||||
|
||||
## 테마 계약
|
||||
|
||||
|
||||
@@ -16,7 +16,11 @@ import {
|
||||
focusContrastFailures,
|
||||
hueMixFailures,
|
||||
rawSemanticColourFailures,
|
||||
focusOffsetFailures,
|
||||
inlineStyleFailures,
|
||||
rawStyleValueFailures,
|
||||
styleSheetColourFailures,
|
||||
tokenRedefinitionFailures,
|
||||
undeclaredComponentTokenFailures,
|
||||
unreadTokenFailures,
|
||||
} from "./lib/design-system-rules.ts";
|
||||
@@ -44,12 +48,14 @@ for (const [layer, file, tokens] of tokenLayers) {
|
||||
}
|
||||
}
|
||||
|
||||
// theme.css only imports the files under styles/theme/, so check them all.
|
||||
const styleFiles = (
|
||||
await readdir("src/presentation/styles", { recursive: true })
|
||||
)
|
||||
// Every style sheet under src/, not only the ones theme.css imports: a
|
||||
// feature's own CSS is a style sheet too (1101/12-03).
|
||||
const tokenFileSet = new Set<string>(Object.values(tokenFiles));
|
||||
const styleFiles = (await readdir("src", { recursive: true }))
|
||||
.filter((file) => file.endsWith(".css"))
|
||||
.map((file) => path.join("src/presentation/styles", file));
|
||||
.map((file) => path.join("src", file))
|
||||
.filter((file) => !tokenFileSet.has(file))
|
||||
.sort();
|
||||
const cssSources = await Promise.all(
|
||||
[...Object.values(tokenFiles), ...styleFiles].map(
|
||||
async (file) => ({ file, source: await readFile(file, "utf8") }),
|
||||
@@ -67,7 +73,21 @@ for (const { file, source } of cssSources) {
|
||||
}
|
||||
}
|
||||
failures.push(...hueMixFailures({ file, source }));
|
||||
if (styleFiles.includes(file)) failures.push(...rawStyleValueFailures({ file, source }));
|
||||
if (!tokenFileSet.has(file)) {
|
||||
failures.push(
|
||||
...rawStyleValueFailures({ file, source }),
|
||||
...styleSheetColourFailures({ file, source }),
|
||||
...focusOffsetFailures({ file, source }),
|
||||
);
|
||||
}
|
||||
}
|
||||
const tokenNames = new Set(
|
||||
cssSources
|
||||
.filter(({ file }) => tokenFileSet.has(file))
|
||||
.flatMap(({ source }) => [...source.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1])),
|
||||
);
|
||||
for (const { file, source } of cssSources) {
|
||||
if (!tokenFileSet.has(file)) failures.push(...tokenRedefinitionFailures({ file, source }, tokenNames));
|
||||
}
|
||||
|
||||
const semanticSource = await readFile(tokenFiles.semantic, "utf8");
|
||||
@@ -166,6 +186,7 @@ for (const file of sources) {
|
||||
) {
|
||||
failures.push(`raw palette value in ${file}`);
|
||||
}
|
||||
failures.push(...hueMixFailures({ file, source }), ...inlineStyleFailures({ file, source }));
|
||||
if (
|
||||
file.includes("tests/fixtures/design-system/forbidden") &&
|
||||
source.includes("TOOLTIP_ONLY_REQUIRED_INFORMATION")
|
||||
|
||||
@@ -64,10 +64,13 @@ export function focusContrastFailures(
|
||||
// stop such as oklch(1 0 0) carries hue 0: 14% blue into white came out
|
||||
// pink. oklab mixes on straight lines and has no hue to drag. CSS
|
||||
// function names and keywords ignore ASCII case, so OKLCH counts too.
|
||||
// A gradient interpolates the same way (`linear-gradient(90deg in oklch,
|
||||
// …)`), and an inline style in TSX is CSS too (1101/12-03).
|
||||
const HUE_MIX =
|
||||
/(?:color-mix\(\s*|(?:repeating-)?(?:linear|radial|conic)-gradient\([^,()]*?)\bin\s+(oklch|lch|hsl|hwb)\b/gi;
|
||||
|
||||
export function hueMixFailures({ file, source }: CssSource): string[] {
|
||||
const mixes = withoutComments(source).matchAll(
|
||||
/color-mix\(\s*in\s+(oklch|lch|hsl|hwb)\b/gi,
|
||||
);
|
||||
const mixes = withoutComments(source).matchAll(HUE_MIX);
|
||||
return [...mixes].map((match) => `${file} mixes colours in ${match[1]}; use oklab`);
|
||||
}
|
||||
|
||||
@@ -203,3 +206,65 @@ export function rawStyleValueFailures({ file, source }: CssSource): string[] {
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
// Outside the token files a style reads colours, it does not define them.
|
||||
// 1101/12-03: a raw colour in a feature's own CSS, a token redefined under
|
||||
// :root in a style sheet (the token file then no longer decides it), and a
|
||||
// focus ring drawn with no offset (UI-01 measures the ring against the
|
||||
// surface around the control, not against the control) all passed.
|
||||
export function styleSheetColourFailures({ file, source }: CssSource): string[] {
|
||||
return [...withoutComments(source).matchAll(/(?<![\w-])([a-z-]+)\s*:\s*([^;{}]+);/g)]
|
||||
.filter((match) => !match[1].startsWith("--") && RAW_COLOUR.test(match[2]))
|
||||
.map((match) => `${file} ${match[1]}: ${match[2].trim()} is a raw colour; read a colour token`);
|
||||
}
|
||||
|
||||
export function tokenRedefinitionFailures(
|
||||
{ file, source }: CssSource,
|
||||
tokens: ReadonlySet<string>,
|
||||
): string[] {
|
||||
return [...withoutComments(source).matchAll(/(?<![\w-])(--[a-z0-9-]+)\s*:/g)]
|
||||
.filter((match) => tokens.has(match[1]))
|
||||
.map((match) => `${file} redefines the token ${match[1]}; change it in the token files`);
|
||||
}
|
||||
|
||||
export function focusOffsetFailures({ file, source }: CssSource): string[] {
|
||||
return [...withoutComments(source).matchAll(/outline-offset\s*:\s*([^;{}]+);/g)]
|
||||
.filter((match) => /^(?:-|0(?:\.0*)?(?:px|rem|em)?\s*$)/.test(match[1].trim()))
|
||||
.map(
|
||||
(match) =>
|
||||
`${file} outline-offset: ${match[1].trim()} draws the focus ring on the control; UI-01 measures it against the surface around the control`,
|
||||
);
|
||||
}
|
||||
|
||||
// 1112/04-14 (decision 2026-11-12). Primitives keep `className` and `style`
|
||||
// open, so a screen can lay a raw colour or spacing over a primitive. An
|
||||
// inline style may place things and read tokens; a colour or a spacing,
|
||||
// type, radius, layer or shadow value written by hand is refused.
|
||||
// The scale values are judged as UI-06 judges a style sheet: an inline
|
||||
// style is the same declaration written in camelCase, and React writes a bare
|
||||
// number as px except for the unitless properties.
|
||||
const INLINE_COLOUR_KEYWORDS = new Set(["transparent", "currentcolor", "inherit", "initial", "unset", "none"]);
|
||||
const INLINE_COLOUR_PROPERTY = /^(?:color|background|fill|stroke)$|Color$/;
|
||||
const INLINE_UNITLESS = new Set(["zIndex", "fontWeight", "lineHeight", "opacity", "flex", "flexGrow", "flexShrink", "order"]);
|
||||
|
||||
export function inlineStyleFailures({ file, source }: CssSource): string[] {
|
||||
const failures: string[] = [];
|
||||
for (const style of source.matchAll(/style=\{\{([\s\S]*?)\}\}/g)) {
|
||||
for (const entry of style[1].matchAll(/([A-Za-z]+)\s*:\s*(`[^`]*`|"[^"]*"|'[^']*'|-?[\d.]+)/g)) {
|
||||
const [, property, written] = entry;
|
||||
const value = written.replace(/^[`"']|[`"']$/g, "").trim();
|
||||
const colour =
|
||||
INLINE_COLOUR_PROPERTY.test(property) &&
|
||||
!/^var\(/.test(value) &&
|
||||
!INLINE_COLOUR_KEYWORDS.has(value.toLowerCase());
|
||||
const css =
|
||||
/^-?[\d.]+$/.test(written) && !INLINE_UNITLESS.has(property) && Number(value) !== 0 ? `${value}px` : value;
|
||||
const scale =
|
||||
handWrittenValues(property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`), css).length > 0;
|
||||
if (colour || scale) {
|
||||
failures.push(`${file} style ${property}: ${written} is written by hand; read a token or use a primitive variant`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
// 1112/04-14. A screen lays a raw colour and spacing over an element.
|
||||
export function RawInlineStyle() {
|
||||
return <div style={{ color: "red", padding: 13 }}>raw inline style</div>;
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
@@ -9,9 +9,13 @@ import {
|
||||
FOCUS_RING_BACKGROUNDS,
|
||||
firstFontFamilyFailures,
|
||||
focusContrastFailures,
|
||||
focusOffsetFailures,
|
||||
hueMixFailures,
|
||||
inlineStyleFailures,
|
||||
rawSemanticColourFailures,
|
||||
rawStyleValueFailures,
|
||||
styleSheetColourFailures,
|
||||
tokenRedefinitionFailures,
|
||||
undeclaredComponentTokenFailures,
|
||||
unreadTokenFailures,
|
||||
} from "../../scripts/lib/design-system-rules.ts";
|
||||
@@ -77,6 +81,22 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => {
|
||||
]);
|
||||
});
|
||||
|
||||
// 1101/12-03. A gradient interpolates in its colour space too.
|
||||
it.each([
|
||||
"linear-gradient(in oklch, red, blue)",
|
||||
"linear-gradient(90deg in hsl, red, blue)",
|
||||
"radial-gradient(circle in lch, red, blue)",
|
||||
"repeating-conic-gradient(from 0deg in hwb, red, blue)",
|
||||
])("fails %s", (gradient) => {
|
||||
expect(hueMixFailures(css(`a { background: ${gradient}; }`))).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("passes a gradient in oklab or without a colour space", () => {
|
||||
expect(
|
||||
hueMixFailures(css("a { background: linear-gradient(90deg in oklab, red, blue), linear-gradient(red, blue); }")),
|
||||
).toEqual([]);
|
||||
});
|
||||
|
||||
it("passes oklab, and old code left in a comment", () => {
|
||||
expect(
|
||||
hueMixFailures(
|
||||
@@ -228,6 +248,74 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => {
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/12-03. Style sheets read colours; the token files define them.
|
||||
describe("style sheets outside the token files", () => {
|
||||
it("fails a raw colour, and passes a token read or a mix of tokens", () => {
|
||||
expect(
|
||||
styleSheetColourFailures(css(".a { color: #ff0000; border-color: rgb(1 2 3); }\n.b { color: var(--color-content); background: color-mix(in oklab, var(--color-panel) 92%, transparent); }")),
|
||||
).toEqual([
|
||||
"probe.css color: #ff0000 is a raw colour; read a colour token",
|
||||
"probe.css border-color: rgb(1 2 3) is a raw colour; read a colour token",
|
||||
]);
|
||||
});
|
||||
|
||||
it("fails a token redefined in a style sheet, and passes a local property", () => {
|
||||
expect(
|
||||
tokenRedefinitionFailures(css(":root { --font-sans: serif; }\n.a { --local-gap: 1px; }"), new Set(["--font-sans"])),
|
||||
).toEqual(["probe.css redefines the token --font-sans; change it in the token files"]);
|
||||
});
|
||||
|
||||
it.each(["0", "0px", "-1px"])("fails a focus ring drawn with outline-offset %s", (offset) => {
|
||||
expect(focusOffsetFailures(css(`.a:focus-visible { outline-offset: ${offset}; }`))).toEqual([
|
||||
`probe.css outline-offset: ${offset} draws the focus ring on the control; UI-01 measures it against the surface around the control`,
|
||||
]);
|
||||
});
|
||||
|
||||
it("passes a focus ring drawn away from the control", () => {
|
||||
expect(focusOffsetFailures(css(".a:focus-visible { outline-offset: 0.1875rem; }"))).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// 1112/04-14. Primitives keep className and style open (decision
|
||||
// 2026-11-12); the check refuses raw values laid over them.
|
||||
describe("inline styles in TSX", () => {
|
||||
it("fails a colour or a scale value written by hand", () => {
|
||||
expect(
|
||||
inlineStyleFailures({
|
||||
file: "probe.tsx",
|
||||
source: `<Button style={{ color: "red", padding: 13, borderRadius: "4px", zIndex: 5 }} />`,
|
||||
}),
|
||||
).toEqual([
|
||||
'probe.tsx style color: "red" is written by hand; read a token or use a primitive variant',
|
||||
"probe.tsx style padding: 13 is written by hand; read a token or use a primitive variant",
|
||||
'probe.tsx style borderRadius: "4px" is written by hand; read a token or use a primitive variant',
|
||||
"probe.tsx style zIndex: 5 is written by hand; read a token or use a primitive variant",
|
||||
]);
|
||||
});
|
||||
|
||||
it("judges the scale values as UI-06 does, and every colour property", () => {
|
||||
expect(
|
||||
inlineStyleFailures({
|
||||
file: "probe.tsx",
|
||||
source: `<div style={{ margin: "0 auto", zIndex: -1, lineHeight: 1, borderTopColor: "red", fontWeight: 700 }} />`,
|
||||
}),
|
||||
).toEqual([
|
||||
'probe.tsx style borderTopColor: "red" is written by hand; read a token or use a primitive variant',
|
||||
"probe.tsx style fontWeight: 700 is written by hand; read a token or use a primitive variant",
|
||||
]);
|
||||
});
|
||||
|
||||
it("passes token reads, keywords, zero and layout", () => {
|
||||
expect(
|
||||
inlineStyleFailures({
|
||||
file: "probe.tsx",
|
||||
source:
|
||||
"<div style={{ backgroundColor: `var(${token})`, color: \"currentColor\", margin: 0, padding: \"var(--space-2)\", gridColumn: \"1 / 3\", width: 120 }} />",
|
||||
}),
|
||||
).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("UI-05 first font family", () => {
|
||||
it("fails a named font that nothing loads", () => {
|
||||
expect(firstFontFamilyFailures("Inter, system-ui, sans-serif", [])).toEqual([
|
||||
@@ -295,6 +383,17 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => {
|
||||
path.join(root, "src/presentation/styles/theme/probe.css"),
|
||||
".probe { color: color-mix(in oklch, red, blue); }\n",
|
||||
);
|
||||
await mkdir(path.join(root, "src/features/probe"), { recursive: true });
|
||||
await writeFile(
|
||||
path.join(root, "src/features/probe/probe.css"),
|
||||
[
|
||||
".probe-a { color: #ff0000; }",
|
||||
".probe-b { background: linear-gradient(in oklch, var(--color-action), var(--color-panel)); }",
|
||||
".probe-c:focus-visible { outline-offset: 0; }",
|
||||
":root { --font-sans: serif; }",
|
||||
"",
|
||||
].join("\n"),
|
||||
);
|
||||
|
||||
const result = spawnSync(process.execPath, [path.resolve("scripts/check-design-system.ts")], {
|
||||
cwd: root,
|
||||
@@ -311,6 +410,10 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => {
|
||||
/^--font-sans starts with "Inter", which is neither a generic family, loaded by @font-face, nor listed in PRODUCT_LOADED_FONT_FAMILIES$/,
|
||||
/^src\/presentation\/styles\/theme\/shell\.css:\d+ z-index: 50 writes 50 by hand; read a token \(docs\/styling\/design-tokens\.md UI-06\)$/,
|
||||
/^semantic token --layer-navigation is defined but no style reads it$/,
|
||||
/^src\/features\/probe\/probe\.css color: #ff0000 is a raw colour; read a colour token$/,
|
||||
/^src\/features\/probe\/probe\.css mixes colours in oklch; use oklab$/,
|
||||
/^src\/features\/probe\/probe\.css outline-offset: 0 draws the focus ring on the control; UI-01 measures it against the surface around the control$/,
|
||||
/^src\/features\/probe\/probe\.css redefines the token --font-sans; change it in the token files$/,
|
||||
/^src\/presentation\/design-system\/tokens\/component\.css defines --probe-unlisted, which REQUIRED_COMPONENT_TOKENS in token-contract\.ts does not list$/,
|
||||
/^src\/presentation\/design-system\/tokens\/semantic\.css --color-danger-surface is the raw colour oklch\(0\.96 0\.035 25\); name it in primitive\.css and read it with var\(\)$/,
|
||||
];
|
||||
|
||||
Reference in New Issue
Block a user