From 5fa4ebe189b8f3dfb42535a452b1f18b66fbffc8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:29:33 +0900 Subject: [PATCH] =?UTF-8?q?fix(design-system):=20=EB=94=94=EC=9E=90?= =?UTF-8?q?=EC=9D=B8=20=EA=B2=80=EC=82=AC=EA=B0=80=20=EA=B8=B0=EB=8A=A5=20?= =?UTF-8?q?CSS=C2=B7gradient=C2=B7=EC=9D=B8=EB=9D=BC=EC=9D=B8=20style?= =?UTF-8?q?=EC=9D=98=20=EB=82=A0=20=EA=B0=92=EC=9D=84=20=EC=9E=A1=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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 --- .claude/skills/fe-design-system/SKILL.md | 2 +- docs/styling/design-tokens.md | 9 +- scripts/check-design-system.ts | 33 +++++- scripts/lib/design-system-rules.ts | 71 +++++++++++- .../forbidden/raw-inline-style.tsx | 4 + tests/unit/design-system-rules.test.ts | 105 +++++++++++++++++- 6 files changed, 212 insertions(+), 12 deletions(-) create mode 100644 tests/fixtures/design-system/forbidden/raw-inline-style.tsx diff --git a/.claude/skills/fe-design-system/SKILL.md b/.claude/skills/fe-design-system/SKILL.md index e849c645..cb54fec9 100644 --- a/.claude/skills/fe-design-system/SKILL.md +++ b/.claude/skills/fe-design-system/SKILL.md @@ -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` diff --git a/docs/styling/design-tokens.md b/docs/styling/design-tokens.md index 77ad3482..130cff05 100644 --- a/docs/styling/design-tokens.md +++ b/docs/styling/design-tokens.md @@ -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(--…)`를 읽는 것은 +된다). ## 테마 계약 diff --git a/scripts/check-design-system.ts b/scripts/check-design-system.ts index 75f2247c..07001af5 100644 --- a/scripts/check-design-system.ts +++ b/scripts/check-design-system.ts @@ -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(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") diff --git a/scripts/lib/design-system-rules.ts b/scripts/lib/design-system-rules.ts index ef203ce5..9f372a03 100644 --- a/scripts/lib/design-system-rules.ts +++ b/scripts/lib/design-system-rules.ts @@ -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(/(? !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[] { + return [...withoutComments(source).matchAll(/(? 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; +} diff --git a/tests/fixtures/design-system/forbidden/raw-inline-style.tsx b/tests/fixtures/design-system/forbidden/raw-inline-style.tsx new file mode 100644 index 00000000..9928968a --- /dev/null +++ b/tests/fixtures/design-system/forbidden/raw-inline-style.tsx @@ -0,0 +1,4 @@ +// 1112/04-14. A screen lays a raw colour and spacing over an element. +export function RawInlineStyle() { + return
raw inline style
; +} diff --git a/tests/unit/design-system-rules.test.ts b/tests/unit/design-system-rules.test.ts index 75504130..9a3eb459 100644 --- a/tests/unit/design-system-rules.test.ts +++ b/tests/unit/design-system-rules.test.ts @@ -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: `