Merge pull request 'fix(design-system): 스타일·토큰·story·검사를 토큰 계약에 맞춘다' (#56) from donghyeon.kang/fix/r9-design-tokens-stories into main
frontend-quality-gates / merge / static checks (push) Successful in 1m12s
frontend-quality-gates / merge / tests (push) Failing after 10m10s
frontend-quality-gates / merge / browser tests (push) Successful in 6m1s
frontend-quality-gates / FE-GATE-017 / diagram-review (push) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (push) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (push) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (push) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (push) Skipped
frontend-quality-gates / external-vulnerability-provider (push) Skipped
frontend-quality-gates / external-provenance-provider (push) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (push) Skipped
frontend-quality-gates / deploy-promoted-release (push) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (push) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (push) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (push) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (push) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (push) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (push) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (push) Skipped
frontend-quality-gates / main / self-tests and removal drills (push) Failing after 2m3s

This commit was merged in pull request #56.
This commit is contained in:
2026-11-13 19:13:49 +00:00
34 changed files with 1486 additions and 281 deletions
+41 -11
View File
@@ -20,16 +20,39 @@ component별 값에 연결한다.
- UI-01: `--color-focus`는 두 테마 모두에서, focus ring이 놓일 수 있는 모든
surface와 3:1 이상 대비를 가진다. 대비를 계산할 수 있도록 그 토큰들은 불투명한
`oklch()` 값으로 풀려야 한다.
- UI-02: `color-mix()`는 `oklab`에서 섞는다. 색상(hue) 기반 색 공간에서는 섞지
않는다.
- UI-02: `color-mix()`와 gradient는 색상(hue) 기반 색 공간(oklch·lch·hsl·hwb)에서
섞지 않는다. 기본은 `oklab`이다. 반투명 색을 브라우저가 겹쳐 그린 결과를 재현할
때만 `srgb`를 쓴다(`component.css`의 `--dialog-backdrop-on-surface`).
- 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하지 않을 것.
import하지 않을 것. 토큰 파일 밖의 CSS는 `src/` 아래 전부(기능 폴더 포함)를 보고,
날 색을 쓰거나 토큰을 다시 정의하거나 focus ring을 `outline-offset: 0`으로
그리면 실패한다. gradient의 색 공간도 UI-02를 따른다.
primitive의 `className`·`style`은 배치용이다: 그리드 위치, 바깥 여백, 너비 같은
것. 색과 간격·글자·반경·층·그림자는 variant와 토큰으로 정한다. TSX의
`style={{ … }}`에 이런 값을 손으로 쓰면 검사가 실패한다(`var(--…)`를 읽는 것은
된다).
## 테마 계약
@@ -47,14 +70,21 @@ component는 `--color-panel`, `--color-content`, `--color-border`,
## 들어 있는 primitive
- `Button`: primary, secondary, danger, ghost 의도
- `TextField`: label, 도움말, 필수 상태, 연결된 검증 오류
- `Card`: 이름이 붙은 surface와 선택적 footer
- `Alert`와 `Badge`: 색에만 기대지 않는 status 피드백
- `Dialog`: native modal 의미, Escape·backdrop으로 닫기, 닫은 뒤 trigger로 focus
되돌리기
- 비동기·접근 상태 surface: 로딩, 새로고침, 빈 상태, 끝난(terminal) 오류, 인증
필요, 권한 없음, 찾을 수 없음
primitive·pattern·페이지 템플릿·폼 구성요소의 목록은 공개 배럴
`src/presentation/design-system/index.ts`가 정본이다. 이 문서는 목록을 손으로
들지 않는다. 컴포넌트의 상태는 story에서 연다: 갤러리
`src/presentation/design-system/galleries.stories.tsx`(primitive를 함께, 화면
상태), 카탈로그 `src/presentation/design-system/catalog.stories.tsx`(나머지를
묶음마다). 배럴의 화면 컴포넌트마다 story가 있는지는
`tests/unit/design-system-story-coverage.test.ts`가 대조한다.
모든 primitive가 지키는 약속:
- status 피드백(`Alert`, `Badge`, 상태 surface)은 색에만 기대지 않는다. 글자와
아이콘이 같은 뜻을 전한다.
- 필요한 정보를 tooltip에만 두지 않는다.
- overlay(`Dialog`, `Drawer`, `ConfirmationDialog`)는 native modal 의미를 쓰고,
Escape로 닫고, 닫은 뒤 연 곳으로 focus를 돌린다.
임의 값(arbitrary value) 정책: