docs(site): redesign the docs site and demo pages

.claude/skills/add-feature-demo/SKILL.md

@@ -6,8 +6,8 @@ description: Use this skill when adding a new feature to the engine.
 # Add a Demo
 
 `documentation-site/src/pages/demos/<name>/` holds interactive, in-browser
-demos of engine features, each rendered through
-`documentation-site/src/components/Demo.tsx`. Read `AGENTS.md`'s
+demos of engine features, each rendered through `DemoPage`
+(`documentation-site/src/components/demo-page/`). Read `AGENTS.md`'s
 "Documentation Site Demos" section first for the `file:..`/`dist` gotcha
 that governs how demos are verified — it applies to every demo, new or
 existing.
@@ -57,8 +57,8 @@ Follow the existing file split, every demo uses the same shape:
   `_create-boundaries.ts` from `_spawn-shapes.ts`, not into one monolithic
   file — each file also becomes its own tab in the demo's code viewer (see
   step 3).
-- `index.tsx` — the page itself, a thin wrapper around `<Demo>` (see step
-  3).
+- `index.tsx` — the page itself, a thin wrapper around `<DemoPage>` (see
+  step 3).
 
 Demo-only components/systems (input handling for interaction, camera
 follow, reset-on-key, etc.) still follow the engine's own component/system
@@ -71,59 +71,93 @@ instead of `/src` because they're not part of the public API.
 import React, { JSX } from 'react';
 import { create<PascalName>Game } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
-import someOtherCode from '!!raw-loader!./_some-other-file';
+import thingSystemCode from '!!raw-loader!./_thing.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function <PascalName>(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: '<Human Title> Demo',
-        description: 'A demo showcasing <what it shows>.',
-      }}
-      header="<Human Title>"
-      blurb="<1-3 sentences: what the demo shows, what the engine feature
-        does, and how to interact with it (click/drag/keys) if applicable.>"
+    <DemoPage
+      slug="<kebab-case-name>"
       createGame={create<PascalName>Game}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'some-other-file.ts', content: someOtherCode },
+      controls={[
+        { inputs: ['←', 'A'], action: 'Move left' },
+        { inputs: [{ device: 'mouse', label: 'Click' }], action: 'Select' },
+      ]}
+      highlights={[
+        {
+          text: '<One short sentence on what the engine does here.>',
+          file: 'thing.system.ts',
+        },
+      ]}
+      docLinks={[{ label: '<Guide>', to: '/docs/docs/<module>/<page>' }]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: '<One sentence on what the file does.>',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: '<Feature>',
+          files: [
+            {
+              name: 'thing.system.ts',
+              summary: '<One sentence.>',
+              content: thingSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
 }
 ```
 
-Each `codeFiles` entry drives one tab in the demo's live code viewer, so
-list every demo-source file the reader would need to fully understand the
-scene, in the order that makes it easiest to follow (usually `game.ts`
-first, since it's the entry point). Import each via `!!raw-loader!` exactly
-like `gameCode` — this is what pulls the raw source text in at build time,
-not the compiled/imported binding.
-
-If the demo needs live interaction controls beyond canvas input (a slider,
-a toggle button), pass a React node via `interactions` — see
-`space-shooter/index.tsx` and `_BloomControls.tsx` for the pattern of a
-small controls component alongside the demo files.
-
-## 4. Wire it into the navbar
-
-Add an entry to the `Demos` dropdown in
-`documentation-site/docusaurus.config.ts` (currently around line 114),
-alphabetical-ish grouping isn't strictly enforced but new entries are
-generally added near thematically similar ones (physics demos are grouped
-together, etc.):
-
-```typescript
-{
-  to: 'demos/<kebab-case-name>',
-  label: '<Human Label>',
-},
-```
-
-This is the only place demos are registered/linked — there's no separate
-index page or sidebar to update.
+The page's title and one-line summary come from the demo's entry in
+`documentation-site/src/data/demos.ts` (step 4), so the catalogue card and
+the page always agree. Write the rest for a reader who has never seen the
+feature:
+
+- `controls`: one row per action, with alternative inputs in the same
+  row. Check each binding against the demo's input code. Leave it out for
+  a demo you only watch.
+- `highlights`: 3-5 "How it works" points, one short sentence each, each
+  linked to the file that implements it. Clicking the link opens that file
+  in the code explorer.
+- `docLinks`: the guides under `documentation-site/docs/docs` that cover
+  the feature (`/docs/docs/<path>`, a folder's `index.md` is
+  `/docs/docs/<folder>`).
+- `fileGroups`: every demo-source file a reader needs, grouped by purpose,
+  with `create-game.ts` alone under "Start here". Name each after its
+  source file without the leading underscore, and keep the
+  `.component.ts`/`.system.ts` suffixes: the explorer's type icons and
+  filter come from them. Import each via `!!raw-loader!` exactly like
+  `gameCode`, which pulls in the raw source text at build time.
+- **Never list React or other framework code** (`.tsx`/`.jsx`) in
+  `fileGroups`. The explorer shows engine code a reader can reuse in their
+  own game; a settings panel that only exists to drive this site's page
+  isn't that. `DemoPage` throws if a `.tsx`/`.jsx` file is listed.
+
+If the demo needs something else beside the game, such as live settings (a
+slider, a toggle) or a legend for colors in the scene, pass it as `panels`,
+wrapped in `DemoPanel` (with `DemoLegend` for a legend). Build live
+settings from `DemoSettings`, `DemoSlider`, `DemoToggle`, `DemoChoice` and
+`DemoTextField`. Keep the game-side logic the panel changes in a plain
+`.ts` file (shown in the explorer) and the React panel itself out of the
+explorer. See `text/index.tsx` and `easing-functions/index.tsx`.
+
+## 4. Add it to the demo catalogue
+
+Add an entry to `documentation-site/src/data/demos.ts` with the demo's
+`slug` (its directory name), `title`, a one-sentence `description` (what
+you see or do, and which feature it shows; it's the page's summary too) and
+the category slugs it belongs to. See AGENTS.md's "Demo Catalogue and
+Categories" section.
 
 ## 5. Verify
 
@@ -138,23 +172,14 @@ verification checklist:
    already-built, unchanged API).
 2. From `documentation-site/`: `npm run typecheck`, then `npm run build`
    (`docusaurus build`) — this is what actually catches a broken import
-   against the published package surface or an MDX/broken-link error from
-   the navbar entry.
+   against the published package surface or a broken `docLinks` entry.
 3. `npm run start` in `documentation-site/` (or reuse a running dev
    server), open `demos/<kebab-case-name>` in a browser with a full page
    reload (fast refresh doesn't guarantee a clean re-init), and confirm it
-   renders and behaves correctly — click through any interactions the
-   `blurb` describes.
-4. **Also click the entry from the actual "Demos" navbar dropdown** - don't
-   only visit the URL directly. Adding the array entry in step 4 above is
-   necessary but not sufficient: the dropdown has grown to ~30 entries and
-   its `.dropdown__menu` is capped to the viewport height with internal
-   scrolling (`documentation-site/src/css/custom.css`) specifically so
-   every entry stays reachable regardless of list length - confirm your new
-   entry actually scrolls into view and is clickable in a real browser,
-   since a syntactically-correct array entry can still end up unreachable
-   if that CSS ever regresses or a future redesign changes the dropdown
-   markup.
+   renders and behaves correctly — try every control the page lists and
+   open each highlight's file link.
+4. Open the demo from its card on `/demos` too, to check the catalogue
+   entry.
 
 If this was prompted by a `/src` change (not a brand-new demo for existing
 functionality), also re-run the full root-level `CLAUDE.md` verification

.cspell/project-words.txt

@@ -394,3 +394,13 @@ Zoltan
 rrggbb
 rrggbbaa
 zstandard
+sublist
+orbitron
+mcinerney
+inerney
+rasmus
+andersson
+oxanium
+overcrafted
+squaremeapixel
+manu

AGENTS.md

@@ -673,7 +673,14 @@ e2e/playwright-report` opens the HTML report, which links each test's
 
 `documentation-site/src/pages/demos/<name>/` holds interactive, in-browser
 demos of engine features (`physics`, `ecs`, `particles`, `rendering`, ...),
-each rendered through `documentation-site/src/components/Demo.tsx`.
+each rendered through `DemoPage` (`documentation-site/src/components/demo-page/`):
+the running game with its controls and a short "How it works" list beside
+it, and a code explorer for the demo's source below. Its title and summary
+come from the demo's entry in `documentation-site/src/data/demos.ts`. The
+`add-feature-demo` skill shows how to write a page. The code explorer only
+shows engine code a reader can reuse: never list React or other framework
+code (`.tsx`/`.jsx`) in it, such as a settings panel that only drives the
+site's page.
 
 **Critical gotcha**: these demos import the engine as a published package
 (e.g. `import { addRigidBodyComponent } from '@forge-game-engine/forge/physics'`),
@@ -721,8 +728,9 @@ wrapper around the shared `CategoryDemosPage` component.
 The catalogue's data lives separately from the demo pages themselves:
 
 - `documentation-site/src/data/demo-categories.ts` - the fixed list of
-  categories (slug, title, description, card image under
-  `static/img/demos/categories/`).
+  categories (slug, title, description, and the line icon its card shows,
+  from `src/components/ModuleIcon.tsx`, the same set the homepage's feature
+  grid uses).
 - `documentation-site/src/data/demos.ts` - one entry per demo (slug, title,
   short description, and the category slugs it belongs to). A demo can
   belong to more than one category - e.g. the car demo is tagged both
@@ -731,8 +739,8 @@ The catalogue's data lives separately from the demo pages themselves:
 
 **When adding a new demo**, also add an entry to `demos.ts` with the
 category slugs it belongs to (adding a new category itself means adding to
-`demo-categories.ts` and a matching SVG under
-`static/img/demos/categories/`, plus a new
+`demo-categories.ts` with a `ModuleIcon` name, drawing a new icon in
+`ModuleIcon.tsx` in the same style if none fits, plus a new
 `src/pages/demos/category/<slug>/index.tsx` wrapper). A demo that combines
 many engine features into a complete mini-game (like the space shooter,
 brick breaker and car demos) belongs in the `games` category regardless of

documentation-site/docs/credits.md

@@ -2,24 +2,82 @@
 title: Credits and attributions
 ---
 
-## Icons
+Forge's demos, documentation and website use art, audio and fonts made by
+the people below. Thank you to all of them.
+
+## Sprites and textures
 
-Scroll down icons created by [Smashicons](https://www.flaticon.com/free-icons/scroll-down) from [Flaticon](https://www.flaticon.com/)
+- [Kenney](https://kenney.nl), all licensed
+  [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/):
+  - [UI Pack](https://kenney.nl/assets/ui-pack): the buttons, sliders, text
+    inputs and panels in the UI demos.
+  - [Fantasy UI Borders](https://kenney.nl/assets/fantasy-ui-borders): the
+    frames in the nine-slice and masks demos.
+  - [Particle Pack](https://kenney.nl/assets/particle-pack): the particle
+    textures in the particles demo.
+  - [Pattern Pack](https://kenney.nl/assets/pattern-pack): the backgrounds in
+    the physics demos.
+  - [Pirate Pack](https://kenney.nl/assets/pirate-pack): the sprites in the
+    pirate battle demo.
+  - [Puzzle Pack 2](https://kenney.nl/assets/puzzle-pack-2): the sprites in
+    the brick breaker demo.
+  - [Rolling Ball Assets](https://kenney.nl/assets/rolling-ball-assets): the
+    balls and blocks in the physics demos.
+  - [Simple Space](https://kenney.nl/assets/simple-space): ships, meteors and
+    stars in the space demos.
+- [Screaming Brain Studios](https://screamingbrainstudios.com/dl-seamless-space-backgrounds/):
+  the nebula space background.
+- [Wenrexa](https://opengameart.org/content/assets-free-laser-bullets-pack-2020):
+  the laser bullets in the space shooter demo.
+- [Squaremeapixel](https://squaremeapixel.itch.io/space-pack): the
+  spaceships and asteroids in the space shooter demo.
+- [CodeManu](https://codemanu.itch.io/vfx-free-pack): the explosion
+  animation in the space shooter demo.
+- [Overcrafted](https://overcrafted.itch.io/free-paid-vehicle-car-sprites-):
+  the car body and wheels in the car demo.
+- [Deep-Fold's Pixel Planet Generator](https://deep-fold.itch.io/pixel-planet-generator):
+  the pixel-art planet in the rendering demos and blog.
+- [OboroPixel](https://oboropixel.itch.io/characters-animations-asset-pack):
+  the soldier sprite sheets in the sprite animation docs.
 
-## Sprites
+## Music and sound effects
 
-- Some assets used in the demos and documentation have been provided by [Screaming Brain Studios - OpenGameArt.org](https://opengameart.org/content/seamless-space-backgrounds)
-- Some assets used in the demos and documentation have been provided by [Wenrexa - OpenGameArt.org](https://opengameart.org/content/assets-free-laser-bullets-pack-2020)
-- Some assets used in the demos and documentation have been provided by [OboroPixel - itch.io](https://oboropixel.itch.io/characters-animations-asset-pack)
+- Music by
+  [GerardDEP](https://pixabay.com/users/gerarddep-48160304/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808)
+  from
+  [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808).
+- Sound effects by
+  [LoLa Joy](https://pixabay.com/users/u_xg7ssi08yr-48039129/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976)
+  from
+  [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976).
 
 ## Fonts
 
-- The engine's shipped default font atlas, and the text rendering demo's
-  font, both use [Liberation Sans](https://github.com/liberationfonts)
-  (Copyright (c) 2012 Red Hat, Inc. with Reserved Font Name Liberation),
-  licensed under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/OFL).
+All licensed under the
+[SIL Open Font License, Version 1.1](https://openfontlicense.org):
+
+- [Liberation Sans](https://github.com/liberationfonts) (Copyright (c) 2012
+  Red Hat, Inc. with Reserved Font Name Liberation): the engine's default
+  font atlas, used by the text demo.
+- [Orbitron](https://github.com/theleagueof/orbitron) by Matt McInerney:
+  the website's headings.
+- [Inter](https://github.com/rsms/inter) by Rasmus Andersson: the website's
+  body text.
+- [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) by JetBrains:
+  the website's code.
+
+## Icons
+
+- [Font Awesome Free](https://fontawesome.com) icons, licensed
+  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+## Galactic Journey
 
-## Music
+The gameplay video on the home page is from
+[Galactic Journey](https://galactic-journey-6517e.web.app), a game made with
+Forge. Besides the art credited above, it uses:
 
-- Some music used in the demos and documentation have been provided by [GerardDEP](https://pixabay.com/users/gerarddep-48160304/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808) from [Pixabay](https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808)
-- Some sound effects used in the demos and documentation have been provided by [LoLa Joy](https://pixabay.com/users/u_xg7ssi08yr-48039129/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976) from [Pixabay](https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976)
+- The sci-fi UI kit by [Wenrexa](https://wenrexa.itch.io).
+- [Oxanium](https://github.com/sevmeyer/oxanium) (Copyright 2019 The Oxanium
+  Project Authors), licensed under the
+  [SIL Open Font License, Version 1.1](https://openfontlicense.org).

documentation-site/docusaurus.config.ts

@@ -56,7 +56,16 @@ const config: Config = {
           onUntruncatedBlogPosts: 'warn',
         },
         theme: {
-          customCss: './src/css/custom.css',
+          // Self-hosted fonts: Orbitron for headings, Inter for body text and
+          // JetBrains Mono for code and small eyebrow labels.
+          customCss: [
+            require.resolve('@fontsource/orbitron/600.css'),
+            require.resolve('@fontsource/orbitron/700.css'),
+            require.resolve('@fontsource-variable/inter/index.css'),
+            require.resolve('@fontsource/jetbrains-mono/400.css'),
+            require.resolve('@fontsource/jetbrains-mono/500.css'),
+            './src/css/custom.css',
+          ],
         },
       } satisfies Preset.Options,
     ],
@@ -95,6 +104,7 @@ const config: Config = {
     // Replace with your project's social card
     image: 'img/forge-social-card.jpg',
     colorMode: {
+      defaultMode: 'dark',
       respectPrefersColorScheme: true,
     },
     navbar: {