문제: docs/runbooks, docs/security, docs/styling/design-tokens.md, docs/accessibility, docs/contracts, docs/testing/taxonomy.md와 src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다. PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code, 기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로 둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장 끝만 바꾼다. 위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임 문체를 더하면 verify:documentation이 실패한다. 검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다. 문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
# 디자인 토큰 스타일 계약
|
|
|
|
토큰은 `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 토큰은 어떤 스타일이든 하나에서 읽힌다.
|
|
- UI-05: `--font-sans`는 generic family로 시작하거나, repository가
|
|
`@font-face`로 함께 배포하는 글꼴로 시작한다.
|
|
|
|
같은 검사는 다음도 요구한다: `token-contract.ts`의 토큰 이름, 핵심 semantic
|
|
역할의 어두운 테마 덮어쓰기, `component.css`의 forced-colors fallback, 토큰 파일
|
|
밖에서 가공하지 않은 팔레트 값을 쓰지 않을 것, headless 라이브러리를 직접
|
|
import하지 않을 것.
|
|
|
|
## 테마 계약
|
|
|
|
공개로 지원하는 선택값은 닫힌 집합 `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 계약](../design/2026-07-26-design-system-platform-design.md)은 목표 상태를
|
|
정의한다: 목표 토큰 층, component 목록, 로컬 Lucide·headless 라이브러리 facade,
|
|
페이지 패턴, 접근성·국제화 규칙, 격리된 workshop, component 작성 recipe. 그 목표
|
|
문서의 항목은 인수 테스트가 통과하기 전에는 구현된 것으로 보지 않는다.
|