문제: 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이 비었다.
4.2 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 토큰은 어떤 스타일이든 하나에서 읽힌다.
- 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와 선택적 footerAlert와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. 그 목표 문서의 항목은 인수 테스트가 통과하기 전에는 구현된 것으로 보지 않는다.