FCE-2061: Premium docs look & feel via @swmansion/t-rex-ui

docusaurus.config.ts

@@ -163,6 +163,19 @@ const config: Config = {
   onBrokenAnchors: "log",
   onDuplicateRoutes: "throw",
 
+  // Ask-AI sidepanel config (rendered in src/theme/Root.tsx via @docsearch/react).
+  // Lives here because themeConfig now uses `algolia` (for t-rex's search) rather
+  // than the @docsearch adapter's `docsearch` key.
+  customFields: {
+    askAi: {
+      appId: "IBX716Q0KT",
+      apiKey: "5dcaa347f57ca14f8cb59926164dd129",
+      indexName: "Fishjam",
+      assistantId: "49fdf088-e614-4b89-86c2-da8c4b566260",
+      agentStudio: true,
+    },
+  },
+
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
   // may want to replace "en" with "zh-Hans".
@@ -181,7 +194,10 @@ const config: Config = {
 
   future: {
     v4: true,
-    faster: {
+    // Docusaurus is pinned to 3.9.2 to match @swmansion/t-rex-ui (it imports 3.9-only
+    // theme-common internals). On 3.9.x this key is `experimental_faster`; it became
+    // `faster` in 3.10. Rename back if Docusaurus is ever upgraded.
+    experimental_faster: {
       swcJsLoader: true,
       swcJsMinimizer: true,
     },
@@ -224,6 +240,9 @@ const config: Config = {
         },
       } satisfies Preset.Options,
     ],
+    // Software Mansion premium docs theme. Placed after classic so it can
+    // override theme components. llms:false — we already run docusaurus-plugin-llms.
+    [require.resolve("@swmansion/t-rex-ui/preset"), { llms: false }],
   ],
 
   themeConfig: {
@@ -265,17 +284,19 @@ const config: Config = {
         },
       ],
     },
-    docsearch: {
+    // Search: classic Algolia DocSearch via @docusaurus/theme-search-algolia
+    // (registered in `themes`). t-rex's navbar search bar and search page read
+    // themeConfig.algolia directly. We use this instead of the
+    // @docsearch/docusaurus-adapter plugin because the adapter forbids
+    // themeConfig.algolia alongside its `docsearch` key, and t-rex's navbar search
+    // requires `algolia`. The Ask-AI sidepanel keys moved to customFields.askAi
+    // (consumed by src/theme/Root.tsx -> AskAiSidepanel, which uses @docsearch/react).
+    algolia: {
       appId: "IBX716Q0KT",
       apiKey: "5dcaa347f57ca14f8cb59926164dd129",
       indexName: "Fishjam",
       contextualSearch: true,
       searchPagePath: "search",
-      insights: false,
-      askAi: {
-        assistantId: "49fdf088-e614-4b89-86c2-da8c4b566260",
-        agentStudio: true,
-      },
     },
     footer: {
       links: [
@@ -320,8 +341,32 @@ const config: Config = {
   } satisfies Preset.ThemeConfig & DocSearchThemeConfig,
 
   plugins: [
+    // t-rex-ui ships its theme as untranspiled JSX under node_modules. Docusaurus's
+    // JS rule excludes node_modules from transpilation (it only un-excludes
+    // "docusaurus"-named packages), so the build fails to parse t-rex's theme/*.js
+    // (e.g. theme/MDXContent, theme/DocItem/Layout). Run just that theme dir through
+    // Docusaurus's own JS loader. The core rule already excludes it, so no double
+    // compilation. (t-rex's own docs dodge this because there the theme is a
+    // monorepo workspace, i.e. resolved outside node_modules.)
+    function transpileTRexUiTheme() {
+      return {
+        name: "transpile-t-rex-ui-theme",
+        configureWebpack(_config: unknown, isServer: boolean, utils: any) {
+          return {
+            module: {
+              rules: [
+                {
+                  test: /\.jsx?$/,
+                  include: [/[/\\]@swmansion[/\\]t-rex-ui[/\\]theme[/\\]/],
+                  use: [utils.getJSLoader({ isServer })],
+                },
+              ],
+            },
+          };
+        },
+      };
+    },
     ["@docusaurus/plugin-client-redirects", { createRedirects }],
-    "@docsearch/docusaurus-adapter",
     [
       "@scalar/docusaurus",
       {

package.json

@@ -24,40 +24,50 @@
     "spellcheck:report": "yarn spellcheck --no-show-suggestions"
   },
   "dependencies": {
+    "@docsearch/core": "^4.0.0",
+    "@docsearch/css": "^4.0.0",
     "@docsearch/docusaurus-adapter": "^4.0.0",
-    "@docusaurus/core": "^3.10.0",
-    "@docusaurus/faster": "^3.10.0",
-    "@docusaurus/plugin-client-redirects": "^3.10.0",
-    "@docusaurus/preset-classic": "^3.10.0",
-    "@docusaurus/remark-plugin-npm2yarn": "^3.10.0",
-    "@docusaurus/theme-mermaid": "^3.10.0",
-    "@docusaurus/utils": "^3.10.0",
+    "@docsearch/sidepanel": "^4.0.0",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/faster": "3.9.2",
+    "@docusaurus/plugin-client-redirects": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/remark-plugin-npm2yarn": "3.9.2",
+    "@docusaurus/theme-mermaid": "3.9.2",
+    "@docusaurus/theme-search-algolia": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@emotion/react": "^11.13.0",
+    "@emotion/styled": "^11.13.0",
     "@fastify/env": "^5.0.2",
     "@fishjam-cloud/js-server-sdk": "link:./packages/js-server-sdk/packages/js-server-sdk",
     "@fishjam-cloud/react-client": "link:./packages/web-client-sdk/packages/react-client",
     "@fishjam-cloud/react-native-client": "link:./packages/web-client-sdk/packages/mobile-client",
     "@mdx-js/react": "^3.1.0",
+    "@mui/material": "^7.0.0",
     "@scalar/docusaurus": "^0.8.5",
     "@shikijs/rehype": "^3.6.0",
     "@shikijs/transformers": "^3.6.0",
     "@swmansion/smelter": "^0.2.1",
     "@swmansion/smelter-web-wasm": "^0.2.1",
+    "@swmansion/t-rex-ui": "1.3.3",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "clsx": "^2.0.0",
+    "copy-text-to-clipboard": "^3.2.0",
     "expo-camera": "^16.1.8",
     "fastify": "^5.4.0",
     "mock-import": "^4.2.1",
     "prism-react-renderer": "^2.4.1",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-icons": "^5.5.0",
     "react-native": "^0.80.0",
     "shiki": "^3.6.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.10.0",
-    "@docusaurus/tsconfig": "^3.10.0",
-    "@docusaurus/types": "^3.10.0",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/tsconfig": "3.9.2",
+    "@docusaurus/types": "3.9.2",
     "@google/genai": "^1.35.0",
     "@shikijs/twoslash": "^3.6.0",
     "@vapi-ai/server-sdk": "^1.1.0",
@@ -69,6 +79,23 @@
     "typedoc-plugin-markdown": "4.7.0",
     "typescript": "~5.8.2"
   },
+  "resolutions": {
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/theme-classic": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/theme-search-algolia": "3.9.2",
+    "@docusaurus/theme-translations": "3.9.2",
+    "@docusaurus/plugin-content-docs": "3.9.2",
+    "@docusaurus/plugin-debug": "3.9.2",
+    "@docusaurus/mdx-loader": "3.9.2",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2"
+  },
   "browserslist": {
     "production": [
       ">0.5%",

src/components/AskAiSidepanel.tsx

@@ -5,16 +5,16 @@ import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 
 export default function AskAiSidepanel(): ReactElement {
   const { siteConfig } = useDocusaurusContext();
-  const { appId, apiKey, indexName, askAi } = siteConfig.themeConfig
-    .docsearch as any;
+  const { appId, apiKey, indexName, assistantId, agentStudio } = siteConfig
+    .customFields!.askAi as any;
 
   return (
     <DocSearchSidepanel
       appId={appId}
       apiKey={apiKey}
       indexName={indexName}
-      assistantId={askAi.assistantId}
-      agentStudio={askAi.agentStudio}
+      assistantId={assistantId}
+      agentStudio={agentStudio}
       button={{ variant: "floating" }}
       panel={{ variant: "floating", side: "right" }}
     />

src/components/QuickNavigation/index.module.css

@@ -12,15 +12,20 @@
   --ifm-link-hover-color: var(--ifm-color-emphasis-700);
   --ifm-link-hover-decoration: none;
 
-  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
-  border: 1px solid var(--ifm-color-emphasis-200);
-  transition: all var(--ifm-transition-fast) ease;
-  transition-property: border, box-shadow;
+  background: var(--swm-card-background, var(--ifm-background-color));
+  border: 1px solid var(--swm-card-border, var(--ifm-color-emphasis-200));
+  border-radius: 12px;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 8%);
+  transition:
+    transform var(--ifm-transition-fast) ease,
+    border-color var(--ifm-transition-fast) ease,
+    box-shadow var(--ifm-transition-fast) ease;
 }
 
 .cardContainer:hover {
-  border-color: var(--ifm-color-primary);
-  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+  border-color: var(--swm-card-border-hover, var(--ifm-color-primary));
+  box-shadow: 0 8px 20px rgb(0 0 0 / 10%);
+  transform: translateY(-2px);
 }
 
 .cardContainer *:last-child {

src/css/custom.css

@@ -6,18 +6,55 @@
 
 @import url("https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,100..1000;1,9..40,100..1000&display=swap");
 
-/* You can override the default Infima variables here. */
-
-/* matches landing site */
+/* t-rex-ui design tokens (vendored). Fishjam brand overrides follow below. */
+@import "./trex-theme.css";
+
+/* ===== Fishjam brand overrides for the vendored t-rex-ui tokens =====
+   t-rex's component tokens reference two base palette scales: navy-light-*
+   (body text, borders, sidebar, footer, search) and purple-light-* (links,
+   active tabs, TOC, card hover, paginator). Remapping just these two scales
+   rebrands the whole theme to Fishjam — navy -> warm near-black neutral,
+   purple -> Fishjam orange — so we don't have to touch every component token. */
 :root {
-  --ifm-font-family-base: "DM Sans", sans-serif;
-  --ifm-color-primary: #dd6460; /* fishjam.orange.60 */
-  --ifm-color-primary-dark: #dd6460;
-  --ifm-color-primary-darker: #dd6460;
-  --ifm-color-primary-darkest: #dd6460;
-  --ifm-color-primary-light: #dd6460;
-  --ifm-color-primary-lighter: #dd6460;
-  --ifm-color-primary-lightest: #dd6460;
+  /* Fonts: Fishjam uses DM Sans; no Aeonik. */
+  --swm-title-landing-font: "DM Sans";
+  --swm-title-font: "DM Sans";
+  --swm-body-font: "DM Sans";
+  --swm-code-font: ui-monospace, SFMono-Regular, "Liberation Mono", Menlo,
+    monospace;
+
+  /* Neutral scale (was SM navy) -> Fishjam warm near-black. */
+  --swm-navy-light-100: #221f1c;
+  --swm-navy-light-80: #46413c;
+  --swm-navy-light-60: #6f6862;
+  --swm-navy-light-40: #9c958d;
+  --swm-navy-light-20: #ddd5c9;
+  --swm-navy-light-10: #f6f1e7;
+  --swm-navy-light-transparent: #46413c40;
+
+  /* Accent scale (was SM purple) -> Fishjam orange. */
+  --swm-purple-light-100: #dd6460; /* fishjam.orange.60 */
+  --swm-purple-light-80: #e58884;
+  --swm-purple-light-60: #ecaaa7;
+  --swm-purple-light-40: #f4cbc9;
+  --swm-purple-light-20: #fce6e1; /* fishjam.orange.20 */
+  --swm-purple-light-transparent: #fce6e140;
+
+  /* Infima primary -> a real Fishjam orange scale (fixes the old flat scale). */
+  --ifm-color-primary: #dd6460;
+  --ifm-color-primary-dark: #d6433d;
+  --ifm-color-primary-darker: #ca3f39;
+  --ifm-color-primary-darkest: #a6342f;
+  --ifm-color-primary-light: #e3857f;
+  --ifm-color-primary-lighter: #e89992;
+  --ifm-color-primary-lightest: #f1c4c0;
+
+  /* Warm Fishjam surfaces: beige navbar/footer (matches the landing site). */
+  --swm-background: #ffffff;
+  --swm-off-background: #f7f3ec;
+  --ifm-navbar-background-color: #fcf4e4;
+  --ifm-footer-background-color: #fcf4e4;
+
   --ifm-code-font-size: 95%;
   --docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.5);
 }