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

3.6 KiB

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 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.