Semantic architecture
WBDS는 raw value보다 semantic role을 먼저 정의하고, 그 역할을 theme별 실제 값으로 resolve합니다.
Canvas, Surface, Text, Border가 읽기와 containment의 기본층을 구성합니다.
절제된 olive 계열이 다음으로 중요한 결정이나 행동을 담당합니다.
Warm Sakura는 review, noteworthy, evidence, editorial emphasis처럼 드물게 강조가 필요한 순간에만 사용합니다.
Destructive, revoke, prohibited, severe-error 의미는 Signal과 분리합니다.
Positive, Caution, Info, Focus와 관련 soft surface는 각각 독립된 semantic role로 유지합니다.
Light & Dark
A2 aged paper와 D1 Moonlit Desert Midnight는 같은 semantic role system을 서로 다른 theme 값으로 매핑합니다.
#f4eee6
#fbf7f1
#efe5d8
#231f1a
#685e54
#d4c5b4
#566247
#9f5660
#a94431
#446845
#7d571d
#3e6076
#111723
#182132
#202a3f
#f6f0e8
#c4bcaf
#334055
#7d8968
#c1717f
#d67864
#7ca17c
#c7a86e
#85a6c7
Semantic states
theme에 따라 시각 값이 달라져도 Action, Signal, Critical 및 다른 state의 의미는 서로 분리된 채 유지됩니다.
다음으로 중요한 결정이나 행동에 사용합니다. 가장 강한 대비를 화면 전체에 균등하게 뿌리지 않습니다.
Review, noteworthy, evidence, editorial emphasis에 사용합니다. Signal은 Positive도 아니고 destructive 의미도 아닙니다.
Destructive, revoke, prohibited, severe-error 의미에만 사용합니다.
Signal과 별개로 Positive semantic family를 유지합니다.
Critical과 별개로 Caution semantic family를 유지합니다.
정보 상태가 필요한 컴포넌트는 독립된 Info semantic family를 사용합니다.
Focus는 Action이나 Signal을 빌려 쓰지 않고 독립된 semantic color를 사용합니다.
Usage
개별 hue 취향이 아니라 semantic role을 기준으로 색상을 선택하고 적용합니다.
값보다 역할을 먼저 선택
WBDS는 Neutral, Action, Signal, Critical 등 semantic purpose를 먼저 정한 뒤 theme별 실제 값으로 resolve합니다. 소비 제품은 이 페이지의 hex 값을 복사하지 말고 public semantic token에 의존해야 합니다.
Signal은 의도적으로 드물게 사용
Warm Sakura는 review, noteworthy, evidence, editorial moment를 표시합니다. 일반 accent처럼 남용하거나 success 의미로 재사용하지 않습니다.
Dark는 inversion이 아니라 semantic remap
D1 Moonlit Desert Midnight는 동일한 semantic role을 moonlit-blue 계열의 night palette로 다시 매핑합니다. Action은 Action, Signal은 Signal, Critical은 Critical로 의미가 유지됩니다.
Theme ownership
<html data-wb-theme="light">
<html data-wb-theme="dark">
<html data-wb-theme="system">Foundation contract는 명시적인 Light, Dark, System mode를 지원합니다. preference 저장이나 제품별 adaptation은 소비 제품이 소유합니다.
Color structure
하나의 public semantic token API가 Light와 Dark에서 서로 다른 실제 값으로 resolve됩니다.
Neutral
| Role | Token | Light | Dark |
|---|---|---|---|
| Canvas | |||
| Surface | |||
| Surface Muted | |||
| Surface Strong | |||
| Text | |||
| Text Muted | |||
| Text Subtle | |||
| Border | |||
| Border Strong | |||
| Selection |
Action
| Role | Token | Light | Dark |
|---|---|---|---|
| Action | |||
| Action Hover | |||
| Action Pressed | |||
| On Action |
Signal
| Role | Token | Light | Dark |
|---|---|---|---|
| Signal | |||
| Signal Strong | |||
| Signal Hover | |||
| Signal Pressed | |||
| Signal Soft | |||
| On Signal |
Critical
| Role | Token | Light | Dark |
|---|---|---|---|
| Critical | |||
| Critical Hover | |||
| Critical Pressed | |||
| Critical Soft | |||
| On Critical |
Semantic states
| Role | Token | Light | Dark |
|---|---|---|---|
| Positive | |||
| Positive Soft | |||
| Caution | |||
| Caution Soft | |||
| Info | |||
| Info Soft | |||
| Focus |
Instrument & Presence
| Role | Token | Light | Dark |
|---|---|---|---|
| Instrument | |||
| Instrument Raised | |||
| Instrument Text | |||
| Instrument Muted | |||
| Presence Eye |
How to use
대비는 의도적으로 사용하고, Signal은 드물게 유지하며, 상태 의미가 색상 하나에 의존하지 않게 합니다.
- raw palette value 대신
--wb-color-action같은 semantic token을 사용합니다. - 가장 강한 대비는 다음으로 중요한 결정이나 행동을 위해 남겨둡니다.
- Signal은 review/noteworthy/evidence/editorial emphasis에 사용합니다.
- Destructive 또는 prohibited consequence에는 Critical을 별도로 사용합니다.
- 상태 색상은 언어, semantic structure, 필요한 경우 shape/iconography, behavior와 함께 전달합니다.
- Warm Sakura를 모든 곳의 generic decorative accent로 사용하지 않습니다.
- Signal을 Positive/success로 사용하지 않습니다.
- 상태를 색상 하나로만 전달하지 않습니다.
- Light 값을 기계적으로 반전해 Dark를 만들지 않습니다.
- semantic token이 있는데 문서의 hex 값을 복사해 사용하지 않습니다.
Accessibility
색상은 의미를 보조하며, semantic structure와 검증된 contrast가 함께 contract를 이룹니다.
WBDS에서 색상은 상태를 보조하는 evidence이며 유일한 evidence가 아닙니다. Light와 Dark mapping은 동일한 상태 의미와 focus visibility를 보존해야 합니다.
scripts/validate-tokens.mjs는 이 contrast floor를 Light와 Dark token map 모두에서 검증합니다. token gate 통과가 컴포넌트 수준의 수동 visual/accessibility review를 대체하지는 않습니다.