docs(#956): persona × screen UX 行列を docs/ux/ に新規 doc 化

[susumutomita]

Summary

epic #952 / #956 Phase 1: 直近 audit (image #29 / #32-#36 / #43 / #45 / #50 等) で表面 UX を 1 件ずつ修正してきたが、 画面ごとの IA (= 情報設計) を体系的に見直していなかった。

本 PR は 5 persona (Participant / TenantAdmin / TenantOperator / TenantViewer / SystemAdmin) × 12 主要 screen の primary / secondary / non-target を 1 表で正本化 する。

実装

新規 `docs/ux/persona-screen-matrix.html`:

• Persona 一覧 — 主役の状況 / 典型タスク / 絶対に見せない情報
• Screen × Persona 行列 — 12 screen × 5 persona の primary action と一等地に出すべきもの
• 情報のティアリング規約 — 一等地 (1 秒) / 中段 (5 秒) / 下段 (scroll) に何を入れるか
• エラー / 空状態 UX 規約 — `FriendlyErrorAlert` の 4 要素 (= 何が起きた / なぜ / 次に何をすればよいか / correlationId) + 空状態 = 「次の一歩への入口」
• Cloudscape 使い方規約 — Header / Container / Table-vs-Cards / Button variant の使い分け
• Roadmap — Phase 1 = 本 PR / Phase 2 = primary action 統一 (画面ごとに別 PR) / Phase 3 = FriendlyErrorAlert を全 SPA 展開 / Phase 4 = ADR 化

設計判断

• HTML 直書き — ADR と同じ理由で表現力 (row span / color / class-based persona 配色) を保つ。 `feedback_design_docs_html` memory に沿う
• `docs/ux/` を新設 — 既存の `docs/operations/` `docs/problems/` と並列、 設計知識の置き場を分離
• 機械検査ルール (= harness) は Phase 4 で追加 — 本 doc はまず reference として配布し、 検証可能な規約に絞り込んでから harness 化

Regression 分析

• 既存コードに変更なし (= doc 追加のみ)
• 既存 audit 修正で出した動作は本 doc が正当化する形 (= 例: audit docs: 初期版CLAUDE.mdを追加 #1 / feat: マルチテナントSaaSアーキテクチャの基盤構築 #3 / update #33 で削除した「Job ID / 想定プレイ時間 / 学習目的」 は本 doc で「下段に格下げ」 として規約化される)
• 新規問題作者 / 新規 contributor が persona と画面の責務をすぐ参照できる

物理影響

• CREATE: `docs/ux/persona-screen-matrix.html` (= 441 行)
• CFn / AWS / コード: NO-OP

Test plan

• `make harness` — no findings
• `bun run lint:text` — clean
• `make before-commit` (= pre-commit hook 経由) — pass
• OSS reader が persona × screen の責務を 1 ページで把握できるか (= user レビューで確認)

Next steps (= 別 PR で順次)

• Phase 2: 各画面の primary action を 1 つに統一 (Participant Portal / Home → Quests → ProblemDetail から)
• Phase 3: `FriendlyErrorAlert` を `packages/portal-plugin-sdk` に bundle して全 SPA で共有
• Phase 4: 本 doc を ADR-NNN として正本化、 `make harness` に Cloudscape 使い方 lint rule を追加

Relates #956 Phase 1
Relates #952

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@susumutomita has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 10 minutes and 48 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3aa46b25-a158-44dd-9693-3a425ddba054

📥 Commits

Reviewing files that changed from the base of the PR and between f06ec1d and cc0e2ad.

📒 Files selected for processing (1)

• docs/ux/persona-screen-matrix.html

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/956-ux-matrix-doc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@f06ec1d). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #964   +/-   ##
=======================================
  Coverage        ?   92.95%           
=======================================
  Files           ?        8           
  Lines           ?      227           
  Branches        ?       66           
=======================================
  Hits            ?      211           
  Misses          ?       16           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.