feat: establish workspace web design language
This commit is contained in:
+10
-7
@@ -19,13 +19,16 @@ It is not a dumping ground for external research, old plans, API inventories, or
|
||||
11. [`design/memory-knowledge.md`](design/memory-knowledge.md) — generated memory and audit records.
|
||||
12. [`design/workspace-kanban-orchestrator-runtime.md`](design/workspace-kanban-orchestrator-runtime.md) — how Kanban operations become durable orchestration events and backend-internal routing decisions.
|
||||
13. [`design/workspace-runtime-docker.md`](design/workspace-runtime-docker.md) — the WebUI / Backend / Runtime split, Docker image layout, worker launch path, and workdir materialization boundary.
|
||||
14. [`design/workspace-web-ux.md`](design/workspace-web-ux.md) — Workspace Webの情報設計、操作設計、視覚設計、レスポンシブ対応、アクセシビリティ、CSSの責務。
|
||||
15. [`development/server-runtime-auth.md`](development/server-runtime-auth.md) — manual Workspace Server / Runtime public-key exchange and authenticated Runtime startup checks.
|
||||
16. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed.
|
||||
17. [`development/rust-testing-strategy.md`](development/rust-testing-strategy.md) — what Yoi Rust tests should prove, where they belong, and how to name them.
|
||||
18. [`development/validation.md`](development/validation.md) — how to check changes.
|
||||
19. [`development/workspace-schema-migrations.md`](development/workspace-schema-migrations.md) — how to preflight, apply, verify, and roll back control-plane SQLite schema changes.
|
||||
20. [`design/standalone-agent-host.md`](design/standalone-agent-host.md) — in-process standalone Worker host の依存方向、authority、lifecycle、非目標。
|
||||
14. [`development/ui-ux/design-language.md`](development/ui-ux/design-language.md) — Workspace Webの視覚・interaction原則、文法、token、汎用component。
|
||||
15. [`development/ui-ux/product-ux.md`](development/ui-ux/product-ux.md) — Workspace resource、navigation IA、resource固有pattern。
|
||||
16. [`development/ui-ux/application-architecture.md`](development/ui-ux/application-architecture.md) — application shell、Header、Sidebar、nested override architecture。
|
||||
17. [`development/ui-ux/visual-review.md`](development/ui-ux/visual-review.md) — Web UI実装者がbefore/afterを目視し、完了前に残すvisual validation evidence。
|
||||
18. [`development/server-runtime-auth.md`](development/server-runtime-auth.md) — manual Workspace Server / Runtime public-key exchange and authenticated Runtime startup checks.
|
||||
19. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed.
|
||||
20. [`development/rust-testing-strategy.md`](development/rust-testing-strategy.md) — what Yoi Rust tests should prove, where they belong, and how to name them.
|
||||
21. [`development/validation.md`](development/validation.md) — how to check changes.
|
||||
22. [`development/workspace-schema-migrations.md`](development/workspace-schema-migrations.md) — how to preflight, apply, verify, and roll back control-plane SQLite schema changes.
|
||||
23. [`design/standalone-agent-host.md`](design/standalone-agent-host.md) — in-process standalone Worker host の依存方向、authority、lifecycle、非目標。
|
||||
|
||||
## What belongs here
|
||||
|
||||
|
||||
@@ -1,413 +0,0 @@
|
||||
# Workspace Web UX・デザインルール
|
||||
|
||||
状態: レビュー用の正規ルール案
|
||||
|
||||
この文書は、`web/workspace`の情報設計、操作設計、視覚設計、responsive対応、accessibility、CSSの責務を定義する。本番画面はこの文書へ収束させる。現行実装は判断材料ではあるが、ルールそのものではない。この文書と矛盾する既存のマークアップやCSSは、別の有効なパターンではなく移行対象として扱う。
|
||||
|
||||
`docs/.local/workspace-web-pattern-candidate-v1.md`は比較検討に利用できるが、productionの設計authorityではない。
|
||||
|
||||
## 設計の立場
|
||||
|
||||
Workspace
|
||||
Webは、Workspace内のリソースを起点に、権威ある状態を確認し、注意が必要な箇所を判断し、一度に一つの操作を行うための作業面である。宣伝用ダッシュボード、分析画面、Backend
|
||||
DTOのraw viewerにはしない。
|
||||
|
||||
永続化されたBackend
|
||||
recordを状態のauthorityとする。UIは入力途中のdraftを保持したり、操作準備を先行したりしてよいが、推測、cache、通信状態を現在のdomain
|
||||
stateとして表示してはならない。
|
||||
|
||||
## ページモデル
|
||||
|
||||
各routeは、主要な目的を一つだけ持つ。その目的は「Ticketを選ぶ」「このWorkerを確認する」「Repository
|
||||
accessを設定する」のように、動詞と対象を一つずつ使って表現できなければならない。一文で表現できない場合はrouteを分けるか、副次的な情報を段階的に開示する。
|
||||
|
||||
Workspaceのページは、次のいずれかを基本形とする。
|
||||
|
||||
1. **一覧またはboard** — リソースを探し、注意が必要な項目を見つける。
|
||||
2. **詳細** — 一つのリソースを理解し、現在実行できる次の操作を行う。
|
||||
3. **formまたはeditor** — 範囲の明確な設定変更を行う。
|
||||
4. **Console** — 一つのWorkerを操作しながら、履歴と現在のcontrolを確認する。
|
||||
|
||||
同じ目的を支える場合に限り、一つのrouteで複数の基本形を組み合わせてよい。たとえばTicket詳細では履歴とworkflow
|
||||
actionを併置できる。一方、Workspace landing
|
||||
pageに無関係なRuntime、Repository、診断情報を並べてはならない。
|
||||
|
||||
## 画面枠とナビゲーション
|
||||
|
||||
- root layoutが唯一のapplication shellとsidebar containerを所有する。
|
||||
- sidebar
|
||||
sectionは、Global、Workspace、Settings、route固有sectionの順に積み重ねる。
|
||||
- 子routeは自分のscopeに属するlinkだけを追加する。親のnavigationを置き換えたり複製したりしない。
|
||||
- Workspace scopeのlinkは、Workspace routeの中だけに表示する。
|
||||
- navigation labelとURLにはcanonical resource
|
||||
keyを使う。内部UUIDをlabelやfallback linkとして露出しない。
|
||||
- 存在しない、または閲覧できないWorkspaceを開いた場合は、その状態を明示する。別のWorkspaceへ暗黙に切り替えない。
|
||||
- sidebarのfold状態はshellが所有する。navigation
|
||||
sectionが別のsidebar、独自の幅、fold controlを持ってはならない。
|
||||
|
||||
## 情報階層
|
||||
|
||||
### ページヘッダー
|
||||
|
||||
通常のページは、一つの簡潔なheader rowから始める。
|
||||
|
||||
- 左側にpage titleを置く。
|
||||
- 右側のprimary actionは最大一つとする。
|
||||
- route分類を繰り返すeyebrowは置かない。
|
||||
- titleを言い換えただけの導入文は置かない。
|
||||
|
||||
subtitleを置けるのは、判断に影響する情報、分かりにくいscope、重要な制約を伝える場合だけとする。resource
|
||||
keyは、detail
|
||||
pageで識別に必要な場合にtitle付近へ置いてよいが、人が読むtitleより強く見せない。
|
||||
|
||||
### セクション
|
||||
|
||||
- sectionはDTOやdatabase fieldの順ではなく、ユーザーの作業順に並べる。
|
||||
- primary actionと、その判断に必要な状態を初期viewportに置く。
|
||||
- containerを追加する前に、spacing、alignment、typography、必要最小限のseparatorで階層を作る。
|
||||
- scanningに役立つ場合だけsection headingを置く。page
|
||||
titleで意味が明らかな領域を`Overview`などで重ねて囲まない。
|
||||
- list、board、table、form
|
||||
group、timelineは連続した作業面として扱う。項目ごとに独立したcardへ分解しない。
|
||||
- 一つの境界は一度だけ表現する。nested
|
||||
border、背景差、大きなgap、shadowを重ねて同じ階層を表現しない。
|
||||
|
||||
### メタデータ
|
||||
|
||||
主要画面に表示するのは、リソースの識別、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を使う。labelや説明文にはsans
|
||||
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の後に表示する。継続編集が主目的でなければ、成功後はresource
|
||||
viewへ戻すかformを閉じる。
|
||||
- disclosure
|
||||
labelは内容または操作対象を具体的に示す。名詞を伴わない`More`や`Advanced`を使わない。
|
||||
|
||||
blocking error、permission requirement、validation constraint、unsaved
|
||||
changeを閉じたdisclosureへ隠してはならない。
|
||||
|
||||
## Authority、権限、操作
|
||||
|
||||
permissionはcontrolのenabled状態だけでなく、ページ構成そのものへ反映する。
|
||||
|
||||
- non-ownerにowner-only mutation controlを表示しない。
|
||||
- readは可能だがmutationできない場合、有用なread viewだけを構成する。空のaction
|
||||
barや理由の分からないdisabled controlを置かない。
|
||||
- permission
|
||||
boundaryの説明は現在の作業に影響する場所だけに置く。`owner only`をpage
|
||||
eyebrowとして使わない。
|
||||
- endpointからdataを取得できたかどうかでpermissionを推測しない。権威あるpermission
|
||||
projectionを使う。
|
||||
- domain stateとtransport
|
||||
stateを混同しない。たとえばWebSocketがopenであることは、Workerがidleまたはhealthyであることを意味しない。
|
||||
- 現在の権威あるstateで有効なactionだけを利用可能として提示する。
|
||||
- destructive
|
||||
actionには対象リソースと結果を明記する。即時に復元できない場合は意図的なconfirmationを要求し、通常のprimary
|
||||
pathと視覚的に区別する。
|
||||
|
||||
page headerまたはform action group内のfilled primary
|
||||
actionは一つだけとする。secondary actionはbordered actionまたはtext
|
||||
actionとする。destructive actionは、最後の破壊確認段階を除きfilledにしない。
|
||||
|
||||
## 読み込み中、空、エラー、利用不能
|
||||
|
||||
dataを持つsurfaceは、意味のある状態を個別に扱う。
|
||||
|
||||
### 読み込み中
|
||||
|
||||
- data取得中もpage frameとsection位置を維持する。
|
||||
- scopeが明らかでない場合は、何を読み込んでいるか示す。
|
||||
- page全体を中央spinnerへ置き換えてlayout shiftを起こさない。
|
||||
- spinnerだけに意味を持たせず、accessibility上のlabelも与える。
|
||||
|
||||
### 空
|
||||
|
||||
- absenceは`No tickets`のように直接表現する。装飾的なillustrationや長い説明文を置かない。
|
||||
- permissionがあり、実際に利用できる場合だけ、次のactionを一つ提示する。
|
||||
- recordが存在しない状態と、recordを読み込めなかった状態を区別する。
|
||||
|
||||
### エラー
|
||||
|
||||
- field validationは対象fieldの近くに置く。
|
||||
- operation errorは失敗したactionの近くに置く。
|
||||
- section load errorは対象section内に置き、利用できる他のsectionは残す。
|
||||
- routeの主要目的を果たせない場合だけroute-level errorにする。
|
||||
- diagnosticsはboundedかつactionableにする。payload、secret、内部traceをdumpしない。
|
||||
- 新しく発生し、即時の注意が必要なerrorには`role="alert"`を使う。常設の説明文をalertにしない。
|
||||
|
||||
### 利用不能と権限不足
|
||||
|
||||
resource unavailable、capability missing、permission
|
||||
deniedは異なる状態として扱い、copyも分ける。利用できない具体的なcapabilityまたは必要なpermissionと、安全な次のactionがあればそれを示す。`403`をempty
|
||||
listとして表示したり、別のWorkspaceへredirectしたりしない。
|
||||
|
||||
## 視覚設計
|
||||
|
||||
### 基本姿勢
|
||||
|
||||
Workspace Webは、分離したwidgetの集合ではなく、一つのcontrol
|
||||
surfaceとして見えるようにする。情報のgroupingには、まずspacing、typography、text
|
||||
contrastを使う。border、rounded rectangle、shadow、filled
|
||||
panelは、spacingだけでは伝わらない意味のある境界に限定する。
|
||||
|
||||
### カラーパレット
|
||||
|
||||
colorは`app.css`のCSS custom propertyをauthorityとし、OKLCHで定義する。light
|
||||
modeとdark modeは`prefers-color-scheme`を通じて同じsemantic tokenを使う。
|
||||
|
||||
ルール:
|
||||
|
||||
- page backgroundとlayout surfaceはchroma zeroの`oklch(... 0 0)`を使う。
|
||||
- primary textとcode textは、ほぼneutralなwarm colorとする。CSS
|
||||
OKLCHはsaturationではなくchromaを直接扱うため、「約5%
|
||||
saturation」の意図は`C = 0.01`から`0.012`程度の小さなwarm chromaで表現する。
|
||||
- muted textは新しいhueを増やす前にlightnessとchromaを下げる。
|
||||
- accentとstatus colorはsemantic
|
||||
exceptionとする。state、focus、navigationを示すために使い、container装飾には使わない。
|
||||
- Workspace Web componentへraw hexまたはrgb
|
||||
colorを追加しない。必要な場合は`app.css`へsemantic tokenを追加する。
|
||||
|
||||
基本token:
|
||||
|
||||
```css
|
||||
--bg
|
||||
--bg-raised
|
||||
--bg-subtle
|
||||
--line
|
||||
--line-strong
|
||||
--text
|
||||
--text-strong
|
||||
--text-muted
|
||||
--text-faint
|
||||
--code
|
||||
--accent
|
||||
--success
|
||||
--warning
|
||||
--danger
|
||||
```
|
||||
|
||||
### 表示面と操作部品
|
||||
|
||||
- structural surfaceにshadowや装飾目的のradiusを使わない。
|
||||
- bordered parentの内側にbordered childを置かない。
|
||||
- rowは一つのseparatorと、必要に応じたhoverまたはselected backgroundで表現する。
|
||||
- button、input、select、textareaなどのinteractive
|
||||
controlだけに`var(--radius-soft)`を使う。
|
||||
- resource key、link、status、table cell、Ticket、sectionをpillにしない。
|
||||
- statusは小さなmarkerとtextで表現する。markerは`aria-hidden`とし、textに意味を持たせる。
|
||||
- laneやsectionがすでにstateを示している場合、row内で同じstateを繰り返さない。
|
||||
- colorとspacingにはsemantic tokenだけを使う。literal colorや局所的なspacing
|
||||
scaleを追加しない。
|
||||
|
||||
## タイポグラフィと文言
|
||||
|
||||
通常のWorkspace pageでは、三段階のtype hierarchyを使う。
|
||||
|
||||
| 用途 | size / line height | 使用箇所 |
|
||||
| -------------------------------------- | ------------------ | -------------------- |
|
||||
| Page title | `24px / 32px` | routeごとに一つ |
|
||||
| Body、control、row、section title | `14px / 20px` | contentとinteraction |
|
||||
| Metadata、table heading、machine value | `12px / 16px` | 副次情報と機械的な値 |
|
||||
|
||||
別のfont sizeを増やす前に、配置、spacing、weight、muted
|
||||
colorでhierarchyを作る。Consoleとterminal outputは、密度が必要な場合にmetadata
|
||||
sizeのmonospace
|
||||
styleを使ってよい。より多くのdataを表示するためにtextを`12px`未満へ縮小しない。
|
||||
|
||||
copyのルール:
|
||||
|
||||
- 具体的な名詞と動詞を使う。
|
||||
- Workspace、Ticket、Objective、Repository、Runtime、Workdir、Worker、Merge
|
||||
Requestなど、ユーザーに見えるdomain nameを使う。
|
||||
- identifier、API名、type名は、正確性が必要な場合に原文を維持する。
|
||||
- page title、navigation label、明らかなcontrol behaviorを説明文で繰り返さない。
|
||||
- proseを追加するのは、判断を変える情報、結果へのwarning、permissionまたはvalidation
|
||||
constraint、error recoveryを示す場合だけとする。
|
||||
- empty copyとstatus copyは短く、事実を直接書く。
|
||||
- buttonは`Add repository`、`Save settings`、`Stop Worker`のように操作を表す。`Submit`、`OK`、装飾的なcategory
|
||||
labelを避ける。
|
||||
- statusとattentionをcolorだけで表現しない。
|
||||
- uppercase labelは小さなmetadata labelに限る。大きなall-caps blockを置かない。
|
||||
|
||||
## リソースごとのパターン
|
||||
|
||||
### Tickets
|
||||
|
||||
- boardを一つの連続した横方向の作業面として扱う。
|
||||
- laneは控えめなheadingと、隣接laneとの一つのseparatorで区切る。
|
||||
- Ticketはlane内のflat rowとし、独立したcardにしない。
|
||||
- Ticket key、title、優先判断を変えるmetadataだけを表示する。
|
||||
- blockerとattentionはtextでも示す。
|
||||
- narrow viewportでは、Ticketをmobile cardへ変換せず、label付きhorizontal scroll
|
||||
regionでlane比較を維持する。
|
||||
|
||||
### リソース一覧
|
||||
|
||||
- 同じfieldをリソース間で比較する場合、flat listまたはtableを使う。
|
||||
- 人が読むnameとcanonical keyを最初のcolumnに置く。
|
||||
- columnは判断に必要な値だけに絞る。provider detailとrevisionはresource
|
||||
detailへ移す。
|
||||
- narrow viewportでcolumnを消すと比較できなくなる場合、label付きhorizontal
|
||||
scroll regionを使う。それ以外は一つのrowを明確なlabel付きでstackする。
|
||||
|
||||
### 詳細ページ
|
||||
|
||||
- identity、current state、attentionを最初に置く。
|
||||
- narrativeまたはhistoryをprimary
|
||||
columnに置く。actionを同時に確認する必要がある場合だけ、bounded secondary
|
||||
regionを併置する。
|
||||
- relation、target、review、workflowが別のauthorityを持つ場合、それぞれを独立したsectionにする。
|
||||
- raw metadataは閉じたdetailまたはdebug disclosureへ置く。
|
||||
|
||||
### Settingsとフォーム
|
||||
|
||||
- 一つのSettings routeは一つの設定関心事を所有する。
|
||||
- edit actionの前または同時に、現在有効な値を示す。
|
||||
- labelはcontrolの直上に置く。
|
||||
- help textはfield nameの説明ではなくconstraintを示す。
|
||||
- 一つの判断に必要なfieldをgroup化する。fieldやgroupごとにcardで囲まない。
|
||||
- narrow screenでは一列にする。複数columnは、同時に比較または決定する値に限る。
|
||||
- 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で置き換えない。
|
||||
- hidden reasoningとraw system promptはdebug modeでも表示しない。
|
||||
|
||||
## レスポンシブ対応
|
||||
|
||||
レスポンシブ設計では、すべてを同じstackへ変換するのではなく、作業上の関係性を維持する。
|
||||
|
||||
- desktopのpage paddingは`32px`、`760px`以下では`16px`とする。
|
||||
- page全体にhorizontal scrollを発生させない。board、table、code
|
||||
view、terminalは、自分の範囲内でbounded horizontal scrollを所有してよい。
|
||||
- side-by-side表示が同じ判断を支えなくなった場合、detail
|
||||
gridまたはformを一列にする。
|
||||
- stack化によってworkflowやcolumn
|
||||
relationshipが失われる場合、比較面を横方向に維持する。
|
||||
- primary actionを初期viewportから追い出さない。
|
||||
- touch targetの操作性を維持し、overflow解消のためにtextを縮小しない。
|
||||
- 長いkey、ref、diagnosticはwrapまたはtruncateし、完全な値へaccessできる手段を用意する。
|
||||
|
||||
## アクセシビリティ
|
||||
|
||||
- `main`、`nav`、`section`、`table`、`form`、`fieldset`、`label`、`button`などのsemantic
|
||||
elementを使う。
|
||||
- すべてのcontrolに明示的なaccessible
|
||||
nameを与える。placeholderをlabelとして使わない。
|
||||
- keyboard focusをsemantic accent outlineで常に見えるようにする。
|
||||
- tab orderを画面上の順序と作業順に合わせる。
|
||||
- icon-only controlには、対象リソースを含む具体的な`aria-label`を付ける。
|
||||
- 重要なloadingとoperation statusにはboundedな`aria-live`
|
||||
regionを使う。streaming noiseを繰り返しannounceしない。
|
||||
- error、warning、success、selected、runningは、color以外のtextまたはsemantic
|
||||
distinctionを持つ。
|
||||
- 必要なhorizontal scroll regionはfocus可能にし、accessible nameを付ける。
|
||||
- light schemeとdark schemeで同じsemantic tokenを使い、component-local color
|
||||
overrideなしで可読性を保つ。
|
||||
- motionは任意かつ短くし、意味の必須条件にしない。繰り返しまたは連続animationではreduced-motion
|
||||
preferenceを尊重する。
|
||||
|
||||
## CSSの責務
|
||||
|
||||
`app.css`はglobal-onlyとし、次だけを所有する。
|
||||
|
||||
- font import
|
||||
- cascade layer order
|
||||
- semantic design token
|
||||
- resetとbase element style
|
||||
- application-level layout helper
|
||||
- 無関係なfeature間で共有する小さなprimitive
|
||||
|
||||
featureとpageのstyleは、`workspace-pages.css`、`tickets.css`、`workers.css`、`settings.css`、`sidebar.css`など、その領域を所有するstylesheetへ置く。共有するvisual
|
||||
ruleはliteral valueのcopyではなくglobal tokenで表現する。
|
||||
|
||||
Svelte-local
|
||||
styleは、behaviorとstyleを分離できず、再利用もしない場合に限る。広範なpage
|
||||
styleを`app.css`へ戻したり、component-localなcolor、spacing scale、font、z-index
|
||||
systemを作ったりしない。
|
||||
|
||||
新しいUIを追加するときは、次の順に判断する。
|
||||
|
||||
1. semantic HTMLと、この文書のpage modelから始める。
|
||||
2. global tokenと既存のfeature-owned patternを再利用する。
|
||||
3. spacingとtext contrastでhierarchyを作る。
|
||||
4. boundaryが意味を持つ場合だけborderを使う。
|
||||
5. background fillはpage-level surface、selection、attention、read-only
|
||||
codeまたはrecord bodyに限定する。
|
||||
6. 新しいcolorが必要ならOKLCH tokenとして追加し、既存のsemantic
|
||||
tokenで表現できない理由を残す。
|
||||
|
||||
## 避けるパターン
|
||||
|
||||
次のパターンを設計慣習として追加または維持しない。
|
||||
|
||||
- 無関係なaction cardで構成されたdashboard風landing page
|
||||
- card-within-cardまたはpanel-within-panel
|
||||
- hierarchyを作るためだけのshadowや大きなradius
|
||||
- `Delivery`、`Workspace resources`、`owner only`などのeyebrow
|
||||
- page titleで示したリソースを管理する画面だと繰り返すlede
|
||||
- statusまたはresource keyのpill
|
||||
- laneですでに示したstateをrow内で繰り返す表示
|
||||
- DTO順に全fieldを露出するpage
|
||||
- primary viewに置かれた内部ID、revision、digest、fingerprint、authority label
|
||||
- non-ownerに表示されたowner-only disabled control
|
||||
- loading、empty、error、unavailable、permissionを一つのgeneric
|
||||
messageへまとめる表示
|
||||
- page全体をoverflowさせる固定desktop grid
|
||||
- 比較関係を壊す任意のmobile card化
|
||||
- color-only state、placeholder-only label、見えないkeyboard focus、accessible
|
||||
nameのないicon-only control
|
||||
- 二つ目のsidebar、route-local application
|
||||
shell、親navigationを置き換えるsection
|
||||
- component-localなliteral color、spacing scale、font、z-index system
|
||||
|
||||
## レビューと変更手順
|
||||
|
||||
Workspace Webの意味のある変更では、`tools/web-ux`をrepeatable browser
|
||||
captureの手段として使う。
|
||||
|
||||
1. representative personaとviewportで現在のrouteをcaptureする。
|
||||
2. screenshotと`review-context.json`を確認する。visible
|
||||
UI、console、page、HTTP、scenario failureを含めて判定する。
|
||||
3. UX上の具体的な問題と、違反しているルールを記録する。
|
||||
4. 最小で一貫したproduction変更を行う。
|
||||
5. 同じpersona、route、viewportで再captureする。
|
||||
6. before/after evidenceを比較し、関連するsource test、UI test、E2E
|
||||
testを実行する。
|
||||
|
||||
HTTP document
|
||||
statusが200でも、画面に`401 Unauthorized`などのerrorが表示されていれば成功とはみなさない。authentication
|
||||
profileはorigin-boundであり、別のhostまたはport用に取得したprofileを暗黙に再利用しない。
|
||||
|
||||
Design reviewでは、最初にユーザーのtask、次に情報階層とstate
|
||||
handling、最後にvisual polishを評価する。test通過やscreenshot生成だけではUX
|
||||
acceptanceを満たさない。
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user