197 lines
9.8 KiB
Markdown
197 lines
9.8 KiB
Markdown
# Workspace Web Design Language
|
||
|
||
この文書は、Workspace Webのrendered resultが満たす設計規則を定義する。
|
||
|
||
一つの規則は最も具体的な一箇所だけをauthorityとする。具体的な二案の一方を棄却できない文は規則として残さない。
|
||
|
||
## 1. Principles
|
||
|
||
複数の規則や要求が競合した場合だけ、この章の優先原理を使う。
|
||
|
||
### Task before explanation
|
||
|
||
次の有効なactionへ到達する前の操作、scroll、常設説明が少ない案を選ぶ。ただし、説明を省くと対象、結果、permission、不可逆性を誤認する場合は説明をactionより前に置く。
|
||
|
||
### Meaning before decoration
|
||
|
||
情報の関係、重要度、操作可能性、stateのいずれも変えない視覚差を追加しない。
|
||
|
||
### Authority before convenience
|
||
|
||
Backend authorityが確定していないdata、state、permission、actionを、UIの都合で補完または推測する案を棄却する。
|
||
|
||
## 2. Semantics / Grammar
|
||
|
||
### Information structure
|
||
|
||
- pageと、page内で一つのtaskまたは判断を完結させる領域をscopeとする。
|
||
- 各scopeで最も強い視覚要素はheading、現在判断が必要なattention、filled actionのいずれか一つだけにする。同じ強さのheading、attention、filled actionを複数置かない。
|
||
- hierarchyをcolorだけで表現しない。DOMと画面上の配置順を一致させた上で、size、weight、contrastを使う。
|
||
- scopeを識別するprimary titleは、一つのscopeにつき一度だけ表示する。
|
||
- actionは、そのactionが影響するscope内に置く。
|
||
- DTOにfieldが存在するという理由だけで表示せず、current taskの判断またはactionを変える値だけを常設する。
|
||
|
||
**Disclosure**
|
||
|
||
- Raw dataやデバッグ情報など、通常は必要としない詳細な情報は折りたたみ領域に隠す。
|
||
- 作成または編集のformを表示用screenへ常時同居させず、明示的なactionで開く折りたたみ領域または別pageに置く。
|
||
|
||
### Interaction and state
|
||
|
||
- actionにはbutton、navigationにはlink、選択には対応するform controlを使う。
|
||
- interactive elementはhover、focus、active、disabledを視覚的に区別する。
|
||
- staticなstatus、key、metadataをbuttonやpillの形にしない。
|
||
- clickable rowは遷移先を一つだけ持ち、row全体で同じ遷移を実行する。
|
||
- permissionがないactionをdisabled controlとして表示しない。
|
||
|
||
**State and operation**
|
||
|
||
- stateの違いによってユーザーの判断または利用できるactionが変わる場合、その違いを一つの表示へ統合しない。
|
||
- UI stateはそのstateを所有するauthorityから取得し、別domainやtransportのsignalから推測しない。
|
||
- 非同期mutationでは楽観的更新か悲観的更新を選ぶ。楽観的更新は暫定stateを明示し、failure時のrollbackまたは再取得を定義できる場合だけ使う。それ以外は確定済みstateを維持し、operationのpending stateを別に表示する。
|
||
- loading、failure、unavailableの表示は利用不能になった最小のscopeだけを置き換え、利用可能な親scopeとsibling scopeを残す。
|
||
- destructive actionは対象と結果を明記し、復元できない場合だけconfirmationを要求する。
|
||
|
||
### Language / Copy
|
||
|
||
- title、navigation label、control labelで明らかな内容を説明文で繰り返さない。
|
||
- 常設proseは、対象またはactionの選択を変えるwarning、permission、validation constraint、error recoveryに必要な内容だけにする。
|
||
- button labelには具体的なactionを表す動詞を使い、`Submit`と`OK`を使わない。
|
||
- identifier、API名、type名を別の語へ言い換えない。
|
||
|
||
### Responsive behavior
|
||
|
||
- page全体にhorizontal scrollを発生させない。
|
||
- wrappingまたはstack化によって情報の対応関係が失われる場合だけ、その領域内にbounded horizontal scrollを持たせる。それ以外のside-by-side layoutは一列にする。
|
||
- primary actionを初期viewportから追い出さない。
|
||
- contentをtruncateする場合、完全な値をcopyまたはdetailで取得できるようにする。
|
||
|
||
### Accessibility
|
||
|
||
- action、navigation、form controlを非semantic elementだけで実装しない。
|
||
- すべてのcontrolにaccessible nameを与える。
|
||
- keyboard focusを不可視にしない。
|
||
- tab orderを画面上の順序と一致させる。
|
||
- stateをcolorだけで区別しない。
|
||
- horizontal scroll regionをkeyboard focus可能にし、accessible nameを与える。
|
||
|
||
## 3. Primitives / Tokens
|
||
|
||
### Color / Theme
|
||
|
||
colorはCSS custom propertyをauthorityとし、通常のWorkspace colorはOKLCHで定義する。lightとdarkは同じsemantic token名を使う。
|
||
|
||
```css
|
||
--bg
|
||
--bg-raised
|
||
--bg-subtle
|
||
--line
|
||
--line-strong
|
||
--text
|
||
--text-strong
|
||
--text-muted
|
||
--text-faint
|
||
--code
|
||
--accent
|
||
--accent-muted
|
||
--success
|
||
--warning
|
||
--danger
|
||
--interactive-hover
|
||
--interactive-selected
|
||
--shadow-overlay
|
||
```
|
||
|
||
- `--bg`、`--bg-raised`、`--bg-subtle`へhueを持たせない。
|
||
- accentはfocus、current navigation、current selectionだけに使い、通常本文や通常actionの背景へ使わない。
|
||
- success、warning、dangerを、それぞれ対応するstate以外へ使わない。
|
||
- componentへraw colorを追加せず、上記semantic tokenを使う。
|
||
- ConsoleとterminalのANSI paletteを通常のstatusやformへ流用しない。
|
||
|
||
### Typography
|
||
|
||
font sizeは、その領域でユーザーが行う読み方によって選ぶ。
|
||
|
||
- defaultは`14px / 20px`とし、個々のtextを読むこと自体がtaskの中心になる領域に使う。
|
||
- 同じ構造の反復を一覧として走査する領域と、位置、順序、形、選択状態を中心に識別するUI chromeには`12px / 16px`を使う。textを読まなければactionの意味や結果を判断できない場合は`14px / 20px`を使う。
|
||
- `24px / 32px`はページまたはdocument内で唯一かつ最大のheadingだけに使う。
|
||
- 収めるため、または情報を弱く見せるためにfont sizeを下げない。`12px`未満と`13px`を使わない。
|
||
- 機械的な値にはmonospace familyを使う。
|
||
|
||
```css
|
||
--font-sans
|
||
--font-mono
|
||
--font-size-title /* 24px */
|
||
--line-height-title /* 32px */
|
||
--font-size-body /* 14px */
|
||
--line-height-body /* 20px */
|
||
--font-size-compact /* 12px */
|
||
--line-height-compact /* 16px */
|
||
```
|
||
|
||
### Spacing / Shape
|
||
|
||
```css
|
||
--space-1 /* 4px */
|
||
--space-2 /* 8px */
|
||
--space-3 /* 12px */
|
||
--space-4 /* 16px */
|
||
--space-5 /* 24px */
|
||
--space-6 /* 32px */
|
||
--radius-soft
|
||
```
|
||
|
||
- 一つの境界にspacing、line、surface backgroundを重ねず、primary cueを一つだけ使う。
|
||
- 汎用的な`Card` primitiveを設けない。
|
||
- nested surfaceでparentと同じ境界表現を繰り返さない。
|
||
- shadowは通常flowから浮くmenu、popover、Tooltipだけに使う。
|
||
- radiusはinteractive controlだけに使う。
|
||
|
||
### Motion
|
||
|
||
- motion完了をactionの受付、state change、content理解の条件にしない。
|
||
- 繰り返しまたは連続animationを、`prefers-reduced-motion: reduce`で停止する。
|
||
|
||
## 4. Components / Patterns
|
||
|
||
### Border / Structural edge
|
||
|
||
- `Bevel`は1pxの単色borderを描くvisual wrapperであり、照明、raised／inset、ridge／grooveを表現しない。
|
||
- `Bevel`自体へbackgroundやsurface toneを与えず、必要なbackgroundは内側のsemantic childが持つtext/content areaへ適用する。
|
||
- 隣接するsurfaceでは、実際に境界となる辺だけを有効にする。
|
||
- standaloneな閉じた領域は全辺を`Bevel`で囲う。Desktop shellではHeaderのbottom edgeとSidebarのright edgeだけを有効にし、viewport外周のtop／left edgeを描かない。
|
||
- `BevelLine`は開いた領域内の1px separatorだけに使う。同じlayerではheading、本文、Lineの端を揃え、Lineだけに端方向のpaddingやmarginを追加しない。
|
||
- nested layerでは親layoutがそのlayer全体へinline方向の余白を与え、content、row、Lineを一緒に移動する。Lineだけを短くしない。
|
||
- control自身のborder、focus ring、status marker、table gridを`Bevel`または`BevelLine`で置き換えない。
|
||
|
||
### Sidebar
|
||
|
||
- Desktop幅は`clamp(220px, 20vw, 280px)`とする。
|
||
- navigation contentだけをscrollさせる。
|
||
- Desktopのfold controlはSidebar下部、Mobileのfold controlはHeaderに置く。
|
||
- MobileでSidebarを表示するときはHeader下の残りviewport全体を使い、main contentと同時表示しない。
|
||
- navigationとscope control以外を置かない。
|
||
- navigation linkはSidebar幅全体を使うflat rowとする。
|
||
- active routeは一つの視覚cueと`aria-current="page"`で示す。
|
||
- iconだけでnavigation labelを置き換えない。
|
||
- fold controlは一つだけ置き、current stateに対応するaccessible nameを使う。
|
||
|
||
### Tooltip / Contextual help
|
||
|
||
- operationやtable全体を説明する常設proseを置く前に、button labelとcolumn headingだけで識別できるようにする。
|
||
- labelだけでは表現できない補助説明だけを、対象へbindしたTooltipに入れる。
|
||
- pointer hoverとkeyboard focusの両方で開く。
|
||
- triggerとTooltipを`aria-describedby`で関連付ける。
|
||
- hoverはdelay後、focusは直ちに表示する。
|
||
- `Escape`で閉じ、triggerからfocusを移動しない。
|
||
- 複数paragraph、form、link、buttonを入れない。
|
||
- error、permission、validation constraint、不可逆操作の結果、current stateをTooltipへ入れない。
|
||
- touch環境ではTooltipだけを説明への到達手段にしない。
|
||
|
||
### Generic component patterns
|
||
|
||
- **Form field**: label、control、constraintまたはhelp、field errorの順に配置する。
|
||
- **Key-value**: 一つのresourceの属性には`dl`を使う。
|
||
|
||
Design-labではcomponent名と実際のsampleだけを表示する。規則とrationaleをUIへ書かない。
|