v0.7.8: fix text/background contrast across all themes

- Add WCAG 2.1 luminance helpers (luminance, pickTextColor) to JS renderer
- Fix hardcoded colors in addSlideHeader, renderTitleSlide, renderTimelineSlide,
  renderFunnelSlide, renderProcessSlide, renderSwotSlide
- Funnel labels now auto-select light/dark text per segment fill color
- Process step fills now follow active theme instead of hardcoded pastels
- SWOT quadrant colors now derive from chartColors
- Python pptx_renderer _get_colors() merges full theme palette from templates
- Add color/contrast docs to SKILL.md and USER_GUIDE (en/zh-CN/ja)
- Bump version to 0.7.8

Author: lijunliu-gh

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.7.8] - 2026-03-24
+
+### Fixed
+
+- **Text/Background Contrast Across Themes** — Added WCAG-based luminance helpers (`luminance()`, `pickTextColor()`) to JS renderer. Fixed hardcoded text colors in `addSlideHeader()`, `renderTitleSlide()`, `renderTimelineSlide()`, `renderFunnelSlide()`, `renderProcessSlide()`, and `renderSwotSlide()` to use theme-aware colors instead of always using dark `closingBg`. Funnel stage labels now dynamically choose light or dark text based on each segment's fill color. Process step backgrounds now follow the active theme instead of hardcoded pastels. SWOT quadrant colors now derive from `chartColors`. Python renderer `_get_colors()` now merges full theme palette (text, background, closing colors) from templates. All 6 built-in themes (including dark-executive and tech) now render with correct contrast.
+
 ## [0.7.7] - 2026-03-23
 
 ### Changed

ROADMAP.md

@@ -1,14 +1,14 @@
 # Project Status
 
-Current version: **v0.7.7**
+Current version: **v0.7.8**
 
 Product positioning: **to-B PPT generation engine** — embeddable into enterprise AI workflows with private deployment, API-driven generation (MCP / CLI / HTTP), and multi-language support (CJK + English). Core differentiators are data security (no data leaves the enterprise), content intelligence (AI-driven layout and visualization selection), and cross-platform output (PowerPoint, Keynote, Google Slides).
 
 Current release posture: **published in its current scope**. This repository is being released as a personal open-source project in maintenance mode. No additional roadmap items are currently committed.
 
 ---
 
-## Current Capabilities (v0.7.7)
+## Current Capabilities (v0.7.8)
 
 | Area | What's Included |
 |------|----------------|
@@ -43,6 +43,7 @@ This repository is published as a stable personal-project snapshot.
 
 | Version | Milestone |
 |---------|-----------|
+| v0.7.8 | Fix text/background contrast across all themes; WCAG luminance-aware rendering |
 | v0.7.7 | Current-scope release alignment; roadmap converted to project status / maintenance posture |
 | v0.7.6 | Release metadata audit cleanup and public baseline verification |
 | v0.7.5 | README positioning update for personal-project release |

SECURITY.md

@@ -29,7 +29,7 @@ Examples include:
 
 ## Implemented Mitigations
 
-As of v0.7.7, the following security controls are in place:
+As of v0.7.8, the following security controls are in place:
 
 - **Path traversal prevention**: file paths are resolved and validated to stay within the project directory
 - **SSRF blocking**: URL targets are validated to reject private/internal network addresses

SKILL.md

@@ -139,7 +139,16 @@ When using chart layout, always populate concrete data:
 - If no real data is available, use realistic placeholders and note it in assumptions
 - Never leave categories or series as empty arrays
 
-The system automatically validates chart data after generation. If a chart slide has invalid data (empty categories, missing series, or non-numeric values), it falls back to a bullet layout and records the fallback in assumptions.
+The system automatically validates chart data after generation.
+
+## Color and Contrast
+
+The renderer uses WCAG 2.1 relative-luminance detection to pick readable text colors automatically. When choosing themes or creating custom ones:
+
+- **Light themes** (business-clean, corporate-blue, warm-modern, minimal): dark text on light slide backgrounds
+- **Dark themes** (dark-executive, tech): light text on dark slide backgrounds
+- Chart labels and funnel stage text auto-select light or dark based on the segment fill color
+- Custom themes should ensure all text/background pairs meet a minimum 4.5:1 contrast ratio If a chart slide has invalid data (empty categories, missing series, or non-numeric values), it falls back to a bullet layout and records the fallback in assumptions.
 
 ## Narrative Guidance
 

docs/USER_GUIDE.en.md

@@ -304,6 +304,17 @@ Create a JSON file following the schema in `assets/themes/theme-schema.json`:
 
 Pass a custom theme file path via `--theme /path/to/my-brand.json`.
 
+### Color and Accessibility
+
+The renderer uses WCAG 2.1 luminance detection to ensure readable text on all backgrounds. This works automatically for all 6 built-in themes, including dark themes like `dark-executive` and `tech`.
+
+When creating custom themes, ensure text/background color pairs meet WCAG AA contrast (minimum 4.5:1 for normal text, 3:1 for large text):
+
+- **Light theme example**: `text: "1A202C"` on `slideBg: "FFFFFF"` — 16.1:1 contrast ✓
+- **Dark theme example**: `text: "E2E8F0"` on `slideBg: "0F172A"` — 12.6:1 contrast ✓
+
+Chart labels and funnel stage text automatically switch between light and dark based on each segment's fill color.
+
 ## Chart Data Handling
 
 When slides use the `chart` layout, the system validates chart data automatically:

docs/USER_GUIDE.ja.md

@@ -233,6 +233,17 @@ npm run revise:mock
 
 `assets/themes/theme-schema.json` のスキーマに従って JSON ファイルを作成します。`--theme /path/to/my-brand.json` でカスタムテーマファイルを指定できます。
 
+### カラーとアクセシビリティ
+
+レンダラーは WCAG 2.1 の輝度検出を使用して、すべての背景上でテキストが読みやすくなるよう自動調整します。`dark-executive` や `tech` などのダークテーマを含む 6 つのビルトインテーマすべてに自動対応しています。
+
+カスタムテーマを作成する際は、テキスト/背景の色ペアが WCAG AA コントラスト基準（通常テキスト最低 4.5:1、大テキスト 3:1）を満たすようにしてください：
+
+- **ライトテーマ例**: `text: "1A202C"` × `slideBg: "FFFFFF"` — コントラスト比 16.1:1 ✓
+- **ダークテーマ例**: `text: "E2E8F0"` × `slideBg: "0F172A"` — コントラスト比 12.6:1 ✓
+
+チャートラベルやファネルステージのテキストは、各セグメントの塗りつぶし色に基づいてライト/ダークを自動切り替えします。
+
 ## チャートデータの処理
 
 スライドが `chart` レイアウトを使う場合、システムが自動的にデータを検証します:

docs/USER_GUIDE.zh-CN.md

@@ -276,6 +276,17 @@ npm run revise:mock
 
 通过 `--theme /path/to/my-brand.json` 传入自定义主题文件。
 
+### 颜色与无障碍
+
+渲染器使用 WCAG 2.1 亮度检测，确保所有背景上的文字可读。6 个内置主题（包括 `dark-executive` 和 `tech` 等深色主题）均已自动适配。
+
+创建自定义主题时，请确保文字/背景颜色对的对比度满足 WCAG AA 标准（普通文字最低 4.5:1，大文字 3:1）：
+
+- **浅色主题示例**：`text: "1A202C"` 配 `slideBg: "FFFFFF"` — 对比度 16.1:1 ✓
+- **深色主题示例**：`text: "E2E8F0"` 配 `slideBg: "0F172A"` — 对比度 12.6:1 ✓
+
+图表标签和漏斗阶段文字会根据每个色块的填充色自动切换深色或浅色。
+
 ## 图表数据处理
 
 当 slide 使用 `chart` 布局时，系统会自动验证图表数据：

generate-ppt.js

@@ -73,6 +73,33 @@ function mergeTheme(partial) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Color contrast helpers (WCAG 2.1 relative luminance)
+// ---------------------------------------------------------------------------
+
+/**
+ * Relative luminance per WCAG 2.1.
+ * @param {string} hex  6-char hex color (no #)
+ */
+function luminance(hex) {
+  const r = parseInt(hex.slice(0, 2), 16) / 255;
+  const g = parseInt(hex.slice(2, 4), 16) / 255;
+  const b = parseInt(hex.slice(4, 6), 16) / 255;
+  const [sr, sg, sb] = [r, g, b].map(c =>
+    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+  );
+  return 0.2126 * sr + 0.7152 * sg + 0.0722 * sb;
+}
+
+/**
+ * Pick a readable text color for the given background.
+ * Returns theme text color (dark) for light backgrounds,
+ * theme textLight (white/light) for dark backgrounds.
+ */
+function pickTextColor(bgHex) {
+  return luminance(bgHex) > 0.4 ? _t.colors.text : _t.colors.textLight;
+}
+
 // Active theme — set at the start of buildDeck(), used by all render helpers
 let _t = DEFAULT_THEME;
 
@@ -181,7 +208,7 @@ function addSlideHeader(slide, deck, current) {
     h: 0.5,
     fontSize: 24,
     bold: true,
-    color: _t.colors.closingBg
+    color: _t.colors.text
   });
 
   if (current.objective) {
@@ -308,7 +335,7 @@ function renderTitleSlide(slide, deck, current) {
     h: 1.1,
     fontSize: 28,
     bold: true,
-    color: _t.colors.closingBg
+    color: pickTextColor(_t.colors.titleBg)
   });
 
   addTextBox(slide, current.subtitle || deck.scenario || deck.audience || '', {
@@ -519,7 +546,7 @@ function renderTimelineSlide(slide, deck, current) {
       fontSize: 10,
       align: 'center',
       bold: true,
-      color: _t.colors.closingBg
+      color: _t.colors.text
     });
 
     addTextBox(slide, item, {
@@ -547,7 +574,7 @@ function renderProcessSlide(slide, deck, current) {
       w: width,
       h: 1.6,
       rectRadius: 0.05,
-      fill: { color: index % 2 === 0 ? 'ECFDF5' : 'EFF6FF' },
+      fill: { color: index % 2 === 0 ? _t.colors.background : _t.colors.headerBg },
       line: { color: _t.colors.border, pt: 1 }
     });
 
@@ -873,11 +900,12 @@ function renderKpiSlide(slide, deck, current) {
 function renderSwotSlide(slide, deck, current) {
   addSlideHeader(slide, deck, current);
   const q = current.quadrants || {};
+  const cc = _t.chartColors;
   const sections = [
-    { label: 'Strengths', items: q.strengths || [], color: '059669' },
-    { label: 'Weaknesses', items: q.weaknesses || [], color: 'DC2626' },
-    { label: 'Opportunities', items: q.opportunities || [], color: '2563EB' },
-    { label: 'Threats', items: q.threats || [], color: 'D97706' },
+    { label: 'Strengths', items: q.strengths || [], color: cc[0] || '059669' },
+    { label: 'Weaknesses', items: q.weaknesses || [], color: cc[3] || 'DC2626' },
+    { label: 'Opportunities', items: q.opportunities || [], color: cc[1] || '2563EB' },
+    { label: 'Threats', items: q.threats || [], color: cc[2] || 'D97706' },
   ];
 
   const gridX = 0.9, gridY = 1.8;
@@ -975,7 +1003,7 @@ function renderFunnelSlide(slide, deck, current) {
     const label = stage.value ? `${stage.label}  —  ${stage.value}` : stage.label;
     addTextBox(slide, label, {
       x, y, w, h: stageH,
-      fontSize: 13, bold: true, color: 'FFFFFF', align: 'center', valign: 'mid'
+      fontSize: 13, bold: true, color: pickTextColor(color), align: 'center', valign: 'mid'
     });
   });
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-ppt-engine",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Python-first AI-agent-ready PowerPoint workflow for planning, revising, validating, and rendering PPTX decks.",
   "license": "Apache-2.0",
   "main": "generate-ppt.js",