Hugging Face's logo

Spaces:
KazukiWatanabe
/
FE_Dev
Sleeping

App Files Community
FE_Dev / docs /archive /theme-customization-implementation-plan.md
GitHub Actions
Deploy from GitHub Actions [dev] - 2025-10-31 07:28:50
68f7925
preview code
|
raw
history blame contribute delete
11.7 kB

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

概要

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変数システムの導入 

: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 

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の拡張

既存メソッドの拡張 

generateTemplateBasedHtml(
  tabName: string,
  sections?: ContentSection[],
  isDummyMode?: boolean,
  theme?: ThemeExtractionResult  // 新規追加
): { html: string; css: string }

実装内容

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

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

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

自動テーマ抽出モードの追加 

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
  • 追加パラメータ：
    {
  theme?: ThemeExtractionResult;
  autoExtractTheme?: boolean;
  referenceUrl?: string;
}

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

フォールバック機能

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

品質チェック

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

実装計画詳細

新規作成ファイル

1. server/lib/theme/theme-customizer.ts （Phase 1.2 実装対象） 

export class ThemeCustomizer {
  // テーマカスタマイズ機能の中核
}

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

2. server/lib/styles/theme-variables.ts （Phase 1.2 実装対象） 

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 実装対象） 

// 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以降に移行します。実装時は各段階で十分なテストを行い、問題があれば前の段階に戻れる柔軟性を保つことが重要です。