Files
clean-architecture-frontend…/docs/styling/design-tokens.md
T
DongHyeonka 5fa4ebe189 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
2026-11-13 23:27:47 +09:00

6.0 KiB

디자인 토큰 스타일 계약

토큰은 src/presentation/design-system/tokens/ 아래 세 층으로 정의한다. primitive.css에는 가공하지 않은 색 팔레트와 단계(scale)가 있다. semantic.css는 그것을 역할(surface, content, border, action, status)에 연결하고, 어두운 테마에서는 그 역할 값을 덮어쓴다. component.css는 역할을 component별 값에 연결한다. src/presentation/styles/theme.css는 세 파일과 src/presentation/styles/theme/ 아래 스타일 파일을 import만 한다. component는 semantic 색, 간격, 글자(typography), status, 모서리 반경(radius) 토큰을 정적 class로 쓴다. 실행해 볼 수 있는 토큰·primitive 갤러리는 workshop story src/presentation/design-system/galleries.stories.tsx다(corepack pnpm storybook).

리브랜드할 때 지켜야 할 규칙

토큰을 고쳐서 아래 규칙 하나라도 깨지면 check:design-system(scripts/check-design-system.ts)이 실패한다. 규칙마다 이유는 scripts/lib/design-system-rules.ts에서 그 규칙 옆에 적혀 있다.

  • UI-01: --color-focus는 두 테마 모두에서, focus ring이 놓일 수 있는 모든 surface와 3:1 이상 대비를 가진다. 대비를 계산할 수 있도록 그 토큰들은 불투명한 oklch() 값으로 풀려야 한다.
  • UI-02: color-mix()는 oklab에서 섞는다. 색상(hue) 기반 색 공간에서는 섞지 않는다.
  • UI-03: 모든 component 토큰은 어떤 스타일이든 하나에서 읽힌다. component.css의 @theme에 정의한 토큰은 모두 token-contract.ts의 REQUIRED_COMPONENT_TOKENS에 있어야 한다. 필수 semantic 토큰도 스타일 하나가 읽어야 한다. 예외는 SEMANTIC_TOKENS_WITHOUT_TEMPLATE_READER에 이유와 함께 적는다(지금 --layer-modal 하나: native <dialog>는 top layer에 열려 z-index가 닿지 않는다).
  • UI-05: --font-sans는 generic family로 시작하거나, repository가 @font-face로 함께 배포하는 글꼴로 시작한다.
  • UI-06: src/ 아래 토큰 파일 밖의 스타일은 간격(padding·margin·gap), 글자 크기·굵기·줄 높이, 모서리 반경, z-index, 그림자를 손으로 쓰지 않고 토큰(var(--space-*), --font-size-*, --font-weight-*, --line-height-*, --radius-*, --layer-*, --elevation-*)을 읽는다. 0, auto, 키워드, %, viewport 단위, margin·padding의 1px 선, 부모 글자에 대한 em, line-height: 1, z-index 0·-1은 된다. 맞는 단계가 없으면 primitive.css에 단계를 더한다.
  • UI-07: semantic.css는 색 값을 직접 쓰지 않는다. 색은 primitive.css 팔레트에 이름을 두고 var()로 읽는다. 토큰끼리 섞는 color-mix()는 된다. 그래서 팔레트만 고쳐도 status 색, focus, 어두운 테마가 따라온다.

같은 검사는 다음도 요구한다: token-contract.ts의 토큰 이름, 핵심 semantic 역할의 어두운 테마 덮어쓰기, component.css의 forced-colors fallback, 토큰 파일 밖에서 가공하지 않은 팔레트 값을 쓰지 않을 것, headless 라이브러리를 직접 import하지 않을 것. 토큰 파일 밖의 CSS는 src/ 아래 전부(기능 폴더 포함)를 보고, 날 색을 쓰거나 토큰을 다시 정의하거나 focus ring을 outline-offset: 0으로 그리면 실패한다. gradient의 색 공간도 UI-02를 따른다.

primitive의 className·style은 배치용이다: 그리드 위치, 바깥 여백, 너비 같은 것. 색과 간격·글자·반경·층·그림자는 variant와 토큰으로 정한다. TSX의 style={{ … }}에 이런 값을 손으로 쓰면 검사가 실패한다(var(--…)를 읽는 것은 된다).

테마 계약

공개로 지원하는 선택값은 닫힌 집합 system, light, dark다. ThemeProvider는 application storage port를 거쳐 COLOR_SCHEME을 읽고 쓴다. 가공하지 않은 storage key에 직접 접근하지 않는다. system은 prefers-color-scheme 변화를 구독한다. 부트 과정(bootstrap)은 React가 화면을 그리기 전에 저장된 선택값을 적용한다.

component는 --color-panel, --color-content, --color-border, --color-action 같은 semantic 토큰과 status의 surface/content/border 세 쌍을 쓴다. 밝은 테마에서만 맞는 panel 색이나 글자 색을 하드코딩하면 안 된다. 자동 axe 검사는 밝은 surface와 어두운 surface를 모두 본다.

들어 있는 primitive

  • Button: primary, secondary, danger, ghost 의도
  • TextField: label, 도움말, 필수 상태, 연결된 검증 오류
  • Card: 이름이 붙은 surface와 선택적 footer
  • Alert와 Badge: 색에만 기대지 않는 status 피드백
  • Dialog: native modal 의미, Escape·backdrop으로 닫기, 닫은 뒤 trigger로 focus 되돌리기
  • 비동기·접근 상태 surface: 로딩, 새로고침, 빈 상태, 끝난(terminal) 오류, 인증 필요, 권한 없음, 찾을 수 없음

임의 값(arbitrary value) 정책:

  • 이름 있는 semantic 토큰을 먼저 쓴다
  • 대괄호 값은 지금 scale로 나타낼 수 없는 일회성 platform 제약에만 쓴다
  • 같은 대괄호 값이 반복되면 @theme으로 올려야 한다
  • 사용자가 정하거나 runtime에 조합하는 class 문자열은 금지한다
  • class 변형은 닫힌 정적 map에서 골라야 한다

feature는 토큰을 시연할 수 있다. 하지만 범용 production starter 모듈은 feature의 domain, application, adapter, presentation 구현을 import하지 않는다.

이 파일은 지금 구현된 토큰과 primitive 기준선을 적는다. 디자인 시스템 platform 계약은 목표 상태를 정의한다: 목표 토큰 층, component 목록, 로컬 Lucide·headless 라이브러리 facade, 페이지 패턴, 접근성·국제화 규칙, 격리된 workshop, component 작성 recipe. 그 목표 문서의 항목은 인수 테스트가 통과하기 전에는 구현된 것으로 보지 않는다.