mantle-ai-trader/skills/ppt/design-system.md

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.