ADR-0041 — human-layer visual design system

Status: accepted · Date: 2026-06-15 · folio v1.0.0 · 人間層を「要件定義書のための汎用ビジュアル design system」と再定義する決定。 ADR-0040 の圧縮 (informative prose を audience 降格して人間既定表示から隠す) を改訂し、 情報を隠すのではなく密度高く視覚的に「再提示」する方向へ転換する。 視覚言語 = deck 寄りハイブリッド (色帯で章を開く掴み + 高密度の表/RTM グリッド/密リストで情報保持)、 テーマは環境追従 (prefers-color-scheme)。 人間プレゼンは機械 SSoT から別ファイルとして生成し (ADR-0033 §2.3 が残した derive 原理を別ファイル形態で起動)、 更新は差分 + 現行 HTML を渡して再生成・更新日時で同期する。 ADR-0033 が「co-author を enforcement で担保」したのに対し、 本 ADR は「生成物を検証で担保」する: 2-gate = 非エンジニア persona walk (わかりやすい言語か) + fidelity check (機械 SSoT と突合し情報が落ちていないか)。 floor も「人間可視 prose の長さ」から「visual-first / 用語被覆 / renders-unbroken」へ刷新する。 適用範囲 = γ (SRS 核を ISO/IEC/IEEE 29148 で完全性錨留め + folio 自身の ADR/research/原則は拡張パックで後追い)。 EC 注文確定・決済の難要件で実証済 (persona = 合格 / fidelity = AI が捏造した RTM 行を検出 = 生成 + 検証アーキの正しさを実証)。 grill 2026-06-15 で全論点確定。 実装は MINOR (1.1.0)、 epic folio-c5g。

§1. Context

ADR-0040 は人間層を「制限時間付きプレゼン」と定義し、 informative prose を data-audience="machine" へ降格して既定表示から隠す圧縮で「字が多すぎる」を解こうとした。 epic folio-8jy 完了後の 1.0.0 宣言 (2026-06-13) を経て、 user は圧縮済みの corpus を実機で再評価し「量は多少減ったが、内容が依然読みづらい・専門用語が多すぎる・日本語が不自然・全然グラフィカルでない」と判定した。

grill (2026-06-15) で根因を 2 つに切り分けた。 第一に、 標準と検証の非対称: P-14 は「読者がそのページの仕事を果たせる形で提示される」ことを要求するのに、 floor が測っていたのは人間可視 prose の長さ (字数)だけで、 「わかりやすさ・視覚性」は一度も検証していなかった — 「非エンジニアが頑張れば読める」という読者基準を定義も計測もしていなかった (validate が全 green でも読めない、 という ADR-0038 が指摘した価値の非対称の再発)。 第二に、 圧縮 (降格) は情報を「隠す」方向であり、 視覚言語そのものを設計していなかった — ADR-0040 §2.2 は「スライド的な語り順・独自レイアウトは要件としない」とプレゼン設計を明示的に scope 外に落とし、 「グラフィカル化」を「mermaid を数枚足す」に矮小化していた。 結果、 実装は圧縮はしたがプレゼン化はしていない。

user の本来の要求は「非エンジニアが頑張れば読める、 プレゼンとして出来の良い成果物」であり、 これは ADR-0040 の「字を減らす」では届かない別の軸 — 視覚デザインで意味を運ぶ (文字は最小、 構造・色・図・表が主役) — を求めている。 視覚サンプルの反復 (会議室予約 → EC 決済) で user は具体の視覚言語を判定でき、 機械的圧縮では解けないこの軸を design system で解く方針が確定した。

§2. Decision

§2.1 人間層 = 要件定義書のビジュアル design system (grill 論点 1〜3)

人間層 (既定表示で人間が見る内容) を「読める文書」ではなく「設計された視覚プレゼン」と再定義し、 その実体を「要件定義書のための汎用ビジュアル design system」とする。 北極星は folio 特化でなく「要件定義書として最適」 — folio はその最初の consumer (dogfood) であって設計の地平線ではない。 これは folio の使命 (rules は元々 Layer 1 consumer 向け universal rules) と整合し、 再利用可能な資産になる。 design system は 「大胆な帯」と「高密度の表」の両 register を持つ部品庫で、 要件定義書の各パーツ (スコープ / アクター / EARS 要件 / 非機能要件 / ユースケース / 受入基準 / 用語集 / トレーサビリティ等) を視覚コンポーネントに対応づける。 dual-audience の境界は部品単位に降りる: 各部品は「機械精密スロット」と「設計された人間の顔」を持つ。

§2.2 視覚言語 = deck 帯 × 高密度 + 環境追従テーマ (grill 論点 4〜5)

視覚言語はdeck 寄りハイブリッド × 高密度とする (user 判定: 3 方向比較 → ハイブリッド → 密度 2 段階のうち高密度)。 各主要セクションを全幅の色帯(章番号の透かし + 大見出し + 短いリード) で開き (大胆な掴み)、 詳細は高密度コンポーネント(型色つき要件マトリクス / 本格 RTM 行列グリッド / 数値ヒーロー + メトリクステーブル / 密な 2 リスト / 定義テーブル) で情報量を保ったまま視覚整理する。 テーマは環境追従 (prefers-color-scheme で CSS 変数を差し替え、 ライト/ダークいずれも意図的に設計) — ダーク固定にしない (ADR-0033 の ALLOW = dark-light 切替と整合)。 成果物は自己完結の static HTML + CSS + インライン SVG + vendored mermaid とし、 外部 URL/CDN/ES module に依存しない (no-build・AI 直読・file:// 動作を維持、 ADR-0033 / P-13)。

§2.3 原則の精緻化 — 圧縮から再提示へ (grill 論点 6)

人間層の原則を「見やすい + わかりやすい言語 + 情報を落としすぎない」に精緻化する。 これは ADR-0040 の中核 (informative prose を降格して人間既定表示から隠す) を改訂する: 人間既定の情報量を減らして読みやすくするのではなく、 同じ情報を密度高く視覚的に「再提示」する (圧縮 = 量削減 → 再提示 = 見せ方の変換)。 ゆえに本 ADR の下では人間既定ビューの情報量は ADR-0040 より増える。 専門用語は消さず、 やさしい言い換え + 正確な用語を併記して情報を捨てない (例:「金額を仮押さえ (オーソリ)」)。

§2.4 生成方式 — 機械 SSoT から別ファイルを derive (grill 論点 7)

高密度に設計された人間プレゼンを機械精密文の隣で手 co-author するのは、 corpus 規模では維持不能 (ADR-0033 が受け入れた co-author の代償が高密度デザインで限界に達する)。 ゆえに人間プレゼンを機械 SSoT から別ファイルとして生成 (derive) する — これは ADR-0033 §2.3 が roadmap に残した Option A' (derive) を起動するものである (ただし same-DOM への埋込でなく別ファイル生成を採る、 §4 参照)。 生成は高能力モデルが行い、 更新は変更差分 + 現行の人間プレゼン HTML を渡して再生成し、 更新日時で同期を追跡する (機械 SSoT が唯一の真実源、 人間プレゼンは派生)。 ADR-0033 が「co-author の consistency を enforcement で担保」したのに対し、 本 ADR は「生成物の consistency を検証で担保」する (§2.5)。

§2.5 検証 — 2-gate + floor 刷新

生成物を 2 つの gate で担保する。 (a) persona walk ceiling — 非エンジニア persona で人間プレゼンを歩き、 「やさしい言語か・不明用語/不自然な日本語はないか・読者がそのページの仕事を果たせるか」を判定する (P-14 の「読者が仕事を果たせる」の意味検証)。 (b) fidelity check — 人間可視内容を機械 SSoT と突き合わせ、 「情報の脱落・意味の歪曲・元に無い主張の捏造」を検出する (「情報を落としすぎない」の機械寄り検証)。 加えて floor を刷新する: 「人間可視 prose の長さ (字数)」から「visual-first (地の文偏重の禁止) / 用語被覆 (未説明の専門語ゼロ) / renders-unbroken (render-gate)」へ — 長さでなく「視覚主・説明済み・破綻なし」を測る (ADR-0040 が長さしか測らなかった死角の是正)。 2-gate は EC 注文確定・決済の難要件で実証済: persona = 合格 (非エンジニアが読み通し要点を把握)、 fidelity = 生成 AI が元に無い RTM 行 (FR7→AC2→NFR1) を捏造したのを検出 — gate が飾りでなく load-bearing (生成は plausible-but-wrong を混ぜる、 検証がそれを止める) であることを実物で確認した。

§2.6 適用範囲 — γ (SRS 核 + 拡張パック)

design system の到達点 (「要件定義書を十分に構成しうる」の done-condition) はSRS 核を ISO/IEC/IEEE 29148 で完全性錨留めすることで定める (use-case / EARS と合成)。 folio 自身の corpus は SRS でない部分 (ADR = decision/WHY、 research = exploration、 constitution = 原則) を含むため、 これらは拡張パックとして後追いする (folio が自分の文書を組めない矛盾を避けつつ、「要件定義書として最適」の純度を核で保つ)。 部品 taxonomy の標準接地は epic 先頭 slice (folio-036) が担う。

§2.7 frozen 改訂宣言

本 ADR は ADR-0040 §2.1 (time-box 圧縮) / §2.2 (既定表示 = 人間プレゼン圧縮型) を「視覚 design system による再提示」へ改訂し、 ADR-0039 §2.4 (層別既定表示) を design system 部品で具体化する。 frozen である両 ADR の本文は触らず、 本 ADR が改訂を宣言し rules (living) が新規範を持つ (P-10 の divergence trace 流儀、 ADR-0040 自身がこの流儀を踏んだのと同型)。 ADR-0033 が roadmap に残した derive 原理を本 ADR が別ファイル形態で起動する (co-author → 生成への移行。 Option A' が想定した into-DOM 版は §4(R) で roadmap 据置)。 ADR-0040 の time-box (字数上限) は floor 刷新で置換され (長さ → visual-first 系)、 「一次資料層」(decisions/research を圧縮対象外とする区分、 ADR-0040 §2.6) は γ の「拡張パック後追い」に引き継がれる。

§3. Consequences

§4. Alternatives

§5. Trace

上位原則: ADR-0038 (P-14 — 本 ADR が P-14 を「視覚 design system + 生成 + 2-gate 検証」で実装)。 改訂対象: ADR-0040 §2.2 (圧縮 = 隠蔽の既定表示モデル → design system による再提示。 §2.1 の time-box 字数上限は floor 刷新で置換。 frozen 本文不変、 本 ADR が改訂を宣言)、 ADR-0039 §2.4 (層別既定表示を design system 部品で具体化)。 起動: ADR-0033 §2.3 が残した derive 原理を別ファイル形態で (Option A' の into-DOM 版は §4(R) roadmap 据置)、 co-author → 生成。 継承: ADR-0039 §2.5 (toggle)・§2.7 (warn→block 昇格規律)、 ADR-0037 (render-gate を floor 新 arm に流用)。 version: ADR-0030 (実装は後方互換 MINOR = 1.1.0、 strict-SemVer)。 規範化先: rules.html (design system + 生成 + 2-gate + floor 刷新の新規範 SSoT)。 REQ 追加先: verification.html (2-gate + floor 刷新)。 完全性 anchor: ISO/IEC/IEEE 29148 (SRS 部品 taxonomy)。 追跡: bd epic folio-c5g (子 task: folio-7rp 本 ADR / folio-036 taxonomy 接地 / folio-8oc 部品庫 / folio-ruc generator / folio-vhy 2-gate / folio-16y rules 規範化 / folio-94j 実コンテンツ proof / folio-ym8 1.1.0 bump)。 実証: EC 注文確定・決済 proof 2026-06-15 (persona = 合格 / fidelity = AI 捏造 RTM 行を検出)。 決定の経緯: user grill 2026-06-15 (診断 A → 視覚プレゼン → design system → deck×高密度 → 環境追従 → 情報保持 → 別ファイル生成 → γ scope) + 視覚サンプル反復。