문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을 가리킨다. 고른 방법: 기계적으로 바꾼다. - 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고, 대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다. 옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은 링크 대상뿐이다(백엔드 1단계와 같은 예외). - 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`, `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과 CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와 review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토 작업 공간의 출처 표시라 그대로 둔다. 위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는 없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다. 검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록, CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시 쓴다) 밖에서 0건.
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-focushas at least 3:1 contrast against every surface a focus ring can sit on, in both themes. Those tokens must resolve to opaqueoklch()values so the contrast can be computed. - UI-02:
color-mix()mixes inoklab, never in a hue-based space. - UI-03: every component token is read by some style.
- UI-05:
--font-sansstarts 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 intentTextField: label, help text, required state, and associated validation errorCard: labelled surface with optional footerAlertandBadge: non-color-only status feedbackDialog: 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.