Files
clean-architecture-frontend…/scripts/lib/oklch-contrast.ts
T
DongHyeonka e714c0d770 fix(design-system): 디자인 검사가 deg 색상각과 시스템 글꼴 이름을 받는다 (12-04)
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.

고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
  그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
  <값>; contrast needs an opaque oklch(L C H), hue in degrees with or
  without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
  검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
  규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
  해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
  새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
  곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.

위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.

검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
  실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
  "names the value it cannot compute …" 메시지 불일치, "-apple-system"
  expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
  null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
  probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
  oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
  / 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
  documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
2026-11-01 22:16:26 +09:00

78 lines
2.8 KiB
TypeScript

// WCAG contrast for design tokens written as oklch(). The conversion is
// OKLab -> linear sRGB (Björn Ottosson's matrices) with a plain clip to the
// sRGB gamut, which is what the browser draws for every token we ship.
export interface Oklch {
readonly l: number;
readonly c: number;
readonly h: number;
}
export function parseOklch(value: string): Oklch | null {
// No alpha: a translucent colour depends on what is drawn beneath it.
const match =
/^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+(none|-?[\d.]+(?:deg)?)\s*\)$/.exec(
value.trim(),
);
if (!match) return null;
return {
l: Number(match[1]) / (match[2] === "%" ? 100 : 1),
c: Number(match[3]),
h: match[4] === "none" ? 0 : Number.parseFloat(match[4]),
};
}
export function relativeLuminance({ l, c, h }: Oklch): number {
const hue = (h * Math.PI) / 180;
const a = c * Math.cos(hue);
const b = c * Math.sin(hue);
const long = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
const medium = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
const short = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
const clip = (channel: number) => Math.min(1, Math.max(0, channel));
const red = clip(4.0767416621 * long - 3.3077115913 * medium + 0.2309699292 * short);
const green = clip(-1.2684380046 * long + 2.6097574011 * medium - 0.3413193965 * short);
const blue = clip(-0.0041960863 * long - 0.7034186147 * medium + 1.707614701 * short);
return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
}
export function contrastRatio(first: Oklch, second: Oklch): number {
const [lighter, darker] = [relativeLuminance(first), relativeLuminance(second)]
.sort((x, y) => y - x);
return (lighter + 0.05) / (darker + 0.05);
}
export function readCustomProperties(css: string): Map<string, string> {
return new Map(
[...css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)].map(
(match) => [match[1], match[2].trim()] as const,
),
);
}
// Follows var(--x) chains to the value at the end. undefined when a link
// is missing or the chain is deeper than 8.
export function resolveValue(
token: string,
properties: ReadonlyMap<string, string>,
): string | undefined {
let value = properties.get(token);
for (let depth = 0; value !== undefined && depth < 8; depth += 1) {
const reference = /^var\((--[a-z0-9-]+)\)$/.exec(value);
if (!reference) return value;
value = properties.get(reference[1]);
}
return undefined;
}
// Returns null for anything that is not a plain oklch() at the end of the
// chain (color-mix, alpha, keywords), so callers fail loudly instead of
// guessing.
export function resolveColor(
token: string,
properties: ReadonlyMap<string, string>,
): Oklch | null {
const value = resolveValue(token, properties);
return value === undefined ? null : parseOklch(value);
}