From bc4fb65ad1d27130d4ec2a04fe855eab10b2f7bd Mon Sep 17 00:00:00 2001
From: Kamil Majkrzak <kamil.majkrzak@octopus.com>
Date: Mon, 25 May 2026 18:11:09 +0200
Subject: [PATCH 1/5] Docs design-system MVP

---
 astro.config.mjs                              |   6 +
 package.json                                  |   5 +-
 pnpm-lock.yaml                                | 395 +++++++++++++-
 src/design-system/README.md                   | 228 ++++++++
 .../docs-shell/DocsBreadcrumbs.astro          |  39 ++
 .../docs-shell/DocsContentLayout.astro        | 198 +++++++
 src/design-system/docs-shell/DocsHead.astro   | 135 +++++
 src/design-system/docs-shell/DocsHeader.astro | 344 ++++++++++++
 src/design-system/docs-shell/DocsLayout.astro | 115 ++++
 .../docs-shell/DocsSidebar.astro              |  51 ++
 .../docs-shell/DocsSidebarNav.astro           |  94 ++++
 src/design-system/docs-shell/DocsToc.astro    |  85 +++
 src/design-system/theme.css                   | 512 ++++++++++++++++++
 src/design-system/tokens.css                  | 162 ++++++
 src/design-system/ui/Badge.astro              |  26 +
 src/design-system/ui/Button.astro             |  39 ++
 src/design-system/ui/Callout.astro            |  67 +++
 src/design-system/ui/Card.astro               |  45 ++
 src/design-system/ui/CodeBlock.astro          | 101 ++++
 src/pages/docs.mdx                            |   2 +-
 src/pages/docs/ui-mvp.astro                   | 200 +++++++
 src/pages/ui-update-sample.mdx                |   2 +-
 22 files changed, 2838 insertions(+), 13 deletions(-)
 create mode 100644 src/design-system/README.md
 create mode 100644 src/design-system/docs-shell/DocsBreadcrumbs.astro
 create mode 100644 src/design-system/docs-shell/DocsContentLayout.astro
 create mode 100644 src/design-system/docs-shell/DocsHead.astro
 create mode 100644 src/design-system/docs-shell/DocsHeader.astro
 create mode 100644 src/design-system/docs-shell/DocsLayout.astro
 create mode 100644 src/design-system/docs-shell/DocsSidebar.astro
 create mode 100644 src/design-system/docs-shell/DocsSidebarNav.astro
 create mode 100644 src/design-system/docs-shell/DocsToc.astro
 create mode 100644 src/design-system/theme.css
 create mode 100644 src/design-system/tokens.css
 create mode 100644 src/design-system/ui/Badge.astro
 create mode 100644 src/design-system/ui/Button.astro
 create mode 100644 src/design-system/ui/Callout.astro
 create mode 100644 src/design-system/ui/Card.astro
 create mode 100644 src/design-system/ui/CodeBlock.astro
 create mode 100644 src/pages/docs/ui-mvp.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 541c7c43be..3a8ceba87f 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -2,6 +2,7 @@ import remarkDirective from 'remark-directive';
 import remarkHeading from 'remark-heading-id';
 import { defineConfig } from 'astro/config';
 import mdx from '@astrojs/mdx';
+import tailwindcss from '@tailwindcss/vite';
 import { attributeMarkdown, wrapTables } from '/src/themes/octopus/utilities/custom-markdown.mjs';
 import llmMdEmitter from './src/integrations/llm-md-emitter.ts';
 
@@ -12,6 +13,11 @@ export default defineConfig({
         mdx(),
         llmMdEmitter()
     ],
+    // Tailwind v4 only lands on pages that import the design-system entry
+    // (src/design-system/theme.css), so the live site stays untouched.
+    vite: {
+        plugins: [tailwindcss()]
+    },
     markdown: {
         shikiConfig: {
             theme: 'light-plus'
diff --git a/package.json b/package.json
index 80a61b7ca8..b3a5d5de83 100644
--- a/package.json
+++ b/package.json
@@ -43,13 +43,16 @@
     "devDependencies": {
         "@playwright/test": "^1.59.1",
         "@pnpm/exe": "^11.0.9",
+        "@tailwindcss/typography": "^0.5.19",
+        "@tailwindcss/vite": "^4.3.0",
         "cspell": "^10.0.0",
         "csv-parse": "^6.2.1",
         "linkinator": "7.0.0",
         "npm-run-all": "^4.1.5",
         "onchange": "^7.1.0",
         "prettier": "^3.8.3",
-        "prettier-plugin-astro": "^0.14.1"
+        "prettier-plugin-astro": "^0.14.1",
+        "tailwindcss": "^4.3.0"
     },
     "pnpm": {
         "overrides": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 939299a054..a022fedb80 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -20,10 +20,10 @@ importers:
     dependencies:
       '@astrojs/mdx':
         specifier: ^5.0.4
-        version: 5.0.4(astro@6.3.1(@types/node@24.10.1)(rollup@4.60.3)(yaml@2.8.4))
+        version: 5.0.4(astro@6.3.1(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.60.3)(yaml@2.8.4))
       astro:
         specifier: ^6.3.1
-        version: 6.3.1(@types/node@24.10.1)(rollup@4.60.3)(yaml@2.8.4)
+        version: 6.3.1(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.60.3)(yaml@2.8.4)
       astro-accelerator-utils:
         specifier: ^0.3.84
         version: 0.3.84
@@ -61,6 +61,12 @@ importers:
       '@pnpm/exe':
         specifier: ^11.0.9
         version: 11.0.9
+      '@tailwindcss/typography':
+        specifier: ^0.5.19
+        version: 0.5.19(tailwindcss@4.3.0)
+      '@tailwindcss/vite':
+        specifier: ^4.3.0
+        version: 4.3.0(vite@7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4))
       cspell:
         specifier: ^10.0.0
         version: 10.0.0
@@ -82,6 +88,9 @@ importers:
       prettier-plugin-astro:
         specifier: ^0.14.1
         version: 0.14.1
+      tailwindcss:
+        specifier: ^4.3.0
+        version: 4.3.0
 
 packages:
 
@@ -680,9 +689,22 @@ packages:
     resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
     engines: {node: '>=12'}
 
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
   '@jridgewell/sourcemap-codec@1.5.5':
     resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
 
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
   '@mdx-js/mdx@3.1.1':
     resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
 
@@ -959,6 +981,101 @@ packages:
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
+  '@tailwindcss/node@4.3.0':
+    resolution: {integrity: sha512-aFb4gUhFOgdh9AXo4IzBEOzBkkAxm9VigwDJnMIYv3lcfXCJVesNfbEaBl4BNgVRyid92AmdviqwBUBRKSeY3g==}
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    resolution: {integrity: sha512-TJPiq67tKlLuObP6RkwvVGDoxCMBVtDgKkLfa/uyj7/FyxvQwHS+UOnVrXXgbEsfUaMgiVvC4KbJnRr26ho4Ng==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    resolution: {integrity: sha512-oMN/WZRb+SO37BmUElEgeEWuU8E/HXRkiODxJxLe1UTHVXLrdVSgfaJV7pSlhRGMSOiXLuxTIjfsF3wYvz8cgQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    resolution: {integrity: sha512-N6CUmu4a6bKVADfw77p+iw6Yd9Q3OBhe0veaDX+QazfuVYlQsHfDgxBrsjQ/IW+zywL8mTrNd0SdJT/zgtvMdA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    resolution: {integrity: sha512-zDL5hBkQdH5C6MpqbK3gQAgP80tsMwSI26vjOzjJtNCMUo0lFgOItzHKBIupOZNQxt3ouPH7RPhvNhiTfCe5CQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    resolution: {integrity: sha512-R06HdNi7A7OEoMsf6d4tjZ71RCWnZQPHj2mnotSFURjNLdBC+cIgXQ7l81CqeoiQftjf6OOblxXMInMgN2VzMA==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    resolution: {integrity: sha512-qTJHELX8jetjhRQHCLilkVLmybpzNQAtaI/gaoVoidn/ufbNDbAo8KlK2J+yPoc8wQxvDxCmh/5lr8nC1+lTbg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    resolution: {integrity: sha512-Z6sukiQsngnWO+l39X4pPbiWT81IC+PLKF+PHxIlyZbGNb9MODfYlXEVlFvej5BOZInWX01kVyzeLvHsXhfczQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    resolution: {integrity: sha512-DRNdQRpSGzRGfARVuVkxvM8Q12nh19l4BF/G7zGA1oe+9wcC6saFBHTISrpIcKzhiXtSrlSrluCfvMuledoCTQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    resolution: {integrity: sha512-Z0IADbDo8bh6I7h2IQMx601AdXBLfFpEdUotft86evd/8ZPflZe9COPO8Q1vw+pfLWIUo9zN/JGZvwuAJqduqg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    resolution: {integrity: sha512-HNZGOUxEmElksYR7S6sC5jTeNGpobAsy9u7Gu0AskJ8/20FR9GqebUyB+HBcU/ax6BHuiuJi+Oda4B+YX6H1yA==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    resolution: {integrity: sha512-Pe+RPVTi1T+qymuuRpcdvwSVZjnll/f7n8gBxMMh3xLTctMDKqpdfGimbMyioqtLhUYZxdJ9wGNhV7MKHvgZsQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    resolution: {integrity: sha512-Mvrf2kXW/yeW/OTezZlCGOirXRcUuLIBx/5Y12BaPM7wJoryG6dfS/NJL8aBPqtTEx/Vm4T4vKzFUcKDT+TKUA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.3.0':
+    resolution: {integrity: sha512-F7HZGBeN9I0/AuuJS5PwcD8xayx5ri5GhjYUDBEVYUkexyA/giwbDNjRVrxSezE3T250OU2K/wp/ltWx3UOefg==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/typography@0.5.19':
+    resolution: {integrity: sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==}
+    peerDependencies:
+      tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
+
+  '@tailwindcss/vite@4.3.0':
+    resolution: {integrity: sha512-t6J3OrB5Fc0ExuhohouH0fWUGMYL6PTLhW+E7zIk/pdbnJARZDCwjBznFnkh5ynRnIRSI4YjtTH0t6USjJISrw==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
   '@types/debug@4.1.13':
     resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
 
@@ -1272,6 +1389,11 @@ packages:
     resolution: {integrity: sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==}
     engines: {node: '>= 6'}
 
+  cssesc@3.0.0:
+    resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
   csso@5.0.5:
     resolution: {integrity: sha512-0LrrStPOdJj+SPCCrGhzryycLjwcgUSHBtxNA8aIDxf0GLsRh1cKYhB00Gd1lDOS4yGH69+SNn13+TWbVHETFQ==}
     engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0, npm: '>=7.0.0'}
@@ -1369,6 +1491,10 @@ packages:
   emoji-regex@9.2.2:
     resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
 
+  enhanced-resolve@5.22.0:
+    resolution: {integrity: sha512-xYcDWrpELkFzz9SpZ3PlI6Eu6eD93Yf0WLDRxikGhWJ3MAir2SNZTIVCVZqZ/NUyx8AdMc2gT9C0gPiw18kG+A==}
+    engines: {node: '>=10.13.0'}
+
   entities@4.5.0:
     resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
     engines: {node: '>=0.12'}
@@ -1882,6 +2008,10 @@ packages:
   jackspeak@3.4.3:
     resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
 
+  jiti@2.7.0:
+    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
+    hasBin: true
+
   js-yaml@3.14.2:
     resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==}
     hasBin: true
@@ -1907,6 +2037,76 @@ packages:
   leac@0.7.0:
     resolution: {integrity: sha512-qMrZeyEekgdRQ9o6a4NAB2EQZrv827GJdn1vnapwSJ90hWRB4TzUSunvacPkxQ2TnNqHNI1/zSt0hlo0crG8Jw==}
 
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
   linkinator@7.0.0:
     resolution: {integrity: sha512-81sjQATza2eVL5Bqk96QrdVnYYI6fxWSrOHIC3/oWM6qG+5ARqwAVVwkrqSZ6RawsJcBRqOmOm4pkkj3r6Nrow==}
     engines: {node: '>=20'}
@@ -2318,6 +2518,10 @@ packages:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
 
+  postcss-selector-parser@6.0.10:
+    resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
+    engines: {node: '>=4'}
+
   postcss@8.5.14:
     resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -2661,6 +2865,13 @@ packages:
     engines: {node: '>=16'}
     hasBin: true
 
+  tailwindcss@4.3.0:
+    resolution: {integrity: sha512-y6nxMGB1nMW9R6k96e5gdIFzcfL/gTJRNaqGes1YvkLnPVXzWgbqFF2yLC0T8G774n24cx3Pe8XrKoniCOAH+Q==}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
   tiny-inflate@1.0.3:
     resolution: {integrity: sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==}
 
@@ -2832,6 +3043,9 @@ packages:
       uploadthing:
         optional: true
 
+  util-deprecate@1.0.2:
+    resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
+
   validate-npm-package-license@3.0.4:
     resolution: {integrity: sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew==}
 
@@ -3000,12 +3214,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/mdx@5.0.4(astro@6.3.1(@types/node@24.10.1)(rollup@4.60.3)(yaml@2.8.4))':
+  '@astrojs/mdx@5.0.4(astro@6.3.1(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.60.3)(yaml@2.8.4))':
     dependencies:
       '@astrojs/markdown-remark': 7.1.1
       '@mdx-js/mdx': 3.1.1
       acorn: 8.16.0
-      astro: 6.3.1(@types/node@24.10.1)(rollup@4.60.3)(yaml@2.8.4)
+      astro: 6.3.1(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.60.3)(yaml@2.8.4)
       es-module-lexer: 2.1.0
       estree-util-visit: 2.0.0
       hast-util-to-html: 9.0.5
@@ -3474,8 +3688,25 @@ snapshots:
       wrap-ansi: 8.1.0
       wrap-ansi-cjs: wrap-ansi@7.0.0
 
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
   '@jridgewell/sourcemap-codec@1.5.5': {}
 
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
   '@mdx-js/mdx@3.1.1':
     dependencies:
       '@types/estree': 1.0.9
@@ -3713,6 +3944,79 @@ snapshots:
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
+  '@tailwindcss/node@4.3.0':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.22.0
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide@4.3.0':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-x64': 4.3.0
+      '@tailwindcss/oxide-freebsd-x64': 4.3.0
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.0
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.0
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.0
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.0
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.0
+
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.3.0)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/vite@4.3.0(vite@7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4))':
+    dependencies:
+      '@tailwindcss/node': 4.3.0
+      '@tailwindcss/oxide': 4.3.0
+      tailwindcss: 4.3.0
+      vite: 7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4)
+
   '@types/debug@4.1.13':
     dependencies:
       '@types/ms': 2.1.0
@@ -3810,7 +4114,7 @@ snapshots:
 
   astro-accelerator-utils@0.3.84: {}
 
-  astro@6.3.1(@types/node@24.10.1)(rollup@4.60.3)(yaml@2.8.4):
+  astro@6.3.1(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.60.3)(yaml@2.8.4):
     dependencies:
       '@astrojs/compiler': 4.0.0
       '@astrojs/internal-helpers': 0.9.0
@@ -3862,8 +4166,8 @@ snapshots:
       unist-util-visit: 5.1.0
       unstorage: 1.17.5
       vfile: 6.0.3
-      vite: 7.3.3(@types/node@24.10.1)(yaml@2.8.4)
-      vitefu: 1.1.3(vite@7.3.3(@types/node@24.10.1)(yaml@2.8.4))
+      vite: 7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4)
+      vitefu: 1.1.3(vite@7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4))
       xxhash-wasm: 1.1.0
       yargs-parser: 22.0.0
       zod: 4.4.3
@@ -4147,6 +4451,8 @@ snapshots:
 
   css-what@6.2.2: {}
 
+  cssesc@3.0.0: {}
+
   csso@5.0.5:
     dependencies:
       css-tree: 2.2.1
@@ -4241,6 +4547,11 @@ snapshots:
 
   emoji-regex@9.2.2: {}
 
+  enhanced-resolve@5.22.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
   entities@4.5.0: {}
 
   entities@6.0.1: {}
@@ -4929,6 +5240,8 @@ snapshots:
     optionalDependencies:
       '@pkgjs/parseargs': 0.11.0
 
+  jiti@2.7.0: {}
+
   js-yaml@3.14.2:
     dependencies:
       argparse: 1.0.10
@@ -4948,6 +5261,55 @@ snapshots:
 
   leac@0.7.0: {}
 
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
   linkinator@7.0.0:
     dependencies:
       chalk: 5.6.2
@@ -5650,6 +6012,11 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
+  postcss-selector-parser@6.0.10:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
   postcss@8.5.14:
     dependencies:
       nanoid: 3.3.12
@@ -6173,6 +6540,10 @@ snapshots:
       picocolors: 1.1.1
       sax: 1.6.0
 
+  tailwindcss@4.3.0: {}
+
+  tapable@2.3.3: {}
+
   tiny-inflate@1.0.3: {}
 
   tinyclip@0.1.12: {}
@@ -6329,6 +6700,8 @@ snapshots:
       ofetch: 1.5.1
       ufo: 1.6.4
 
+  util-deprecate@1.0.2: {}
+
   validate-npm-package-license@3.0.4:
     dependencies:
       spdx-correct: 3.2.0
@@ -6349,7 +6722,7 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite@7.3.3(@types/node@24.10.1)(yaml@2.8.4):
+  vite@7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4):
     dependencies:
       esbuild: 0.28.0
       fdir: 6.5.0(picomatch@4.0.4)
@@ -6360,11 +6733,13 @@ snapshots:
     optionalDependencies:
       '@types/node': 24.10.1
       fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
       yaml: 2.8.4
 
-  vitefu@1.1.3(vite@7.3.3(@types/node@24.10.1)(yaml@2.8.4)):
+  vitefu@1.1.3(vite@7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4)):
     optionalDependencies:
-      vite: 7.3.3(@types/node@24.10.1)(yaml@2.8.4)
+      vite: 7.3.3(@types/node@24.10.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.8.4)
 
   vscode-languageserver-textdocument@1.0.12: {}
 
diff --git a/src/design-system/README.md b/src/design-system/README.md
new file mode 100644
index 0000000000..eb251959ed
--- /dev/null
+++ b/src/design-system/README.md
@@ -0,0 +1,228 @@
+# Octopus Design System (portable module)
+
+A self-contained, framework-free design system for Octopus Astro sites. It exists so the
+docs site and the other (drifted) microsites can share **one** visual language instead of
+each maintaining its own CSS. Everything here is plain Astro + CSS custom properties +
+Tailwind v4 utilities - **no React/Vue/Svelte, no client framework runtime** - which keeps
+SEO and Core Web Vitals intact on statically generated pages.
+
+> Status: MVP. Proven in this repo on `/docs/ui-mvp`, which is the first consumer of this
+> module. Adopt it elsewhere by copying this one folder and wiring two things.
+
+---
+
+## 1. Anatomy
+
+```
+src/design-system/
+├── README.md            ← this file
+├── tokens.css           ← brand + semantic CSS variables (THE customization surface)
+├── theme.css            ← Tailwind v4 entry: imports tokens, maps them into the @theme,
+│                          tunes the typography plugin. Import this once per page.
+├── ui/                  ← universal primitives (any Octopus site: docs, marketing, app)
+│   ├── Button.astro
+│   ├── Badge.astro
+│   ├── Card.astro
+│   ├── Callout.astro
+│   └── CodeBlock.astro  ← code surface + filename bar + vanilla copy button
+└── docs-shell/          ← documentation-site chrome (only docs-style sites need this)
+    ├── DocsLayout.astro      ← page shell: <head>, header, sidebar, article, toc, footer
+    ├── DocsHeader.astro      ← top bar: real OctopusLogo, search w/ results dropdown,
+    │                           theme toggle, trial CTA
+    ├── DocsSidebar.astro     ← left section nav
+    ├── DocsToc.astro         ← right "on this page" nav w/ scroll-spy
+    └── DocsBreadcrumbs.astro ← RDFa BreadcrumbList breadcrumbs
+```
+
+**Two tiers, adopt independently:**
+- `tokens.css` + `theme.css` + `ui/` - the universal core. Any Octopus Astro site can use it.
+- `docs-shell/` - opinionated documentation chrome. Take it for docs sites; skip it for
+  marketing/app sites and build their own shells on top of the core.
+
+---
+
+## 2. The single customization surface: `tokens.css`
+
+`tokens.css` is the **only** file a site is expected to edit. It defines two layers:
+
+1. **Brand primitives** - the literal Octopus palette (`--octo-blue`, `--octo-green`, the
+   navy scale) and font stacks. These are the brand source of truth, mirrored from
+   `public/docs/css/vars.css`.
+2. **Semantic tokens** (shadcn shape) - `--background`, `--foreground`, `--primary`,
+   `--accent`, `--muted`, `--border`, `--ring`, callout intents, surfaces, elevation, etc.,
+   defined for light (`:root`) and dark (`[data-theme='dark']`).
+
+Components and `theme.css` reference **only the semantic tokens**, never raw hex. So:
+- Re-skinning a site = edit `tokens.css`, nothing else.
+- Because every microsite is the *same* Octopus brand, `tokens.css` ports **1:1 unchanged** -
+  that is the whole point: copy it verbatim and every site converges on one look. Only fork
+  it if a site genuinely needs to diverge.
+
+Dark mode is driven by the `[data-theme='dark']` attribute on `<html>` (matches the existing
+Octopus site switch), not a Tailwind `dark:` class.
+
+---
+
+## 3. Adopting it in another repo
+
+**Prerequisites:** Astro 5+ (built/tested on Astro 6.3) using Vite, and pnpm.
+
+### Step 1 - install dependencies
+
+```bash
+pnpm add -D tailwindcss@^4 @tailwindcss/vite@^4 @tailwindcss/typography@^0.5
+```
+
+### Step 2 - wire the Tailwind v4 Vite plugin
+
+Tailwind v4 is added as a **Vite plugin**, not an Astro integration. In `astro.config.mjs`:
+
+```js
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  // ...existing integrations stay as-is...
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+
+This is global to the build, but Tailwind only emits CSS for pages that actually **import
+`theme.css`** - so it does not leak onto pages that don't opt in.
+
+### Step 3 - copy the module
+
+Copy `src/design-system/` into the target repo's `src/`. Keep the folder intact so the
+relative imports inside it keep working (`theme.css` → `./tokens.css`, `docs-shell` files →
+each other).
+
+### Step 4 - satisfy the `docs-shell` external dependencies (docs sites only)
+
+`docs-shell` deliberately reuses two existing shared Octopus assets rather than reinventing
+them. If you adopt `docs-shell`, the target repo must provide:
+
+| Dependency | Used by | Path in this repo | Notes |
+|---|---|---|---|
+| `OctopusLogo.astro` | `DocsHeader.astro` | `public/docs/img/OctopusLogo.astro` | The genuine wordmark+glyph. Import path is `../../../public/docs/img/OctopusLogo.astro` - adjust if your asset lives elsewhere. |
+| Shared `Footer.astro` | `DocsLayout.astro` | `src/components/Footer.astro` | Imported as `../../components/Footer.astro`. Swap for the site's own footer if needed. |
+| `footer-bundle.css` | `DocsLayout.astro` `<head>` | `public/docs/css/footer-bundle.css` | Linked by absolute URL `/docs/css/footer-bundle.css`. |
+
+The `ui/` core has **no** external dependencies.
+
+### Step 5 - use it
+
+```astro
+---
+import DocsLayout from '../design-system/docs-shell/DocsLayout.astro';
+import Callout from '../design-system/ui/Callout.astro';
+import Card from '../design-system/ui/Card.astro';
+import Button from '../design-system/ui/Button.astro';
+import Badge from '../design-system/ui/Badge.astro';
+import CodeBlock from '../design-system/ui/CodeBlock.astro';
+---
+<DocsLayout title="..." description="..." breadcrumbs={[...]} sidebar={[...]} toc={[...]}>
+  <Callout intent="info" title="Note">Body text…</Callout>
+  <!-- prose / MDX content -->
+</DocsLayout>
+```
+
+For a non-docs site, import `theme.css` once in your own layout's frontmatter and use the
+`ui/` primitives:
+
+```astro
+---
+import '../design-system/theme.css';
+import Button from '../design-system/ui/Button.astro';
+---
+```
+
+> Tip: add an alias (e.g. `@ds/*` → `src/design-system/*`) in `tsconfig.json` /
+> `astro.config` to avoid `../../` import chains. Optional.
+
+---
+
+## 3a. Finding what's what (developer experience)
+
+With Tailwind the styling lives **on the element, inside the component file** — there is no
+semantic stylesheet like the old `main.css` to grep for `.article-nav__title`. The source of
+truth is the `.astro` component, not a CSS file. To keep the DOM traceable we tag every
+component's root element with a **`data-component="<FileName>"`** attribute.
+
+Workflow to locate and fix anything:
+1. Inspect the element in browser devtools.
+2. Walk up to the nearest `[data-component="X"]`.
+3. Open `src/design-system/**/X.astro` — the Tailwind classes you want to change are right
+   there on the element (the component bodies are small and readable).
+
+Example: a sidebar link → nearest `data-component` is `DocsSidebarNav` → edit
+`docs-shell/DocsSidebarNav.astro`. The nav region itself is `DocsSidebar` (the `<aside>` in
+`DocsContentLayout.astro`).
+
+Convention: PascalCase value == the `.astro` filename. Add `data-component` to the root of any
+new component. (This is the same idea as shadcn/ui's `data-slot`; it survives into production
+and is greppable.) For finer granularity inside a component, add `data-slot="<part>"`.
+
+Optional dev aid: Astro can emit `data-astro-source-file` / `data-astro-source-loc` (click an
+element to open the exact file:line in your editor) — not currently enabled in this repo; can
+be turned on for the dev build if wanted.
+
+---
+
+## 4. Guarantees, and how not to break them
+
+These hold by construction; preserve them when extending the system.
+
+- **Zero framework runtime.** Components are `.astro` (compile to static HTML) + Tailwind
+  utilities. The only JavaScript is a handful of tiny `is:inline` vanilla scripts. Do **not**
+  introduce a UI framework or a client-side component library.
+- **SEO surfaces preserved.** `DocsBreadcrumbs` emits an RDFa `BreadcrumbList`; `DocsLayout`
+  wraps content in `<article itemscope itemtype="https://schema.org/TechArticle">` with
+  `itemprop` headline/description/articleBody; heading hierarchy is semantic. Keep these when
+  editing the shell.
+- **Core Web Vitals.** No web fonts (system-ui sans + Consolas/monaco mono), no blocking JS,
+  no layout-shifting hydration. A FOUC-prevention inline script in `DocsLayout`'s `<head>`
+  applies the stored theme before paint.
+- **Typography plugin override technique.** The prose/table/code/status rules in `theme.css`
+  are intentionally **unlayered** (outside `@layer base`) so they beat `@tailwindcss/typography`'s
+  utility-layer defaults. Pages use `class="prose"` (not `prose-slate`). Don't move these into
+  a layer or the brand colors will lose to the plugin (and dark-mode body text will go dark).
+
+### Inline-script inventory (all vanilla, all `is:inline`)
+
+| Script | File | Purpose |
+|---|---|---|
+| FOUC theme apply | `docs-shell/DocsLayout.astro` (head) | Set `data-theme` from `localStorage` before paint |
+| Theme toggle | `docs-shell/DocsHeader.astro` | Toggle + persist light/dark |
+| Search dropdown | `docs-shell/DocsHeader.astro` | Filtered, keyboard-navigable results list (currently sample data - see gaps) |
+| TOC scroll-spy | `docs-shell/DocsToc.astro` | IntersectionObserver active-section highlight |
+| Copy button | `ui/CodeBlock.astro` | Delegated copy-to-clipboard with "Copied" state |
+
+---
+
+## 5. Known MVP gaps (intentionally out of scope)
+
+- **Search is demo data.** The dropdown filters ~14 hard-coded sample entries. Wiring the
+  real search index (the existing `search.json` / `Search.astro` backend) is a data swap, not
+  a structural change.
+- **Code blocks: no syntax highlighting.** `CodeBlock` gives the surface + filename bar +
+  copy button, but not token highlighting. Add a build-time highlighter (Shiki via
+  rehype/remark) if needed. Bare fenced code in MDX gets the styled surface but not the
+  filename bar/copy button until a rehype step wraps fenced code in the `CodeBlock` shape.
+- **Mobile nav** is a simple `<details>` disclosure (no slide-over/scroll-lock), to honor the
+  zero-JS constraint.
+
+---
+
+## 6. Porting checklist
+
+- [ ] `pnpm add -D tailwindcss@^4 @tailwindcss/vite@^4 @tailwindcss/typography@^0.5`
+- [ ] Add `vite.plugins: [tailwindcss()]` to `astro.config.mjs`
+- [ ] Copy `src/design-system/` into the target repo (keep folder structure intact)
+- [ ] (docs-shell) Provide `OctopusLogo.astro`, shared `Footer.astro`, `footer-bundle.css`,
+      and fix the three relative paths if your layout sits at a different depth
+- [ ] Import `theme.css` once per page (directly, or transitively via `DocsLayout`)
+- [ ] Confirm dark mode toggles via `[data-theme='dark']`
+- [ ] Verify a built page: HTTP 200, no Vite error overlay, RDFa/TechArticle present,
+      brand colors render in both themes
+- [ ] Decide whether `tokens.css` ports verbatim (recommended for brand unification) or forks
diff --git a/src/design-system/docs-shell/DocsBreadcrumbs.astro b/src/design-system/docs-shell/DocsBreadcrumbs.astro
new file mode 100644
index 0000000000..36b252fc30
--- /dev/null
+++ b/src/design-system/docs-shell/DocsBreadcrumbs.astro
@@ -0,0 +1,39 @@
+---
+interface Crumb {
+  label: string;
+  href?: string;
+}
+interface Props {
+  items: Crumb[];
+}
+const { items } = Astro.props;
+---
+
+<!-- RDFa BreadcrumbList preserved (SEO guardrail: matches existing Breadcrumbs.astro) -->
+<nav aria-label="Breadcrumb" class="mb-4 text-sm" data-component="DocsBreadcrumbs">
+  <ol
+    class="flex flex-wrap items-center gap-1.5 text-muted-foreground"
+    vocab="https://schema.org/"
+    typeof="BreadcrumbList"
+  >
+    {
+      items.map((c, i) => (
+        <li
+          class="flex items-center gap-1.5"
+          property="itemListElement"
+          typeof="ListItem"
+        >
+          {c.href ? (
+            <a property="item" typeof="WebPage" href={c.href} class="hover:text-foreground transition-colors">
+              <span property="name">{c.label}</span>
+            </a>
+          ) : (
+            <span property="name" class="text-foreground font-medium">{c.label}</span>
+          )}
+          <meta property="position" content={String(i + 1)} />
+          {i < items.length - 1 && <span aria-hidden="true" class="text-border">/</span>}
+        </li>
+      ))
+    }
+  </ol>
+</nav>
diff --git a/src/design-system/docs-shell/DocsContentLayout.astro b/src/design-system/docs-shell/DocsContentLayout.astro
new file mode 100644
index 0000000000..3b37488b47
--- /dev/null
+++ b/src/design-system/docs-shell/DocsContentLayout.astro
@@ -0,0 +1,198 @@
+---
+// Phase A adapter layout: markdown-compatible entrypoint that lets any real
+// content page adopt the new design system by switching its `layout:`
+// frontmatter line. Reuses the site's existing data sources (nav tree,
+// breadcrumbs, SEO head via HtmlHead) and renders them through our chrome.
+import '../theme.css';
+import { Accelerator } from 'astro-accelerator-utils';
+import { SITE } from '@config';
+import { menu } from '@data/navigation';
+import Head from './DocsHead.astro';
+
+import DocsHeader from './DocsHeader.astro';
+import DocsToc from './DocsToc.astro';
+import DocsBreadcrumbs from './DocsBreadcrumbs.astro';
+import DocsSidebarNav from './DocsSidebarNav.astro';
+import Footer from '../../components/Footer.astro';
+
+type Props = {
+  frontmatter: Record<string, any>;
+  headings: { depth: number; slug: string; text: string }[];
+  breadcrumbs?: { url: string; title: string; ariaCurrent?: string }[] | null;
+};
+const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props;
+
+const accelerator = new Accelerator(SITE);
+const lang = frontmatter.lang ?? SITE.default.lang;
+const currentUrl = new URL(Astro.request.url);
+
+// Real sidebar nav tree (NavPage[]).
+const pages = accelerator.navigation.menu(currentUrl, SITE.subfolder, menu);
+
+// Lightweight nav (mirrors src/themes/octopus/components/Navigation.astro from
+// main): keep only the active section's subtree expanded and collapse every
+// other top-level section to a single labelled link, so the rendered DOM stays
+// small for AI-crawler token budgets. Collapsed sections render as links with a
+// right-chevron 'navigate' affordance (see DocsSidebarNav); the active section
+// stays an expandable dropdown.
+const currentPath = currentUrl.pathname.replace(/\/$/, '');
+const isOnActivePath = (page: any): boolean => {
+  const pUrl = (page.url ?? '').replace(/\/$/, '');
+  if (!pUrl) return false;
+  return currentPath === pUrl || currentPath.startsWith(pUrl + '/');
+};
+const markActiveBranchOpen = (items: any[]): void => {
+  for (const item of items) {
+    if (item.children && item.children.length > 0 && isOnActivePath(item)) {
+      item.isOpen = true;
+      markActiveBranchOpen(item.children);
+    }
+  }
+};
+for (const top of pages) {
+  if (top.children && top.children.length > 0) {
+    if (isOnActivePath(top)) {
+      top.isOpen = true;
+      markActiveBranchOpen(top.children);
+    } else {
+      if (top.section) top.title = top.section;
+      top.children = [];
+    }
+  }
+}
+
+// Real breadcrumbs from accelerator nav data.
+const crumbs = accelerator.navigation
+  .breadcrumbs(currentUrl, SITE.subfolder, breadcrumbs?.length ?? 0)
+  .map((crumb: any) => ({
+    label: crumb.section || crumb.title,
+    href: accelerator.urlFormatter.formatAddress(crumb.url),
+  }));
+
+// TOC from the rendered markdown headings (h2/h3 only).
+const toc = headings
+  .filter((h) => h.depth >= 2 && h.depth <= 3)
+  .map((h) => ({
+    label: h.text,
+    href: '#' + h.slug,
+    depth: h.depth >= 3 ? 2 : 1,
+  }));
+
+const sortedTopLevel = pages
+  .slice()
+  .sort((a: any, b: any) => a.order - b.order);
+---
+
+<html lang={lang}>
+  <Head frontmatter={frontmatter} headings={headings} lang={lang} />
+  <body
+    class="min-h-screen bg-background font-sans text-foreground antialiased"
+  >
+    <script is:inline>
+      if (localStorage.getItem('mvp-theme') === 'dark')
+        document.documentElement.setAttribute('data-theme', 'dark');
+    </script>
+    <DocsHeader />
+
+    <div class="mx-auto flex max-w-[1600px]">
+      <aside
+        data-component="DocsSidebar"
+        class="hidden w-64 shrink-0 border-r border-border bg-sidebar lg:block"
+        aria-label="Documentation navigation"
+      >
+        <nav
+          class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-4 py-6 [scrollbar-width:thin]"
+        >
+          <ul>
+            {sortedTopLevel.map((page: any) => <DocsSidebarNav page={page} />)}
+          </ul>
+        </nav>
+      </aside>
+
+      <div class="flex min-w-0 flex-1">
+        <main
+          class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-14"
+          data-component="DocsContentLayout"
+        >
+          <div class="mx-auto max-w-3xl xl:mx-0">
+            <details
+              class="group mb-5 rounded-lg border border-border bg-sidebar lg:hidden"
+            >
+              <summary
+                class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-2.5 text-sm font-medium text-foreground [&::-webkit-details-marker]:hidden"
+              >
+                <span class="flex items-center gap-2">
+                  <svg
+                    class="h-4 w-4 text-muted-foreground"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    aria-hidden="true"
+                    ><path d="M4 6h16M4 12h16M4 18h16"></path></svg
+                  >
+                  Documentation menu
+                </span>
+                <svg
+                  class="h-4 w-4 text-muted-foreground transition-transform group-open:rotate-180"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  aria-hidden="true"><path d="m6 9 6 6 6-6"></path></svg
+                >
+              </summary>
+              <nav
+                class="border-t border-border px-3 py-3"
+                aria-label="Documentation navigation"
+              >
+                <ul>
+                  {
+                    sortedTopLevel.map((page: any) => (
+                      <DocsSidebarNav page={page} />
+                    ))
+                  }
+                </ul>
+              </nav>
+            </details>
+
+            <DocsBreadcrumbs items={crumbs} />
+
+            <article itemscope itemtype="https://schema.org/TechArticle">
+              <header class="mb-8 border-b border-border pb-7">
+                <h1
+                  class="text-[2.05rem] font-bold leading-[1.15] tracking-[-0.02em] text-foreground"
+                  itemprop="headline"
+                >
+                  {frontmatter.title}
+                </h1>
+                {
+                  frontmatter.description && (
+                    <p
+                      class="mt-3 text-lg leading-relaxed text-muted-foreground"
+                      itemprop="description"
+                    >
+                      {frontmatter.description}
+                    </p>
+                  )
+                }
+              </header>
+
+              <div class="prose" itemprop="articleBody">
+                <slot />
+              </div>
+            </article>
+          </div>
+        </main>
+
+        <DocsToc items={toc} />
+      </div>
+    </div>
+
+    <Footer />
+  </body>
+</html>
diff --git a/src/design-system/docs-shell/DocsHead.astro b/src/design-system/docs-shell/DocsHead.astro
new file mode 100644
index 0000000000..e6ac41d5fb
--- /dev/null
+++ b/src/design-system/docs-shell/DocsHead.astro
@@ -0,0 +1,135 @@
+---
+// HtmlHead minus main.css, for design-system pages (prevents legacy CSS bleed).
+import { Accelerator } from 'astro-accelerator-utils';
+import type { Frontmatter } from 'astro-accelerator-utils/types/Frontmatter';
+import { SITE, OPEN_GRAPH, HEADER_SCRIPTS } from '@config';
+import { getEligibleSlugs } from '@util/mdxContent';
+import JsonLd from '@components/JsonLd.astro';
+
+const accelerator = new Accelerator(SITE);
+const stats = new accelerator.statistics('octopus/components/HtmlHead.astro');
+stats.start();
+
+// Properties
+type Props = {
+  lang: string;
+  frontmatter: Frontmatter;
+  headings: { depth: number; slug: string; text: string }[];
+};
+const { frontmatter } = Astro.props;
+
+// Logic
+const imageSrc = frontmatter.bannerImage?.src ?? OPEN_GRAPH.image.src;
+const imageAlt = frontmatter.bannerImage?.alt ?? OPEN_GRAPH.image.alt;
+const robots = frontmatter.robots ?? 'index, follow';
+const canonicalImageSrc = new URL(imageSrc, Astro.site);
+const canonicalURL = accelerator.urlFormatter.formatUrl(
+  new URL(Astro.url.pathname, Astro.site + SITE.subfolder)
+);
+const socialTitle = await accelerator.markdown.getTextFrom(frontmatter?.title);
+const title = `${accelerator.markdown.titleCase(socialTitle)} ${frontmatter.titleAdditional ? ` ${frontmatter.titleAdditional}` : ''} | ${SITE.title}`;
+const pageMeta =
+  frontmatter?.meta && frontmatter?.meta?.length > 0 ? frontmatter.meta : [];
+
+const authorList = accelerator.authors.forPost(frontmatter);
+const authorMeta =
+  authorList.mainAuthor?.frontmatter?.meta &&
+  authorList.mainAuthor?.frontmatter?.meta?.length > 0
+    ? authorList.mainAuthor.frontmatter.meta
+    : [];
+
+const autoMeta = (name: string) => {
+  return pageMeta.filter((m) => m.name.toLowerCase() === name).length === 0;
+};
+
+const docsPath = Astro.url.pathname.replace(/\/$/, '');
+const subfolderPrefix = SITE.subfolder.replace(/\/$/, '') + '/';
+const docsSlug = docsPath.startsWith(subfolderPrefix)
+  ? docsPath.slice(subfolderPrefix.length)
+  : null;
+const eligibleSlugs = getEligibleSlugs();
+const markdownAlternateHref =
+  docsSlug && eligibleSlugs.has(docsSlug) ? SITE.url + docsPath + '.md' : null;
+
+stats.stop();
+---
+
+<head>
+  <meta charset="utf-8" />
+  <title>{title}</title>
+  <meta name="robots" content={'max-image-preview:large, ' + robots} />
+  <meta name="keywords" content={frontmatter.keywords} />
+  <meta name="description" content={frontmatter.description} />
+  <link rel="stylesheet" href={SITE.subfolder + '/css/vars.css'} />
+  <link rel="stylesheet" href={SITE.subfolder + '/css/footer-bundle.css'} />
+  {
+    autoMeta('viewport') && (
+      <meta
+        name="viewport"
+        content="width=device-width, initial-scale=1, minimum-scale=1"
+      />
+    )
+  }
+  {
+    autoMeta('format-detection') && (
+      <meta name="format-detection" content="telephone=no" />
+    )
+  }
+  {
+    autoMeta('theme-color') && (
+      <meta name="theme-color" content={SITE.themeColor} />
+    )
+  }
+  {autoMeta('canonical') && <link rel="canonical" href={canonicalURL} />}
+  {
+    markdownAlternateHref && (
+      <link rel="alternate" type="text/markdown" href={markdownAlternateHref} />
+    )
+  }
+  {
+    SITE.feedUrl && (
+      <link
+        rel="alternate"
+        type="application/atom+xml"
+        title={SITE.title}
+        href={SITE.feedUrl}
+      />
+    )
+  }
+  <link
+    rel="alternate"
+    href={SITE.subfolder + '/sitemap.xml'}
+    type="application/rss+xml"
+  />
+  <link
+    rel="shortcut icon"
+    href={SITE.subfolder + '/icons/favicon.ico'}
+    type="image/x-icon"
+  />
+  <link
+    rel="apple-touch-icon"
+    href={SITE.subfolder + '/icons/apple-touch-icon.png'}
+  />
+  <meta property="og:type" content="website" />
+  <meta property="og:url" content={canonicalURL} />
+  <meta property="og:title" content={socialTitle} />
+  <meta property="og:description" content={frontmatter.description} />
+  <meta property="og:image" content={canonicalImageSrc} />
+  <meta property="og:image:alt" content={imageAlt} />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content={socialTitle} />
+  <meta name="twitter:description" content={frontmatter.description} />
+  <meta name="twitter:image" content={canonicalImageSrc} />
+  <meta name="twitter:image:alt" content={imageAlt} />
+  <meta name="view-transition" content="same-origin" />
+  {pageMeta.map((m) => <meta name={m.name} content={m.content} />)}
+  {authorMeta.map((m) => <meta name={m.name} content={m.content} />)}
+  <JsonLd
+    frontmatter={frontmatter}
+    canonicalURL={canonicalURL.toString()}
+    socialTitle={socialTitle}
+    imageURL={canonicalImageSrc.toString()}
+    authors={authorList}
+  />
+  <Fragment set:html={HEADER_SCRIPTS} />
+</head>
diff --git a/src/design-system/docs-shell/DocsHeader.astro b/src/design-system/docs-shell/DocsHeader.astro
new file mode 100644
index 0000000000..63f2ac4927
--- /dev/null
+++ b/src/design-system/docs-shell/DocsHeader.astro
@@ -0,0 +1,344 @@
+---
+// Top navigation bar. The only JS is a tiny theme toggle (vanilla, no framework
+// runtime) to demonstrate dark mode - consistent with the zero-JS approach.
+import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
+---
+
+<header
+  data-component="DocsHeader"
+  class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur-md supports-[backdrop-filter]:bg-background/65"
+>
+  <!-- No left padding: the logo's left edge lines up with the sidebar column. -->
+  <div class="mx-auto flex h-16 max-w-[1600px] items-center gap-4 pr-4 lg:pr-6">
+    <!-- Brand: genuine Octopus wordmark (glyph stays brand blue; wordmark text
+         follows --foreground so it stays legible in both themes). -->
+    <a
+      href="/docs"
+      class="group mvp-brand flex shrink-0 items-center gap-2.5 rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+      style="--octopus-logo-text-color: var(--foreground);"
+    >
+      <OctopusLogo />
+      <span
+        class="hidden border-l border-border pl-2.5 text-[0.82rem] font-medium text-muted-foreground sm:inline-block"
+        >Docs</span
+      >
+    </a>
+
+    <!-- Search: type-ahead dropdown of matching docs (demo data, no backend). -->
+    <div class="mvp-search relative ml-2 hidden flex-1 max-w-md md:flex">
+      <label class="group relative w-full">
+        <span class="sr-only">Search documentation</span>
+        <svg
+          class="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground transition-colors group-focus-within:text-primary"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <circle cx="11" cy="11" r="8"></circle>
+          <path d="m21 21-4.3-4.3"></path>
+        </svg>
+        <input
+          id="mvp-search-input"
+          data-mvp-search-query
+          type="search"
+          role="combobox"
+          autocomplete="off"
+          aria-expanded="false"
+          aria-controls="mvp-search-results"
+          aria-autocomplete="list"
+          placeholder="Search documentation…"
+          class="h-9 w-full rounded-lg border border-input bg-muted/50 pl-9 pr-14 text-sm text-foreground transition-[background-color,border-color,box-shadow] placeholder:text-muted-foreground hover:border-border hover:bg-muted/70 focus:border-primary/50 focus:bg-background focus:outline-none focus:ring-2 focus:ring-ring/60"
+        />
+        <kbd
+          class="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 rounded-md border border-border bg-background/80 px-1.5 py-0.5 font-mono text-[10px] font-medium text-muted-foreground shadow-[var(--shadow-sm)]"
+          >⌘K</kbd
+        >
+      </label>
+
+      <!-- Results dropdown (populated by the inline script). -->
+      <div
+        id="mvp-search-panel"
+        data-mvp-search-panel
+        hidden
+        class="absolute left-0 right-0 top-[calc(100%+0.4rem)] z-50 overflow-hidden rounded-xl border border-border bg-popover shadow-[var(--shadow-lg)]"
+      >
+        <ul
+          id="mvp-search-results"
+          data-mvp-search-results
+          role="listbox"
+          aria-label="Search results"
+          class="max-h-80 overflow-y-auto py-1 [scrollbar-width:thin]"
+        >
+        </ul>
+        <p
+          data-mvp-search-empty
+          hidden
+          class="px-3.5 py-6 text-center text-sm text-muted-foreground"
+        >
+        </p>
+      </div>
+    </div>
+
+    <nav class="ml-auto flex items-center gap-1">
+      <a
+        href="https://octopus.com"
+        class="hidden h-9 items-center rounded-md px-3 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:inline-flex"
+        >octopus.com</a
+      >
+      <span class="mx-1 hidden h-5 w-px bg-border sm:block" aria-hidden="true"
+      ></span>
+      <button
+        id="mvp-theme-toggle"
+        type="button"
+        aria-label="Toggle dark mode"
+        class="grid h-9 w-9 place-items-center rounded-md border border-border text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <svg
+          class="block dark:hidden"
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          ><circle cx="12" cy="12" r="4"></circle><path
+            d="M12 2v2m0 16v2M4.93 4.93l1.41 1.41m11.32 11.32 1.41 1.41M2 12h2m16 0h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41"
+          ></path></svg
+        >
+        <svg
+          class="hidden dark:block"
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          ><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path></svg
+        >
+      </button>
+      <a
+        href="https://octopus.com/start"
+        class="ml-1.5 hidden h-9 items-center gap-1.5 rounded-md bg-accent px-3.5 text-[0.8rem] font-semibold text-accent-foreground outline-none ring-1 ring-inset ring-black/5 transition-[background-color,box-shadow,transform] hover:bg-accent/90 hover:shadow-[var(--shadow-sm)] active:translate-y-px focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background sm:inline-flex"
+        >Start free trial</a
+      >
+    </nav>
+  </div>
+</header>
+
+<style is:global>
+  .mvp-brand .octo-header__logo {
+    height: 3.125rem;
+    width: auto;
+    display: block;
+    transition: opacity 0.2s ease;
+  }
+  .mvp-brand:hover .octo-header__logo {
+    opacity: 0.88;
+  }
+</style>
+
+<script is:inline>
+  (() => {
+    const root = document.documentElement;
+    const stored = localStorage.getItem('mvp-theme');
+    if (stored === 'dark') root.setAttribute('data-theme', 'dark');
+    document
+      .getElementById('mvp-theme-toggle')
+      ?.addEventListener('click', () => {
+        const dark = root.getAttribute('data-theme') === 'dark';
+        if (dark) {
+          root.removeAttribute('data-theme');
+          localStorage.setItem('mvp-theme', 'light');
+        } else {
+          root.setAttribute('data-theme', 'dark');
+          localStorage.setItem('mvp-theme', 'dark');
+        }
+      });
+  })();
+</script>
+
+<script is:inline>
+  (() => {
+    const input = document.querySelector('[data-mvp-search-query]');
+    const panel = document.querySelector('[data-mvp-search-panel]');
+    const list = document.querySelector('[data-mvp-search-results]');
+    const empty = document.querySelector('[data-mvp-search-empty]');
+    if (!input || !panel || !list || !empty) return;
+
+    const docs = [
+      { title: 'Deploying a release', section: 'Getting started › Deployments', href: '#' },
+      { title: 'Your first project', section: 'Getting started', href: '#' },
+      { title: 'Installation', section: 'Getting started', href: '#' },
+      { title: 'Environments', section: 'Getting started', href: '#' },
+      { title: 'Deployment process', section: 'Deployments', href: '#' },
+      { title: 'Variables', section: 'Deployments › Configuration', href: '#' },
+      { title: 'Releases & channels', section: 'Deployments', href: '#' },
+      { title: 'Runbooks', section: 'Deployments › Operations', href: '#' },
+      { title: 'Deployment targets', section: 'Infrastructure', href: '#' },
+      { title: 'Workers', section: 'Infrastructure', href: '#' },
+      { title: 'Accounts', section: 'Infrastructure › Security', href: '#' },
+      { title: 'Tenants & multi-tenancy', section: 'Tenants', href: '#' },
+      { title: 'Octopus CLI reference', section: 'Automation', href: '#' },
+      { title: 'Lifecycles & phases', section: 'Deployments › Lifecycles', href: '#' },
+    ];
+
+    let results = [];
+    let active = -1;
+
+    const docIcon = () => {
+      const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      svg.setAttribute('viewBox', '0 0 24 24');
+      svg.setAttribute('fill', 'none');
+      svg.setAttribute('stroke', 'currentColor');
+      svg.setAttribute('stroke-width', '2');
+      svg.setAttribute('stroke-linecap', 'round');
+      svg.setAttribute('stroke-linejoin', 'round');
+      svg.setAttribute('aria-hidden', 'true');
+      svg.setAttribute('class', 'mt-0.5 h-4 w-4 shrink-0 text-muted-foreground');
+      const p1 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      p1.setAttribute('d', 'M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z');
+      const p2 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      p2.setAttribute('d', 'M14 2v6h6');
+      svg.append(p1, p2);
+      return svg;
+    };
+
+    const titleNode = (title, q) => {
+      const span = document.createElement('span');
+      span.className = 'block truncate text-foreground';
+      const i = q ? title.toLowerCase().indexOf(q.toLowerCase()) : -1;
+      if (i < 0) {
+        span.textContent = title;
+        return span;
+      }
+      span.append(document.createTextNode(title.slice(0, i)));
+      const mark = document.createElement('mark');
+      mark.className = 'bg-transparent font-semibold text-primary';
+      mark.textContent = title.slice(i, i + q.length);
+      span.append(mark, document.createTextNode(title.slice(i + q.length)));
+      return span;
+    };
+
+    const close = () => {
+      panel.hidden = true;
+      input.setAttribute('aria-expanded', 'false');
+      input.removeAttribute('aria-activedescendant');
+      active = -1;
+    };
+
+    const setActive = (idx) => {
+      const items = list.querySelectorAll('[role="option"]');
+      items.forEach((el, i) => {
+        const on = i === idx;
+        el.setAttribute('aria-selected', on ? 'true' : 'false');
+        el.classList.toggle('bg-muted', on);
+        if (on) el.scrollIntoView({ block: 'nearest' });
+      });
+      active = idx;
+      if (idx >= 0 && items[idx])
+        input.setAttribute('aria-activedescendant', items[idx].id);
+      else input.removeAttribute('aria-activedescendant');
+    };
+
+    const render = (q) => {
+      const query = q.trim();
+      if (!query) {
+        close();
+        return;
+      }
+      results = docs.filter(
+        (d) =>
+          d.title.toLowerCase().includes(query.toLowerCase()) ||
+          d.section.toLowerCase().includes(query.toLowerCase())
+      );
+      panel.hidden = false;
+      input.setAttribute('aria-expanded', 'true');
+      list.replaceChildren();
+
+      if (!results.length) {
+        empty.hidden = false;
+        empty.textContent = 'No results for “' + query + '”';
+        setActive(-1);
+        return;
+      }
+      empty.hidden = true;
+      results.forEach((d, i) => {
+        const li = document.createElement('li');
+        li.id = 'mvp-search-opt-' + i;
+        li.setAttribute('role', 'option');
+        li.setAttribute('aria-selected', 'false');
+        li.className =
+          'mx-1 flex cursor-pointer items-start gap-2.5 rounded-lg px-3 py-2 text-sm hover:bg-muted';
+        const text = document.createElement('span');
+        text.className = 'min-w-0';
+        const sec = document.createElement('span');
+        sec.className = 'mt-0.5 block truncate text-[0.75rem] text-muted-foreground';
+        sec.textContent = d.section;
+        text.append(titleNode(d.title, query), sec);
+        li.append(docIcon(), text);
+        list.append(li);
+      });
+      setActive(0);
+    };
+
+    const go = (idx) => {
+      const d = results[idx];
+      if (d) window.location.hash = d.href.startsWith('#') ? d.href.slice(1) : '';
+      close();
+    };
+
+    input.addEventListener('input', () => render(input.value));
+    input.addEventListener('focus', () => {
+      if (input.value.trim()) render(input.value);
+    });
+
+    input.addEventListener('keydown', (e) => {
+      if (panel.hidden) return;
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        if (results.length) setActive((active + 1) % results.length);
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        if (results.length)
+          setActive((active - 1 + results.length) % results.length);
+      } else if (e.key === 'Enter') {
+        if (active >= 0) {
+          e.preventDefault();
+          go(active);
+        }
+      } else if (e.key === 'Escape') {
+        close();
+        input.blur();
+      }
+    });
+
+    list.addEventListener('mousedown', (e) => {
+      const opt = e.target.closest('[role="option"]');
+      if (!opt) return;
+      e.preventDefault();
+      const items = Array.from(list.querySelectorAll('[role="option"]'));
+      go(items.indexOf(opt));
+    });
+
+    document.addEventListener('click', (e) => {
+      if (!e.target.closest('.mvp-search')) close();
+    });
+
+    document.addEventListener('keydown', (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        input.focus();
+        input.select();
+      }
+    });
+  })();
+</script>
diff --git a/src/design-system/docs-shell/DocsLayout.astro b/src/design-system/docs-shell/DocsLayout.astro
new file mode 100644
index 0000000000..3ded990fee
--- /dev/null
+++ b/src/design-system/docs-shell/DocsLayout.astro
@@ -0,0 +1,115 @@
+---
+import '../theme.css';
+import DocsHeader from './DocsHeader.astro';
+import DocsSidebar from './DocsSidebar.astro';
+import DocsToc from './DocsToc.astro';
+import DocsBreadcrumbs from './DocsBreadcrumbs.astro';
+import Footer from '../../components/Footer.astro';
+
+interface Props {
+  title: string;
+  description?: string;
+  breadcrumbs: { label: string; href?: string }[];
+  sidebar: { title: string; items: { label: string; href: string; active?: boolean }[] }[];
+  toc: { label: string; href: string; depth?: number }[];
+}
+
+const { title, description, breadcrumbs, sidebar, toc } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title} · Octopus Docs</title>
+    {description && <meta name="description" content={description} />}
+    <!-- Shared footer styles (footer remains the existing shared component) -->
+    <link rel="stylesheet" href="/docs/css/footer-bundle.css" />
+    <!-- Avoid dark-mode flash before the toggle script runs -->
+    <script is:inline>
+      if (localStorage.getItem('mvp-theme') === 'dark')
+        document.documentElement.setAttribute('data-theme', 'dark');
+    </script>
+  </head>
+  <body class="min-h-screen bg-background font-sans text-foreground antialiased">
+    <DocsHeader />
+
+    <div class="mx-auto flex max-w-[1600px]">
+      <DocsSidebar sections={sidebar} />
+
+      <div class="flex min-w-0 flex-1">
+        <main class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-14">
+          <div class="mx-auto max-w-3xl xl:mx-0">
+            <details class="group mb-5 rounded-lg border border-border bg-sidebar lg:hidden">
+              <summary
+                class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-2.5 text-sm font-medium text-foreground [&::-webkit-details-marker]:hidden"
+              >
+                <span class="flex items-center gap-2">
+                  <svg class="h-4 w-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16"></path></svg>
+                  Documentation menu
+                </span>
+                <svg class="h-4 w-4 text-muted-foreground transition-transform group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"></path></svg>
+              </summary>
+              <nav class="border-t border-border px-3 py-3" aria-label="Documentation navigation">
+                {sidebar.map((section) => (
+                  <div class="mb-3 last:mb-0">
+                    <p class="mb-1 px-2 text-[0.72rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground/70">
+                      {section.title}
+                    </p>
+                    <ul class="space-y-px">
+                      {section.items.map((item) => (
+                        <li>
+                          <a
+                            href={item.href}
+                            aria-current={item.active ? 'page' : undefined}
+                            class={`block rounded-md px-2 py-1.5 text-[0.925rem] transition-colors ${
+                              item.active
+                                ? 'bg-primary/10 font-medium text-primary'
+                                : 'text-sidebar-foreground hover:bg-muted hover:text-foreground'
+                            }`}
+                          >
+                            {item.label}
+                          </a>
+                        </li>
+                      ))}
+                    </ul>
+                  </div>
+                ))}
+              </nav>
+            </details>
+
+            <DocsBreadcrumbs items={breadcrumbs} />
+
+            <article itemscope itemtype="https://schema.org/TechArticle">
+              <header class="mb-8 border-b border-border pb-7">
+                <h1
+                  class="text-[2.05rem] font-bold leading-[1.15] tracking-[-0.02em] text-foreground"
+                  itemprop="headline"
+                >
+                  {title}
+                </h1>
+                {description && (
+                  <p
+                    class="mt-3 text-lg leading-relaxed text-muted-foreground"
+                    itemprop="description"
+                  >
+                    {description}
+                  </p>
+                )}
+              </header>
+
+              <div class="prose" itemprop="articleBody">
+                <slot />
+              </div>
+            </article>
+          </div>
+        </main>
+
+        <DocsToc items={toc} />
+      </div>
+    </div>
+
+    <Footer />
+  </body>
+</html>
diff --git a/src/design-system/docs-shell/DocsSidebar.astro b/src/design-system/docs-shell/DocsSidebar.astro
new file mode 100644
index 0000000000..9d4edc19c4
--- /dev/null
+++ b/src/design-system/docs-shell/DocsSidebar.astro
@@ -0,0 +1,51 @@
+---
+interface NavItem {
+  label: string;
+  href: string;
+  active?: boolean;
+}
+interface NavSection {
+  title: string;
+  items: NavItem[];
+}
+interface Props {
+  sections: NavSection[];
+}
+const { sections } = Astro.props;
+---
+
+<aside
+  class="hidden lg:block w-64 shrink-0 border-r border-border bg-sidebar"
+  aria-label="Documentation navigation"
+>
+  <nav
+    class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3 py-6 [scrollbar-width:thin]"
+  >
+    {
+      sections.map((section, si) => (
+        <div class={si === sections.length - 1 ? '' : 'mb-5'}>
+          <p class="mb-1.5 px-2.5 text-[0.72rem] font-semibold uppercase tracking-[0.09em] text-muted-foreground/65">
+            {section.title}
+          </p>
+          <ul>
+            {section.items.map((item) => (
+              <li>
+                <a
+                  href={item.href}
+                  aria-current={item.active ? 'page' : undefined}
+                  class={`relative block rounded-md py-[0.35rem] pl-2.5 pr-2 text-[0.925rem] leading-snug outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
+                    item.active
+                      ? 'bg-primary/[0.09] font-medium text-primary before:absolute before:inset-y-[0.35rem] before:-left-3 before:w-[2px] before:rounded-r-full before:bg-primary'
+                      : 'text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+                  }`}
+                >
+                  {item.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))
+    }
+  </nav>
+</aside>
diff --git a/src/design-system/docs-shell/DocsSidebarNav.astro b/src/design-system/docs-shell/DocsSidebarNav.astro
new file mode 100644
index 0000000000..ff0b93442a
--- /dev/null
+++ b/src/design-system/docs-shell/DocsSidebarNav.astro
@@ -0,0 +1,94 @@
+---
+// Recursive nav renderer for the real Octopus nav tree (NavPage[]).
+// Reuses DocsSidebar's visual language (eyebrow section labels, active-item
+// indicator, focus rings) but renders nested native <details> sections.
+// Zero-JS: collapsible state is native <details open>.
+import { Accelerator } from 'astro-accelerator-utils';
+import type { NavPage } from 'astro-accelerator-utils/types/NavPage';
+import { SITE } from '@config';
+
+const accelerator = new Accelerator(SITE);
+
+type Props = {
+  page: NavPage;
+  depth?: number;
+};
+const { page, depth = 0 } = Astro.props satisfies Props;
+
+const displayLink = page.title != null;
+const linkTitle = page.title === page.fullTitle ? null : page.fullTitle;
+const children = page.children.slice().sort((a, b) => a.order - b.order);
+---
+
+{
+  displayLink && page.children.length === 0 && (
+    <li data-component="DocsSidebarNav">
+      <a
+        href={accelerator.urlFormatter.formatAddress(page.url)}
+        aria-current={page.ariaCurrent ? page.ariaCurrent : undefined}
+        rel={page.rel}
+        title={linkTitle}
+        class={`relative flex items-center justify-between gap-2 rounded-md py-[0.35rem] pr-2 text-[0.925rem] leading-snug outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
+          depth > 0 ? 'pl-3' : 'pl-2'
+        } ${
+          page.ariaCurrent
+            ? 'bg-primary/[0.09] font-medium text-primary before:absolute before:inset-y-[0.35rem] before:-left-1 before:w-[2px] before:rounded-r-full before:bg-primary'
+            : 'text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+        }`}
+      >
+        <span class="truncate">{page.title}</span>
+        {depth === 0 && (
+          <svg
+            class="h-3.5 w-3.5 shrink-0 text-muted-foreground/45"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+        )}
+      </a>
+    </li>
+  )
+}
+{
+  displayLink && page.children.length > 0 && (
+    <li data-component="DocsSidebarNav">
+      <details
+        open={page.isOpen}
+        class={`group ${depth === 0 ? 'mb-4 last:mb-0' : 'mt-px'}`}
+      >
+        <summary
+          class={`flex cursor-pointer list-none items-center justify-between gap-2 rounded-md pl-2 pr-2 outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-webkit-details-marker]:hidden ${
+            depth === 0
+              ? 'mb-1 py-1 text-[0.73rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground'
+              : 'py-[0.35rem] text-[0.925rem] font-medium leading-snug text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+          }`}
+        >
+          <span>{page.section}</span>
+          <svg
+            class="h-3.5 w-3.5 shrink-0 text-muted-foreground/70 transition-transform group-open:rotate-90"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+        </summary>
+        <ul class={depth === 0 ? '' : 'ml-2 border-l border-border/70 pl-1.5'}>
+          {children.map((child) => (
+            <Astro.self page={child} depth={depth + 1} />
+          ))}
+        </ul>
+      </details>
+    </li>
+  )
+}
diff --git a/src/design-system/docs-shell/DocsToc.astro b/src/design-system/docs-shell/DocsToc.astro
new file mode 100644
index 0000000000..ff8cabe7a4
--- /dev/null
+++ b/src/design-system/docs-shell/DocsToc.astro
@@ -0,0 +1,85 @@
+---
+interface TocItem {
+  label: string;
+  href: string;
+  depth?: number;
+}
+interface Props {
+  items: TocItem[];
+}
+const { items } = Astro.props;
+---
+
+<aside class="hidden xl:block w-56 shrink-0" aria-label="On this page" data-component="DocsToc">
+  <nav class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto py-14 pl-6">
+    <p
+      class="mb-3 flex items-center gap-2 text-[0.74rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground/70"
+    >
+      <svg
+        class="h-3.5 w-3.5"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"></path>
+      </svg>
+      On this page
+    </p>
+    <ul class="space-y-0.5 border-l border-border" data-toc>
+      {
+        items.map((item) => (
+          <li>
+            <a
+              href={item.href}
+              data-toc-link
+              class={`-ml-px block border-l-2 border-transparent py-[0.3rem] text-[0.875rem] leading-snug text-muted-foreground transition-colors duration-150 hover:border-primary/50 hover:text-foreground aria-[current=true]:border-primary aria-[current=true]:font-medium aria-[current=true]:text-primary ${
+                item.depth === 2 ? 'pl-7' : 'pl-4'
+              }`}
+            >
+              {item.label}
+            </a>
+          </li>
+        ))
+      }
+    </ul>
+  </nav>
+</aside>
+
+<script is:inline>
+  (() => {
+    const links = Array.from(document.querySelectorAll('[data-toc-link]'));
+    if (!links.length) return;
+    const byId = new Map();
+    const targets = [];
+    for (const link of links) {
+      const id = link.getAttribute('href')?.slice(1);
+      if (!id) continue;
+      const el = document.getElementById(id);
+      if (el) {
+        byId.set(id, link);
+        targets.push(el);
+      }
+    }
+    let current = null;
+    const setActive = (id) => {
+      if (id === current) return;
+      current = id;
+      for (const [lid, link] of byId)
+        link.setAttribute('aria-current', lid === id ? 'true' : 'false');
+    };
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+        if (visible.length) setActive(visible[0].target.id);
+      },
+      { rootMargin: '-88px 0px -65% 0px', threshold: 0 }
+    );
+    targets.forEach((t) => observer.observe(t));
+  })();
+</script>
diff --git a/src/design-system/theme.css b/src/design-system/theme.css
new file mode 100644
index 0000000000..c54de458c1
--- /dev/null
+++ b/src/design-system/theme.css
@@ -0,0 +1,512 @@
+/*
+  Design-system entry (MVP). Importing this file is what opts a page into the
+  new UI: it pulls Tailwind v4, the typography plugin, the brand tokens, and
+  maps those tokens into Tailwind's theme so utilities like `bg-background`,
+  `text-foreground`, `border-border`, `text-primary` resolve to brand values.
+
+  Nothing here leaks onto pages that don't import it.
+*/
+
+@import 'tailwindcss';
+@import './tokens.css';
+@plugin '@tailwindcss/typography';
+
+/* Dark mode is driven by the existing [data-theme="dark"] attribute, not a class. */
+@custom-variant dark (&:where([data-theme='dark'], [data-theme='dark'] *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-surface: var(--surface);
+  --color-surface-2: var(--surface-2);
+
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  --shadow-sm: var(--shadow-sm);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+}
+
+/* Reserve the vertical scrollbar gutter from first paint so a late-appearing
+   scrollbar (e.g. after images load) can't narrow the viewport and shift the
+   centered header/content sideways. */
+html {
+  scrollbar-gutter: stable;
+}
+
+/* Tune the `prose` typography plugin to brand tokens so markdown content
+   matches the design system without bespoke per-element CSS.
+
+   These rules are intentionally UNLAYERED: the typography plugin sets its
+   default `--tw-prose-*` color vars from the `prose` utility (utilities layer),
+   which would beat an `@layer base` override. Unlayered rules win over any
+   layered rule, so this is what makes our brand tokens (and dark mode) stick. */
+.prose {
+  --tw-prose-body: var(--foreground);
+  --tw-prose-headings: var(--foreground);
+  --tw-prose-links: var(--primary);
+  --tw-prose-bold: var(--foreground);
+  --tw-prose-counters: var(--muted-foreground);
+  --tw-prose-bullets: var(--octo-navy-300);
+  --tw-prose-hr: var(--border);
+  --tw-prose-quotes: var(--muted-foreground);
+  --tw-prose-quote-borders: var(--primary);
+  --tw-prose-captions: var(--muted-foreground);
+  --tw-prose-code: var(--foreground);
+  --tw-prose-th-borders: var(--border);
+  --tw-prose-td-borders: var(--border);
+  --tw-prose-pre-bg: var(--code-bg);
+  --tw-prose-pre-code: var(--code-foreground);
+  max-width: 46rem;
+  font-size: 1rem;
+  line-height: 1.75;
+}
+
+/* Typographic rhythm: calmer vertical spacing and tighter, confident headings. */
+.prose :where(h2):not(:where([class~='not-prose'] *)) {
+  margin-top: 2.75rem;
+  margin-bottom: 1rem;
+  font-size: 1.5rem;
+  line-height: 1.3;
+  font-weight: 650;
+  letter-spacing: -0.014em;
+  scroll-margin-top: 5.5rem;
+}
+.prose :where(h3):not(:where([class~='not-prose'] *)) {
+  margin-top: 2rem;
+  margin-bottom: 0.625rem;
+  font-size: 1.2rem;
+  line-height: 1.35;
+  font-weight: 625;
+  letter-spacing: -0.01em;
+  scroll-margin-top: 5.5rem;
+}
+.prose :where(h2, h3):not(:where([class~='not-prose'] *)):first-child {
+  margin-top: 0;
+}
+.prose :where(p, ul, ol):not(:where([class~='not-prose'] *)) {
+  margin-top: 0;
+  margin-bottom: 1.25rem;
+}
+.prose :where(strong):not(:where([class~='not-prose'] *)) {
+  font-weight: 625;
+}
+.prose :where(a):not(:where([class~='not-prose'] *)) {
+  font-weight: 500;
+  text-decoration-color: color-mix(in oklab, var(--primary) 35%, transparent);
+  text-underline-offset: 2px;
+  transition:
+    text-decoration-color 0.15s ease,
+    color 0.15s ease;
+}
+.prose :where(a):not(:where([class~='not-prose'] *)):hover {
+  text-decoration-color: var(--primary);
+}
+
+/* Lists: tidy markers and spacing. */
+.prose :where(ol > li, ul > li):not(:where([class~='not-prose'] *)) {
+  margin-top: 0.375rem;
+  margin-bottom: 0.375rem;
+  padding-left: 0.4em;
+}
+.prose :where(ol > li)::marker:not(:where([class~='not-prose'] *)) {
+  font-weight: 600;
+  color: var(--muted-foreground);
+}
+
+/* Horizontal rule */
+.prose :where(hr):not(:where([class~='not-prose'] *)) {
+  margin-top: 3rem;
+  margin-bottom: 3rem;
+}
+
+/* --- Code block treatment: a calm bordered surface with a slim label bar.
+   Inspired by Stripe/Vercel/Linear docs - the code is the hero, the chrome is
+   quiet. The label bar (filename/language) and copy affordance live in a
+   `figure.code-block` wrapper rendered alongside the <pre>. */
+.prose :where(pre):not(:where([class~='not-prose'] *)) {
+  position: relative;
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  padding: 1.15rem 1.25rem;
+  background: var(--code-bg);
+  color: var(--code-foreground);
+  border: 1px solid var(--code-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+  font-size: 0.875rem;
+  line-height: 1.75;
+  overflow-x: auto;
+}
+.prose :where(pre code):not(:where([class~='not-prose'] *)) {
+  background: transparent;
+  padding: 0;
+  font-weight: 400;
+  font-size: inherit;
+  color: inherit;
+}
+
+/* Code-block wrapper: slim top bar + bordered body sharing one frame. */
+.prose :where(.code-block):not(:where([class~='not-prose'] *)) {
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  border: 1px solid var(--code-border);
+  border-radius: var(--radius-lg);
+  background: var(--code-bg);
+  box-shadow: var(--shadow-sm);
+  overflow: hidden;
+}
+.code-block > .code-block__bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 2.5rem;
+  padding: 0 0.5rem 0 0.9rem;
+  background: var(--code-chrome);
+  border-bottom: 1px solid var(--code-border);
+}
+.code-block__label {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  letter-spacing: 0.02em;
+  font-weight: 500;
+  color: color-mix(in oklab, var(--code-foreground) 62%, transparent);
+}
+.code-block__label svg {
+  width: 0.85rem;
+  height: 0.85rem;
+  color: color-mix(in oklab, var(--code-foreground) 45%, transparent);
+}
+/* When wrapped (figure is .not-prose), the inner <pre> is excluded from the
+   prose pre rules, so re-apply the code surface here and drop the outer frame -
+   the figure provides it. */
+.code-block > pre {
+  margin: 0;
+  padding: 1.15rem 1.25rem;
+  border: 0;
+  border-radius: 0;
+  box-shadow: none;
+  background: var(--code-bg);
+  color: var(--code-foreground);
+  font-family: var(--font-mono);
+  font-size: 0.875rem;
+  line-height: 1.75;
+  overflow-x: auto;
+}
+.code-block > pre code {
+  background: transparent;
+  padding: 0;
+  font-weight: 400;
+  font-size: inherit;
+  color: inherit;
+}
+/* Copy affordance: a quiet button that brightens to brand on interaction. */
+.code-block__copy {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  height: 1.75rem;
+  padding: 0 0.55rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: color-mix(in oklab, var(--code-foreground) 55%, transparent);
+  font-family: var(--font-sans);
+  font-size: 0.72rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease,
+    border-color 0.15s ease;
+}
+.code-block__copy svg {
+  width: 0.85rem;
+  height: 0.85rem;
+}
+.code-block__copy:hover {
+  color: var(--code-foreground);
+  background: color-mix(in oklab, var(--code-foreground) 10%, transparent);
+}
+.code-block__copy:focus-visible {
+  outline: none;
+  border-color: color-mix(in oklab, var(--primary) 55%, transparent);
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 55%, transparent);
+}
+.code-block__copy[data-copied] {
+  color: var(--accent);
+}
+.code-block__copy-idle,
+.code-block__copy-done {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+.code-block__copy-done {
+  display: none;
+}
+.code-block__copy[data-copied] .code-block__copy-idle {
+  display: none;
+}
+.code-block__copy[data-copied] .code-block__copy-done {
+  display: inline-flex;
+}
+
+/* --- Tables: zebra + hover, token-aligned borders, refined header --- */
+.prose :where(table):not(:where([class~='not-prose'] *)) {
+  width: 100%;
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  border-collapse: separate;
+  border-spacing: 0;
+  overflow: hidden;
+  font-size: 0.95rem;
+}
+.prose :where(thead):not(:where([class~='not-prose'] *)) {
+  background: var(--muted);
+  border-bottom: 1px solid var(--border);
+}
+.prose :where(thead th):not(:where([class~='not-prose'] *)) {
+  padding: 0.7rem 1rem;
+  font-size: 0.82rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--muted-foreground);
+  border-bottom: 1px solid var(--border);
+}
+.prose :where(tbody td):not(:where([class~='not-prose'] *)) {
+  padding: 0.7rem 1rem;
+  border-bottom: 1px solid var(--border);
+  vertical-align: middle;
+}
+.prose :where(tbody tr:last-child td):not(:where([class~='not-prose'] *)) {
+  border-bottom: 0;
+}
+.prose :where(tbody tr):not(:where([class~='not-prose'] *)):nth-child(even) {
+  background: color-mix(in oklab, var(--muted) 45%, transparent);
+}
+.prose :where(tbody tr):not(:where([class~='not-prose'] *)):hover {
+  background: color-mix(in oklab, var(--primary) 6%, transparent);
+}
+
+/* Inline code chips, brand-tinted */
+.prose :not(pre) > code {
+  background: color-mix(in oklab, var(--muted) 70%, var(--background));
+  color: var(--foreground);
+  border: 1px solid var(--border);
+  padding: 0.1em 0.4em;
+  border-radius: var(--radius-sm);
+  font-weight: 500;
+  font-size: 0.8125em;
+  white-space: nowrap;
+}
+.prose :not(pre) > code::before,
+.prose :not(pre) > code::after {
+  content: none;
+}
+
+/* Status pills (used in tables to render state cells tastefully) */
+.status-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.15rem 0.6rem 0.15rem 0.5rem;
+  border-radius: 9999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1.4;
+  white-space: nowrap;
+  border: 1px solid transparent;
+}
+.status-dot {
+  width: 0.45rem;
+  height: 0.45rem;
+  border-radius: 9999px;
+  background: currentColor;
+  box-shadow: 0 0 0 3px color-mix(in oklab, currentColor 22%, transparent);
+}
+.status-pill--ok {
+  color: var(--success-border);
+  background: color-mix(in oklab, var(--success-border) 12%, var(--background));
+  border-color: color-mix(in oklab, var(--success-border) 30%, transparent);
+}
+.status-pill--wait {
+  color: var(--warning-border);
+  background: color-mix(in oklab, var(--warning-border) 12%, var(--background));
+  border-color: color-mix(in oklab, var(--warning-border) 30%, transparent);
+}
+
+/* --- Callout boxes (remark directive output) ---
+   Authored as `:::div{.hint|.info|.success|.warning|.problem|.question}` and
+   rendered as raw `<div class="...">` inside .prose. Match ui/Callout.astro:
+   soft border + stronger left accent, tinted bg, comfortable padding. */
+.prose
+  :where(
+    div.hint,
+    div.info,
+    div.success,
+    div.warning,
+    div.problem,
+    div.question
+  ):not(:where([class~='not-prose'] *)) {
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  padding: 0.95rem 1.1rem;
+  border: 1px solid color-mix(in oklab, var(--bd) 35%, transparent);
+  border-left: 3px solid var(--bd);
+  border-radius: var(--radius-lg);
+  background: var(--bg);
+  color: var(--c);
+  font-size: 0.95rem;
+  line-height: 1.65;
+}
+/* Intent token mapping (hint -> info/blue, question -> neutral/muted). */
+.prose :where(div.hint, div.info):not(:where([class~='not-prose'] *)) {
+  --c: var(--info);
+  --bg: var(--info-bg);
+  --bd: var(--info-border);
+}
+.prose :where(div.success):not(:where([class~='not-prose'] *)) {
+  --c: var(--success);
+  --bg: var(--success-bg);
+  --bd: var(--success-border);
+}
+.prose :where(div.warning):not(:where([class~='not-prose'] *)) {
+  --c: var(--warning);
+  --bg: var(--warning-bg);
+  --bd: var(--warning-border);
+}
+.prose :where(div.problem):not(:where([class~='not-prose'] *)) {
+  --c: var(--problem);
+  --bg: var(--problem-bg);
+  --bd: var(--problem-border);
+}
+.prose :where(div.question):not(:where([class~='not-prose'] *)) {
+  --c: var(--question);
+  --bg: var(--question-bg);
+  --bd: var(--question-border);
+}
+/* Tighten internal spacing and inherit the intent text color. */
+.prose
+  :where(
+    div.hint,
+    div.info,
+    div.success,
+    div.warning,
+    div.problem,
+    div.question
+  )
+  :where(p):not(:where([class~='not-prose'] *)) {
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+  color: inherit;
+}
+.prose
+  :where(
+    div.hint,
+    div.info,
+    div.success,
+    div.warning,
+    div.problem,
+    div.question
+  )
+  :where(p:first-child):not(:where([class~='not-prose'] *)) {
+  margin-top: 0;
+}
+.prose
+  :where(
+    div.hint,
+    div.info,
+    div.success,
+    div.warning,
+    div.problem,
+    div.question
+  )
+  :where(p:last-child):not(:where([class~='not-prose'] *)) {
+  margin-bottom: 0;
+}
+
+/* --- Figures / images (remark `:::figure` directive output) ---
+   Rendered with .image (figure), .image__img (img), .image__caption (caption).
+   Center, constrain, round, subtle border; keep responsive srcset intact. */
+.prose :where(figure, .image):not(:where([class~='not-prose'] *)) {
+  margin-top: 1.75rem;
+  margin-bottom: 1.75rem;
+  text-align: center;
+}
+.prose :where(figure > p):not(:where([class~='not-prose'] *)) {
+  margin: 0;
+}
+.prose :where(img, .image__img):not(:where([class~='not-prose'] *)) {
+  display: inline-block;
+  max-width: 100%;
+  height: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+}
+.prose :where(.image__caption):not(:where([class~='not-prose'] *)) {
+  display: block;
+  margin-top: 0.65rem;
+  text-align: center;
+  color: var(--muted-foreground);
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
+/* --- Table wrapper (wrapTables -> <div class="table-wrap">) ---
+   Allow horizontal scroll on overflow; the inner table keeps its own border. */
+.prose :where(.table-wrap):not(:where([class~='not-prose'] *)) {
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  overflow-x: auto;
+}
+.prose :where(.table-wrap > table):not(:where([class~='not-prose'] *)) {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+/* --- Shiki code blocks (`<pre class="astro-code ...">`) ---
+   Give our frame (border + radius + padding) but leave Shiki's inline bg/colors
+   alone. Known: this renders light against our dark code surface - deferred. */
+.prose :where(pre.astro-code):not(:where([class~='not-prose'] *)) {
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+  padding: 1.15rem 1.25rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+  font-size: 0.875rem;
+  line-height: 1.7;
+  overflow-x: auto;
+}
diff --git a/src/design-system/tokens.css b/src/design-system/tokens.css
new file mode 100644
index 0000000000..f864ab123a
--- /dev/null
+++ b/src/design-system/tokens.css
@@ -0,0 +1,162 @@
+/*
+  Octopus docs design-system tokens (MVP).
+
+  This is the portable contract: brand primitives + shadcn-style semantic tokens,
+  light + dark. A microsite adopts the design system by shipping this file (and
+  theme.css) unchanged. Dark mode keys off [data-theme="dark"] to match the
+  existing site switch.
+
+  Brand source of truth: public/docs/css/vars.css.
+*/
+
+:root {
+  /* --- Brand primitives (from vars.css) --- */
+  --octo-blue: #1a77ca;
+  --octo-blue-light: #2f95e3;
+  --octo-blue-bright: #1fc0ff;
+  --octo-green: #00e693;
+  --octo-green-bright: #00ffa3;
+  --octo-navy-900: #10212f;
+  --octo-navy-800: #152b3d;
+  --octo-navy-700: #2e475d;
+  --octo-navy-600: #3e607d;
+  --octo-navy-400: #7c98b4;
+  --octo-navy-300: #a9bbcb;
+  --octo-navy-200: #dae2e9;
+  --octo-navy-100: #f4f6f8;
+  --octo-blue-100: #f2f8fd;
+
+  /* --- Semantic tokens (shadcn shape) --- */
+  --background: #ffffff;
+  --foreground: var(--octo-navy-900);
+
+  --card: #ffffff;
+  --card-foreground: var(--octo-navy-900);
+
+  --popover: #ffffff;
+  --popover-foreground: var(--octo-navy-900);
+
+  --primary: var(--octo-blue);
+  --primary-foreground: #ffffff;
+
+  /* Octopus CTA green is the brand "accent" action color */
+  --accent: var(--octo-green);
+  --accent-foreground: #0a3b2a;
+
+  --secondary: var(--octo-navy-100);
+  --secondary-foreground: var(--octo-navy-700);
+
+  --muted: var(--octo-navy-100);
+  --muted-foreground: var(--octo-navy-600);
+
+  --border: var(--octo-navy-200);
+  --input: var(--octo-navy-200);
+  --ring: var(--octo-blue);
+
+  --destructive: #d63d3d;
+  --destructive-foreground: #ffffff;
+
+  /* Callout intents (map to existing hint/info/success/warning/problem) */
+  --info: #124164;
+  --info-bg: #e5f4ff;
+  --info-border: var(--octo-blue);
+  --success: #04502f;
+  --success-bg: #e8ffeb;
+  --success-border: #00b065;
+  --warning: #a23623;
+  --warning-bg: #fefae9;
+  --warning-border: #fc8431;
+  --problem: #931919;
+  --problem-bg: #fff2ee;
+  --problem-border: #ff4848;
+  /* question -> neutral/muted treatment */
+  --question: var(--octo-navy-700);
+  --question-bg: var(--octo-navy-100);
+  --question-border: var(--octo-navy-400);
+
+  --sidebar: #fafdff;
+  --sidebar-foreground: var(--octo-navy-700);
+
+  /* Surfaces for layered UI (code blocks, window chrome, hover states) */
+  --surface: var(--octo-navy-100);
+  --surface-2: #f8fafc;
+  --code-bg: #0c1a24;
+  --code-foreground: #e6edf3;
+  --code-chrome: #142736;
+  --code-border: #1f3a52;
+
+  /* Elevation */
+  --shadow-sm: 0 1px 2px 0 rgba(16, 33, 47, 0.06);
+  --shadow-md:
+    0 4px 12px -2px rgba(16, 33, 47, 0.1), 0 2px 6px -2px rgba(16, 33, 47, 0.06);
+  --shadow-lg:
+    0 12px 32px -8px rgba(16, 33, 47, 0.18),
+    0 4px 10px -4px rgba(16, 33, 47, 0.1);
+
+  --radius: 0.5rem;
+
+  /* Fonts - preserve the existing system stack designers expect */
+  --font-sans:
+    system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+    'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+    'Segoe UI Symbol';
+  --font-mono: Consolas, monaco, monospace;
+}
+
+[data-theme='dark'] {
+  --background: #10202e;
+  --foreground: #dae2e9;
+
+  --card: #132838;
+  --card-foreground: #dae2e9;
+
+  --popover: #0c1a24;
+  --popover-foreground: #dae2e9;
+
+  --primary: var(--octo-blue-bright);
+  --primary-foreground: #06121b;
+
+  --accent: var(--octo-green-bright);
+  --accent-foreground: #06121b;
+
+  --secondary: var(--octo-navy-800);
+  --secondary-foreground: var(--octo-navy-200);
+
+  --muted: #16344a;
+  --muted-foreground: var(--octo-navy-300);
+
+  --border: #314c62;
+  --input: #314c62;
+  --ring: var(--octo-blue-bright);
+
+  /* Callout text colors must lighten for legibility on the dark surfaces;
+     light-mode values stay dark and would be invisible here. */
+  --info: #cfe6fb;
+  --info-bg: rgba(13, 128, 216, 0.1);
+  --info-border: var(--octo-blue);
+  --success: #6fe6b4;
+  --success-bg: rgba(0, 176, 101, 0.12);
+  --warning: #ffb27a;
+  --warning-bg: rgba(252, 132, 49, 0.12);
+  --problem: #ff9b9b;
+  --problem-bg: rgba(255, 72, 72, 0.12);
+  --question: var(--octo-navy-200);
+  --question-bg: rgba(124, 152, 180, 0.12);
+  --question-border: var(--octo-navy-400);
+
+  --sidebar: #0c1a24;
+  --sidebar-foreground: var(--octo-navy-200);
+
+  --surface: #0f2230;
+  --surface-2: #16344a;
+  --code-bg: #0a161f;
+  --code-foreground: #e6edf3;
+  --code-chrome: #0f2230;
+  --code-border: #233a4f;
+
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.4);
+  --shadow-md:
+    0 4px 12px -2px rgba(0, 0, 0, 0.5), 0 2px 6px -2px rgba(0, 0, 0, 0.4);
+  --shadow-lg:
+    0 12px 32px -8px rgba(0, 0, 0, 0.6), 0 4px 10px -4px rgba(0, 0, 0, 0.4);
+}
diff --git a/src/design-system/ui/Badge.astro b/src/design-system/ui/Badge.astro
new file mode 100644
index 0000000000..fca973379c
--- /dev/null
+++ b/src/design-system/ui/Badge.astro
@@ -0,0 +1,26 @@
+---
+type Variant = 'default' | 'brand' | 'success' | 'outline';
+
+interface Props {
+  variant?: Variant;
+  class?: string;
+}
+
+const { variant = 'default', class: extra = '' } = Astro.props;
+
+const variants: Record<Variant, string> = {
+  default: 'bg-muted text-muted-foreground ring-1 ring-inset ring-border/60',
+  brand: 'bg-primary/10 text-primary ring-1 ring-inset ring-primary/20',
+  success:
+    'bg-[color-mix(in_oklab,var(--octo-green)_16%,var(--background))] text-[color-mix(in_oklab,var(--octo-green)_60%,var(--foreground))] ring-1 ring-inset ring-[color-mix(in_oklab,var(--octo-green)_35%,transparent)]',
+  outline: 'border border-border text-muted-foreground',
+};
+
+const cls = [
+  'inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-xs font-medium tracking-tight',
+  variants[variant],
+  extra,
+].join(' ');
+---
+
+<span class={cls} data-component="Badge"><slot /></span>
diff --git a/src/design-system/ui/Button.astro b/src/design-system/ui/Button.astro
new file mode 100644
index 0000000000..0dd1cb5365
--- /dev/null
+++ b/src/design-system/ui/Button.astro
@@ -0,0 +1,39 @@
+---
+type Variant = 'primary' | 'accent' | 'outline' | 'ghost';
+type Size = 'sm' | 'md' | 'lg';
+
+interface Props {
+  href?: string;
+  variant?: Variant;
+  size?: Size;
+  class?: string;
+}
+
+const { href, variant = 'primary', size = 'md', class: extra = '' } = Astro.props;
+
+const base =
+  'inline-flex items-center justify-center gap-2 rounded-md font-medium whitespace-nowrap transition-all duration-150 ease-out active:translate-y-px focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50';
+
+const variants: Record<Variant, string> = {
+  primary:
+    'bg-primary text-primary-foreground shadow-[var(--shadow-sm)] hover:bg-primary/90 hover:shadow-[var(--shadow-md)]',
+  accent:
+    'bg-accent text-accent-foreground shadow-[var(--shadow-sm)] hover:bg-accent/90 hover:shadow-[var(--shadow-md)]',
+  outline:
+    'border border-border bg-background text-foreground hover:bg-muted hover:border-primary/40',
+  ghost: 'text-foreground hover:bg-muted',
+};
+
+const sizes: Record<Size, string> = {
+  sm: 'h-8 px-3 text-sm',
+  md: 'h-10 px-4 text-sm',
+  lg: 'h-11 px-6 text-[0.95rem]',
+};
+
+const cls = [base, variants[variant], sizes[size], extra].join(' ');
+const Tag = href ? 'a' : 'button';
+---
+
+<Tag class={cls} href={href} data-component="Button">
+  <slot />
+</Tag>
diff --git a/src/design-system/ui/Callout.astro b/src/design-system/ui/Callout.astro
new file mode 100644
index 0000000000..0cbffe7b59
--- /dev/null
+++ b/src/design-system/ui/Callout.astro
@@ -0,0 +1,67 @@
+---
+type Intent = 'info' | 'success' | 'warning' | 'problem';
+
+interface Props {
+  intent?: Intent;
+  title?: string;
+}
+
+const { intent = 'info', title } = Astro.props;
+
+// Colors pull from the intent tokens defined in tokens.css.
+const styles: Record<Intent, string> = {
+  info: '[--c:var(--info)] [--bg:var(--info-bg)] [--bd:var(--info-border)]',
+  success:
+    '[--c:var(--success)] [--bg:var(--success-bg)] [--bd:var(--success-border)]',
+  warning:
+    '[--c:var(--warning)] [--bg:var(--warning-bg)] [--bd:var(--warning-border)]',
+  problem:
+    '[--c:var(--problem)] [--bg:var(--problem-bg)] [--bd:var(--problem-border)]',
+};
+
+const labels: Record<Intent, string> = {
+  info: 'Note',
+  success: 'Success',
+  warning: 'Warning',
+  problem: 'Important',
+};
+
+// Per-intent inline SVG paths (24x24 viewBox), stroke-based to match the brand iconography.
+const icons: Record<Intent, string> = {
+  info: '<circle cx="12" cy="12" r="9"></circle><path d="M12 11v5"></path><path d="M12 8h.01"></path>',
+  success:
+    '<circle cx="12" cy="12" r="9"></circle><path d="m8.5 12.5 2.5 2.5 4.5-5"></path>',
+  warning:
+    '<path d="M10.3 4.3 2.5 18a2 2 0 0 0 1.7 3h15.6a2 2 0 0 0 1.7-3L13.7 4.3a2 2 0 0 0-3.4 0Z"></path><path d="M12 9v4"></path><path d="M12 17h.01"></path>',
+  problem:
+    '<circle cx="12" cy="12" r="9"></circle><path d="M12 8v5"></path><path d="M12 16h.01"></path>',
+};
+---
+
+<div
+  data-component="Callout"
+  class={`my-6 flex gap-3 rounded-lg border border-l-[3px] px-4 py-3.5 text-[0.95rem] ${styles[intent]}`}
+  style="border-color: color-mix(in oklab, var(--bd) 35%, transparent); border-left-color: var(--bd); background: var(--bg); color: var(--c);"
+  role="note"
+>
+  <svg
+    class="mt-0.5 h-[18px] w-[18px] shrink-0"
+    style="color: var(--bd);"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    set:html={icons[intent]}
+  />
+  <div class="min-w-0">
+    <p class="mb-1 font-semibold leading-snug">{title ?? labels[intent]}</p>
+    <div
+      class="leading-relaxed opacity-95 [&_a]:font-medium [&_a]:underline [&_a]:underline-offset-2 [&_p]:my-1 [&_p:last-child]:mb-0"
+    >
+      <slot />
+    </div>
+  </div>
+</div>
diff --git a/src/design-system/ui/Card.astro b/src/design-system/ui/Card.astro
new file mode 100644
index 0000000000..d2364be71e
--- /dev/null
+++ b/src/design-system/ui/Card.astro
@@ -0,0 +1,45 @@
+---
+interface Props {
+  href?: string;
+  title?: string;
+  class?: string;
+}
+
+const { href, title, class: extra = '' } = Astro.props;
+const interactive = href
+  ? 'group hover:-translate-y-0.5 hover:border-primary/45 hover:shadow-[var(--shadow-md)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background'
+  : '';
+const cls = [
+  'relative flex h-full flex-col rounded-xl border border-border bg-card text-card-foreground p-5 transition-all duration-200 ease-out',
+  interactive,
+  extra,
+].join(' ');
+const Tag = href ? 'a' : 'div';
+// Title may carry a trailing arrow glyph in content; strip it so we render our own.
+const cleanTitle = title?.replace(/\s*→\s*$/, '');
+---
+
+<Tag class={cls} href={href} data-component="Card">
+  {
+    cleanTitle && (
+      <h3 class="mb-1.5 flex items-center gap-1.5 font-semibold tracking-tight">
+        <span>{cleanTitle}</span>
+        {href && (
+          <svg
+            class="h-4 w-4 shrink-0 text-muted-foreground transition-all duration-200 ease-out group-hover:translate-x-0.5 group-hover:text-primary"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M5 12h14M13 6l6 6-6 6" />
+          </svg>
+        )}
+      </h3>
+    )
+  }
+  <div class="text-sm leading-relaxed text-muted-foreground"><slot /></div>
+</Tag>
diff --git a/src/design-system/ui/CodeBlock.astro b/src/design-system/ui/CodeBlock.astro
new file mode 100644
index 0000000000..8a9fbd6a4e
--- /dev/null
+++ b/src/design-system/ui/CodeBlock.astro
@@ -0,0 +1,101 @@
+---
+// Calm bordered code surface with a slim label bar (filename/language) and an
+// optional copy affordance. The copy button is a tiny is:inline vanilla script
+// (no framework runtime) - it reads textContent from the sibling <pre>.
+type Lang = 'bash' | 'shell' | 'json' | 'yaml' | 'powershell' | 'text';
+
+interface Props {
+  label?: string;
+  lang?: Lang;
+  copy?: boolean;
+}
+
+const { label, lang = 'text', copy = true } = Astro.props;
+
+const icons: Record<Lang, string> = {
+  bash: '<path d="M4 17l6-6-6-6"></path><path d="M12 19h8"></path>',
+  shell: '<path d="M4 17l6-6-6-6"></path><path d="M12 19h8"></path>',
+  powershell: '<path d="M4 17l6-6-6-6"></path><path d="M12 19h8"></path>',
+  json: '<path d="M8 3H7a2 2 0 0 0-2 2v4a2 2 0 0 1-2 2 2 2 0 0 1 2 2v4a2 2 0 0 0 2 2h1"></path><path d="M16 3h1a2 2 0 0 1 2 2v4a2 2 0 0 0 2 2 2 2 0 0 0-2 2v4a2 2 0 0 1-2 2h-1"></path>',
+  yaml: '<path d="M8 3H7a2 2 0 0 0-2 2v4a2 2 0 0 1-2 2 2 2 0 0 1 2 2v4a2 2 0 0 0 2 2h1"></path><path d="M16 3h1a2 2 0 0 1 2 2v4a2 2 0 0 0 2 2 2 2 0 0 0-2 2v4a2 2 0 0 1-2 2h-1"></path>',
+  text: '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><path d="M14 2v6h6"></path>',
+};
+---
+
+<figure class="code-block not-prose" data-component="CodeBlock">
+  <div class="code-block__bar">
+    <span class="code-block__label">
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+        set:html={icons[lang]}
+      />
+      {label ?? lang}
+    </span>
+    {
+      copy && (
+        <button
+          type="button"
+          class="code-block__copy"
+          data-copy
+          aria-label="Copy code to clipboard"
+        >
+          <span class="code-block__copy-idle">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+              <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+            </svg>
+            Copy
+          </span>
+          <span class="code-block__copy-done">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <path d="m20 6-11 11-5-5" />
+            </svg>
+            Copied
+          </span>
+        </button>
+      )
+    }
+  </div>
+  <slot />
+</figure>
+
+<script is:inline>
+  (() => {
+    if (window.__mvpCopyInit) return;
+    window.__mvpCopyInit = true;
+    document.addEventListener('click', (e) => {
+      const btn = e.target.closest('[data-copy]');
+      if (!btn) return;
+      const pre = btn.closest('.code-block')?.querySelector('pre');
+      if (!pre) return;
+      const text = pre.innerText;
+      navigator.clipboard?.writeText(text).then(() => {
+        btn.setAttribute('data-copied', '');
+        clearTimeout(btn.__t);
+        btn.__t = setTimeout(() => btn.removeAttribute('data-copied'), 1600);
+      });
+    });
+  })();
+</script>
diff --git a/src/pages/docs.mdx b/src/pages/docs.mdx
index 481cf9215f..73e61f42ee 100644
--- a/src/pages/docs.mdx
+++ b/src/pages/docs.mdx
@@ -1,5 +1,5 @@
 ---
-layout: src/layouts/Default.astro
+layout: src/design-system/docs-shell/DocsContentLayout.astro
 pubDate: 2023-01-01
 modDate: 2024-03-18
 title: Hello, Octopus Deploy! 👋
diff --git a/src/pages/docs/ui-mvp.astro b/src/pages/docs/ui-mvp.astro
new file mode 100644
index 0000000000..9c4183cd9c
--- /dev/null
+++ b/src/pages/docs/ui-mvp.astro
@@ -0,0 +1,200 @@
+---
+import DocsLayout from '../../design-system/docs-shell/DocsLayout.astro';
+import Card from '../../design-system/ui/Card.astro';
+import Badge from '../../design-system/ui/Badge.astro';
+import Button from '../../design-system/ui/Button.astro';
+import Callout from '../../design-system/ui/Callout.astro';
+import CodeBlock from '../../design-system/ui/CodeBlock.astro';
+
+const breadcrumbs = [
+  { label: 'Docs', href: '/docs' },
+  { label: 'Getting started', href: '/docs/getting-started' },
+  { label: 'Deploying a release' },
+];
+
+const sidebar = [
+  {
+    title: 'Getting started',
+    items: [
+      { label: 'Overview', href: '#' },
+      { label: 'Installation', href: '#' },
+      { label: 'Your first project', href: '#' },
+      { label: 'Deploying a release', href: '#', active: true },
+      { label: 'Environments', href: '#' },
+    ],
+  },
+  {
+    title: 'Deployments',
+    items: [
+      { label: 'Deployment process', href: '#' },
+      { label: 'Variables', href: '#' },
+      { label: 'Releases & channels', href: '#' },
+      { label: 'Runbooks', href: '#' },
+    ],
+  },
+  {
+    title: 'Infrastructure',
+    items: [
+      { label: 'Targets', href: '#' },
+      { label: 'Workers', href: '#' },
+      { label: 'Accounts', href: '#' },
+    ],
+  },
+];
+
+const toc = [
+  { label: 'Before you begin', href: '#before-you-begin' },
+  { label: 'Create a release', href: '#create-a-release' },
+  { label: 'Promote to an environment', href: '#promote', depth: 2 },
+  { label: 'Deploy from the CLI', href: '#deploy-cli' },
+  { label: 'Next steps', href: '#next-steps' },
+];
+---
+
+<DocsLayout
+  title="Deploying a release"
+  description="Create a release from your deployment process and promote it through your environments - from the dashboard or the CLI."
+  breadcrumbs={breadcrumbs}
+  sidebar={sidebar}
+  toc={toc}
+>
+  <div class="not-prose mb-7 flex flex-wrap items-center gap-2">
+    <Badge variant="brand">Guide</Badge>
+    <Badge variant="outline">
+      <svg
+        class="h-3 w-3"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+        ><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"
+        ></path></svg
+      >
+      10 min read
+    </Badge>
+    <Badge variant="success">Beginner</Badge>
+  </div>
+
+  <p>
+    A <strong>release</strong> is a snapshot of your deployment process and the variables
+    and packages it references. Once you have a release, you deploy it to an environment
+    such as <em>Development</em>, <em>Test</em>, or
+    <em>Production</em>.
+  </p>
+
+  <h2 id="before-you-begin">Before you begin</h2>
+  <p>
+    Make sure you have a project with a configured deployment process and at
+    least one deployment target registered in an environment.
+  </p>
+
+  <Callout intent="info" title="Prerequisites">
+    You need the <code>Project deployer</code> role (or higher) to create and deploy
+    releases. See <a href="#">Managing users and teams</a>.
+  </Callout>
+
+  <h2 id="create-a-release">Create a release</h2>
+  <p>
+    From your project dashboard, choose <strong>Create release</strong>. Octopus
+    assigns a version number based on your versioning strategy:
+  </p>
+
+  <ol>
+    <li>Open the project and select <strong>Create release</strong>.</li>
+    <li>Review the package versions selected for the release.</li>
+    <li>Add release notes (optional but recommended).</li>
+    <li>Select <strong>Save</strong>.</li>
+  </ol>
+
+  <h3 id="promote">Promote to an environment</h3>
+  <p>
+    Releases move through your lifecycle phases. The dashboard shows which
+    environments a release has reached:
+  </p>
+
+  <table>
+    <thead>
+      <tr><th>Environment</th><th>Status</th><th>Last deployed</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Development</td>
+        <td
+          ><span class="status-pill status-pill--ok"
+            ><span class="status-dot"></span>Success</span
+          ></td
+        >
+        <td>2 hours ago</td>
+      </tr>
+      <tr>
+        <td>Test</td>
+        <td
+          ><span class="status-pill status-pill--ok"
+            ><span class="status-dot"></span>Success</span
+          ></td
+        >
+        <td>1 hour ago</td>
+      </tr>
+      <tr>
+        <td>Production</td>
+        <td
+          ><span class="status-pill status-pill--wait"
+            ><span class="status-dot"></span>Awaiting approval</span
+          ></td
+        >
+        <td>-</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <Callout intent="warning" title="Production gates">
+    Deployments to <em>Production</em> in this lifecycle require manual approval.
+    The release will pause until an authorized user intervenes.
+  </Callout>
+
+  <h2 id="deploy-cli">Deploy from the CLI</h2>
+  <p>You can script the same flow with the Octopus CLI:</p>
+
+  <CodeBlock label="Terminal" lang="bash"
+    ><pre><code>octopus release deploy \
+  --project "Web Store" \
+  --version "2024.1.0" \
+  --environment "Production" \
+  --progress</code></pre></CodeBlock
+  >
+
+  <p>
+    The <code>--progress</code> flag streams the deployment log to your terminal so
+    it integrates cleanly with CI pipelines.
+  </p>
+
+  <Callout intent="success" title="Done">
+    Once the deployment completes, the dashboard and the CLI both report a green
+    <strong>Success</strong> status for that environment.
+  </Callout>
+
+  <h2 id="next-steps">Next steps</h2>
+
+  <div class="not-prose mt-4 grid gap-4 sm:grid-cols-2">
+    <Card href="#" title="Deployment process →">
+      Define the steps Octopus runs when it deploys your release.
+    </Card>
+    <Card href="#" title="Variables →">
+      Parameterize deployments per environment, tenant, and target.
+    </Card>
+    <Card href="#" title="Runbooks →">
+      Automate routine operations like backups and failover.
+    </Card>
+    <Card href="#" title="Channels →">
+      Route releases through different lifecycles and rules.
+    </Card>
+  </div>
+
+  <div class="not-prose mt-8 flex flex-wrap gap-3">
+    <Button href="#" variant="primary">Read the deployment guide</Button>
+    <Button href="#" variant="outline">Browse the CLI reference</Button>
+  </div>
+</DocsLayout>
diff --git a/src/pages/ui-update-sample.mdx b/src/pages/ui-update-sample.mdx
index 373131aadb..5bbe4613ae 100644
--- a/src/pages/ui-update-sample.mdx
+++ b/src/pages/ui-update-sample.mdx
@@ -1,5 +1,5 @@
 ---
-layout: src/layouts/Default.astro
+layout: src/design-system/docs-shell/DocsContentLayout.astro
 pubDate: 2024-05-10
 modDate: 2024-05-10
 title: Tenant variables

From cec72c2fea6daa1275054c8f23ef3bc82b4a396b Mon Sep 17 00:00:00 2001
From: Kamil Majkrzak <kamil.majkrzak@octopus.com>
Date: Tue, 26 May 2026 17:19:58 +0200
Subject: [PATCH 2/5] MVP iteration

---
 src/design-system/README.md                   |  36 +-
 .../docs-shell/DocsContentLayout.astro        |  45 +-
 src/design-system/docs-shell/DocsHead.astro   |   5 +
 src/design-system/docs-shell/DocsHeader.astro |  55 +-
 src/design-system/docs-shell/DocsLayout.astro | 160 +++--
 .../docs-shell/DocsSidebar.astro              |  22 +-
 .../docs-shell/DocsSidebarNav.astro           |  24 +-
 src/design-system/docs-shell/DocsToc.astro    | 376 +++++++++-
 src/design-system/theme.css                   | 643 ++++++++++++++----
 src/design-system/tokens.css                  | 262 +++++--
 src/design-system/ui/Button.astro             |  64 +-
 src/design-system/ui/Callout.astro            |  32 +-
 src/design-system/ui/Card.astro               |   6 +-
 src/pages/docs/ui-mvp.astro                   |  15 +-
 14 files changed, 1402 insertions(+), 343 deletions(-)

diff --git a/src/design-system/README.md b/src/design-system/README.md
index eb251959ed..21f8d885b8 100644
--- a/src/design-system/README.md
+++ b/src/design-system/README.md
@@ -43,14 +43,20 @@ src/design-system/
 
 ## 2. The single customization surface: `tokens.css`
 
-`tokens.css` is the **only** file a site is expected to edit. It defines two layers:
+`tokens.css` is the **only** file a site is expected to edit. It defines three layers:
 
 1. **Brand primitives** - the literal Octopus palette (`--octo-blue`, `--octo-green`, the
-   navy scale) and font stacks. These are the brand source of truth, mirrored from
-   `public/docs/css/vars.css`.
+   navy scale) and font stacks (`--font-display` / `--font-sans` / `--font-mono`). These are
+   the brand source of truth, mirrored from `public/docs/css/vars.css`.
 2. **Semantic tokens** (shadcn shape) - `--background`, `--foreground`, `--primary`,
    `--accent`, `--muted`, `--border`, `--ring`, callout intents, surfaces, elevation, etc.,
    defined for light (`:root`) and dark (`[data-theme='dark']`).
+3. **Bioluminescence layer** (the "Abyssal" look) - the decorative palette is cyan -> purple
+   -> pink (`#1FC0FF` / `#6950FF` / `#CC3CFF`); green is reserved for semantic success only.
+   Glow tokens (`--glow-primary`, `--glow-brand`), brand gradients (`--gradient-brand`,
+   `--gradient-ink`), the atmosphere stops (`--aurora-1..3`, `--grid-line`, `--grain-opacity`),
+   and `--shadow-glow`. Dial the whole mood from here: drop the glow alphas and grain to
+   near-zero for a flatter skin, or push them up for more drama. No component edits required.
 
 Components and `theme.css` reference **only the semantic tokens**, never raw hex. So:
 - Re-skinning a site = edit `tokens.css`, nothing else.
@@ -180,9 +186,26 @@ These hold by construction; preserve them when extending the system.
   wraps content in `<article itemscope itemtype="https://schema.org/TechArticle">` with
   `itemprop` headline/description/articleBody; heading hierarchy is semantic. Keep these when
   editing the shell.
-- **Core Web Vitals.** No web fonts (system-ui sans + Consolas/monaco mono), no blocking JS,
-  no layout-shifting hydration. A FOUC-prevention inline script in `DocsLayout`'s `<head>`
-  applies the stored theme before paint.
+- **Core Web Vitals.** No blocking JS, no layout-shifting hydration. A FOUC-prevention inline
+  script in `DocsLayout`'s `<head>` applies the stored theme before paint. The "Abyssal"
+  revamp **does** load three web fonts (Bricolage Grotesque / Hanken Grotesk / JetBrains Mono
+  via Bunny Fonts, a privacy-friendly Google Fonts mirror) - a deliberate trade for distinctive
+  type. They are `preconnect`ed and `display=swap`, and every `--font-*` token keeps a system
+  stack fallback, so first paint uses system fonts and there is no invisible-text delay. If a
+  site must stay font-free, point the `--font-*` tokens back at system stacks and drop the
+  `<link>`s from the layout heads - nothing else changes.
+- **In-content images get the "glass" effect.** Images authored inside documentation content
+  (`.prose figure` / `.image` / `[data-image]` from `<Image>` and the `:::figure` / `:img`
+  directives, plus standalone `img.resp-img`) are wrapped in a frosted panel with a blurred
+  cyan/pink bloom behind them - ported 1:1 from the marketing site. It is **scoped to `.prose`**,
+  so the logo and all UI/chrome imagery are never touched. The look is tokenized in `tokens.css`
+  (`--glass-*`): dark mode uses the exact marketing values; light mode is retuned (cyan-tinted
+  frost, visible border, softened bloom) since the white-translucent originals vanish on the
+  pale background. Padding is `--glass-pad` (the main project's `--space-12`).
+- **Atmosphere is decorative and pointer-transparent.** The fixed `.ds-atmosphere` (aurora
+  mesh + engineering grid) and `.ds-grain` overlay sit at `z-index:-1` behind content and are
+  GPU-cheap. The page-load `[data-rise]` reveal, the aurora drift, and the status-dot pulse all
+  collapse under `prefers-reduced-motion: reduce`.
 - **Typography plugin override technique.** The prose/table/code/status rules in `theme.css`
   are intentionally **unlayered** (outside `@layer base`) so they beat `@tailwindcss/typography`'s
   utility-layer defaults. Pages use `class="prose"` (not `prose-slate`). Don't move these into
@@ -197,6 +220,7 @@ These hold by construction; preserve them when extending the system.
 | Search dropdown | `docs-shell/DocsHeader.astro` | Filtered, keyboard-navigable results list (currently sample data - see gaps) |
 | TOC scroll-spy | `docs-shell/DocsToc.astro` | IntersectionObserver active-section highlight |
 | Copy button | `ui/CodeBlock.astro` | Delegated copy-to-clipboard with "Copied" state |
+| Button glow | `ui/Button.astro` | Tracks the pointer to set `--hover-x/--hover-y` for the cursor-following glow |
 
 ---
 
diff --git a/src/design-system/docs-shell/DocsContentLayout.astro b/src/design-system/docs-shell/DocsContentLayout.astro
index 3b37488b47..1ed8a9cb2a 100644
--- a/src/design-system/docs-shell/DocsContentLayout.astro
+++ b/src/design-system/docs-shell/DocsContentLayout.astro
@@ -86,22 +86,24 @@ const sortedTopLevel = pages
 <html lang={lang}>
   <Head frontmatter={frontmatter} headings={headings} lang={lang} />
   <body
-    class="min-h-screen bg-background font-sans text-foreground antialiased"
+    class="relative min-h-screen bg-background font-sans text-foreground antialiased"
   >
     <script is:inline>
       if (localStorage.getItem('mvp-theme') === 'dark')
         document.documentElement.setAttribute('data-theme', 'dark');
     </script>
+    <div class="ds-atmosphere"></div>
+    <div class="ds-grain"></div>
     <DocsHeader />
 
     <div class="mx-auto flex max-w-[1600px]">
       <aside
         data-component="DocsSidebar"
-        class="hidden w-64 shrink-0 border-r border-border bg-sidebar lg:block"
+        class="hidden w-[16.5rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
         aria-label="Documentation navigation"
       >
         <nav
-          class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-4 py-6 [scrollbar-width:thin]"
+          class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3.5 py-8 [scrollbar-gutter:stable]"
         >
           <ul>
             {sortedTopLevel.map((page: any) => <DocsSidebarNav page={page} />)}
@@ -160,12 +162,26 @@ const sortedTopLevel = pages
               </nav>
             </details>
 
-            <DocsBreadcrumbs items={crumbs} />
+            <div data-rise style="--rise:60ms">
+              <DocsBreadcrumbs items={crumbs} />
+            </div>
 
             <article itemscope itemtype="https://schema.org/TechArticle">
-              <header class="mb-8 border-b border-border pb-7">
+              <header class="relative mb-9 pb-8">
+                <p
+                  data-rise
+                  style="--rise:90ms"
+                  class="mb-3 flex items-center gap-2 font-mono text-[0.72rem] font-medium uppercase tracking-[0.18em] text-primary"
+                >
+                  <span
+                    class="inline-block h-1.5 w-1.5 rounded-full shadow-[0_0_10px_2px_var(--glow-brand)]"
+                    style="background:var(--purple-300)"></span>
+                  {crumbs[crumbs.length - 2]?.label ?? 'Documentation'}
+                </p>
                 <h1
-                  class="text-[2.05rem] font-bold leading-[1.15] tracking-[-0.02em] text-foreground"
+                  data-rise
+                  style="--rise:150ms"
+                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.9rem]"
                   itemprop="headline"
                 >
                   {frontmatter.title}
@@ -173,16 +189,29 @@ const sortedTopLevel = pages
                 {
                   frontmatter.description && (
                     <p
-                      class="mt-3 text-lg leading-relaxed text-muted-foreground"
+                      data-rise
+                      style="--rise:230ms"
+                      class="mt-4 max-w-2xl text-[1.12rem] leading-relaxed text-muted-foreground"
                       itemprop="description"
                     >
                       {frontmatter.description}
                     </p>
                   )
                 }
+                <div
+                  data-rise
+                  style="--rise:300ms"
+                  class="absolute bottom-0 left-0 h-px w-full bg-gradient-to-r from-primary/55 via-border to-transparent"
+                >
+                </div>
               </header>
 
-              <div class="prose" itemprop="articleBody">
+              <div
+                class="prose"
+                itemprop="articleBody"
+                data-rise
+                style="--rise:380ms"
+              >
                 <slot />
               </div>
             </article>
diff --git a/src/design-system/docs-shell/DocsHead.astro b/src/design-system/docs-shell/DocsHead.astro
index e6ac41d5fb..08fa1dd6d7 100644
--- a/src/design-system/docs-shell/DocsHead.astro
+++ b/src/design-system/docs-shell/DocsHead.astro
@@ -60,6 +60,11 @@ stats.stop();
   <meta name="robots" content={'max-image-preview:large, ' + robots} />
   <meta name="keywords" content={frontmatter.keywords} />
   <meta name="description" content={frontmatter.description} />
+  <link rel="preconnect" href="https://fonts.bunny.net" crossorigin />
+  <link
+    rel="stylesheet"
+    href="https://fonts.bunny.net/css?family=bricolage-grotesque:600,700,800|hanken-grotesk:400,500,600,700|jetbrains-mono:400,500&display=swap"
+  />
   <link rel="stylesheet" href={SITE.subfolder + '/css/vars.css'} />
   <link rel="stylesheet" href={SITE.subfolder + '/css/footer-bundle.css'} />
   {
diff --git a/src/design-system/docs-shell/DocsHeader.astro b/src/design-system/docs-shell/DocsHeader.astro
index 63f2ac4927..3e98a47f36 100644
--- a/src/design-system/docs-shell/DocsHeader.astro
+++ b/src/design-system/docs-shell/DocsHeader.astro
@@ -2,11 +2,12 @@
 // Top navigation bar. The only JS is a tiny theme toggle (vanilla, no framework
 // runtime) to demonstrate dark mode - consistent with the zero-JS approach.
 import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
+import Button from '../ui/Button.astro';
 ---
 
 <header
   data-component="DocsHeader"
-  class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur-md supports-[backdrop-filter]:bg-background/65"
+  class="sticky top-0 z-40 border-b border-border/70 bg-background/70 backdrop-blur-xl supports-[backdrop-filter]:bg-background/55"
 >
   <!-- No left padding: the logo's left edge lines up with the sidebar column. -->
   <div class="mx-auto flex h-16 max-w-[1600px] items-center gap-4 pr-4 lg:pr-6">
@@ -125,13 +126,31 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
           ><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path></svg
         >
       </button>
-      <a
+      <Button
         href="https://octopus.com/start"
-        class="ml-1.5 hidden h-9 items-center gap-1.5 rounded-md bg-accent px-3.5 text-[0.8rem] font-semibold text-accent-foreground outline-none ring-1 ring-inset ring-black/5 transition-[background-color,box-shadow,transform] hover:bg-accent/90 hover:shadow-[var(--shadow-sm)] active:translate-y-px focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background sm:inline-flex"
-        >Start free trial</a
+        variant="primary"
+        class="ml-1.5 hidden h-9 gap-1.5 px-4 py-0 text-[0.8rem] sm:inline-flex"
       >
+        Start free trial
+        <svg
+          class="h-3.5 w-3.5"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2.2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"><path d="M5 12h14M13 6l6 6-6 6"></path></svg
+        >
+      </Button>
     </nav>
   </div>
+  <!-- Bottom hairline. -->
+  <div
+    aria-hidden="true"
+    class="pointer-events-none absolute inset-x-0 bottom-0 h-px bg-gradient-to-r from-transparent via-primary/45 to-transparent"
+  >
+  </div>
 </header>
 
 <style is:global>
@@ -175,7 +194,11 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
     if (!input || !panel || !list || !empty) return;
 
     const docs = [
-      { title: 'Deploying a release', section: 'Getting started › Deployments', href: '#' },
+      {
+        title: 'Deploying a release',
+        section: 'Getting started › Deployments',
+        href: '#',
+      },
       { title: 'Your first project', section: 'Getting started', href: '#' },
       { title: 'Installation', section: 'Getting started', href: '#' },
       { title: 'Environments', section: 'Getting started', href: '#' },
@@ -188,7 +211,11 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
       { title: 'Accounts', section: 'Infrastructure › Security', href: '#' },
       { title: 'Tenants & multi-tenancy', section: 'Tenants', href: '#' },
       { title: 'Octopus CLI reference', section: 'Automation', href: '#' },
-      { title: 'Lifecycles & phases', section: 'Deployments › Lifecycles', href: '#' },
+      {
+        title: 'Lifecycles & phases',
+        section: 'Deployments › Lifecycles',
+        href: '#',
+      },
     ];
 
     let results = [];
@@ -203,9 +230,15 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
       svg.setAttribute('stroke-linecap', 'round');
       svg.setAttribute('stroke-linejoin', 'round');
       svg.setAttribute('aria-hidden', 'true');
-      svg.setAttribute('class', 'mt-0.5 h-4 w-4 shrink-0 text-muted-foreground');
+      svg.setAttribute(
+        'class',
+        'mt-0.5 h-4 w-4 shrink-0 text-muted-foreground'
+      );
       const p1 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-      p1.setAttribute('d', 'M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z');
+      p1.setAttribute(
+        'd',
+        'M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z'
+      );
       const p2 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
       p2.setAttribute('d', 'M14 2v6h6');
       svg.append(p1, p2);
@@ -281,7 +314,8 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
         const text = document.createElement('span');
         text.className = 'min-w-0';
         const sec = document.createElement('span');
-        sec.className = 'mt-0.5 block truncate text-[0.75rem] text-muted-foreground';
+        sec.className =
+          'mt-0.5 block truncate text-[0.75rem] text-muted-foreground';
         sec.textContent = d.section;
         text.append(titleNode(d.title, query), sec);
         li.append(docIcon(), text);
@@ -292,7 +326,8 @@ import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
 
     const go = (idx) => {
       const d = results[idx];
-      if (d) window.location.hash = d.href.startsWith('#') ? d.href.slice(1) : '';
+      if (d)
+        window.location.hash = d.href.startsWith('#') ? d.href.slice(1) : '';
       close();
     };
 
diff --git a/src/design-system/docs-shell/DocsLayout.astro b/src/design-system/docs-shell/DocsLayout.astro
index 3ded990fee..d22adb0cfa 100644
--- a/src/design-system/docs-shell/DocsLayout.astro
+++ b/src/design-system/docs-shell/DocsLayout.astro
@@ -9,12 +9,18 @@ import Footer from '../../components/Footer.astro';
 interface Props {
   title: string;
   description?: string;
+  eyebrow?: string;
   breadcrumbs: { label: string; href?: string }[];
-  sidebar: { title: string; items: { label: string; href: string; active?: boolean }[] }[];
+  sidebar: {
+    title: string;
+    items: { label: string; href: string; active?: boolean }[];
+  }[];
   toc: { label: string; href: string; depth?: number }[];
 }
 
-const { title, description, breadcrumbs, sidebar, toc } = Astro.props;
+const { title, description, eyebrow, breadcrumbs, sidebar, toc } = Astro.props;
+const kicker =
+  eyebrow ?? breadcrumbs[breadcrumbs.length - 2]?.label ?? 'Documentation';
 ---
 
 <!doctype html>
@@ -24,6 +30,12 @@ const { title, description, breadcrumbs, sidebar, toc } = Astro.props;
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{title} · Octopus Docs</title>
     {description && <meta name="description" content={description} />}
+    <!-- Web fonts via Bunny (GF mirror); preconnect + swap. -->
+    <link rel="preconnect" href="https://fonts.bunny.net" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.bunny.net/css?family=bricolage-grotesque:600,700,800|hanken-grotesk:400,500,600,700|jetbrains-mono:400,500&display=swap"
+    />
     <!-- Shared footer styles (footer remains the existing shared component) -->
     <link rel="stylesheet" href="/docs/css/footer-bundle.css" />
     <!-- Avoid dark-mode flash before the toggle script runs -->
@@ -32,74 +44,134 @@ const { title, description, breadcrumbs, sidebar, toc } = Astro.props;
         document.documentElement.setAttribute('data-theme', 'dark');
     </script>
   </head>
-  <body class="min-h-screen bg-background font-sans text-foreground antialiased">
+  <body
+    class="relative min-h-screen bg-background font-sans text-foreground antialiased"
+  >
+    <div class="ds-atmosphere"></div>
+    <div class="ds-grain"></div>
+
     <DocsHeader />
 
     <div class="mx-auto flex max-w-[1600px]">
       <DocsSidebar sections={sidebar} />
 
       <div class="flex min-w-0 flex-1">
-        <main class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-14">
+        <main class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-16">
           <div class="mx-auto max-w-3xl xl:mx-0">
-            <details class="group mb-5 rounded-lg border border-border bg-sidebar lg:hidden">
+            <details
+              class="group mb-5 rounded-lg border border-border bg-sidebar/70 backdrop-blur lg:hidden"
+            >
               <summary
                 class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-2.5 text-sm font-medium text-foreground [&::-webkit-details-marker]:hidden"
               >
                 <span class="flex items-center gap-2">
-                  <svg class="h-4 w-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16"></path></svg>
+                  <svg
+                    class="h-4 w-4 text-muted-foreground"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    aria-hidden="true"
+                    ><path d="M4 6h16M4 12h16M4 18h16"></path></svg
+                  >
                   Documentation menu
                 </span>
-                <svg class="h-4 w-4 text-muted-foreground transition-transform group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"></path></svg>
+                <svg
+                  class="h-4 w-4 text-muted-foreground transition-transform group-open:rotate-180"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  aria-hidden="true"><path d="m6 9 6 6 6-6"></path></svg
+                >
               </summary>
-              <nav class="border-t border-border px-3 py-3" aria-label="Documentation navigation">
-                {sidebar.map((section) => (
-                  <div class="mb-3 last:mb-0">
-                    <p class="mb-1 px-2 text-[0.72rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground/70">
-                      {section.title}
-                    </p>
-                    <ul class="space-y-px">
-                      {section.items.map((item) => (
-                        <li>
-                          <a
-                            href={item.href}
-                            aria-current={item.active ? 'page' : undefined}
-                            class={`block rounded-md px-2 py-1.5 text-[0.925rem] transition-colors ${
-                              item.active
-                                ? 'bg-primary/10 font-medium text-primary'
-                                : 'text-sidebar-foreground hover:bg-muted hover:text-foreground'
-                            }`}
-                          >
-                            {item.label}
-                          </a>
-                        </li>
-                      ))}
-                    </ul>
-                  </div>
-                ))}
+              <nav
+                class="border-t border-border px-3 py-3"
+                aria-label="Documentation navigation"
+              >
+                {
+                  sidebar.map((section) => (
+                    <div class="mb-4 last:mb-0">
+                      <p class="mb-2 px-3 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60">
+                        {section.title}
+                      </p>
+                      <ul class="space-y-0.5">
+                        {section.items.map((item) => (
+                          <li>
+                            <a
+                              href={item.href}
+                              aria-current={item.active ? 'page' : undefined}
+                              class={`block rounded-lg px-3 py-[0.47rem] text-[0.9rem] transition-colors ${
+                                item.active
+                                  ? 'bg-primary/[0.08] font-semibold text-primary'
+                                  : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
+                              }`}
+                            >
+                              {item.label}
+                            </a>
+                          </li>
+                        ))}
+                      </ul>
+                    </div>
+                  ))
+                }
               </nav>
             </details>
 
-            <DocsBreadcrumbs items={breadcrumbs} />
+            <div data-rise style="--rise:60ms">
+              <DocsBreadcrumbs items={breadcrumbs} />
+            </div>
 
             <article itemscope itemtype="https://schema.org/TechArticle">
-              <header class="mb-8 border-b border-border pb-7">
+              <header class="relative mb-9 pb-8">
+                <p
+                  data-rise
+                  style="--rise:90ms"
+                  class="mb-3 flex items-center gap-2 font-mono text-[0.72rem] font-medium uppercase tracking-[0.18em] text-primary"
+                >
+                  <span
+                    class="inline-block h-1.5 w-1.5 rounded-full shadow-[0_0_10px_2px_var(--glow-brand)]"
+                    style="background:var(--purple-300)"></span>
+                  {kicker}
+                </p>
                 <h1
-                  class="text-[2.05rem] font-bold leading-[1.15] tracking-[-0.02em] text-foreground"
+                  data-rise
+                  style="--rise:150ms"
+                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.9rem]"
                   itemprop="headline"
                 >
                   {title}
                 </h1>
-                {description && (
-                  <p
-                    class="mt-3 text-lg leading-relaxed text-muted-foreground"
-                    itemprop="description"
-                  >
-                    {description}
-                  </p>
-                )}
+                {
+                  description && (
+                    <p
+                      data-rise
+                      style="--rise:230ms"
+                      class="mt-4 max-w-2xl text-[1.12rem] leading-relaxed text-muted-foreground"
+                      itemprop="description"
+                    >
+                      {description}
+                    </p>
+                  )
+                }
+                <div
+                  data-rise
+                  style="--rise:300ms"
+                  class="absolute bottom-0 left-0 h-px w-full bg-gradient-to-r from-primary/55 via-border to-transparent"
+                >
+                </div>
               </header>
 
-              <div class="prose" itemprop="articleBody">
+              <div
+                class="prose"
+                itemprop="articleBody"
+                data-rise
+                style="--rise:380ms"
+              >
                 <slot />
               </div>
             </article>
diff --git a/src/design-system/docs-shell/DocsSidebar.astro b/src/design-system/docs-shell/DocsSidebar.astro
index 9d4edc19c4..7a5189b5e8 100644
--- a/src/design-system/docs-shell/DocsSidebar.astro
+++ b/src/design-system/docs-shell/DocsSidebar.astro
@@ -15,30 +15,36 @@ const { sections } = Astro.props;
 ---
 
 <aside
-  class="hidden lg:block w-64 shrink-0 border-r border-border bg-sidebar"
+  class="hidden w-[16.5rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
   aria-label="Documentation navigation"
 >
   <nav
-    class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3 py-6 [scrollbar-width:thin]"
+    class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3.5 py-8 [scrollbar-gutter:stable]"
   >
     {
       sections.map((section, si) => (
-        <div class={si === sections.length - 1 ? '' : 'mb-5'}>
-          <p class="mb-1.5 px-2.5 text-[0.72rem] font-semibold uppercase tracking-[0.09em] text-muted-foreground/65">
+        <div class={si === sections.length - 1 ? '' : 'mb-7'}>
+          <p class="mb-2.5 px-3 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60">
             {section.title}
           </p>
-          <ul>
+          <ul class="space-y-0.5">
             {section.items.map((item) => (
               <li>
                 <a
                   href={item.href}
                   aria-current={item.active ? 'page' : undefined}
-                  class={`relative block rounded-md py-[0.35rem] pl-2.5 pr-2 text-[0.925rem] leading-snug outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
+                  class={`group relative flex items-center rounded-lg px-3 py-[0.47rem] text-[0.9rem] leading-snug outline-none transition-[color,background-color] duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
                     item.active
-                      ? 'bg-primary/[0.09] font-medium text-primary before:absolute before:inset-y-[0.35rem] before:-left-3 before:w-[2px] before:rounded-r-full before:bg-primary'
-                      : 'text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+                      ? 'bg-primary/[0.08] font-semibold text-primary'
+                      : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
                   }`}
                 >
+                  {item.active && (
+                    <span
+                      aria-hidden="true"
+                      class="absolute inset-y-1.5 left-0 w-[3px] rounded-r-full bg-primary shadow-[0_0_10px_1px_var(--glow-primary)]"
+                    />
+                  )}
                   {item.label}
                 </a>
               </li>
diff --git a/src/design-system/docs-shell/DocsSidebarNav.astro b/src/design-system/docs-shell/DocsSidebarNav.astro
index ff0b93442a..bae4f99c31 100644
--- a/src/design-system/docs-shell/DocsSidebarNav.astro
+++ b/src/design-system/docs-shell/DocsSidebarNav.astro
@@ -28,12 +28,12 @@ const children = page.children.slice().sort((a, b) => a.order - b.order);
         aria-current={page.ariaCurrent ? page.ariaCurrent : undefined}
         rel={page.rel}
         title={linkTitle}
-        class={`relative flex items-center justify-between gap-2 rounded-md py-[0.35rem] pr-2 text-[0.925rem] leading-snug outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
-          depth > 0 ? 'pl-3' : 'pl-2'
+        class={`group/link relative flex items-center justify-between gap-2 rounded-lg py-[0.47rem] pr-2.5 text-[0.9rem] leading-snug outline-none transition-[color,background-color] duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
+          depth > 0 ? 'pl-3' : 'pl-3'
         } ${
           page.ariaCurrent
-            ? 'bg-primary/[0.09] font-medium text-primary before:absolute before:inset-y-[0.35rem] before:-left-1 before:w-[2px] before:rounded-r-full before:bg-primary'
-            : 'text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+            ? 'bg-primary/[0.08] font-semibold text-primary before:absolute before:inset-y-1.5 before:left-0 before:w-[3px] before:rounded-r-full before:bg-primary before:shadow-[0_0_10px_1px_var(--glow-primary)]'
+            : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
         }`}
       >
         <span class="truncate">{page.title}</span>
@@ -60,13 +60,13 @@ const children = page.children.slice().sort((a, b) => a.order - b.order);
     <li data-component="DocsSidebarNav">
       <details
         open={page.isOpen}
-        class={`group ${depth === 0 ? 'mb-4 last:mb-0' : 'mt-px'}`}
+        class={`group ${depth === 0 ? 'mb-7 last:mb-0' : 'mt-px'}`}
       >
         <summary
-          class={`flex cursor-pointer list-none items-center justify-between gap-2 rounded-md pl-2 pr-2 outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-webkit-details-marker]:hidden ${
+          class={`flex cursor-pointer list-none items-center justify-between gap-2 rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-webkit-details-marker]:hidden ${
             depth === 0
-              ? 'mb-1 py-1 text-[0.73rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground'
-              : 'py-[0.35rem] text-[0.925rem] font-medium leading-snug text-sidebar-foreground hover:bg-muted/70 hover:text-foreground'
+              ? 'mb-2.5 px-3 py-1 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60'
+              : 'px-3 py-[0.47rem] text-[0.9rem] font-medium leading-snug text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
           }`}
         >
           <span>{page.section}</span>
@@ -83,7 +83,13 @@ const children = page.children.slice().sort((a, b) => a.order - b.order);
             <path d="m9 18 6-6-6-6" />
           </svg>
         </summary>
-        <ul class={depth === 0 ? '' : 'ml-2 border-l border-border/70 pl-1.5'}>
+        <ul
+          class={
+            depth === 0
+              ? 'space-y-0.5'
+              : 'ml-3 space-y-0.5 border-l border-border/50 pl-2'
+          }
+        >
           {children.map((child) => (
             <Astro.self page={child} depth={depth + 1} />
           ))}
diff --git a/src/design-system/docs-shell/DocsToc.astro b/src/design-system/docs-shell/DocsToc.astro
index ff8cabe7a4..e5321f2fbe 100644
--- a/src/design-system/docs-shell/DocsToc.astro
+++ b/src/design-system/docs-shell/DocsToc.astro
@@ -10,13 +10,66 @@ interface Props {
 const { items } = Astro.props;
 ---
 
-<aside class="hidden xl:block w-56 shrink-0" aria-label="On this page" data-component="DocsToc">
-  <nav class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto py-14 pl-6">
-    <p
-      class="mb-3 flex items-center gap-2 text-[0.74rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground/70"
+<aside
+  class="hidden xl:block w-56 shrink-0"
+  aria-label="On this page"
+  data-component="DocsToc"
+>
+  <nav
+    class="ds-toc sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto py-14 pl-6"
+  >
+    <div class="ds-toc__head">
+      <p class="ds-toc__title">
+        <svg
+          class="ds-toc__title-icon"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"></path>
+        </svg>
+        On this page
+      </p>
+      <span class="ds-toc__pct" data-toc-pct aria-hidden="true">0%</span>
+    </div>
+
+    <div class="ds-toc__rail-wrap">
+      <span class="ds-toc__rail" aria-hidden="true"></span>
+      <span class="ds-toc__progress" data-toc-progress aria-hidden="true"
+      ></span>
+      <span class="ds-toc__thumb" data-toc-thumb aria-hidden="true"></span>
+
+      <ul class="ds-toc__list" data-toc>
+        {
+          items.map((item) => (
+            <li>
+              <a
+                href={item.href}
+                data-toc-link
+                class={`ds-toc__link ${item.depth === 2 ? 'is-nested' : ''}`}
+              >
+                <span class="ds-toc__dot" aria-hidden="true" />
+                <span class="ds-toc__label">{item.label}</span>
+              </a>
+            </li>
+          ))
+        }
+      </ul>
+    </div>
+
+    <a
+      href="#"
+      class="ds-toc__top"
+      data-toc-top
+      tabindex="-1"
+      aria-hidden="true"
     >
       <svg
-        class="h-3.5 w-3.5"
+        class="ds-toc__top-icon"
         viewBox="0 0 24 24"
         fill="none"
         stroke="currentColor"
@@ -25,34 +78,249 @@ const { items } = Astro.props;
         stroke-linejoin="round"
         aria-hidden="true"
       >
-        <path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"></path>
+        <path d="M12 19V5M5 12l7-7 7 7"></path>
       </svg>
-      On this page
-    </p>
-    <ul class="space-y-0.5 border-l border-border" data-toc>
-      {
-        items.map((item) => (
-          <li>
-            <a
-              href={item.href}
-              data-toc-link
-              class={`-ml-px block border-l-2 border-transparent py-[0.3rem] text-[0.875rem] leading-snug text-muted-foreground transition-colors duration-150 hover:border-primary/50 hover:text-foreground aria-[current=true]:border-primary aria-[current=true]:font-medium aria-[current=true]:text-primary ${
-                item.depth === 2 ? 'pl-7' : 'pl-4'
-              }`}
-            >
-              {item.label}
-            </a>
-          </li>
-        ))
-      }
-    </ul>
+      Back to top
+    </a>
   </nav>
 </aside>
 
+<style>
+  /* TOC: continuous rail with a brand reading-progress fill and a sliding
+     active thumb. Active state is driven by aria-current from the scroll-spy
+     script; thumb position/height come from --thumb-* set in the script. */
+  .ds-toc {
+    --thumb-top: 0px;
+    --thumb-h: 0px;
+    --thumb-on: 0;
+    --toc-progress: 0%;
+  }
+
+  .ds-toc__head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    margin-bottom: 0.9rem;
+  }
+  .ds-toc__title {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-size: 0.74rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: color-mix(in oklab, var(--muted-foreground) 78%, transparent);
+  }
+  .ds-toc__title-icon {
+    height: 0.85rem;
+    width: 0.85rem;
+    color: var(--primary);
+  }
+  .ds-toc__pct {
+    font-family: var(--font-mono);
+    font-size: 0.66rem;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+    font-variant-numeric: tabular-nums;
+    color: color-mix(in oklab, var(--muted-foreground) 60%, transparent);
+    opacity: 0;
+    transform: translateY(-2px);
+    transition:
+      opacity 0.3s ease,
+      transform 0.3s ease;
+  }
+  .ds-toc[data-scrolled] .ds-toc__pct {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  .ds-toc__rail-wrap {
+    position: relative;
+  }
+  /* Base rail: the faint track. */
+  .ds-toc__rail {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: 2px;
+    border-radius: 9999px;
+    background: var(--border);
+  }
+  /* Reading-progress fill grows top-down with scroll. */
+  .ds-toc__progress {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 2px;
+    height: var(--toc-progress);
+    border-radius: 9999px;
+    background: var(--gradient-brand);
+    box-shadow: 0 0 8px -1px var(--glow-brand);
+    transition: height 0.15s linear;
+  }
+  /* Sliding active thumb: a brighter, glowing segment of the rail. */
+  .ds-toc__thumb {
+    position: absolute;
+    left: -1px;
+    top: 0;
+    width: 4px;
+    height: var(--thumb-h);
+    border-radius: 9999px;
+    background: var(--primary);
+    box-shadow:
+      0 0 0 1px color-mix(in oklab, var(--primary) 35%, transparent),
+      0 0 14px -1px var(--glow-primary);
+    opacity: var(--thumb-on);
+    transform: translateY(var(--thumb-top));
+    transition:
+      transform 0.32s cubic-bezier(0.16, 1, 0.3, 1),
+      height 0.32s cubic-bezier(0.16, 1, 0.3, 1),
+      opacity 0.25s ease;
+  }
+
+  .ds-toc__list {
+    position: relative;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+  .ds-toc__list li {
+    margin: 0;
+  }
+
+  .ds-toc__link {
+    position: relative;
+    display: flex;
+    align-items: baseline;
+    gap: 0.55rem;
+    padding: 0.34rem 0 0.34rem 1rem;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    color: var(--muted-foreground);
+    text-decoration: none;
+    border-radius: 0.3rem;
+    transition:
+      color 0.2s ease,
+      transform 0.2s ease;
+  }
+  .ds-toc__link.is-nested {
+    padding-left: 1.75rem;
+    font-size: 0.82rem;
+  }
+  /* Small leading dot brightens on hover/active for a tactile feel. */
+  .ds-toc__dot {
+    flex: none;
+    margin-top: 0.5em;
+    height: 4px;
+    width: 4px;
+    border-radius: 9999px;
+    background: color-mix(in oklab, var(--muted-foreground) 45%, transparent);
+    transition:
+      background 0.2s ease,
+      box-shadow 0.2s ease,
+      transform 0.2s ease;
+  }
+  .ds-toc__link.is-nested .ds-toc__dot {
+    height: 3px;
+    width: 3px;
+  }
+  .ds-toc__label {
+    transition: inherit;
+  }
+
+  .ds-toc__link:hover {
+    color: var(--foreground);
+    transform: translateX(2px);
+  }
+  .ds-toc__link:hover .ds-toc__dot {
+    background: color-mix(in oklab, var(--primary) 70%, transparent);
+  }
+  .ds-toc__link[aria-current='true'] {
+    color: var(--primary);
+    font-weight: 550;
+  }
+  .ds-toc__link[aria-current='true'] .ds-toc__dot {
+    background: var(--primary);
+    transform: scale(1.4);
+    box-shadow: 0 0 8px 0 var(--glow-primary);
+  }
+  .ds-toc__link:focus-visible {
+    outline: none;
+    color: var(--foreground);
+    box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 60%, transparent);
+  }
+
+  /* Back to top: appears once the reader has scrolled. */
+  .ds-toc__top {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    margin-top: 1.4rem;
+    padding: 0.3rem 0.1rem;
+    font-size: 0.78rem;
+    font-weight: 500;
+    color: var(--muted-foreground);
+    text-decoration: none;
+    opacity: 0;
+    transform: translateY(4px);
+    pointer-events: none;
+    transition:
+      color 0.2s ease,
+      opacity 0.3s ease,
+      transform 0.3s ease;
+  }
+  .ds-toc[data-scrolled] .ds-toc__top {
+    opacity: 1;
+    transform: translateY(0);
+    pointer-events: auto;
+  }
+  .ds-toc__top:hover {
+    color: var(--primary);
+  }
+  .ds-toc__top:focus-visible {
+    outline: none;
+    color: var(--foreground);
+    border-radius: 0.3rem;
+    box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 60%, transparent);
+  }
+  .ds-toc__top-icon {
+    height: 0.85rem;
+    width: 0.85rem;
+    transition: transform 0.2s ease;
+  }
+  .ds-toc__top:hover .ds-toc__top-icon {
+    transform: translateY(-2px);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ds-toc__thumb,
+    .ds-toc__progress,
+    .ds-toc__link,
+    .ds-toc__dot,
+    .ds-toc__pct,
+    .ds-toc__top,
+    .ds-toc__top-icon {
+      transition: none;
+    }
+    .ds-toc__link:hover {
+      transform: none;
+    }
+  }
+</style>
+
 <script is:inline>
   (() => {
+    const root = document.querySelector('[data-component="DocsToc"] .ds-toc');
     const links = Array.from(document.querySelectorAll('[data-toc-link]'));
-    if (!links.length) return;
+    if (!root || !links.length) return;
+
+    const thumb = root.querySelector('[data-toc-thumb]');
+    const pctEl = root.querySelector('[data-toc-pct]');
+    const topBtn = root.querySelector('[data-toc-top]');
+
     const byId = new Map();
     const targets = [];
     for (const link of links) {
@@ -64,13 +332,26 @@ const { items } = Astro.props;
         targets.push(el);
       }
     }
+
+    // Slide the active thumb to the current link (relative to the list).
+    const moveThumb = (link) => {
+      if (!thumb || !link) return;
+      const h = link.offsetHeight * 0.6;
+      const top = link.offsetTop + (link.offsetHeight - h) / 2;
+      root.style.setProperty('--thumb-top', `${top}px`);
+      root.style.setProperty('--thumb-h', `${h}px`);
+      root.style.setProperty('--thumb-on', '1');
+    };
+
     let current = null;
     const setActive = (id) => {
       if (id === current) return;
       current = id;
       for (const [lid, link] of byId)
         link.setAttribute('aria-current', lid === id ? 'true' : 'false');
+      moveThumb(byId.get(id));
     };
+
     const observer = new IntersectionObserver(
       (entries) => {
         const visible = entries
@@ -81,5 +362,48 @@ const { items } = Astro.props;
       { rootMargin: '-88px 0px -65% 0px', threshold: 0 }
     );
     targets.forEach((t) => observer.observe(t));
+
+    // Reading progress + scrolled affordances, throttled to animation frames.
+    let ticking = false;
+    const onScroll = () => {
+      if (ticking) return;
+      ticking = true;
+      requestAnimationFrame(() => {
+        ticking = false;
+        const doc = document.documentElement;
+        const max = doc.scrollHeight - doc.clientHeight;
+        const pct = max > 0 ? Math.min(1, Math.max(0, doc.scrollTop / max)) : 0;
+        root.style.setProperty('--toc-progress', `${(pct * 100).toFixed(1)}%`);
+        if (pctEl) pctEl.textContent = `${Math.round(pct * 100)}%`;
+        if (doc.scrollTop > 120) root.setAttribute('data-scrolled', '');
+        else root.removeAttribute('data-scrolled');
+      });
+    };
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', () => {
+      moveThumb(byId.get(current));
+      onScroll();
+    });
+    onScroll();
+
+    // Keep "Back to top" keyboard-reachable only when visible.
+    if (topBtn) {
+      const sync = () => {
+        const on = root.hasAttribute('data-scrolled');
+        topBtn.setAttribute('tabindex', on ? '0' : '-1');
+        topBtn.setAttribute('aria-hidden', on ? 'false' : 'true');
+      };
+      new MutationObserver(sync).observe(root, {
+        attributes: true,
+        attributeFilter: ['data-scrolled'],
+      });
+      topBtn.addEventListener('click', (e) => {
+        e.preventDefault();
+        const reduce = window.matchMedia(
+          '(prefers-reduced-motion: reduce)'
+        ).matches;
+        window.scrollTo({ top: 0, behavior: reduce ? 'auto' : 'smooth' });
+      });
+    }
   })();
 </script>
diff --git a/src/design-system/theme.css b/src/design-system/theme.css
index c54de458c1..5ce1e3950c 100644
--- a/src/design-system/theme.css
+++ b/src/design-system/theme.css
@@ -1,10 +1,7 @@
 /*
-  Design-system entry (MVP). Importing this file is what opts a page into the
-  new UI: it pulls Tailwind v4, the typography plugin, the brand tokens, and
-  maps those tokens into Tailwind's theme so utilities like `bg-background`,
-  `text-foreground`, `border-border`, `text-primary` resolve to brand values.
-
-  Nothing here leaks onto pages that don't import it.
+  Design-system entry. Importing this opts a page in: Tailwind v4 + typography
+  plugin + brand tokens mapped into the theme. Web fonts load in the layout
+  <head>. Nothing here leaks onto pages that don't import it.
 */
 
 @import 'tailwindcss';
@@ -39,33 +36,157 @@
   --color-surface: var(--surface);
   --color-surface-2: var(--surface-2);
 
+  --font-display: var(--font-display);
   --font-sans: var(--font-sans);
   --font-mono: var(--font-mono);
 
   --radius-lg: var(--radius);
   --radius-md: calc(var(--radius) - 2px);
   --radius-sm: calc(var(--radius) - 4px);
-  --radius-xl: calc(var(--radius) + 4px);
+  --radius-xl: calc(var(--radius) + 5px);
 
   --shadow-sm: var(--shadow-sm);
   --shadow-md: var(--shadow-md);
   --shadow-lg: var(--shadow-lg);
+  --shadow-glow: var(--shadow-glow);
 }
 
-/* Reserve the vertical scrollbar gutter from first paint so a late-appearing
-   scrollbar (e.g. after images load) can't narrow the viewport and shift the
-   centered header/content sideways. */
+/* Reserve the scrollbar gutter so a late-appearing scrollbar can't shift the
+   centered layout sideways. Smooth in-page scrolling for the TOC anchors. */
 html {
   scrollbar-gutter: stable;
+  scroll-behavior: smooth;
+  -webkit-text-size-adjust: 100%;
+}
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+
+/* Tinted, thin scrollbars that match the abyss. */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: color-mix(in oklab, var(--muted-foreground) 35%, transparent)
+    transparent;
+}
+*::-webkit-scrollbar {
+  width: 9px;
+  height: 9px;
+}
+*::-webkit-scrollbar-thumb {
+  background: color-mix(in oklab, var(--muted-foreground) 32%, transparent);
+  border-radius: 9999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+*::-webkit-scrollbar-thumb:hover {
+  background: color-mix(in oklab, var(--muted-foreground) 55%, transparent);
+  background-clip: padding-box;
 }
 
-/* Tune the `prose` typography plugin to brand tokens so markdown content
-   matches the design system without bespoke per-element CSS.
+::selection {
+  background: color-mix(in oklab, var(--primary) 24%, transparent);
+  color: var(--foreground);
+}
+
+/* Atmosphere: fixed aurora mesh + grid + grain, behind everything (z-index:-1).
+   Layout renders the .ds-atmosphere / .ds-grain divs. */
+.ds-atmosphere {
+  position: fixed;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background:
+    radial-gradient(52rem 38rem at 12% -8%, var(--aurora-1), transparent 60%),
+    radial-gradient(46rem 40rem at 100% 0%, var(--aurora-2), transparent 58%),
+    radial-gradient(60rem 46rem at 78% 108%, var(--aurora-3), transparent 62%);
+  background-color: var(--background);
+}
+.ds-atmosphere::before {
+  /* Engineering grid, masked to fade inward. */
+  content: '';
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(to right, var(--grid-line) 1px, transparent 1px),
+    linear-gradient(to bottom, var(--grid-line) 1px, transparent 1px);
+  background-size: 56px 56px;
+  background-position: center top;
+  -webkit-mask-image: radial-gradient(
+    120% 80% at 50% 0%,
+    #000 0%,
+    transparent 75%
+  );
+  mask-image: radial-gradient(120% 80% at 50% 0%, #000 0%, transparent 75%);
+}
+.ds-atmosphere::after {
+  /* Slow-drifting luminous bloom. */
+  content: '';
+  position: absolute;
+  inset: -20% -10% auto -10%;
+  height: 60%;
+  background: radial-gradient(
+    40rem 22rem at 30% 0%,
+    var(--aurora-1),
+    transparent 70%
+  );
+  opacity: 0.7;
+  animation: ds-drift 22s ease-in-out infinite alternate;
+}
+.ds-grain {
+  position: fixed;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  opacity: var(--grain-opacity);
+  mix-blend-mode: soft-light;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+
+@keyframes ds-drift {
+  from {
+    transform: translate3d(-3%, -2%, 0) scale(1);
+  }
+  to {
+    transform: translate3d(5%, 3%, 0) scale(1.12);
+  }
+}
 
-   These rules are intentionally UNLAYERED: the typography plugin sets its
-   default `--tw-prose-*` color vars from the `prose` utility (utilities layer),
-   which would beat an `@layer base` override. Unlayered rules win over any
-   layered rule, so this is what makes our brand tokens (and dark mode) stick. */
+/* Staggered page-load reveal: [data-rise] fades/lifts, --rise sets the delay. */
+@keyframes ds-rise {
+  from {
+    opacity: 0;
+    transform: translateY(14px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+[data-rise] {
+  animation: ds-rise 0.7s cubic-bezier(0.16, 1, 0.3, 1) both;
+  animation-delay: var(--rise, 0ms);
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-rise] {
+    animation: none;
+  }
+  .ds-atmosphere::after {
+    animation: none;
+  }
+}
+
+/* Gradient brand text (hero H1 / accents). */
+.ds-gradient-text {
+  background: var(--gradient-ink);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+/* Prose: brand-tuned typography. Intentionally UNLAYERED to beat the typography
+   plugin's utility-layer defaults (keeps brand colors + dark mode). */
 .prose {
   --tw-prose-body: var(--foreground);
   --tw-prose-headings: var(--foreground);
@@ -74,7 +195,7 @@ html {
   --tw-prose-counters: var(--muted-foreground);
   --tw-prose-bullets: var(--octo-navy-300);
   --tw-prose-hr: var(--border);
-  --tw-prose-quotes: var(--muted-foreground);
+  --tw-prose-quotes: var(--foreground);
   --tw-prose-quote-borders: var(--primary);
   --tw-prose-captions: var(--muted-foreground);
   --tw-prose-code: var(--foreground);
@@ -83,28 +204,44 @@ html {
   --tw-prose-pre-bg: var(--code-bg);
   --tw-prose-pre-code: var(--code-foreground);
   max-width: 46rem;
-  font-size: 1rem;
-  line-height: 1.75;
+  font-size: 1.02rem;
+  line-height: 1.78;
+  font-feature-settings: 'ss01', 'cv01';
 }
 
-/* Typographic rhythm: calmer vertical spacing and tighter, confident headings. */
+/* Confident display headings with a luminous anchored accent. */
 .prose :where(h2):not(:where([class~='not-prose'] *)) {
-  margin-top: 2.75rem;
+  position: relative;
+  margin-top: 3rem;
   margin-bottom: 1rem;
-  font-size: 1.5rem;
-  line-height: 1.3;
-  font-weight: 650;
-  letter-spacing: -0.014em;
-  scroll-margin-top: 5.5rem;
+  font-family: var(--font-display);
+  font-size: 1.7rem;
+  line-height: 1.22;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  scroll-margin-top: 6rem;
+}
+/* Glowing tick to the left of every H2. */
+.prose :where(h2):not(:where([class~='not-prose'] *))::before {
+  content: '';
+  position: absolute;
+  left: -1.15rem;
+  top: 0.45em;
+  height: 1.05em;
+  width: 3px;
+  border-radius: 9999px;
+  background: var(--gradient-brand);
+  box-shadow: 0 0 12px -1px var(--glow-primary);
 }
 .prose :where(h3):not(:where([class~='not-prose'] *)) {
-  margin-top: 2rem;
-  margin-bottom: 0.625rem;
-  font-size: 1.2rem;
-  line-height: 1.35;
-  font-weight: 625;
-  letter-spacing: -0.01em;
-  scroll-margin-top: 5.5rem;
+  margin-top: 2.1rem;
+  margin-bottom: 0.6rem;
+  font-family: var(--font-display);
+  font-size: 1.28rem;
+  line-height: 1.32;
+  font-weight: 650;
+  letter-spacing: -0.014em;
+  scroll-margin-top: 6rem;
 }
 .prose :where(h2, h3):not(:where([class~='not-prose'] *)):first-child {
   margin-top: 0;
@@ -114,53 +251,87 @@ html {
   margin-bottom: 1.25rem;
 }
 .prose :where(strong):not(:where([class~='not-prose'] *)) {
-  font-weight: 625;
+  font-weight: 650;
+  color: var(--foreground);
 }
+
+/* Links: an underline that grows in from the left on hover. */
 .prose :where(a):not(:where([class~='not-prose'] *)) {
   font-weight: 500;
-  text-decoration-color: color-mix(in oklab, var(--primary) 35%, transparent);
-  text-underline-offset: 2px;
-  transition:
-    text-decoration-color 0.15s ease,
-    color 0.15s ease;
+  text-decoration: none;
+  color: var(--primary);
+  background-image: linear-gradient(var(--primary), var(--primary));
+  background-position: 0 100%;
+  background-repeat: no-repeat;
+  background-size: 100% 1px;
+  padding-bottom: 1px;
+  transition: background-size 0.25s ease;
 }
 .prose :where(a):not(:where([class~='not-prose'] *)):hover {
-  text-decoration-color: var(--primary);
+  background-size: 100% 2px;
 }
 
 /* Lists: tidy markers and spacing. */
 .prose :where(ol > li, ul > li):not(:where([class~='not-prose'] *)) {
-  margin-top: 0.375rem;
-  margin-bottom: 0.375rem;
+  margin-top: 0.4rem;
+  margin-bottom: 0.4rem;
   padding-left: 0.4em;
 }
 .prose :where(ol > li)::marker:not(:where([class~='not-prose'] *)) {
   font-weight: 600;
-  color: var(--muted-foreground);
+  color: var(--primary);
+}
+.prose :where(ul > li)::marker:not(:where([class~='not-prose'] *)) {
+  color: var(--primary);
+}
+
+/* Blockquote: glassy panel with a luminous edge. */
+.prose :where(blockquote):not(:where([class~='not-prose'] *)) {
+  margin: 1.75rem 0;
+  padding: 0.9rem 1.25rem;
+  border: 0;
+  border-left: 3px solid transparent;
+  border-image: var(--gradient-brand) 1;
+  border-radius: 0 var(--radius) var(--radius) 0;
+  background: color-mix(in oklab, var(--primary) 6%, transparent);
+  font-style: normal;
+  font-weight: 450;
+  color: var(--foreground);
+}
+.prose :where(blockquote p:first-of-type)::before,
+.prose :where(blockquote p:last-of-type)::after {
+  content: '';
 }
 
-/* Horizontal rule */
+/* Horizontal rule: a faded brand line. */
 .prose :where(hr):not(:where([class~='not-prose'] *)) {
   margin-top: 3rem;
   margin-bottom: 3rem;
+  border: 0;
+  height: 1px;
+  background: linear-gradient(
+    to right,
+    transparent,
+    var(--border) 18%,
+    var(--border) 82%,
+    transparent
+  );
 }
 
-/* --- Code block treatment: a calm bordered surface with a slim label bar.
-   Inspired by Stripe/Vercel/Linear docs - the code is the hero, the chrome is
-   quiet. The label bar (filename/language) and copy affordance live in a
-   `figure.code-block` wrapper rendered alongside the <pre>. */
+/* Code blocks. The label bar + copy button live in a figure.code-block wrapper. */
 .prose :where(pre):not(:where([class~='not-prose'] *)) {
   position: relative;
   margin-top: 1.5rem;
   margin-bottom: 1.5rem;
-  padding: 1.15rem 1.25rem;
+  padding: 1.2rem 1.3rem;
   background: var(--code-bg);
   color: var(--code-foreground);
   border: 1px solid var(--code-border);
   border-radius: var(--radius-lg);
-  box-shadow: var(--shadow-sm);
-  font-size: 0.875rem;
-  line-height: 1.75;
+  box-shadow: var(--shadow-md);
+  font-family: var(--font-mono);
+  font-size: 0.86rem;
+  line-height: 1.78;
   overflow-x: auto;
 }
 .prose :where(pre code):not(:where([class~='not-prose'] *)) {
@@ -171,54 +342,68 @@ html {
   color: inherit;
 }
 
-/* Code-block wrapper: slim top bar + bordered body sharing one frame. */
+/* Code-block wrapper: top bar + body in one frame, with a lit top edge. */
 .prose :where(.code-block):not(:where([class~='not-prose'] *)) {
-  margin-top: 1.5rem;
-  margin-bottom: 1.5rem;
+  position: relative;
+  text-align: left;
+  margin-top: 1.75rem;
+  margin-bottom: 1.75rem;
   border: 1px solid var(--code-border);
   border-radius: var(--radius-lg);
   background: var(--code-bg);
-  box-shadow: var(--shadow-sm);
+  box-shadow: var(--shadow-md);
   overflow: hidden;
 }
+.prose :where(.code-block):not(:where([class~='not-prose'] *))::before {
+  content: '';
+  position: absolute;
+  inset: -1px -1px auto -1px;
+  height: 1px;
+  background: linear-gradient(
+    to right,
+    transparent,
+    color-mix(in oklab, var(--octo-blue-bright) 55%, transparent),
+    color-mix(in oklab, var(--pink-100) 45%, transparent),
+    transparent
+  );
+}
 .code-block > .code-block__bar {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  height: 2.5rem;
-  padding: 0 0.5rem 0 0.9rem;
+  height: 2.6rem;
+  padding: 0 0.5rem 0 1rem;
   background: var(--code-chrome);
   border-bottom: 1px solid var(--code-border);
 }
 .code-block__label {
   display: inline-flex;
   align-items: center;
-  gap: 0.45rem;
+  gap: 0.5rem;
   font-family: var(--font-mono);
   font-size: 0.72rem;
-  letter-spacing: 0.02em;
+  letter-spacing: 0.03em;
   font-weight: 500;
-  color: color-mix(in oklab, var(--code-foreground) 62%, transparent);
+  color: color-mix(in oklab, var(--code-foreground) 64%, transparent);
 }
 .code-block__label svg {
-  width: 0.85rem;
-  height: 0.85rem;
-  color: color-mix(in oklab, var(--code-foreground) 45%, transparent);
+  width: 0.9rem;
+  height: 0.9rem;
+  color: color-mix(in oklab, var(--octo-blue-bright) 70%, transparent);
 }
-/* When wrapped (figure is .not-prose), the inner <pre> is excluded from the
-   prose pre rules, so re-apply the code surface here and drop the outer frame -
-   the figure provides it. */
+/* The inner <pre> (inside the .not-prose figure) re-states the code surface. */
 .code-block > pre {
   margin: 0;
-  padding: 1.15rem 1.25rem;
+  text-align: left;
+  padding: 1.2rem 1.3rem;
   border: 0;
   border-radius: 0;
   box-shadow: none;
   background: var(--code-bg);
   color: var(--code-foreground);
   font-family: var(--font-mono);
-  font-size: 0.875rem;
-  line-height: 1.75;
+  font-size: 0.86rem;
+  line-height: 1.78;
   overflow-x: auto;
 }
 .code-block > pre code {
@@ -233,8 +418,8 @@ html {
   display: inline-flex;
   align-items: center;
   gap: 0.4rem;
-  height: 1.75rem;
-  padding: 0 0.55rem;
+  height: 1.8rem;
+  padding: 0 0.6rem;
   border: 1px solid transparent;
   border-radius: var(--radius-sm);
   background: transparent;
@@ -290,23 +475,24 @@ html {
   border-collapse: separate;
   border-spacing: 0;
   overflow: hidden;
-  font-size: 0.95rem;
+  font-size: 0.94rem;
+  background: color-mix(in oklab, var(--card) 60%, transparent);
 }
 .prose :where(thead):not(:where([class~='not-prose'] *)) {
   background: var(--muted);
   border-bottom: 1px solid var(--border);
 }
 .prose :where(thead th):not(:where([class~='not-prose'] *)) {
-  padding: 0.7rem 1rem;
-  font-size: 0.82rem;
-  font-weight: 600;
-  letter-spacing: 0.02em;
+  padding: 0.72rem 1rem;
+  font-size: 0.72rem;
+  font-weight: 650;
+  letter-spacing: 0.06em;
   text-transform: uppercase;
   color: var(--muted-foreground);
   border-bottom: 1px solid var(--border);
 }
 .prose :where(tbody td):not(:where([class~='not-prose'] *)) {
-  padding: 0.7rem 1rem;
+  padding: 0.72rem 1rem;
   border-bottom: 1px solid var(--border);
   vertical-align: middle;
 }
@@ -317,18 +503,19 @@ html {
   background: color-mix(in oklab, var(--muted) 45%, transparent);
 }
 .prose :where(tbody tr):not(:where([class~='not-prose'] *)):hover {
-  background: color-mix(in oklab, var(--primary) 6%, transparent);
+  background: color-mix(in oklab, var(--primary) 7%, transparent);
 }
 
 /* Inline code chips, brand-tinted */
 .prose :not(pre) > code {
-  background: color-mix(in oklab, var(--muted) 70%, var(--background));
-  color: var(--foreground);
-  border: 1px solid var(--border);
-  padding: 0.1em 0.4em;
+  background: color-mix(in oklab, var(--primary) 10%, var(--background));
+  color: color-mix(in oklab, var(--primary) 72%, var(--foreground));
+  border: 1px solid color-mix(in oklab, var(--primary) 22%, transparent);
+  padding: 0.12em 0.42em;
   border-radius: var(--radius-sm);
+  font-family: var(--font-mono);
   font-weight: 500;
-  font-size: 0.8125em;
+  font-size: 0.8em;
   white-space: nowrap;
 }
 .prose :not(pre) > code::before,
@@ -343,7 +530,7 @@ html {
   gap: 0.4rem;
   padding: 0.15rem 0.6rem 0.15rem 0.5rem;
   border-radius: 9999px;
-  font-size: 0.75rem;
+  font-size: 0.74rem;
   font-weight: 600;
   line-height: 1.4;
   white-space: nowrap;
@@ -355,6 +542,21 @@ html {
   border-radius: 9999px;
   background: currentColor;
   box-shadow: 0 0 0 3px color-mix(in oklab, currentColor 22%, transparent);
+  animation: ds-pulse 2.4s ease-in-out infinite;
+}
+@keyframes ds-pulse {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 color-mix(in oklab, currentColor 35%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 4px color-mix(in oklab, currentColor 8%, transparent);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .status-dot {
+    animation: none;
+  }
 }
 .status-pill--ok {
   color: var(--success-border);
@@ -369,8 +571,7 @@ html {
 
 /* --- Callout boxes (remark directive output) ---
    Authored as `:::div{.hint|.info|.success|.warning|.problem|.question}` and
-   rendered as raw `<div class="...">` inside .prose. Match ui/Callout.astro:
-   soft border + stronger left accent, tinted bg, comfortable padding. */
+   rendered as raw `<div class="...">` inside .prose. Match ui/Callout.astro. */
 .prose
   :where(
     div.hint,
@@ -380,18 +581,19 @@ html {
     div.problem,
     div.question
   ):not(:where([class~='not-prose'] *)) {
-  margin-top: 1.5rem;
-  margin-bottom: 1.5rem;
-  padding: 0.95rem 1.1rem;
-  border: 1px solid color-mix(in oklab, var(--bd) 35%, transparent);
+  position: relative;
+  margin-top: 1.6rem;
+  margin-bottom: 1.6rem;
+  padding: 1rem 1.15rem 1rem 1.2rem;
+  border: 1px solid color-mix(in oklab, var(--bd) 32%, transparent);
   border-left: 3px solid var(--bd);
   border-radius: var(--radius-lg);
   background: var(--bg);
   color: var(--c);
   font-size: 0.95rem;
-  line-height: 1.65;
+  line-height: 1.66;
+  box-shadow: var(--shadow-sm);
 }
-/* Intent token mapping (hint -> info/blue, question -> neutral/muted). */
 .prose :where(div.hint, div.info):not(:where([class~='not-prose'] *)) {
   --c: var(--info);
   --bg: var(--info-bg);
@@ -417,7 +619,6 @@ html {
   --bg: var(--question-bg);
   --bd: var(--question-border);
 }
-/* Tighten internal spacing and inherit the intent text color. */
 .prose
   :where(
     div.hint,
@@ -457,35 +658,76 @@ html {
   margin-bottom: 0;
 }
 
-/* --- Figures / images (remark `:::figure` directive output) ---
-   Rendered with .image (figure), .image__img (img), .image__caption (caption).
-   Center, constrain, round, subtle border; keep responsive srcset intact. */
-.prose :where(figure, .image):not(:where([class~='not-prose'] *)) {
-  margin-top: 1.75rem;
-  margin-bottom: 1.75rem;
+/* In-content image "glass" effect (from the marketing site), scoped to .prose
+   so chrome imagery is untouched. Frosted panel + blurred bloom (::before)
+   behind; image/caption above via z-index. Tokens: --glass-* in tokens.css. */
+.prose :where(figure, .image, [data-image]):not(:where([class~='not-prose'] *)),
+.prose p:has(> img.resp-img:only-child):not(:where([class~='not-prose'] *)) {
+  position: relative;
+  isolation: isolate;
+  width: fit-content;
+  max-width: 100%;
+  margin: 2.25rem auto;
+  padding: var(--glass-pad);
+  border-radius: var(--radius-lg);
+  background: var(--glass-background);
+  border: 1px solid var(--glass-border-color);
+  box-shadow: var(--glass-shadow);
+  overflow: visible;
   text-align: center;
 }
-.prose :where(figure > p):not(:where([class~='not-prose'] *)) {
-  margin: 0;
-}
-.prose :where(img, .image__img):not(:where([class~='not-prose'] *)) {
-  display: inline-block;
+.prose
+  :where(figure, .image, [data-image]):not(
+    :where([class~='not-prose'] *)
+  )::before,
+.prose
+  p:has(> img.resp-img:only-child):not(:where([class~='not-prose'] *))::before {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  filter: blur(60px);
+  z-index: 0;
+  pointer-events: none;
+  background: var(--glass-blur-glow);
+}
+/* Inner image stacks above the bloom. */
+.prose
+  :where(figure, .image, [data-image]):not(:where([class~='not-prose'] *))
+  :where(img, .image__img),
+.prose
+  p:has(> img.resp-img:only-child):not(:where([class~='not-prose'] *))
+  > img {
+  position: relative;
+  z-index: 1;
+  display: block;
   max-width: 100%;
   height: auto;
-  border: 1px solid var(--border);
-  border-radius: var(--radius-lg);
+  /* Zero the plugin's block margins so glass padding is uniform on all sides. */
+  margin: 0 auto;
+  border-radius: calc(var(--radius-lg) - 0.15rem);
+}
+/* Strip prose margin from a wrapping <p> inside the figure. */
+.prose
+  :where(figure, .image, [data-image]):not(:where([class~='not-prose'] *))
+  :where(p):not(:where([class~='not-prose'] *)) {
+  margin: 0;
 }
-.prose :where(.image__caption):not(:where([class~='not-prose'] *)) {
+.prose :where(.image__caption, figcaption):not(:where([class~='not-prose'] *)) {
+  position: relative;
+  z-index: 1;
   display: block;
-  margin-top: 0.65rem;
+  margin-top: 0.7rem;
   text-align: center;
   color: var(--muted-foreground);
   font-size: 0.85rem;
   line-height: 1.5;
 }
 
-/* --- Table wrapper (wrapTables -> <div class="table-wrap">) ---
-   Allow horizontal scroll on overflow; the inner table keeps its own border. */
+/* --- Table wrapper (wrapTables -> <div class="table-wrap">) --- */
 .prose :where(.table-wrap):not(:where([class~='not-prose'] *)) {
   margin-top: 1.5rem;
   margin-bottom: 1.5rem;
@@ -496,17 +738,182 @@ html {
   margin-bottom: 0;
 }
 
-/* --- Shiki code blocks (`<pre class="astro-code ...">`) ---
-   Give our frame (border + radius + padding) but leave Shiki's inline bg/colors
-   alone. Known: this renders light against our dark code surface - deferred. */
+/* --- Shiki code blocks (`<pre class="astro-code ...">`) --- */
 .prose :where(pre.astro-code):not(:where([class~='not-prose'] *)) {
   margin-top: 1.5rem;
   margin-bottom: 1.5rem;
-  padding: 1.15rem 1.25rem;
-  border: 1px solid var(--border);
+  padding: 1.2rem 1.3rem;
+  border: 1px solid var(--code-border);
   border-radius: var(--radius-lg);
-  box-shadow: var(--shadow-sm);
-  font-size: 0.875rem;
+  box-shadow: var(--shadow-md);
+  font-size: 0.86rem;
   line-height: 1.7;
   overflow-x: auto;
 }
+
+/* Buttons (ported from the marketing site's pu-button mixins). Primary = purple
+   with a cursor-tracked pink glow; secondary = gradient-border (::after mask).
+   --hover-x/--hover-y are set by the inline script in Button.astro. In the
+   components layer so utilities (h-9, hidden, px-*) can override base sizing. */
+@layer components {
+  .ds-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    max-width: fit-content;
+    padding: var(--space-12) var(--space-24);
+    border-radius: 0.5rem;
+    border: 0.0625rem solid transparent;
+    font-family: var(--font-sans);
+    font-size: var(--button-font-size);
+    font-weight: var(--button-font-weight);
+    line-height: 1.2;
+    white-space: nowrap;
+    text-decoration: none;
+    cursor: pointer;
+    appearance: none;
+    transition-property: background, box-shadow, border-color, color;
+    transition-duration: 250ms;
+    transition-timing-function: ease-in-out;
+  }
+
+  .ds-btn--primary {
+    position: relative;
+    z-index: 0;
+    overflow: hidden;
+    color: var(--white);
+    background: var(--purple-300);
+    border: none;
+  }
+  .ds-btn--primary::before {
+    content: '';
+    position: absolute;
+    left: var(--hover-x, 50%);
+    top: var(--hover-y, 50%);
+    width: 16rem;
+    height: 16rem;
+    background: radial-gradient(
+      circle closest-side,
+      var(--pink-100),
+      transparent
+    );
+    transform: translate(-50%, -50%) scale(0);
+    transition: transform 0.3s ease;
+    z-index: -1;
+    pointer-events: none;
+  }
+  .ds-btn--primary:hover {
+    box-shadow: inset 0 0 0 0.0625rem rgba(255, 255, 255, 0.25);
+  }
+  .ds-btn--primary:hover::before {
+    transform: translate(-50%, -50%) scale(1);
+  }
+  .ds-btn--primary:active {
+    box-shadow: var(--button-shadow-inner);
+  }
+  .ds-btn--primary:focus-visible {
+    outline: 0.25rem solid rgba(105, 80, 255, 0.5);
+    box-shadow: none;
+  }
+  .ds-btn--primary:focus-visible::before {
+    transform: translate(-50%, -50%) scale(0);
+  }
+
+  .ds-btn--secondary {
+    position: relative;
+    z-index: 0;
+    overflow: hidden;
+    color: var(--secondary-button-text);
+    background: var(--secondary-button-bg);
+    border: none;
+  }
+  .ds-btn--secondary::before {
+    content: '';
+    position: absolute;
+    left: var(--hover-x, 50%);
+    top: var(--hover-y, 50%);
+    width: 14rem;
+    height: 14rem;
+    background: radial-gradient(
+      circle closest-side,
+      var(--secondary-button-hover-glow),
+      transparent
+    );
+    transform: translate(-50%, -50%) scale(0);
+    transition: transform 0.3s ease;
+    z-index: -1;
+    pointer-events: none;
+  }
+  /* Gradient border ring via a masked padding box. */
+  .ds-btn--secondary::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    padding: 0.0625rem;
+    background: var(--purple-300);
+    -webkit-mask-image: linear-gradient(#fff 0 0), linear-gradient(#fff 0 0);
+    -webkit-mask-clip: content-box, border-box;
+    -webkit-mask-composite: xor;
+    mask-image: linear-gradient(#fff 0 0), linear-gradient(#fff 0 0);
+    mask-clip: content-box, border-box;
+    mask-composite: exclude;
+    pointer-events: none;
+    z-index: 2;
+  }
+  .ds-btn--secondary svg path {
+    transition: stroke 200ms ease-in-out;
+  }
+  .ds-btn--secondary:hover {
+    color: var(--secondary-button-hover-text);
+    background: var(--secondary-button-hover-bg);
+  }
+  .ds-btn--secondary:hover svg path {
+    stroke: var(--secondary-button-hover-text);
+  }
+  .ds-btn--secondary:hover::before {
+    transform: translate(-50%, -50%) scale(1);
+  }
+  .ds-btn--secondary:hover::after {
+    background: radial-gradient(
+      circle 7rem at var(--hover-x, 50%) var(--hover-y, 50%),
+      var(--secondary-button-hover-border),
+      var(--purple-300)
+    );
+  }
+  .ds-btn--secondary:active {
+    box-shadow: var(--button-shadow-inner);
+  }
+  .ds-btn--secondary:active::before {
+    transform: translate(-50%, -50%) scale(0);
+  }
+  .ds-btn--secondary:active::after {
+    background: var(--purple-400);
+  }
+  .ds-btn--secondary:focus-visible {
+    background: var(--secondary-button-bg);
+    outline: 0.25rem solid var(--purple-300);
+    box-shadow: none;
+  }
+  .ds-btn--secondary:focus-visible::before {
+    transform: translate(-50%, -50%) scale(0);
+  }
+
+  /* Low-emphasis text button. */
+  .ds-btn--ghost {
+    color: var(--foreground);
+    background: transparent;
+    border-color: transparent;
+  }
+  .ds-btn--ghost:hover {
+    background: var(--muted);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ds-btn--primary::before,
+    .ds-btn--secondary::before {
+      transition: none;
+    }
+  }
+}
diff --git a/src/design-system/tokens.css b/src/design-system/tokens.css
index f864ab123a..672fa8db0f 100644
--- a/src/design-system/tokens.css
+++ b/src/design-system/tokens.css
@@ -1,12 +1,7 @@
 /*
-  Octopus docs design-system tokens (MVP).
-
-  This is the portable contract: brand primitives + shadcn-style semantic tokens,
-  light + dark. A microsite adopts the design system by shipping this file (and
-  theme.css) unchanged. Dark mode keys off [data-theme="dark"] to match the
-  existing site switch.
-
-  Brand source of truth: public/docs/css/vars.css.
+  Design-system tokens: brand primitives + shadcn-style semantic tokens + a
+  glow/aurora layer. Portable: ship this + theme.css unchanged. Dark mode keys
+  off [data-theme="dark"]. Brand source: public/docs/css/vars.css.
 */
 
 :root {
@@ -27,7 +22,7 @@
   --octo-blue-100: #f2f8fd;
 
   /* --- Semantic tokens (shadcn shape) --- */
-  --background: #ffffff;
+  --background: #f7fafc;
   --foreground: var(--octo-navy-900);
 
   --card: #ffffff;
@@ -40,16 +35,16 @@
   --primary-foreground: #ffffff;
 
   /* Octopus CTA green is the brand "accent" action color */
-  --accent: var(--octo-green);
-  --accent-foreground: #0a3b2a;
+  --accent: #00b86f;
+  --accent-foreground: #04241a;
 
   --secondary: var(--octo-navy-100);
   --secondary-foreground: var(--octo-navy-700);
 
   --muted: var(--octo-navy-100);
-  --muted-foreground: var(--octo-navy-600);
+  --muted-foreground: #587088;
 
-  --border: var(--octo-navy-200);
+  --border: #dde6ee;
   --input: var(--octo-navy-200);
   --ring: var(--octo-blue);
 
@@ -58,105 +53,236 @@
 
   /* Callout intents (map to existing hint/info/success/warning/problem) */
   --info: #124164;
-  --info-bg: #e5f4ff;
+  --info-bg: #eaf5ff;
   --info-border: var(--octo-blue);
   --success: #04502f;
-  --success-bg: #e8ffeb;
+  --success-bg: #e6fbef;
   --success-border: #00b065;
   --warning: #a23623;
-  --warning-bg: #fefae9;
+  --warning-bg: #fef7e7;
   --warning-border: #fc8431;
   --problem: #931919;
-  --problem-bg: #fff2ee;
+  --problem-bg: #fff1ed;
   --problem-border: #ff4848;
   /* question -> neutral/muted treatment */
   --question: var(--octo-navy-700);
   --question-bg: var(--octo-navy-100);
   --question-border: var(--octo-navy-400);
 
-  --sidebar: #fafdff;
-  --sidebar-foreground: var(--octo-navy-700);
+  --sidebar: #fbfdff;
+  --sidebar-foreground: #4a6076;
 
   /* Surfaces for layered UI (code blocks, window chrome, hover states) */
-  --surface: var(--octo-navy-100);
-  --surface-2: #f8fafc;
-  --code-bg: #0c1a24;
-  --code-foreground: #e6edf3;
-  --code-chrome: #142736;
-  --code-border: #1f3a52;
-
-  /* Elevation */
+  --surface: #f2f6fa;
+  --surface-2: #ffffff;
+  --code-bg: #0b1a26;
+  --code-foreground: #e6f0f7;
+  --code-chrome: #112637;
+  --code-border: #1d384d;
+
+  /* --- Bioluminescence: colored glows + accent gradients --- */
+  --glow-primary: color-mix(in oklab, var(--octo-blue) 38%, transparent);
+  --glow-accent: color-mix(in oklab, var(--octo-green) 42%, transparent);
+  /* Decorative brand glow (cyan->purple->pink language); green stays semantic. */
+  --glow-brand: color-mix(in oklab, var(--purple-300) 50%, transparent);
+  --gradient-brand: linear-gradient(
+    100deg,
+    var(--octo-blue-bright) 0%,
+    var(--purple-300) 52%,
+    var(--pink-100) 108%
+  );
+  --gradient-ink: linear-gradient(
+    100deg,
+    var(--octo-navy-900) 0%,
+    var(--purple-300) 60%,
+    var(--pink-100) 125%
+  );
+
+  /* --- Atmosphere (fixed background layers): cyan -> purple -> pink mesh --- */
+  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 20%, transparent);
+  --aurora-2: color-mix(in oklab, var(--pink-100) 14%, transparent);
+  --aurora-3: color-mix(in oklab, var(--purple-300) 16%, transparent);
+  --grid-line: color-mix(in oklab, var(--octo-navy-700) 6%, transparent);
+  --grain-opacity: 0.035;
+
+  /* Glass effect for in-content images (mirrors the marketing site). Raw
+     primitives are theme-independent; composed tokens here are light-adapted
+     (the white originals vanish on the pale bg), dark uses the exact values. */
+  --glass-white-31: hsla(0, 0%, 100%, 0.31);
+  --glass-white-35: hsla(0, 0%, 100%, 0.35);
+  --glass-white-20: hsla(0, 0%, 100%, 0.2);
+  --glass-white-15: hsla(0, 0%, 100%, 0.15);
+  --glass-cyan: rgba(147, 225, 255, 0.31);
+  --glass-cyan-glow: rgba(31, 192, 255, 0.45);
+  --glass-pink-glow: rgba(204, 60, 255, 0.5);
+  --glass-navy-fade: rgba(10, 35, 54, 0);
+  --glass-pad: 0.75rem;
+
+  --glass-background: linear-gradient(
+    263.36deg,
+    rgba(255, 255, 255, 0.72) -46.77%,
+    rgba(147, 225, 255, 0.42) 86.43%
+  );
+  --glass-border-color: rgba(31, 192, 255, 0.32);
+  --glass-shadow: 0 12px 36px -12px rgba(31, 192, 255, 0.3);
+  --glass-blur-glow: radial-gradient(
+    101.55% 101.55% at 50% -1.55%,
+    rgba(255, 255, 255, 0.55) 0%,
+    rgba(31, 192, 255, 0.38) 18.63%,
+    rgba(204, 60, 255, 0.3) 73.48%,
+    var(--glass-navy-fade) 100%
+  );
+
+  /* Marketing-site button palette + base (purple primary, gradient-border
+     secondary). Primary/palette are theme-independent; the --secondary-button-*
+     set below is light, overridden for dark. */
+  --white: #ffffff;
+  --purple-300: #6950ff;
+  --purple-400: #9747ff;
+  --pink-100: #cc3cff;
+  --space-12: 0.75rem;
+  --space-24: 1.5rem;
+  --button-font-size: 1rem;
+  --button-font-weight: 600;
+  --button-shadow-inner: inset 0 2px 6px rgba(0, 0, 0, 0.25);
+
+  --secondary-button-text: var(--purple-300);
+  --secondary-button-bg: transparent;
+  --secondary-button-hover-text: var(--pink-100);
+  --secondary-button-hover-bg: transparent;
+  --secondary-button-hover-glow: rgba(204, 60, 255, 0.15);
+  --secondary-button-hover-border: var(--pink-100);
+
+  /* Elevation - layered, slightly tinted toward the brand navy */
   --shadow-sm: 0 1px 2px 0 rgba(16, 33, 47, 0.06);
   --shadow-md:
-    0 4px 12px -2px rgba(16, 33, 47, 0.1), 0 2px 6px -2px rgba(16, 33, 47, 0.06);
+    0 4px 14px -3px rgba(16, 33, 47, 0.12),
+    0 2px 6px -2px rgba(16, 33, 47, 0.07);
   --shadow-lg:
-    0 12px 32px -8px rgba(16, 33, 47, 0.18),
-    0 4px 10px -4px rgba(16, 33, 47, 0.1);
+    0 18px 40px -12px rgba(16, 33, 47, 0.22),
+    0 6px 14px -6px rgba(16, 33, 47, 0.12);
+  --shadow-glow: 0 10px 40px -10px var(--glow-primary);
 
-  --radius: 0.5rem;
+  --radius: 0.65rem;
 
-  /* Fonts - preserve the existing system stack designers expect */
+  /* Fonts - distinctive type carries the redesign. Loaded via Bunny Fonts in
+     the layout head; system stacks remain as graceful fallbacks. */
+  --font-display:
+    'Bricolage Grotesque', 'Hanken Grotesk', system-ui, -apple-system,
+    BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-sans:
-    system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
-    'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
-    'Segoe UI Symbol';
-  --font-mono: Consolas, monaco, monospace;
+    'Hanken Grotesk', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI',
+    Roboto, 'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji',
+    'Segoe UI Emoji', 'Segoe UI Symbol';
+  --font-mono:
+    'JetBrains Mono', ui-monospace, SFMono-Regular, Consolas, monaco, monospace;
 }
 
 [data-theme='dark'] {
-  --background: #10202e;
-  --foreground: #dae2e9;
+  /* The abyss: deep navy with a faint blue cast, luminous accents. */
+  --background: #081521;
+  --foreground: #dde7ef;
 
-  --card: #132838;
-  --card-foreground: #dae2e9;
+  --card: #0e2231;
+  --card-foreground: #dde7ef;
 
-  --popover: #0c1a24;
-  --popover-foreground: #dae2e9;
+  --popover: #0b1d2a;
+  --popover-foreground: #dde7ef;
 
   --primary: var(--octo-blue-bright);
-  --primary-foreground: #06121b;
+  --primary-foreground: #04121c;
 
   --accent: var(--octo-green-bright);
-  --accent-foreground: #06121b;
+  --accent-foreground: #04241a;
 
-  --secondary: var(--octo-navy-800);
+  --secondary: #122a3c;
   --secondary-foreground: var(--octo-navy-200);
 
-  --muted: #16344a;
-  --muted-foreground: var(--octo-navy-300);
+  --muted: #102636;
+  --muted-foreground: #8aa4bd;
 
-  --border: #314c62;
-  --input: #314c62;
+  --border: #1e394e;
+  --input: #284459;
   --ring: var(--octo-blue-bright);
 
-  /* Callout text colors must lighten for legibility on the dark surfaces;
-     light-mode values stay dark and would be invisible here. */
+  /* Callout text colors must lighten for legibility on the dark surfaces. */
   --info: #cfe6fb;
-  --info-bg: rgba(13, 128, 216, 0.1);
-  --info-border: var(--octo-blue);
+  --info-bg: rgba(31, 192, 255, 0.08);
+  --info-border: var(--octo-blue-bright);
   --success: #6fe6b4;
-  --success-bg: rgba(0, 176, 101, 0.12);
+  --success-bg: rgba(0, 230, 147, 0.09);
+  --success-border: var(--octo-green);
   --warning: #ffb27a;
-  --warning-bg: rgba(252, 132, 49, 0.12);
+  --warning-bg: rgba(252, 132, 49, 0.1);
+  --warning-border: #fc8431;
   --problem: #ff9b9b;
-  --problem-bg: rgba(255, 72, 72, 0.12);
+  --problem-bg: rgba(255, 72, 72, 0.1);
+  --problem-border: #ff4848;
   --question: var(--octo-navy-200);
-  --question-bg: rgba(124, 152, 180, 0.12);
+  --question-bg: rgba(124, 152, 180, 0.1);
   --question-border: var(--octo-navy-400);
 
-  --sidebar: #0c1a24;
-  --sidebar-foreground: var(--octo-navy-200);
+  --sidebar: #091a27;
+  --sidebar-foreground: #a9c0d4;
+
+  --surface: #0c1f2d;
+  --surface-2: #112a3b;
+  --code-bg: #06121c;
+  --code-foreground: #e6f0f7;
+  --code-chrome: #0c2031;
+  --code-border: #16344a;
+
+  --glow-primary: color-mix(in oklab, var(--octo-blue-bright) 50%, transparent);
+  --glow-accent: color-mix(in oklab, var(--octo-green-bright) 50%, transparent);
+  --glow-brand: color-mix(in oklab, var(--pink-100) 55%, transparent);
+  --gradient-brand: linear-gradient(
+    100deg,
+    var(--octo-blue-bright) 0%,
+    var(--purple-400) 50%,
+    var(--pink-100) 115%
+  );
+  /* Hero H1 text: bright cyan -> light purple -> pink, readable on the abyss. */
+  --gradient-ink: linear-gradient(
+    100deg,
+    #9fe7ff 0%,
+    #b69cff 52%,
+    #ec8cff 120%
+  );
+
+  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 16%, transparent);
+  --aurora-2: color-mix(in oklab, var(--pink-100) 12%, transparent);
+  --aurora-3: color-mix(in oklab, var(--purple-300) 18%, transparent);
+  --grid-line: color-mix(in oklab, var(--octo-blue-bright) 6%, transparent);
+  --grain-opacity: 0.05;
+
+  /* Glass effect: the exact marketing-site values (tuned for dark backgrounds). */
+  --glass-background: linear-gradient(
+    263.36deg,
+    var(--glass-white-31) -46.77%,
+    var(--glass-cyan) 86.43%
+  );
+  --glass-border-color: var(--glass-white-20);
+  --glass-shadow: 0 0 30px var(--glass-white-15);
+  --glass-blur-glow: radial-gradient(
+    101.55% 101.55% at 50% -1.55%,
+    var(--glass-white-35) 0%,
+    var(--glass-cyan-glow) 18.63%,
+    var(--glass-pink-glow) 73.48%,
+    var(--glass-navy-fade) 100%
+  );
 
-  --surface: #0f2230;
-  --surface-2: #16344a;
-  --code-bg: #0a161f;
-  --code-foreground: #e6edf3;
-  --code-chrome: #0f2230;
-  --code-border: #233a4f;
+  /* Secondary button (dark): purple-tinted fill instead of transparent. */
+  --secondary-button-text: var(--white);
+  --secondary-button-bg: rgba(105, 80, 255, 0.3);
+  --secondary-button-hover-text: var(--white);
+  --secondary-button-hover-bg: rgba(105, 80, 255, 0.3);
+  --secondary-button-hover-glow: rgba(204, 60, 255, 0.5);
+  --secondary-button-hover-border: var(--pink-100);
 
-  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.4);
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.45);
   --shadow-md:
-    0 4px 12px -2px rgba(0, 0, 0, 0.5), 0 2px 6px -2px rgba(0, 0, 0, 0.4);
+    0 4px 14px -3px rgba(0, 0, 0, 0.55), 0 2px 6px -2px rgba(0, 0, 0, 0.45);
   --shadow-lg:
-    0 12px 32px -8px rgba(0, 0, 0, 0.6), 0 4px 10px -4px rgba(0, 0, 0, 0.4);
+    0 18px 44px -12px rgba(0, 0, 0, 0.65), 0 6px 16px -6px rgba(0, 0, 0, 0.5);
+  --shadow-glow: 0 10px 44px -8px var(--glow-primary);
 }
diff --git a/src/design-system/ui/Button.astro b/src/design-system/ui/Button.astro
index 0dd1cb5365..c7df190bf8 100644
--- a/src/design-system/ui/Button.astro
+++ b/src/design-system/ui/Button.astro
@@ -1,39 +1,47 @@
 ---
-type Variant = 'primary' | 'accent' | 'outline' | 'ghost';
-type Size = 'sm' | 'md' | 'lg';
+type Variant = 'primary' | 'secondary' | 'ghost';
 
 interface Props {
   href?: string;
   variant?: Variant;
-  size?: Size;
   class?: string;
 }
 
-const { href, variant = 'primary', size = 'md', class: extra = '' } = Astro.props;
-
-const base =
-  'inline-flex items-center justify-center gap-2 rounded-md font-medium whitespace-nowrap transition-all duration-150 ease-out active:translate-y-px focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50';
-
-const variants: Record<Variant, string> = {
-  primary:
-    'bg-primary text-primary-foreground shadow-[var(--shadow-sm)] hover:bg-primary/90 hover:shadow-[var(--shadow-md)]',
-  accent:
-    'bg-accent text-accent-foreground shadow-[var(--shadow-sm)] hover:bg-accent/90 hover:shadow-[var(--shadow-md)]',
-  outline:
-    'border border-border bg-background text-foreground hover:bg-muted hover:border-primary/40',
-  ghost: 'text-foreground hover:bg-muted',
-};
-
-const sizes: Record<Size, string> = {
-  sm: 'h-8 px-3 text-sm',
-  md: 'h-10 px-4 text-sm',
-  lg: 'h-11 px-6 text-[0.95rem]',
-};
-
-const cls = [base, variants[variant], sizes[size], extra].join(' ');
+const { href, variant = 'primary', class: extra = '' } = Astro.props;
+const cls = ['ds-btn', `ds-btn--${variant}`, extra].join(' ');
 const Tag = href ? 'a' : 'button';
 ---
 
-<Tag class={cls} href={href} data-component="Button">
-  <slot />
-</Tag>
+<Tag class={cls} href={href} data-component="Button"><slot /></Tag>
+
+<script is:inline>
+  // Cursor-tracked glow: set --hover-x/--hover-y per pointer position.
+  (() => {
+    if (window.__dsBtnInit) return;
+    window.__dsBtnInit = true;
+    const SELECTOR = '.ds-btn--primary, .ds-btn--secondary';
+    const seen = new WeakSet();
+    const track = (btn) => {
+      if (seen.has(btn)) return;
+      seen.add(btn);
+      let rect = null;
+      btn.addEventListener('mouseenter', () => {
+        rect = btn.getBoundingClientRect();
+      });
+      btn.addEventListener('mousemove', (e) => {
+        if (!rect) rect = btn.getBoundingClientRect();
+        btn.style.setProperty('--hover-x', e.clientX - rect.left + 'px');
+        btn.style.setProperty('--hover-y', e.clientY - rect.top + 'px');
+      });
+    };
+    document.querySelectorAll(SELECTOR).forEach(track);
+    new MutationObserver((muts) => {
+      for (const m of muts)
+        for (const n of m.addedNodes) {
+          if (n.nodeType !== 1) continue;
+          if (n.matches?.(SELECTOR)) track(n);
+          n.querySelectorAll?.(SELECTOR).forEach(track);
+        }
+    }).observe(document.body, { childList: true, subtree: true });
+  })();
+</script>
diff --git a/src/design-system/ui/Callout.astro b/src/design-system/ui/Callout.astro
index 0cbffe7b59..7f5abf638f 100644
--- a/src/design-system/ui/Callout.astro
+++ b/src/design-system/ui/Callout.astro
@@ -40,22 +40,26 @@ const icons: Record<Intent, string> = {
 
 <div
   data-component="Callout"
-  class={`my-6 flex gap-3 rounded-lg border border-l-[3px] px-4 py-3.5 text-[0.95rem] ${styles[intent]}`}
-  style="border-color: color-mix(in oklab, var(--bd) 35%, transparent); border-left-color: var(--bd); background: var(--bg); color: var(--c);"
+  class={`my-7 flex gap-3.5 rounded-xl border border-l-[3px] px-4 py-4 text-[0.95rem] shadow-[var(--shadow-sm)] ${styles[intent]}`}
+  style="border-color: color-mix(in oklab, var(--bd) 32%, transparent); border-left-color: var(--bd); background: var(--bg); color: var(--c);"
   role="note"
 >
-  <svg
-    class="mt-0.5 h-[18px] w-[18px] shrink-0"
-    style="color: var(--bd);"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    stroke-width="2"
-    stroke-linecap="round"
-    stroke-linejoin="round"
-    aria-hidden="true"
-    set:html={icons[intent]}
-  />
+  <span
+    class="mt-0.5 grid h-7 w-7 shrink-0 place-items-center rounded-lg"
+    style="color: var(--bd); background: color-mix(in oklab, var(--bd) 15%, transparent); box-shadow: 0 0 16px -3px color-mix(in oklab, var(--bd) 55%, transparent);"
+  >
+    <svg
+      class="h-[17px] w-[17px]"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      set:html={icons[intent]}
+    />
+  </span>
   <div class="min-w-0">
     <p class="mb-1 font-semibold leading-snug">{title ?? labels[intent]}</p>
     <div
diff --git a/src/design-system/ui/Card.astro b/src/design-system/ui/Card.astro
index d2364be71e..44d481a699 100644
--- a/src/design-system/ui/Card.astro
+++ b/src/design-system/ui/Card.astro
@@ -7,10 +7,10 @@ interface Props {
 
 const { href, title, class: extra = '' } = Astro.props;
 const interactive = href
-  ? 'group hover:-translate-y-0.5 hover:border-primary/45 hover:shadow-[var(--shadow-md)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background'
+  ? 'group hover:-translate-y-1 hover:border-primary/45 hover:[box-shadow:var(--shadow-glow)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background before:absolute before:inset-x-5 before:top-0 before:h-px before:bg-gradient-to-r before:from-transparent before:via-primary/50 before:to-transparent before:opacity-0 before:transition-opacity before:duration-300 hover:before:opacity-100'
   : '';
 const cls = [
-  'relative flex h-full flex-col rounded-xl border border-border bg-card text-card-foreground p-5 transition-all duration-200 ease-out',
+  'relative flex h-full flex-col overflow-hidden rounded-xl border border-border bg-card/70 text-card-foreground p-5 backdrop-blur-sm transition-[transform,box-shadow,border-color] duration-300 ease-out',
   interactive,
   extra,
 ].join(' ');
@@ -22,7 +22,7 @@ const cleanTitle = title?.replace(/\s*→\s*$/, '');
 <Tag class={cls} href={href} data-component="Card">
   {
     cleanTitle && (
-      <h3 class="mb-1.5 flex items-center gap-1.5 font-semibold tracking-tight">
+      <h3 class="mb-1.5 flex items-center gap-1.5 font-display text-[1.05rem] font-bold tracking-tight">
         <span>{cleanTitle}</span>
         {href && (
           <svg
diff --git a/src/pages/docs/ui-mvp.astro b/src/pages/docs/ui-mvp.astro
index 9c4183cd9c..5599890634 100644
--- a/src/pages/docs/ui-mvp.astro
+++ b/src/pages/docs/ui-mvp.astro
@@ -109,6 +109,19 @@ const toc = [
     <li>Select <strong>Save</strong>.</li>
   </ol>
 
+  <figure class="image" data-image>
+    <img
+      class="image__img"
+      src="/docs/img/getting-started.png"
+      alt="The Create release screen in the Octopus dashboard"
+      loading="lazy"
+    />
+    <figcaption class="image__caption">
+      The release editor, showing the package versions selected for this
+      release.
+    </figcaption>
+  </figure>
+
   <h3 id="promote">Promote to an environment</h3>
   <p>
     Releases move through your lifecycle phases. The dashboard shows which
@@ -195,6 +208,6 @@ const toc = [
 
   <div class="not-prose mt-8 flex flex-wrap gap-3">
     <Button href="#" variant="primary">Read the deployment guide</Button>
-    <Button href="#" variant="outline">Browse the CLI reference</Button>
+    <Button href="#" variant="secondary">Browse the CLI reference</Button>
   </div>
 </DocsLayout>

From 01f1e3c2c1f21d891d73e845d6a7a2a97c41b1e1 Mon Sep 17 00:00:00 2001
From: Kamil Majkrzak <kamil.majkrzak@octopus.com>
Date: Wed, 27 May 2026 16:13:49 +0200
Subject: [PATCH 3/5] MVP docs design-system with search and swapped layout

---
 src/design-system/README.md                   |  26 +-
 .../docs-shell/DocsContentLayout.astro        |  58 +-
 src/design-system/docs-shell/DocsHeader.astro | 276 +-----
 src/design-system/docs-shell/DocsLayout.astro |  22 +-
 .../docs-shell/DocsSidebar.astro              |  89 +-
 .../docs-shell/DocsSidebarNav.astro           |  69 +-
 src/design-system/docs-shell/DocsToc.astro    |  38 +-
 .../docs-shell/SidebarBehavior.astro          |  86 ++
 src/design-system/theme.css                   | 833 ++++++++++++++++--
 src/design-system/tokens.css                  |  52 +-
 src/design-system/ui/Button.astro             |  41 +-
 src/layouts/Default.astro                     | 163 +---
 src/layouts/DefaultLegacy.astro               | 149 ++++
 src/pages/docs.mdx                            |   2 +-
 src/pages/ui-update-sample.mdx                |   2 +-
 15 files changed, 1289 insertions(+), 617 deletions(-)
 create mode 100644 src/design-system/docs-shell/SidebarBehavior.astro
 create mode 100644 src/layouts/DefaultLegacy.astro

diff --git a/src/design-system/README.md b/src/design-system/README.md
index 21f8d885b8..30f704a74b 100644
--- a/src/design-system/README.md
+++ b/src/design-system/README.md
@@ -6,8 +6,9 @@ each maintaining its own CSS. Everything here is plain Astro + CSS custom proper
 Tailwind v4 utilities - **no React/Vue/Svelte, no client framework runtime** - which keeps
 SEO and Core Web Vitals intact on statically generated pages.
 
-> Status: MVP. Proven in this repo on `/docs/ui-mvp`, which is the first consumer of this
-> module. Adopt it elsewhere by copying this one folder and wiring two things.
+> Status: MVP / preview — not yet production-complete. Proven in this repo on `/docs/ui-mvp`,
+> the first consumer of this module. Adopt it elsewhere by copying this one folder and wiring
+> two things.
 
 ---
 
@@ -187,13 +188,11 @@ These hold by construction; preserve them when extending the system.
   `itemprop` headline/description/articleBody; heading hierarchy is semantic. Keep these when
   editing the shell.
 - **Core Web Vitals.** No blocking JS, no layout-shifting hydration. A FOUC-prevention inline
-  script in `DocsLayout`'s `<head>` applies the stored theme before paint. The "Abyssal"
-  revamp **does** load three web fonts (Bricolage Grotesque / Hanken Grotesk / JetBrains Mono
-  via Bunny Fonts, a privacy-friendly Google Fonts mirror) - a deliberate trade for distinctive
-  type. They are `preconnect`ed and `display=swap`, and every `--font-*` token keeps a system
-  stack fallback, so first paint uses system fonts and there is no invisible-text delay. If a
-  site must stay font-free, point the `--font-*` tokens back at system stacks and drop the
-  `<link>`s from the layout heads - nothing else changes.
+  script in `DocsLayout`'s `<head>` applies the stored theme before paint. Three web fonts
+  (Bricolage Grotesque / Hanken Grotesk / JetBrains Mono via Bunny Fonts, a privacy-friendly
+  Google Fonts mirror) are `preconnect`ed and `display=swap`, and every `--font-*` token keeps
+  a system-stack fallback, so first paint uses system fonts with no invisible-text delay. To go
+  font-free, point the `--font-*` tokens at system stacks and drop the `<link>`s from the heads.
 - **In-content images get the "glass" effect.** Images authored inside documentation content
   (`.prose figure` / `.image` / `[data-image]` from `<Image>` and the `:::figure` / `:img`
   directives, plus standalone `img.resp-img`) are wrapped in a frosted panel with a blurred
@@ -217,7 +216,7 @@ These hold by construction; preserve them when extending the system.
 |---|---|---|
 | FOUC theme apply | `docs-shell/DocsLayout.astro` (head) | Set `data-theme` from `localStorage` before paint |
 | Theme toggle | `docs-shell/DocsHeader.astro` | Toggle + persist light/dark |
-| Search dropdown | `docs-shell/DocsHeader.astro` | Filtered, keyboard-navigable results list (currently sample data - see gaps) |
+| Search | `docs-shell/DocsHeader.astro` renders the real `themes/octopus/components/Search.astro` | The real `search.js` engine (index + scoring + synonyms), re-skinned via `.ds-search` CSS. Not a design-system script. |
 | TOC scroll-spy | `docs-shell/DocsToc.astro` | IntersectionObserver active-section highlight |
 | Copy button | `ui/CodeBlock.astro` | Delegated copy-to-clipboard with "Copied" state |
 | Button glow | `ui/Button.astro` | Tracks the pointer to set `--hover-x/--hover-y` for the cursor-following glow |
@@ -226,9 +225,10 @@ These hold by construction; preserve them when extending the system.
 
 ## 5. Known MVP gaps (intentionally out of scope)
 
-- **Search is demo data.** The dropdown filters ~14 hard-coded sample entries. Wiring the
-  real search index (the existing `search.json` / `Search.astro` backend) is a data swap, not
-  a structural change.
+- **Search uses the real engine.** The header renders the existing `Search.astro` +
+  `search.js` (full `search.json` index, scoring, synonyms), re-skinned to the new UI via
+  `.ds-search` CSS. The engine files are unmodified; the layout sets `window.site_url` /
+  `window.site_features` (which `search.js` depends on).
 - **Code blocks: no syntax highlighting.** `CodeBlock` gives the surface + filename bar +
   copy button, but not token highlighting. Add a build-time highlighter (Shiki via
   rehype/remark) if needed. Bare fenced code in MDX gets the styled surface but not the
diff --git a/src/design-system/docs-shell/DocsContentLayout.astro b/src/design-system/docs-shell/DocsContentLayout.astro
index 1ed8a9cb2a..dfa5d7a5d2 100644
--- a/src/design-system/docs-shell/DocsContentLayout.astro
+++ b/src/design-system/docs-shell/DocsContentLayout.astro
@@ -3,6 +3,11 @@
 // content page adopt the new design system by switching its `layout:`
 // frontmatter line. Reuses the site's existing data sources (nav tree,
 // breadcrumbs, SEO head via HtmlHead) and renders them through our chrome.
+//
+// ⚠️ MVP / PREVIEW — NOT production-complete. Versus DefaultLegacy.astro this
+// omits essential plumbing (main.js, Plausible, Marketo, SkipLinks, real search,
+// theme reconciliation, article-footer features) — complete these before any
+// real rollout.
 import '../theme.css';
 import { Accelerator } from 'astro-accelerator-utils';
 import { SITE } from '@config';
@@ -13,6 +18,7 @@ import DocsHeader from './DocsHeader.astro';
 import DocsToc from './DocsToc.astro';
 import DocsBreadcrumbs from './DocsBreadcrumbs.astro';
 import DocsSidebarNav from './DocsSidebarNav.astro';
+import SidebarBehavior from './SidebarBehavior.astro';
 import Footer from '../../components/Footer.astro';
 
 type Props = {
@@ -92,23 +98,49 @@ const sortedTopLevel = pages
       if (localStorage.getItem('mvp-theme') === 'dark')
         document.documentElement.setAttribute('data-theme', 'dark');
     </script>
+    <script
+      is:inline
+      define:vars={{ site_url: SITE.url, site_features: SITE.featureFlags }}
+    >
+      window.site_url = site_url;
+      window.site_features = site_features;
+    </script>
     <div class="ds-atmosphere"></div>
     <div class="ds-grain"></div>
-    <DocsHeader />
+    <DocsHeader lang={lang} />
 
     <div class="mx-auto flex max-w-[1600px]">
       <aside
         data-component="DocsSidebar"
-        class="hidden w-[16.5rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
-        aria-label="Documentation navigation"
+        class="hidden w-[18.75rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
       >
-        <nav
-          class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3.5 py-8 [scrollbar-gutter:stable]"
+        <div
+          class="ds-navscroll"
+          data-navscroll
+          data-at-top="true"
+          data-at-bottom="true"
         >
-          <ul>
-            {sortedTopLevel.map((page: any) => <DocsSidebarNav page={page} />)}
-          </ul>
-        </nav>
+          <nav
+            class="ds-navscroll__viewport px-3.5 py-8"
+            data-navscroll-viewport
+            aria-label="Documentation navigation"
+          >
+            <ul>
+              {
+                sortedTopLevel.map((page: any) => (
+                  <DocsSidebarNav page={page} />
+                ))
+              }
+            </ul>
+          </nav>
+          <span
+            class="ds-navscroll__fade ds-navscroll__fade--top"
+            aria-hidden="true"></span>
+          <span
+            class="ds-navscroll__fade ds-navscroll__fade--bottom"
+            aria-hidden="true"></span>
+        </div>
+        <SidebarBehavior />
       </aside>
 
       <div class="flex min-w-0 flex-1">
@@ -116,7 +148,7 @@ const sortedTopLevel = pages
           class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-14"
           data-component="DocsContentLayout"
         >
-          <div class="mx-auto max-w-3xl xl:mx-0">
+          <div class="mx-auto max-w-3xl">
             <details
               class="group mb-5 rounded-lg border border-border bg-sidebar lg:hidden"
             >
@@ -171,7 +203,7 @@ const sortedTopLevel = pages
                 <p
                   data-rise
                   style="--rise:90ms"
-                  class="mb-3 flex items-center gap-2 font-mono text-[0.72rem] font-medium uppercase tracking-[0.18em] text-primary"
+                  class="mb-3 flex items-center gap-2 font-mono text-xs font-medium uppercase tracking-[0.18em] text-primary"
                 >
                   <span
                     class="inline-block h-1.5 w-1.5 rounded-full shadow-[0_0_10px_2px_var(--glow-brand)]"
@@ -181,7 +213,7 @@ const sortedTopLevel = pages
                 <h1
                   data-rise
                   style="--rise:150ms"
-                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.9rem]"
+                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.75rem]"
                   itemprop="headline"
                 >
                   {frontmatter.title}
@@ -191,7 +223,7 @@ const sortedTopLevel = pages
                     <p
                       data-rise
                       style="--rise:230ms"
-                      class="mt-4 max-w-2xl text-[1.12rem] leading-relaxed text-muted-foreground"
+                      class="mt-4 max-w-2xl text-lg leading-relaxed text-muted-foreground"
                       itemprop="description"
                     >
                       {frontmatter.description}
diff --git a/src/design-system/docs-shell/DocsHeader.astro b/src/design-system/docs-shell/DocsHeader.astro
index 3e98a47f36..7ae8865ea7 100644
--- a/src/design-system/docs-shell/DocsHeader.astro
+++ b/src/design-system/docs-shell/DocsHeader.astro
@@ -1,8 +1,17 @@
 ---
 // Top navigation bar. The only JS is a tiny theme toggle (vanilla, no framework
 // runtime) to demonstrate dark mode - consistent with the zero-JS approach.
+// Search renders the REAL site search component + engine (search.js), restyled
+// via tokens in theme.css. The engine is unchanged; we only provide its markup.
 import OctopusLogo from '../../../public/docs/img/OctopusLogo.astro';
 import Button from '../ui/Button.astro';
+import Search from '../../themes/octopus/components/Search.astro';
+import { SITE } from '@config';
+
+type Props = {
+  lang?: string;
+};
+const { lang = SITE.default.lang } = Astro.props satisfies Props;
 ---
 
 <header
@@ -20,75 +29,21 @@ import Button from '../ui/Button.astro';
     >
       <OctopusLogo />
       <span
-        class="hidden border-l border-border pl-2.5 text-[0.82rem] font-medium text-muted-foreground sm:inline-block"
+        class="hidden border-l border-border pl-2.5 text-sm font-medium text-muted-foreground sm:inline-block"
         >Docs</span
       >
     </a>
 
-    <!-- Search: type-ahead dropdown of matching docs (demo data, no backend). -->
-    <div class="mvp-search relative ml-2 hidden flex-1 max-w-md md:flex">
-      <label class="group relative w-full">
-        <span class="sr-only">Search documentation</span>
-        <svg
-          class="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground transition-colors group-focus-within:text-primary"
-          width="16"
-          height="16"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-        >
-          <circle cx="11" cy="11" r="8"></circle>
-          <path d="m21 21-4.3-4.3"></path>
-        </svg>
-        <input
-          id="mvp-search-input"
-          data-mvp-search-query
-          type="search"
-          role="combobox"
-          autocomplete="off"
-          aria-expanded="false"
-          aria-controls="mvp-search-results"
-          aria-autocomplete="list"
-          placeholder="Search documentation…"
-          class="h-9 w-full rounded-lg border border-input bg-muted/50 pl-9 pr-14 text-sm text-foreground transition-[background-color,border-color,box-shadow] placeholder:text-muted-foreground hover:border-border hover:bg-muted/70 focus:border-primary/50 focus:bg-background focus:outline-none focus:ring-2 focus:ring-ring/60"
-        />
-        <kbd
-          class="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 rounded-md border border-border bg-background/80 px-1.5 py-0.5 font-mono text-[10px] font-medium text-muted-foreground shadow-[var(--shadow-sm)]"
-          >⌘K</kbd
-        >
-      </label>
-
-      <!-- Results dropdown (populated by the inline script). -->
-      <div
-        id="mvp-search-panel"
-        data-mvp-search-panel
-        hidden
-        class="absolute left-0 right-0 top-[calc(100%+0.4rem)] z-50 overflow-hidden rounded-xl border border-border bg-popover shadow-[var(--shadow-lg)]"
-      >
-        <ul
-          id="mvp-search-results"
-          data-mvp-search-results
-          role="listbox"
-          aria-label="Search results"
-          class="max-h-80 overflow-y-auto py-1 [scrollbar-width:thin]"
-        >
-        </ul>
-        <p
-          data-mvp-search-empty
-          hidden
-          class="px-3.5 py-6 text-center text-sm text-muted-foreground"
-        >
-        </p>
-      </div>
+    <!-- Search: the REAL site search component (markup + search.js engine),
+         restyled in theme.css under `.ds-search`. Engine code is unchanged. -->
+    <div class="ds-search relative ml-2 hidden flex-1 max-w-md md:flex">
+      <Search lang={lang} />
     </div>
 
     <nav class="ml-auto flex items-center gap-1">
       <a
         href="https://octopus.com"
-        class="hidden h-9 items-center rounded-md px-3 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:inline-flex"
+        class="hidden h-9 items-center rounded-md px-3 text-base text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:inline-flex"
         >octopus.com</a
       >
       <span class="mx-1 hidden h-5 w-px bg-border sm:block" aria-hidden="true"
@@ -129,7 +84,7 @@ import Button from '../ui/Button.astro';
       <Button
         href="https://octopus.com/start"
         variant="primary"
-        class="ml-1.5 hidden h-9 gap-1.5 px-4 py-0 text-[0.8rem] sm:inline-flex"
+        class="ml-1.5 hidden h-9 gap-1.5 px-4 py-0 sm:inline-flex"
       >
         Start free trial
         <svg
@@ -186,194 +141,21 @@ import Button from '../ui/Button.astro';
 </script>
 
 <script is:inline>
+  // Scroll shades on the search results dropdown (mirrors the sidebar).
   (() => {
-    const input = document.querySelector('[data-mvp-search-query]');
-    const panel = document.querySelector('[data-mvp-search-panel]');
-    const list = document.querySelector('[data-mvp-search-results]');
-    const empty = document.querySelector('[data-mvp-search-empty]');
-    if (!input || !panel || !list || !empty) return;
-
-    const docs = [
-      {
-        title: 'Deploying a release',
-        section: 'Getting started › Deployments',
-        href: '#',
-      },
-      { title: 'Your first project', section: 'Getting started', href: '#' },
-      { title: 'Installation', section: 'Getting started', href: '#' },
-      { title: 'Environments', section: 'Getting started', href: '#' },
-      { title: 'Deployment process', section: 'Deployments', href: '#' },
-      { title: 'Variables', section: 'Deployments › Configuration', href: '#' },
-      { title: 'Releases & channels', section: 'Deployments', href: '#' },
-      { title: 'Runbooks', section: 'Deployments › Operations', href: '#' },
-      { title: 'Deployment targets', section: 'Infrastructure', href: '#' },
-      { title: 'Workers', section: 'Infrastructure', href: '#' },
-      { title: 'Accounts', section: 'Infrastructure › Security', href: '#' },
-      { title: 'Tenants & multi-tenancy', section: 'Tenants', href: '#' },
-      { title: 'Octopus CLI reference', section: 'Automation', href: '#' },
-      {
-        title: 'Lifecycles & phases',
-        section: 'Deployments › Lifecycles',
-        href: '#',
-      },
-    ];
-
-    let results = [];
-    let active = -1;
-
-    const docIcon = () => {
-      const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
-      svg.setAttribute('viewBox', '0 0 24 24');
-      svg.setAttribute('fill', 'none');
-      svg.setAttribute('stroke', 'currentColor');
-      svg.setAttribute('stroke-width', '2');
-      svg.setAttribute('stroke-linecap', 'round');
-      svg.setAttribute('stroke-linejoin', 'round');
-      svg.setAttribute('aria-hidden', 'true');
-      svg.setAttribute(
-        'class',
-        'mt-0.5 h-4 w-4 shrink-0 text-muted-foreground'
-      );
-      const p1 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-      p1.setAttribute(
-        'd',
-        'M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z'
-      );
-      const p2 = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-      p2.setAttribute('d', 'M14 2v6h6');
-      svg.append(p1, p2);
-      return svg;
-    };
-
-    const titleNode = (title, q) => {
-      const span = document.createElement('span');
-      span.className = 'block truncate text-foreground';
-      const i = q ? title.toLowerCase().indexOf(q.toLowerCase()) : -1;
-      if (i < 0) {
-        span.textContent = title;
-        return span;
-      }
-      span.append(document.createTextNode(title.slice(0, i)));
-      const mark = document.createElement('mark');
-      mark.className = 'bg-transparent font-semibold text-primary';
-      mark.textContent = title.slice(i, i + q.length);
-      span.append(mark, document.createTextNode(title.slice(i + q.length)));
-      return span;
-    };
-
-    const close = () => {
-      panel.hidden = true;
-      input.setAttribute('aria-expanded', 'false');
-      input.removeAttribute('aria-activedescendant');
-      active = -1;
-    };
-
-    const setActive = (idx) => {
-      const items = list.querySelectorAll('[role="option"]');
-      items.forEach((el, i) => {
-        const on = i === idx;
-        el.setAttribute('aria-selected', on ? 'true' : 'false');
-        el.classList.toggle('bg-muted', on);
-        if (on) el.scrollIntoView({ block: 'nearest' });
-      });
-      active = idx;
-      if (idx >= 0 && items[idx])
-        input.setAttribute('aria-activedescendant', items[idx].id);
-      else input.removeAttribute('aria-activedescendant');
-    };
-
-    const render = (q) => {
-      const query = q.trim();
-      if (!query) {
-        close();
-        return;
-      }
-      results = docs.filter(
-        (d) =>
-          d.title.toLowerCase().includes(query.toLowerCase()) ||
-          d.section.toLowerCase().includes(query.toLowerCase())
+    const res = document.querySelector('.ds-search [data-site-search-results]');
+    if (!res) return;
+    const update = () => {
+      res.setAttribute('data-at-top', res.scrollTop <= 1 ? 'true' : 'false');
+      res.setAttribute(
+        'data-at-bottom',
+        res.scrollTop + res.clientHeight >= res.scrollHeight - 1
+          ? 'true'
+          : 'false'
       );
-      panel.hidden = false;
-      input.setAttribute('aria-expanded', 'true');
-      list.replaceChildren();
-
-      if (!results.length) {
-        empty.hidden = false;
-        empty.textContent = 'No results for “' + query + '”';
-        setActive(-1);
-        return;
-      }
-      empty.hidden = true;
-      results.forEach((d, i) => {
-        const li = document.createElement('li');
-        li.id = 'mvp-search-opt-' + i;
-        li.setAttribute('role', 'option');
-        li.setAttribute('aria-selected', 'false');
-        li.className =
-          'mx-1 flex cursor-pointer items-start gap-2.5 rounded-lg px-3 py-2 text-sm hover:bg-muted';
-        const text = document.createElement('span');
-        text.className = 'min-w-0';
-        const sec = document.createElement('span');
-        sec.className =
-          'mt-0.5 block truncate text-[0.75rem] text-muted-foreground';
-        sec.textContent = d.section;
-        text.append(titleNode(d.title, query), sec);
-        li.append(docIcon(), text);
-        list.append(li);
-      });
-      setActive(0);
-    };
-
-    const go = (idx) => {
-      const d = results[idx];
-      if (d)
-        window.location.hash = d.href.startsWith('#') ? d.href.slice(1) : '';
-      close();
     };
-
-    input.addEventListener('input', () => render(input.value));
-    input.addEventListener('focus', () => {
-      if (input.value.trim()) render(input.value);
-    });
-
-    input.addEventListener('keydown', (e) => {
-      if (panel.hidden) return;
-      if (e.key === 'ArrowDown') {
-        e.preventDefault();
-        if (results.length) setActive((active + 1) % results.length);
-      } else if (e.key === 'ArrowUp') {
-        e.preventDefault();
-        if (results.length)
-          setActive((active - 1 + results.length) % results.length);
-      } else if (e.key === 'Enter') {
-        if (active >= 0) {
-          e.preventDefault();
-          go(active);
-        }
-      } else if (e.key === 'Escape') {
-        close();
-        input.blur();
-      }
-    });
-
-    list.addEventListener('mousedown', (e) => {
-      const opt = e.target.closest('[role="option"]');
-      if (!opt) return;
-      e.preventDefault();
-      const items = Array.from(list.querySelectorAll('[role="option"]'));
-      go(items.indexOf(opt));
-    });
-
-    document.addEventListener('click', (e) => {
-      if (!e.target.closest('.mvp-search')) close();
-    });
-
-    document.addEventListener('keydown', (e) => {
-      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
-        e.preventDefault();
-        input.focus();
-        input.select();
-      }
-    });
+    res.addEventListener('scroll', update, { passive: true });
+    new MutationObserver(update).observe(res, { childList: true });
+    update();
   })();
 </script>
diff --git a/src/design-system/docs-shell/DocsLayout.astro b/src/design-system/docs-shell/DocsLayout.astro
index d22adb0cfa..53b19d8097 100644
--- a/src/design-system/docs-shell/DocsLayout.astro
+++ b/src/design-system/docs-shell/DocsLayout.astro
@@ -1,5 +1,6 @@
 ---
 import '../theme.css';
+import { SITE } from '@config';
 import DocsHeader from './DocsHeader.astro';
 import DocsSidebar from './DocsSidebar.astro';
 import DocsToc from './DocsToc.astro';
@@ -30,7 +31,7 @@ const kicker =
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{title} · Octopus Docs</title>
     {description && <meta name="description" content={description} />}
-    <!-- Web fonts via Bunny (GF mirror); preconnect + swap. -->
+    <!-- Web fonts via Bunny (privacy-friendly GF mirror); preconnect + swap. -->
     <link rel="preconnect" href="https://fonts.bunny.net" crossorigin />
     <link
       rel="stylesheet"
@@ -47,6 +48,13 @@ const kicker =
   <body
     class="relative min-h-screen bg-background font-sans text-foreground antialiased"
   >
+    <script
+      is:inline
+      define:vars={{ site_url: SITE.url, site_features: SITE.featureFlags }}
+    >
+      window.site_url = site_url;
+      window.site_features = site_features;
+    </script>
     <div class="ds-atmosphere"></div>
     <div class="ds-grain"></div>
 
@@ -57,7 +65,7 @@ const kicker =
 
       <div class="flex min-w-0 flex-1">
         <main class="min-w-0 flex-1 px-5 py-6 sm:px-6 lg:px-12 lg:py-16">
-          <div class="mx-auto max-w-3xl xl:mx-0">
+          <div class="mx-auto max-w-3xl">
             <details
               class="group mb-5 rounded-lg border border-border bg-sidebar/70 backdrop-blur lg:hidden"
             >
@@ -96,7 +104,7 @@ const kicker =
                 {
                   sidebar.map((section) => (
                     <div class="mb-4 last:mb-0">
-                      <p class="mb-2 px-3 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60">
+                      <p class="mb-2 px-3 text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground/60">
                         {section.title}
                       </p>
                       <ul class="space-y-0.5">
@@ -105,7 +113,7 @@ const kicker =
                             <a
                               href={item.href}
                               aria-current={item.active ? 'page' : undefined}
-                              class={`block rounded-lg px-3 py-[0.47rem] text-[0.9rem] transition-colors ${
+                              class={`block rounded-lg px-3 py-[0.47rem] text-base transition-colors ${
                                 item.active
                                   ? 'bg-primary/[0.08] font-semibold text-primary'
                                   : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
@@ -131,7 +139,7 @@ const kicker =
                 <p
                   data-rise
                   style="--rise:90ms"
-                  class="mb-3 flex items-center gap-2 font-mono text-[0.72rem] font-medium uppercase tracking-[0.18em] text-primary"
+                  class="mb-3 flex items-center gap-2 font-mono text-xs font-medium uppercase tracking-[0.18em] text-primary"
                 >
                   <span
                     class="inline-block h-1.5 w-1.5 rounded-full shadow-[0_0_10px_2px_var(--glow-brand)]"
@@ -141,7 +149,7 @@ const kicker =
                 <h1
                   data-rise
                   style="--rise:150ms"
-                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.9rem]"
+                  class="ds-gradient-text font-display text-[2.5rem] font-extrabold leading-[1.08] tracking-[-0.03em] sm:text-[2.75rem]"
                   itemprop="headline"
                 >
                   {title}
@@ -151,7 +159,7 @@ const kicker =
                     <p
                       data-rise
                       style="--rise:230ms"
-                      class="mt-4 max-w-2xl text-[1.12rem] leading-relaxed text-muted-foreground"
+                      class="mt-4 max-w-2xl text-lg leading-relaxed text-muted-foreground"
                       itemprop="description"
                     >
                       {description}
diff --git a/src/design-system/docs-shell/DocsSidebar.astro b/src/design-system/docs-shell/DocsSidebar.astro
index 7a5189b5e8..31f2afaf9c 100644
--- a/src/design-system/docs-shell/DocsSidebar.astro
+++ b/src/design-system/docs-shell/DocsSidebar.astro
@@ -1,4 +1,5 @@
 ---
+import SidebarBehavior from './SidebarBehavior.astro';
 interface NavItem {
   label: string;
   href: string;
@@ -15,43 +16,57 @@ const { sections } = Astro.props;
 ---
 
 <aside
-  class="hidden w-[16.5rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
-  aria-label="Documentation navigation"
+  class="hidden w-[18.75rem] shrink-0 border-r border-border/60 bg-sidebar/55 backdrop-blur-sm lg:block"
 >
-  <nav
-    class="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-3.5 py-8 [scrollbar-gutter:stable]"
+  <div
+    class="ds-navscroll"
+    data-navscroll
+    data-at-top="true"
+    data-at-bottom="true"
   >
-    {
-      sections.map((section, si) => (
-        <div class={si === sections.length - 1 ? '' : 'mb-7'}>
-          <p class="mb-2.5 px-3 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60">
-            {section.title}
-          </p>
-          <ul class="space-y-0.5">
-            {section.items.map((item) => (
-              <li>
-                <a
-                  href={item.href}
-                  aria-current={item.active ? 'page' : undefined}
-                  class={`group relative flex items-center rounded-lg px-3 py-[0.47rem] text-[0.9rem] leading-snug outline-none transition-[color,background-color] duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
-                    item.active
-                      ? 'bg-primary/[0.08] font-semibold text-primary'
-                      : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
-                  }`}
-                >
-                  {item.active && (
-                    <span
-                      aria-hidden="true"
-                      class="absolute inset-y-1.5 left-0 w-[3px] rounded-r-full bg-primary shadow-[0_0_10px_1px_var(--glow-primary)]"
-                    />
-                  )}
-                  {item.label}
-                </a>
-              </li>
-            ))}
-          </ul>
-        </div>
-      ))
-    }
-  </nav>
+    <nav
+      class="ds-navscroll__viewport px-3.5 py-8"
+      data-navscroll-viewport
+      aria-label="Documentation navigation"
+    >
+      {
+        sections.map((section, si) => (
+          <div class={si === sections.length - 1 ? '' : 'mb-7'}>
+            <p class="mb-2.5 px-[0.65rem] text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground/70">
+              {section.title}
+            </p>
+            <ul class="space-y-px">
+              {section.items.map((item) => (
+                <li>
+                  <a
+                    href={item.href}
+                    aria-current={item.active ? 'page' : undefined}
+                    class={`group relative flex items-center rounded-lg px-[0.6rem] py-[0.4rem] text-base leading-snug outline-none transition-[color,background-color] duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
+                      item.active
+                        ? 'bg-primary/[0.09] font-semibold text-primary'
+                        : 'font-normal text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
+                    }`}
+                  >
+                    {item.active && (
+                      <span
+                        aria-hidden="true"
+                        class="absolute inset-y-[0.32rem] left-0 w-[3px] rounded-r-full bg-primary shadow-[0_0_10px_1px_var(--glow-primary)]"
+                      />
+                    )}
+                    {item.label}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))
+      }
+    </nav>
+    <span class="ds-navscroll__fade ds-navscroll__fade--top" aria-hidden="true"
+    ></span>
+    <span
+      class="ds-navscroll__fade ds-navscroll__fade--bottom"
+      aria-hidden="true"></span>
+  </div>
+  <SidebarBehavior />
 </aside>
diff --git a/src/design-system/docs-shell/DocsSidebarNav.astro b/src/design-system/docs-shell/DocsSidebarNav.astro
index bae4f99c31..ce5522b804 100644
--- a/src/design-system/docs-shell/DocsSidebarNav.astro
+++ b/src/design-system/docs-shell/DocsSidebarNav.astro
@@ -1,8 +1,7 @@
 ---
-// Recursive nav renderer for the real Octopus nav tree (NavPage[]).
-// Reuses DocsSidebar's visual language (eyebrow section labels, active-item
-// indicator, focus rings) but renders nested native <details> sections.
-// Zero-JS: collapsible state is native <details open>.
+// Recursive nav over the Octopus nav tree (NavPage[]). Three shapes: leaf link,
+// collapsed top-level link (right-chevron), expandable native <details>.
+// Zero-JS. Styling lives in theme.css (.ds-nav__*) so it paints on first load.
 import { Accelerator } from 'astro-accelerator-utils';
 import type { NavPage } from 'astro-accelerator-utils/types/NavPage';
 import { SITE } from '@config';
@@ -18,28 +17,43 @@ const { page, depth = 0 } = Astro.props satisfies Props;
 const displayLink = page.title != null;
 const linkTitle = page.title === page.fullTitle ? null : page.fullTitle;
 const children = page.children.slice().sort((a, b) => a.order - b.order);
+
+const href = accelerator.urlFormatter.formatAddress(page.url);
+
+// page.ariaCurrent is the source of truth; fall back to a normalized path
+// compare because the upstream exact-match misses on trailing-slash diffs.
+const normalize = (p: string) => p.replace(/\/+$/, '') || '/';
+const currentPath = normalize(new URL(Astro.url).pathname);
+const isCurrent = Boolean(page.ariaCurrent) || normalize(href) === currentPath;
+const ariaCurrent = isCurrent ? page.ariaCurrent || 'page' : undefined;
+
+// Open section on the active branch lights its rail (the trail to the page).
+const isCurrentPage = (p: NavPage): boolean =>
+  Boolean(p.ariaCurrent) ||
+  normalize(accelerator.urlFormatter.formatAddress(p.url)) === currentPath;
+const onActiveTrail =
+  page.children.length > 0 &&
+  page.isOpen &&
+  page.children.some(function hasCurrent(c: NavPage): boolean {
+    return isCurrentPage(c) || c.children.some(hasCurrent);
+  });
 ---
 
 {
   displayLink && page.children.length === 0 && (
-    <li data-component="DocsSidebarNav">
+    <li class="ds-nav__item" data-component="DocsSidebarNav">
       <a
-        href={accelerator.urlFormatter.formatAddress(page.url)}
-        aria-current={page.ariaCurrent ? page.ariaCurrent : undefined}
+        href={href}
+        aria-current={ariaCurrent}
         rel={page.rel}
         title={linkTitle}
-        class={`group/link relative flex items-center justify-between gap-2 rounded-lg py-[0.47rem] pr-2.5 text-[0.9rem] leading-snug outline-none transition-[color,background-color] duration-150 focus-visible:ring-2 focus-visible:ring-ring ${
-          depth > 0 ? 'pl-3' : 'pl-3'
-        } ${
-          page.ariaCurrent
-            ? 'bg-primary/[0.08] font-semibold text-primary before:absolute before:inset-y-1.5 before:left-0 before:w-[3px] before:rounded-r-full before:bg-primary before:shadow-[0_0_10px_1px_var(--glow-primary)]'
-            : 'font-medium text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
-        }`}
+        class={`ds-nav__link ${depth === 0 ? 'ds-nav__link--top' : 'ds-nav__link--leaf'}`}
       >
-        <span class="truncate">{page.title}</span>
+        {depth > 0 && <span class="ds-nav__node" aria-hidden="true" />}
+        <span class="ds-nav__text">{page.title}</span>
         {depth === 0 && (
           <svg
-            class="h-3.5 w-3.5 shrink-0 text-muted-foreground/45"
+            class="ds-nav__chevron ds-nav__chevron--nav"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
@@ -57,21 +71,18 @@ const children = page.children.slice().sort((a, b) => a.order - b.order);
 }
 {
   displayLink && page.children.length > 0 && (
-    <li data-component="DocsSidebarNav">
+    <li class="ds-nav__item" data-component="DocsSidebarNav">
       <details
         open={page.isOpen}
-        class={`group ${depth === 0 ? 'mb-7 last:mb-0' : 'mt-px'}`}
+        class={`ds-nav__section ${depth === 0 ? 'ds-nav__section--top' : 'ds-nav__section--nested'} ${onActiveTrail ? 'is-trail' : ''}`}
       >
         <summary
-          class={`flex cursor-pointer list-none items-center justify-between gap-2 rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-webkit-details-marker]:hidden ${
-            depth === 0
-              ? 'mb-2.5 px-3 py-1 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-muted-foreground/60'
-              : 'px-3 py-[0.47rem] text-[0.9rem] font-medium leading-snug text-sidebar-foreground hover:bg-muted/55 hover:text-foreground'
-          }`}
+          class={`ds-nav__summary ${depth === 0 ? 'ds-nav__summary--top' : 'ds-nav__summary--nested'}`}
         >
-          <span>{page.section}</span>
+          {depth > 0 && <span class="ds-nav__node" aria-hidden="true" />}
+          <span class="ds-nav__text">{page.section}</span>
           <svg
-            class="h-3.5 w-3.5 shrink-0 text-muted-foreground/70 transition-transform group-open:rotate-90"
+            class="ds-nav__chevron"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
@@ -80,15 +91,11 @@ const children = page.children.slice().sort((a, b) => a.order - b.order);
             stroke-linejoin="round"
             aria-hidden="true"
           >
-            <path d="m9 18 6-6-6-6" />
+            <path d="m6 9 6 6 6-6" />
           </svg>
         </summary>
         <ul
-          class={
-            depth === 0
-              ? 'space-y-0.5'
-              : 'ml-3 space-y-0.5 border-l border-border/50 pl-2'
-          }
+          class={`ds-nav__list ${depth === 0 ? 'ds-nav__list--top' : 'ds-nav__list--nested'}`}
         >
           {children.map((child) => (
             <Astro.self page={child} depth={depth + 1} />
diff --git a/src/design-system/docs-shell/DocsToc.astro b/src/design-system/docs-shell/DocsToc.astro
index e5321f2fbe..bfd817f4ad 100644
--- a/src/design-system/docs-shell/DocsToc.astro
+++ b/src/design-system/docs-shell/DocsToc.astro
@@ -86,14 +86,13 @@ const { items } = Astro.props;
 </aside>
 
 <style>
-  /* TOC: continuous rail with a brand reading-progress fill and a sliding
-     active thumb. Active state is driven by aria-current from the scroll-spy
-     script; thumb position/height come from --thumb-* set in the script. */
+  /* TOC: continuous rail. The brand fill and the active thumb share one point -
+     both end at the current topic (set from the scroll-spy script). */
   .ds-toc {
     --thumb-top: 0px;
     --thumb-h: 0px;
     --thumb-on: 0;
-    --toc-progress: 0%;
+    --toc-fill: 0px;
   }
 
   .ds-toc__head {
@@ -107,7 +106,7 @@ const { items } = Astro.props;
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font-size: 0.74rem;
+    font-size: 0.75rem;
     font-weight: 600;
     text-transform: uppercase;
     letter-spacing: 0.08em;
@@ -120,7 +119,7 @@ const { items } = Astro.props;
   }
   .ds-toc__pct {
     font-family: var(--font-mono);
-    font-size: 0.66rem;
+    font-size: 0.75rem;
     font-weight: 500;
     letter-spacing: 0.02em;
     font-variant-numeric: tabular-nums;
@@ -149,17 +148,22 @@ const { items } = Astro.props;
     border-radius: 9999px;
     background: var(--border);
   }
-  /* Reading-progress fill grows top-down with scroll. */
+  /* Glassy translucent fill that grows down to the active topic; its tip meets
+     the thumb. Soft and frosted, so the bright thumb stays the accent. */
   .ds-toc__progress {
     position: absolute;
     left: 0;
     top: 0;
     width: 2px;
-    height: var(--toc-progress);
+    height: var(--toc-fill);
     border-radius: 9999px;
-    background: var(--gradient-brand);
-    box-shadow: 0 0 8px -1px var(--glow-brand);
-    transition: height 0.15s linear;
+    background: linear-gradient(
+      to bottom,
+      color-mix(in oklab, var(--primary) 16%, transparent) 0%,
+      color-mix(in oklab, var(--purple-300) 24%, transparent) 52%,
+      color-mix(in oklab, var(--purple-300) 40%, transparent) 100%
+    );
+    transition: height 0.32s cubic-bezier(0.16, 1, 0.3, 1);
   }
   /* Sliding active thumb: a brighter, glowing segment of the rail. */
   .ds-toc__thumb {
@@ -197,7 +201,7 @@ const { items } = Astro.props;
     align-items: baseline;
     gap: 0.55rem;
     padding: 0.34rem 0 0.34rem 1rem;
-    font-size: 0.875rem;
+    font-size: 1rem;
     line-height: 1.4;
     color: var(--muted-foreground);
     text-decoration: none;
@@ -208,7 +212,6 @@ const { items } = Astro.props;
   }
   .ds-toc__link.is-nested {
     padding-left: 1.75rem;
-    font-size: 0.82rem;
   }
   /* Small leading dot brightens on hover/active for a tactile feel. */
   .ds-toc__dot {
@@ -260,7 +263,7 @@ const { items } = Astro.props;
     gap: 0.45rem;
     margin-top: 1.4rem;
     padding: 0.3rem 0.1rem;
-    font-size: 0.78rem;
+    font-size: 0.875rem;
     font-weight: 500;
     color: var(--muted-foreground);
     text-decoration: none;
@@ -333,7 +336,7 @@ const { items } = Astro.props;
       }
     }
 
-    // Slide the active thumb to the current link (relative to the list).
+    // Slide the active thumb to the current link, and grow the fill to meet it.
     const moveThumb = (link) => {
       if (!thumb || !link) return;
       const h = link.offsetHeight * 0.6;
@@ -341,6 +344,10 @@ const { items } = Astro.props;
       root.style.setProperty('--thumb-top', `${top}px`);
       root.style.setProperty('--thumb-h', `${h}px`);
       root.style.setProperty('--thumb-on', '1');
+      root.style.setProperty(
+        '--toc-fill',
+        `${link.offsetTop + link.offsetHeight / 2}px`
+      );
     };
 
     let current = null;
@@ -373,7 +380,6 @@ const { items } = Astro.props;
         const doc = document.documentElement;
         const max = doc.scrollHeight - doc.clientHeight;
         const pct = max > 0 ? Math.min(1, Math.max(0, doc.scrollTop / max)) : 0;
-        root.style.setProperty('--toc-progress', `${(pct * 100).toFixed(1)}%`);
         if (pctEl) pctEl.textContent = `${Math.round(pct * 100)}%`;
         if (doc.scrollTop > 120) root.setAttribute('data-scrolled', '');
         else root.removeAttribute('data-scrolled');
diff --git a/src/design-system/docs-shell/SidebarBehavior.astro b/src/design-system/docs-shell/SidebarBehavior.astro
new file mode 100644
index 0000000000..8e9e5e42d2
--- /dev/null
+++ b/src/design-system/docs-shell/SidebarBehavior.astro
@@ -0,0 +1,86 @@
+---
+// Sidebar behaviour for [data-navscroll] viewports: edge fade shades, auto-reveal
+// of the active item, and a tooltip for truncated labels. Vanilla, zero deps.
+// Shared by DocsSidebar (showcase) and DocsContentLayout (real nav).
+---
+
+<script is:inline>
+  (() => {
+    const roots = document.querySelectorAll('[data-navscroll]');
+    if (!roots.length) return;
+
+    // One fixed tooltip, reused. Fixed position escapes the scroll clip.
+    let tip;
+    const getTip = () => {
+      if (!tip) {
+        tip = document.createElement('div');
+        tip.className = 'ds-nav-tip';
+        tip.setAttribute('role', 'tooltip');
+        document.body.appendChild(tip);
+      }
+      return tip;
+    };
+    const hideTip = () => tip && tip.removeAttribute('data-show');
+    const truncated = (el) => el && el.scrollWidth > el.clientWidth + 1;
+    const showTip = (textEl, row) => {
+      const t = getTip();
+      t.textContent = textEl.textContent.trim();
+      const r = row.getBoundingClientRect();
+      t.style.top = `${r.top + r.height / 2}px`;
+      t.style.left = `${r.right + 10}px`;
+      t.setAttribute('data-show', '');
+      const tr = t.getBoundingClientRect();
+      if (tr.right > window.innerWidth - 8)
+        t.style.left = `${Math.max(8, window.innerWidth - 8 - tr.width)}px`;
+    };
+    const onOver = (e) => {
+      const row = e.target.closest('.ds-nav__link, .ds-nav__summary');
+      if (!row) return;
+      const tx = row.querySelector('.ds-nav__text');
+      if (truncated(tx)) showTip(tx, row);
+      else hideTip();
+    };
+
+    roots.forEach((root) => {
+      const vp = root.querySelector('[data-navscroll-viewport]');
+      if (!vp || vp.__nsInit) return;
+      vp.__nsInit = true;
+
+      const update = () => {
+        root.setAttribute('data-at-top', vp.scrollTop <= 1 ? 'true' : 'false');
+        root.setAttribute(
+          'data-at-bottom',
+          vp.scrollTop + vp.clientHeight >= vp.scrollHeight - 1
+            ? 'true'
+            : 'false'
+        );
+      };
+
+      // Reveal the active item if it loaded out of view.
+      const active = vp.querySelector('[aria-current="page"]');
+      if (active) {
+        const v = vp.getBoundingClientRect();
+        const a = active.getBoundingClientRect();
+        if (a.top < v.top || a.bottom > v.bottom)
+          vp.scrollTop +=
+            a.top - v.top - (vp.clientHeight - active.offsetHeight) / 2;
+      }
+
+      vp.addEventListener(
+        'scroll',
+        () => {
+          update();
+          hideTip();
+        },
+        { passive: true }
+      );
+      window.addEventListener('resize', update);
+      window.addEventListener('scroll', hideTip, { passive: true });
+      vp.addEventListener('mouseover', onOver);
+      vp.addEventListener('focusin', onOver);
+      vp.addEventListener('mouseleave', hideTip);
+      vp.addEventListener('focusout', hideTip);
+      update();
+    });
+  })();
+</script>
diff --git a/src/design-system/theme.css b/src/design-system/theme.css
index 5ce1e3950c..4ef4b7c5f8 100644
--- a/src/design-system/theme.css
+++ b/src/design-system/theme.css
@@ -99,8 +99,7 @@ html {
   pointer-events: none;
   background:
     radial-gradient(52rem 38rem at 12% -8%, var(--aurora-1), transparent 60%),
-    radial-gradient(46rem 40rem at 100% 0%, var(--aurora-2), transparent 58%),
-    radial-gradient(60rem 46rem at 78% 108%, var(--aurora-3), transparent 62%);
+    radial-gradient(46rem 40rem at 100% 0%, var(--aurora-2), transparent 58%);
   background-color: var(--background);
 }
 .ds-atmosphere::before {
@@ -120,20 +119,6 @@ html {
   );
   mask-image: radial-gradient(120% 80% at 50% 0%, #000 0%, transparent 75%);
 }
-.ds-atmosphere::after {
-  /* Slow-drifting luminous bloom. */
-  content: '';
-  position: absolute;
-  inset: -20% -10% auto -10%;
-  height: 60%;
-  background: radial-gradient(
-    40rem 22rem at 30% 0%,
-    var(--aurora-1),
-    transparent 70%
-  );
-  opacity: 0.7;
-  animation: ds-drift 22s ease-in-out infinite alternate;
-}
 .ds-grain {
   position: fixed;
   inset: 0;
@@ -144,15 +129,6 @@ html {
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
 }
 
-@keyframes ds-drift {
-  from {
-    transform: translate3d(-3%, -2%, 0) scale(1);
-  }
-  to {
-    transform: translate3d(5%, 3%, 0) scale(1.12);
-  }
-}
-
 /* Staggered page-load reveal: [data-rise] fades/lifts, --rise sets the delay. */
 @keyframes ds-rise {
   from {
@@ -172,9 +148,6 @@ html {
   [data-rise] {
     animation: none;
   }
-  .ds-atmosphere::after {
-    animation: none;
-  }
 }
 
 /* Gradient brand text (hero H1 / accents). */
@@ -204,8 +177,8 @@ html {
   --tw-prose-pre-bg: var(--code-bg);
   --tw-prose-pre-code: var(--code-foreground);
   max-width: 46rem;
-  font-size: 1.02rem;
-  line-height: 1.78;
+  font-size: 1rem;
+  line-height: 1.75;
   font-feature-settings: 'ss01', 'cv01';
 }
 
@@ -215,19 +188,20 @@ html {
   margin-top: 3rem;
   margin-bottom: 1rem;
   font-family: var(--font-display);
-  font-size: 1.7rem;
-  line-height: 1.22;
+  font-size: 1.75rem;
+  line-height: 1.25;
   font-weight: 700;
   letter-spacing: -0.02em;
   scroll-margin-top: 6rem;
 }
-/* Glowing tick to the left of every H2. */
+/* Glowing tick to the left of every H2, centered on the first line. */
 .prose :where(h2):not(:where([class~='not-prose'] *))::before {
   content: '';
   position: absolute;
   left: -1.15rem;
-  top: 0.45em;
-  height: 1.05em;
+  top: 50%;
+  transform: translateY(-50%);
+  height: 0.82em;
   width: 3px;
   border-radius: 9999px;
   background: var(--gradient-brand);
@@ -237,8 +211,8 @@ html {
   margin-top: 2.1rem;
   margin-bottom: 0.6rem;
   font-family: var(--font-display);
-  font-size: 1.28rem;
-  line-height: 1.32;
+  font-size: 1.25rem;
+  line-height: 1.35;
   font-weight: 650;
   letter-spacing: -0.014em;
   scroll-margin-top: 6rem;
@@ -255,20 +229,26 @@ html {
   color: var(--foreground);
 }
 
-/* Links: an underline that grows in from the left on hover. */
-.prose :where(a):not(:where([class~='not-prose'] *)) {
+/* Links: no underline at rest; on hover it draws in from the left (matches the
+   marketing site). Uses background-size width (0 -> 100%) rather than an
+   absolute ::after, so it works on links that wrap across lines. Buttons opt out. */
+.prose :where(a):not(.button):not(:where([class~='not-prose'] *)) {
   font-weight: 500;
   text-decoration: none;
   color: var(--primary);
-  background-image: linear-gradient(var(--primary), var(--primary));
+  background-image: linear-gradient(currentColor, currentColor);
   background-position: 0 100%;
   background-repeat: no-repeat;
-  background-size: 100% 1px;
+  background-size: 0% 1px;
   padding-bottom: 1px;
-  transition: background-size 0.25s ease;
+  transition:
+    background-size 0.2s ease-in-out,
+    color 0.2s ease-in-out;
 }
-.prose :where(a):not(:where([class~='not-prose'] *)):hover {
-  background-size: 100% 2px;
+.prose :where(a):not(.button):not(:where([class~='not-prose'] *)):hover,
+.prose
+  :where(a):not(.button):not(:where([class~='not-prose'] *)):focus-visible {
+  background-size: 100% 1px;
 }
 
 /* Lists: tidy markers and spacing. */
@@ -330,7 +310,7 @@ html {
   border-radius: var(--radius-lg);
   box-shadow: var(--shadow-md);
   font-family: var(--font-mono);
-  font-size: 0.86rem;
+  font-size: 0.875rem;
   line-height: 1.78;
   overflow-x: auto;
 }
@@ -381,7 +361,7 @@ html {
   align-items: center;
   gap: 0.5rem;
   font-family: var(--font-mono);
-  font-size: 0.72rem;
+  font-size: 0.75rem;
   letter-spacing: 0.03em;
   font-weight: 500;
   color: color-mix(in oklab, var(--code-foreground) 64%, transparent);
@@ -402,7 +382,7 @@ html {
   background: var(--code-bg);
   color: var(--code-foreground);
   font-family: var(--font-mono);
-  font-size: 0.86rem;
+  font-size: 0.875rem;
   line-height: 1.78;
   overflow-x: auto;
 }
@@ -425,7 +405,7 @@ html {
   background: transparent;
   color: color-mix(in oklab, var(--code-foreground) 55%, transparent);
   font-family: var(--font-sans);
-  font-size: 0.72rem;
+  font-size: 0.75rem;
   font-weight: 500;
   cursor: pointer;
   transition:
@@ -475,7 +455,7 @@ html {
   border-collapse: separate;
   border-spacing: 0;
   overflow: hidden;
-  font-size: 0.94rem;
+  font-size: 0.875rem;
   background: color-mix(in oklab, var(--card) 60%, transparent);
 }
 .prose :where(thead):not(:where([class~='not-prose'] *)) {
@@ -484,7 +464,7 @@ html {
 }
 .prose :where(thead th):not(:where([class~='not-prose'] *)) {
   padding: 0.72rem 1rem;
-  font-size: 0.72rem;
+  font-size: 0.75rem;
   font-weight: 650;
   letter-spacing: 0.06em;
   text-transform: uppercase;
@@ -515,8 +495,10 @@ html {
   border-radius: var(--radius-sm);
   font-family: var(--font-mono);
   font-weight: 500;
-  font-size: 0.8em;
-  white-space: nowrap;
+  font-size: 0.875em;
+  /* Long unbroken tokens (URLs, paths) must wrap inside the container, not overflow it. */
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 .prose :not(pre) > code::before,
 .prose :not(pre) > code::after {
@@ -530,7 +512,7 @@ html {
   gap: 0.4rem;
   padding: 0.15rem 0.6rem 0.15rem 0.5rem;
   border-radius: 9999px;
-  font-size: 0.74rem;
+  font-size: 0.75rem;
   font-weight: 600;
   line-height: 1.4;
   white-space: nowrap;
@@ -590,7 +572,7 @@ html {
   border-radius: var(--radius-lg);
   background: var(--bg);
   color: var(--c);
-  font-size: 0.95rem;
+  font-size: 1rem;
   line-height: 1.66;
   box-shadow: var(--shadow-sm);
 }
@@ -723,7 +705,7 @@ html {
   margin-top: 0.7rem;
   text-align: center;
   color: var(--muted-foreground);
-  font-size: 0.85rem;
+  font-size: 0.875rem;
   line-height: 1.5;
 }
 
@@ -746,7 +728,7 @@ html {
   border: 1px solid var(--code-border);
   border-radius: var(--radius-lg);
   box-shadow: var(--shadow-md);
-  font-size: 0.86rem;
+  font-size: 0.875rem;
   line-height: 1.7;
   overflow-x: auto;
 }
@@ -917,3 +899,742 @@ html {
     }
   }
 }
+
+/* Sidebar nav (DocsSidebarNav). Kept here (not a scoped <style>) so it paints on
+   first load. All nav text is 1rem; hierarchy comes from indent, rails, weight
+   and the active highlight, not size. */
+.ds-nav__item {
+  margin: 0;
+  list-style: none;
+}
+.ds-nav__link,
+.ds-nav__summary {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  border-radius: 0.5rem;
+  outline: none;
+  text-decoration: none;
+  transition:
+    color 0.16s ease,
+    background-color 0.16s ease;
+}
+.ds-nav__text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Top-level section: identical typography whether collapsed (link) or open
+   (summary); only the chevron + revealed children differ. */
+.ds-nav__link--top,
+.ds-nav__summary--top {
+  padding: 0.47rem 0.6rem 0.47rem 0.65rem;
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.4;
+  color: var(--sidebar-foreground);
+}
+.ds-nav__summary--top {
+  cursor: pointer;
+  list-style: none;
+}
+.ds-nav__summary--top::-webkit-details-marker {
+  display: none;
+}
+.ds-nav__link--top:hover,
+.ds-nav__summary--top:hover {
+  background: color-mix(in oklab, var(--muted) 55%, transparent);
+  color: var(--foreground);
+}
+
+/* Nested section toggle. */
+.ds-nav__summary--nested {
+  padding: 0.42rem 0.55rem 0.42rem 0.45rem;
+  cursor: pointer;
+  list-style: none;
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.4;
+  color: var(--sidebar-foreground);
+}
+.ds-nav__summary--nested::-webkit-details-marker {
+  display: none;
+}
+.ds-nav__summary--nested:hover {
+  background: color-mix(in oklab, var(--muted) 55%, transparent);
+  color: var(--foreground);
+}
+.ds-nav__section--nested[open] > .ds-nav__summary--nested {
+  color: var(--foreground);
+}
+
+/* Leaf link. */
+.ds-nav__link--leaf {
+  padding: 0.4rem 0.55rem 0.4rem 0.45rem;
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.4;
+  color: var(--sidebar-foreground);
+}
+.ds-nav__link--leaf:hover {
+  background: color-mix(in oklab, var(--muted) 55%, transparent);
+  color: var(--foreground);
+}
+
+/* Tree connector dot before nested items. */
+.ds-nav__node {
+  flex: none;
+  position: relative;
+  width: 0.55rem;
+  height: 0.55rem;
+  margin-left: 0.1rem;
+}
+.ds-nav__node::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  width: 4px;
+  height: 4px;
+  border-radius: 9999px;
+  background: color-mix(in oklab, var(--muted-foreground) 45%, transparent);
+  transition:
+    background 0.16s ease,
+    box-shadow 0.16s ease,
+    transform 0.16s ease;
+}
+.ds-nav__link--leaf:hover .ds-nav__node::before,
+.ds-nav__summary--nested:hover .ds-nav__node::before {
+  background: color-mix(in oklab, var(--primary) 70%, transparent);
+}
+.ds-nav__section--nested[open]
+  > .ds-nav__summary--nested
+  .ds-nav__node::before {
+  background: color-mix(in oklab, var(--primary) 60%, transparent);
+}
+
+/* Chevrons. Toggle = down caret that flips up when open (disclosure); the
+   collapsed-link "navigate" chevron (--nav) points right and nudges on hover. */
+.ds-nav__chevron {
+  flex: none;
+  height: 0.85rem;
+  width: 0.85rem;
+  color: color-mix(in oklab, var(--muted-foreground) 70%, transparent);
+  transition:
+    transform 0.22s cubic-bezier(0.16, 1, 0.3, 1),
+    color 0.16s ease;
+}
+.ds-nav__section[open] > .ds-nav__summary > .ds-nav__chevron {
+  transform: rotate(180deg);
+  color: var(--primary);
+}
+.ds-nav__summary:hover > .ds-nav__chevron {
+  color: var(--foreground);
+}
+.ds-nav__chevron--nav {
+  color: color-mix(in oklab, var(--muted-foreground) 45%, transparent);
+  transition:
+    transform 0.18s ease,
+    color 0.16s ease;
+}
+.ds-nav__link--top:hover .ds-nav__chevron--nav {
+  transform: translateX(2px);
+  color: color-mix(in oklab, var(--primary) 80%, transparent);
+}
+
+/* Top-level grouping rhythm. */
+.ds-nav__section--top {
+  margin-bottom: 1.75rem;
+}
+.ds-nav__section--top:last-child {
+  margin-bottom: 0;
+}
+
+/* Nested group: tree-guide rail + open tint. */
+.ds-nav__list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.ds-nav__list--top > .ds-nav__item + .ds-nav__item {
+  margin-top: 1px;
+}
+.ds-nav__list--nested {
+  position: relative;
+  margin-left: 0.7rem;
+  padding-left: 0.55rem;
+  border-left: 1px solid color-mix(in oklab, var(--border) 90%, transparent);
+}
+.ds-nav__list--nested > .ds-nav__item + .ds-nav__item {
+  margin-top: 1px;
+}
+.ds-nav__section.is-trail > .ds-nav__list--nested {
+  border-left-color: color-mix(in oklab, var(--primary) 40%, var(--border));
+}
+.ds-nav__section--nested[open] {
+  border-radius: 0.5rem;
+  background: color-mix(in oklab, var(--muted) 22%, transparent);
+}
+
+/* Active leaf: tinted bg + glowing brand rail. */
+.ds-nav__link[aria-current] {
+  color: var(--primary);
+  font-weight: 600;
+  background: color-mix(in oklab, var(--primary) 9%, transparent);
+}
+.ds-nav__link[aria-current] .ds-nav__text {
+  color: var(--primary);
+}
+.ds-nav__link[aria-current]::before {
+  content: '';
+  position: absolute;
+  top: 0.32rem;
+  bottom: 0.32rem;
+  left: -0.56rem;
+  width: 3px;
+  border-radius: 9999px;
+  background: var(--primary);
+  box-shadow: 0 0 10px 1px var(--glow-primary);
+}
+.ds-nav__link[aria-current] .ds-nav__node::before {
+  background: var(--primary);
+  transform: scale(1.35);
+  box-shadow: 0 0 8px 0 var(--glow-primary);
+}
+.ds-nav__link--top[aria-current]::before {
+  left: -0.65rem;
+}
+
+.ds-nav__link:focus-visible,
+.ds-nav__summary:focus-visible {
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 65%, transparent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ds-nav__chevron,
+  .ds-nav__chevron--nav,
+  .ds-nav__node::before,
+  .ds-nav__link,
+  .ds-nav__summary {
+    transition: none;
+  }
+}
+
+/* Sidebar scroll container: a sticky wrapper holds the scroller plus top/bottom
+   fade scrims. The script toggles data-at-top/bottom so each scrim shows only
+   when there's hidden content that way, hinting "scroll to reveal more". */
+.ds-navscroll {
+  position: sticky;
+  top: 4rem;
+}
+.ds-navscroll__viewport {
+  max-height: calc(100vh - 4rem);
+  overflow-y: auto;
+  scrollbar-gutter: stable;
+}
+.ds-navscroll__fade {
+  position: absolute;
+  left: 0;
+  right: 0;
+  height: 2.75rem;
+  z-index: 1;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.25s ease;
+}
+.ds-navscroll__fade--top {
+  top: 0;
+  background: linear-gradient(to bottom, var(--sidebar), transparent);
+}
+.ds-navscroll__fade--bottom {
+  bottom: 0;
+  background: linear-gradient(to top, var(--sidebar), transparent);
+}
+.ds-navscroll[data-at-top='false'] .ds-navscroll__fade--top {
+  opacity: 1;
+}
+.ds-navscroll[data-at-bottom='false'] .ds-navscroll__fade--bottom {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ds-navscroll__fade {
+    transition: none;
+  }
+}
+
+/* Tooltip revealing a truncated nav label. Fixed so it escapes the sidebar's
+   scroll clip; shown by the script only when the label is actually cut off. */
+.ds-nav-tip {
+  position: fixed;
+  z-index: 60;
+  max-width: 20rem;
+  padding: 0.35rem 0.65rem;
+  border-radius: 0.45rem;
+  background: var(--popover);
+  color: var(--popover-foreground);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow-md);
+  font-size: 0.875rem;
+  line-height: 1.35;
+  text-align: left;
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(-50%);
+  transition: opacity 0.14s ease;
+}
+.ds-nav-tip[data-show] {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ds-nav-tip {
+    transition: none;
+  }
+}
+
+/* ---------------------------------------------------------------------------
+   Header search re-skin.
+   This styles the REAL site search markup (src/themes/octopus/components/
+   Search.astro) + engine (public/docs/js/search.js) which are unchanged.
+   main.css is not loaded on design-system pages, so we provide the entire
+   look here, scoped under `.ds-search` (the wrapper added in DocsHeader).
+   Engine contract reminder: results show by toggling `.is-active` on
+   `[data-site-search]`; dropdown is `[data-site-search-results]`.
+--------------------------------------------------------------------------- */
+.ds-search {
+  --search-dropdown-height: 70vh;
+  --search-dropdown-duration: 0ms;
+}
+.ds-search .site-search__wrapper {
+  position: relative;
+  width: 100%;
+}
+/* The engine adds an overlay div + a mobile fallback link we don't use here. */
+.ds-search .site-search__overlay,
+.ds-search .site-search__mobile {
+  display: none;
+}
+
+/* Input box: rounded field with subtle border, muted bg, left search icon. */
+.ds-search .site-search {
+  position: relative;
+  margin: 0;
+  width: 100%;
+}
+.ds-search .site-search fieldset {
+  position: relative;
+  display: flex;
+  align-items: center;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.ds-search .site-search__icon {
+  position: absolute;
+  left: 0.75rem;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 16px;
+  height: 16px;
+  pointer-events: none;
+  color: var(--muted-foreground);
+}
+.ds-search .site-search__icon path {
+  fill: currentColor;
+}
+.ds-search .site-search-query {
+  width: 100%;
+  height: 2.25rem;
+  padding: 0 2.5rem 0 2.25rem;
+  font-size: 1rem;
+  color: var(--foreground);
+  background: color-mix(in oklab, var(--muted) 50%, transparent);
+  border: 1px solid var(--input);
+  border-radius: var(--radius-lg);
+  outline: none;
+  transition:
+    background-color 0.15s ease,
+    border-color 0.15s ease,
+    box-shadow 0.15s ease;
+}
+.ds-search .site-search-query::placeholder {
+  color: var(--muted-foreground);
+}
+.ds-search .site-search-query:hover {
+  border-color: var(--border);
+  background: color-mix(in oklab, var(--muted) 70%, transparent);
+}
+.ds-search .site-search-query:focus {
+  background: var(--background);
+  border-color: color-mix(in oklab, var(--primary) 50%, transparent);
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 60%, transparent);
+}
+.ds-search .site-search:focus-within .site-search__icon {
+  color: var(--primary);
+}
+
+/* Clear button (engine wires [data-site-search-remove]). */
+.ds-search .site-search__remove-btn {
+  position: absolute;
+  right: 0.5rem;
+  top: 50%;
+  transform: translateY(-50%);
+  display: grid;
+  place-items: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  opacity: 0;
+  transition:
+    opacity 0.15s ease,
+    background-color 0.15s ease,
+    color 0.15s ease;
+}
+.ds-search .site-search__remove-btn svg path {
+  fill: currentColor;
+}
+.ds-search
+  .site-search-query:not(:placeholder-shown)
+  ~ .site-search__remove-btn,
+.ds-search .site-search.is-active .site-search__remove-btn {
+  opacity: 1;
+}
+.ds-search .site-search__remove-btn:hover {
+  background: var(--muted);
+  color: var(--foreground);
+}
+
+/* Results dropdown: popover panel, hidden until engine adds `.is-active`. */
+.ds-search .site-search-results {
+  display: none;
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + 0.4rem);
+  z-index: 50;
+  max-height: min(70vh, 28rem);
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: 0 0.4rem;
+  background: var(--popover);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-xl);
+  box-shadow: var(--shadow-lg);
+  scrollbar-width: thin;
+}
+.ds-search .site-search.is-active ~ .site-search-results {
+  display: block;
+}
+/* Scroll shades: sticky pseudo-element scrims pinned to the viewport edges
+   (negative margins cancel their flow space). The header script toggles
+   data-at-top/bottom so each appears only when there's more to scroll. */
+.ds-search .site-search-results::before,
+.ds-search .site-search-results::after {
+  content: '';
+  position: sticky;
+  left: 0;
+  z-index: 2;
+  display: block;
+  height: 1.75rem;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.25s ease;
+}
+.ds-search .site-search-results::before {
+  top: 0;
+  margin-bottom: -1.75rem;
+  background: linear-gradient(to bottom, var(--popover), transparent);
+}
+.ds-search .site-search-results::after {
+  bottom: 0;
+  margin-top: -1.75rem;
+  background: linear-gradient(to top, var(--popover), transparent);
+}
+.ds-search .site-search-results[data-at-top='false']::before {
+  opacity: 1;
+}
+.ds-search .site-search-results[data-at-bottom='false']::after {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ds-search .site-search-results::before,
+  .ds-search .site-search-results::after {
+    transition: none;
+  }
+}
+.ds-search .site-search-results__list {
+  list-style: none;
+  margin: 0;
+  padding: 0.4rem 0;
+}
+.ds-search .site-search-results__item {
+  list-style: none;
+  margin: 0;
+}
+.ds-search .site-search-results__item + .site-search-results__item {
+  margin-top: 0.4rem;
+}
+/* Each result is a card. */
+.ds-search .result-wrapper {
+  display: block;
+  padding: 0.85rem 1rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  background: var(--card);
+  text-decoration: none;
+  color: inherit;
+  transition:
+    border-color 0.14s ease,
+    box-shadow 0.14s ease;
+}
+.ds-search .result-wrapper:hover,
+.ds-search .result-wrapper:focus,
+.ds-search .result-wrapper:focus-visible {
+  border-color: color-mix(in oklab, var(--primary) 45%, var(--border));
+  box-shadow: var(--shadow-sm);
+  outline: none;
+}
+.ds-search .result-title {
+  display: block;
+  font-size: 1rem;
+  font-weight: 600;
+  line-height: 1.35;
+  color: var(--foreground);
+}
+.ds-search .result-title mark {
+  background: color-mix(in oklab, var(--primary) 16%, transparent);
+  color: var(--primary);
+  font-weight: 700;
+  border-radius: 0.2rem;
+  padding: 0 0.14em;
+}
+.ds-search .result-path {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.22rem;
+  margin-bottom: 0.3rem;
+  font-size: 0.75rem;
+  letter-spacing: 0.01em;
+  color: color-mix(in oklab, var(--muted-foreground) 80%, transparent);
+}
+.ds-search .result-path__segment:last-child {
+  color: var(--muted-foreground);
+  font-weight: 500;
+}
+.ds-search .result-path__icon {
+  display: inline-flex;
+  align-items: center;
+  opacity: 0.7;
+  color: var(--muted-foreground);
+}
+/* Chevron in the path ships with a hardcoded stroke; follow the theme instead. */
+.ds-search .result-path__icon svg path {
+  stroke: currentColor;
+}
+.ds-search .result-description {
+  margin: 0.3rem 0 0;
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--muted-foreground);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.ds-search .result-description mark {
+  background: transparent;
+  color: var(--foreground);
+  font-weight: 600;
+}
+/* Optional matched-headings sublist (gated by site_features.search 'headings'). */
+.ds-search .result-headings {
+  list-style: none;
+  margin: 0.4rem 0 0.35rem 1rem;
+  padding: 0.1rem 0 0.1rem 0.75rem;
+  border-left: 1px solid var(--border);
+}
+.ds-search .result-headings a {
+  display: block;
+  padding: 0.22rem 0.5rem;
+  border-radius: var(--radius-sm);
+  font-size: 0.875rem;
+  color: var(--muted-foreground);
+  text-decoration: none;
+  transition:
+    color 0.12s ease,
+    background-color 0.12s ease;
+}
+.ds-search .result-headings a:hover {
+  color: var(--foreground);
+  background: var(--muted);
+}
+.ds-search .result-headings mark {
+  background: transparent;
+  color: var(--primary);
+  font-weight: 600;
+}
+
+/* Empty-state heading + "see more" button. */
+.ds-search .search-results__heading {
+  margin: 0;
+  padding: 1.4rem 0.75rem;
+  text-align: center;
+  font-size: 1rem;
+  font-weight: 500;
+  color: var(--muted-foreground);
+}
+.ds-search .show-more {
+  display: block;
+  width: calc(100% - 0.5rem);
+  margin: 0.35rem auto 0.1rem;
+  padding: 0.5rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  background: transparent;
+  color: var(--foreground);
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color 0.12s ease;
+}
+.ds-search .show-more:hover {
+  background: var(--muted);
+}
+
+/* Content buttons: authored in docs as `.button.button--primary` / `--secondary`
+   (the marketing-site class names). Scoped to .prose and unlayered so they beat
+   the prose link styling; same look as ui/Button.astro. */
+.prose a.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  position: relative;
+  z-index: 0;
+  max-width: fit-content;
+  overflow: hidden;
+  padding: var(--space-12) var(--space-24);
+  border-radius: 0.5rem;
+  border: 0.0625rem solid transparent;
+  font-family: var(--font-sans);
+  font-size: 1rem;
+  font-weight: var(--button-font-weight);
+  line-height: 1.2;
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    background 0.25s ease-in-out,
+    box-shadow 0.25s ease-in-out,
+    color 0.25s ease-in-out;
+}
+.prose a.button:hover {
+  text-decoration: none;
+}
+
+.prose a.button--primary {
+  color: var(--white);
+  background: var(--purple-300);
+}
+.prose a.button--primary::before {
+  content: '';
+  position: absolute;
+  left: var(--hover-x, 50%);
+  top: var(--hover-y, 50%);
+  width: 16rem;
+  height: 16rem;
+  background: radial-gradient(
+    circle closest-side,
+    var(--pink-100),
+    transparent
+  );
+  transform: translate(-50%, -50%) scale(0);
+  transition: transform 0.3s ease;
+  z-index: -1;
+  pointer-events: none;
+}
+.prose a.button--primary:hover {
+  box-shadow: inset 0 0 0 0.0625rem rgba(255, 255, 255, 0.25);
+}
+.prose a.button--primary:hover::before {
+  transform: translate(-50%, -50%) scale(1);
+}
+.prose a.button--primary:active {
+  box-shadow: var(--button-shadow-inner);
+}
+.prose a.button--primary:focus-visible {
+  outline: 0.25rem solid rgba(105, 80, 255, 0.5);
+}
+
+.prose a.button--secondary {
+  color: var(--secondary-button-text);
+  background: var(--secondary-button-bg);
+}
+.prose a.button--secondary::before {
+  content: '';
+  position: absolute;
+  left: var(--hover-x, 50%);
+  top: var(--hover-y, 50%);
+  width: 14rem;
+  height: 14rem;
+  background: radial-gradient(
+    circle closest-side,
+    var(--secondary-button-hover-glow),
+    transparent
+  );
+  transform: translate(-50%, -50%) scale(0);
+  transition: transform 0.3s ease;
+  z-index: -1;
+  pointer-events: none;
+}
+.prose a.button--secondary::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  padding: 0.0625rem;
+  background: var(--purple-300);
+  -webkit-mask-image: linear-gradient(#fff 0 0), linear-gradient(#fff 0 0);
+  -webkit-mask-clip: content-box, border-box;
+  -webkit-mask-composite: xor;
+  mask-image: linear-gradient(#fff 0 0), linear-gradient(#fff 0 0);
+  mask-clip: content-box, border-box;
+  mask-composite: exclude;
+  pointer-events: none;
+  z-index: 2;
+}
+.prose a.button--secondary:hover {
+  color: var(--secondary-button-hover-text);
+  background: var(--secondary-button-hover-bg);
+}
+.prose a.button--secondary:hover::before {
+  transform: translate(-50%, -50%) scale(1);
+}
+.prose a.button--secondary:active {
+  box-shadow: var(--button-shadow-inner);
+}
+.prose a.button--secondary:focus-visible {
+  background: var(--secondary-button-bg);
+  outline: 0.25rem solid var(--purple-300);
+}
+@media (prefers-reduced-motion: reduce) {
+  .prose a.button--primary::before,
+  .prose a.button--secondary::before {
+    transition: none;
+  }
+}
+
+/* The CTA's <span> wrapper is inline, so a margin on the inline-flex button
+   can't space it from the next block. Give the wrapper block rhythm instead. */
+.prose span:has(> a.button) {
+  display: block;
+  margin-bottom: 1.25rem;
+}
diff --git a/src/design-system/tokens.css b/src/design-system/tokens.css
index 672fa8db0f..308f50fa3d 100644
--- a/src/design-system/tokens.css
+++ b/src/design-system/tokens.css
@@ -99,10 +99,10 @@
   );
 
   /* --- Atmosphere (fixed background layers): cyan -> purple -> pink mesh --- */
-  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 20%, transparent);
-  --aurora-2: color-mix(in oklab, var(--pink-100) 14%, transparent);
-  --aurora-3: color-mix(in oklab, var(--purple-300) 16%, transparent);
-  --grid-line: color-mix(in oklab, var(--octo-navy-700) 6%, transparent);
+  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 11%, transparent);
+  --aurora-2: color-mix(in oklab, var(--pink-100) 7%, transparent);
+  --aurora-3: color-mix(in oklab, var(--purple-300) 9%, transparent);
+  --grid-line: color-mix(in oklab, var(--octo-navy-700) 3%, transparent);
   --grain-opacity: 0.035;
 
   /* Glass effect for in-content images (mirrors the marketing site). Raw
@@ -118,18 +118,20 @@
   --glass-navy-fade: rgba(10, 35, 54, 0);
   --glass-pad: 0.75rem;
 
+  /* Docs-calm glass: same structure as the marketing site, much softer (faint
+     tint, neutral lift, whisper of a bloom) so screenshots feel framed not hero. */
   --glass-background: linear-gradient(
     263.36deg,
-    rgba(255, 255, 255, 0.72) -46.77%,
-    rgba(147, 225, 255, 0.42) 86.43%
+    rgba(255, 255, 255, 0.6) -46.77%,
+    rgba(147, 225, 255, 0.12) 86.43%
   );
-  --glass-border-color: rgba(31, 192, 255, 0.32);
-  --glass-shadow: 0 12px 36px -12px rgba(31, 192, 255, 0.3);
+  --glass-border-color: rgba(31, 192, 255, 0.18);
+  --glass-shadow: 0 8px 26px -16px rgba(16, 33, 47, 0.18);
   --glass-blur-glow: radial-gradient(
     101.55% 101.55% at 50% -1.55%,
-    rgba(255, 255, 255, 0.55) 0%,
-    rgba(31, 192, 255, 0.38) 18.63%,
-    rgba(204, 60, 255, 0.3) 73.48%,
+    rgba(255, 255, 255, 0.35) 0%,
+    rgba(31, 192, 255, 0.14) 18.63%,
+    rgba(204, 60, 255, 0.09) 73.48%,
     var(--glass-navy-fade) 100%
   );
 
@@ -165,8 +167,8 @@
 
   --radius: 0.65rem;
 
-  /* Fonts - distinctive type carries the redesign. Loaded via Bunny Fonts in
-     the layout head; system stacks remain as graceful fallbacks. */
+  /* Fonts - distinctive web type (loaded via Bunny Fonts in the layout head);
+     system stacks remain as graceful fallbacks. */
   --font-display:
     'Bricolage Grotesque', 'Hanken Grotesk', system-ui, -apple-system,
     BlinkMacSystemFont, 'Segoe UI', sans-serif;
@@ -249,25 +251,27 @@
     #ec8cff 120%
   );
 
-  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 16%, transparent);
-  --aurora-2: color-mix(in oklab, var(--pink-100) 12%, transparent);
-  --aurora-3: color-mix(in oklab, var(--purple-300) 18%, transparent);
-  --grid-line: color-mix(in oklab, var(--octo-blue-bright) 6%, transparent);
+  --aurora-1: color-mix(in oklab, var(--octo-blue-bright) 9%, transparent);
+  --aurora-2: color-mix(in oklab, var(--pink-100) 7%, transparent);
+  --aurora-3: color-mix(in oklab, var(--purple-300) 10%, transparent);
+  --grid-line: color-mix(in oklab, var(--octo-blue-bright) 3%, transparent);
   --grain-opacity: 0.05;
 
   /* Glass effect: the exact marketing-site values (tuned for dark backgrounds). */
+  /* Docs-calm glass (dark): a gentle frost + faint bloom, not the bright
+     marketing panel. */
   --glass-background: linear-gradient(
     263.36deg,
-    var(--glass-white-31) -46.77%,
-    var(--glass-cyan) 86.43%
+    rgba(255, 255, 255, 0.08) -46.77%,
+    rgba(147, 225, 255, 0.09) 86.43%
   );
-  --glass-border-color: var(--glass-white-20);
-  --glass-shadow: 0 0 30px var(--glass-white-15);
+  --glass-border-color: rgba(255, 255, 255, 0.1);
+  --glass-shadow: 0 14px 30px -18px rgba(0, 0, 0, 0.5);
   --glass-blur-glow: radial-gradient(
     101.55% 101.55% at 50% -1.55%,
-    var(--glass-white-35) 0%,
-    var(--glass-cyan-glow) 18.63%,
-    var(--glass-pink-glow) 73.48%,
+    rgba(255, 255, 255, 0.18) 0%,
+    rgba(31, 192, 255, 0.18) 18.63%,
+    rgba(204, 60, 255, 0.14) 73.48%,
     var(--glass-navy-fade) 100%
   );
 
diff --git a/src/design-system/ui/Button.astro b/src/design-system/ui/Button.astro
index c7df190bf8..ff9f2e01d9 100644
--- a/src/design-system/ui/Button.astro
+++ b/src/design-system/ui/Button.astro
@@ -15,33 +15,24 @@ const Tag = href ? 'a' : 'button';
 <Tag class={cls} href={href} data-component="Button"><slot /></Tag>
 
 <script is:inline>
-  // Cursor-tracked glow: set --hover-x/--hover-y per pointer position.
+  // Cursor-tracked glow: set --hover-x/--hover-y per pointer position. Delegated
+  // on the document so it works for any button, including content buttons parsed
+  // after this header script runs.
   (() => {
     if (window.__dsBtnInit) return;
     window.__dsBtnInit = true;
-    const SELECTOR = '.ds-btn--primary, .ds-btn--secondary';
-    const seen = new WeakSet();
-    const track = (btn) => {
-      if (seen.has(btn)) return;
-      seen.add(btn);
-      let rect = null;
-      btn.addEventListener('mouseenter', () => {
-        rect = btn.getBoundingClientRect();
-      });
-      btn.addEventListener('mousemove', (e) => {
-        if (!rect) rect = btn.getBoundingClientRect();
-        btn.style.setProperty('--hover-x', e.clientX - rect.left + 'px');
-        btn.style.setProperty('--hover-y', e.clientY - rect.top + 'px');
-      });
-    };
-    document.querySelectorAll(SELECTOR).forEach(track);
-    new MutationObserver((muts) => {
-      for (const m of muts)
-        for (const n of m.addedNodes) {
-          if (n.nodeType !== 1) continue;
-          if (n.matches?.(SELECTOR)) track(n);
-          n.querySelectorAll?.(SELECTOR).forEach(track);
-        }
-    }).observe(document.body, { childList: true, subtree: true });
+    const SELECTOR =
+      '.ds-btn--primary, .ds-btn--secondary, .prose a.button--primary, .prose a.button--secondary';
+    document.addEventListener(
+      'pointermove',
+      (e) => {
+        const btn = e.target.closest?.(SELECTOR);
+        if (!btn) return;
+        const r = btn.getBoundingClientRect();
+        btn.style.setProperty('--hover-x', e.clientX - r.left + 'px');
+        btn.style.setProperty('--hover-y', e.clientY - r.top + 'px');
+      },
+      { passive: true }
+    );
   })();
 </script>
diff --git a/src/layouts/Default.astro b/src/layouts/Default.astro
index 0221ebdc55..94154c064d 100644
--- a/src/layouts/Default.astro
+++ b/src/layouts/Default.astro
@@ -1,149 +1,20 @@
 ---
-import { Accelerator, PostFiltering } from 'astro-accelerator-utils';
-import type { Frontmatter as OriginalFrontmatter } from 'astro-accelerator-utils/types/Frontmatter';
-import { SITE } from '@config';
-import { getImageInfo } from '@util/custom-markdown.mjs';
-
-// Theme components
-import Head from '@components/HtmlHead.astro';
-import SkipLinks from '@components/SkipLinks.astro';
-import Breadcrumbs from '@components/Breadcrumbs.astro';
-import Navigation from '@components/Navigation.astro';
-import Authors from '@components/Authors.astro';
-import Taxonomy from '@components/Taxonomy.astro';
-
-// Custom components
-import ArticleHeader from '../components/ArticleHeader.astro';
-import ArticleNav from '../components/ArticleNav.astro';
-import Copyright from '../components/Copyright.astro';
-import Header from '../components/Header.astro';
-import Related from '../components/Related.astro';
-import ArticleJourney from '../components/ArticleJourney.astro';
-import Feedback from '../components/Feedback.astro';
-import EditOnGithub from '../components/EditOnGithub.astro';
-import LastUpdated from '../components/LastUpdated.astro';
-import CopyMarkdown from '../components/CopyMarkdown.astro';
-import Plausible from 'src/components/Plausible.astro';
-import Footer from 'src/components/Footer.astro';
-
-// Extend Frontmatter with icon
-type Frontmatter = OriginalFrontmatter & {
-  icon?: string; // Add the icon property
-};
-
-type Props = {
-  frontmatter: Frontmatter;
-  headings: { depth: number; slug: string; text: string }[];
-  breadcrumbs?: { url: string; title: string; ariaCurrent?: string }[] | null;
-};
-const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props;
-
-const lang = frontmatter.lang ?? SITE.default.lang;
-const textDirection = frontmatter.dir ?? SITE.default.dir;
-
-// Logic
-const accelerator = new Accelerator(SITE);
-
-const metaImage = frontmatter.bannerImage
-  ? getImageInfo(frontmatter.bannerImage.src, '', SITE.images.contentSize)
-  : null;
-
-const title = await accelerator.markdown.getInlineHtmlFrom(
-  frontmatter.title ?? SITE.title
-);
-
-const subtitle = frontmatter.subtitle
-  ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.subtitle)
-  : null;
-
-const icon = frontmatter.icon
-  ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.icon)
-  : null;
-
-const site_url = SITE.url;
-const site_features = SITE.featureFlags;
-const search =
-  accelerator.posts.all().filter(PostFiltering.isSearch).shift() ?? null;
-const searchUrl = search && accelerator.urlFormatter.formatAddress(search.url);
-const isSearchPage =
-  accelerator.urlFormatter.formatAddress(Astro.url.pathname) === searchUrl;
-
-const showSearch = !isSearchPage;
+// Layout delegator. Every content page references `layout: src/layouts/Default.astro`
+// in its frontmatter, so this single file decides what the whole site renders -
+// no per-page frontmatter changes needed to switch designs.
+//
+// Default: the new design system (DocsContentLayout).
+// Escape hatch: set `legacyLayout: true` in a page's frontmatter to render the
+// original layout (preserved verbatim in DefaultLegacy.astro).
+// Global revert: swap the `Layout` default back to LegacyLayout, or restore this
+// file from DefaultLegacy.astro.
+import NewLayout from '../design-system/docs-shell/DocsContentLayout.astro';
+import LegacyLayout from './DefaultLegacy.astro';
+
+const { frontmatter, headings, breadcrumbs } = Astro.props;
+const Layout = frontmatter?.legacyLayout ? LegacyLayout : NewLayout;
 ---
 
-<html dir={textDirection} lang={lang} class="initial">
-  <Head frontmatter={frontmatter} headings={headings} lang={lang} />
-  <body data-theme="dark">
-    <SkipLinks frontmatter={frontmatter} headings={headings} lang={lang} />
-    <Header
-      frontmatter={frontmatter}
-      headings={headings}
-      lang={lang}
-      showSearch={showSearch}
-    />
-    <div class="content-group">
-      <main id="site-main">
-        <Breadcrumbs
-          frontmatter={frontmatter}
-          headings={headings}
-          lang={lang}
-          breadcrumbs={breadcrumbs}
-        />
-        <article itemscope itemtype="https://schema.org/Article">
-          <ArticleHeader
-            icon={icon}
-            lang={lang}
-            subtitle={subtitle}
-            title={title}
-          />
-          <div class="page-content anim-show-parent" itemprop="articleBody">
-            <slot />
-            <Feedback
-              frontmatter={frontmatter}
-              headings={headings}
-              lang={lang}
-            />
-            <Authors frontmatter={frontmatter} lang={lang} />
-            <Taxonomy frontmatter={frontmatter} lang={lang} />
-            <LastUpdated
-              frontmatter={frontmatter}
-              headings={headings}
-              lang={lang}
-            />
-            <EditOnGithub
-              frontmatter={frontmatter}
-              headings={headings}
-              lang={lang}
-            />
-            <CopyMarkdown lang={lang} />
-            <ArticleJourney
-              frontmatter={frontmatter}
-              headings={headings}
-              lang={lang}
-            />
-            {metaImage && <meta itemprop="image" content={metaImage.src} />}
-          </div>
-        </article>
-      </main>
-      <Navigation lang={lang} />
-      <div class="side-nav">
-        <!-- <TableOfContents
-          expanded={930}
-          frontmatter={frontmatter}
-          headings={headings}
-          lang={lang}
-        /> -->
-        <ArticleNav headings={headings} lang={lang} />
-      </div>
-    </div>
-    <Related frontmatter={frontmatter} headings={headings} lang={lang} />
-    <Footer />
-    <script define:vars={{ site_url, site_features }}>
-      window.site_url = site_url;
-      window.site_features = site_features;
-    </script>
-    <script src={SITE.subfolder + '/js/main.js'} type="module" async></script>
-    <Plausible />
-    <script src="//get.octopus.com/js/forms2/js/forms2.min.js" defer></script>
-  </body>
-</html>
+<Layout frontmatter={frontmatter} headings={headings} breadcrumbs={breadcrumbs}>
+  <slot />
+</Layout>
diff --git a/src/layouts/DefaultLegacy.astro b/src/layouts/DefaultLegacy.astro
new file mode 100644
index 0000000000..0221ebdc55
--- /dev/null
+++ b/src/layouts/DefaultLegacy.astro
@@ -0,0 +1,149 @@
+---
+import { Accelerator, PostFiltering } from 'astro-accelerator-utils';
+import type { Frontmatter as OriginalFrontmatter } from 'astro-accelerator-utils/types/Frontmatter';
+import { SITE } from '@config';
+import { getImageInfo } from '@util/custom-markdown.mjs';
+
+// Theme components
+import Head from '@components/HtmlHead.astro';
+import SkipLinks from '@components/SkipLinks.astro';
+import Breadcrumbs from '@components/Breadcrumbs.astro';
+import Navigation from '@components/Navigation.astro';
+import Authors from '@components/Authors.astro';
+import Taxonomy from '@components/Taxonomy.astro';
+
+// Custom components
+import ArticleHeader from '../components/ArticleHeader.astro';
+import ArticleNav from '../components/ArticleNav.astro';
+import Copyright from '../components/Copyright.astro';
+import Header from '../components/Header.astro';
+import Related from '../components/Related.astro';
+import ArticleJourney from '../components/ArticleJourney.astro';
+import Feedback from '../components/Feedback.astro';
+import EditOnGithub from '../components/EditOnGithub.astro';
+import LastUpdated from '../components/LastUpdated.astro';
+import CopyMarkdown from '../components/CopyMarkdown.astro';
+import Plausible from 'src/components/Plausible.astro';
+import Footer from 'src/components/Footer.astro';
+
+// Extend Frontmatter with icon
+type Frontmatter = OriginalFrontmatter & {
+  icon?: string; // Add the icon property
+};
+
+type Props = {
+  frontmatter: Frontmatter;
+  headings: { depth: number; slug: string; text: string }[];
+  breadcrumbs?: { url: string; title: string; ariaCurrent?: string }[] | null;
+};
+const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props;
+
+const lang = frontmatter.lang ?? SITE.default.lang;
+const textDirection = frontmatter.dir ?? SITE.default.dir;
+
+// Logic
+const accelerator = new Accelerator(SITE);
+
+const metaImage = frontmatter.bannerImage
+  ? getImageInfo(frontmatter.bannerImage.src, '', SITE.images.contentSize)
+  : null;
+
+const title = await accelerator.markdown.getInlineHtmlFrom(
+  frontmatter.title ?? SITE.title
+);
+
+const subtitle = frontmatter.subtitle
+  ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.subtitle)
+  : null;
+
+const icon = frontmatter.icon
+  ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.icon)
+  : null;
+
+const site_url = SITE.url;
+const site_features = SITE.featureFlags;
+const search =
+  accelerator.posts.all().filter(PostFiltering.isSearch).shift() ?? null;
+const searchUrl = search && accelerator.urlFormatter.formatAddress(search.url);
+const isSearchPage =
+  accelerator.urlFormatter.formatAddress(Astro.url.pathname) === searchUrl;
+
+const showSearch = !isSearchPage;
+---
+
+<html dir={textDirection} lang={lang} class="initial">
+  <Head frontmatter={frontmatter} headings={headings} lang={lang} />
+  <body data-theme="dark">
+    <SkipLinks frontmatter={frontmatter} headings={headings} lang={lang} />
+    <Header
+      frontmatter={frontmatter}
+      headings={headings}
+      lang={lang}
+      showSearch={showSearch}
+    />
+    <div class="content-group">
+      <main id="site-main">
+        <Breadcrumbs
+          frontmatter={frontmatter}
+          headings={headings}
+          lang={lang}
+          breadcrumbs={breadcrumbs}
+        />
+        <article itemscope itemtype="https://schema.org/Article">
+          <ArticleHeader
+            icon={icon}
+            lang={lang}
+            subtitle={subtitle}
+            title={title}
+          />
+          <div class="page-content anim-show-parent" itemprop="articleBody">
+            <slot />
+            <Feedback
+              frontmatter={frontmatter}
+              headings={headings}
+              lang={lang}
+            />
+            <Authors frontmatter={frontmatter} lang={lang} />
+            <Taxonomy frontmatter={frontmatter} lang={lang} />
+            <LastUpdated
+              frontmatter={frontmatter}
+              headings={headings}
+              lang={lang}
+            />
+            <EditOnGithub
+              frontmatter={frontmatter}
+              headings={headings}
+              lang={lang}
+            />
+            <CopyMarkdown lang={lang} />
+            <ArticleJourney
+              frontmatter={frontmatter}
+              headings={headings}
+              lang={lang}
+            />
+            {metaImage && <meta itemprop="image" content={metaImage.src} />}
+          </div>
+        </article>
+      </main>
+      <Navigation lang={lang} />
+      <div class="side-nav">
+        <!-- <TableOfContents
+          expanded={930}
+          frontmatter={frontmatter}
+          headings={headings}
+          lang={lang}
+        /> -->
+        <ArticleNav headings={headings} lang={lang} />
+      </div>
+    </div>
+    <Related frontmatter={frontmatter} headings={headings} lang={lang} />
+    <Footer />
+    <script define:vars={{ site_url, site_features }}>
+      window.site_url = site_url;
+      window.site_features = site_features;
+    </script>
+    <script src={SITE.subfolder + '/js/main.js'} type="module" async></script>
+    <Plausible />
+    <script src="//get.octopus.com/js/forms2/js/forms2.min.js" defer></script>
+  </body>
+</html>
diff --git a/src/pages/docs.mdx b/src/pages/docs.mdx
index 73e61f42ee..481cf9215f 100644
--- a/src/pages/docs.mdx
+++ b/src/pages/docs.mdx
@@ -1,5 +1,5 @@
 ---
-layout: src/design-system/docs-shell/DocsContentLayout.astro
+layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2024-03-18
 title: Hello, Octopus Deploy! 👋
diff --git a/src/pages/ui-update-sample.mdx b/src/pages/ui-update-sample.mdx
index 5bbe4613ae..373131aadb 100644
--- a/src/pages/ui-update-sample.mdx
+++ b/src/pages/ui-update-sample.mdx
@@ -1,5 +1,5 @@
 ---
-layout: src/design-system/docs-shell/DocsContentLayout.astro
+layout: src/layouts/Default.astro
 pubDate: 2024-05-10
 modDate: 2024-05-10
 title: Tenant variables

From 5ed9df2feb1839eeb76c333bc677e0886141e959 Mon Sep 17 00:00:00 2001
From: Kamil Majkrzak <kamil.majkrzak@octopus.com>
Date: Wed, 27 May 2026 17:59:25 +0200
Subject: [PATCH 4/5] Fix cspell + markdownlint for design-system files

---
 dictionary-octopus.txt      | 12 ++++++++++++
 src/design-system/README.md |  9 ++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index 01adb046a3..e8118af1b8 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -3,6 +3,7 @@ actionid
 actiontemplates
 Adfs
 advfirewall
+affordances
 agentic
 allatclaims
 ALLUSERSPROFILE
@@ -44,6 +45,7 @@ azureaccount
 azureactivedirectory
 azurefile
 bacpac
+behaviour
 Bento
 Blkio
 bootstrap
@@ -191,6 +193,7 @@ gruntfile
 guestloginenabled
 gulpfile
 GZRS
+Hanken
 hasattr
 Hashtable
 hastscript
@@ -282,6 +285,7 @@ maxage
 mdast
 Metabase
 microsite
+microsites
 milli
 minidump
 minifier
@@ -310,6 +314,7 @@ mytransform.config
 namespacing
 Nartac
 navigationid
+navscroll
 NETBIOS
 netcore
 netcoreapp
@@ -341,6 +346,7 @@ npmjs
 NTDS
 NTFS
 NTLM
+nums
 nupkg
 NVARCHAR
 O_WRONLY
@@ -373,6 +379,7 @@ Octostache
 octostorage
 octoterra
 OIDC
+oklab
 oldcert
 oldguid
 oldthumbprint
@@ -490,6 +497,7 @@ serviceaccount
 Sesna
 setspn
 sfproj
+shadcn
 shiki
 showcerts
 Showplan
@@ -527,6 +535,7 @@ struct
 stylesheet
 subcomponent
 subcontext
+sublist
 sunsetting
 swaggerui
 systemprofile
@@ -573,6 +582,7 @@ umoci
 undeployed
 undeploying
 uniquestring
+unlayered
 Unmarshal
 updateprogress
 upgradeavailability
@@ -590,6 +600,7 @@ VARCHAR
 variablename
 variableset
 vhdx
+viewports
 violationreason
 VMSS
 vnet
@@ -612,6 +623,7 @@ windir
 windowsfeatures
 Wireshark
 WIXUI
+wordmark
 workerpool
 workerpools
 workertools
diff --git a/src/design-system/README.md b/src/design-system/README.md
index 85fdac5f09..951516a043 100644
--- a/src/design-system/README.md
+++ b/src/design-system/README.md
@@ -14,7 +14,7 @@ SEO and Core Web Vitals intact on statically generated pages.
 
 ## 1. Anatomy
 
-```
+```text
 src/design-system/
 ├── README.md            ← this file
 ├── tokens.css           ← brand + semantic CSS variables (THE customization surface)
@@ -36,6 +36,7 @@ src/design-system/
 ```
 
 **Two tiers, adopt independently:**
+
 - `tokens.css` + `theme.css` + `ui/` - the universal core. Any Octopus Astro site can use it.
 - `docs-shell/` - opinionated documentation chrome. Take it for docs sites; skip it for
   marketing/app sites and build their own shells on top of the core.
@@ -60,6 +61,7 @@ src/design-system/
    near-zero for a flatter skin, or push them up for more drama. No component edits required.
 
 Components and `theme.css` reference **only the semantic tokens**, never raw hex. So:
+
 - Re-skinning a site = edit `tokens.css`, nothing else.
 - Because every microsite is the *same* Octopus brand, `tokens.css` ports **1:1 unchanged** -
   that is the whole point: copy it verbatim and every site converges on one look. Only fork
@@ -110,7 +112,7 @@ each other).
 them. If you adopt `docs-shell`, the target repo must provide:
 
 | Dependency | Used by | Path in this repo | Notes |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `OctopusLogo.astro` | `DocsHeader.astro` | `public/docs/img/OctopusLogo.astro` | The genuine wordmark+glyph. Import path is `../../../public/docs/img/OctopusLogo.astro` - adjust if your asset lives elsewhere. |
 | Shared `SharedFooter.astro` | `DocsLayout.astro` / `DocsContentLayout.astro` | `src/components/SharedFooter.astro` | Imported as `../../components/SharedFooter.astro` (fetches the shared footer + Marketo form). Swap for the site's own footer if needed. |
 | `footer-bundle.css` | `DocsLayout.astro` `<head>` | `public/docs/css/footer-bundle.css` | Linked by absolute URL `/docs/css/footer-bundle.css`. |
@@ -157,6 +159,7 @@ truth is the `.astro` component, not a CSS file. To keep the DOM traceable we ta
 component's root element with a **`data-component="<FileName>"`** attribute.
 
 Workflow to locate and fix anything:
+
 1. Inspect the element in browser devtools.
 2. Walk up to the nearest `[data-component="X"]`.
 3. Open `src/design-system/**/X.astro` — the Tailwind classes you want to change are right
@@ -213,7 +216,7 @@ These hold by construction; preserve them when extending the system.
 ### Inline-script inventory (all vanilla, all `is:inline`)
 
 | Script | File | Purpose |
-|---|---|---|
+| --- | --- | --- |
 | FOUC theme apply | `docs-shell/DocsLayout.astro` (head) | Set `data-theme` from `localStorage` before paint |
 | Theme toggle | `docs-shell/DocsHeader.astro` | Toggle + persist light/dark |
 | Search | `docs-shell/DocsHeader.astro` renders the real `themes/octopus/components/Search.astro` | The real `search.js` engine (index + scoring + synonyms), re-skinned via `.ds-search` CSS. Not a design-system script. |

From c8d7bd152ff142f453afe323eaaded2d6f3f0601 Mon Sep 17 00:00:00 2001
From: Kamil Majkrzak <kamil.majkrzak@octopus.com>
Date: Wed, 27 May 2026 18:18:18 +0200
Subject: [PATCH 5/5] Fix shared Footer

---
 src/design-system/docs-shell/DocsContentLayout.astro | 2 ++
 src/design-system/docs-shell/DocsHead.astro          | 8 +++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/design-system/docs-shell/DocsContentLayout.astro b/src/design-system/docs-shell/DocsContentLayout.astro
index 87488f78c4..ed0a489fd6 100644
--- a/src/design-system/docs-shell/DocsContentLayout.astro
+++ b/src/design-system/docs-shell/DocsContentLayout.astro
@@ -255,5 +255,7 @@ const sortedTopLevel = pages
     </div>
 
     <SharedFooter />
+    <!-- Marketo library: MarketoForm (in SharedFooter) only renders once MktoForms2 exists. -->
+    <script src="//get.octopus.com/js/forms2/js/forms2.min.js" defer></script>
   </body>
 </html>
diff --git a/src/design-system/docs-shell/DocsHead.astro b/src/design-system/docs-shell/DocsHead.astro
index 08fa1dd6d7..ce38816a47 100644
--- a/src/design-system/docs-shell/DocsHead.astro
+++ b/src/design-system/docs-shell/DocsHead.astro
@@ -5,6 +5,7 @@ import type { Frontmatter } from 'astro-accelerator-utils/types/Frontmatter';
 import { SITE, OPEN_GRAPH, HEADER_SCRIPTS } from '@config';
 import { getEligibleSlugs } from '@util/mdxContent';
 import JsonLd from '@components/JsonLd.astro';
+import { ASSETS, ASSETS_ORIGIN } from 'src/lib/sharedNavbarFooter';
 
 const accelerator = new Accelerator(SITE);
 const stats = new accelerator.statistics('octopus/components/HtmlHead.astro');
@@ -66,7 +67,12 @@ stats.stop();
     href="https://fonts.bunny.net/css?family=bricolage-grotesque:600,700,800|hanken-grotesk:400,500,600,700|jetbrains-mono:400,500&display=swap"
   />
   <link rel="stylesheet" href={SITE.subfolder + '/css/vars.css'} />
-  <link rel="stylesheet" href={SITE.subfolder + '/css/footer-bundle.css'} />
+  <!-- Shared footer/Marketo styles for the fetched SharedFooter (matches HtmlHead;
+       replaces the old footer-bundle.css). main.css is still intentionally omitted. -->
+  <link rel="preconnect" href={ASSETS_ORIGIN} crossorigin />
+  <link rel="stylesheet" href={`${ASSETS}/pu-vars.css`} />
+  <link rel="stylesheet" href={`${ASSETS}/footer-pu-styles.css`} />
+  <link rel="stylesheet" href={`${ASSETS}/marketo-pu-styles.css`} />
   {
     autoMeta('viewport') && (
       <meta