refactor(tokens): semantic 색을 모두 팔레트에서 읽고 검사가 날 색을 거절한다

`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
This commit is contained in:
DongHyeonka
2026-11-13 23:27:47 +09:00
parent 009a29918e
commit b384d29ca5
6 changed files with 140 additions and 39 deletions
+3
View File
@@ -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, 토큰 파일
+4
View File
@@ -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] ??
"";
+18 -2
View File
@@ -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()`,
);
}
@@ -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;
@@ -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);
}
+39 -1
View File
@@ -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) {