MAS-356: Tremor + v0.dev 採用（フロントエンド UI コンポーネント生成効率化）

概要

背景・目的

現状の課題

bizlp コックピットのフロントエンドは React + Vite + カスタム CSS で構成されている。

解決策

Tailwind CSS v4 + Tremor v3 (@tremor/react) をダッシュボード専用 UI 基盤として導入し、v0.dev をコード生成ワークフローに組み込む。

現状: カスタム CSS (2,673 行) + React JSX 手書き
導入後: Tailwind ユーティリティ + Tremor コンポーネント + v0.dev で生成加速

Tremor / v0.dev の位置づけ

技術スタックの変更

現状

React 18 + Vite 5 + TypeScript
vite-plugin-singlefile (全 JS/CSS を 1 HTML にインライン化)
カスタム CSS のみ (cockpit.css / sidebar.css)
chart.js + d3-sankey (チャート)

導入後

React 18 + Vite 5 + TypeScript              ← 変更なし
vite-plugin-singlefile                       ← 変更なし (制約:後述)
Tailwind CSS v4 (@tailwindcss/vite)          ← 新規追加
Tremor v3 (@tremor/react)                    ← 新規追加 (ダッシュボード用)
カスタム CSS (既存パネルはそのまま維持)      ← 共存
chart.js + d3-sankey                         ← 変更なし

重要制約と事前検証項目

制約 1: vite-plugin-singlefile によるインライン化

GAS HtmlService の CSP 制約上、vite-plugin-singlefile で全 JS/CSS を 1 HTML にインライン化している。Tailwind と Tremor の追加はバンドルサイズに直接影響する。

GAS HtmlService のファイルサイズ上限は公式ドキュメント未記載だが、実績上 数 MB は問題ない。ただしブラウザロード時間は GAS Web App の ?embedded=1 iframe 内で体感するため、目標上限を設ける。

Tailwind v4 の PurgeCSS 相当機能 (@tailwindcss/vite の tree-shaking) により、使用していないユーティリティクラスは最終バンドルに含まれない。Phase 2 完了後にビルドサイズを実測してから続行判断する（ゴーサイン判定）。

制約 2: 既存 cockpit.css との共存

cockpit.css (2,673 行) は既存パネル全体の見た目を定義している。Tailwind を導入すると CSS Reset (preflight) が既存スタイルと衝突する可能性がある。

対処方針: @layer base { ... } で Tailwind の preflight を Tremor 専用スコープに閉じ込める。具体的には tremor-scope.css で @scope .tremor-root { @tailwind base; ... } として既存 CSS に影響させない。

制約 3: Tremor v3 の安定性

Tremor は v2 が安定版・v3 が shadcn/ui ベースへの移行版（2025 年時点で開発中）。Phase 2 着手前に @tremor/react の最新安定版をピン留めし、CHANGELOG を確認すること。 v3 の API が破壊的変更を含む場合は v2 (@tremor/[email protected]) で代替する。

実装仕様

Phase 1 — Tailwind CSS v4 導入

目的: Tremor と v0.dev 産物コードの両方の前提条件を整える。

1-A. 依存追加

cd webapp_client
npm install --save-dev tailwindcss @tailwindcss/vite
# Tremor が v2 なら: npm install @tremor/react tailwindcss@3  (v3 なら上記のみ)

1-B. vite.config.ts 変更

import tailwindcss from '@tailwindcss/vite';        // 追加

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),   // ← react() の後に追加
    viteSingleFile(),
  ],
  // ... 既存設定は変更なし
});

1-C. tremor-scope.css — Tailwind を Tremor 専用スコープに閉じ込める

ファイル: webapp_client/src/styles/tremor-scope.css

/*
 * MAS-356: Tremor コンポーネントにのみ Tailwind を適用するスコープ境界。
 * .tremor-root クラスを持つ要素の内側にのみ Tailwind の preflight と
 * ユーティリティが適用され、既存 cockpit.css との衝突を防ぐ。
 */
@import "tailwindcss" layer(tremor);

@layer tremor.base {
  /* Tailwind preflight をここに閉じ込める (既存 CSS に影響させない) */
}

既存の cockpit.css の先頭に @import './tremor-scope.css'; を追加する（cockpit / multiyear ビルドのみ）。

1-D. 動作確認

npm run build:cockpit が成功し、financial_cockpit.html のサイズが大幅増加していないことを確認する（Tailwind のみでは PurgeCSS が効くため数 KB 増程度が期待値）。

Phase 2 — Tremor 試験採用（CapitalAllocationPanel）

目的: CapitalAllocationPanel.tsx（639 行）の KPI 表示部分を Tremor コンポーネントに置き換えて、実装品質とバンドルサイズを実測する。

2-A. Tremor 依存追加

npm install @tremor/react
# v3 の場合は追加で: npm install @headlessui/react (依存)

2-B. 置き換えターゲット

CapitalAllocationPanel 内の以下の表示を Tremor コンポーネントに移行する。

移行方針: 既存コンポーネントを一括置換せず、セクション単位で段階的に置き換える。Tremor コンポーネントには .tremor-root クラスを持つ親 <div> でラップして CSS スコープを確保する。

// 移行前
<div className="cap-alloc-bucket-bar">
  <div style={{ width: `${defenseRatio * 100}%` }} className="bucket-defense" />
  ...
</div>

// 移行後
<div className="tremor-root">
  <ProgressBar value={defenseRatio * 100} color="blue" label="防衛" />
  <ProgressBar value={strategicRatio * 100} color="amber" label="戦略投資" />
  <ProgressBar value={surplusRatio * 100} color="rose" label="純余剰" />
</div>

2-C. ゴーサイン判定（バンドルサイズ計測）

Phase 2 完了後に npm run build:cockpit を実行し、サイズを計測する。

ls -la templates/financial_cockpit.html

Phase 3 — v0.dev ワークフロー確立

目的: v0.app を使ったコンポーネント高速生成フローをチームの開発標準として文書化する。

3-A. v0.dev の位置づけと制限

v0.dev は 外部 Web ツール であり npm 依存ではない。出力されたコードを手動でプロジェクトにコピーして使う。

制限事項:

• v0 の産物は Tailwind + shadcn/ui ベースのため、Phase 1 完了（Tailwind 導入済み）が前提
• google.script.run / GAS API 等のビジネスロジックは v0 では生成できない → UI シェルのみ生成してロジックを後付けする
• v0 産物の外部 CDN 参照（フォントリンク等）は GAS CSP 違反 → 産物受け取り後に必ず削除

3-B. cockpit パネル向けプロンプトテンプレート

v0.dev に入力するプロンプトのひな型を確立する。

以下の仕様で React + Tailwind + Tremor のダッシュボードパネルを生成してください。

## コンテキスト
- GAS Web App 内の iframe で動作する SPA
- 外部フォント・外部 CDN の参照禁止（import 文でのみ依存解決）
- 既存: 背景色 #1e2330 のダークナビ + #f5f5f5 のメインコンテンツ

## 生成するコンポーネント
[コンポーネント名と要件をここに記述]

## 使用可能なコンポーネント
- Tremor: Card, Metric, Badge, ProgressBar, List, Callout, AreaChart
- shadcn/ui: Button, Select, Tabs

## 制約
- Props 経由で全データを受け取る（fetch 禁止）
- className は既存の cockpit-section クラスと共存可能な形で

3-C. ワークフロー文書

以下のフローを docs/_internal/ai_agent_tips.md の「§8 フロントエンド UI 生成」として追記する。

1. v0.app でプロンプト入力（上記テンプレート使用）
2. 産物コードをコピー
3. 外部 CDN 参照を除去（import 'https://...' 等を削除）
4. .tremor-root ラッパーを追加
5. Props 型定義を sidebar_api.d.ts のデータ型に合わせる
6. npm run build:cockpit でサイズ確認
7. 動作確認（dev サーバーまたは GAS dev 環境）

エッジケース・異常系

ファイル変更マトリクス

推奨実行モデル

受け入れ条件

• npm run build:cockpit が成功する（サイズが 800KB 超の場合はファイル分割で対処・Tremor 採用は継続）
• npm run type-check がエラーなし
• 既存コックピットパネル（CompensationStrategyPanel / SoloFinancialStatementsPanel 等）の表示に変化なし
• CapitalAllocationPanel の 3 バケツバー / ROE / Rule of 40 が Tremor コンポーネントで表示される
• v0.dev プロンプトテンプレートが ai_agent_tips.md に追記されている
• .tremor-root 外のパネルには Tailwind の影響が出ない

依存関係

• MAS-355 部分完了: CapitalAllocationPanel.tsx の試験ターゲットとして使用するため、Phase 2 の CSS/JSX 構造を確認済みであること（実装済み・webapp_client/src/cockpit/CapitalAllocationPanel.tsx として存在確認済み）
• 後続 MAS-358: 本案件完了後、CockpitNavSidebar.tsx 実装で Tremor Sidebar / SidebarItem を活用できる
• 後続 MAS-357: Firebase Hosting 移行後も Tailwind / Tremor は動作継続（npm バンドルのため外部 CDN 参照なし）

Phase 4: ローカル UI 開発環境 + ビジュアル回帰テスト（実装済）

背景

GAS HtmlService は Google 認証が必要なため、UI の確認のたびに clasp push → デプロイ（20〜30秒）が必要だった。 Playwright によるスクリーンショット比較も GAS URL では自動化が困難。

解決策

Vite dev server + GAS モック + Playwright の 3 層構成で、GAS なしで UI 開発・テストができる環境を整備した。

UI の形を作る  → localhost で高速イテレーション（GAS 不要）
     ↓
形が決まったら → GAS にデプロイして実データで最終確認

構成ファイル

開発フロー

# 1. ローカルで UI を確認
npm run dev:cockpit          # http://localhost:5173/financial_cockpit.html

# 2. 変更後にテストで差分確認
npm run test:ui              # 差分 2% 超で失敗 + diff 画像生成

# 3. 意図した変更なら baseline を更新
npm run test:ui:update       # 新しいスクリーンショットを baseline として保存

# 4. GAS にデプロイして実データで最終確認
npm run deploy:dev

CI フロー（GitHub Actions）

PR 作成
  ↓
ui-test.yml が自動実行（Ubuntu）
  ↓
Linux snapshot が未存在 → 自動生成してコミット（初回のみ）
Linux snapshot が存在  → 前回 baseline と比較
  ↓
差分なし → 通過
差分あり → 失敗 + visual-diff artifact に diff 画像をアップロード

PR の Artifacts から visual-diff をダウンロードすると、変更箇所を赤くハイライトした diff 画像で確認できる。 意図した UI 変更の場合は npm run test:ui:update を実行して baseline を更新してから再 push する。

制約・注意事項

• GAS 実データとの差異: localhost はモックデータ（固定値）を使用。実データの edge case（金額が極端に大きい等）はGAS で最終確認が必要
• GAS iframe 環境: HtmlService の iframe 内での挙動は Playwright では再現できない
• プラットフォーム別 baseline: macOS（-darwin.png）と Linux CI（-linux.png）でフォント描画が微妙に異なるため別ファイルで管理
• ブラウザ: Chromium（Chrome）のみ。Safari / Firefox は対象外

変更履歴