docs/archive/theme-customization-implementation-plan.md

# テーマカスタマイズ機能実装計画

## 概要
commonCSSをテーマでカスタマイズ可能にし、既存のテーマ抽出機能と統合してHTML生成時に動的にスタイルを適用する機能を実装する。

## 現状分析

### 現在のHTML生成機能
- `ContentsHtmlService` がHTMLの生成を担当
- `commonCSS`（固定CSS）を利用してスタイリング
- 画像生成機能（Adobe Firefly）が組み込み済み
- ファイル場所：`server/services/html-preview/contents/contents-html.service.ts`

### 既存のテーマ抽出機能
- `ThemeExtractionService` が既に実装済み
- スクリーンショットからカラー・デザイン特性・ブランド印象を抽出
- 15色のカラーパレット対応
  - メインカラー：primary_color, secondary_color, accent_color
  - セマンティックカラー：success, warning, error, info
  - 背景色：primary, secondary, tertiary, overlay
  - テキスト色：primary, secondary, disabled, inverse
- フォントファミリー情報（heading、main、special）
- ファイル場所：`server/services/theme-extraction.service.ts`

## 批判的分析

### 方針の評価

**強み：**
- 既存のテーマ抽出機能が充実している
- カラー抽出機能が15色対応で包括的
- 段階的な実装アプローチが適切
- 既存のHTML生成フローとの親和性が高い

**課題と懸念：**
1. **CSS構造の複雑性**
   - 現在の `commonCSS` は1600行以上の巨大ファイル
   - セクション別・レスポンシブ対応など複雑な構造
   - nth-of-type セレクターによる詳細な背景色制御

2. **動的CSS生成の性能問題**
   - テーマ適用のたびにCSS全体を動的生成すると処理時間が増大
   - ブラウザでの CSS パース時間への影響

3. **CSS優先順位の問題**
   - 既存の詳細なセレクター（.section-base:nth-of-type(3n) など）とカスタムテーマの競合
   - 特異性の管理が複雑化

4. **保守性の課題**
   - CSSカスタマイズ機能追加により、既存コードの可読性・保守性が低下する可能性
   - デバッグ難易度の増加

## 第1段階：commonCSSのテーマ対応拡張

### 1. CSS構造の分析と設計

#### CSS変数システムの導入
```css
:root {
  /* カラーパレット */
  --primary-color: #5a6c7d;
  --secondary-color: #f8f9fa;
  --accent-color: #f59e0b;

  /* セマンティックカラー */
  --success-color: #10b981;
  --warning-color: #f59e0b;
  --error-color: #ef4444;
  --info-color: #3b82f6;

  /* 背景色 */
  --bg-primary: #ffffff;
  --bg-secondary: #f8f9fa;
  --bg-tertiary: #222222;
  --bg-overlay: rgba(0, 0, 0, 0.5);

  /* テキスト色 */
  --text-primary: #222222;
  --text-secondary: #555555;
  --text-disabled: #999999;
  --text-inverse: #ffffff;

  /* フォントファミリー */
  --font-heading: "YuGothic", "Yu Gothic Medium", sans-serif;
  --font-main: "YuGothic", "Yu Gothic Medium", sans-serif;
  --font-special: "YuGothic", "Yu Gothic Medium", sans-serif;
}
```

#### CSSテンプレート化
- **ベースCSS**: 構造・レイアウト・アニメーション
- **テーマCSS**: 色・フォント・装飾要素
- テーマ適用時にCSS変数のみを動的に変更

### 2. テーマカスタマイズエンジンの実装

#### 新規クラス：ThemeCustomizer
```typescript
export class ThemeCustomizer {
  /**
   * テーマ抽出結果からCSS変数を生成
   */
  generateCSSVariables(theme: ThemeExtractionResult): string;

  /**
   * カラーコードの妥当性検証
   */
  validateColors(colors: ColorTheme): boolean;

  /**
   * フォントファミリーのWeb安全フォント変換
   */
  sanitizeFontFamily(fontFamily: string): string;

  /**
   * アクセシビリティチェック（コントラスト比）
   */
  checkAccessibility(theme: ThemeExtractionResult): AccessibilityReport;
}
```

#### CSS生成の最適化
- 事前コンパイル済みベースCSS + 動的CSS変数
- メモリキャッシュでパフォーマンス向上
- 差分更新による最適化

### 3. ContentsHtmlServiceの拡張

#### 既存メソッドの拡張
```typescript
generateTemplateBasedHtml(
  tabName: string,
  sections?: ContentSection[],
  isDummyMode?: boolean,
  theme?: ThemeExtractionResult  // 新規追加
): { html: string; css: string }
```

#### 実装内容
- テーマが指定された場合はカスタムCSSを生成
- 既存機能との後方互換性を維持
- エラー時のフォールバック機能

## 第2段階：テーマ抽出機能の統合

### 1. HTML生成フローへの組み込み

#### 自動テーマ抽出モードの追加
```typescript
async generateContentsHtmlWithTheme(
  tabName: string,
  sections?: ContentSection[],
  options?: {
    isDummyMode?: boolean;
    autoExtractTheme?: boolean;
    referenceUrl?: string;
    customTheme?: ThemeExtractionResult;
  }
): Promise<{ html: string; css: string; batchId?: string; theme?: ThemeExtractionResult }>
```

#### フロー
1. 参照URLが指定されている場合、テーマを自動抽出
2. カスタムテーマが指定されている場合はそれを使用
3. どちらもない場合はデフォルトテーマを使用
4. 抽出/指定されたテーマをHTMLスタイルに反映

### 2. API拡張

#### エンドポイント修正
- 既存：`POST /api/contents-html`
- 追加パラメータ：
  ```typescript
  {
    theme?: ThemeExtractionResult;
    autoExtractTheme?: boolean;
    referenceUrl?: string;
  }
  ```

### 3. エラーハンドリングと品質保証

#### フォールバック機能
- テーマ抽出失敗時はデフォルトテーマを使用
- 無効なカラーコードの自動修正
- CSS生成エラー時の安全な代替処理

#### 品質チェック
- カラーアクセシビリティ（WCAG基準）
- ブランド適合性の基本チェック
- CSS妥当性検証

## 実装計画詳細

### 新規作成ファイル

#### 1. `server/lib/theme/theme-customizer.ts` （Phase 1.2 実装対象）
```typescript
export class ThemeCustomizer {
  // テーマカスタマイズ機能の中核
}

export interface AccessibilityReport {
  contrastIssues: string[];
  recommendations: string[];
  score: number;
}
```

#### 2. `server/lib/styles/theme-variables.ts` （Phase 1.2 実装対象）
```typescript
export const CSS_VARIABLES = {
  colors: {
    primary: '--primary-color',
    secondary: '--secondary-color',
    // ... 15色すべて
  },
  fonts: {
    heading: '--font-heading',
    main: '--font-main',
    special: '--font-special',
  }
};

export function generateCSSVariables(theme: ThemeExtractionResult): string;
```

#### 3. `server/lib/styles/base-css.ts` （Phase 1.2 実装対象）
```typescript
// CSS変数を使用した構造用ベースCSS
export const BASE_CSS = `
/* レイアウト・構造・アニメーション */
.container { ... }
.section-base { ... }
/* 色・フォントはCSS変数を使用 */
`;
```

### 修正対象ファイル

#### 1. `server/lib/styles/common-css.ts` （Phase 1.2 実装対象）
- 現在のハードコードされた色をCSS変数に変換
- セクション背景色ルールの変数化
- レスポンシブ対応の維持

#### 2. `server/services/html-preview/contents/contents-html.service.ts` （Phase 1.3 実装対象）
- `generateTemplateBasedHtml`メソッドにテーマパラメータ追加
- `generateContentsHtmlWithImages`にテーマ統合
- ThemeCustomizerの組み込み

### 実装優先度と順序

#### Phase 1: 基盤構築（優先度：高）
1. **CSS構造分析とベース設計** ✅
   - CSS詳細分析（1714行）完了
   - 70個以上のハードコード色特定
   - セレクター特異性マップ作成
   - CSS変数設計仕様書完成
2. ThemeCustomizerクラスの実装
3. CSS変数システムの基本構造
4. 色のみのテーマ適用（限定実装）
5. 基本的な動作確認

#### Phase 2: 機能拡張（優先度：中）
1. フォントファミリー対応
2. 完全なCSS変数化
3. エラーハンドリング強化
4. パフォーマンス最適化

#### Phase 3: 統合機能（優先度：中）
1. 自動テーマ抽出機能
2. API拡張とフロントエンド連携
3. アクセシビリティチェック
4. 包括的テスト

### リスク管理

#### 高リスク要素
1. **既存CSS構造の複雑さ**
   - 対策：段階的移行、詳細なテスト
   - 影響：既存HTML出力の崩れ

2. **パフォーマンス影響**
   - 対策：キャッシュ機能、最適化
   - 影響：レスポンス時間の増加

3. **ブラウザ互換性**
   - 対策：CSS変数フォールバック
   - 影響：古いブラウザでの表示問題

#### 中リスク要素
1. CSS優先順位の競合
2. 保守性の低下
3. デバッグ難易度の増加

### 品質保証計画

#### テスト項目
1. **回帰テスト**
   - 既存HTML出力との比較
   - 全セクションタイプでの動作確認

2. **互換性テスト**
   - 複数ブラウザでの表示確認
   - レスポンシブ動作の検証

3. **パフォーマンステスト**
   - CSS生成時間の測定
   - メモリ使用量の監視
   - ファイルサイズの最適化確認

4. **アクセシビリティテスト**
   - カラーコントラスト比の検証
   - スクリーンリーダー対応確認

### 成功指標

#### 技術指標
- CSS生成時間: 100ms以内
- 既存機能の100%互換性維持
- アクセシビリティスコア: AA準拠

#### 機能指標
- テーマ抽出成功率: 95%以上
- カラー適用精度: 90%以上
- フォント適用成功率: 90%以上

## 確定実装順序

### 作業順序の決定（2025年9月27日）

**批判的評価結果**: 詳細版Phase優先アプローチを採用

#### 確定作業フロー
1. **詳細版Phase1**: CSS構造分析とベース設計 ✅ **完了**
   - CSS詳細分析（1714行）完了
   - 70個以上のハードコード色特定
   - セレクター特異性マップ作成
   - CSS変数設計仕様書完成

2. **詳細版Phase2**: ThemeCustomizerクラス実装 🔄 **次期実装**
   - ThemeCustomizerクラス実装
   - CSS変数システム構築
   - 単体テスト実施

3. **詳細版Phase3**: ContentsHtmlService拡張 ⏳ **待機**
   - ContentsHtmlService拡張
   - 既存機能100%回帰テスト
   - 基盤部分の品質確保

4. **概要版Phase2**: 機能拡張 ⏳ **後続**（安定基盤上での拡張）
   - フォントファミリー対応
   - 完全なCSS変数化
   - パフォーマンス最適化

5. **概要版Phase3**: 統合機能 ⏳ **最終**
   - 自動テーマ抽出機能
   - API拡張とフロントエンド連携
   - 包括的テスト

#### 採用理由
1. **リスク最小化**: 高リスク要素に集中し、段階的実装でロールバック可能
2. **技術的依存関係**: 基盤完成後の機能拡張により安定性確保
3. **品質保証**: 詳細版Phase3で基盤品質確保後、機能拡張に移行

## まとめ

この計画により、既存のHTML生成機能を損なうことなく、段階的にテーマカスタマイズ機能を実装できます。特に重要なのは：

1. **段階的実装**による リスク最小化
2. **既存機能との互換性**の維持
3. **パフォーマンス**への配慮
4. **保守性**の確保

**確定方針**: 詳細版Phase1〜3を完全に完了させてから、概要版Phase2以降に移行します。実装時は各段階で十分なテストを行い、問題があれば前の段階に戻れる柔軟性を保つことが重要です。