Skip to content

Polish exports: logo card on Band covers, readable PDF callouts, no stranded callouts - #325

Merged
Twest2 merged 2 commits into
fix/rich-text-word-pptxfrom
fix/export-polish
Nov 17, 2026
Merged

Twest2 merged 2 commits into
fix/rich-text-word-pptxfrom
fix/export-polish

Conversation

@Twest2

@Twest2 Twest2 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Issue

No issue filed. Builds on #324 (this PR's base is that branch); merge #324 first and this one retargets to main.

Summary

These are the smaller fixes from the same review of every export format:

  • A dark logo disappeared on the Brand color band cover in PDF, Word, HTML and the GIF title card. It now sits on a white card there, as it already did in PowerPoint. The card appears only when the logo needs it: when more than a quarter of the logo's pixels contrast with the band by less than 3:1, the WCAG minimum for graphics.
  • PDF callout labels were hard to read. "Warning" in amber on cream was about 2:1, and "Tip" in green on pale green was not much better. They now use darker shades, all at least 4.5:1 (amber is 4.8:1), like Word, HTML and Markdown.
  • PDF could strand a callout on a page of its own, away from the screenshot it follows. Short callouts after a screenshot now stay on the screenshot's page; the screenshot moves to the next page with them when they don't both fit.
  • The GIF title card said "6 steps" for a 7-step guide. It counted only steps with a screenshot, while the frames kept their real step numbers. It now counts every step.
  • Word code blocks had no padding, and tables filled only part of the page. Code blocks are now padded. Tables span the page (or their side-by-side column) and have a shaded header row.
  • HTML:
    • Callouts placed after a step title sat flush left, while the rest of the step was indented. They now sit in the step body.
    • On a phone, the step number was centered against a long wrapped title. It now lines up with the first line.

Changes

  • exporters/branding.js:
    • luminance, contrast, logoNeedsCard and coverLogo. coverLogo returns the logo itself, or the logo drawn on a white rounded card with padding.
    • exporters/pptx.js drops its own copies and uses these.
  • exporters/pdf.js:
    • The band cover uses coverLogo.
    • The callout styles have a separate darker label color.
    • drawImage takes a keepWith height: the height of the callouts right after the screenshot, when they're short (under about a third of a page).
  • exporters/docx.js:
    • The band cover uses the carded logo (brand-logo-card.png).
    • New codeBoxProps: borders in the code block's own fill color, set off from the text, pad the box, and an indent keeps the padding inside the text column.
    • table() is 100% of its container, with a shaded header row.
    • The page-break estimate understands percentage cell widths.
  • exporters/html.js:
    • An on-card class on the header logo, styled as a white card.
    • Callouts placed after the title render inside .step-body.
    • .step-head aligns to the top.
  • exporters/gif.js:
    • The band title card uses the carded logo, checked against the band's actual color, since the Export dialog can change it.
    • New titleCardMeta(ast) counts every step.
  • tests/unit/export-polish.test.js (new):
    • The logo card check and drawing.
    • Carded logos in the PDF, Word, HTML and GIF outputs.
    • The GIF step count.
    • Every PDF label color.
    • A guide whose screenshots fall at every height on a page, checked so that no callout starts a page away from its screenshot.
    • Word code-block padding and table width.
    • HTML callout placement and step-head alignment.
    • The PDF tests and the logo-card test fail against Keep step text formatting in Word and PowerPoint exports #324's exporters.
  • docs/BRANDING.md: a note on the logo card.

Area

  • Exports
  • Branding
  • Documentation
  • Tests

Testing

  • bash tests/run_test.sh passes
  • Tested manually (described below)

bash tests/run_test.sh was not run. npm test passes: 1,665 tests, 1,639 passed, 0 failed, 26 skipped. tests/e2e/exports.test.js passes on a private Xvfb display, and npm run translations lists nothing missing.

Checked on Ubuntu 26.04:

  • PDFs are rendered with Poppler.
  • Word files are converted with LibreOffice 26.2.
  • HTML is screenshotted in Electron's Chromium at 1280 px and at 390 px (phone width).
  • GIF frames are decoded with the repository's test decoder.

The Word file has not been opened in Microsoft Word yet.

Screenshots or recordings

All from the same guide, exported on main and on this branch.

Band covers, left to right: PDF, Word, GIF title card, HTML. On main the dark wordmark nearly disappears, and the GIF says 6 steps:

Before After
before after

PDF callout labels:

Before After
before after

The PDF's last two pages. On main, the "Escalate" callout is alone on the last page; now the screenshot moves there with it:

Before After
before after

Word code block and table:

Before After
before after

HTML at phone width, with a long step title:

Before After
before after

Rollout notes

None.

Checklist

  • Linked to an issue above
  • Scope is limited to that issue
  • New behavior has tests that check real output
  • Docs updated for anything users will notice
  • New interface text is in t(), and npm run translations lists nothing missing
  • Anything that still needs manual verification is listed above
  • No new network calls, dependencies, or third-party branding
  • Follow-up work is tracked in an issue

…tranded callouts

- A logo that wouldn't show up on the Band cover's color (more than a quarter
  of its pixels under 3:1 against it, the WCAG minimum for graphics) sits on
  a white card in PDF, Word, HTML and the GIF title card, as it already did in
  PowerPoint. The check and the carded drawing are shared in
  exporters/branding.js, and PowerPoint now uses them too.
- PDF callout labels use a darker shade of their color, at least 4.5:1 on the
  tint (amber on cream was about 2:1), like Word, HTML and Markdown.
- PDF keeps short callouts placed after a screenshot on the screenshot's page,
  so one no longer starts the next page on its own.
- The GIF title card counts every step, not just those with a screenshot, so
  the total matches the step numbers on the frames.
- Word code blocks have padding; tables span the text (or column) width with
  a shaded header row.
- HTML: callouts placed after a step title sit in the step body with the rest
  of the step, and the step number lines up with the first line of a long
  title.
@Twest2

Twest2 commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T19:13:00.503157Z 819d321 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 819d321abd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread exporters/branding.js Outdated
Comment on lines +135 to +136
raster.fillRoundRect(card, 0, 0, card.width, card.height, Math.round(pad * 0.9), [255, 255, 255, 255]);
raster.drawImage(card, img, pad, pad);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Check logo contrast against the card before making it white

For a transparent white logo on a light band such as #AAAAAA, the contrast check requests a card, but drawing the logo onto this white background makes it disappear completely. I reproduced this with coverLogo: it returns carded: true, and the opaque logo pixels become indistinguishable from the card, whereas the original logo had approximately 2.32:1 contrast against the band. This newly affects PDF, Word, HTML, and GIF band covers. Choose a card color that contrasts with the logo, or retain the original background when a white card would reduce contrast.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 62674d6: the card is now white or dark slate, whichever the logo contrasts with better, and there is no card when neither beats the band. The PowerPoint picture-cover card follows the same choice. Regression test uses a white logo on #AAAAAA.

A logo that was faint on the band always got a white card, so a white
logo on a light band (#AAAAAA, say) vanished into its card. The card is
now white or dark slate, whichever the logo stands out on, and is left
off when neither would make the logo clearer than the band itself. The
PowerPoint picture cover's card follows the same choice.
@Twest2
Twest2 merged commit 18ca034 into fix/rich-text-word-pptx Nov 17, 2026
9 of 10 checks passed
Twest2 added a commit that referenced this pull request Nov 17, 2026
Polish exports: logo card on Band covers, readable PDF callouts, no stranded callouts (land #325 on main)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant