feat: establish workspace web design language

2026-09-17 01:31:54 +09:00
parent c8eb767d63
commit ab6450b9fe
39 changed files with 3626 additions and 614 deletions
@@ -0,0 +1,104 @@
+# Workspace Web Application Architecture
+
+この文書は、Workspace Webのapplication shell、Header、Sidebar、nested
+layoutのcomposition authorityを定義する。Navigation
+IAは[`product-ux.md`](product-ux.md)、視覚とinteractionの共通規則は[`design-language.md`](design-language.md)、具体的なsource
+pathとCSS
+ownershipは[`../../../web/workspace/README.md`](../../../web/workspace/README.md)を参照する。
+
+## Application shell
+
+root layoutが唯一のapplication shellを所有する。
+
+- Sidebar frame
+- global fallback navigation
+- Header frame
+- main content
+- SidebarとHeaderのoverride context
+
+page routeはapplication shell、global Header、Sidebar、fold
+controlを再実装しない。Pageのmarkupは標準shellのmainへ配置するcontentから始める。
+
+## Header composition
+
+Headerはroot shellが一度だけrenderする。Nested
+layoutは`HeaderOverride`を通じて現在scopeのlocation contentを登録する。
+
+- page componentはHeader frameを作らない。
+- 最も深いactive overrideを表示する。
+- layoutが破棄されたら直前のoverrideへ戻る。
+- overrideがなければroot fallbackを表示する。
+- route titleをmain contentへ複製しない。
+
+## Sidebar composition
+
+### Root
+
+root shellは`SidebarFrame`と`GlobalSidebar`を一度だけrenderし、root
+`SidebarController`を提供する。Overrideがない場合、`GlobalNavSections`がfallbackになる。
+
+### Workspace
+
+Workspace layoutは、親のroot
+slotへ`WorkspaceSidebar`を登録する。同時に、さらに深いlayoutが使う新しい`SidebarController`をcontextへ設定する。
+
+`WorkspaceSidebar`はWorkspace shortcut headerを保持し、その下へchild
+slotをrenderする。Child overrideがない場合だけ、Workspace navigation
+fallbackを表示する。
+
+### Settings
+
+Settings layoutは、Workspace layoutが提供したchild
+slotへ`SettingsSidebar`を登録する。Workspace shortcut headerは残り、Workspace
+navigation fallbackだけがSettings navigationへ置き換わる。
+
+さらに深いscopeも同じcontractを使う。
+
+## Override stack
+
+`HeaderOverride`と`SidebarOverride`は、layout lifecycleにbindしたLIFO
+stackとして扱う。
+
+1. Layout mount時にparent controllerへregisterする。
+2. Controllerは最も新しいactive registrationを表示する。
+3. Nested layoutはchild controllerを新しく提供する。
+4. Layout destroy時に自分のregistrationをremoveする。
+5. 一つ前のregistrationがあれば復元する。
+6. Stackが空ならfallbackへ戻る。
+
+同じregistrationを複数回removeしても結果を変えない。古いcleanupが新しいactive
+registrationを削除してはならない。
+
+## Ownership
+
+- `SidebarFrame`だけが`aside`、外枠、scroll領域、fold controlを所有する。
+- `GlobalSidebar`、`WorkspaceSidebar`、`SettingsSidebar`は各scopeのcontentを所有する。
+- `SidebarOverride`を登録できるのはscopeを定義するlayoutだけとする。
+- page component、一時的なwidget、dialogはSidebarを差し替えない。
+- child layoutは親navigationをcopyせず、自分のsidebar layerだけをregisterする。
+- Global、Workspace、Settingsを一つのsnippetへ平坦化しない。
+
+## Data authority
+
+Sidebar compositionはnavigation
+structureを決めるが、Workspace、permission、Worker
+stateのauthorityにはならない。
+
+- Workspace identityとpermissionはBackend projectionを使う。
+- Worker listとstateはWorkspace protocol projectionを使う。
+- route pathやdisplay labelからauthorityを推測しない。
+- unavailable dataを架空の正常stateで置き換えない。
+- permissionにより利用できないnavigationは、権威あるpermission
+  projectionに基づいて除外する。
+
+## Design-lab
+
+認証不要のstatic design-labはroot shellを再利用し、実際と同じnested
+controllerとoverride stackを構成する。
+
+Live Workspace protocolへbindするresource listだけは、同じscope layer内のstatic
+fixtureへ置き換えてよい。Static fixtureへ別scopeのnavigationを混ぜず、production
+componentと同じ順序、state表現を使う。
+
+Design-lab固有のswitch controlでSidebarを差し替えず、route
+hierarchyによってlayout lifecycleを発生させる。
@@ -0,0 +1,304 @@
+# Workspace Web Design Language
+
+この文書は、Workspace Webをどう知覚させ、情報、状態、操作をどの視覚文法で表現するかを定義する。Product固有のresource構成は[`product-ux.md`](product-ux.md)、application shellとSidebar slotの実装構造は[`application-architecture.md`](application-architecture.md)、CSSとsource配置は[`../../../web/workspace/README.md`](../../../web/workspace/README.md)をauthorityとする。
+
+一つの規則は、次の4階層のうち最も具体的な一箇所だけをauthorityとする。別の章で同じ禁止や手段を再掲せず、必要な場合はauthorityとなる章を参照する。
+
+## 1. Principles
+
+なぜこの設計にするかを定義する。個別の表示規則に迷った場合は、この章へ戻って判断する。
+
+### 基本思想
+
+- 作業ツールとして、シンプルで直感的なUX
+- UIのために曖昧な情報を推測しない。データを正直に表示し、操作を見通せるようにする
+- 状態・scope・操作を、装飾ではなく構造で読ませ、情報量を増やしても騒がしくならない
+- 説明的に見せるのではなく、配置と関係で理解させる
+
+### 知覚原則
+
+size、weight、color、spacing、line、background、motionを使うときは、次のどの知覚を成立させるためか説明できなければならない。説明できない視覚表現は追加しない。
+
+#### Hierarchy — 何が重要か
+
+- 情報は、primary、secondary、technicalの順に読む構造にする。
+- 重要度は、最初に配置順、次にsize、weight、contrastで示す。colorや装飾だけで重要度を作らない。
+- 同じscopeに最も強いheading、filled action、attention表現を複数置かない。
+- primary contentと、その判断に必要なstateまたはactionを初期viewportへ置く。
+- metadataと補助操作は、主要なidentityやcurrent stateより強く見せない。
+
+#### Grouping — 何と何が同じグループか
+
+- 同じ判断や操作に使う情報は、一つのまとまりとして知覚できるようにする。
+- groupの単位は、共通のownership、behavior、またはユーザーが行う一つの判断から決める。
+- label、value、help、error、actionの対応関係を、別の説明を読まなくても追えるようにする。
+- data sourceやDTOが同じという理由だけでgroup化しない。
+- 一つの関係へ複数の視覚cueを重ねず、何がgroupを成立させているか一つに定める。
+
+#### Separation — 何が別物か
+
+- 異なるgroupの境界を知覚でき、その強さが意味上の距離と一致するようにする。
+- すべての境界について、何と何を分けているか説明できなければならない。
+- 一つの意味上の境界へ複数のseparation cueを重ねない。
+- 境界がどのgroupの開始または終端を示すか、読み順から判別できるようにする。
+- 異なるhierarchyの境界をすべて同じ強さで表現しない。
+
+#### Affordance — 何が操作できるか
+
+- actionにはbutton、navigationにはlink、選択にはcontrolを使い、役割を見た目とsemantic elementで一致させる。
+- interactive elementは、通常、hover、focus、active、disabledを区別できるようにする。
+- staticなstatus、key、metadataをbuttonやpillの形にしない。
+- clickable rowは、click可能な範囲と遷移先を一つにする。
+- permissionがない操作をdisabled controlとして見せることでaffordanceを偽らない。
+
+#### State — 現在どういう状態か
+
+- 権威を持つdata sourceのstateをそのまま表示し、UIの都合でunknown、stale、unavailableを推測で埋めない。
+- stateは対象resourceまたはoperationの近くに置き、何のstateかを位置関係で判別できるようにする。
+- stateはmarkerとtextで示し、colorを補助に使う。
+- loading、empty、error、permission denied、unavailable、staleを別の状態として扱う。
+- 非同期operationでは、開始、処理中、完了、失敗を見通せるようにする。
+
+#### Focus — 今どこを見るべきか
+
+- 一つのscopeでは、primary resource、current attention、next actionのいずれか一つを最初のfocusにする。
+- accent、filled action、強いcontrast、motionを複数箇所で競合させない。
+- normal stateは静かに保ち、attention表現は現在判断が必要な例外へ限定する。
+- 視覚的なfocusとkeyboard focusを一致させる。
+- focusを作るために周囲の情報を過度に薄くしたり、小さくしたりしない。
+
+### 検証原則
+
+この文書はrendered resultが満たす設計規則を定義する。実装者自身がbefore/afterをcaptureし、grouping、separator、spacing、wrapping、responsive、stateを目視して完了判定する手順は、[`visual-review.md`](visual-review.md)をauthorityとする。
+
+## 2. Semantics / Grammar
+
+何を、どの関係と意味で表現するかを定義する。
+
+### 情報階層
+
+route titleはshell headerとmain contentを通じて一度だけ表示する。
+
+- 標準headerまたはbreadcrumbが現在routeを十分に識別している場合、main contentは最初の操作対象またはsectionから始める。
+- shell headerがscopeだけを示し、main contentの対象を識別できない場合に限り、main側へ一つのtitleを置く。
+- primary actionは、そのactionがpage全体の主要操作である場合だけtitleと同じrowへ置く。
+- route分類、breadcrumb、header titleをeyebrow、heading、keyで繰り返さない。
+- subtitleとledeは原則として置かない。
+
+一つのsectionは、一つの目的、ownership、または読み順を持つ。目的が異なる内容を同じsectionへ入れず、同じ目的の内容を見た目だけで複数sectionへ分けない。Section間とsection内の関係は`Principles`のGroupingとSeparationに従い、具体的なcueは`Primitives / Tokens`だけから選ぶ。
+
+### Metadata
+
+主要表示に置くのは、identity、healthまたはattention、比較、次の操作に必要な値だけとする。
+
+次の値は通常、label付きのdetail、debug、copy affordanceの後ろへ置く。
+
+- 内部ID
+- schema、config、recordのrevision
+- digestとfingerprint
+- provider diagnostics
+- authority source label
+- raw requestまたはresponse payload
+
+機械的な値にはmonospace familyを使う。DTOに値が存在することだけを理由に表示しない。
+
+### 段階的な開示
+
+- primary viewにはidentity、current state、attention、次の有効なactionを表示する。
+- 副次的な運用情報はplain section、side panel、またはlabel付き`details`へ置く。
+- debug evidenceとraw metadataは、ユーザーが明示的に開いた場合だけ表示する。
+- destructive controlは、ユーザーが該当flowへ入るまでprimary actionより弱く表示する。
+- create formとedit formは明示的なactionの後に表示する。
+- blocking error、permission requirement、validation constraint、unsaved changeを閉じたdisclosureへ隠さない。
+
+### Authority、権限、操作
+
+- permissionはcontrolのenabled状態だけでなく、表示構成そのものへ反映する。
+- readは可能だがmutationできない場合、有用なread viewだけを構成する。
+- endpointからdataを取得できたかどうかでpermissionを推測しない。
+- domain stateとtransport stateを混同しない。
+- current stateで有効なactionだけを利用可能として提示する。
+- destructive actionには対象と結果を明記し、復元できない場合は意図的なconfirmationを要求する。
+- 同じscopeのfilled primary actionは一つだけとする。
+
+### Loading、empty、error、unavailable
+
+#### Loading
+
+- page frameとsection位置を維持する。
+- scopeが明らかでない場合は、何を読み込んでいるか示す。
+- page全体を中央spinnerへ置き換えない。
+- spinnerだけに意味を持たせない。
+
+#### Empty
+
+- absenceを直接表現する。
+- permissionがあり、actionが実際に利用できる場合だけ、次のactionを一つ提示する。
+- recordが存在しない状態と、読み込めなかった状態を区別する。
+
+#### Error
+
+- field validationは対象fieldの近くに置く。
+- operation errorは失敗したactionの近くに置く。
+- section load errorは対象section内に置き、利用できるsibling sectionは残す。
+- routeの主要目的を果たせない場合だけroute-level errorにする。
+- diagnosticsはboundedかつactionableにする。
+
+#### Unavailableとpermission
+
+resource unavailable、capability missing、permission deniedを別の状態として扱う。`403`をempty listとして表示したり、別scopeへredirectしたりしない。
+
+### 文言
+
+- 具体的な名詞と動詞を使う。
+- identifier、API名、type名は正確性が必要な場合に原文を維持する。
+- title、navigation label、明らかなcontrol behavior、componentの存在理由を説明文で繰り返さない。
+- proseを追加するのは、判断を変える具体的な情報、warning、permission、validation constraint、error recoveryに必要な場合だけとする。
+- empty copyとstatus copyは短く、事実を直接書く。
+- buttonは操作を表す。`Submit`、`OK`、装飾的なcategory labelを避ける。
+
+### Responsive
+
+- page全体にhorizontal scrollを発生させない。
+- board、table、code view、terminalは、自分の範囲内でbounded horizontal scrollを所有してよい。
+- side-by-side表示が同じ判断を支えなくなった場合、一列にする。
+- stack化によって比較関係が失われる場合、比較面を横方向に維持する。
+- primary actionを初期viewportから追い出さない。
+- touch targetの操作性を維持し、overflow解消のためにtextを縮小しない。
+- 長いkey、ref、diagnosticはwrapまたはtruncateし、完全な値へaccessできる手段を用意する。
+
+### Accessibility
+
+- semantic elementを使う。
+- すべてのcontrolに明示的なaccessible nameを与える。
+- keyboard focusを常に見えるようにする。
+- tab orderを画面上の順序と作業順に合わせる。
+- icon-only controlには具体的な`aria-label`を付ける。
+- stateはcolor以外のtextまたはsemantic distinctionを持つ。
+- 必要なhorizontal scroll regionはfocus可能にし、accessible nameを付ける。
+- lightとdarkで同じsemantic tokenを使う。
+
+## 3. Primitives / Tokens
+
+色、文字、間隔、形、motionの最小単位を定義する。
+
+### 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
+--bevel-highlight
+--bevel-shadow
+--bevel-face-width
+--shadow-overlay
+```
+
+- backgroundとlayout surfaceはneutralにする。
+- muted textは新しいhueを増やす前にlightnessとchromaを下げる。
+- accentとstatus colorはstate、focus、navigationへ限定する。
+- componentへraw colorを追加せず、semantic tokenを使う。
+- `--bevel-highlight`と`--bevel-shadow`はBevel共通の照明endpointとし、componentのbackgroundから派生させない。Bevel wrapper、`profile`、`depth`、描画辺へsurface色を与えてはならず、Bevelはedge lightingだけを所有する。背景色を変更できるのは内側のsemantic childが所有するtext/content areaだけとする。
+- Bevelの一面の幅はproject-wideな`--bevel-face-width: 2px`へ固定し、component APIから変更させない。`edge`は一面2px、`ridge`と`BevelLine`は二面を重ねた合計4pxとする。
+- Bevelのgeometryは`profile = edge | ridge`、凹凸方向は`depth = raised | inset`として直交させる。`ridge + inset`はgrooveを表す。Lineも`depth = raised | inset`を使う。
+- Box Bevelは`top`、`right`、`bottom`、`left`で描画辺を個別に選べる。defaultは全辺有効とし、角丸はその角に隣接する2辺がともに有効な場合だけ描画する。ridgeの内側面も有効辺からだけinsetする。
+- 独立した構造separatorは`BevelLine`を使い、片側のsolid borderで代用しない。外周border、focus ring、status marker、表の意味的なgridは別のprimitiveとして扱う。
+- 意味が重なるtoken aliasを作らない。
+
+ConsoleとterminalのANSI paletteは専用tokenを使い、通常のstatusやformへ流用しない。
+
+### Typography
+
+| 用途                                   | size / line height | 使用箇所                      |
+| -------------------------------------- | ------------------ | ----------------------------- |
+| Route title                            | `24px / 32px`      | shellまたはmainのどちらか一方 |
+| Body、control、row、section title      | `14px / 20px`      | contentとinteraction          |
+| Metadata、table heading、machine value | `12px / 16px`      | 副次情報と機械的な値          |
+
+```css
+--font-sans
+--font-mono
+```
+
+別のfont sizeを増やす前に、配置、spacing、weight、muted colorでhierarchyを作る。textを`12px`未満へ縮小しない。
+
+### Spacing / Shape
+
+```css
+--space-1 /* 4px */
+--space-2 /* 8px */
+--space-3 /* 12px */
+--space-4 /* 16px */
+--space-5 /* 24px */
+--space-6 /* 32px */
+--radius-soft
+```
+
+- groupingはspacingとalignmentを最初のcueとする。
+- separationにはspacing、line、surface backgroundのいずれか一つをprimary cueとして選ぶ。
+- 汎用的な`Card` primitiveは設けない。
+- nested surfaceはparentと同じ境界表現を繰り返さない。
+- shadowは通常flowから浮くmenu、popover、Tooltipなどの一時的overlayだけが使用できる。
+- radiusはinteractive controlだけが使用できる。
+
+### Motion
+
+- motionは任意かつ短くし、意味の必須条件にしない。
+- 繰り返しまたは連続animationではreduced-motion preferenceを尊重する。
+
+## 4. Components / Patterns
+
+実際のUIを、上のprinciple、grammar、tokenから組み立てる。完成pageを固定templateにしない。
+
+### Sidebar
+
+- Sidebarは現在位置と利用可能なscopeを一つのnavigation hierarchyとして示す。
+- desktop幅は`clamp(220px, 20vw, 280px)`を基本とする。
+- navigation contentだけをscrollさせ、fold controlはframe下部に残す。
+- navigationとscope controlだけを置く。
+- navigation linkはsidebar幅全体を使うflat rowとする。
+- active stateは一つのcueと`aria-current="page"`で示す。
+- iconだけでlabelを置き換えない。
+- fold controlは一つだけ置き、現在stateに対応するaccessible nameを使う。
+- narrow viewportでも同じSidebarの意味とnavigation hierarchyを維持する。
+
+### 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環境でも同じ説明へ到達できるようにする。
+
+### 汎用component pattern
+
+- **Action**: `primary`、`secondary`、`text`、`destructive`、`disabled`を同じ高さ、padding、focus contractで表現する。
+- **Form field**: label、control、constraintまたはhelp、field errorの順に配置する。
+- **Status**: markerと短いtextを一組にする。
+- **Feedback**: loading、empty、operation error、permission boundaryを別の状態として表現する。
+- **Resource row**: keyまたはname、判断に必要なmetadata、attentionまたはstate、一つのdestinationを置く。
+- **Comparable data**: 同じfieldを比較する場合だけtableを使う。
+- **Key-value**: 一つのresourceの属性には`dl`を使う。
+- **Disclosure**: secondary metadataやdiagnosticは具体的なlabelを持つ`details`などへ置く。
+
+Design-labではcomponent名と実際のsampleだけを表示する。規則とrationaleをUIへ書かない。
@@ -0,0 +1,143 @@
+# Workspace Web Product UX
+
+この文書は、Workspace Webで扱うresource、navigationのinformation
+architecture、resourceごとの主要taskを定義する。見せ方の共通文法は[`design-language.md`](design-language.md)、application
+shellとSidebar
+slotは[`application-architecture.md`](application-architecture.md)を参照する。
+
+## Product position
+
+Workspace
+Webは、Workspace内の権威ある状態を確認し、注意が必要な箇所を判断し、一度に一つの操作を行うための作業面である。Marketing
+dashboard、analytics画面、Backend DTOのraw viewerにはしない。
+
+基本的な操作の流れは次とする。
+
+```text
+scopeを選ぶ
+→ resourceを選ぶ
+→ current stateを確認する
+→ 次の有効なactionを行う
+→ 結果を確認する
+```
+
+## Resource
+
+主要resourceは次のとおり。
+
+- Workspace
+- Ticket
+- Objective
+- Merge Request
+- Memory
+- Worker
+- Workdir
+- Runtime
+- Repository
+
+通常の表示とURLにはcanonical resource keyを使う。内部UUIDをlabelやfallback
+linkとして露出しない。
+
+## Navigation IA
+
+### Global
+
+Workspaceを選ぶ前のscopeを扱う。
+
+- Workspace catalog
+- Account
+- Device Login
+- Workspace作成
+
+### Workspace
+
+一つのWorkspace内で日常的に扱うresourceを置く。
+
+1. Tickets
+2. Objectives
+3. Merge Requests
+4. Memory
+   - Document
+   - Staging
+5. Workers
+
+### Settings
+
+Workspaceの管理と構成を扱う。
+
+- Runtimes
+- Configuration Sources
+- Repositories
+- Repository Access
+- Profile Sources
+- Workspace Identity
+
+`Runtimes`、`Repositories`、`Repository Access`をWorkspace primary
+navigationへ混ぜない。permissionにより利用できないSettings itemは表示しない。
+
+## Page model
+
+各routeは、主要な目的を一つだけ持つ。その目的は「Ticketを選ぶ」「このWorkerを確認する」「Repository
+accessを設定する」のように、動詞と対象を一つずつ使って表現できなければならない。
+
+Workspace pageは、次のいずれかを基本形とする。
+
+1. **一覧またはboard** — resourceを探し、注意が必要な項目を見つける。
+2. **詳細** — 一つのresourceを理解し、現在実行できる次の操作を行う。
+3. **formまたはeditor** — 範囲の明確な設定変更を行う。
+4. **Console** — 一つのWorkerを操作しながら、履歴とcurrent controlを確認する。
+
+同じ目的を支える場合に限り、一つのrouteで複数の基本形を組み合わせてよい。
+
+## Product pattern
+
+### Tickets
+
+- boardを一つの横方向の作業面として扱う。
+- laneはworkflow stateを表し、隣接laneとの関係を維持する。
+- Ticketはlane内でDesign Languageの`Resource row` patternを使う。
+- Ticket key、title、優先判断を変えるmetadataだけを表示する。
+- blockerとattentionはtextでも示す。
+- narrow viewportでは、bounded horizontal scrollでlane比較を維持する。
+
+### Resource index
+
+- 同じfieldをresource間で比較する場合、flat listまたはtableを使う。
+- 人が読むnameとcanonical keyを最初のcolumnに置く。
+- columnは判断に必要な値だけに絞る。
+- provider detail、revision、digestはdetailまたはtechnical disclosureへ移す。
+
+### Resource detail
+
+- identity、current state、attentionを最初に置く。
+- narrativeまたはhistoryをprimary領域に置く。
+- relation、target、review、workflowが別のauthorityを持つ場合、それぞれを独立したsectionにする。
+- raw metadataはtechnical disclosureへ置く。
+
+### Settingsとform
+
+- 一つのSettings routeは一つの設定関心事を所有する。
+- edit actionの前または同時に、現在有効な値を示す。
+- 一つの判断に必要なfieldをgroup化する。
+- narrow viewportでは一列にする。
+- form内でfilled actionにするのはsave actionだけとする。
+
+### Worker Console
+
+- transcriptをprimary surfaceとする。
+- direct SubWorkerを表示している場合も、Composerとrun
+  controlは親Workerへbindしたままにする。
+- OverviewとNormalはpresentationだけを変え、authorityを変えない。
+- command outputはterminalに近いcompactな表示とし、prose messageから分離する。
+- live stateは権威あるWorker snapshotから導出する。
+- connection stateやtransient eventでcurrent stateを置き換えない。
+- hidden reasoningとraw system promptはdebug modeでも表示しない。
+
+## Stateとpermission
+
+- 存在しない、閲覧できない、読み込みに失敗したWorkspaceを別の状態として扱う。
+- 別のWorkspaceへ暗黙に切り替えない。
+- owner-only mutation controlをnon-ownerへ表示しない。
+- read-onlyの場合は、有用なread viewを残す。
+- Workerのdomain stateとWebSocket connection stateを混同しない。
+- Mergeなど不可逆または重要なoperationは、対象と結果を明示してから実行する。
@@ -0,0 +1,272 @@
+# Web visual review
+
+この文書は、Web UIを変更する実装者が完了前に行うvisual
+reviewの必須手順を定義する。Visual reviewは任意のpolish工程ではなく、type
+check、linter、testと並ぶvalidationである。
+
+[`design-language.md`](design-language.md)はWorkspace
+Webが満たす視覚とinteractionの共通規則を定義する。Product固有の構成は[`product-ux.md`](product-ux.md)を参照する。[`tools/web-ux/README.md`](../../../tools/web-ux/README.md)はcapture
+toolの操作方法を定義する。この文書は、誰が、いつ、何を目視し、どの証拠を残さなければ実装完了とみなせないかを定義する。
+
+## 実装者の責任
+
+Visual
+reviewは、後段のReviewerやユーザーへ最初の発見を委ねない。UIを変更した実装者自身が、同じ変更の中で次を行う。
+
+1. 変更前をcaptureする。
+2. 変更後を同じ条件でcaptureする。
+3. screenshotとbrowser evidenceを自分で確認する。
+4. 発見した問題を修正する。
+5. 修正後を再captureして確認する。
+6. 変更と無関係な既存問題は、根拠を付けて分離する。
+
+Agentが実装者の場合、そのAgent自身が`ViewImage`または同等のVLM入力で実画面を確認する。captureを生成しただけ、別のAgentへ画像を渡しただけ、HTTP
+200を確認しただけでは完了しない。
+
+## 適用範囲
+
+次の変更ではvisual reviewを必須とする。
+
+- page、layout、navigation、Sidebar、Header、Console、dialog
+- componentのmarkupまたはstyle
+- color、typography、spacing、border、radius、shadow、theme token
+- copy、label、status、empty/loading/error/permission表示
+- responsive breakpoint、container、overflow、scroll
+- 表示dataの追加、削除、並び替え、progressive disclosure
+- icon、focus、keyboard interaction、motion
+- UIへ影響するgenerated typeまたはAPI projection
+
+型、Backend、CLI、文書だけの変更でrendered Web
+UIが変わらない場合は省略できる。省略する場合は、UIへ影響しない理由をvalidation
+evidenceへ一文で残す。
+
+## 必須の確認条件
+
+変更したsurfaceに関係する条件だけを選ぶが、都合のよい一画面だけに限定しない。
+
+### Persona
+
+権限やdataが表示を変える場合は、該当するpersonaを分ける。
+
+- owner
+- non-owner
+- anonymous
+- read-onlyまたは操作権限なし
+
+owner表示だけでpermission-aware UIを承認しない。
+
+### Viewport
+
+最低限、次を確認する。
+
+- desktop: `1440px`幅を基準
+- narrow: Sidebarとmainが競合する幅。現在は`768px`を基準
+- mobile: `390px`幅を基準
+
+`320px`対応、table、long form、Console、Sidebar
+foldなどが変更対象なら、その境界も追加する。media
+queryのviewport幅だけでなく、Sidebarやpanelを差し引いた実際のcontent幅を確認する。
+
+### Theme
+
+color、border、background、focus、status、code、terminalを変更した場合はlightとdarkの両方を確認する。片方のthemeで読めることを、もう片方のcontrastの証拠にしない。
+
+### Data state
+
+該当するstateを明示的に用意する。
+
+- representative data
+- empty
+- loading
+- error
+- permission deniedまたはread-only
+- long title、long key、long error、複数行content
+- collectionの最小件数と、実際に起こりうる多い件数
+
+happy pathだけでcomponentを承認しない。
+
+## 目視確認の観点
+
+### 情報のまとまり
+
+- 同じ判断に使う情報がproximity、alignment、typographyによって一つのgroupに見えるか。
+- 別の意味を持つ情報が、十分な距離または一つの明確なboundaryで分離されているか。
+- 親子、peer、metadata、actionの関係が、DOMを読まなくても判別できるか。
+- card、background、border、shadow、余白を重ねて同じgroupingを重複表現していないか。
+- page title、Header、breadcrumb、section
+  heading、説明文が同じ意味を繰り返していないか。
+
+### Separatorとborder
+
+画面上のすべての線について、何と何を区切る線か説明できなければならない。
+
+- Headerの終端、peer row間、section開始、table
+  cellなど、線の役割が一つに定まっているか。
+- 近接した二本の線が同じboundaryを重複表現していないか。
+- 線の上下の余白から、その線が前後どちらのgroupに属するか分かるか。
+- すべてのsectionへ機械的に同じ線を置き、hierarchyを平坦化していないか。
+- borderがなくてもspacingだけで十分な箇所へ線を追加していないか。
+
+### Spacingとdensity
+
+- 余白がtoken scaleに沿い、近い関係ほど狭く、別groupほど広くなっているか。
+- labelとvalue、headingとcontent、rowとrow、sectionとsectionの間に一貫した大小関係があるか。
+- 線の前後へ同程度の大きな余白を置き、boundaryの所属を曖昧にしていないか。
+- 初期viewportにprimary contentまたは主要操作が存在するか。
+- 空きすぎた領域が情報不足やhierarchyの弱さを隠していないか。
+- 密度を上げるためにfont、touch target、line heightを過度に縮めていないか。
+
+### Wrapping、overflow、可変長content
+
+- 実際に起こりうる最長のlabel、title、key、ref、error、翻訳で確認したか。
+- 一行を前提とするcontrolが意図せず二行にならないか。
+- button labelが折り返されたとき、row heightとalignmentが壊れないか。
+- title、metadata、code、URLが隣接actionを押し出さないか。
+- truncateする場合、完全な値へaccessできるか。
+- horizontal
+  scrollはtable、board、terminalなど、その意味を所有する領域だけに閉じているか。
+- page全体へhorizontal overflowが発生していないか。
+- `overflow-wrap`だけで問題を隠さず、可読性と比較可能性を維持しているか。
+
+### Responsive layout
+
+- DOM順、視覚順、keyboard順が一致しているか。
+- Sidebar、Header、primary contentの順序がmobileでも目的に合うか。
+- Sidebarだけで初期viewportを占有していないか。
+- breakpoint直前と直後の両方で、content幅とcontrol配置が成立するか。
+- viewport
+  queryだけでなく、containerの実幅に応じて一列化またはscrollを選べているか。
+- desktopの比較関係を、理由なくmobile cardへ変換していないか。
+
+### Typographyとcopy
+
+- route titleが画面上で一度だけ表示されているか。
+- page purpose、componentの存在理由、設計意図を説明するmeta
+  copyが残っていないか。
+- proseが判断、warning、constraint、permission、recoveryのいずれかに実際に必要か。
+- heading level、font size、weight、colorが同じhierarchyで揃っているか。
+- metadataがbodyより強く見えていないか。
+- uppercase、letter spacing、monospaceを装飾目的で多用していないか。
+
+### State、permission、action
+
+- loading、empty、error、permission denied、unavailableが見分けられるか。
+- statusがcolorだけに依存していないか。
+- 利用できないowner-only actionをdisabledで並べるのではなく、page
+  compositionから除外できているか。
+- filled primary actionが同じscopeに複数ないか。
+- destructive actionが通常のprimary pathと誤認されないか。
+- errorとrecovery actionが、失敗したsurfaceの近くにあるか。
+
+### Interactionとaccessibility
+
+- keyboard focusが全controlで見えるか。
+- focus順が画面の作業順と一致するか。
+- fold、disclosure、dialog、menuを操作した後にfocusが失われないか。
+- hoverでしか得られない必須情報がないか。
+- scroll region、icon-only control、status markerにaccessible
+  nameまたはtextがあるか。
+- reduced motionで意味が失われないか。
+
+## 実行手順
+
+### 1. Scenarioを決める
+
+変更対象route、persona、viewport、theme、data state、capture
+pointを列挙する。既存scenarioが目的を満たす場合は再利用し、満たさない場合は同じ変更内で追加または更新する。
+
+### 2. 変更前をcaptureする
+
+`tools/web-ux`を使い、変更前のsourceとscenarioを固定する。出力はrepositoryのproduction
+sourceへ混ぜず、`target/web-ux`などの開発artifact領域へ置く。
+
+### 3. 変更前を目視する
+
+既存問題も含め、変更対象付近のgrouping、separator、spacing、wrapping、responsive、stateを確認する。変更前を見ずに、変更後の印象だけで改善を主張しない。
+
+### 4. 実装する
+
+発見した問題と、適用するUX規則を対応付けて修正する。screenshotだけを整えるfixture固有hackや、productionと異なるshell、CSS、data
+authorityを作らない。
+
+### 5. 同条件で再captureする
+
+persona、route、viewport、theme、data
+stateを揃える。変更後だけ別の好条件へ変えない。
+
+### 6. Screenshotとreview contextを確認する
+
+実装者自身が画像を開き、`review-context.json`も読む。次を確認する。
+
+- document status
+- visible UI error
+- console error
+- page error
+- failed request
+- accessibility snapshot
+- screenshot hashとcapture point
+
+HTTP 200でも画面に`401 Unauthorized`などが表示されていれば失敗とする。
+
+### 7. Compareする
+
+before/afterを比較し、差分が意図した領域に限定されているか確認する。pixel
+differenceの大小だけで合否を決めない。意図しない移動、折返し、欠落、色変化を目視する。
+
+### 8. Testとevidenceを揃える
+
+source test、component test、E2E、type checkを実行し、visual
+evidenceと一緒に記録する。test成功はvisual reviewの代替ではなく、visual
+review成功もtestの代替ではない。
+
+## 合格条件
+
+次をすべて満たした場合だけvisual reviewを合格とする。
+
+- 実装者自身がbefore/afterを目視した。
+- 必要なpersona、viewport、theme、data stateを確認した。
+- grouping、separator、spacing、wrapping、responsiveを確認した。
+- visible、console、page、request errorが解決または明確にdispositionされた。
+- 発見した新規問題を修正し、修正後を再captureした。
+- 意図しないvisual regressionがない。
+- artifact path、scenario、確認結果をhandoffへ記録した。
+
+次は不合格である。
+
+- capture commandが成功しただけ。
+- screenshotを生成したが開いていない。
+- desktopだけ、ownerだけ、happy pathだけを見た。
+- 後段Reviewerまたはユーザーが目視する前提でhandoffした。
+- 「好みの問題」として、説明できないseparator、spacing、overflowを未確認のまま残した。
+- testまたはlinterが成功したため、visual reviewを省略した。
+
+## Evidenceの記録
+
+handoffには最低限、次を記録する。
+
+```text
+Visual review
+- Scenario: <scenario path>
+- Before: <run id or artifact path>
+- After: <run id or artifact path>
+- Personas: <list>
+- Viewports: <list>
+- Themes: <list>
+- Data states: <list>
+- Findings fixed: <bounded list>
+- Known issues: <bounded list with disposition>
+- Result: pass | fail
+```
+
+画像をTicketやGitへ大量にcommitしない。artifact pathとsource
+revisionを結び付け、必要なreviewerが同じ条件を再現できるようにする。認証profile、cookie、token、secret、private
+response bodyをartifactやhandoffへ含めない。
+
+## Toolの位置付け
+
+`tools/web-ux`はbrowser起動、scenario再現、capture、review
+context、compareを提供する。Toolは視覚的な良否を自動決定しない。
+
+Linterが構文規則を検査し、testが特定のbehaviorを検査するのと同様に、visual
+reviewはrendered
+resultの関係性を検査する。三者は補完関係であり、どれか一つで他を代替しない。
@@ -32,6 +32,20 @@ cargo check --workspace

 Avoid repository-wide formatting churn when a validation failure is caused by pre-existing unrelated formatting.

+## Web UI changes
+
+Rendered Web UI changes require implementer-owned visual review in addition to type check, linter, and test. Follow [`ui-ux/visual-review.md`](ui-ux/visual-review.md).
+
+Minimum evidence includes:
+
+- before/after capture under the relevant persona, viewport, theme, and data state;
+- the implementer’s own inspection of grouping, separator meaning, spacing, wrapping, overflow, responsive order, and visible errors;
+- `review-context.json` inspection;
+- disposition of every observed problem;
+- artifact paths and a final `pass | fail` result.
+
+A successful capture command, HTTP 200, screenshot generation, or later Reviewer inspection does not replace this validation.
+
 ## Work item checks

 Run: