Design Decisions — `/app/admin` — Round 1

Agent: kashi-ui-mockupper · 生成: 2026-05-27 · Picked variant: B (中庸 — 3-Layer Action Architecture + Scope Boundary Banner) · Surface: Admin dashboard · Output: 静的 HTML mockup（実装ではない）

このドキュメントの目的: 「なぜ mockup がそうなっているか」を将来の自分 (or React 実装エンジニア) が辿れるように記録する。 Justine が co-founder / メンター / 友人に共有して feedback を取った後、 redo or 実装フェーズ移行の判断材料になる。全ての判断は (a) Stage 1 research (b) Stage 2 translator proposal (c) Kashi canon (permanent-ui-principles / DATA_VISIBILITY_MATRIX / design_system_v1) のいずれかに根拠を持つ。

0. Variant 概要

Justine picked Variant B (中庸)。 translator の比較表によると B は:

11 アクション flat grid を Primary 1 / Secondary 4 / Tertiary 6 の 3 層に再構造化 (P-3)
H1 直下に Scope Boundary Banner を恒久配置 (P-4)、 dismissible でない
setup checklist を post-setup transition 案内に進化 (P-1 evolved)
KPI strip + drill-down を operational ページ限定 (P-2)
TeamRow 展開を 件数 + 日付範囲 に絞る (P-5 調整版、タイトル列除去でリスク 2 回避)

実装工数 M (5-7 日) / cross-surface 影響なし / canon §3 §4 §7 §8 すべて PASS+。 C と比べると 11 アクション削除ではなく「再配置 + 折りたたみ」で行うため、 admin の既存 muscle memory を維持しつつ認知負荷を下げる。

1. 主タスクと上位構造 (IA)

決定: 「テナント運用の next step を 1 つだけ提示し、 admin がそれ以外で迷わない」を主タスクに設定

現状の主タスクは「11 アクションへの分岐ハブ」だった。これが C-A1 (認知負荷) の根因。 B では pilot phase に応じて Primary CTA が動的 になる主タスクに再定義。 mockup では phase A (setup 未完) / phase B (post-setup, default 表示) / phase C (定常運用) の 3 状態を切り替え可能にした (mockup-only の phase switcher)。

根拠: translator proposal Variant B 「主タスク」セクション + research §8 リスク 3 (post-setup 空白問題) の回避策 / canon: permanent-ui-principles §8 「one primary CTA」

決定: 3 階層 = Primary (1) / Secondary (4) / Tertiary (6 fold) で 11 アクションを再配置

Primary (1): phase-aware 大カード (filled evergreen button)。 mockup の default = Phase B 「Manager に Mirror URL を共有」
Secondary (4): 日常運用の outline カード grid — ユーザー管理 / チーム作成 / 単発 Upload / 一括 Upload
Tertiary (6 fold): 折りたたみ accordion 内 — 稼働状況 / データ品質 / 準備度チェック / コミュニケーションポリシー / 話者管理 / ジョブ監視 + 通知管理 (現状の「ジョブ」と「通知」をまとめて 1 カードに)

Tertiary は default 折りたたみだが「6 項目を表示 ▾」の明示的 hint で「機能が無いと思い込む」リスクを回避 (translator の残るリスク 1 への対応)。

根拠: research §3 P-3 (N=5: Stripe + Vercel + Okta + Google WS + B2B UX) / canon: permanent-ui-principles §7 「default visible layer 3-5 cards」 §8 「grouped controls」

2. Scope Boundary Banner (canon 強制レベル)

決定: H1 直下にフル banner で恒久配置、 dismissible でない

文言:
「あなたは 『組織と利用状況』 の管理者です」
「この画面では ユーザー・チーム・アップロード・運用設定 を管理できます」
「一方で、 ミーティングの中身・メンバー個別の発話パターン・シグナル はこの画面からは閲覧できません」
「— これは Kashi の canon (役割境界) です」
フッターリンク: 「データ可視性マトリクス §3 / §8」 + 「canon: 永続UI原則 §4」

banner は F7F8FA 背景 + 4px 2F6B4A left border + ShieldCheck icon。 surveillance 系の「目」「カメラ」メタファーを避けて「盾 = 境界保護」のメタファーを採用 (permanent-ui-principles §13)。

根拠: translator Variant B Scope Boundary Banner 仕様 + research P-4 (N=4: Stripe + GitHub + Okta + Google WS) / canon: permanent-ui-principles §3 (Role Boundary First) + §4 (System Admin = operational only) + DATA_VISIBILITY_MATRIX §3 / §8 (Bypass forbidden)

差別化テーゼの物理実装: SmartHR / カオナビ等の HR SaaS は「全従業員データを admin が俯瞰できる」ことが価値。 Kashi Admin は その逆 で「中身を見られない」ことが価値。この「不在」を「欠如」ではなく「設計的選択」として UI で示すのが Kashi 差別化の核 (permanent-ui-principles §1 「The UI wins by showing less」)。 banner はその核を 1 画面で見せる装置。

3. Stage 1 patterns の採用状況

Pattern	適用	調整点
P-1 Setup Checklist → Post-Setup Transition	採用 (発展)	checklist 完了で消す現状実装を「稼働中バナー + 次アクション CTA」に切り替える evolved 版に。 mockup の phase switcher で 3 状態を確認可能
P-2 KPI strip (3-stat with drill-down)	採用	drill-down 先を operational ページに限定 (チーム一覧 / ユーザー管理 / アップロード履歴)。分析系 (Longitudinal 等) には絶対飛ばさない
P-3 3-Layer Action Architecture	採用	translator 仕様通り Primary 1 / Secondary 4 / Tertiary 6 fold
P-4 Scope Boundary Banner	採用 (フル)	H1 直下、 dismissible 無し、 ShieldCheck icon 付き
P-5 Expandable TeamRow	採用 (調整)	展開 detail は期間 / 平均時間 / 処理ソース内訳 + scope-note のみ。ミーティングタイトル列は完全除去 (research §7 リスク 2 回避)

4. Canon Compliance チェック (PR template §15 準拠)

§	判定	根拠
permanent-ui §3 Role Boundary First	PASS+	H1 直下に Scope Boundary Banner + role chip + 6 質問 (who/what visible/what hidden/safe action/forbidden/audit) を banner で 1 箇所集約
permanent-ui §4 Visibility (System Admin)	PASS+	「operational configuration + technical logs のみ」を banner で明示。 Tertiary 6 項目はすべて operational 文言 (稼働状況 / データ品質 / 準備度 / ポリシー / 話者 / ジョブ・通知)
permanent-ui §7 Progressive Disclosure	PASS	default visible = H1 + banner + KPI 3 + primary CTA 1 + secondary 4 + tertiary header (折りたたみ) + チーム 5 行 → 「3-5 cards + 1 primary CTA」ルール準拠
permanent-ui §8 Cognitive Load	PASS	明確な H1 + 4 つの H2 セクション + 1 primary CTA + grouped controls。「equal-weight CTA spam」が構造的に解消
permanent-ui §9 Dashboard Rules	PASS	KPI は count のみ (チーム数 / メンバー数 / 処理件数)。個人 rank / health score / 「at-risk」ラベル 0 件
permanent-ui §11 Internal Screen Rules	PASS+	role label (header chip) + visibility boundary (banner) + safe actions (secondary 4) + forbidden context (banner の「ミーティング中身は見えない」) + audit semantics (Tertiary 内「ジョブ監視・通知・監査ログ」)
permanent-ui §12 A11y / Mobile	PASS	1 H1 + 4 H2 (順序正) + button/accordion に `aria-expanded` + focus ring (--shadow-focus) + 920px / 600px breakpoint + tap target 44px+ + badge は色のみでなくテキストラベル
permanent-ui §13 Visual System	PASS	off-white base + 濃緑 accent + outline Lucide-style icon 1.5px stroke。 ShieldCheck は「policy boundary」メタファーで「security camera」とは別物 (§7 アクセプタブル icon)
DATA_VISIBILITY_MATRIX §3 (Admin scope)	PASS+	Pattern summaries / Per-meeting metrics / Team aggregates いずれも N。表示は organizational count + operational config のみ
DATA_VISIBILITY_MATRIX §8 (Bypass forbidden)	PASS	分析系ページへの CTA 0 件。「ミーティング洞察」「メンバー発言」系の語彙 0 件 (チーム展開の scope-note でも明示)
permanent-ui §2 forbidden wording	CLEAN	「at-risk」「organizational health score」「team health score」「productivity score」「detects harassment」等 0 件。 footer disclaimer で明示的 refuse

5. 採用したトークン (design_system_v1.md)

トークン	使用箇所
`--kashi-evergreen` #2F6B4A	Scope Banner left border / Primary CTA filled button / Secondary card icon / accordion title color / KPI hover border / ShieldCheck icon
`--kashi-evergreen-deep` #1F4A33	page H1 / H2 / banner title / primary CTA hover
`--cream` #F5F0E6	role chip background / footer disclaimer / TeamRow scope-note / portal header brand text
`--kashi-paper-tint` #F7F8FA	Scope Banner 背景 (subtle differentiation)
`--kashi-paper` + `--kashi-border`	全 outline カード (KPI / Secondary / Tertiary / Primary CTA / Teams card)
`--stone-50` #FAFAF7	body background (off-white base per §13)
`--shadow-focus`	全 interactive 要素の focus-visible ring (a11y baseline §12)
type scale (font-serif Fraunces)	H1 36px / H2 24px (h3 token) / KPI 数値 32px / banner title 16px / 全 display text
type scale (font-sans IBM Plex + Zen Kaku)	body / labels / CTA text
type scale (font-mono IBM Plex Mono)	kicker / role badge / KPI subtitle / accordion hint / scope banner footnote / manager id labels
spacing rhythm (8pt grid)	--space-2/3/4/5/6/8 を使用。セクション間 --space-8、カード内 --space-5、 card gap --space-4

6. 採用した evidence-grade 表現

この surface には evidence-grade badge は配置していない

理由: admin home はそもそも個別ミーティング / pattern summary / structural metric を表示しない (canon §4)。 evidence grade は「signal の確からしさ」を伝える装置であり、 admin scope の operational view にはそもそも該当する情報が無い。 design_system_v1 のトークン定義 (grade-stable 等) は CSS root に記載してあるが、 mockup 上で使用していない。 Mirror / CEO / Reviewer 等の signal-bearing surface でのみ表示される予定 (DATA_VISIBILITY_MATRIX §5 経由)。

根拠: DATA_VISIBILITY_MATRIX §3 / permanent-ui-principles §4 §5 / design_system_v1 §1

7. 現状の Kashi (kashi/app/app/admin/page.tsx) からの diff

削った要素

第 2 段「Longitudinal / Communication Policy」濃緑 filled カード 2 個 → operational 文言に改訂のうえ Tertiary 折りたたみ内に格下げ。視覚的に第 2 段 hierarchy が消えるため C-A2 (スタイル混在) も同時解消。
第 3 段「Coverage / Readiness / Speakers / Jobs / Notices」 5 枚白カード → 同じく Tertiary 折りたたみへ。 6 項目 (Jobs と Notices を 1 カードに統合) として整理。
RecentMeetingsList (直近 50 件) → 削除。タイトル + 日時 + meeting_type を Admin が見ることは canon §4 グレーゾーン (operational metadata だが個別ミーティングを示す)。 Admin home から外し、必要なら Tertiary 「稼働状況」ページ内で operational summary として再構成 (mockup 範囲外、別 surface 課題)。
TeamRow 展開内のミーティングタイトル一覧 → 削除。件数 + 期間 + 平均時間 + ingest_source 内訳のみに置換 (research §7 リスク 2 回避策)。
「分析」「洞察」「メンバー発言」系 CTA → 0 件確認 (もともと現状コードにもラベル直接は無いが、リンク先ページ名が誤解を生むので URL も含めて整理)。

追加した要素

Scope Boundary Banner (H1 直下、恒久) → 最重要追加。 P-4 N=4 reference (Stripe / GitHub / Okta / Google WS) + canon §3/§4 強制実装。
Primary CTA カード (phase-aware) → P-1 evolved。 setup 完了後の「次のステップ」空白を解消 (research §7 リスク 3)。
KPI カードへの drill-down リンク → operational ページ限定。数値 + 「→ 一覧へ」動線。
KPI subtitle に補足数値 → 「先月比 +2」「アクティブ 47 · 招待中 3」「自動 134 件 · 手動 22 件」で operational context を強化。
TeamRow 内 scope-note → 「集計のみ表示 — ミーティング個別のタイトル・内容・参加者発言は Admin からは見えません」を展開時に明示。
セクション右側 count chip → 「primary action / 1 件」「secondary / 4 件」「tertiary / 6 件 · 折りたたみ」で hierarchy を視覚的に補強。
mockup-only phase switcher → Phase A/B/C 切り替え UI。実装時は削除、 backend で自動判定。

変更した要素 (改訂)

「Longitudinal」 → 「稼働状況」: operational 文言に。「ミーティング洞察を見に行く」と読まれないように。
「Coverage」 → 「データ品質」: transcript 品質と抜けチェックの operational view。
「Readiness」 → 「準備度チェック」: パイロット要件達成の operational checklist。
KPI 「ミーティング数」 → 「処理件数 (累計)」: 「ミーティング」という個別性のある言葉から「処理件数」という operational metric に。
H1 「demo株式会社」 + kicker 「管理ダッシュボード」: 現状の「タイトルが org name」を維持しつつ kicker で role context を添える。既存ユーザーの muscle memory に配慮。
setup checklist 配色: 暗い stone-900 背景 → 通常の outline カード (kashi-paper + kashi-border): 「unfinished business」的な圧迫感を解消、 normal section として表示。完了/未完了は check icon の色で表現。

8. 既知のトレードオフ / 未解決事項

Tertiary 折りたたみは初見の admin が「機能が無い」と誤読する可能性
対策: 「6 項目を表示 ▾」のヒントを accordion header に常時明示。ただし feedback で「Tertiary を default 展開してほしい」が出る可能性。 → redo 時に検討。
Primary CTA の phase 判定 backend 依存
mockup では phase switcher で 3 状態を確認可能だが、実装には setup_complete / pilot_active / steady_state を判定する backend logic が必要。既存 setupComplete フラグは流用可能だが、「Manager に Mirror URL 共有済みか」等の post-setup state は未実装。
Scope Boundary Banner の文言は wording sensitive
「これは Kashi の canon (役割境界) です」という言葉は haseruida@ / Justine の最終 review 必要。現案は research の研究パターンに沿った文言だが、ブランド voice の調整余地あり。
「利用状況概観」ニーズ (C-A5) は部分解決
KPI drill-down + TeamRow 件数表示で「誰がどれくらい使っているか」はある程度見えるが、時系列・チーム間比較は Tertiary 「稼働状況」ページに depth が必要。 mockup ではその深い page の design は範囲外。
RecentMeetings 削除の影響
現状 admin はトラブル時に「直近のミーティングが処理されたか」を一覧で見ていた可能性。これは Tertiary 「ジョブ監視」で代替可能だが、ワンクリックではなくなる。 feedback で「最近のアップロード状況だけは home に欲しい」が出たら「自動 134 / 手動 22」の subtitle を expand する方向で対応。
mobile (375px) responsive はチェックしたが Real Device 未検証
CSS @media 600px / 920px breakpoint で grid 縮退。 PortalHeader nav は overflow-x: auto で横スクロール。ただし実機での touch target / iOS Safari 描画は未検証。実装段階で要 QA。

9. 実装フェーズへの引き継ぎ

このモックアップを React で実装する際の注意:

該当する Kashi コード

kashi/src/app/app/admin/page.tsx (484 行) — メインの実装対象。現状の 11 アクション grid を 3 層構造に再構築。
kashi/src/app/app/admin/team-row.tsx — 展開 detail からミーティングタイトル列を除去、集計 4 ブロック表示に整理。
kashi/src/app/app/admin/recent-meetings-list.tsx — admin home からは削除、別 page (「稼働状況」内) に移動するか完全廃止。
kashi/messages/ja.json + en.json — admin.home.* の copy を Scope Banner / phase-aware CTA / 改訂ラベル (稼働状況 / データ品質 / 準備度) に拡張。 i18n 39 test files が pin する verbatim string と同期必要 (LESSONS 2026-05-15 参照)。

影響を受ける共有コンポーネント

kashi/src/components/portal/PortalHeader.tsx — 変更なし (B は cross-surface 影響なしの中庸案)。 navigation は維持。
kashi/src/lib/auth/authorization.ts — requireRole 維持。 phase 判定の helper 追加が必要 (setup_complete / pilot_active / steady_state)。

必要な新規コンポーネント

ScopeBoundaryBanner — 全 admin/internal screen で再利用可能。 props: role + scopeStatement + canonRefs[]。
PrimaryCTACard — phase-aware の next-action card。 props: phase + headline + detail + ctaHref + ctaLabel + statusLabel。
SecondaryActionGrid — 4 cards layout。既存 Card component と統一可能。
TertiaryAccordion — fold/unfold operational links。既存 Lucide chevron + radix-ui Accordion 等。
KPIStrip — 3 cards with drill-down。 admin / ceo / reviewer で再利用可能 (drill-down 先のみ role-aware)。

r19 既存課題のうち本案で同時解決されるもの

r19 §6.2 「Color semantics inconsistent (濃緑 / 白カード混在)」 → Primary / Secondary / Tertiary の意図的階層に整理されることで解消
r19 §7 「11 アクション flat grid の認知負荷」 → 3 層構造で解消
r19 §8 「セットアップ完了後の next step 空白」 → P-1 evolved の Phase B CTA で解消

i18n verbatim test pinning に注意

LESSONS 2026-05-15 「i18n verbatim test pinning — 39 test files pin 検証文字列」通り、 admin.home.* キー追加 / 改訂時は以下を同期必要:

新規キー (scopeBoundary.* / primaryCta.phase{A|B|C}.* / tertiary.* / secondary.*) を messages/ja.json + en.json に追加
削除キー (旧 actionLongitudinal* / actionCoverage* / actionReadiness* / actionSpeakers* / actionJobs* / actionNoticesTitle / actionNoticesSub) を verbatim pin している test を grep して同時更新
pre-commit hook (PR #327) が auto-discover するが、 3-incident 履歴 (#280/#297/#327) があるため non-trivial 変更は 3-round 監査 (Claude + codex + gemini)

RLS / data fetch の整合性

現状 admin/page.tsx は meetings table から title + ingest_source を SELECT している。 B 案では Admin home でこれらを表示しないので、 query は meetings.count + ingest_source group by に簡素化可能。 title fetch は「稼働状況」 page にだけ残せばよく、 RLS は変更不要 (admin は既に meetings.title 読み取り可)。

10. Justine の confirm / redo 判断点

このまま実装フェーズに進む (confirm) と判断する基準:

Scope Boundary Banner の文言が canon の趣旨を正確に表現できている
Phase A/B/C の Primary CTA が pilot lifecycle の実態に合っている (B = 「Manager に Mirror URL 共有」が本当に次の運用 step か)
Tertiary 折りたたみ default が co-founder/メンター feedback で許容される (誰も「機能が無い」と思わない)
TeamRow の展開 detail が「個別ミーティング閲覧ではない operational 集計」として違和感ない

redo を依頼する典型ケース:

「Scope Banner が冗長」: 文言短縮 or 1 行 subtitle 版に縮小 → A 案寄りに調整
「Primary CTA の phase 判定はやりすぎ」: 静的「セットアップ進捗」 + 「直近の運用 status」の 2 ブロックに分解
「Tertiary 6 項目は default 表示にして」: Tertiary 展開を default にし、「日常」と「その他」の H2 区切りで視覚 hierarchy 維持
「mockup は B で OK だが KPI に時系列グラフが欲しい」: Stage 2 で C 寄り (operational inbox) に拡張、別 round で再 design
「色が業務ツールにしては地味すぎる / 派手すぎる」: token 維持しつつ Banner accent 強度のみ調整

共有時の case framing 推奨

co-founder/メンターに共有する際は以下のフレーミング推奨:

まず Phase B (default) のスクリーンショットを共有し「Admin の home はこういう view になる」を 30 秒で伝える
phase switcher を使って Phase A → C を見せて pilot lifecycle 全体感を示す
Scope Boundary Banner を指して「これが Kashi 差別化の核」を強調 (SmartHR / カオナビとの対比)
Tertiary を展開して「11 機能は全部維持してるが priority 整理した」を示す
TeamRow 展開で「集計のみ・タイトル無し」を示し canon 強制の物理実装を確認

出典: app-admin__references.html (Stage 1) · app-admin__variants.html (Stage 2 Variant B) · permanent-ui-principles.md §1-§15 · design_system_v1.md §1-§10 · DATA_VISIBILITY_MATRIX.md §3 / §8 · kashi/src/app/app/admin/page.tsx (現状実装) · kashi/src/components/portal/PortalHeader.tsx (shell replica)

Design Decisions — /app/admin — Round 1

0. Variant 概要

1. 主タスクと上位構造 (IA)

2. Scope Boundary Banner (canon 強制レベル)

3. Stage 1 patterns の採用状況

4. Canon Compliance チェック (PR template §15 準拠)

5. 採用したトークン (design_system_v1.md)

6. 採用した evidence-grade 表現

7. 現状の Kashi (kashi/app/app/admin/page.tsx) からの diff

削った要素

追加した要素

変更した要素 (改訂)

8. 既知のトレードオフ / 未解決事項

9. 実装フェーズへの引き継ぎ

該当する Kashi コード

影響を受ける共有コンポーネント

必要な新規コンポーネント

r19 既存課題のうち本案で同時解決されるもの

i18n verbatim test pinning に注意

RLS / data fetch の整合性

10. Justine の confirm / redo 判断点

共有時の case framing 推奨

Design Decisions — `/app/admin` — Round 1