Files
clean-architecture-frontend…/docs/styling/design-tokens.md
T
DongHyeonka c7e80f2f8a test(visual): 갤러리를 Storybook story로 옮기고 골든 대상을 바꾼다
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).

두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.

위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.

검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
2026-11-08 13:51:54 +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
The removable reference feature may demonstrate tokens, but generic production
starter modules do not import its 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.