docs: add editor hero, live-demo link, social card, and "Why Apollon" (#823)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/proud-donkeys-shine.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": patch
+---
+
+Polish the npm README: an editor screenshot in a browser-window frame plus "Try the live demo" / "Documentation" buttons, so the package page shows the product, not just badges. All images are generated from the live editor by the `readme-assets` Playwright project and hosted from the repository, using npm-safe plain markdown images (npmjs.com strips GitHub's `<picture>` theme swap and img sizing attributes).

.github/workflows/update-visual-baselines.yml

@@ -63,10 +63,12 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           # Scope strictly to generated snapshot PNGs so a render bug can't
           # smuggle other tree changes back onto the branch. The how-to-use modal
-          # assets are regenerated by the same run (howto-assets project) but land
-          # under assets/images/, not a *-snapshots dir, so stage them explicitly.
+          # assets and the README/social-card assets are regenerated by the same
+          # run (howto-assets + readme-assets projects) but land outside the
+          # *-snapshots dirs, so stage them explicitly.
           git add 'standalone/webapp/tests/**/*-snapshots/*.png' \
-            'standalone/webapp/assets/images/how-to-use-*.png'
+            'standalone/webapp/assets/images/how-to-use-*.png' \
+            'docs/static/img/apollon-*.png'
           if git diff --cached --quiet; then
             echo "Baselines already match — nothing to commit." >> "$GITHUB_STEP_SUMMARY"
             exit 0

README.md

@@ -1,9 +1,51 @@
-# Apollon
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/static/img/apollon-lockup-dark.png" />
+  <img src="docs/static/img/apollon-lockup-light.png" alt="Apollon" height="84" />
+</picture>
 
 [![npm version](https://img.shields.io/npm/v/@tumaet/apollon)](https://www.npmjs.com/package/@tumaet/apollon)
+[![npm downloads](https://img.shields.io/npm/dm/@tumaet/apollon)](https://www.npmjs.com/package/@tumaet/apollon)
 [![npm license](https://img.shields.io/npm/l/@tumaet/apollon)](./LICENSE)
 
-Apollon is an open-source UML modeling editor for the web. Draw 13 UML and modeling diagram types (class, component, activity, BPMN, SFC, and more) in the browser, collaborate in real time, and export to SVG, PNG, PDF, or JSON.
+**Open-source UML modeling editor for the web.** Draw 13 UML and modeling diagram types (class, component, activity, BPMN, SFC, and more) in the browser, collaborate in real time, and export to SVG, PNG, PDF, PPTX, or JSON.
+
+<p>
+  <a href="https://apollon.aet.cit.tum.de">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/static/img/apollon-btn-demo-dark.png" />
+      <img src="docs/static/img/apollon-btn-demo-light.png" alt="Try the live demo" height="64" />
+    </picture>
+  </a>
+  <a href="https://ls1intum.github.io/Apollon/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/static/img/apollon-btn-docs-dark.png" />
+      <img src="docs/static/img/apollon-btn-docs-light.png" alt="Documentation" height="64" />
+    </picture>
+  </a>
+</p>
+
+[npm package](https://www.npmjs.com/package/@tumaet/apollon) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=aet-tum.apollon-extension)
+
+<a href="https://apollon.aet.cit.tum.de">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/static/img/apollon-editor-dark.png" />
+    <img src="docs/static/img/apollon-editor-light.png" alt="The Apollon editor showing a UML class diagram, with the element palette on the left and the app chrome on top" />
+  </picture>
+</a>
+
+</div>
+
+## Why Apollon
+
+- **Made for learning and teaching.** Apollon powers the UML modeling exercises and grading workflows in [Artemis](https://artemis.tum.de/), TUM's interactive learning platform, and holds up in large university courses — but it is a general-purpose editor that works just as well outside the classroom.
+- **Embeddable first.** The editor is an npm library with an imperative API (plus a React component); the standalone web app and the VS Code extension in this repo are built on top of it. If you need diagramming inside your own product, you embed the exact editor you see in the demo.
+- **Framework-agnostic.** One API works from Angular, Vue, Svelte, vanilla JS, or React.
+- **Real-time collaboration built in.** Opt-in multi-user editing over [Yjs](https://yjs.dev/), with any transport you like.
+- **MIT-licensed and self-hostable.** No account, no cloud dependency — run the whole stack yourself.
+
+## What's in this repo
 
 This monorepo contains every piece of the Apollon platform:
 

docs/contributor/development/visual-tests.md

@@ -41,6 +41,22 @@ cd standalone/webapp
 pnpm exec playwright test tests/visual/svg-export --update-snapshots
 ```
 
+## Generated UI assets
+
+Two Playwright projects double as asset generators — their baselines **are** the shipped files, so the images can never drift from the real editor:
+
+- `howto-assets` writes the "How this editor works" modal images to `standalone/webapp/assets/images/`.
+- `readme-assets` writes the README hero screenshots (`apollon-editor-light.png`, `apollon-editor-dark.png`), the README header widgets (`apollon-lockup-*.png`, `apollon-btn-*.png` — brand lockup and call-to-action buttons, per color scheme), and the 1280×640 social preview card (`apollon-social-card.png`) to `docs/static/img/`. These are referenced by `README.md`, `library/README.md` (the npm page), and `themeConfig.image` in `docs/docusaurus.config.ts`.
+
+Both regenerate through the same baseline-refresh flows above, or individually:
+
+```sh
+cd standalone/webapp
+pnpm exec playwright test --project readme-assets --update-snapshots
+```
+
+One manual step remains: GitHub has no API for the repository social preview, so after `apollon-social-card.png` changes, a maintainer re-uploads it under **Settings → General → Social preview**.
+
 ## Triage
 
 If `visual-regression-tests` fails on a PR, download the `playwright-report-visual` artifact from the run, open `playwright-report/index.html` locally, and inspect the actual-vs-expected diff before deciding whether to refresh the baseline (intentional UI change — see above) or fix the regression (unintended).

docs/docusaurus.config.ts

@@ -141,9 +141,10 @@ const config: Config = {
   ],
 
   themeConfig: {
-    // Link-unfurl preview image. The logo works; a dedicated 1200×630 card
-    // would render better in social embeds.
-    image: "img/logo.png",
+    // Link-unfurl preview image: the 1280×640 social card generated from the
+    // live editor by the "readme-assets" Playwright project (see
+    // standalone/webapp/tests/visual/readme-assets.visual.spec.ts).
+    image: "img/apollon-social-card.png",
     colorMode: {
       respectPrefersColorScheme: true,
       disableSwitch: false,

docs/src/pages/index.tsx

@@ -100,9 +100,9 @@ function Hero() {
           browser.
         </h1>
         <p className={styles.heroSubtitle}>
-          An open-source UML modeling editor. 13 diagram types, SVG/PNG/PDF/JSON
-          export, real-time collaboration. Use it in the browser, in VS Code, or
-          as an npm library.
+          An open-source UML modeling editor. 13 diagram types,
+          SVG/PNG/PDF/PPTX/JSON export, real-time collaboration. Use it in the
+          browser, in VS Code, or as an npm library.
         </p>
         <div className={styles.buttons}>
           <Link className="button button--primary button--lg" href={HOSTED_URL}>
@@ -286,7 +286,7 @@ const FEATURES = [
   {
     kicker: "Output",
     title: "Export anywhere",
-    body: "SVG, PNG, PDF, and JSON — from a mounted editor or a headless model. Round-trips through JSON without loss.",
+    body: "SVG, PNG, PDF, and JSON — from a mounted editor or a headless model; the web app adds PPTX slides. Round-trips through JSON without loss.",
   },
   {
     kicker: "Collaboration",