Deck Design Pdf

Deck Design PDF — Operational Playbook

What This Skill Does

• Input: a deck brief + any structured data the user provides.
• Output: a PDF file — pixel-perfect slides rendered from HTML/CSS via Playwright. Not editable in PowerPoint. This is the high-fidelity, print-ready format.

When to use this vs deck-design-ppt

What the web stack unlocks (beyond pptx)

• CSS Grid and Flexbox — responsive layouts instead of coordinate math
• Google Fonts with optical sizing and variable weights
• Font Awesome 6 icons inline with text
• Gradient backgrounds, box shadows, rounded corners, opacity
• ECharts 5 (SVG renderer) — 21 chart types: bar, line, pie, scatter, waterfall, gauge, sankey, treemap, radar, funnel, heatmap, and more
• Tailwind utility classes — rapid, consistent styling

Phase 1 — Understand and Route

1. Read the room

Before asking the user anything, scan the working directory for artifacts that establish context — briefs, consultant storyboards (*-ghost.md, *-outline.md), data files, brand specs, existing build scripts. Read what's there and form a working hypothesis about what this deck needs: objective, audience, tone, density, and data.

Then ask only for what's genuinely ambiguous and would change the deck's argument or audience calibration. Frame questions as choices, not open fields: "The data suggests a Bain decision-first structure — does that fit, or is this more of an internal working session?" One sharp question beats five vague ones. Maximum 1–3 questions; zero is fine if the artifacts are clear.

2. Classify the deck

This determines how deep the planning phase goes. Two paths:

Consultant handoff — if a storyboard from the consultant skill already exists (governing thought, pillars, action titles, content descriptions), the argument layer is done. Skip ghost deck construction entirely. Validate the argument (run the helicopter test on the titles), then proceed to the production outline.

3. Pick style and density

Style:

The fonts above are vendored locally for the default palettes. The agent is not limited to these — any Google Font can be loaded via a <link> tag in headExtra when the brief calls for a different typeface.

Density:

Show deck vs. working deck — infer from audience and objective, don't ask. "Board presentation" → tier: 'presentation' (body ≥15pt, room-safe). "Diligence data room" → tier: 'document' (body ≥12pt, dense but legible). The tier shifts ALL text tokens automatically.

For L2+ consulting decks, apply firm-specific conventions from firm-dna.md. For density adaptation rules, see density-adaptation.md.

Phase 1.5 — Ghost Deck

Before writing any HTML, build the ghost deck — the narrative skeleton that precedes all visualization. Charts and code are execution. The ghost deck is the thinking.

The ghost deck process produces two artifacts:

• `{slug}-ghost.md` — the argument layer: governing thought, action titles, exhibit types. A senior reviewer can approve this without knowing CSS.
• `{slug}-outline.md` — the execution layer: ghost deck + density tiers, layout geometry, chart dimensions, column alignment. This is what the build phase reads.

Process management. Building a ghost deck requires populating multiple interdependent layers and passing quality gates that may trigger backtracking. Use your task management tools to track which layers are complete, which gates have passed, and what needs revisiting. Externalize this state — don't try to hold it all in one pass.

Universal quality gates

These apply to every deck — consulting, startup, board update, conference talk. They are not consulting methodology; they are good deck design.

Start from the governing thought — one sentence that states the deck's answer. Build pillars that support it. Write action titles for every slide before you touch any charts. Read the titles in sequence — if they don't tell a complete story, the problem is in the pillars, not the titles. Only assign exhibits once the argument holds. Cut any slide that isn't load-bearing.

What must exist in every ghost deck:

Common deck patterns. For non-consulting decks, chart-taxonomy.md § Deck Archetypes provides narrative arcs and exhibit mixes for common formats — investor/roadshow (Problem → Solution → Traction → Market → Model → Team → Ask), board updates (Headlines → KPIs → Progress → Risks → Decisions), due diligence memos, transformation roadmaps, and more. Use these as starting points for the slide sequence, then write action titles and apply the quality gates above. Don't force a pattern that doesn't fit the brief — adapt or combine as the argument requires.

Backtracking, not patching. If the helicopter test fails, the problem is upstream — the pillars don't support the governing thought, or the titles are topic labels instead of conclusions. Go back to where the argument breaks. Don't patch titles to paper over a structural gap.

When the brief supports multiple valid governing thoughts — surface the options and let the user choose before proceeding. Otherwise, commit to the strongest hypothesis and work forward.

Consulting path

For MBB engagements and strategy consulting, the ghost deck goes deeper. Load the full reference library:

On top of the universal quality gates, the consulting path adds:

• Archetype classification — classify the engagement using engagement-archetypes.md, then load the matching skeleton from skeletons/. The skeleton provides a pillar architecture and slide-by-slide index as a starting point — customize it to the specific brief.
• Pillar architecture — 3–5 MECE pillars supporting the governing thought. Work backward: "What must be true for the governing thought to hold?"
• Transition architecture — at each pillar boundary, select a transition type (Pivot, Narrowing, Escalation, Synthesis, Decision Gate). Verify rising-stakes progression: Recognition → Clarity → Conviction → Urgency.
• Firm overlay — apply firm-dna.md conventions for the target firm style. This affects header structure, communication signature, and composition patterns — not the argument itself.
• Evidence recipes — for each exhibit, check evidence-recipes.md for the standard composition: primary chart + supporting elements + annotation layers, governed by density level.

These layers have dependencies — you can't design transitions until pillars exist, and you can't assign evidence recipes until exhibits are selected — but the agent decides the working order based on what the brief gives it. A brief with strong data might start from what the data proves and work backward to the governing thought. A brief with a clear strategic question might start top-down.

Consultant handoff

When a storyboard from the consultant skill already exists (governing thought, pillars, action titles, content descriptions, structured data), the argument layer is done. This skill inherits it and focuses on production:

1. Run the helicopter test on the provided action titles. If titles read as topic labels rather than conclusions, strengthen them. 2. For each slide, use the content description + chart-taxonomy.md decision tree to select exhibit types. The consultant describes WHAT each slide proves; this skill decides HOW to visualize it. 3. This skill may tighten action titles, add transition slides, or adjust slide count for density. The consultant's governing thought and pillar architecture are authoritative; exhibit selection and layout composition belong to this skill.

Presenting the ghost deck

Once the ghost deck is complete, present it to the user as the storyline — just the action titles in sequence. This is the helicopter test output:

Here is the argument this deck makes, read top to bottom:

1. [Action title]

2. [Action title]

...

Does this story hold? Anything missing, out of order, or unconvincing?

Don't print the full outline with density tiers and exhibit types — that's implementation detail. The user's job is to validate the argument, not review the geometry. If they approve, proceed to the production outline. If they redirect, revise and present again.

Production outline

The production outline ({slug}-outline.md) extends the ghost deck by adding geometry to every slide. This is the contract between thinking and building — the build phase copies these numbers, no sizing reasoning required at code time.

For every slide in the ghost deck, add:

• Density tier — which CSS class governs typography
• Layout — composition type + percentage split (e.g., "asymmetric split — left 60% / right 40%")
• Column alignment — items-start when columns differ in content height; items-center only for visually balanced columns
• Chart spec — explicit dimensions derived from the space budget (see § Space audit below)
• Evidence layers — 1 for L1, 1–2 for L2, 2–4 for L3

N. **Action title — full sentence conclusion**
   - Density: sd-medium
   - Layout: asymmetric split — left 60% / right 40%
   - Column alignment: items-start
   - Exhibit: clustered bars (market share by segment)
   - Chart spec: 700px × 480px — body 600px − 120px (top labels + gap) = 480px
   - Data: SWE-bench scores, coding market share
   - Evidence layers: 2

Save as {slug}-outline.md. The ghost deck is not modified — it remains the clean argument document.

Outlines that omit exhibit types produce decks dominated by KPI cards and text bullets — the most common quality failure. The outline must have Layout + Exhibit before the build starts.

Space audit

Before writing any code, run a space audit on every slide that contains a chart or diagram. The slide canvas is 1280×720px. After header (~76px) and footer (~44px), the body zone is ≈ 600px tall, ≈ 1168px wide (56px margins each side). In a two-column layout, each column is ≈ 576px.

For each chart slide: subtract any non-chart content (card rows, KPI strips, table rows, gaps) from the 600px body height. The remainder is the chart height. Write this math in the outline — the build agent copies the number directly.

body height 600px − top content Apx − bottom content Bpx = chart height

Key rules:

• If chart height > chart width for that column, the chart is portrait. That's correct — portrait orientation eliminates blank space structurally.
• If two columns have different content heights, set align-items:start. Don't default to center.
• If the computed chart height exceeds the density class default, override it. The space budget wins.

Estimation reference (1280×720):

Phase 2 — Build

How to build slides

Read {slug}-outline.md. Each slide entry has an action title, exhibit type, layout, and chart dimensions. The build phase executes these specs — it does not re-derive them. Sizing decisions were made in the outline; the build agent copies the numbers.

You are composing custom HTML for each slide based on the user's actual data and the outline's argument. You are NOT filling in a template. The examples under examples/*.js are visual pattern references — study their approach, then write original HTML that serves the specific argument.

Space budget reference. At 1280×720, the available zones are:

For each slide in the outline:

1. Set the tier — 'presentation' for any deck projected in a room or read by executives. 'document' (default) for working sessions and analysis. The tier shifts all text baselines automatically. Do not adjust individual font sizes. Infer from audience and objective — don't ask. 2. The action title tells you what to prove. The exhibit type tells you how to prove it. The chart spec tells you the exact dimensions. 3. Read the relevant example file to learn the visual pattern — the ECharts config structure, the CSS layout approach, the annotation placement. Do not copy its data or dimensions. 4. Compose the slide HTML with the user's real data. Use the slide shell (header → body → footer). Apply palette CSS custom properties — never hardcode brand colors. 5. Size text and spacing through the token system (tokens.adapt(), getFigureTypography(), getChartChrome()), not hardcoded pixels.

What to learn from each example:

What NOT to copy from examples:

• Sample data ("$4.2B", "12.4M units") — use the user's actual numbers
• Action titles and section labels — write new ones from the ghost deck
• Hardcoded hex colors for palette roles — use var(--accent), var(--text), etc.
• Fixed dimensions — adapt to the content density and slide count. Examples follow a roughly landscape aspect ratio; your slide's body space may demand a portrait or square chart. Fill the available body height first, then constrain only if content overflows.

Fill-first orientation. When sizing a chart or visual exhibit, start from the body height (≈ 600px), subtract any labels, gaps, or card rows above/below the chart, and set the chart to that remaining height. Do not start from an example's hardcoded height and stretch slightly. A chart that fills the body zone vertically eliminates blank space structurally — no bottom padding hack required. Portrait charts (height > width) are valid and preferred over leaving empty space at the slide bottom.

Choosing between visual patterns:

When two exhibit types could work, choose based on the argument, not the visual appeal:

• Waterfall answers "what drove the change?" — use when the audience needs to see sequential drivers
• Driver tree answers "what multiplies into what?" — use when the audience needs to see the structural decomposition
• Horizontal bars answer "who is ahead?" — use when ranking is the point
• Distribution answers "how spread out?" — use when the variance is the insight, not the average

If the taxonomy's decision tree doesn't clearly route to one pattern, default to the simplest exhibit that proves the title's claim. A single bold number is often more powerful than a chart. Simplicity is not laziness — it's restraint.

Load build-reference.md for the full slide construction reference — build script template, slide shell, layout primitives, content primitives, typography scale, design tokens, spatial constants, icons, ECharts configuration, composition routing, and layout anti-patterns.

Key build principles

• Use CSS Grid for the slide shell (grid-template-rows: auto minmax(0,1fr) 48px). This structurally prevents footer overflow. Do not use flex flex-col with flex-1.
• Fill-first orientation. Start from body height (≈ 600px), subtract surrounding elements, set the chart to the remainder. Portrait charts (height > width) are valid and preferred over leaving empty space.
• Use palette tokens (var(--accent), var(--text), etc.), not hardcoded hex.
• Use `headExtra` CSS classes for the shell on decks >5 slides. Use Tailwind for body content layout.
• For decks >10 slides, consider modular authoring — one file per slide, assembled by build.js.
• ECharts: SVG renderer only ({ renderer: 'svg' }). Canvas blanks in Playwright PDF. Always set animation: false.

Firm Style

For L2+ consulting decks only. All three firms use the same charts. What differs is communication structure.

For full firm conventions, load firm-dna.md. For chart-level visual treatment, see chart-taxonomy.md § Firm Visual Identity.

Composition Rules

• Start with a cover slide. Use section dividers for chapter breaks in decks >8 slides.
• One slide = one argument. Every action title advances a distinct claim.
• Dead slide test. If you can remove a slide and the argument still works, remove it. Every slide must be load-bearing.
• Do not repeat the same layout back-to-back. Alternate between layout types.
• Helicopter test. Read all action titles in sequence — they must tell a complete, persuasive story without any exhibit bodies.
• Density level governs composition. Do not use L3 multi-evidence composites on an L1 pitch deck.
• Chart variety. Do not use the same chart type on consecutive slides.
• Icon restraint. One icon per card or list item. No icon walls. Use accent color, not rainbow.
• Section rhythm. For decks >8 slides, group into 3–4 sections. Open each with agenda (active item) or divider. Close with synthesis before the next section.
• Content fit. Content must fill the body zone without overflow or sparseness. If a slide looks empty, add evidence layers. If it's crowded, split into two slides.
• Visual balance. Content is vertically centered in the body zone by Flexbox — let flex-1 handle distribution. Do not force absolute positioning.
• Color discipline. Use palette tokens, not hardcoded hex. Semantic colors (emerald/amber/red) only for status indicators, never for decoration.
• Annotation is value, not decoration. See chart-taxonomy.md's Annotation Grammar. The callout that says "This 15% gap = $340M unrealized" is why the engagement costs what it costs.

Output Organization

Save deliverables to the current working directory (or user-specified folder). Kebab-case naming:

• {slug}.pdf — the deliverable
• build-{slug}.js — the build script (reproducible)
• {slug}-ghost.md — the argument layer (governing thought, action titles, exhibits)
• {slug}-outline.md — the execution layer (ghost deck + geometry)

Architecture

Self-contained: package.json + node_modules/ are inside the skill folder. All require() calls resolve locally.

How examples relate to deck building: The agent does NOT import or call example files at runtime. Examples exist as read-only references — the agent reads them to learn visual patterns, then writes original HTML in the build script. The build script uses only engine/index.js (createDeck). The examples use _shared.js to demonstrate best practices for token usage, but the agent composes slide HTML directly.

The engine handles: HTML document assembly, vendored font loading, Font Awesome injection, ECharts (SVG renderer), Tailwind injection, palette CSS injection, Playwright launch, page.pdf() rendering. All assets are local — zero network dependency at build time.

What NOT To Do

Rendering constraints:

• Do not use <canvas> for charts — canvas elements blank in Playwright's PDF pipeline. Use ECharts SVG renderer or CSS-only visuals.
• Do not add animation, transitions, or hover states. The output is static PDF.
• Do not use @media print overrides — the engine uses emulateMedia('screen').
• Use CSS Grid (grid-template-rows: auto minmax(0,1fr) 48px) for the slide shell, not flex flex-col with flex-1. See § Wrapped slide shell and § Slide layout anti-patterns.

Architecture constraints:

• Do not create separate HTML files per slide. All slides go in one build script, one HTML document, one PDF.
• Do not generate interactive presentations (Reveal.js, Slidev). Output is always static PDF.
• Do not hardcode palette colors — use CSS custom properties (var(--accent), var(--text), etc.) so palette switching works.

Design discipline:

• Do not copy example data into real decks. Example numbers ($4.2B, 12.4M units) are illustrative — use the user's actual data.
• Do not choose exhibit types by visual appeal. Choose by what the slide's argument needs to prove. A bold number can be more powerful than a chart.
• Do not over-decorate. No icon walls, no rainbow colors, no gradients on data elements. Consulting aesthetics come from restraint, not embellishment.
• Do not use the same exhibit type on consecutive slides. Alternate to maintain visual rhythm.

Agent behavior:

• Do not ask the user to pick a chart type. The taxonomy's decision tree and the ghost deck's action titles determine the exhibit. You make the visual decision.
• Do not ask the user for show vs. working deck preference. Infer from audience and objective — "board presentation" is show, "diligence data room" is working.
• Do not present multiple layout options for approval. Commit to the best composition based on the content density and argument structure. The user reviews the output PDF, not a menu of choices.

Build Reference — Slide Construction

Load this reference during Phase 2 (Build) when writing slide HTML, configuring ECharts, or structuring the build script. Not needed during planning or ghost deck construction.

Build script

For decks with more than 5 slides, define a CSS class system in headExtra rather than repeating inline Tailwind on every slide.

const { createDeck } = require('./skills/deck-design-pdf/engine');

createDeck({
  palette: 'consulting-mckinsey',
  title: 'Strategy Update Q1 2026',
  output: 'strategy-update.pdf',
  tier: 'document',  // 'document' (default) or 'presentation' for show decks
  width: 1280,       // optional
  height: 720,       // optional
  headExtra: `<style>
    /* Slide shell — CSS Grid prevents footer overflow */
    .deck-shell { height: 100%; display: grid; grid-template-rows: auto minmax(0,1fr) 48px; }
    .deck-header { padding: 28px 56px 8px 56px; border-top: 4px solid var(--accent); }
    .deck-body { min-height: 0; overflow: hidden; padding: 12px 56px 8px 56px; }
    .deck-footer { display: flex; align-items: center; justify-content: space-between;
                   padding: 0 56px; font-size: 12px; color: var(--text-fine);
                   border-top: 1px solid rgba(0,0,0,0.06); font-family: var(--font-body); }
    .deck-section { margin: 0 0 4px; font-size: 12px; letter-spacing: 0.2em;
                    text-transform: uppercase; color: var(--accent); font-weight: 700; }
    .deck-title { margin: 0 0 8px; font-size: 30px; line-height: 1.15; letter-spacing: -0.03em;
                  color: var(--text); font-family: var(--font-heading); font-weight: 700; }
    .deck-rule { height: 3px; border-radius: 2px; background: var(--accent); margin-top: 4px; }
  </style>`,
  slides: [
    // Each string is the inner HTML of one slide.
    // The engine wraps each in <section class="slide">.
    `<div class="deck-shell">
       <div class="deck-header">
         <p class="deck-section">Section Label</p>
         <h2 class="deck-title">Action title — full sentence conclusion</h2>
         <div class="deck-rule"></div>
       </div>
       <div class="deck-body">
         <!-- content -->
       </div>
       <div class="deck-footer">
         <span>Source: Analysis, 2026</span>
         <span>Confidential</span>
       </div>
     </div>`,
  ],
});

Run: node build-{slug}.js → produces the PDF directly.

Why `headExtra` CSS classes over inline Tailwind for the shell:

• One change to .deck-title fixes all 20+ slides — vs editing each slide's text-3xl font-semibold leading-snug tracking-tight
• The grid shell guarantees footer placement structurally
• Token-efficient: a class name is ~15 chars vs ~80 chars of Tailwind utilities per slide
• Tailwind is still used for body content layout (grids, gaps, cards) — only the shell is CSS classes

ECharts formatter warning: Inside JavaScript template literals (backtick strings), '${value}' is interpreted as JS interpolation. Use function(v) { return '$' + v + 'B'; } instead. This applies to all formatter, axisLabel.formatter, and label.formatter properties.

Modular authoring for large decks

For decks with more than ~10 slides, consider authoring each slide as a separate module file. The createDeck() API is unchanged — the convention only affects how the slide strings are assembled.

Recommended structure:

build-deck-name/
  slides/
    s01-cover.js
    s02-context.js
    s04-investment.js
    ...
    s17-flywheel.js
  shared/
    head-extra.js     ← palette tokens, CSS classes
  build.js            ← imports slides, calls createDeck()

Each slide module exports exactly two things:

// s04-investment.js
module.exports = {
  html: `<div class="deck-shell">...</div>`,
  script: `(function() { /* echarts init for this slide */ })();`
};

build.js assembles and calls createDeck():

const slides = require('./slides/s04-investment');
// ...
createDeck({
  slides: [s01, s02, s04, ...].map(s => s.html + (s.script ? '<script>' + s.script + '</script>' : '')),
  headExtra,
  // ...
});

Why this matters for quality:

• Each slide file is 80–120 lines — readable in one pass; the agent can fix S11 without scrolling through 1,500 lines
• Slide-level isolation: changing S11's chart height cannot accidentally touch S14
• The space budget comment at the top of each module makes sizing decisions auditable
• One file = one argument = one layout decision — matches the ghost deck's one-slide-one-claim rule

This is a convention, not a requirement. For decks under 10 slides, a single build script is fine.

Slide shell

The shell uses CSS Grid with fixed row heights — this structurally prevents footer overflow, which is the most common layout failure in deck production.

<div style="height: 100%; display: grid; grid-template-rows: auto minmax(0, 1fr) 48px;">
  <!-- HEADER ZONE — action title with accent bar -->
  <div class="px-14 pt-8 pb-2 border-t-4 border-[var(--accent)]">
    <p class="text-xs font-semibold tracking-widest uppercase text-[var(--accent)] mb-1">
      Section Label
    </p>
    <h2 class="text-3xl font-semibold leading-snug tracking-tight text-[var(--text)]"
        style="font-family: var(--font-heading)">
      Action title — full sentence conclusion
    </h2>
  </div>

  <!-- BODY ZONE — all content lives here; overflow is clipped, never pushes footer -->
  <div class="px-14 py-3" style="min-height: 0; overflow: hidden;">
    <!-- Layout primitives go here (grids, cards, charts, etc.) -->
  </div>

  <!-- FOOTER ZONE — fixed 48px row, cannot be displaced -->
  <div class="px-14 flex items-center justify-between
              text-xs text-[var(--text-fine)]"
       style="font-family: var(--font-body); border-top: 1px solid var(--accent-light, #ccc)33;">
    <span>Source: Analysis team, 2026</span>
    <span>Confidential</span>
  </div>
</div>

Why grid, not flex: The grid-template-rows: auto minmax(0, 1fr) 48px layout guarantees three things: 1. Header takes its natural height (auto) 2. Body fills remaining space but cannot push the footer off-slide (minmax(0, 1fr)) 3. Footer is always exactly 48px from the bottom, regardless of body content

The older flex flex-col h-full + flex-1 approach allowed body overflow to push the footer off the slide — a failure that required manual QA to catch.

Cover slides and dividers replace this shell with a full-bleed layout (see Layout primitives below).

Atomic exhibits vs wrapped slides

The reusable production unit is the atomic exhibit: graph/table/visual only, with no header or footer baked into the template. Examples under examples/*.js export:

{
  id,
  title,
  tier,
  proves,
  data,
  sectionLabel,
  actionTitle,
  source,
  exhibitId,
  responsiveSpec,  // optional: chart ranges or layout QA samples
  renderExhibit({ checkpoint, width, height, tokens }) { ... }
}

Use the shared helpers in examples/_shared.js to render:

• an exhibit-only QA artifact
• a wrapped slide reference artifact

Treat examples/_shared.js as the internal standards layer. Share only reusable typography, text roles, chart chrome, and repeated semantic colors. Keep exhibit geometry, data mapping, label placement, and one-off visual emphasis inside each template.

Layout anti-patterns

Common failures in deck production. Avoid these:

Design tokens

Every palette provides these CSS custom properties. Use via Tailwind arbitrary values.

Typography scale

Two systems exist for typography sizing. They serve different contexts — don't mix them.

1. Slide HTML — use the Tailwind class table below. Pick a role, use its class. No programmatic tokens. 2. ECharts exhibits — use the responsive tokens from examples/_shared.js. ECharts takes fontSize as a JS number, so Tailwind classes don't apply inside chart config.

Tailwind type roles — slide HTML

Every text element in slide HTML must use one of these roles. All roles use native Tailwind classes — no arbitrary pixel values except tag/badge.

Legibility floor: No text below text-xs (12px) except tags/badges. Body-readable text must be ≥text-sm (14px).

L1 density adaptation: Bump each role up one Tailwind step. See density-adaptation.md § L1 Sizing for the full mapping.

Tailwind ↔ px reference (default theme):

ECharts exhibit tokens

For chart/exhibit JavaScript, use the responsive token system from examples/_shared.js:

• tokens.bodyText / tokens.smallText / tokens.microText — text sizes that scale with canvas
• tokens.adapt(compact, preferred, wide) — continuous interpolation for geometry
• tokens.textAdapt(compact, preferred, wide) — slower compression for text legibility
• getFigureTypography(tokens) — axis, legend, label, annotation, metric role presets
• getChartChrome(tokens) — shared axis/gridline/legend config fragments

Use token roles wherever the styling is standard. Do not abstract geometry, chart-specific layout, or exhibit-specific emphasis into shared helpers.

Spatial constants

Icons — Font Awesome 6

Font Awesome 6 Free is vendored locally. Use <i> tags inline with text or as standalone decorators only when the glyph is render-stable in PDF output.

Common icons for consulting slides:

Usage pattern:

<!-- Inline with text -->
<span class="text-[var(--accent)]"><i class="fa-solid fa-arrow-trend-up mr-2"></i>12% YoY</span>

<!-- Card decorator (large) -->
<i class="fa-solid fa-chart-line text-3xl text-[var(--accent)] mb-3"></i>

<!-- Status indicator -->
<i class="fa-solid fa-circle-check text-emerald-500 mr-1"></i>
<i class="fa-solid fa-triangle-exclamation text-amber-500 mr-1"></i>
<i class="fa-solid fa-circle-xmark text-red-500 mr-1"></i>

Icons work best as visual anchors on KPI cards, process steps, and list items. Do not over-decorate.

Data Visualization — ECharts 5

ECharts 5 is vendored locally with SVG renderer (mandatory — <canvas> blanks in Playwright PDF). For exhibit selection, use chart-taxonomy.md.

Chart container pattern:

<!-- In the slide HTML, place a div with explicit dimensions -->
<div id="chart-1" style="width: 100%; height: 340px;"></div>

<!-- After ALL slides, add a <script> block that initializes charts -->
<script>
document.addEventListener('DOMContentLoaded', () => {
  const chart1 = echarts.init(document.getElementById('chart-1'), null, { renderer: 'svg' });
  chart1.setOption({
    animation: false,   // mandatory for static PDF
    // ... option config
  });
});
</script>

Important: The <script> block goes inside the slide HTML string (after the layout HTML but before the closing backtick). For multi-chart slides, use unique IDs and initialize all charts in a single <script> block.

MBB chart aesthetics — the configuration that makes charts look consulting-quality:

{
  animation: false,
  grid: { left: 48, right: 24, top: 32, bottom: 40, containLabel: true },
  textStyle: { fontFamily: 'Inter, system-ui, sans-serif', fontSize: 12, color: '#4E6176' },
  title: { show: false },
  tooltip: { show: false },
  legend: { bottom: 0, textStyle: { fontSize: 11, color: '#4E6176' }, itemWidth: 12, itemHeight: 12, itemGap: 16 },
  xAxis: { axisLine: { lineStyle: { color: '#C7D5E5' } }, axisTick: { show: false },
           axisLabel: { fontSize: 11, color: '#4E6176' }, splitLine: { show: false } },
  yAxis: { axisLine: { show: false }, axisTick: { show: false },
           axisLabel: { fontSize: 11, color: '#4E6176' },
           splitLine: { lineStyle: { color: '#E4EDF7', type: 'dashed' } } },
}

Chart type routing:

Waterfall chart pattern (MBB signature):

series: [
  { name: 'base', type: 'bar', stack: 'waterfall',
    data: [0, 3800, 3800, 4100, 3900],
    itemStyle: { color: 'transparent' },
    emphasis: { itemStyle: { color: 'transparent' } },
  },
  { name: 'delta', type: 'bar', stack: 'waterfall',
    data: [3800, 500, 300, -200, 300],
    itemStyle: { color: (params) => params.data >= 0 ? '#123A63' : '#CC4444' },
    label: { show: true, position: 'top',
      formatter: (p) => (p.data >= 0 ? '+' : '') + p.data,
      fontSize: 11, fontWeight: 'bold' },
  },
]

Color discipline for charts:

• Primary series: var(--chart-primary) or the hex value from the palette
• Secondary series: var(--chart-secondary) — always gray
• Positive delta: accent color or #2E9E5A (green)
• Negative delta: #CC4444 (red)
• Never more than 4 colors in one chart. MBB charts are restrained.

CSS-only bar charts (no ECharts needed for simple bars):

<div class="flex items-center gap-3 mb-2">
  <span class="w-24 text-sm text-[var(--text)] text-right shrink-0">Revenue</span>
  <div class="flex-1 bg-[var(--surface-muted)] rounded-full h-6 overflow-hidden">
    <div class="h-full bg-[var(--accent)] rounded-full" style="width: 78%"></div>
  </div>
  <span class="text-sm font-semibold text-[var(--text)] w-12">78%</span>
</div>

Use CSS-only bars for simple progress/comparison visuals. Use ECharts for anything with axes, legends, or complex data.

Responsive support model

Do not author examples against hardwired sm/md/lg buckets. The reference canvas remains 1280×720, but responsiveness follows the actual target width and height.

Use one of two contracts:

1. Chart / figure templates

responsiveSpec: {
  templateClass: 'chart',
  exhibitRange: {
    min: { width: 960, height: 540 },
    preferred: { width: 1280, height: 720 },
    max: { width: 1600, height: 900 },
  },
  slideRange: {
    min: { width: 1024, height: 576 },
    preferred: { width: 1280, height: 720 },
    max: { width: 1600, height: 900 },
  },
  rationale: 'end labels become unreadable below the declared minimum',
}

2. Layout / content templates

responsiveSpec: {
  templateClass: 'layout',
  previewSamples: [
    { label: 'compact', width: 1024, height: 576 },
    { label: 'preferred', width: 1280, height: 720 },
    { label: 'wide', width: 1440, height: 810 },
  ],
  agentSizingNotes: 'agent should split or simplify if width falls below the compact QA sample',
}

Layout primitives

Six layout structures for the body zone. Combine with the slide shell above.

Content primitives

Small HTML components to compose inside layout primitives.

KPI Metric Card:

<div class="bg-[var(--surface-muted)] rounded-lg p-5 flex flex-col">
  <i class="fa-solid fa-chart-line text-2xl text-[var(--accent)] mb-3"></i>
  <span class="text-2xl font-bold tracking-tight text-[var(--text)]">$4.2B</span>
  <span class="text-sm font-semibold text-[var(--text)] mt-1">Revenue</span>
  <span class="text-xs text-[var(--text-muted)] mt-1">
    <i class="fa-solid fa-arrow-trend-up text-emerald-500 mr-1"></i>↑ 12% YoY
  </span>
</div>

Evidence Panel (bordered):

<div class="border border-[var(--accent-light)]/40 rounded-lg p-5">
  <h3 class="text-xs font-bold tracking-widest uppercase text-[var(--accent)] mb-3">
    Key Drivers
  </h3>
  <ul class="space-y-2 text-sm text-[var(--text)]" style="font-family: var(--font-body)">
    <li class="flex items-start gap-2">
      <i class="fa-solid fa-chevron-right text-[10px] text-[var(--accent)] mt-1.5 shrink-0"></i>
      <span>Market share grew 3pp driven by pricing advantage in mid-tier segment</span>
    </li>
  </ul>
</div>

Data Table:

<table class="w-full text-sm" style="font-family: var(--font-body)">
  <thead>
    <tr class="border-b-2 border-[var(--accent)]">
      <th class="text-left py-2 font-semibold text-[var(--text)]">Metric</th>
      <th class="text-right py-2 font-semibold text-[var(--text)]">2024</th>
      <th class="text-right py-2 font-semibold text-[var(--text)]">2025</th>
      <th class="text-right py-2 font-semibold text-[var(--text)]">Delta</th>
    </tr>
  </thead>
  <tbody class="text-[var(--text)]">
    <tr class="border-b border-[var(--accent-light)]/30">
      <td class="py-2">Revenue</td>
      <td class="text-right py-2 tabular-nums">$3.8B</td>
      <td class="text-right py-2 tabular-nums">$4.2B</td>
      <td class="text-right py-2 font-semibold text-emerald-600">+11%</td>
    </tr>
  </tbody>
</table>

Callout Box:

<div class="bg-[var(--accent)]/5 border-l-4 border-[var(--accent)] px-5 py-4 rounded-r-lg">
  <p class="text-sm font-medium text-[var(--text)]">
    <i class="fa-solid fa-lightbulb text-[var(--accent)] mr-2"></i>
    Key insight or recommendation text here
  </p>
</div>

Composition routing

Map each slide's communication move to a layout composition.

Exhibit Design — Practitioner Playbook

The chart is never the point. The argument is the point. The chart is proof.

>

Load this reference when designing exhibits. Don't start with "what chart?"

Start with "what does this slide need to prove?"

The Exhibit Principle

An exhibit is NOT a chart. An exhibit is a visual argument:

A chart without an action title is data. A title without evidence is assertion. Together they form proof.

---

Exhibit Selection — Decision Tree

Given the slide's claim, follow the path to the right exhibit.

"How big is it?" — Sizing, Comparison, Benchmarking

Practitioner note: A single large number ($4.2B, 44px bold, centered) often hits harder than any chart. If the number is surprising, let it land alone.

"Why did it happen?" — Decomposition, Drivers

Practitioner note: The waterfall is consulting's default exhibit for any delta question. Sort deltas by magnitude (largest positive first → largest negative last) unless chronological order matters more.

"What should we do?" — Positioning, Prioritization

Practitioner note: The axis choice on a 2×2 IS the insight. The value is selecting dimensions that reveal something non-obvious.

---

Chart Repertoire by Deck Need

Grouped by when you need them, not by abstract categories. Build templates in this order.

Tier 1 — Foundation

Every consulting deck draws from these. Master these first.

Tier 2 — Strategic

Strategy, recommendation, positioning, and evaluation decks.

Tier 3 — Operational

Transformation, implementation, and monitoring decks.

Tier 4 — Specialist

Specific analytical needs. Used when the analysis demands it, not routine.

CSS-Only vs. ECharts

CSS-only (simpler, more reliable in PDF pipeline):

• Horizontal progress bars, simple comparisons (<5 items)
• 2×2 matrices, priority grids, evaluation grids
• Process flows, swimlanes, driver trees
• Timelines, roadmaps, Gantt
• KPI cards, data tables, RACI

ECharts (when you need axes, computed layouts, or complex data):

• Any chart with axes (bar, line, scatter)
• Waterfalls (stacked bar with invisible base)
• Sankey, treemap, radar, funnel, heatmap
• Pareto (dual axis bar + line)
• Any data series with >5 data points

---

Firm Visual Identity

Documented — What Each Firm Actually Invented

Historical facts that shape each firm's visual DNA.

McKinsey: Barbara Minto developed the Pyramid Principle at McKinsey (1960s–70s) — structured communication where the conclusion leads and evidence follows. This is why McKinsey-style slides open with the verdict in the action title. Every slide proves one conclusion stated upfront.

BCG: Bruce Henderson created the Growth-Share Matrix in 1970 — the original 2×2 matrix (Stars, Cash Cows, Dogs, Question Marks). This established two-dimensional strategic positioning as a fundamental consulting tool. BCG's analytical framework tradition descends from this: process-transparent, framework-anchored arguments.

Bain: Fred Reichheld (Bain Fellow) created the Net Promoter Score in 2003. Bain positions around "Results Delivery" — every analysis connects to a specific decision and measurable outcome. This action-orientation shapes their visual language: always tie the exhibit to "what should the CEO do?"

Observable — What's Visible in Public Materials

From published reports, brand guidelines, and public presentations:

Practitioner Conventions — Honest Assessment

These are real patterns but they vary by partner, office, and engagement. Treat as useful defaults, not hard rules.

Communication style is the real differentiator — more than chart selection:

What's universal (NOT firm-specific):

• Waterfalls, bars, lines, stacked bars — foundational exhibits used identically across all three firms
• Marimekko charts for market landscape — used across firms, not proprietary to any one
• 2×2 matrices — universal despite BCG's historical association
• Data tables, KPI cards — universal

What's genuinely firm-specific:

• Bain's Facts-vs-Perspectives layout — slides split into facts (left, ~55%, data/evidence) and perspectives (right, ~45%, interpretation/recommendation). This separates what the data shows from what the firm recommends. I've not seen this used systematically at McKinsey or BCG. This is the ONE clearly differentiating visual convention.

What varies by partner more than by firm:

• Annotation density (minimal vs. liberal) — some partners at any firm want callout boxes, some kill them
• Chart type tolerance (radar love/hate, pie chart acceptance) — partner-specific
• Color accent system details — each firm has brand colors, but individual engagements vary

Practical guidance for the skill:

• McKinsey palette → navy primary, minimal annotation, two-tier header (section label + action title), clean exhibits that prove the title without additional interpretation
• BCG palette → green primary, annotation welcomed, panel mini-headers on multi-panel slides, green rule below action title as visual signature
• Bain palette → grayscale + red accent on focal element, simpler header (title + red rule), facts-vs-perspectives on analytic slides

---

Deck Archetypes

By what the deck needs to DO. Exhibit mixes below are approximate guidelines — actual decks vary.

Diagnostic / Current State

Purpose: "Here's what we found." Arc: Performance context → Gap analysis → Root causes → Value at stake → Implications

Strategic Recommendation

Purpose: "Here's what you should do." Arc: Strategic context → Options assessed → Recommended path → Value at stake → Roadmap → Next steps

Transformation Roadmap

Purpose: "Here's how we'll execute." Arc: Initiative portfolio → Sequencing → Governance → Quick wins → Milestones

Board / Steering Committee

Purpose: "Here's where we are." Arc: Headlines → KPIs → Progress vs. plan → Risks → Decisions needed

Due Diligence / Investment Memo

Purpose: "Here's what this asset is worth." Arc: Market → Competitive position → Financial performance → Growth → Risks → Valuation → Recommendation

Investor / Roadshow

Purpose: "Here's why you should invest." Arc: Problem → Solution → Traction → Market → Model → Competition → Team → Ask

---

Annotation Grammar

Annotations turn data into insight. The chart shows what happened; annotations show what it means.

Annotation Rules

1. Every data point gets a direct label. Never force the reader to estimate from an axis. Most common correction in deck reviews. 2. Reference lines get text ON the line. "Target: $4.2B" sitting on the line — not in a legend. 3. One callout per exhibit. Two means the exhibit is trying to say two things — split it. 4. Callout = interpretation, not description. Wrong: "Revenue grew 12%." Right: "Growth was entirely price-driven — volume was flat." 5. Number formatting: "$4.2B" not "$4,234M". "23%" not "0.23". "3.2×" not "320%". Use the unit that makes comparison intuitive. 6. Delta formatting: Always include sign. "+12%" green, "−8%" red. Exception: when positive is bad (cost growth → red "+12%").

Callout Box Implementation

<!-- Position relative to chart container -->
<div class="relative">
  <div id="chart-1" style="width: 100%; height: 340px;"></div>
  <!-- Callout — positioned over chart area -->
  <div class="absolute top-4 right-4 max-w-[200px] bg-white border border-[var(--accent)]
              rounded px-3 py-2 text-xs text-[var(--text)] shadow-sm">
    <span class="font-semibold text-[var(--accent)]">Key insight:</span>
    Growth was entirely price-driven — volume was flat
  </div>
</div>

---

Consulting Compositions

These are NOT charts — they are structural layouts that no charting library produces. They answer organizational, governance, and synthesis questions where the visual is a system, not a data series.

When to use a composition instead of a chart

Composition characteristics

• CSS-only: facts-perspectives, rapid-map, driver-tree, org-model, kpi-cascade, swimlane, screening-funnel, coverage-matrix, communication-cascade, capability-matrix, decision-flow, three-horizons.
• ECharts: dumbbell-benchmark (scatter), stakeholder-map (scatter), network-map (graph), cohort-retention (heatmap), economic-value-stack (stacked bar).
• Firm affinity: Facts-vs-Perspectives is Bain's signature. RAPID maps are Bain-originated. Driver trees are McKinsey's signature. Economic value stacks are BCG-originated (EVE). Three horizons is McKinsey-originated. Others are universal.
• Density: All compositions work at L2 and L3. At L1, Facts-vs-Perspectives, Driver Tree, and Three Horizons adapt well; RAPID maps, Swimlanes, Capability matrices, and Decision flows are inherently L2+.
• Token-driven: All use _shared.js tokens for responsive text and spacing. No hardcoded font sizes.

---

Aesthetic Rules

Apply regardless of chart type, firm, or archetype.

1. No chartjunk. No 3D, gradients, shadows, decorative elements. 2. Direct label > legend. Label data directly. Legend only when labeling would clutter (4+ overlapping series). 3. Max 4 colors per exhibit. Primary + gray + 1–2 semantic. Never rainbow. 4. Title in the slide header. title: { show: false } in ECharts. The action title IS the chart title. 5. No tooltips. tooltip: { show: false }. Static PDF. 6. No animation. animation: false. 7. Y-axis gridlines only. Dashed, light. No X gridlines. 8. Axis labels: Muted color, 11–12px. Reference, not content. 9. Color discipline: Use palette tokens. Primary accent + gray + 1–2 semantic colors max. 10. Spend visual budget on interpretation. If you can afford one extra element, make it a callout — not a gradient.

Density Adaptation — L1 / L2 / L3

How the same argument structure compresses or expands across density levels.

What Changes Between Levels

L2 → L1 Compression (Show Deck)

1. Collapse methodology slides → move to appendix. Show deck shows WHAT, not how. 2. Merge diagnostic detail — 3 analytical slides building one insight → 1 slide stating the insight with supporting evidence. 3. Promote action titles — title alone must carry the argument. If you need to read the chart, the title is too weak. 4. Add explicit pivot slides — between pillars, insert a transition slide (no data). Net effect: remove analytical slides, add transitions. Count drops 30–40%. 5. Curate evidence — each slide gets ONE layer. Choose strongest proof point.

L1 compression is NOT "delete slides." It is "restructure the argument for an audience that spends 3 seconds per slide."

L2 → L3 Expansion (Dense / Appendix)

1. Expose model architecture — value driver tree structure, assumption tables, data source maps. 2. Add sensitivity analysis — for every quantified claim, show how conclusions change under different assumptions. 3. Chain exhibit references — number every exhibit. Titles reference prior exhibits. 4. Expand data tables — complete data, not curated subsets. Segment-level, time-series, statistical confidence. 5. Remove transition slides — transitions happen in title chains only.

Selection Heuristic

Board / SteerCo / CEO-only  →  L1 show deck + L2 appendix
Project team / working session  →  L2 working deck
Technical review / due diligence  →  L3 dense
Unsure  →  Default to L2

Most engagements produce BOTH L1 and L2. Build L2 first, compress to L1.

Typical Slide Counts

Firm × Density Interaction

See firm-dna.md for full firm-specific density behavior. Key differences:

• McKinsey: Methodology goes to appendix even at L2. L1 appendix can be 40–60% of main deck length.
• BCG: L2 is native density. Panel mini-headers and annotation arrows persist even at L1. BCG at L1 still looks denser than McKinsey at L1.
• Bain: Decision brief stays at every density. Facts vs Perspectives only appears at L2+. Sprint plans at L1 show milestones only; at L2 they show week-by-week detail.

Typography Tier Mapping

Density and typography tier are related but distinct:

L1 Sizing — Fill, Don't Float

L1 means fewer elements per slide, not smaller content floating in empty space. Each element should scale up to fill the ~600px body zone. The fill-first rule applies at every density level — L1 achieves it with larger fonts and more breathing room between fewer items, not by leaving blank space at the bottom.

L1 typography rule: Bump each role up one native Tailwind step from the L2 baseline. Footer stays at the floor (text-xs).

The hierarchy holds at both levels: cover > action > metric > subtitle > body > labels > fine print. No ranges to decide — one class per role per density.

L1 chart sizing: Charts at L1 still follow the fill-first rule. A chart that is the sole exhibit on a slide should fill the body zone (≈ 540–580px after title and gap), not sit at 300px with whitespace below. L1 charts tend to be simpler (fewer series, fewer data points) but physically larger.

Engagement Archetypes & Transitions

Archetype classification, transition patterns, and exhibit routing for deck construction.

The Eight Archetypes

Hybrid engagements: Use one archetype as primary skeleton, pull pillar modules from secondary. Never stitch two full skeletons together.

Five Transition Types

Every pillar boundary needs a transition. These are the five canonical patterns:

Rising-Stakes Progression

Never skip a state. Each must be earned through evidence. Flat stakes = dead deck.

Common Transition Sequences

Archetype → Exhibit Mix

Which example modules each archetype typically uses. Use this to auto-route from archetype to templates.

How to use this table: After classifying the archetype, scan the signature and supporting columns to select exhibits. The action titles determine what's needed — not every deck uses every exhibit listed.

Evidence Recipes — Data-Shape Compositions

Standard exhibit compositions for consulting slides. Each recipe answers: "When I need to prove [X], what chart combination should I use?"

Quick Lookup

Layering Rules

One evidence layer = one distinct visual element (chart, table, metric cards, callout stack).

Hard ceiling: 4 layers per slide. More = you haven't made the editorial choice.

Recipe Details

1. Waterfall Bridge

Proves: "The gap/change is driven by these specific factors, in this order of magnitude."

• Primary: waterfall chart (5–8 bars: start anchor, 3–6 deltas, end anchor)
• Supporting: sidebar with 2–3 interpretation bullets explaining WHY largest deltas exist
• Annotation: delta labels on each bar, variance share row beneath

2. Evaluation Grid

Proves: "Among all options, [this one] is strongest across [these criteria]."

• Primary: matrix with criteria rows (4–8) × option columns (3–5), RAG-coded cells
• Supporting: summary row or recommendation highlight (bold border on winner)
• Annotation: "Key finding" bullets summarizing the pattern

3. Market Sizing Stack

Proves: "The addressable opportunity is $X, concentrated in [segments]."

• Primary: stacked bar or nested waterfall (total → segments → addressable)
• Supporting: segment callout sidebar with growth rates and fit scores
• Annotation: CAGR labels, segment boundary labels

4. Priority Matrix

Proves: "Given [dim 1] and [dim 2], these items are in the priority zone."

• Primary: scatter/bubble plot with named items (size = 3rd dimension)
• Supporting: quadrant labels ("Quick wins", "Strategic bets", etc.)
• Annotation: highlight zone or callout for recommended cluster

5. Timeline / Phasing

Proves: "Implementation follows N phases, with these milestones as gates."

• Primary: Gantt bars or phase blocks on time axis
• Supporting: milestone markers at decision points
• Annotation: dependency arrows, value realization markers

6. KPI Scorecard

Proves: "Across N dimensions, performance is [strong/mixed/weak]."

• Primary: 4–6 metric cards with KPI number + trend + context
• Supporting: RAG status indicators
• Annotation: assessment summary connecting scorecard to next action

7. Facts vs. Perspectives

Proves: "Here's what we know (facts) and what we recommend (perspectives)."

• Left column (~57%): "KEY FACTS & DATA" — 3–6 quantified bullets + optional mini-exhibit
• Right column (~43%): "PERSPECTIVES" — action-oriented recommendation bullets
• Annotation: implication callout band at bottom

8. Scenario Fan

Proves: "Under N scenarios, outcome ranges from X to Y, base case at Z."

• Primary: line chart with 3 paths (base, upside, downside) diverging from common point
• Supporting: scenario labels with key assumptions
• Annotation: decision-relevant threshold line (breakeven, hurdle rate)

9. Process Diagram

Proves: "This is how the system works, and [this step] is the leverage point."

• Primary: process steps (boxes/nodes) connected by arrows, one step highlighted
• Supporting: feedback loops or reinforcing connections
• Annotation: callout at leverage point explaining WHY it matters

10. Benchmark Comparison

Proves: "[Client] is at X on [metric], [above/below] peer median by Y."

• Primary: horizontal bars with peers in gray, client highlighted in accent
• Supporting: peer median line (dashed)
• Annotation: gap annotation converted to dollar/percentage impact

Recipe × Engagement Type