presentation-by-html

Use when the user needs to create a technical sharing, presentation, or talk material. Triggered by requests like "prepare a sharing", "make slides", "build a presentation", or any scenario requiring structured visual storytelling for an audience.

Presentation Builder

Overview

Build presentation materials as HTML through a two-phase process: brainstorm first, build second. Never produce slides before the narrative structure is solid.

Phase 1: Brainstorm

Conduct a structured dialogue before writing any code.

Required Questions

Audience & Format:

• Who is the audience? Technical depth? Prior knowledge?
• Duration? Format constraints?

Content Core:

• What problem does this solve? What was the status quo before?
• What is the core capability / contribution?
• Current status (shipped / MVP / in-progress)?
• Demos, data, or real cases available?

Narrative Intent:

• What should the audience take away?
• Pitfalls, "aha moments", counter-intuitive insights?

Structuring Principles

• Effect before mechanism: Show what it does before explaining how
• Pitfalls are gold: Real failures resonate more than polished success. Structure each as: phenomenon -> cause -> solution -> generalizable insight
• Avoid cliché openings: Prefer tension, paradox, or direct demo over "imagine it's 3am..."
• Time-box sections: Allocate minutes explicitly. Core insights deserve >40% of time
• One takeaway per slide: Two ideas = two slides

Iterate Until Stable

Continue dialogue until:

• Framework covers all sections with time estimates
• Narrative arc is clear (hook -> problem -> solution -> lessons -> future)
• User confirms "framework OK"

Phase 2: Build HTML

File Structure

Separate concerns into three files for maintainability:

project/
  presentation.html    # Semantic structure only, no inline styles except layout-specific
  css/style.css        # All visual styling, animations, component patterns
  js/deck.js           # Navigation, interactions, TOC, expandable logic
  images/              # Screenshots, avatars, demo videos

Interaction Patterns (Critical)

The presentation is NOT a static slide deck. It uses interactive detail-on-demand patterns:

1. Tab Cards — Clickable cards that switch a shared detail area below

<div class="grid-3">
  <div class="card tab-card active" data-tab="topic-a">Summary A</div>
  <div class="card tab-card" data-tab="topic-b">Summary B</div>
</div>
<div class="tab-detail-area">
  <div class="tab-detail active" data-tab="topic-a">...full detail...</div>
  <div class="tab-detail" data-tab="topic-b">...full detail...</div>
</div>

Use when: Multiple sub-topics exist under one slide, each with rich detail.

2. Expandable Details — Cards that expand to reveal deeper content

<div class="card expandable" data-expand-target="detail-id">Summary</div>
<div class="expand-content-full" id="detail-id">
  <div class="expand-inner">...detailed content...</div>
</div>

Use when: A slide has layered information — show summary by default, expand for evidence/examples. Supports data-default-open attribute.

3. Left-Tab + Right-Detail Panel — Vertical tab list with adjacent detail pane

Use when: Each tab has substantial content (code blocks, diagrams) that benefits from full-width display. Example: security isolation details.

Visual Design System

Component	CSS Class	Usage
Cards	.card .card-accent .card-{color}	Discrete points, categorized items
Tags	.tag .tag-{color}	Labels, keywords, status badges
Grids	.grid-2 .grid-3	Parallel comparisons
Quote	.quote	Key insights, memorable one-liners
Architecture boxes	.arch-box .arch-box.primary	System diagrams
Code blocks	<pre> with .comment .keyword .string .func .op spans	Syntax-highlighted dark code
Comparison	.compare-box .compare-before .compare-after	Before/after with positioned labels
Timeline	.timeline .timeline-item	Sequential events with time markers
Pitfall insight	.pitfall-step .pitfall-insight	Highlighted takeaway badges
Big numbers	.big-number	Metrics with placeholder __ for pending data

Color System (Semantic)

--primary: #1a73e8;       /* neutral/default/architecture */
--accent: #ea4335;        /* problem/danger/before */
--accent-green: #34a853;  /* solution/success/after */
--accent-yellow: #fbbc04; /* caution/intermediate */
--accent-purple: #9334e6; /* advanced/depth/evaluator */

Animation Patterns

• Fade-in with stagger: .fade-in .fade-in-d1 through .fade-in-d6 for progressive reveal
• Step-by-step flow: .anim-step + .anim-flow container, revealed sequentially by JS
• Flow diagram: .flow-node + .flow-connector revealed node-by-node with delays
• Tab transitions: CSS @keyframes tabFadeIn for smooth panel switching

Slide Types

1. Title slide (.slide-title): Gradient background, white text
2. Section divider (.slide-section): Large faded number + heading
3. Content slide: h2/h3 + interactive components
4. Architecture slide: CSS flex/grid layouts with .arch-box nodes
5. Comparison slide: .compare-before / .compare-after side-by-side
6. Data slide: .big-number with __ placeholders for pending metrics
7. Q&A slide: Minimal title-slide style

JS Engine Responsibilities

deck.js handles:
- Slide navigation (keyboard ←→/Space/PgUp/PgDn, touch swipe, ESC for TOC)
- Progress bar + counter update
- Tab card switching (click → toggle active class on cards and detail panels)
- Expandable toggle (click → open/close with accordion behavior)
- Security panel switching
- Animated flow triggering (reset + staggered reveal on slide enter)
- Default-open restoration on slide enter
- Expand state cleanup on slide leave

Content Density Rules

• Body text: 16-22px; never smaller than 13px even in expand-inner
• Cards: max 3-4 per slide in top-level grid
• Detail areas can be denser (tables, code, smaller font) since they're opt-in
• One core idea per slide at the summary level; detail areas can go deeper
• Use data-title on section/key slides for TOC generation
• Lazy-load heavy media (video onclick pattern)

Things to Avoid

• External CDN links (must work offline/intranet)
• Single-file HTML over 500 lines (split CSS/JS)
• Static walls of text (use expandable/tab patterns for density)
• Inline styles for reusable patterns (extract to CSS classes)
• Images for diagrams (use CSS flex/grid compositions)