Files
clean-architecture-frontend…/docs/styling/design-tokens.md
T
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00

75 lines
3.6 KiB
Markdown

# Design-token styling contract
Tokens are defined in three layers under `src/presentation/design-system/tokens/`:
`primitive.css` holds the raw palette and scales, `semantic.css` maps them to
roles (surface, content, border, action, status) and overrides those roles for
the dark theme, and `component.css` maps roles to per-component values.
`src/presentation/styles/theme.css` only imports the three files and the style
files under `src/presentation/styles/theme/`. Components consume semantic
color, spacing, typography, status, and radius tokens through static classes.
The executable token and primitive gallery is the workshop story
`src/presentation/design-system/galleries.stories.tsx` (`corepack pnpm storybook`).
## Rules a rebrand must keep
`check:design-system` (`scripts/check-design-system.ts`) fails when a token
edit breaks one of these. The reasons are next to each rule in
`scripts/lib/design-system-rules.ts`.
- UI-01: `--color-focus` has at least 3:1 contrast against every surface a
focus ring can sit on, in both themes. Those tokens must resolve to opaque
`oklch()` values so the contrast can be computed.
- UI-02: `color-mix()` mixes in `oklab`, never in a hue-based space.
- UI-03: every component token is read by some style.
- UI-05: `--font-sans` starts with a generic family or one the repository
ships with `@font-face`.
The same check requires the token names in `token-contract.ts`, the dark
overrides of the core semantic roles, a forced-colors fallback in
`component.css`, no raw palette values outside the token files, and no direct
headless-library imports.
## Theme contract
The supported public preference is the closed set `system`, `light`, and
`dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application
storage port; it does not access a raw storage key. `system` subscribes to
`prefers-color-scheme` changes. Bootstrap applies the persisted preference
before React paints.
Components use semantic tokens such as `--color-panel`, `--color-content`,
`--color-border`, `--color-action`, and status surface/content/border triples.
They must not hard-code a light-only panel or text color. Both light and dark
surfaces are included in automated axe checks.
## Included primitives
- `Button`: primary, secondary, danger, and ghost intent
- `TextField`: label, help text, required state, and associated validation error
- `Card`: labelled surface with optional footer
- `Alert` and `Badge`: non-color-only status feedback
- `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus
restoration
- async and access state surfaces: loading, refresh, empty, terminal error,
auth required, forbidden, and not found
Arbitrary-value policy:
- prefer a named semantic token
- bracket values are allowed only for one-off platform constraints that cannot
be expressed by the current scale
- a repeated bracket value must be promoted into `@theme`
- user-controlled or runtime-composed class strings are forbidden
- class variants must be selected from a closed static map
A feature may demonstrate tokens, but generic production starter modules do
not import a feature's domain, application, adapter, or presentation
implementation.
This file documents the currently implemented token and primitive baseline.
The [design-system platform contract](./design-system-platform.md) defines the
target token layers, component catalog, local Lucide/headless-library
facades, page patterns, accessibility and internationalization rules, isolated
workshop, and component-authoring recipe. Items in that target document are not
treated as implemented until their acceptance tests pass.