Pro Report Builder

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

Component Density Limits

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