# Agent Web PPT — Reveal.js Production Guide

> **Purpose:** Complete instructions for building web-based slides for agent product demonstrations, feature reviews, and project presentations using reveal.js. This is the single source of truth — pass this file + your content to Claude to produce a web PPT.
> **Author:** Fei Zuo | **Team:** CMD SOX — Meeting Intelligence

---

## 1. What This Produces

A **single self-contained HTML file** that:
- Renders as a polished slide-by-slide web presentation with animations
- Works offline (CSS/JS loaded from local reveal.js)
- Supports **light/dark mode toggle** with a floating button
- Follows a polished visual identity with Teams-aligned color palette
- Every slide is **dense, visual, and data-forward** — no filler
- Opens in any browser, no install needed

---

## 2. Hard Rules (Read First)

### NEVER Do
- **NEVER create an agenda/table-of-contents slide.** LT hates them. Jump straight from cover to content.
- **NEVER produce a slide with just a short paragraph.** Every slide must be visually rich — if the content is thin, merge it with the next slide or add metric cards / diagrams / callouts.
- **NEVER dump the input as-is into slides.** Always reorganize, redesign, and regenerate.
- **NEVER use plain text bullets as the primary content.** Wrap in cards, tables, flow diagrams, or metric grids.
- **NEVER leave a slide half-empty.** Fill the viewport — use 2-column layouts, metric rows, or visual elements.
- **NEVER put fragments on table rows, bullet lists, metric cards, or flow diagram steps.** These are reference content — show them fully on load. Fragments are only for strategic narrative reveals where each click advances the story. Nobody wants to click 8 times to read a table.

### ALWAYS Do
- **ALWAYS reorganize and redesign** the input content for slide-optimized storytelling. Reorder sections for narrative flow (problem → solution → impact → next steps). Group scattered data points into summary slides.
- **ALWAYS regenerate diagrams** — convert text descriptions, ASCII art, or markdown tables into visual CSS flow diagrams, swimlanes, or architecture boxes. Never paste raw text diagrams.
- **ALWAYS polish all text** — fix grammar, tighten wording, make every sentence LT-ready. This is not a draft viewer; it is the final presentation.
- **ALWAYS use reveal.js features** — fragments, auto-animate, transitions, gradient backgrounds. Make it feel like a real presentation, not a scrolling HTML page.
- **ALWAYS fill every slide visually.** Combine related small items. Use 2-column grid layouts for comparison. Add metric cards as visual anchors.

---

## 3. Reveal.js Setup

### Project Location
```
planning/reveal.js/          <- reveal.js source
planning/ppt/                <- output HTML files go here
planning/ppt/CMD_ppt_sample/ <- reference samples
```

### Required Files (relative path — adjust depth as needed)
```html
<link rel="stylesheet" href="../reveal.js/dist/reset.css">
<link rel="stylesheet" href="../reveal.js/dist/reveal.css">
<link rel="stylesheet" id="reveal-theme" href="../reveal.js/dist/theme/white.css">
<script src="../reveal.js/dist/reveal.js"></script>
<script src="../reveal.js/dist/plugin/highlight.js"></script>
<script src="../reveal.js/dist/plugin/notes.js"></script>
```

### Initialization Config
```javascript
Reveal.initialize({
  hash: true,
  slideNumber: 'c/t',
  showSlideNumber: 'all',
  transition: 'slide',
  backgroundTransition: 'fade',
  transitionSpeed: 'default',
  autoAnimateDuration: 0.8,
  width: 1280,
  height: 720,
  margin: 0.06,
  center: true,
  mouseWheel: true,
  plugins: [RevealHighlight, RevealNotes]
});
```

---

## 4. Color System

### Cover Slide Palette
Cover slides use a **light background with bold accent graphics** — not a dark hero. The key cover colors are:

| Role | Color | Hex | Usage |
|---|---|---|---|
| **Cover Accent 1** | Teams Cyan | `#5ACBF0` | Geometric shapes, decorative strips on cover |
| **Cover Accent 2** | Warm Gold | `#FBAE40` | Highlight accent on cover graphics |
| **Cover Text** | Dark Navy | `#0E2841` | Title text on light cover background |
| **Cover Subtitle** | Teams Purple | `#464FC6` | Subtitle, team name, date |

**Cover slide design:** White/light background with geometric accent shapes (cyan + gold), large bold title in dark navy, subtitle in purple. NOT a dark gradient — that is for section dividers only.

### Content Palette
```css
:root {
  /* Brand */
  --cmd-cyan: #5ACBF0;       /* Cover accent, decorative elements */
  --cmd-gold: #FBAE40;        /* Cover accent, warm highlights */
  --cmd-navy: #0E2841;        /* Cover title text, dark backgrounds */
  --cmd-purple: #464FC6;       /* Cover subtitle, section accents */

  /* Teams Functional */
  --blue: #0078D4;             /* Links, interactive elements, CTAs */
  --purple: #5B5FC7;           /* Section headers, accent borders */
  --dark: #091F2C;             /* Dark section backgrounds */
  --gold: #FFB900;             /* Key metrics, emphasis on dark bg */
  --green: #107C10;            /* Success, shipped, positive */
  --red: #D83B01;              /* Risk, P0, negative trends */
  --teal: #2E8B8B;             /* Infrastructure, storage */
  --magenta: #C03BC4;          /* Skills, tools layer */
  --salmon: #FFA38B;           /* Client layer, experiences */

  /* Neutral */
  --white: #FFFFFF;
  --light-gray: #F5F5F5;
  --border: #E0E0E0;
  --text: #242424;
  --text-muted: #666666;
}
```

### Dark Mode Overrides
```css
[data-theme="dark"] {
  --white: #1a1a2e;
  --light-gray: #16213e;
  --border: #2a3a4a;
  --text: #e0e0e0;
  --text-muted: #999999;
  --cmd-navy: #e0e0e0;
}
```

### Typography
- **Font:** `'Segoe UI', system-ui, -apple-system, sans-serif`
- **Cover Title:** 2.4rem, 800 weight, `var(--cmd-navy)`
- **Section Header (h2):** 1.5rem, 700, `var(--purple)`, bottom border `3px solid var(--purple)`
- **Subsection (h3):** 1.1rem, 600, `var(--blue)`
- **Body:** 0.85–0.9rem, `var(--text)`
- **Code:** `'Cascadia Code', Consolas, monospace`, 0.82rem

---

## 5. Slide Types & Layouts

### Cover Slide (MANDATORY first slide)
Light background with cyan/gold geometric accents. Dark navy title.
```html
<section data-background="#FFFFFF">
  <!-- Decorative accent bar -->
  <div style="position:absolute;top:0;left:0;width:100%;height:6px;
              background:linear-gradient(90deg, #5ACBF0 0%, #FBAE40 50%, #464FC6 100%);"></div>
  <!-- Decorative geometric shape -->
  <div style="position:absolute;top:40px;right:40px;width:120px;height:120px;
              background:linear-gradient(135deg, #5ACBF0, #FBAE40);border-radius:24px;
              opacity:0.15;transform:rotate(15deg);"></div>
  <div style="position:absolute;bottom:60px;left:40px;width:80px;height:80px;
              background:linear-gradient(135deg, #464FC6, #5ACBF0);border-radius:50%;
              opacity:0.12;"></div>
  <h1 style="color:#0E2841; font-size:2.4rem; font-weight:800;">{{TITLE}}</h1>
  <p style="color:#464FC6; font-size:1.1rem; font-weight:600;">{{SUBTITLE}}</p>
  <p style="color:#888; font-size:0.85rem; margin-top:24px;">{{TEAM}} | {{DATE}}</p>
</section>
```

### Section Divider Slide (between major sections)
Dark gradient background with gold text. Use sparingly — only for major topic shifts.
```html
<section data-background="linear-gradient(135deg, #0E2841, #091F2C)"
         data-transition="zoom">
  <h2 style="color:#FFB900; border:none; font-size:2rem;">Section Title</h2>
  <p style="color:#aaa; font-size:0.95rem;">One-line context</p>
</section>
```

### Content Slide
```html
<section>
  <h2>Section Header</h2>
  <div class="r-hstack" style="gap:16px; align-items:flex-start;">
    <div class="card" style="flex:1;">Left content</div>
    <div class="card" style="flex:1;">Right content</div>
  </div>
</section>
```

### Metrics Slide
```html
<section>
  <h2>Key Results</h2>
  <div class="metric-row">
    <div class="metric-card mc-blue"><div class="val">8.7M</div><div class="lbl">MAU</div></div>
    <div class="metric-card mc-green"><div class="val">91%</div><div class="lbl">CSAT</div></div>
    <div class="metric-card mc-gold"><div class="val">+15pts</div><div class="lbl">Accuracy</div></div>
  </div>
  <div class="card">
    <table>...</table>
  </div>
</section>
```

### Architecture / Diagram Slide
Full-bleed dark container. Use for any system diagram, pipeline, or data flow.
```html
<section>
  <h2>Architecture</h2>
  <div class="arch-container">
    <div class="flow-row">
      <div class="flow-box salmon">Client</div>
      <div class="flow-arrow">→</div>
      <div class="flow-box magenta">Bot</div>
      <div class="flow-arrow">→</div>
      <div class="flow-box purple">Orchestration</div>
      <div class="flow-arrow">→</div>
      <div class="flow-box gold">Intelligence</div>
      <div class="flow-arrow">→</div>
      <div class="flow-box teal">Storage</div>
    </div>
  </div>
</section>
```

### Closing Slide
Matches cover style — light bg, accent bar, contact info.
```html
<section data-background="#FFFFFF">
  <div style="position:absolute;bottom:0;left:0;width:100%;height:6px;
              background:linear-gradient(90deg, #5ACBF0, #FBAE40, #464FC6);"></div>
  <h2 style="color:#0E2841; border:none; font-size:2rem;">Thank You</h2>
  <p style="color:#464FC6;">Questions & Feedback</p>
  <p style="color:#888; font-size:0.85rem;">PM: Fei Zuo | CMD SOX — Meeting Intelligence</p>
</section>
```

---

## 6. Reveal.js Features to Use

### Fragments (progressive reveal within a slide)

**USE SPARINGLY.** Fragments require extra clicks. In a real presentation, LT reviewers should see all content immediately on most slides. Every click must earn its place.

**WHEN to use fragments:**
- Strategic narrative builds (e.g., "problem → insight → conclusion" on a single slide)
- Revealing a key metric or decision after context is shown
- Before/after comparisons where the "after" is the punchline
- Architecture diagrams that build layer by layer (max 3–4 steps)

**NEVER use fragments on:**
- Table rows — tables must be fully visible on load. Clicking through 6+ rows is painful.
- Regular bullet lists — show all bullets immediately
- Metric card rows — all cards visible at once
- Flow diagram boxes — show the full flow, don't make people click through each step
- Any content that is reference data, not a narrative reveal

```html
<!-- GOOD: strategic reveal -->
<p>Entity errors cascade through every downstream system.</p>
<p class="fragment fade-up" style="font-size:1.8rem; color:#FFB900; font-weight:700;">28.2% error reduction with SLPv2</p>

<!-- BAD: clicking through table rows -->
<tr class="fragment">...</tr>  <!-- NEVER DO THIS -->
```
Fragment styles: `fade-up`, `fade-in`, `fade-out`, `grow`, `shrink`, `highlight-red`, `highlight-blue`, `highlight-green`, `fade-in-then-semi-out`.

### Auto-Animate (smooth transitions between slides)
Use for progressive build of diagrams, before/after comparisons, or evolving architecture.
```html
<section data-auto-animate>
  <div data-id="box1" style="background:#5ACBF0; width:100px; height:100px;"></div>
</section>
<section data-auto-animate>
  <div data-id="box1" style="background:#FBAE40; width:300px; height:200px;"></div>
</section>
```

### Gradient Backgrounds (per-slide)
```html
<section data-background-gradient="linear-gradient(135deg, #0E2841, #464FC6)">
```

### Fit Text (auto-size to viewport)
For impactful single-stat slides:
```html
<h2 class="r-fit-text" style="color:#FFB900;">28.2%</h2>
<p>Entity Error Reduction</p>
```

### Stack Layout (overlapping elements)
```html
<div class="r-stack">
  <div class="fragment" style="background:#5ACBF0; width:400px; height:300px;"></div>
  <div class="fragment" style="background:#FBAE40; width:300px; height:200px;"></div>
</div>
```

### Horizontal/Vertical Layout Helpers
```html
<div class="r-hstack" style="gap:16px;"><!-- side by side --></div>
<div class="r-vstack" style="gap:12px;"><!-- stacked --></div>
```

### Speaker Notes (not visible in presentation)
```html
<section>
  <h2>Slide content</h2>
  <aside class="notes">Speaker notes here — press S to view</aside>
</section>
```

### Vertical Sub-Slides (drill-down detail)
Use when a section has too much content for one slide. Parent = summary, children = detail.
```html
<section>
  <section>Summary slide (user sees first)</section>
  <section>Detail slide (scroll/arrow down)</section>
  <section>More detail</section>
</section>
```

---

## 7. Content Redesign Rules

When given ANY input format (md, html, docx, raw text, meeting notes), you MUST:

### Reorganize for Narrative Flow
1. **Cover** — title, subtitle, team, date
2. **The Problem / Context** — why this matters, what's broken, customer pain (1–2 slides)
3. **The Solution / What We Built** — feature explanation, architecture, how it works (2–4 slides)
4. **Results / Impact** — metrics, before/after, downstream effects (1–3 slides)
5. **Risks / Open Issues** — P0/P1 items, blockers (1 slide, use red highlight boxes)
6. **Roadmap / Next Steps** — timeline, milestones (1 slide)
7. **Closing** — thank you, contacts

### Redesign Every Element
| Input Format | Redesign To |
|---|---|
| Paragraph describing a metric | Metric card (big number + label) |
| Paragraph describing a flow | CSS flow diagram (colored boxes + arrows) |
| Paragraph describing architecture | Dark arch-container with swimlane pills |
| Bullet list of features | Grid of cards or 2-column layout |
| Bullet list of risks | Red highlight boxes with bold headers |
| Raw table with many columns | Styled table with dark header + alternating rows, or split into metric cards + smaller table |
| Text-only "before/after" | Side-by-side compare layout with red (before) and green (after) |
| A single sentence or short paragraph | MERGE with adjacent content. Never leave it alone on a slide. |
| ASCII diagram | Regenerate as CSS flex flow diagram |
| Markdown code block | Syntax-highlighted code with `data-line-numbers` |

### Slide Density Rules
- **Minimum per slide:** 1 card/table/diagram + 1 supporting element (metric row, callout, or sub-text)
- **Maximum per slide:** 3–4 content blocks. If more, use vertical sub-slides.
- **Tables with 7+ rows:** Own slide. Use fragments to reveal rows progressively if appropriate.
- **Architecture diagrams:** Full-bleed dark slide, no competing elements.
- **Metric cards:** Always in a row of 3–5. Never a single card alone.

### Text Polish Rules
- Fix all grammar, spelling, punctuation
- Replace informal language with professional wording
- Shorten sentences — max 2 lines per bullet
- Bold key terms, product names, metric values
- Use em-dashes for inline asides
- Spell out acronyms on first use, then abbreviate

---

## 8. Light/Dark Mode Toggle

Include in EVERY output:

```html
<div id="theme-toggle" onclick="toggleTheme()"
     style="position:fixed;top:16px;right:16px;z-index:9999;cursor:pointer;
            background:#0E2841;color:#FBAE40;border-radius:50%;width:42px;height:42px;
            display:flex;align-items:center;justify-content:center;font-size:1.3rem;
            box-shadow:0 2px 12px rgba(0,0,0,0.3);transition:all 0.3s;
            border:2px solid rgba(90,203,240,0.3);">
  ☀️
</div>

<script>
function toggleTheme() {
  const html = document.documentElement;
  const btn = document.getElementById('theme-toggle');
  const theme = document.getElementById('reveal-theme');
  if (html.getAttribute('data-theme') === 'dark') {
    html.removeAttribute('data-theme');
    btn.textContent = '☀️';
    btn.style.background = '#0E2841';
    btn.style.color = '#FBAE40';
    if (theme) theme.href = theme.href.replace('black.css', 'white.css');
  } else {
    html.setAttribute('data-theme', 'dark');
    btn.textContent = '🌙';
    btn.style.background = '#FBAE40';
    btn.style.color = '#0E2841';
    if (theme) theme.href = theme.href.replace('white.css', 'black.css');
  }
}
</script>
```

---

## 9. Component CSS Reference

Include all of these in the `<style>` block:

```css
/* Cards */
.card { background: var(--white); border-radius: 12px; padding: 20px; margin: 12px 0;
        box-shadow: 0 2px 8px rgba(0,0,0,0.06); border: 1px solid var(--border); text-align: left; }

/* Tables */
.reveal table { width: 100%; border-collapse: collapse; font-size: 0.78rem; }
.reveal th { background: var(--cmd-navy); color: white; padding: 8px 10px; text-align: left; font-weight: 600; }
.reveal td { padding: 8px 10px; border-bottom: 1px solid var(--border); }
.reveal tr:nth-child(even) td { background: rgba(0,0,0,0.03); }

/* Metric Cards */
.metric-row { display: flex; gap: 12px; justify-content: center; margin: 16px 0; flex-wrap: wrap; }
.metric-card { padding: 14px 20px; border-radius: 10px; text-align: center; color: white; min-width: 120px; }
.metric-card .val { font-size: 1.6rem; font-weight: 700; }
.metric-card .lbl { font-size: 0.7rem; opacity: 0.9; }
.mc-blue { background: linear-gradient(135deg, #0078D4, #005a9e); }
.mc-purple { background: linear-gradient(135deg, #464FC6, #3535a0); }
.mc-green { background: linear-gradient(135deg, #107C10, #0a5a0a); }
.mc-gold { background: linear-gradient(135deg, #FBAE40, #D83B01); color: #0E2841 !important; }
.mc-dark { background: linear-gradient(135deg, #0E2841, #091F2C); }
.mc-teal { background: linear-gradient(135deg, #2E8B8B, #1a6b6b); }
.mc-cyan { background: linear-gradient(135deg, #5ACBF0, #0078D4); }

/* Highlight Boxes */
.highlight-box { padding: 14px 18px; border-radius: 0 8px 8px 0; margin: 12px 0; font-size: 0.85rem; text-align: left; }
.highlight-box.blue { background: #E8F4FD; border-left: 4px solid var(--blue); }
.highlight-box.gold { background: #FFF8E1; border-left: 4px solid var(--cmd-gold); }
.highlight-box.green { background: #E8FFE8; border-left: 4px solid var(--green); }
.highlight-box.red { background: #FFE8E8; border-left: 4px solid var(--red); }
.highlight-box.purple { background: #F0E8FF; border-left: 4px solid var(--purple); }

/* Vision Banner */
.vision-banner { background: linear-gradient(135deg, #0E2841, #091F2C); color: white;
                 padding: 24px 28px; border-radius: 12px; margin: 16px 0; }
.vision-banner strong { color: var(--cmd-gold); }

/* Flow Diagrams */
.flow-row { display: flex; justify-content: center; align-items: center; gap: 8px; margin: 6px 0; flex-wrap: wrap; }
.flow-box { padding: 8px 14px; border-radius: 8px; font-size: 0.75rem; font-weight: 600; text-align: center; min-width: 80px; }
.flow-box.purple { background: var(--purple); color: white; }
.flow-box.blue { background: var(--blue); color: white; }
.flow-box.green { background: var(--green); color: white; }
.flow-box.gold { background: var(--cmd-gold); color: var(--cmd-navy); }
.flow-box.dark { background: var(--cmd-navy); color: #ccc; }
.flow-box.teal { background: var(--teal); color: white; }
.flow-box.salmon { background: var(--salmon); color: var(--cmd-navy); }
.flow-box.magenta { background: var(--magenta); color: white; }
.flow-box.cyan { background: var(--cmd-cyan); color: var(--cmd-navy); }
.flow-box .sub { font-size: 0.62rem; opacity: 0.85; }
.flow-arrow { color: #999; font-size: 1rem; }

/* Architecture Container */
.arch-container { background: var(--cmd-navy); border-radius: 16px; padding: 24px; margin: 12px 0; }
.arch-container .flow-arrow { color: #556; }

/* Badges */
.badge { display: inline-block; padding: 3px 10px; border-radius: 12px; font-size: 0.72rem; font-weight: 600; }
.badge-ring { background: #FFF4CE; color: #835C00; }
.badge-green { background: #DFF6DD; color: #0E700E; }
.badge-red { background: #FFE8E8; color: #D83B01; }
.badge-blue { background: #E8F4FD; color: #0078D4; }
.badge-purple { background: #F0E8FF; color: #464FC6; }

/* Footer */
.footer { position: fixed; bottom: 8px; left: 16px; font-size: 0.65rem; color: var(--text-muted); z-index: 100; }
```

---

## 10. Output Checklist

Before delivering, verify:

- [ ] Cover slide uses light bg + cyan/gold accents (NOT dark gradient)
- [ ] No agenda/TOC slide exists
- [ ] No slide has only a short paragraph — every slide is visually dense
- [ ] All diagrams regenerated as CSS (no ASCII art, no pasted text)
- [ ] All text polished (grammar, spelling, professional tone)
- [ ] Light/dark toggle works
- [ ] Slide navigation works (arrows, scroll, space)
- [ ] Slide numbers visible (current/total)
- [ ] Fragments used only for strategic narrative reveals (NOT on tables, lists, metrics, flow steps)
- [ ] Auto-animate used on 1–2 progressive-build slides
- [ ] Tables have styled headers (dark bg, white text)
- [ ] Metric cards in rows of 3–5
- [ ] Footer shows team + date
- [ ] No content overflow or clipping
- [ ] Relative paths to reveal.js are correct
- [ ] Closing slide matches cover style

---

*This is the single source of truth for agent web presentations. Every output must follow these rules. Pass this file + content to get consistent, presentation-ready results every time.*