pro-report-builder

Pro Report Builder

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

Install

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 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

: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. 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:

"/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:

@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