소유자 결정(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.
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
|
|
|
|
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.
|