feat: redesign shared documentation theme

.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "example-docs",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["--dir", "example", "dev"],
+      "port": 4321
+    },
+    {
+      "name": "nextjs-docs-site",
+      "runtimeExecutable": "/Users/Apple/Desktop/xberg-enteripse-repos/docs-site/node_modules/.bin/next",
+      "runtimeArgs": ["dev", "--turbopack", "/Users/Apple/Desktop/xberg-enteripse-repos/docs-site"],
+      "autoPort": true
+    }
+  ]
+}

README.md

@@ -1,9 +1,10 @@
 # @xberg-io/docs-theme
 
 Shared [Astro Starlight](https://starlight.astro.build) theme for xberg.io documentation sites.
-One versioned package carries the brand — navy/cyan/blue/purple palette, Exo 2, CDN logos and
-favicons, canonical Google Analytics, Open Graph defaults, and `llms.txt` generation — so every
-repo's docs stay consistent without copying assets around.
+One versioned package carries the Kreuzberg Cloud documentation system — warm cream/deep-purple
+surfaces, teal accents, Geist typography, square rule-bound components, CDN assets, analytics,
+Open Graph defaults, and `llms.txt` generation — so every repo stays consistent without copying
+the presentation layer around.
 
 ## Install
 
@@ -58,15 +59,15 @@ in the brand stylesheet, the CDN logo (`SiteTitle` override), and the favicon/OG
 
 | Option              | Default                                   | Notes                                             |
 | ------------------- | ----------------------------------------- | ------------------------------------------------- |
-| `title` (required)  | —                                         | Tab title + nav logo `aria-label`.                |
+| `title` (required)  | —                                         | Tab title + product name beside the nav icon.     |
 | `description`       | —                                         | Meta / social description.                        |
 | `githubUrl`         | —                                         | Drives the default GitHub social link.            |
 | `editBaseUrl`       | —                                         | `editLink.baseUrl`.                               |
 | `ogImage`           | shared OG card on jsDelivr                 | OG/Twitter image URL.                             |
 | `googleAnalyticsId` | `G-8G4NQW55PF`                            | Canonical shared GA4 property.                    |
 | `googleAdsId`       | `AW-17853694443`                          | Canonical shared Ads account.                     |
 | `sidebar`           | —                                         | Starlight sidebar.                                |
-| `social`            | GitHub from `githubUrl` + shared r/xberg   | Starlight social links.                           |
+| `social`            | GitHub + shared Discord + shared r/xberg   | Starlight social links.                           |
 | `plugins`           | `[]`                                      | Starlight plugin instances, e.g. `starlightLlmsTxt()`. |
 | `head` / `customCss` / `components` | —                         | Appended/merged after the theme's own.            |
 | `starlight`         | —                                         | Escape hatch for extra Starlight config.          |

example/src/content/docs/get-started/introduction.md

@@ -9,7 +9,7 @@ supplies everything else.
 
 ## What you get
 
-- Navy/cyan/blue/purple palette with Exo 2, in both light and dark mode.
+- Cream/deep-purple surfaces with Geist and Geist Mono, in both light and dark mode.
 - Nav logo, favicon, and OG image pulled from the `xberg-io/assets` CDN.
 - Canonical Google Analytics + Ads tags.
 - `llms.txt` generation via `starlight-llms-txt`.

example/src/content/docs/index.mdx

@@ -1,60 +1,77 @@
 ---
 title: xberg.io docs theme
-description: Live preview of the shared @xberg-io/docs-theme.
+description: The shared documentation system for xberg.io products.
 template: splash
-hero:
-  tagline: >-
-    One versioned Starlight theme for every xberg.io documentation site — brand palette, logos,
-    analytics, and llms.txt, baked in.
-  image:
-    file: ../../assets/hero.svg
-  actions:
-    - text: Get started
-      link: /get-started/introduction/
-      icon: right-arrow
-      variant: primary
-    - text: View on GitHub
-      link: https://github.com/xberg-io/docs-theme
-      icon: external
-      variant: minimal
+pagefind: false
 ---
 
-import { Card, CardGrid, LinkCard, Tabs, TabItem, Code } from "@astrojs/starlight/components";
+<div className="xb-landing">
+  <section className="xb-landing-hero">
+    <div className="xb-landing-copy">
+      <p className="xb-eyebrow">xberg documentation system</p>
+      <h1>Documentation that feels like part of the <em>product.</em></h1>
+      <p className="xb-lede">
+        One precise, reusable theme for every xberg product. Designed for fast reading,
+        effortless navigation, and technical ideas that deserve clarity.
+      </p>
+      <div className="xb-actions">
+        <a className="xb-button xb-button-primary" href="/get-started/introduction/">Start building <span aria-hidden="true">→</span></a>
+        <a className="xb-button" href="https://github.com/xberg-io/docs-theme">View source <span aria-hidden="true">↗</span></a>
+      </div>
+    </div>
+  </section>
 
-This page exists to exercise the theme: hero, cards, tabs, admonitions, tables, and code blocks —
-all styled by `@xberg-io/docs-theme`.
+  <section className="xb-proof" aria-label="Theme highlights">
+    <div><strong>01</strong><span>shared package</span></div>
+    <div><strong>100%</strong><span>Astro native</span></div>
+    <div><strong>0</strong><span>runtime dependencies</span></div>
+    <div><strong>∞</strong><span>product docs</span></div>
+  </section>
 
-## Why the shared theme
+  <section className="xb-landing-section">
+    <div className="xb-section-heading">
+      <p className="xb-eyebrow">Designed as a system</p>
+      <h2>Everything your documentation needs. <span className="xb-gradient-text">Nothing it doesn’t.</span></h2>
+      <p>From the first navigation click to the last code sample, every surface follows the same visual language.</p>
+    </div>
 
-<CardGrid>
-	<Card title="One source of truth" icon="star">
-		Brand colors, fonts, logos, favicon, OG, and analytics live in one package — no per-repo copies.
-	</Card>
-	<Card title="Frictionless install" icon="rocket">
-		`pnpm add @xberg-io/docs-theme`. Contributors just `pnpm install` — the theme resolves, no auth.
-	</Card>
-	<Card title="llms.txt for free" icon="open-book">
-		`starlight-llms-txt` ships with the theme, so every site emits `llms.txt` out of the box.
-	</Card>
-	<Card title="Astro-native" icon="setting">
-		Pure Starlight + `.astro`/CSS source. Nothing to compile; semver bumps flow via Renovate.
-	</Card>
-</CardGrid>
+    <div className="xb-feature-grid">
+      <article className="xb-feature xb-feature-wide">
+        <div>
+          <h3>A single source of truth</h3>
+          <p>Typography, color, navigation, content components, metadata, analytics, and assets stay aligned across every product.</p>
+        </div>
+      </article>
+      <article className="xb-feature">
+        <div>
+          <h3>Built for reading</h3>
+          <p>Strong hierarchy, restrained line lengths, and clear wayfinding keep complex technical material approachable.</p>
+        </div>
+      </article>
+      <article className="xb-feature">
+        <div>
+          <h3>Brand by default</h3>
+          <p>Install once. Every page inherits the xberg visual language without copying styles or assets between repositories.</p>
+        </div>
+      </article>
+    </div>
+  </section>
 
-## Add it to a site
+  <section className="xb-workflow">
+    <div className="xb-section-heading">
+      <p className="xb-eyebrow">From zero to documented</p>
+      <h2>A clear path to a <span className="xb-gradient-text">coherent result.</span></h2>
+    </div>
+    <ol>
+      <li><div><h3>Install</h3><code>pnpm add @xberg-io/docs-theme</code></div></li>
+      <li><div><h3>Configure</h3><p>Add the product title, repository, and navigation.</p></div></li>
+      <li><div><h3>Write</h3><p>Focus on the documentation. The system handles presentation.</p></div></li>
+    </ol>
+  </section>
 
-<Tabs syncKey="pm">
-	<TabItem label="pnpm">
-		<Code code={`pnpm add @xberg-io/docs-theme @astrojs/starlight astro`} lang="sh" />
-	</TabItem>
-	<TabItem label="npm">
-		<Code code={`npm install @xberg-io/docs-theme @astrojs/starlight astro`} lang="sh" />
-	</TabItem>
-</Tabs>
-
-## Explore
-
-<CardGrid>
-	<LinkCard title="Introduction" href="/get-started/introduction/" description="What the theme provides and how to wire it up." />
-	<LinkCard title="Components demo" href="/guides/components/" description="Admonitions, tabs, tables, and code, themed." />
-</CardGrid>
+  <section className="xb-landing-cta">
+    <p className="xb-eyebrow">Make it yours</p>
+    <h2>Build documentation people <span className="xb-gradient-text">actually want to use.</span></h2>
+    <a className="xb-button xb-button-primary" href="/get-started/introduction/">Read the introduction <span aria-hidden="true">→</span></a>
+  </section>
+</div>

index.d.ts

@@ -6,7 +6,7 @@ export interface XbergStarlightOptions {
   title: string;
   /** Meta description / default social description. */
   description?: string;
-  /** GitHub repo URL — drives the default GitHub social link (alongside the shared r/xberg link). */
+  /** GitHub repo URL — drives the default GitHub social link alongside Discord and Reddit. */
   githubUrl?: string;
   /** `editLink.baseUrl`, e.g. `https://github.com/xberg-io/<repo>/edit/main/docs-site/`. */
   editBaseUrl?: string;
@@ -18,7 +18,7 @@ export interface XbergStarlightOptions {
   googleAdsId?: string;
   /** Starlight sidebar config. */
   sidebar?: StarlightUserConfig["sidebar"];
-  /** Starlight social links. Defaults to a GitHub link from `githubUrl` plus the shared r/xberg link. */
+  /** Starlight social links. Defaults to GitHub plus the shared xberg Discord and Reddit communities. */
   social?: StarlightUserConfig["social"];
   /**
    * Starlight plugins, e.g. `starlightLlmsTxt()`. Import them in your own config
@@ -29,7 +29,7 @@ export interface XbergStarlightOptions {
   head?: StarlightUserConfig["head"];
   /** Extra `customCss` entries, appended after the brand stylesheet. */
   customCss?: string[];
-  /** Extra component overrides, merged over the theme's (theme wins on conflict keys it sets). */
+  /** Extra component overrides, merged after the theme's defaults (consumer overrides win). */
   components?: StarlightUserConfig["components"];
   /** Escape hatch: arbitrary extra Starlight config (branding keys are locked). */
   starlight?: Partial<StarlightUserConfig>;

index.mjs

@@ -8,6 +8,7 @@ const DEFAULT_GA_ID = "G-8G4NQW55PF";
 const DEFAULT_ADS_ID = "AW-17853694443";
 const DEFAULT_OG_IMAGE = `${CDN}/social/open-graph-card.png`;
 const REDDIT_URL = "https://www.reddit.com/r/xberg/";
+const DISCORD_URL = "https://discord.gg/xt9WY3GnKR";
 
 /** @param {string | undefined} gaId @param {string | undefined} adsId */
 function analyticsHead(gaId, adsId) {
@@ -45,8 +46,8 @@ function socialHead(ogImage) {
 }
 
 /**
- * Build a Starlight config carrying the shared xberg.io brand: navy/cyan/blue/purple
- * palette, Exo 2, CDN logos/favicons, canonical Google Analytics, and OG defaults.
+ * Build a Starlight config carrying the shared xberg.io brand: cream/deep-purple
+ * surfaces, Geist typography, CDN logos/favicons, canonical analytics, and OG defaults.
  * Wrap the result with `starlight()` in your `astro.config`:
  *
  * ```js
@@ -91,6 +92,7 @@ export function xbergStarlightConfig(options) {
 
   const defaultSocial = [
     ...(githubUrl ? [{ icon: "github", label: "GitHub", href: githubUrl }] : []),
+    { icon: "discord", label: "Discord", href: DISCORD_URL },
     { icon: "reddit", label: "Reddit", href: REDDIT_URL },
   ];
   const resolvedSocial = social ?? defaultSocial;

src/components/SiteTitle.astro

@@ -1,15 +1,9 @@
 ---
-// Nav logo override: renders the shared xberg wordmark from the assets CDN,
-// with light/dark variants toggled by CSS in brand.css. Sidesteps Astro's
-// image pipeline so the logo needs no local file in each consuming repo.
-import type { Props } from "@astrojs/starlight/props";
-
 const CDN = "https://cdn.jsdelivr.net/gh/xberg-io/assets@v1.0.0/docs";
-const href = import.meta.env.BASE_URL || "/";
-const label = Astro.props.siteTitle;
+const { siteTitle: label, siteTitleHref: href } = Astro.locals.starlightRoute;
 ---
 
-<a href={href} class="site-title xb-site-title sl-flex" aria-label={label}>
-  <img class="xb-logo xb-logo-dark" alt={label} src={`${CDN}/navbar-logo-dark.svg`} />
-  <img class="xb-logo xb-logo-light" alt={label} src={`${CDN}/navbar-logo-light.svg`} />
+<a href={href} class="site-title xb-site-title" aria-label={label}>
+  <img class="xb-logo" alt="" src={`${CDN}/app-icon.svg`} />
+  <span class="xb-product-name">{label}</span>
 </a>