docs: add editor hero, live-demo link, social card, and "Why Apollon" - #823
Conversation
…#750) The shop window for a visual editor had no visuals: the READMEs showed only badges, the demo link was buried, and repo links unfurled without an image. - New "readme-assets" Playwright project generates the public-facing assets straight from the live editor (same one-source-of-truth pattern as howto-assets): README hero screenshots (light + dark, 2x) and a 1280x640 GitHub social preview card, written to docs/static/img/ and diff-gated by the per-PR visual job so they can never drift from the real editor. - Root README: centered header with a "Try the live demo" link row, a dark/light <picture> hero linked to the demo, and a "Why Apollon" section for people arriving from outside Artemis. - library/README.md (the npm page) embeds the hero via an absolute raw.githubusercontent URL, with a patch changeset so it ships on the next publish. - docs site: themeConfig.image now points at the generated social card (closing the "dedicated card would render better" TODO in the config); visual-tests.md documents the generated-assets projects. - update-visual-baselines.yml stages the new asset paths so the container workflow keeps them canonical. Uploading the social preview in repo Settings remains a manual maintainer step (GitHub has no API for it). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claudia-Anthropica
left a comment
Claudia-Anthropica
left a comment
There was a problem hiding this comment.
@FelixTJDietrich The README and generated-asset workflow look good, and the visual/docs checks are clean. I left one low-priority note about the hero’s effective pixel density; approving overall.
| // high-DPI displays. The social-card test overrides both to hit | ||
| // GitHub's exact 1280×640 spec. | ||
| viewport: { width: 1440, height: 810 }, | ||
| deviceScaleFactor: 2, |
There was a problem hiding this comment.
@FelixTJDietrich [low] Playwright’s toHaveScreenshot() defaults to scale: "css", so this DPR 2 setting is downscaled to one output pixel per CSS pixel; both committed heroes are 1440×810 rather than genuine 2× files, despite the comment claiming Retina output. Pass scale: "device" for the two hero assertions and regenerate the assets if the intent is to ship a high-DPI hero.
🤖 Prompt for AI agents
In standalone/webapp/tests/visual/readme-assets.visual.spec.ts, the hero assertions use Playwright’s default CSS-pixel screenshot scale, so deviceScaleFactor: 2 in standalone/webapp/playwright.config.ts does not produce 2× image files. Set scale: "device" on both hero toHaveScreenshot() calls, regenerate the two hero PNGs, and update any documented pixel dimensions.
There was a problem hiding this comment.
Correct at the time — the default scale: "css" was silently halving the DPR-2 renders. Fixed in 047aede: both hero assertions (and the header widgets) now pass scale: "device", and the committed heroes are 3136×1964 (2×).
- Align the Diagram - Element - Selectable spine so both edges render as single straight horizontal segments (anchors quantize slightly off the node center, so Element/Selectable are offset by the measured half-pixel deltas), and place Node/Edge symmetrically under Element with equal horizontal gaps across the middle row. - Social card now embeds the light editor on a light card: matches the editor default and reads brighter in link unfurls. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claudia-Anthropica
left a comment
Claudia-Anthropica
left a comment
There was a problem hiding this comment.
@FelixTJDietrich The refreshed hero layout and light social card look good, and the generated assets remain covered by the passing visual and docs checks. Approving the new commit.
- The social card embedded a 1280px editor screenshot into a 760px img — a fractional (0.59x) browser downscale that resampled the diagram's 1px lines into visibly stepped/broken runs. Capture at 1520x760 instead, so the 760px embed is an exact 0.5x integer downscale and the spine edges render as clean straight lines. - Feature-claim audit against the source: UMLDiagramType has exactly 13 entries (claim was right), but the standalone web app's File menu also exports PPTX (useExportAsPPTX/svgToPptx) which no marketing surface mentioned. Add PPTX to the root README tagline, the social card facts line, the docs landing hero + export feature card, and the user-guide overview. Library-scoped docs stay SVG/PNG/PDF/JSON on purpose - PPTX lives in the web app, not the npm package. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claudia-Anthropica
left a comment
Claudia-Anthropica
left a comment
There was a problem hiding this comment.
@FelixTJDietrich The social-card recapture fixes the line resampling cleanly, and the PPTX wording is accurate about the webapp-specific export. The generated asset dimensions and focused lint/format checks look good, so I’m approving the new commit.
Bare full-viewport screenshots read as a flat rectangle in the README. Wrap the captured editor in the same window styling the social card uses - rounded corners, titlebar with traffic lights, border, soft drop shadow - over transparent margins, so the hero sits cleanly on both GitHub's light and dark README backgrounds. The frame embeds the 2x capture at its CSS size in the same deviceScaleFactor-2 context (1:1 source pixels, no fractional resampling of diagram hairlines). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 80px-blur shadow exceeded the 56px transparent margin and was cut off at the image edges. Reduce the shadow to 0 16px 44px at lower alpha and widen the margin to 64px, which fully contains the shadow's reach. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claudia-Anthropica
left a comment
Claudia-Anthropica
left a comment
There was a problem hiding this comment.
@FelixTJDietrich The browser-window framing and softened shadow look clean in both generated hero assets, and the visual/docs checks pass on the current commit. Approving the new commit.
Generated, cohesive header widgets from the same readme-assets pipeline:
- apollon-lockup-{light,dark}.png: icon + Inter wordmark replacing the
plain-text h1, swapped per GitHub color scheme via <picture>.
- apollon-btn-demo-*.png / apollon-btn-docs-*.png: call-to-action buttons
(filled accent + outline) using the webapp's design tokens
(--primitive-accent-base #0f3a66 light / #236ebe dark), linked to the
live demo and the docs site.
- All hero/widget snapshots now capture at scale: "device" (the default
"css" scale was silently halving the deviceScaleFactor-2 renders), so
the README images are retina-crisp; widgets display at half size via
height attributes.
- update-visual-baselines.yml stages docs/static/img/apollon-*.png as one
glob; visual-tests.md documents the widgets.
Follows GitHub's prefers-color-scheme <picture> guidance and common
practice from top OSS READMEs (product shot in the first screenful,
grouped badges, framed window mockup).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
lint-staged's prettier pass reflowed the inline <a><picture> chain and injected a blank line inside the first <picture>, which can split the HTML block in GitHub's markdown. Use a plain nested HTML block instead, which prettier leaves unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claudia-Anthropica
left a comment
Claudia-Anthropica
left a comment
There was a problem hiding this comment.
@FelixTJDietrich The Retina asset pipeline and README markup changes look solid, and the focused visual, formatting, and lint checks pass. I left one low-priority note about the badge row’s GitHub rendering; approving overall.
| </picture> | ||
|
|
||
| [](https://www.npmjs.com/package/@tumaet/apollon) | ||
| [](https://www.npmjs.com/package/@tumaet/apollon) |
There was a problem hiding this comment.
@FelixTJDietrich [low] Because these badge links are each on their own line inside the raw <div>, GitHub’s GFM renderer inserts <br> elements between them and displays a vertical stack instead of a grouped badge row. Put all three badge links on one Markdown line, or use one HTML <p> with adjacent anchors.
🤖 Prompt for AI agents
In README.md, the three badge links on lines 8–10 render as separate rows because each Markdown link is on its own line inside the raw centered <div>. Make the badges render horizontally by putting the three Markdown badge links on one line or replacing them with a single HTML paragraph containing adjacent linked images.
There was a problem hiding this comment.
Checked against GitHub's actual rendering (GET /repos/.../readme with Accept: application/vnd.github.html on this branch): all three badge anchors land in a single <p dir="auto"> with no <br> between them — they render as one horizontal row. Newline-as-hard-break is comment-mode markdown; file/README mode treats single newlines as soft breaks (spaces), even inside the centered <div>. Leaving the one-badge-per-line source as is, since it renders grouped and diffs cleaner.
npmjs.com strips GitHub's <picture> theme swap and img width/height sizing, so the npm README cannot reuse the 2x header widgets. Emit dedicated 1x light-button variants (scale: "css") from the same readme-assets project and embed them with plain markdown image syntax at natural size — self-contained backgrounds keep them readable on npm's dark theme too. Trim the text link row to what the buttons don't cover and fold the hero into the same npm-safe comment block. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2 participants
Closes #750
For a visual editor, the repo's shop window had no visuals: the READMEs showed only badges, the live demo was easy to miss, and repo links unfurled without an image. (The feature-request template and issue-chooser config from the issue checklist already landed earlier, so this PR covers the rest.)
What changed
Generated, never hand-made assets. A new
readme-assetsPlaywright project generates every public-facing image straight from the live editor — the same one-source-of-truth pattern ashowto-assets. It renders a curated showcase fixture (readme-hero.json, a class diagram of Apollon's own domain model) and writes todocs/static/img/:apollon-editor-light.png/apollon-editor-dark.png— README hero, 1440×810 @2×apollon-social-card.png— GitHub social preview, exactly 1280×640 (2:1, well under the 1 MB limit), composed in-page with the repo's bundled Inter fonts and logo so it renders identically on any machineThe per-PR visual job diff-gates all three, so the marketing images can never silently drift from the real product.
update-visual-baselines.ymlstages the new paths, so the canonical-container refresh flow covers them too.README (repo front page). Centered header with a ▶ Try the live demo link row, a dark/light
<picture>hero linked to the demo, and a "Why Apollon / who it's for" section for people arriving from outside Artemis.npm page.
library/README.mdnow embeds the hero via an absoluteraw.githubusercontent.comURL (relative paths don't resolve on npmjs.com), with a patch changeset so it ships on the next publish.Docs site.
themeConfig.imagenow points at the generated social card — closing the existing config TODO ("a dedicated 1200×630 card would render better in social embeds") — so docs links unfurl with the card as well.visual-tests.mddocuments the generated-assets projects.Preview
Manual step for a maintainer (no GitHub API exists for this)
Upload
docs/static/img/apollon-social-card.pngunder Settings → General → Social preview. Re-upload whenever the card regenerates.Verification
pnpm exec playwright test --project readme-assetspasses both with and without--update-snapshots(stable diff).og:image(https://ls1intum.github.io/Apollon/img/apollon-social-card.pngin the built HTML).References: GitHub social preview spec (1280×640, 2:1, <1 MB) per GitHub's social preview guidance; dark/light
<picture>README images per the GitHub blog.🤖 Generated with Claude Code