Executive Report Design System

Executive Report Design System

Assemble multi-page HTML executive reports from a closed component catalogue and a frozen stylesheet, so that every report looks like a designer built the template and an analyst filled it in — never like a language model improvised a layout.

When to Use

• User wants a recurring report (QBR, board pack, monthly review) that must look the same every time
• User has data — a CSV, a spreadsheet, a set of figures — and needs it presented, not just tabulated
• User needs a document that prints properly to A4 and survives being emailed or stored in SharePoint
• User explicitly complains that AI-generated documents look generic
• User wants a single self-contained file with no external dependencies

When NOT to Use

• Slide deck → use the pptx skill
• Word document or letter → use the docx skill
• A live dashboard that re-reads changing data → build a SharePoint Framework web part
• One quick chart with no narrative → answer inline instead
• A report where the user wants to choose their own colours and layout — this skill is deliberately not configurable

Quick Start

User: "Build a Q3 executive summary from the attached CSV. Audience is the exec team; the headline is that we beat plan but delivery slipped."

Steps:

1. Ask the seven interview questions below. Do not guess any of them.
2. Read the data. Decide which components tell the story, using the decision table in references/component-catalogue.md.
3. Build the JSON data document. Validate it: python scripts/validate_report.py report.json
4. Render: copy assets/design-system.css into a <style> block and assets/motion.js into an inline <script>, then assemble pages from assets/component-snippets.md.
5. Lint the output: python scripts/check_output.py report.html
6. Fix anything the linter flags. Do not hand over a report that fails the lint.

The One Rule

You are not designing. You are assembling.

The design already exists, in assets/reference-report.html. Your job is to pick the right blocks from a fixed catalogue, fill them with the user's data, and emit the file. You do not get a vote on colour, type, spacing or layout.

If you find yourself writing a new CSS rule, you have gone wrong. Stop and pick a different component.

Why This Skill Exists — The Anti-Generic Problem

Left alone, a language model produces a recognisable house style: a centred hero, three or four identical cards with emoji, a purple-to-blue gradient, rounded corners everywhere, Inter at 16px, generous uniform padding, a Key Insights heading, bullet lists of three, and a footer saying Generated by AI.

Everybody has seen it. It reads as a template, and it quietly tells the reader that nobody spent any time on this. For an executive audience that is an own goal — the document undermines its own content.

This design system is opinionated in the specific ways a generic generator never is:

The full ban list, with rationale, is in references/anti-generic-rules.md. scripts/check_output.py enforces the mechanical parts of it.

The test: a reader should assume a designer made the template and an analyst filled it in. Nothing about the output should suggest a machine chose the layout.

How It Works

The three layers

Only one of them changes per report. This is what makes the output deterministic.

  STYLE          CSS custom properties. Four palette classes.        never changes
                 Set one on .page; every colour resolves through it.

  COMPONENTS     A closed catalogue of named blocks. The skill        never changes
                 picks which and in what order. It never invents one.

  DATA           A validated JSON document. Every value, every        changes per report
                 label, every block choice lives here.

Same JSON in, same HTML out. If a report needs regenerating six months later, the JSON reproduces it exactly.

The authoring pipeline

  START      Beautiful HTML example        assets/reference-report.html      once
  EXTRACT    Design read into tokens       assets/design-system.css          once
  CODIFY     Catalogue + rules             SKILL.md + references/            once
  ─────────────────────────────────────────────────────────────────────────────
  EVERY TIME User sends prompt + data      "build a Q3 QBR from this CSV"
  OUTPUT     Validated JSON document       scripts/validate_report.py
  RESULT     Self-contained HTML           scripts/check_output.py

The first three steps are already done — they are this package. In use, the whole interaction is a two-line prompt and a data file.

Page model

Every page is a fixed A4 landscape box containing exactly three children:

<section class="page palette-warm-paper" id="p3">
  <div class="page-head">
    <span class="wordmark">Contoso</span>
    <span class="page-meta">Q3 Executive Summary &middot; Exec Team</span>
  </div>

  <div class="page-body stack gap-lg">
    <!-- three to five components -->
  </div>

  <div class="page-foot">
    <span>Contoso &middot; Q3 executive summary</span>
    <span>Page <span class="pageno"></span> of 9</span>
  </div>
</section>

Content must fit. Nothing scrolls, nothing spills. If a page overflows, move a block to the next page — never shrink the type to make it fit.

Running heads and feet are real elements repeated on every page. This is deliberate and non-negotiable: @page margin boxes are still unsupported in Chromium, and position: fixed does not repeat per page outside Firefox. In-DOM is the only approach that prints identically in Edge, Chrome, Firefox and Safari. See references/pagination-rules.md before changing anything about printing.

Motion

Figures count up with an ease-out quint curve, bars sweep out, the trend line draws itself, and cards rise in with a short stagger, triggered per page as it scrolls into view. You do not write this and you do not configure it — just do not break it:

• The engine reads the final text already in the HTML, replays the arrival, then writes the identical string back. Write real values into the markup: $1.9M, never a placeholder or a zero.
• Prefixes and suffixes survive: $1.9M counts through $1.3M, 4/8 counts through 2/8, +18.4% keeps its sign and decimal.
• Bar widths are authored inline (style="width:61%"). The engine parks them at zero and hands the value back.
• prefers-reduced-motion is honoured, and everything snaps to final on beforeprint, so paper never catches a half-counted number.

Hard Constraints

These come from the report having to survive being emailed, stored in SharePoint, and opened on a machine with no internet.

scripts/check_output.py verifies all of these mechanically.

Procedure

1. Interview

Ask all seven. Do not guess, and do not proceed on assumptions:

1. What is the report, and who reads it?
2. What period does it cover?
3. What is the single most important finding? (this becomes the hero sentence)
4. What are the three or four headline numbers?
5. What decision, if any, do you need from the reader?
6. Organisation name for the wordmark, and any classification label?
7. Which palette? (default to palette-warm-paper)

2. Build the JSON

Against references/report.schema.json. Content, component choice and palette token only — no geometry, no hex colours, no pixel values. Those live in the frozen stylesheet, and keeping them out of the data is what prevents drift.

3. Validate

python scripts/validate_report.py report.json

If it does not validate, fix the JSON. Do not render around a validation failure.

4. Render

Copy the frozen blocks unaltered. Assemble pages from assets/component-snippets.md. Write real final values into the markup.

5. Lint

python scripts/check_output.py report.html

Fix everything it flags before handing over.

Choosing Components — The Decision Table

Do not deliberate. Match the shape of the data:

Emphasis is rationed. At most one .is-emphasis and one .risk-callout per page. If everything is emphasised, nothing is.

Full class inventory: references/component-catalogue.md.

Page Order

Give a page three to five components. Two looks thin; seven looks like a dashboard. Use grow on the last block so a page never ends in a void.

Writing the Words

The prose is half of why this does not look machine-made.

• Headings state findings, not topics. Not "Delivery Status" but "Eight active initiatives, four fully on track".
• The hero sentence is one sentence with two or three figures in .accent. It should survive being read aloud.
• Captions earn their place. "10 deals closed" is useful. "Total revenue" under a card labelled Total Revenue is not.
• Red captions mean risk. .kpi-note.is-alert for "2 at risk · 1 blocked". Never for good news.
• British English. Optimise, prioritise, organisation.
• No hedging. "Legal review has run eleven weeks", not "There may be some potential delays in the legal review process".
• Numbers in prose match the cards exactly. Never restate a figure differently.

Files in This Package

Troubleshooting

Self-Check Before Handing Over

• python scripts/check_output.py report.html passes
• Frozen CSS and JS copied unaltered; no CSS rule added, no class invented
• Every page fits — nothing overflows past the running foot
• Every page has head, body and foot; the page total is written in
• Cover and executive summary present; contents page numbers correct
• Every figure appears in the markup as its final text
• Red used only for meaningful figures and genuine risk
• Charts with more than one style have a legend
• Headings state findings, not topics
• Opens correctly with JavaScript disabled