예제 화면 /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)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
75 lines
3.6 KiB
Markdown
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.
|