Branded Document Suite

Branded Document Suite

Purpose

A unified document generation system producing professionally styled PDF, DOCX, PPTX, and XLSX files with consistent branding, configurable through a single brand configuration file.

Problem Space:

• Inconsistent branding across document types
• Manual formatting overhead
• Difficulty maintaining style guides
• No version control for document templates

Solution Approach:

• Single brand configuration drives all formats
• Template-based generation with content injection
• Support for complex layouts (tables, charts, diagrams)
• Export to multiple formats from single source

When to Use

• Company reports and documentation
• Client deliverables
• Internal presentations
• Automated report generation in pipelines
• White-label document generation
• Any document requiring consistent brand identity

When NOT to Use

• Quick notes or scratch documents
• Documents that require complex interactive elements
• Real-time collaborative editing
• Documents requiring specific proprietary format features

Core Instructions

Brand Configuration Schema

Always establish brand configuration first. This drives all document styling.

# brand-config.yaml
brand:
  name: "Company Name"
  tagline: "Your tagline here"

colors:
  primary: "#3AA7F9"
  primary_dark: "#2A7BC4"
  primary_light: "#E8F4FD"
  secondary: "#211644"
  accent: "#F59E0B"

  # Semantic colors
  success: "#22C55E"
  warning: "#F59E0B"
  danger: "#EF4444"
  info: "#0EA5E9"

  # Text hierarchy
  text_primary: "#0F172A"
  text_secondary: "#334155"
  text_muted: "#94A3B8"

  # Surfaces
  surface_primary: "#FFFFFF"
  surface_secondary: "#F8FAFC"
  surface_tertiary: "#F1F5F9"
  border: "#E2E8F0"

typography:
  display:
    family: "Montserrat"
    weights: [600, 700]
    fallback: "Arial, sans-serif"
  body:
    family: "Inter"
    weights: [400, 500, 600]
    fallback: "system-ui, sans-serif"
  mono:
    family: "JetBrains Mono"
    weights: [400, 500]
    fallback: "monospace"

  # Type scale (px)
  scale:
    h1: 32
    h2: 24
    h3: 20
    h4: 16
    body: 14
    small: 12
    caption: 10

spacing:
  base: 4  # px
  scale: [0, 4, 8, 12, 16, 24, 32, 48, 64]

assets:
  logo_primary: "./assets/logo-primary.svg"
  logo_icon: "./assets/logo-icon.svg"
  logo_white: "./assets/logo-white.svg"

Standard Procedures

1. PDF Generation (ReportLab)

from reportlab.lib.pagesizes import letter
from reportlab.lib.units import inch
from reportlab.lib.colors import HexColor
from reportlab.lib.styles import ParagraphStyle
from reportlab.platypus import SimpleDocTemplate, Paragraph, Table, Spacer, Image
import yaml

class BrandedPDFGenerator:
    def __init__(self, config_path: str):
        with open(config_path) as f:
            self.config = yaml.safe_load(f)
        self.styles = self._build_styles()

    def _build_styles(self) -> dict:
        c = self.config['colors']
        t = self.config['typography']

        return {
            'Title': ParagraphStyle(
                'Title',
                fontName='Helvetica-Bold',
                fontSize=t['scale']['h1'],
                textColor=HexColor(c['text_primary']),
                spaceAfter=24
            ),
            'Heading1': ParagraphStyle(
                'Heading1',
                fontName='Helvetica-Bold',
                fontSize=t['scale']['h2'],
                textColor=HexColor(c['primary_dark']),
                spaceBefore=20,
                spaceAfter=12
            ),
            'Body': ParagraphStyle(
                'Body',
                fontName='Helvetica',
                fontSize=t['scale']['body'],
                textColor=HexColor(c['text_secondary']),
                spaceAfter=8
            )
        }

    def create_report(self, title: str, sections: list, output_path: str):
        doc = SimpleDocTemplate(output_path, pagesize=letter)
        story = []

        # Title
        story.append(Paragraph(title, self.styles['Title']))

        # Sections
        for section in sections:
            story.append(Paragraph(section['title'], self.styles['Heading1']))
            for para in section.get('content', []):
                story.append(Paragraph(para, self.styles['Body']))
            if 'table' in section:
                story.append(self._create_branded_table(section['table']))

        doc.build(story)
        return output_path

2. DOCX Generation (python-docx)

from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

class BrandedDocxGenerator:
    def __init__(self, config_path: str):
        with open(config_path) as f:
            self.config = yaml.safe_load(f)

    def create_document(self, title: str, sections: list, output_path: str):
        doc = Document()

        # Title
        title_para = doc.add_heading(title, level=0)
        self._apply_brand_style(title_para)

        # Sections
        for section in sections:
            heading = doc.add_heading(section['title'], level=1)
            for para in section.get('content', []):
                doc.add_paragraph(para)

        doc.save(output_path)
        return output_path

    def _apply_brand_style(self, paragraph):
        c = self.config['colors']
        for run in paragraph.runs:
            run.font.color.rgb = RGBColor.from_string(c['primary_dark'][1:])

3. PPTX Generation

from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor as PPTXColor

class BrandedPptxGenerator:
    def __init__(self, config_path: str):
        with open(config_path) as f:
            self.config = yaml.safe_load(f)

    def create_presentation(self, title: str, subtitle: str, slides: list, output_path: str):
        prs = Presentation()
        prs.slide_width = Inches(13.333)
        prs.slide_height = Inches(7.5)

        # Title slide
        self._add_title_slide(prs, title, subtitle)

        # Content slides
        for slide_data in slides:
            self._add_content_slide(prs, slide_data)

        prs.save(output_path)
        return output_path

    def _add_title_slide(self, prs, title, subtitle):
        layout = prs.slide_layouts[6]  # Blank
        slide = prs.slides.add_slide(layout)

        # Background
        c = self.config['colors']
        slide.background.fill.solid()
        slide.background.fill.fore_color.rgb = PPTXColor.from_string(c['secondary'][1:])

        # Title text
        title_box = slide.shapes.add_textbox(Inches(0.5), Inches(2.5), Inches(12), Inches(1.5))
        title_frame = title_box.text_frame
        title_para = title_frame.paragraphs[0]
        title_para.text = title
        title_para.font.size = Pt(44)
        title_para.font.bold = True
        title_para.font.color.rgb = PPTXColor(255, 255, 255)

4. XLSX Generation (openpyxl)

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side

class BrandedXlsxGenerator:
    def __init__(self, config_path: str):
        with open(config_path) as f:
            self.config = yaml.safe_load(f)

    def create_spreadsheet(self, title: str, sheets: list, output_path: str):
        wb = Workbook()
        wb.remove(wb.active)  # Remove default sheet

        for sheet_data in sheets:
            ws = wb.create_sheet(title=sheet_data['name'])
            self._populate_sheet(ws, sheet_data)

        wb.save(output_path)
        return output_path

    def _populate_sheet(self, ws, sheet_data):
        c = self.config['colors']

        # Header style
        header_fill = PatternFill(start_color=c['primary'][1:], end_color=c['primary'][1:], fill_type='solid')
        header_font = Font(bold=True, color='FFFFFF')

        # Write headers
        for col, header in enumerate(sheet_data['headers'], 1):
            cell = ws.cell(row=1, column=col, value=header)
            cell.fill = header_fill
            cell.font = header_font

        # Write data
        for row_idx, row_data in enumerate(sheet_data['data'], 2):
            for col_idx, value in enumerate(row_data, 1):
                cell = ws.cell(row=row_idx, column=col_idx, value=value)
                if row_idx % 2 == 0:
                    cell.fill = PatternFill(start_color=c['surface_secondary'][1:],
                                           end_color=c['surface_secondary'][1:],
                                           fill_type='solid')

Decision Framework

Format Selection Logic:

1. Need editing? → DOCX
2. Need calculations? → XLSX
3. Need presenting? → PPTX
4. Final/archival? → PDF

Templates

Report Structure Template

report:
  title: "Quarterly Analysis Report"
  subtitle: "Q4 2025"
  author: "Analytics Team"
  date: "2025-01-11"

  sections:
    - title: "Executive Summary"
      content:
        - "Key findings paragraph 1"
        - "Key findings paragraph 2"

    - title: "Analysis"
      content:
        - "Detailed analysis text"
      table:
        headers: ["Metric", "Q3", "Q4", "Change"]
        rows:
          - ["Revenue", "$1.2M", "$1.5M", "+25%"]
          - ["Users", "10,000", "15,000", "+50%"]

    - title: "Recommendations"
      content:
        - "Recommendation 1"
        - "Recommendation 2"

Presentation Structure Template

presentation:
  title: "Project Overview"
  subtitle: "January 2026"
  author: "Team Lead"

  slides:
    - title: "Agenda"
      bullets:
        - "Current State"
        - "Proposed Changes"
        - "Timeline"
        - "Q&A"

    - title: "Current State"
      bullets:
        - "Point 1"
        - "Point 2"
      chart:
        type: "bar"
        data:
          categories: ["Jan", "Feb", "Mar"]
          series:
            - name: "2024"
              values: [100, 120, 140]
            - name: "2025"
              values: [150, 180, 200]

Examples

Example 1: Generate Branded PDF Report

Input: "Create a quarterly sales report PDF with our brand styling"

Output:

# Using the BrandedPDFGenerator
config = "brand-config.yaml"
generator = BrandedPDFGenerator(config)

sections = [
    {
        "title": "Q4 Sales Summary",
        "content": [
            "Total revenue increased by 25% compared to Q3.",
            "New customer acquisition exceeded targets by 15%."
        ],
        "table": {
            "headers": ["Region", "Q3 Revenue", "Q4 Revenue", "Growth"],
            "rows": [
                ["North", "$500K", "$650K", "+30%"],
                ["South", "$400K", "$480K", "+20%"],
                ["East", "$300K", "$370K", "+23%"]
            ]
        }
    }
]

generator.create_report(
    title="Q4 2025 Sales Report",
    sections=sections,
    output_path="Q4_Sales_Report.pdf"
)

Example 2: Create Branded Presentation

Input: "Make a project kickoff presentation with 5 slides"

Output: PPTX file with branded title slide, agenda, problem statement, solution overview, and next steps slides, all following brand color palette and typography.

Validation Checklist

Before completing document generation:

• Brand config file exists and is valid YAML
• All color codes are valid hex values
• Output directory is writable
• All content is provided (no placeholders)
• Tables have matching header/row column counts
• Images referenced are accessible
• Font fallbacks specified for missing fonts
• Document opens correctly in target application

Related Resources

• Skill: brand-asset-generator - Generate logos and visual assets
• Skill: technical-documentation-generator - HTML documentation
• ReportLab Documentation: https://docs.reportlab.com/
• python-docx Documentation: https://python-docx.readthedocs.io/

Changelog

1.0.0 (January 2026)

• Initial release
• PDF generation with ReportLab
• DOCX generation with python-docx
• PPTX generation with python-pptx
• XLSX generation with openpyxl
• Unified brand configuration system