pro-report-builder

---
name: pro-report-builder
description: Create polished HTML technical reports and multi-page documents for consulting deliverables. Includes a customizable design system with dark cover page, warm cream content pages (8.5x11 portrait), professional typography, and a curated component library (KPI cards, data tables with severity coloring, callout boxes, recommendation cards, priority banners). Trigger on report, audit report, technical document, written report, assessment, or multi-page document. Outputs standalone HTML files exported to PDF via Chrome headless.
license: MIT
origin: custom
author: Rebecca Rae Barton
author_url: https://github.com/thatrebeccarae
metadata:
  version: 1.0.0
  category: reporting
  domain: consulting-deliverables
  updated: 2026-03-18
  tested: 2026-03-18
  tested_with: "Claude Code v2.1"
---

# Pro Report Builder

Polished consulting reports as standalone HTML. Export to PDF via Chrome headless.

## Install

```bash
git clone https://github.com/thatrebeccarae/claude-marketing.git && cp -r claude-marketing/skills/pro-report-builder ~/.claude/skills/
```

## Quick Reference

| Task | Approach |
|------|----------|
| Create report from scratch | Read [REFERENCE.md](REFERENCE.md) for CSS + HTML patterns |
| Add a new component type | Compose from existing components in REFERENCE.md |
| Export to PDF | Chrome headless `--print-to-pdf` (see Export section) |
| Customize brand tokens | Edit CSS custom properties in `:root` block |

### When to Use This Skill vs pro-deck-builder

| | pro-report-builder | pro-deck-builder |
|---|---|---|
| **Format** | 8.5x11" portrait pages | 16:9 landscape slides |
| **Content flow** | Multi-page, flowing text | Single-slide compositions |
| **Export** | Chrome headless `--print-to-pdf` | Puppeteer |
| **Use for** | Audit reports, assessments, written deliverables | Presentation decks, pitch slides |

---

## Before You Start

### Step 1: Understand the Brief

Ask the user:

1. **What type of document?** Audit report, assessment, technical brief, case study?
2. **How many pages roughly?** Helps plan section flow and page distribution.
3. **What data do they have?** Raw numbers, API exports, spreadsheets? Pull exact values -- never estimate when actuals exist.
4. **Where should the file be saved?** Default: `./output/`

### Step 2: Plan the Document Structure

Every report follows this structure:

```
Cover Page --> Executive Summary --> Analysis Sections (3-6) --> Prioritized Recommendations --> Quick Wins --> Appendix
```

Each analysis section should occupy 1-2 pages. Recommendation cards are the most space-intensive component -- budget carefully.

---

## Design System

### Customizable Brand Identity

The included design system provides a professional default. All color tokens, typography, and spacing are defined as CSS custom properties in `:root`. **Override these to match your brand.**

### Color Tokens

```css
:root {
  /* Accent -- change this to your brand color */
  --accent:        #3D7A5C;
  --accent-dim:    rgba(61, 122, 92, 0.08);
  --accent-dark:   #2E6B4A;
  --accent-light:  #6AB88A;

  /* Severity */
  --excellent:     #2e8b57;
  --warning:       #D97706;
  --critical:      #c0392b;

  /* Light-mode backgrounds (warm cream) */
  --bg-page:       #FAF7F2;
  --bg-surface:    #F2EDE6;
  --bg-elevated:   #EBE5DD;

  /* Light-mode text */
  --text-primary:  #0f0e0e;
  --text-body:     #57606a;
  --text-muted:    #8b949e;

  /* Borders */
  --border:        rgba(15, 14, 14, 0.1);
  --border-dim:    rgba(15, 14, 14, 0.06);

  /* Callout tints */
  --tint-blue:     #eaf2ed;
  --tint-green:    #eaf5ef;
  --tint-red:      #fef2f2;
  --tint-amber:    #fffbeb;

  /* Dark mode (cover page only) */
  --dark-bg:       #141414;
  --dark-surface:  #1E1E1E;
  --dark-text:     #f0f3f6;
  --dark-muted:    #6e7681;
  --dark-secondary:#9ca3af;
  --dark-border:   rgba(255, 255, 255, 0.08);
}
```

**Color rules:**
- Warm cream (`#FAF7F2`) backgrounds on ALL content pages -- NOT white. This is a brand differentiator.
- Dark mode (`#141414`) is reserved for the cover page only.
- Accent color for accent rules, table headers, bullet markers, priority banner accents, rec-card left stripes. Used deliberately, never for decoration.
- Severity colors (green/amber/red) ONLY for performance indicators. Never decorative.
- Callout tints (blue/green/red/amber) for left-bordered callout boxes matching their severity.

### Typography

| Role | Font | Weight | Size | Tracking | Notes |
|------|------|--------|------|----------|-------|
| Cover title | Switzer | Light (300) | 36pt | -0.03em | Document name on dark cover. |
| Cover subtitle | Switzer | Regular (400) | 16pt | normal | Below cover title. Color: `--dark-muted`. |
| Cover tag | Cartograph CF | Regular (400) | 8pt | +0.15em | ALL CAPS. Color: `--accent`. Above title. |
| Section title | Switzer | Regular (400) | 18pt | -0.02em | Content page h2. Followed by accent rule. |
| Subsection title | Switzer | SemiBold (600) | 12.5pt | normal | Content page h3. |
| Body text | Switzer | Regular (400) | 9.5pt | normal | Paragraphs, descriptions. Line-height: 1.6. |
| Table header | Cartograph CF | SemiBold (600) | 7.5pt | +0.05em | ALL CAPS. White text on accent bg. |
| Table body | Switzer | Regular (400) | 8.5pt | normal | Alternating row backgrounds. |
| KPI value | Cartograph CF | SemiBold (600) | 16pt | -0.02em | KPI card numbers. |
| KPI label | Cartograph CF | Regular (400) | 6.5pt | +0.06em | ALL CAPS. Below KPI values. |
| Rec-card label | Cartograph CF | SemiBold (600) | 7.5pt | +0.04em | ALL CAPS. Field labels. |
| Priority banner | Cartograph CF | SemiBold (600) | 9pt | +0.08em | ALL CAPS. Priority tier labels. |
| Page footer | Switzer | Regular (400) | 7pt | +0.03em | Centered. Color: `--text-muted`. |

**Critical typography rules:**
1. **Cover title uses Light (300), NOT Bold.** Light at large sizes = confident, premium.
2. **Monospace font for ALL numeric/data content.** KPI values, table headers, rec-card labels, priority banners.
3. **Body text at 9.5pt with 1.6 line-height.** Reading-optimized document, not a slide.
4. **Table headers are ALL CAPS monospace on accent background.** Distinctive table style.

**Font defaults (swappable):**
- Switzer: loaded from Fontshare CDN (free). Fallback: `system-ui, sans-serif`
- Cartograph CF: commercial, loaded via `local()`. Fallback: `JetBrains Mono, monospace`

### Page Dimensions

```
Width:   8.5in
Height:  11in
Orientation: Portrait
```

### Spacing

| Zone | Value |
|------|-------|
| Content padding | `0.6in 0.75in 0.7in` |
| Cover page padding | `0 1in 1in` (bottom-aligned) |
| Page footer | Absolute positioned, `bottom: 0`, `padding: 10px 0.75in 14px` |
| Section title margin-bottom | `4px` (then accent rule adds `20px` below) |
| Subsection title margin | `20px top, 8px bottom` |

---

## Component Library

All components are documented with full HTML + CSS in [REFERENCE.md](REFERENCE.md). Here is what is available:

### Page Structure

| Component | Class | Use |
|-----------|-------|-----|
| Page Container | `.page` | 8.5x11" page with shadow. |
| Cover Page | `.cover-page` | Dark cover with bottom-aligned content. |
| Content Area | `.content` | Padded content region within a page. |
| Page Footer | `.page-footer` | Centered footer with doc name + page number. |
| Section Title | `.section-title` + `.accent-rule` | Section heading with accent underline. |
| Section Continued | `.section-continued` | "(continued)" tag for multi-page sections. |

### Data Display

| Component | Class | Use |
|-----------|-------|-----|
| KPI Row | `.kpi-row` / `.kpi-card` | 4-column grid of big-number cards. |
| KPI Card (Risk) | `.kpi-card--risk` | Red-tinted variant for risk/negative KPIs. |
| Data Table | `table` with severity classes | Striped rows, accent headers, severity colors. |

### Content Blocks

| Component | Class | Use |
|-----------|-------|-----|
| Callout Box | `.callout` + `.callout-{color}` | Left-bordered insight box (blue/green/red/amber). |
| Body Text | `.body-text` | Standard paragraph text. |
| Bullet List | `.bullet-list` | Accent-colored dot bullets. |
| Numbered List | `.numbered-list` | Mono-font accent markers. |

### Recommendations

| Component | Class | Use |
|-----------|-------|-----|
| Priority Banner | `.priority-banner` + level class | Tier label (CRITICAL/HIGH/MEDIUM/LOW). |
| Recommendation Card | `.rec-card` + level class | Multi-field card with left accent stripe. |
| Quick Wins Table | Table with `.qw-num` | Numbered action items table. |

---

## Document Compositions

### Mandatory Pages

Every report must include:

1. **Cover Page** (`.cover-page`) -- Dark background, document title, metadata (date, account, period)
2. **Executive Summary** -- KPI row + key findings callout + brief narrative
3. **Recommendations** -- Prioritized rec-cards grouped by priority tier
4. **Quick Wins** -- Short action table for immediate wins

### Content Page Types

| Type | When to Use | Key Components |
|------|-------------|----------------|
| Data Table + Narrative | Inventory, benchmarking | Table + `.body-text` + `.bullet-list` |
| Callout Stack | Deep-dive on specific items | Multiple `.callout` boxes (green/red/amber) |
| Table + Callout | Performance data with insight | Table + single callout summary |
| Rec-Card Stack | Prioritized recommendations | `.priority-banner` + `.rec-card` stack |
| Mixed Analysis | Multi-part section | Tables + callouts + bullets + subsections |

---

## Narrative Rules

1. **One section per page when possible.** If a section spans multiple pages, use "(continued)" on subsequent pages.
2. **Lead with the data.** Tables and KPI cards BEFORE the narrative explanation.
3. **Callout after evidence.** Every data table should be followed by a callout summarizing the key insight.
4. **Never estimate when actuals exist.** If the data has exact values, compute precise totals.
5. **Benchmark everything.** Always show industry benchmarks alongside metrics.
6. **Severity colors = signal.** Green/amber/red ONLY for performance indicators.
7. **Callout colors match severity.** `.callout-green` for strengths, `.callout-red` for problems, `.callout-amber` for warnings, `.callout-blue` for neutral insights.
8. **Accent rules under section titles.** Every `.section-title` is followed by `<hr class="accent-rule">`.
9. **Consistent rec-card fields.** Every recommendation card should have at minimum: title bar, ISSUE, ACTION fields.

---

## Page Overflow Prevention

Pages are fixed at 11in tall. Content that exceeds the page container overflows visibly in the PDF. **Every page must be budgeted before building.**

### Height Budget

| Zone | Height |
|------|--------|
| Content padding (top + bottom) | ~1.3in |
| Page footer | ~0.4in |
| **Usable content area** | **~9.3in** |

### Component Density Limits

| Component | Max items per page | Dense mode override |
|-----------|-------------------|---------------------|
| **Rec-cards (full fields)** | 3 cards | For 4+: drop optional fields |
| **Rec-cards (minimal)** | 4-5 cards | Reduce margin to `8px 0 12px` |
| **Data tables** | 10-12 rows | For 13+: reduce font to `7.5pt`, padding to `3px 8px` |
| **Callout boxes** | 3-4 per page | Reduce padding to `10px 14px` |
| **Bullet lists** | 6-8 items | Shorten descriptions |

### Page Break Strategy

1. **Test every page in the browser** before exporting to PDF
2. **Redistribute content** across pages when overflow occurs
3. **Each `<div class="page">` is one PDF page**
4. **Use `.keep-together`** on components that should not split across pages
5. **Update ALL downstream page numbers** when redistributing

---

## Anti-Patterns (Never Do)

1. **No white backgrounds.** Always `#FAF7F2` (warm cream) for content pages.
2. **No bold section titles.** Use Regular (400) for `.section-title`.
3. **No decorative accent bars** beyond the 40px accent rule under section titles.
4. **No emoji in reports.** Unless the user explicitly requests them.
5. **No dark-mode content pages.** Dark is only for the cover page.
6. **No walls of text.** Break long prose into bullet lists. Max 3 sentences per callout.
7. **No unformatted numbers.** Always use `$X,XXX` or `$XXXK` with tabular-nums.
8. **No inline styles when a class exists.** Use the component library.
9. **No monospace fonts in page footers.** Use body font for footers.
10. **No orphan rec-cards.** Priority tier banner + first card must be on same page.
11. **No missing accent rules.** Every `.section-title` must be followed by `<hr class="accent-rule">`.

---

## PDF Export

### Automated Export (Preferred)

Use Chrome headless for reliable 8.5x11" portrait PDF generation:

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless \
  --disable-gpu \
  --print-to-pdf="/OUTPUT/PATH/report.pdf" \
  --no-pdf-header-footer \
  --print-to-pdf-no-header \
  "file:///PATH/TO/report.html"
```

### Manual Export (Fallback)

1. Open the HTML file in Chrome
2. `Cmd+P` --> Save as PDF
3. Set margins to "None"
4. Enable "Background graphics"
5. Paper size: Letter (8.5" x 11")

### Required Print CSS

Every report MUST include this `@page` rule and `@media print` block:

```css
@page { size: 8.5in 11in; margin: 0; }
@media print {
  * { print-color-adjust: exact; -webkit-print-color-adjust: exact; }
  body { background: white; margin: 0; }
  .page {
    margin: 0;
    box-shadow: none;
    page-break-after: always;
    page-break-inside: avoid;
    width: 8.5in;
    min-height: 11in;
  }
  .page:last-child { page-break-after: avoid; }
}
```

---

## QA Checklist

Before delivering, verify:

### Data Accuracy
- [ ] All numbers are accurate and internally consistent
- [ ] Percentages add up where they should
- [ ] Revenue figures match across exec summary KPIs, tables, and rec-card references

### Page Overflow (check EVERY page)
- [ ] No content overflows page boundaries
- [ ] Rec-card pages have max 3 full-field cards
- [ ] Data tables with 13+ rows use dense mode

### Visual Consistency
- [ ] Every content page has a `.page-footer` with correct page number
- [ ] Cover page has NO `.page-footer`
- [ ] Every `.section-title` is followed by `<hr class="accent-rule">`
- [ ] Multi-page sections use "(continued)"
- [ ] Callout colors match their severity
- [ ] Priority banners use correct level class

### PDF Export
- [ ] `@page` rule present with `size: 8.5in 11in`
- [ ] `print-color-adjust: exact` applied globally
- [ ] All background colors render in PDF