Evaluation v0.13 Three Perspectives

Schatten Design System 評価レポート v0.13（3視点）

対象: @yasmro/schatten v0.13.0 作成日: 2026-06-23 スコープ: Evaluation-v0.4-and-Roadmap を基準に、v0.4 → v0.13 の変化を スタッフエンジニアリング / デザインストラテジスト / ブランディングストラテジスト の3視点で再評価 基準ページ: Evaluation-v0.4-and-Roadmap

---

エグゼクティブサマリ

v0.4 で挙げた Top 6 ギャップのうち 5 つが解消し、DS は「原型」から「出荷可能なシステム」へ移行した。lv1 は 18 → 25 個に増え、v0.4 で空白だった ナビ系（DropdownMenu / Popover / Tabs）・データ系（Table） が埋まった。最大の前進は、v0.4 で最低評価だった SSR 互換性（⭐→⭐⭐⭐⭐⭐） と、宣言止まりだった framework-agnostic CSS の契約化（.st-* クラス + manifest + per-component subpath）。

残る前線は v0.4 と同じ 合成層（lv2）・1.0 API 契約の発効・ブランドの物語化 の3点に収斂しており、これらはもはや 技術的未熟 ではなく 1.0 に向けた意思決定 の問題に変わっている。

総合スコア（v0.4 → v0.13）

観点	v0.4	v0.13	Δ	v0.13 の根拠（一言）
トークン体系	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	→	state を 4→5-token（emphasis）化、semantic shadow/radius/motion + z-index 帯、tokens.ts 型付き。天井のまま深化
ブランドアイデンティティ	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	→	serif family + JP/EN cap-height 補正を全体適用、朱(vermillion)/red を別 primitive に分離する governance seam（#238/#239）
コンポーネント網羅性	⭐⭐⭐	⭐⭐⭐⭐	▲+1	18→25。DropdownMenu/Popover/Tabs（ナビ）・Table（データ）・Card/Avatar/Skeleton で空白を充填。残: Pagination/Breadcrumb/charts/lv3
合成層 (lv2)	⭐	⭐⭐	▲+1	依然空 stub。ただし「いつ作るか」を post-1.0 と明文化 + 依存方向/lv1→lv1 規約は確定。promotion 基準自体はまだ未定義
テーマ拡張性	⭐⭐⭐	⭐⭐⭐⭐	▲+1	--color-solid を theme ramp 段参照に再配線（#150）し季節色が solid 面全体に波及、Mode×Special を形式化。残: 外部 Special API・allowlist lint・Theming 非表示
a11y	⭐⭐⭐	⭐⭐⭐⭐⭐	▲+2	全 lv1 VRT に @axe-core/playwright（WCAG 2.1 AA）を blocking 化（#346）、コントラスト負債解消（#344）、labelId 命名（#345）、required→aria（#428）
ドキュメント	⭐⭐⭐	⭐⭐⭐⭐	▲+1	Foundations 8 種 + Patterns 7 種 + CSS API、7グループ IA 固定（#320）。残: Theming 非表示・migration/CONTRIBUTING 未了
採用導線	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	▲+1	per-component CSS subpath（/css/*）+ 3 配信モード + Lighthouse mapping + critical CSS recipe。部分採用が component 粒度に
ガバナンス	⭐⭐	⭐⭐⭐⭐	▲+2	changeset CI 強制・audit job blocking（#307）・ADR ディレクトリ（docs/decisions/）・release skill。残: CONTRIBUTING・develop version desync
配布・バージョニング	⭐⭐⭐	⭐⭐⭐⭐	▲+1	develop→main リリースフロー確立 + changeset 駆動 + npm publish/GitHub Release + multi-entry。残: 1.0 未切り・develop 版ずれ運用穴
アーキテクチャ	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	▲+1	component-architecture.md + Biome 境界 lint で core/variants/themes を React-free 強制。v0.4 の「外部依存の境界が曖昧」を機械化
パフォーマンス	⭐⭐	⭐⭐⭐⭐	▲+2	lucide を peerDep 化 + sideEffects 宣言 + size-limit CI（per-comp 1.5KB / 集約上限）。残: 実 Lighthouse 数値の継続計測
SSR 互換性	⭐	⭐⭐⭐⭐⭐	▲+4	tsup banner が 'use client' 注入、ThemeProvider に SSR/hydration test、FOUC snippet を byte-pin + CSP hash、Remix/Astro ガイド
TestID 規約	⭐⭐	⭐⭐⭐⭐⭐	▲+3	component-testid-guideline.md（pass-through/compound/Portal/curated 例外/no-auto-testid）+ Patterns/Testing 実例 story
Theme 切替 API	⭐⭐	⭐⭐⭐⭐⭐	▲+3	src/providers/ThemeProvider 出荷、localStorage 契約（schatten-theme {mode,special}）+ FOUC 初期化を提供
AI 親和性	⭐⭐⭐	⭐⭐⭐⭐⭐	▲+2	token autocomplete 可（tokens.ts）+ AGENTS.md + .claude/rules/ 群 + skills/hooks + no-primitive-color lint + manifest
コード堅牢性	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	▲+1	名指しの 2 欠点を解消 — changeset 強制 + audit:coverage で test/VRT 抜けを blocking、区分 C/D に interaction test 必須化
合計	50 / 85	76 / 85	+26	59% → 89%

読み方（3点）

• 最大の伸びは SSR 互換性（⭐→⭐⭐⭐⭐⭐, +4） — v0.4 で「App Router で破綻」と最低評価だった項目が、'use client' banner + FOUC + Provider で完全反転。次いで TestID / Theme 切替 API が +3。
• 唯一 ⭐⭐ 以下に残るのは「合成層 (lv2)」 — 17観点でここだけが 4 未満。v0.4 の「いつ作るかの規範がない」は 部分的に 答えた（post-1.0 と明記 + 依存規約は確定）が、lv2 実体ゼロ は変わらず。1.0 の最大論点。
• 天井（⭐⭐⭐⭐⭐）維持の 2 項目（トークン体系・ブランド） は据え置きに見えて、5-token 化・cap-height 補正・seasonal 機能化で 中身は v0.4 より明確に厚くなっている（星に表れない深化）。

---

1. スタッフエンジニアリング視点

良くなった点

• 「framework-agnostic」が宣言から契約になった。 これが v0.4→v0.13 最大の成果。.st-* クラスが schatten.manifest.json に列挙され、pnpm check:manifest がリネーム/削除/追加を PR diff で見せる。CSS は 名前（manifest）とコスト（size-limit per-component 予算）の二重契約 で締められている。「公開 API とは何か」が文章でなく機械で定義されている DS は OSS でも稀。
• 多層防御が機能配置として成立。 edit 時 hook（非ブロッキング）→ PR 時 audit / a11y / manifest / size / check:layer-order（ブロッキング）と、同じ関心事を別タイミングで二重に守る設計が言語化されている。「規約が人の頭の中」だった v0.4 からの質的転換。
• a11y が観察モードからブロッキングへ。 @axe-core/playwright（WCAG 2.1 A/AA）を全 lv1 VRT に対で配置し、#344 のコントラスト負債（state token を 5-token 化し emphasis rung 新設）を解消したうえで #346 でゲートを blocking 化。
• 依存リスクの形式知化。 api-stability.md の "visual-contract-affecting dependencies" 表（lucide / radix / tailwind / vite / sonner）が prepare-release skill の dep 検出と接続され、バンプだけで視覚契約が壊れる依存を release 前に必ず parity VRT に通す。vite は exact pin / vitest は caret という非対称も理由つきで設計。

残る改善点

• lv2 不在 = v0.4 の gap は「閉じた」のではなく「先送り」。 「AI も人間も合成を毎回再発明する」問題は まだ解消していない。25 個も primitive が揃った今、合成発散のコストは v0.4 時より むしろ上がっている。「1.0 を primitive 完成で切る」のか「最初の lv2 を 1.0 に含める」のかを早めに確定すべき。
• API stability 契約が「書いてあるが未発効」。 api-stability.md は v1.0.0 から有効で、本文自身が「RC 前に全文を実体と突合せよ」と明記。CSS 変数監査（#231）・クラス名監査の最終 reconcile が 1.0 ブロッカーとして残る。
• 区分 C/D の interaction-test 規律の維持。 #318（Toast の close ボタンが緑のまま壊れていた）の教訓で「JS 必須コンポーネントは実ブラウザ interaction test 必須」が guideline 化されたが、これは 規律であってゲートではない。lint/hook への昇格余地。
• Special allowlist の build-time lint が未実装の可能性。 theme-architecture.md は allowlist を「v0.7.0 で enforcement、それまで hand-checked convention」とする。seasonal が --color-theme-* 以外を書かない保証が まだ目視依存 なら、token 漏れの構造防止が theme 軸だけ穴になっている。

---

2. デザインストラテジスト視点

良くなった点

• token システムが「綺麗」から「正しい」へ。 state token を 4→5（emphasis）に拡張し、淡背景の色文字を AA 4.5:1 に。solid の trilemma は「色のみに依存しない（icon+label / WCAG 1.4.1）」として例外を 明文化して 残す——美学でなく根拠で線を引いている。semantic shadow/radius/motion、z-index 帯予約も追加。
• seasonal が「飾り」から「機能」へ。 --color-solid を theme ramp の段参照に再配線（#150）したことで、季節テーマ適用で Button primary / Badge・Callout・Toast の neutral×solid が 季節色で再着色される。v0.4 で「影響面が狭い」と評された差別化要素が、初めて UI 全体に効くようになった。
• docs IA が固定 7 グループに収束。 Welcome / Getting Started / Tokens / Theming / CSS API / Patterns / Components の taxonomy が #320 spike で確定し、Foundations ページ（Spacing/Elevation/Motion/Iconography/Radius/Z-Index/Typography/Color）と Patterns（Form States/Composition/asChild/Layout/Testing/Data Table/Accessibility）が出揃った。
• variant 語彙が Pattern A/B に統一。 Role 単軸（Button）と Tone×Shape 二軸（Badge/Callout/Toast）の選択基準が文書化され、treatment→appearance・default→neutral のリネームも完了。v0.4 の「variant vocabulary inconsistency」は解消。

残る改善点

• Theming セクションが現在「非表示」。 #410 で Theming をサイドバーから一旦隠している。ThemeAudit / SeasonalShowcase の story と VRT baseline は存在するのに、デザイナー向けの 8 Special × 2 Mode 監査面が読者に見えていない。seasonal の payoff を機能させた直後だけに露出していないのは戦略的にもったいない。
• radius が「定義のみ」で適用待ち。 --radius-control / --radius-surface は define-only（Radius story に「defined only」バッジ）。Button/Input の角丸適用は別 spike。token は AA まで磨かれた一方、形（shape）の言語はまだ半分。
• 合成の設計言語が docs 止まり。 FormField / PageHeader / ConfirmDialog 等「画面で繰り返す塊」は Pattern recipe としてしか存在しない。デザイナーが Figma で組む単位とコードで再利用できる単位がまだ一致しない（= lv2 不在の設計面での現れ）。
• density / responsive の軸が未着手。 size は sm/md/lg 固定で、密度・ブレークポイント連動の token はない。data 系（Table）が入った今、次に要求されやすい軸。

---

3. ブランディングストラテジスト視点

良くなった点

• 和の美学が token から typography まで一貫。 serif family（EB Garamond / Noto Serif JP）追加に加え、JP/EN の cap-height 補正を font-size-adjust で library 全体に適用（#400）——欧文混じりの見た目を CJK 高さに揃える処理を単一値で全 family に効かせる。ink/sumi/vermillion/alabaster の primitive 体系、朱(vermillion) と danger-red を 値同一でも別 primitive に分離 する governance seam（#238/#239）。ブランド色とエラー色を将来独立に retune できる土台。
• 「影 (Schatten)」の世界観が機能的差別化に接続した。 季節という時間軸を持つ DS は OSS でほぼ唯一で、それが上記 solid 再配線で実 UI に効くようになった。ブランド = 飾りでなく システムの振る舞い になった。

残る改善点

• ブランドの「物語」が docs で語られていない。 token には強い世界観があるのに、Theming は非表示、Welcome も deep-link カード中心。#320 で「primary 読者は統合担当でなく評価者」と定めた以上、最初の 5 秒で「Schatten とは何か（影・墨・紙・季節）」を語る面 が要る。今は実装の正しさが勝ち、物語が負けている。
• 命名 surface の 1.0 凍結前ブランド判断が未了。 --vermillion-* をブランド名で残すか中立名にするか、danger-red を朱から色相分岐させるか（#239 デザイナー spike）は未解決。CSS 変数監査（#231）が 1.0 ブロッカー。ブランド語彙の 永続性 をここで決め切る必要がある。
• brand-as-platform（外部 Special）は将来。 seasonal は internal-only で、consumer-authored brand palette（vendor 名前空間 <vendor>--<variant>）は未実装。「他社がこの DS に自社ブランドを載せる」ストーリーはまだ語れない。
• コンポーネント/token を超えたブランド資産がない。 ロゴ・モーション identity・イラスト/写真トーン・voice&tone は範囲外。portfolio 作品としては、color/type 以外の identity moment（例: loading = 墨の滲み、empty state の世界観）を 1 つ作ると訴求が跳ねる。

---

総括 — 各視点の「次の一手」

視点	v0.4→v0.13 の到達点	最優先の次の一手
スタッフエンジニアリング	宣言を 機械検証可能な契約 に変えた（CSS API + manifest + 多層ゲート）。	1.0 の境界を確定 — lv2 を 1.0 に含めるか、API 契約（#231 / クラス名監査）を発効させて primitive 完成で切るか。
デザインストラテジスト	token を AA まで正しくし、seasonal を機能させた。	Theming を再露出 し、合成（lv2/FormField 等）の設計言語を docs から型へ昇格。
ブランディングストラテジスト	和の美学を typography 補正まで一貫させ、季節を振る舞いにした。	ブランドの物語面 を 1 枚作り、命名の永続性（#239/#231）を 1.0 前に決め切る。

一言で言えば — v0.4 で挙がった「実装としての穴」（framework-agnostic 未操作化・SSR・型・カバレッジ）は ほぼ全て塞がり、残る前線は lv2（合成層）・1.0 API 契約の発効・ブランドの物語化 の3点に収斂した。これらは 技術的未熟 ではなく 1.0 に向けた意思決定の問題 に変わっており、健全な進化と言える。

---

関連: Evaluation-v0.4-and-Roadmap（基準ページ） / 開発基盤 / 季節テーマ