Initial commit

skills/ppt/design-system.md

@@ -0,0 +1,211 @@
+# Design System — PPT Creative Guidelines
+
+This file provides **creative principles and a color system** for PPT design. Components and layouts should be inventive and diverse — these guidelines exist to ensure visual coherence, not to constrain creativity.
+
+**Philosophy: Every slide is a design opportunity.** No two slides should look the same. Vary layouts, card treatments, backgrounds, typography weight, and whitespace aggressively. The audience should feel visual momentum, not repetition.
+
+---
+
+## 1. Color Scale System (Mandatory)
+
+The color system is the **only hard constraint**. All colors used in the deck must derive from the chosen theme.
+
+### 1.1 Color Scale Generation
+
+Eight levels are derived from a single Primary color:
+
+| Level | Lightness | Usage Examples |
+|-------|-----------|---------------|
+| `primary-100` | Darkest (L≈8%) | Dark backgrounds, dramatic pages |
+| `primary-90` | Dark (L≈15%) | Title bars, dark blocks, overlays |
+| `primary-80` | **Main color** | Headings, primary UI elements |
+| `primary-60` | Medium dark (L≈45%) | Subheadings, icons, secondary elements |
+| `primary-40` | Medium light (L≈60%) | Muted text, dividers, subtle accents |
+| `primary-20` | Light (L≈80%) | Borders, light decorations, tints |
+| `primary-10` | Very light (L≈90%) | Card fills, surface backgrounds |
+| `primary-5` | Near white (L≈96%) | Page tints, hover states, subtle surfaces |
+
+**Generation method**: From the Primary HSL (H, S, L) — keep H constant; dark levels S×1.1, light levels S×0.3; assign L per the table.
+
+### 1.2 Semantic Colors
+
+| Token | Value | Purpose |
+|-------|-------|---------|
+| `background` | `#FFFFFF` | Default page base |
+| `surface` | `primary-5` | Tinted content area base |
+| `surface-card` | `#FFFFFF` | Card base (floats above surface) |
+| `text-primary` | `primary-80` | Primary text |
+| `text-secondary` | `primary-60` | Secondary text |
+| `text-muted` | `primary-40` | Annotations, footnotes |
+| `on-dark` | `#FFFFFF` | Text on dark backgrounds |
+| `on-dark-secondary` | `rgba(255,255,255,0.7)` | Secondary text on dark backgrounds |
+| `border` | `primary-10` | Dividers, borders |
+| `accent` | Defined by theme | Highlight color |
+| `on-accent` | `#FFFFFF` | Text on accent color |
+
+### 1.3 Color Rules
+
+- **All grays must derive from the primary color scale** — no arbitrary `#666`, `#999`, `#DDD`
+- **Text on dark areas must use `on-dark`** (#FFFFFF) — never use light primary tints on dark backgrounds
+- **Accent color area**: ≤15% on standard pages; up to 40% on emphasis/transition pages
+- **Saturation limit**: Accent colors should have HSL saturation ≤ 65% for most themes. High-energy themes (Deep Mineral, Ember, Mono) may use S ≤ 75% to preserve their intended vibrancy. Colors above S=80% look garish on projected slides. The theme presets already comply; if creating custom colors, check saturation.
+- **Large color blocks** (>15% of page area): reduce saturation further (S ≤ 50%) to avoid visual fatigue. Use higher saturation only for small accents (bars, icons, small badges).
+
+---
+
+## 2. Creative Principles (Guidelines, Not Rules)
+
+These are high-level design intentions. Interpret them freely.
+
+### 2.1 Visual Diversity
+
+- **No two adjacent slides should share the same layout, background treatment, or card style.** This is the single most important principle.
+- Aim for **5+ distinct layout structures** across a deck (split columns, grids, single-focus, full-bleed, asymmetric, timeline, staggered, etc.)
+- Aim for **3+ card styles** (shadow float, outline, solid fill, gradient, frosted glass, tag-style, image-backed, borderless, etc.)
+- Aim for **3+ background treatments** (pure white, tinted surface, dark full-bleed, photo + mask, gradient, diagonal split, corner decoration, color band, etc.)
+
+### 2.1.1 Deck-Wide Consistency Rules
+
+**What MUST stay uniform across the entire deck** (changing these = unprofessional):
+- Body text font and font size (e.g., always 15pt Microsoft YaHei)
+- Page left/right margins (e.g., always 48pt)
+- Primary color palette (same theme throughout)
+- Accent color (same accent variant throughout, or intentional A/B mixing as documented)
+
+**What SHOULD vary across slides** (sameness = monotony):
+- Layout structure (grid, split, list, focus, timeline, etc.)
+- Background treatment (white, surface, dark, photo, gradient)
+- Card style (shadow, outline, solid, accent-bar, dark card)
+- Title bar style (dark bar, accent bar, underline, inline title, vertical band)
+- Decorative elements (accent bars, shapes, circles, dot patterns)
+
+**The boundary is clear: base typography and spacing = consistent; visual composition = diverse.**
+
+### 2.2 Intentional vs Accidental Whitespace
+
+Not all whitespace is bad. The key is **intent**.
+
+**Intentional whitespace (good — preserve it):**
+- KPI / big-number pages: Large number centered with breathing room → dramatic focus
+- Quote / pullout pages: Single sentence with generous margins → elegant emphasis
+- Photo + caption pages: Image dominates, text is minimal → visual storytelling
+- Title / divider pages: Bold text with open space → transition signal
+
+**Accidental whitespace (bad — fix it):**
+- Bullet list with 3 items occupying only 1/3 of the slide → expand or add visuals
+- Card grid with small cards clustered at the top, bottom 60% empty → enlarge cards, increase padding
+- Text block in the upper-left corner with nothing else on the page → redistribute content
+
+**Rule of thumb**: If the whitespace makes the slide feel "unfinished" or "forgot to add content," it's accidental. If it makes the slide feel "clean" or "focused," it's intentional.
+
+### 2.3 Visual Rhythm
+
+- Alternate between high-density and low-density pages
+- Insert a "rhythm breaker" every 3-4 slides — a page that looks dramatically different (full-bleed dark, photo overlay, large single quote, bold color block)
+- Cover and closing page should echo each other in color or mood
+- **Vary the page header treatment** — don't use the same dark title bar on every slide. Alternatives:
+  - Accent-colored bar (e.g., `background:${accent}`)
+  - Transparent header with large colored text and a bottom divider line
+  - No header bar at all — use oversized inline heading text
+  - Left-side vertical color band instead of top horizontal bar
+  - Gradient header (dark-to-transparent from top)
+
+### 2.4 Typography
+
+- **Hierarchy is king**: Headings should be visually distinct from body text through size, weight, and/or color
+- Body text should be readable at projection distance — don't go below ~13pt
+- Let type breathe — generous line-height makes everything feel more designed
+- KPI / hero numbers should be oversized and bold to create a focal point
+- Prefer cutting content over shrinking fonts — only when a slide is already well-filled and overflow is imminent; never cut content preemptively
+
+### 2.5 Spacing & Layout
+
+- Use consistent margins across the deck (recommended: 48pt left/right, 40pt top, ≥36pt bottom safe zone)
+- Content should be **vertically balanced** — not crammed at the top with empty space below
+- Give elements room — tight packing reads as "cheap"
+- Fixed widths for multi-column cards prevent uneven stretching
+
+### 2.6 Decoration & Visual Interest
+
+- Every content slide should have **at least one non-text visual element** — accent bar, color block, photo, shape, large number, chart
+- Decorative elements (circles, bars, geometric shapes, dot patterns) add polish and visual rhythm
+- Decoration should support the content, never compete with it
+
+### 2.7 Imagery
+
+- Real photographs dramatically elevate quality — use them on covers, dividers, and visual pages
+- Background images need a semi-transparent mask overlay for text readability
+- Image tone (warm/cool) should match the theme atmosphere
+
+---
+
+## 3. Technical Constraints (html2pptx Engine)
+
+These are **rendering engine limitations**, not design choices. Violating them causes broken output.
+
+| Constraint | Reason |
+|-----------|--------|
+| Slide canvas: 720×405pt (16:9) | Fixed PPTX dimensions |
+| `background-image` only works on `<body>`, not on `<div>` | html2pptx engine limitation |
+| Don't use `flex-wrap` for multi-row grids — use separate flex containers per row | html2pptx drops wrapped rows |
+| Don't use negative margins | Causes text stacking in PPT (elements become independent text boxes) |
+| `font-family` must include a CJK font name | Required for correct font mapping |
+| Images must be local file paths, not URLs | html2pptx reads from filesystem |
+| Content that exceeds 405pt height will overflow — split into multiple slides instead | No scroll in PPT |
+| Multi-column equal-width cards: use explicit `width` + `flex-shrink:0`, not `flex:1` | Prevents uneven stretching |
+| Titles and short labels: use `white-space:nowrap` | Prevents unexpected line breaks in conversion |
+
+---
+
+## 4. Quick Reference
+
+### Recommended Font Size Range
+
+| Role | Suggested Size | Weight |
+|------|---------------|--------|
+| Display / decorative number (ghost) | 80–100pt | Bold |
+| Hero focal metric (single-stat page) | 56–88pt | Bold |
+| Hero / cover title | 40–48pt | Bold |
+| KPI dashboard numbers | 36–48pt | Bold |
+| Section title | 28–34pt | Bold |
+| Page title (in title bar) | 26–30pt | Bold |
+| Card / sub heading | 20–24pt | Bold |
+| Body text | 14–16pt | Normal |
+| Annotations / footnotes | 12–13pt | Normal |
+| Captions / tiny labels | 10–12pt | Normal |
+| Tag / chip label | 10–11pt | Normal |
+
+**Ghost number technique**: Large decorative numbers (80–100pt) at very low opacity (`color:rgba(255,255,255,0.05)` on dark backgrounds, or `color:rgba(0,0,0,0.04)` on light) add visual depth without competing with readable content. Use as background layer behind chapter numbers, inside TOC cards, or behind section titles.
+
+### Common Spacing Values
+
+| Usage | Suggested |
+|-------|-----------|
+| Page left/right margins | 48pt |
+| Page top margin | 40pt |
+| Bottom safe zone | ≥36pt |
+| Between heading and body | 8-16pt |
+| Between cards | 12-20pt |
+| Card internal padding | 16-24pt |
+
+### Width Reference (720pt total)
+
+| Layout | Approximate Column Widths |
+|--------|--------------------------|
+| Full width (with margins) | ~624pt |
+| Two columns | ~296pt each (16pt gap) |
+| Three columns | ~192pt each (16pt×2 gaps) |
+| Four columns | ~140pt each (16pt×3 gaps) |
+
+### Height Reference (405pt total)
+
+| Component | Approximate Height |
+|-----------|--------------------|
+| Title bar | ~56pt |
+| Single text line (15pt body) | ~23pt |
+| KPI number line (40pt) | ~40pt |
+| Card padding (top+bottom) | ~32-48pt |
+
+---
+
+**Remember: This system gives you a coherent color palette and a few engine-level constraints. Everything else — layout invention, typography expression, decorative flair, card styling, background artistry — is yours to create freely. Make every slide count.**