← nyxcore-systems
6 min read

Elevating Our Reports: A Deep Dive into the NYX CORE PDF Header Redesign

We just gave our PDF report headers a major branding overhaul, transforming static markdown into dynamic, informative, and visually stunning HTML. Learn how we did it!

PDFReportingBrandingUI/UXTypeScriptPythonPlaywrightCSSHTML

In the world of data and analytics, reports are often the final, tangible output of complex processes. They need to be more than just accurate; they need to be professional, branded, and immediately understandable. Recently, our team embarked on a mission to bring our internal PDF reports up to the demanding visual standards of NYX CORE. The goal? A complete redesign of the report header, transforming it from a functional but plain markdown table into a sleek, information-rich, and beautifully branded component.

This post details our journey, the technical decisions we made, and how we achieved a significant visual upgrade with surprising ease.

The Challenge: From Functional to Fantastic

Our existing PDF report headers were generated using a simple markdown table. While effective for displaying basic information, it offered limited styling capabilities and struggled to convey the sophisticated branding and information density we desired for NYX CORE. We needed:

  • Strong Branding: A prominent, visually striking NYX CORE header.
  • Clear Metadata: An organized grid for essential report details like ID, author, generation date, and feature.
  • At-a-Glance Status: Visually distinct indicators for report status (completed, failed, running).
  • Contextual Badges: Cleanly presented "stat pills" and "provider chips."
  • Interactive Elements: A QR code linking back to the digital source.

This meant moving beyond the constraints of markdown and embracing the full power of HTML and CSS.

The Transformation: Crafting the Header with HTML and CSS

The core of this redesign happened within our src/server/services/report-generator.ts file, specifically in the buildReportHeader() function. We completely refactored it to output structured HTML instead of markdown.

Here's a breakdown of the new header's components and design choices:

  1. Branded Header Bar: At the top, a striking dark gradient bar (#1e1b4b to #312e81) now proudly displays "NYX CORE" in a prominent, stylish font. This immediately establishes the report's origin and professionalism.

  2. Metadata Grid: Below the branding, we implemented a 4-column grid layout using CSS. This provides a clean, organized space for critical information:

    • Report ID
    • Author
    • Generated Date
    • Feature

  3. Dynamic Stat Badges: Key statistics are now presented as inline "pill" badges, making important numbers stand out without cluttering the layout.

  4. Color-Coded Status: A critical UX improvement, the report's status is now clearly color-coded:

    • Green: Completed
    • Red: Failed
    • Purple: Running This allows for immediate comprehension of the report's outcome.

  5. Provider Labels: Any associated providers are displayed as dark, distinct badge chips, providing additional context at a glance.

  6. QR Code Integration: In a footer row within the header, we've included a QR code alongside a direct link. This bridges the physical and digital, allowing users to quickly access the report's interactive version online.

Here's a simplified conceptual example of the HTML structure we're now generating:

html
<div class="nyx-header">
  <div class="nyx-brand-bar">
    <span class="nyx-brand">NYX CORE</span>
  </div>
  <div class="nyx-metadata-grid">
    <div><strong>Report ID:</strong> #12345</div>
    <div><strong>Author:</strong> Jane Doe</div>
    <div><strong>Generated:</strong> 2026-02-27</div>
    <div><strong>Feature:</strong> Data Analysis</div>
  </div>
  <div class="nyx-status-badges">
    <span class="nyx-badge nyx-status-completed">Completed</span>
    <span class="nyx-badge nyx-stat">Items: 120</span>
  </div>
  <div class="nyx-provider-chips">
    <span class="nyx-provider">Provider A</span>
  </div>
  <div class="nyx-footer-row">
    <img src="qr_code_url.png" alt="QR Code" class="nyx-qr-code">
    <a href="report_link_url" class="nyx-report-link">View Report Online</a>
  </div>
</div>

The Backend Glue: Ensuring Print-Ready Styles

Generating beautiful HTML is one thing; ensuring it renders perfectly in a PDF is another. Our PDF generation pipeline uses scripts/md2pdf.py, which leverages Playwright for headless browser rendering. The challenge was to ensure all the new CSS was correctly applied and self-contained for offline viewing.

Our solution involved dynamically injecting the necessary CSS directly into the HTML before PDF generation. In scripts/md2pdf.py, we now:

  1. Read our custom CSS rules for classes like .nyx-header, .nyx-brand, .nyx-badge, .nyx-provider, etc.
  2. Inject this full, inline CSS block directly into the <head> section of the HTML document, right before the </head> tag.

This approach guarantees that:

  • The PDF is entirely self-contained, with all styles embedded.
  • Playwright renders the page precisely as intended, leading to a consistent and high-fidelity PDF output.
  • There's no dependency on external stylesheets, which can be problematic for print-ready documents.

A conceptual look at the Python script's modification:

python
# md2pdf.py
# ... existing markdown to HTML conversion ...

# Our custom CSS to be injected
nyx_styles = """
<style>
  .nyx-header { /* ... gradient, padding ... */ }
  .nyx-brand-bar { /* ... flex, alignment ... */ }
  .nyx-brand { /* ... font, color ... */ }
  .nyx-metadata-grid { /* ... display: grid, gap ... */ }
  .nyx-badge { /* ... background, border-radius ... */ }
  .nyx-status-completed { background-color: #22c55e; } /* green */
  .nyx-status-failed { background-color: #ef4444; } /* red */
  .nyx-status-running { background-color: #a855f7; } /* purple */
  .nyx-provider { /* ... dark background, small font ... */ }
  .nyx-qr-code { /* ... size, margin ... */ }
  .nyx-report-link { /* ... color, text-decoration ... */ }
</style>
"""

# Inject styles into the HTML
html_content = markdown_to_html(markdown_input)
final_html = html_content.replace('</head>', nyx_styles + '</head>')

# Playwright then takes final_html and generates the PDF
# ... playwright.pdf(final_html) ...

Lessons Learned: Smooth Sailing Ahead

One of the most satisfying aspects of this project was the complete lack of major roadblocks. We encountered no significant issues during the implementation. This was largely thanks to a crucial architectural detail: our existing markdown_to_html() function was already designed to preserve raw HTML blocks.

This meant we could simply replace the markdown table content with our new, richly structured HTML, and the pipeline would pass it through without interference. This foresight in the original design saved us from having to implement complex HTML parsing or escaping mechanisms, making the integration seamless.

Furthermore, injecting CSS at runtime proved to be an efficient strategy. It meant no environment variable changes, no new schema updates, and no separate CSS files to manage in deployment. The styles are self-contained within the generation script, simplifying the overall process.

Conclusion: A Polished Look for Critical Insights

The redesigned NYX CORE PDF report header is more than just a visual upgrade; it's a significant improvement in how we present critical information. By leveraging structured HTML and dynamic CSS, we've created a header that is:

  • Visually Stunning: Aligned with NYX CORE's brand identity.
  • Highly Informative: Presenting key metadata and status at a glance.
  • User-Friendly: With color-coded statuses and interactive QR codes.

This project reinforces the idea that even seemingly small UI/UX details, like a report header, can have a profound impact on the perceived professionalism and usability of our systems. We're excited to see these polished reports empower better decision-making across the board.

json
{
  "thingsDone": [
    "Redesigned PDF report header with NYX CORE branding",
    "Replaced markdown table with structured HTML and CSS classes in `buildReportHeader()`",
    "Implemented dark gradient header bar with 'NYX CORE' branding",
    "Created 4-column metadata grid (Report ID, Author, Generated, Feature)",
    "Added stat badges as inline pills with values",
    "Integrated color-coded status (green=completed, red=failed, purple=running)",
    "Included provider labels as dark badge chips",
    "Added QR code + link in footer row",
    "Updated `scripts/md2pdf.py` to inject custom CSS inline before `</head>`",
    "Ensured full inline CSS for print-ready rendering in Playwright"
  ],
  "pains": ["No significant issues encountered, integration was smooth."],
  "successes": [
    "Seamless integration of new HTML/CSS due to `markdown_to_html()` preserving raw HTML blocks",
    "Achieved desired branding and information density for PDF reports",
    "Efficient CSS injection strategy without needing env or schema changes"
  ],
  "techStack": [
    "TypeScript",
    "HTML",