From b384d29ca528f3b90cdd32c6a5bf025935fd1ae8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:23:10 +0900 Subject: [PATCH] =?UTF-8?q?refactor(tokens):=20semantic=20=EC=83=89?= =?UTF-8?q?=EC=9D=84=20=EB=AA=A8=EB=91=90=20=ED=8C=94=EB=A0=88=ED=8A=B8?= =?UTF-8?q?=EC=97=90=EC=84=9C=20=EC=9D=BD=EA=B3=A0=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EA=B0=80=20=EB=82=A0=20=EC=83=89=EC=9D=84=20=EA=B1=B0=EC=A0=88?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다(밝은 테마의 focus와 info·success·warning·danger 세 쌍 13개, 어두운 테마 23개). `PRODUCT.md`와 `docs/styling/design-tokens.md`는 토큰이 primitive → semantic → component로 파생되고 팔레트는 `primitive.css`에 있다고 적는다. 그래서 팔레트만 바꿔 리브랜드하면 status 색, focus, 어두운 테마 대부분이 그대로다. 고른 방법: 36개 값을 그대로 `primitive.css` 팔레트로 옮기고 semantic은 `var()`로 읽는다. 색상 이름 무리(slate·night·blue·sky·green·amber·red)마다 밝기 순서로 단계 이름을 붙였다. 값은 바꾸지 않아 화면은 같다. 그리고 `check:design-system`에 UI-07을 더한다: semantic 선언값이 날 색(#hex, oklch·oklab·lch·lab·rgb·hsl·hwb·color 함수)이면 실패하고, 토큰과 위치를 말한다. 버린 대안: 문서에 "semantic은 역할 전용 값을 가질 수 있다"와 예외 목록을 적는 것(리브랜드 약속이 그대로 깨진다). 위험·한계: 다운스트림이 `semantic.css`에 날 색을 더해 두었으면 다음 동기화에서 UI-07이 그 줄을 이름과 함께 알린다. 팔레트로 옮기면 된다. UI-01 대비 계산은 var 사슬을 따라가므로 그대로 돈다. 검증: 규칙 단위 시험(거절 다섯·통과 셋·저장소 파일)과 check-design-system 연결 시험의 RED·GREEN, 시각 골든 불변은 desktop에서 돌려 PR 본문에 적는다. Refs: 1112/04-13 --- docs/styling/design-tokens.md | 3 + scripts/check-design-system.ts | 4 ++ scripts/lib/design-system-rules.ts | 20 +++++- .../design-system/tokens/primitive.css | 40 +++++++++++ .../design-system/tokens/semantic.css | 72 +++++++++---------- tests/unit/design-system-rules.test.ts | 40 ++++++++++- 6 files changed, 140 insertions(+), 39 deletions(-) diff --git a/docs/styling/design-tokens.md b/docs/styling/design-tokens.md index 4ace9a37..08881e07 100644 --- a/docs/styling/design-tokens.md +++ b/docs/styling/design-tokens.md @@ -25,6 +25,9 @@ component별 값에 연결한다. - UI-03: 모든 component 토큰은 어떤 스타일이든 하나에서 읽힌다. - UI-05: `--font-sans`는 generic family로 시작하거나, repository가 `@font-face`로 함께 배포하는 글꼴로 시작한다. +- UI-07: `semantic.css`는 색 값을 직접 쓰지 않는다. 색은 `primitive.css` + 팔레트에 이름을 두고 `var()`로 읽는다. 토큰끼리 섞는 `color-mix()`는 된다. + 그래서 팔레트만 고쳐도 status 색, focus, 어두운 테마가 따라온다. 같은 검사는 다음도 요구한다: `token-contract.ts`의 토큰 이름, 핵심 semantic 역할의 어두운 테마 덮어쓰기, `component.css`의 forced-colors fallback, 토큰 파일 diff --git a/scripts/check-design-system.ts b/scripts/check-design-system.ts index 4e5a39af..74b677b1 100644 --- a/scripts/check-design-system.ts +++ b/scripts/check-design-system.ts @@ -14,6 +14,7 @@ import { firstFontFamilyFailures, focusContrastFailures, hueMixFailures, + rawSemanticColourFailures, unreadTokenFailures, } from "./lib/design-system-rules.ts"; import { readCustomProperties } from "./lib/oklch-contrast.ts"; @@ -66,6 +67,9 @@ for (const { file, source } of cssSources) { } const semanticSource = await readFile(tokenFiles.semantic, "utf8"); +failures.push( + ...rawSemanticColourFailures({ file: tokenFiles.semantic, source: semanticSource }), +); const darkSource = semanticSource.match(/:root\[data-theme="dark"\]\s*\{([\s\S]*?)\n\}/)?.[1] ?? ""; diff --git a/scripts/lib/design-system-rules.ts b/scripts/lib/design-system-rules.ts index 40bbbc79..dd7f02c1 100644 --- a/scripts/lib/design-system-rules.ts +++ b/scripts/lib/design-system-rules.ts @@ -1,5 +1,5 @@ -// The four CSS rules scripts/check-design-system.ts runs over the token -// files and src/presentation/styles/**. Each rule takes file contents and +// The CSS rules scripts/check-design-system.ts runs over the token files and +// the style sheets. Each rule takes file contents and // returns failure messages, so a test can hand it a violation directly. import { contrastRatio, resolveColor, resolveValue } from "./oklch-contrast.ts"; @@ -126,3 +126,19 @@ export function firstFontFamilyFailures( `--font-sans starts with "${first}", which is neither a generic family, loaded by @font-face, nor listed in PRODUCT_LOADED_FONT_FAMILIES`, ]; } + +// UI-07. The semantic layer names roles and reads its colours from the +// palette in primitive.css. A colour written straight into semantic.css is +// out of reach of a rebrand that edits the palette: 36 such values kept the +// status colours, the focus ring and most of the dark theme as they were +// (1112/04-13). +const RAW_COLOUR = /#[0-9a-f]{3,8}\b|\b(?:oklch|oklab|lch|lab|rgba?|hsla?|hwb|color)\(/i; + +export function rawSemanticColourFailures({ file, source }: CssSource): string[] { + return [...withoutComments(source).matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/gi)] + .filter((match) => RAW_COLOUR.test(match[2])) + .map( + (match) => + `${file} ${match[1]} is the raw colour ${match[2].trim()}; name it in primitive.css and read it with var()`, + ); +} diff --git a/src/presentation/design-system/tokens/primitive.css b/src/presentation/design-system/tokens/primitive.css index c0b47770..ab21e6cf 100644 --- a/src/presentation/design-system/tokens/primitive.css +++ b/src/presentation/design-system/tokens/primitive.css @@ -6,12 +6,52 @@ --palette-slate-500: oklch(0.48 0.025 247); --palette-slate-800: oklch(0.25 0.025 247); --palette-slate-950: oklch(0.16 0.02 255); + /* Cool greys of the dark theme (hue 255). */ + --palette-night-100: oklch(0.94 0.012 255); + --palette-night-300: oklch(0.74 0.025 255); + --palette-night-450: oklch(0.58 0.025 255); + --palette-night-650: oklch(0.36 0.025 255); + --palette-night-800: oklch(0.25 0.025 255); + --palette-night-850: oklch(0.235 0.025 255); + --palette-night-900: oklch(0.205 0.022 255); + --palette-blue-50: oklch(0.95 0.03 255); + --palette-blue-150: oklch(0.83 0.1 245); + --palette-blue-200: oklch(0.83 0.09 250); + --palette-blue-250: oklch(0.79 0.12 245); + --palette-blue-300: oklch(0.75 0.08 250); --palette-blue-500: oklch(0.7 0.14 250); + --palette-blue-550: oklch(0.55 0.09 250); --palette-blue-600: oklch(0.55 0.18 255); --palette-blue-700: oklch(0.48 0.2 255); + --palette-blue-800: oklch(0.38 0.16 255); + --palette-blue-900: oklch(0.27 0.045 255); + /* The focus ring hue. */ + --palette-sky-200: oklch(0.82 0.15 220); + --palette-sky-600: oklch(0.52 0.15 230); + /* Success. */ + --palette-green-50: oklch(0.95 0.04 155); + --palette-green-200: oklch(0.83 0.1 155); + --palette-green-400: oklch(0.72 0.1 155); + --palette-green-600: oklch(0.53 0.1 155); + --palette-green-800: oklch(0.35 0.12 155); + --palette-green-900: oklch(0.27 0.045 155); + /* Warning. */ + --palette-amber-50: oklch(0.96 0.05 80); + --palette-amber-200: oklch(0.88 0.1 80); + --palette-amber-400: oklch(0.75 0.12 80); + --palette-amber-600: oklch(0.58 0.11 80); + --palette-amber-800: oklch(0.38 0.12 70); + --palette-amber-900: oklch(0.29 0.045 80); + --palette-red-50: oklch(0.96 0.035 25); + --palette-red-200: oklch(0.84 0.11 25); + --palette-red-300: oklch(0.76 0.16 25); + --palette-red-400: oklch(0.72 0.12 25); --palette-red-500: oklch(0.68 0.19 25); + --palette-red-550: oklch(0.56 0.13 25); --palette-red-600: oklch(0.55 0.2 25); --palette-red-700: oklch(0.47 0.2 25); + --palette-red-800: oklch(0.42 0.18 25); + --palette-red-900: oklch(0.28 0.055 25); --space-1: 0.25rem; --space-2: 0.5rem; diff --git a/src/presentation/design-system/tokens/semantic.css b/src/presentation/design-system/tokens/semantic.css index 0d8f8ab8..53b7c12b 100644 --- a/src/presentation/design-system/tokens/semantic.css +++ b/src/presentation/design-system/tokens/semantic.css @@ -14,21 +14,21 @@ --color-danger: var(--palette-red-600); --color-danger-hover: var(--palette-red-700); --color-on-action: var(--palette-white); - --color-focus: oklch(0.52 0.15 230); + --color-focus: var(--palette-sky-600); --color-disabled-content: color-mix(in oklab, var(--color-content) 55%, transparent); --color-disabled-surface: var(--color-surface-muted); - --color-info-content: oklch(0.38 0.16 255); - --color-info-surface: oklch(0.95 0.03 255); - --color-info-border: oklch(0.75 0.08 250); - --color-success-content: oklch(0.35 0.12 155); - --color-success-surface: oklch(0.95 0.04 155); - --color-success-border: oklch(0.72 0.1 155); - --color-warning-content: oklch(0.38 0.12 70); - --color-warning-surface: oklch(0.96 0.05 80); - --color-warning-border: oklch(0.75 0.12 80); - --color-danger-content: oklch(0.42 0.18 25); - --color-danger-surface: oklch(0.96 0.035 25); - --color-danger-border: oklch(0.72 0.12 25); + --color-info-content: var(--palette-blue-800); + --color-info-surface: var(--palette-blue-50); + --color-info-border: var(--palette-blue-300); + --color-success-content: var(--palette-green-800); + --color-success-surface: var(--palette-green-50); + --color-success-border: var(--palette-green-400); + --color-warning-content: var(--palette-amber-800); + --color-warning-surface: var(--palette-amber-50); + --color-warning-border: var(--palette-amber-400); + --color-danger-content: var(--palette-red-800); + --color-danger-surface: var(--palette-red-50); + --color-danger-border: var(--palette-red-400); --font-sans: system-ui, "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR", "Noto Sans CJK KR", sans-serif; /* 08-04. One step per heading level; a product retunes the scale here. */ @@ -56,33 +56,33 @@ :root[data-theme="dark"] { --color-surface: var(--palette-slate-950); - --color-surface-muted: oklch(0.25 0.025 255); - --color-panel: oklch(0.205 0.022 255); - --color-surface-elevated: oklch(0.235 0.025 255); - --color-border: oklch(0.36 0.025 255); - --color-border-strong: oklch(0.58 0.025 255); - --color-content: oklch(0.94 0.012 255); - --color-content-muted: oklch(0.74 0.025 255); + --color-surface-muted: var(--palette-night-800); + --color-panel: var(--palette-night-900); + --color-surface-elevated: var(--palette-night-850); + --color-border: var(--palette-night-650); + --color-border-strong: var(--palette-night-450); + --color-content: var(--palette-night-100); + --color-content-muted: var(--palette-night-300); --color-content-inverse: var(--palette-slate-950); --color-action: var(--palette-blue-500); - --color-action-hover: oklch(0.79 0.12 245); - --color-action-pressed: oklch(0.83 0.1 245); + --color-action-hover: var(--palette-blue-250); + --color-action-pressed: var(--palette-blue-150); --color-danger: var(--palette-red-500); - --color-danger-hover: oklch(0.76 0.16 25); + --color-danger-hover: var(--palette-red-300); --color-on-action: var(--palette-slate-950); - --color-focus: oklch(0.82 0.15 220); + --color-focus: var(--palette-sky-200); --color-disabled-content: color-mix(in oklab, var(--color-content) 55%, transparent); --color-disabled-surface: var(--color-surface-muted); - --color-info-content: oklch(0.83 0.09 250); - --color-info-surface: oklch(0.27 0.045 255); - --color-info-border: oklch(0.55 0.09 250); - --color-success-content: oklch(0.83 0.1 155); - --color-success-surface: oklch(0.27 0.045 155); - --color-success-border: oklch(0.53 0.1 155); - --color-warning-content: oklch(0.88 0.1 80); - --color-warning-surface: oklch(0.29 0.045 80); - --color-warning-border: oklch(0.58 0.11 80); - --color-danger-content: oklch(0.84 0.11 25); - --color-danger-surface: oklch(0.28 0.055 25); - --color-danger-border: oklch(0.56 0.13 25); + --color-info-content: var(--palette-blue-200); + --color-info-surface: var(--palette-blue-900); + --color-info-border: var(--palette-blue-550); + --color-success-content: var(--palette-green-200); + --color-success-surface: var(--palette-green-900); + --color-success-border: var(--palette-green-600); + --color-warning-content: var(--palette-amber-200); + --color-warning-surface: var(--palette-amber-900); + --color-warning-border: var(--palette-amber-600); + --color-danger-content: var(--palette-red-200); + --color-danger-surface: var(--palette-red-900); + --color-danger-border: var(--palette-red-550); } diff --git a/tests/unit/design-system-rules.test.ts b/tests/unit/design-system-rules.test.ts index cbc9eded..926a463d 100644 --- a/tests/unit/design-system-rules.test.ts +++ b/tests/unit/design-system-rules.test.ts @@ -10,6 +10,7 @@ import { firstFontFamilyFailures, focusContrastFailures, hueMixFailures, + rawSemanticColourFailures, unreadTokenFailures, } from "../../scripts/lib/design-system-rules.ts"; import { childProcessTimeout } from "../helpers/child-process-timeout.ts"; @@ -78,6 +79,39 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => { }); }); + // 1112/04-13. A rebrand edits the palette; the roles follow it. + describe("UI-07 semantic colours come from the palette", () => { + it.each([ + "oklch(0.52 0.15 230)", + "#2563eb", + "rgb(37 99 235)", + "hsl(220 80% 50%)", + "OKLCH(0.5 0.1 200)", + ])("fails a role written as %s", (value) => { + expect(rawSemanticColourFailures(css(`:root { --color-focus: ${value}; }`))).toEqual([ + `probe.css --color-focus is the raw colour ${value}; name it in primitive.css and read it with var()`, + ]); + }); + + it("passes a palette read, a mix of tokens, and a comment", () => { + expect( + rawSemanticColourFailures( + css(`/* was oklch(0.5 0.1 200) */ + :root { + --color-focus: var(--palette-sky-600); + --color-disabled-content: color-mix(in oklab, var(--color-content) 55%, transparent); + --layer-modal: 70; + }`), + ), + ).toEqual([]); + }); + + it("passes the repository's semantic tokens", async () => { + const file = "src/presentation/design-system/tokens/semantic.css"; + expect(rawSemanticColourFailures({ file, source: await readFile(file, "utf8") })).toEqual([]); + }); + }); + describe("UI-03 component token readers", () => { const tokens = ["--field-border", "--field-border-invalid"]; @@ -161,8 +195,11 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => { await writeFile(target, edited); }; const semantic = "src/presentation/design-system/tokens/semantic.css"; - await edit(semantic, /--color-focus: [^;]+;/, "--color-focus: oklch(0.72 0.16 225);"); + // A palette colour too light for 3:1 on the light surfaces (UI-01), read + // as a token so that UI-07 stays quiet. + await edit(semantic, /--color-focus: [^;]+;/, "--color-focus: var(--palette-sky-200);"); await edit(semantic, "--font-sans: ", "--font-sans: Inter, "); + await edit(semantic, "--color-danger-surface: var(--palette-red-50);", "--color-danger-surface: oklch(0.96 0.035 25);"); await edit("src/presentation/styles/theme/primitives.css", "var(--drawer-width)", "20rem"); await writeFile( path.join(root, "src/presentation/styles/theme/probe.css"), @@ -182,6 +219,7 @@ describe("design system rules", { timeout: childProcessTimeout(3_540) }, () => { /^src\/presentation\/styles\/theme\/probe\.css mixes colours in oklch; use oklab$/, /^component token --drawer-width is defined but no style reads it$/, /^--font-sans starts with "Inter", which is neither a generic family, loaded by @font-face, nor listed in PRODUCT_LOADED_FONT_FAMILIES$/, + /^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\(\)$/, ]; expect(failures.filter((failure) => !rules.some((rule) => rule.test(failure)))).toEqual([]); for (const rule of rules) {