@rxova/brand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan Kruszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+<h1 align="center">@rxova/brand</h1>
+
+<p align="center">
+  Design tokens, Starlight theme and shared site chrome for every
+  <a href="https://rxova.org">rxova.org</a> surface.
+</p>
+
+---
+
+## Why this exists
+
+`rxova.org` serves four surfaces from one origin — an Astro landing at `/`, plus
+[journey](https://github.com/rxova/journey),
+[react-inputs](https://github.com/rxova/react-inputs) and
+[use-everywhere](https://github.com/rxova/use-everywhere) docs, each built in its
+own repo and mounted as a static tree under `/packages/<name>/`.
+
+They were built independently and ended up looking like four unrelated products:
+three different accent colours, three different footers, no way to navigate from
+one project's docs to another's. This package is the single source of truth that
+makes them one site — and it lives in its own repo because it is consumed by four
+and owned by none.
+
+## Install
+
+```sh
+pnpm add @rxova/brand
+```
+
+## Use
+
+### In a Starlight docs site
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import starlight from '@astrojs/starlight'
+import { sharedStarlightConfig } from '@rxova/brand'
+
+export default defineConfig({
+  site: process.env.DOCS_URL ?? 'https://rxova.org',
+  // The aggregator mounts this build under its own path.
+  base: process.env.DOCS_BASE_URL ?? '/',
+  integrations: [
+    starlight(
+      sharedStarlightConfig({
+        project: 'use-everywhere',
+        // Note the nesting: Starlight 0.39 removed `label` + `autogenerate`
+        // as siblings, so an autogenerated group goes inside `items`.
+        sidebar: [{ label: 'Learn', items: [{ autogenerate: { directory: 'learn' } }] }],
+      }),
+    ),
+  ],
+})
+```
+
+That gets you the tokens, the typefaces, the rxova mark linking back to the
+umbrella site, the cross-project switcher, the shared four-column footer, and
+Pagefind search.
+
+### In a plain Astro site
+
+```astro
+---
+import '@rxova/brand/fonts.css'
+import '@rxova/brand/astro.css'
+import SiteFooter from '@rxova/brand/components/SiteFooter.astro'
+import { PROJECTS } from '@rxova/brand'
+---
+```
+
+`astro.css` pulls in `tokens.css` and adds the reset and base element styles
+that Starlight gives docs sites for free.
+
+## What's in it
+
+| Export                            | What it is                                                            |
+| --------------------------------- | --------------------------------------------------------------------- |
+| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`       |
+| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.        |
+| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome  |
+| `@rxova/brand/astro.css`          | For plain Astro sites: tokens, a reset, and base element styling      |
+| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                             |
+| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher` |
+| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                             |
+
+## The palette
+
+A warm monochrome — warm near-black ink on warm paper — with the logo's
+blue → violet → magenta gradient as the **only** chroma in the system. The
+restraint is the identity; resist adding a second accent hue.
+
+The gradient earns exactly two placements: the hairline under the site header,
+and the current-project dot in the switcher.
+
+Neutrals flip between light and dark, so a downstream mapping references a token
+once and gets both modes for free.
+
+## Development
+
+```sh
+pnpm install
+pnpm run verify   # format, lint, tsc, astro check, social cards, package contract
+pnpm run og       # re-render the social cards after a palette or tagline change
+```
+
+There is no build step: Astro resolves `.ts` and `.astro` straight from
+`node_modules` (Starlight ships the same way). That means nothing would catch a
+file missing from `files` or a stale `exports` path, which is what
+`check-exports.mjs` is for — it packs the real tarball and asserts every declared
+subpath resolves.
+
+The social cards are generated from `tokens.css` and `sites.ts`, so they cannot
+drift from the brand — but they are committed, so a palette or tagline change
+silently invalidates them. `check:og` compares a hash of those _inputs_ against
+`scripts/og-manifest.json` rather than re-rendering and diffing the PNGs: resvg
+ships per-platform native builds, and an output diff would fail CI for cards that
+are perfectly correct.
+
+### Trying a change in a consumer
+
+The package has no `workspace:*` shortcut, so iterate through snapshot releases:
+
+1. Add a changeset (`pnpm exec changeset`).
+2. Run the **Snapshot** workflow — publishes `0.x.y-next.N` to the `next` tag.
+3. In the consumer: `pnpm add @rxova/brand@next`.
+
+Slower per iteration than linking, but CI resolves exactly what you resolved, so
+a broken export map fails on your machine rather than three repos later.
+
+## License
+
+MIT © Jonatan Kruszewski

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@rxova/brand",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
+  "keywords": [
+    "rxova",
+    "design-tokens",
+    "astro",
+    "starlight",
+    "theme"
+  ],
+  "license": "MIT",
+  "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
+  "homepage": "https://rxova.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rxova/brand.git"
+  },
+  "bugs": "https://github.com/rxova/brand/issues",
+  "packageManager": "pnpm@11.9.0",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "src",
+    "assets"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tokens.css": "./src/tokens.css",
+    "./astro.css": "./src/astro.css",
+    "./starlight.css": "./src/starlight.css",
+    "./fonts.css": "./src/fonts.css",
+    "./components/*": "./src/components/*",
+    "./assets/*": "./assets/*",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.36.0",
+    "astro": ">=5.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/starlight": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "check:astro": "astro check",
+    "check:exports": "node scripts/check-exports.mjs",
+    "og": "node scripts/generate-og.mjs",
+    "check:og": "node scripts/generate-og.mjs --check",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run check:astro && pnpm run check:og && pnpm run check:exports",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@fontsource/ibm-plex-mono": "^5.2.5",
+    "@fontsource/space-grotesk": "^5.2.5"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@astrojs/starlight": "^0.41.4",
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.29.7",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/js": "^10.0.1",
+    "@resvg/resvg-js": "^2.6.2",
+    "@types/node": "^26.1.1",
+    "astro": "^7.1.3",
+    "eslint": "^10.7.0",
+    "eslint-plugin-astro": "^1.3.0",
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.2.0",
+    "prettier": "^3.9.6",
+    "prettier-plugin-astro": "^0.14.0",
+    "satori": "^0.29.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.65.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,astro,mjs,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,jsonc,css,md,mdx,yaml,yml}": "prettier --write"
+  }
+}

package/src/astro.css

@@ -0,0 +1,85 @@
+/**
+ * Entry point for plain Astro surfaces — today, the rxova.org landing.
+ *
+ * Starlight sites use `starlight.css` instead; it maps the same tokens onto
+ * Starlight's own variables. This file carries what a bare Astro page needs and
+ * Starlight already provides: a reset and base element styling.
+ *
+ * It also aliases the short token names the landing was written against
+ * (`--bg`, `--fg`, `--rule`, …) onto their `--rx-*` equivalents, so adopting
+ * this package did not require rewriting several hundred lines of scoped
+ * component styles in one go. New work should use `--rx-*` directly; the
+ * aliases exist to make the migration incremental, not to be a second API.
+ */
+
+@import './tokens.css';
+
+:root {
+  --bg: var(--rx-bg);
+  --fg: var(--rx-fg);
+  --muted: var(--rx-muted);
+  --faint: var(--rx-faint);
+  --rule: var(--rx-rule);
+  --card: var(--rx-card);
+  --tag-bg: var(--rx-tag-bg);
+  --glow-tint: var(--rx-glow-tint);
+  --font: var(--rx-font-sans);
+  --mono: var(--rx-font-mono);
+  --max: var(--rx-max);
+
+  /* The landing's `--accent` is the foreground, not the brand violet: its
+     design is deliberately monochrome and uses the gradient only as an accent
+     rule. Mapping this to --rx-primary would tint every focus ring on the
+     site. */
+  --accent: var(--rx-fg);
+}
+
+/* --- Reset ---------------------------------------------------------------- */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  scroll-behavior: smooth;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+
+body {
+  position: relative;
+  background: var(--rx-bg);
+  color: var(--rx-fg);
+  font-family: var(--rx-font-sans);
+  font-size: 1.0625rem;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease;
+}
+
+a {
+  color: inherit;
+}
+
+a:focus-visible {
+  outline: 2px solid var(--rx-fg);
+  outline-offset: 3px;
+  border-radius: 2px;
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}

package/src/components/Footer.astro

@@ -0,0 +1,18 @@
+---
+/**
+ * Starlight `Footer` override.
+ *
+ * Keeps everything Starlight puts at the bottom of a doc page — pagination,
+ * "edit this page", last-updated — and adds the shared rxova site footer
+ * beneath it. Replacing rather than wrapping would have cost the pagination,
+ * which is load-bearing navigation on a docs site.
+ */
+import Default from '@astrojs/starlight/components/Footer.astro'
+import SiteFooter from './SiteFooter.astro'
+import { projectFromBase } from '../sites.ts'
+
+const project = projectFromBase(import.meta.env.BASE_URL)
+---
+
+<Default><slot /></Default>
+<SiteFooter project={project} />

package/src/components/ProjectSwitcher.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * Cross-project navigation.
+ *
+ * rxova.org serves four surfaces from one origin, and before this existed there
+ * was no way to get from one project's docs to another's without going back to
+ * the landing. Every href is absolute — a relative one would resolve under the
+ * current site's base path.
+ *
+ * Rendered as a `<details>` so it works with zero JavaScript; the current
+ * project gets the gradient dot (see `.rx-switcher__current` in starlight.css).
+ */
+import { PROJECTS, RXOVA_ORIGIN, type ProjectId } from '../sites.ts'
+
+interface Props {
+  /** Which project this site is, so it can be marked as current. */
+  current?: ProjectId
+}
+
+const { current } = Astro.props
+---
+
+<details class="rx-switcher">
+  <summary class="rx-switcher__trigger" aria-label="Switch project">
+    Projects
+    <svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12">
+      <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" stroke-width="1.75"></path>
+    </svg>
+  </summary>
+  <ul class="rx-switcher__menu">
+    <li><a href={RXOVA_ORIGIN}>rxova.org</a></li>
+    {
+      PROJECTS.map((project) => (
+        <li>
+          <a
+            href={`${RXOVA_ORIGIN}${project.mount}`}
+            class={project.id === current ? 'rx-switcher__current' : undefined}
+            aria-current={project.id === current ? 'page' : undefined}
+          >
+            {project.label}
+          </a>
+        </li>
+      ))
+    }
+  </ul>
+</details>
+
+<style>
+  .rx-switcher__trigger {
+    display: flex;
+    align-items: center;
+    gap: 0.3rem;
+    padding: 0.25rem 0.5rem;
+    border-radius: var(--rx-radius-sm);
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .rx-switcher__trigger::-webkit-details-marker {
+    display: none;
+  }
+
+  .rx-switcher__trigger:hover {
+    color: var(--sl-color-white);
+    background: var(--sl-color-gray-6);
+  }
+
+  .rx-switcher[open] > .rx-switcher__trigger svg {
+    transform: rotate(180deg);
+  }
+
+  .rx-switcher__menu {
+    position: absolute;
+    z-index: var(--sl-z-index-navbar, 20);
+    inset-inline-end: 0;
+    min-width: 12rem;
+    margin: 0.4rem 0 0;
+    padding: 0.35rem;
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: var(--rx-radius);
+    background: var(--sl-color-bg-nav);
+    box-shadow: var(--sl-shadow-md);
+    list-style: none;
+  }
+
+  .rx-switcher__menu a {
+    display: flex;
+    align-items: center;
+    padding: 0.4rem 0.6rem;
+    border-radius: var(--rx-radius-sm);
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+    text-decoration: none;
+  }
+
+  .rx-switcher__menu a:hover {
+    color: var(--sl-color-white);
+    background: var(--sl-color-gray-6);
+  }
+</style>

package/src/components/SiteFooter.astro

@@ -0,0 +1,96 @@
+---
+/**
+ * The four-column rxova footer, shared by all four surfaces.
+ *
+ * Before this, the landing had a single dot-separated link row and the three
+ * docs sites had a bare copyright line (journey went further and hid its footer
+ * links outright). The footer is the second-best place, after the switcher, to
+ * make one origin feel like one site — so it carries the full project list on
+ * every page.
+ *
+ * All cross-project hrefs are absolute; see sites.ts for why.
+ */
+import { PROJECTS, RXOVA_ORIGIN, getProject, siteUrl, type ProjectId } from '../sites.ts'
+
+interface Props {
+  /** Current project, if this is a docs site. Omitted on the landing. */
+  project?: ProjectId
+  /** Optional per-site "Docs" column. */
+  docs?: { label: string; href: string }[]
+}
+
+const { project, docs } = Astro.props
+const self = project ? getProject(project) : undefined
+const year = new Date().getFullYear()
+---
+
+<footer class="rx-footer">
+  <div class="rx-footer__columns">
+    {
+      docs && docs.length > 0 && (
+        <div>
+          <h2 class="rx-footer__title">Docs</h2>
+          <ul class="rx-footer__list">
+            {docs.map((link) => (
+              <li>
+                <a href={link.href}>{link.label}</a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )
+    }
+
+    <div>
+      <h2 class="rx-footer__title">Projects</h2>
+      <ul class="rx-footer__list">
+        <li><a href={RXOVA_ORIGIN}>rxova.org</a></li>
+        {
+          PROJECTS.map((p) => (
+            <li>
+              <a href={`${RXOVA_ORIGIN}${p.mount}`}>{p.label}</a>
+            </li>
+          ))
+        }
+      </ul>
+    </div>
+
+    {
+      self && (
+        <div>
+          <h2 class="rx-footer__title">Community</h2>
+          <ul class="rx-footer__list">
+            <li>
+              <a href={self.repo}>GitHub</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/issues`}>Issues</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/discussions`}>Discussions</a>
+            </li>
+            <li>
+              <a href={self.npm}>npm</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/blob/main/CONTRIBUTING.md`}>Contributing</a>
+            </li>
+          </ul>
+        </div>
+      )
+    }
+
+    <div>
+      <h2 class="rx-footer__title">rxova</h2>
+      <ul class="rx-footer__list">
+        <li><a href={RXOVA_ORIGIN}>Home</a></li>
+        <li><a href="https://github.com/rxova">GitHub org</a></li>
+        <li><a href={siteUrl('/privacy')}>Privacy</a></li>
+        <li><a href={siteUrl('/terms')}>Terms</a></li>
+        <li><a href="mailto:rxova@proton.me">rxova@proton.me</a></li>
+      </ul>
+    </div>
+  </div>
+
+  <p class="rx-footer__legal">© {year} rxova · MIT licensed</p>
+</footer>

package/src/components/SiteTitle.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * Starlight `SiteTitle` override.
+ *
+ * The mark links to rxova.org, not to the local docs home. That is deliberate:
+ * on an aggregated site the mark means "the umbrella", and the wordmark beside
+ * it says which project you are in — and links to that project's docs root.
+ *
+ * The mark's href is absolute because the four surfaces sit at four base paths.
+ * The wordmark uses Starlight's own `siteTitleHref`, which already accounts for
+ * the base and the locale.
+ *
+ * The image is imported from this package rather than read from each site's
+ * `public/`, so adopting the shared chrome does not also mean copying assets
+ * into three repos and keeping them in sync.
+ */
+import mark from '../../assets/rxova-logo-256.png'
+import { RXOVA_ORIGIN } from '../sites.ts'
+
+// Narrowed structurally rather than by declaring an `App.Locals` augmentation
+// here: a consumer site already gets Starlight's own augmentation, and two
+// declarations of the same property would collide at their build time.
+const { siteTitle, siteTitleHref } = (
+  Astro.locals as unknown as {
+    starlightRoute: { siteTitle: string; siteTitleHref: string }
+  }
+).starlightRoute
+---
+
+<div class="rx-site-title">
+  <a href={RXOVA_ORIGIN} class="rx-site-title__mark" aria-label="rxova home">
+    <img src={mark.src} alt="" width="28" height="28" />
+  </a>
+  <span class="rx-site-title__sep" aria-hidden="true"></span>
+  <a href={siteTitleHref} class="rx-site-title__project" translate="no">{siteTitle}</a>
+</div>
+
+<style>
+  /* Visual styling lives in @rxova/brand/starlight.css so the Astro landing can
+     reuse the same classnames without importing this component. */
+  .rx-site-title__mark {
+    display: inline-flex;
+  }
+</style>

package/src/components/SocialIcons.astro

@@ -0,0 +1,19 @@
+---
+/**
+ * Starlight `SocialIcons` override: the stock icons, plus the project switcher.
+ *
+ * Starlight has no dedicated slot in the header's right-hand cluster, and this
+ * is the documented place to add one — it sits immediately before search and
+ * the theme toggle on every page.
+ */
+import Default from '@astrojs/starlight/components/SocialIcons.astro'
+import ProjectSwitcher from './ProjectSwitcher.astro'
+import { projectFromBase } from '../sites.ts'
+
+// Overrides receive no props, so the current project is inferred from the base
+// path the aggregator mounts this site at.
+const current = projectFromBase(import.meta.env.BASE_URL)
+---
+
+<ProjectSwitcher current={current} />
+<Default><slot /></Default>

package/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="astro/client" />
+
+// Deliberately NOT referencing `@astrojs/starlight/locals` for the
+// `Astro.locals.starlightRoute` augmentation: that declaration pulls in
+// Starlight's own `.ts` sources, which import `virtual:starlight/*` modules
+// that only exist inside an Astro build — so plain `tsc` fails on them.
+// The one component that reads route data narrows it structurally instead.

package/src/fonts.css

@@ -0,0 +1,23 @@
+/**
+ * Self-hosted brand typefaces.
+ *
+ * Space Grotesk + IBM Plex Mono came from the journey docs, which was the only
+ * rxova surface with a real typographic identity. They are bundled here rather
+ * than pulled from Google Fonts at runtime: journey's original
+ * `@import url("https://fonts.googleapis.com/...")` sat inside a stylesheet, so
+ * it was a render-blocking third-party request on the critical path (bad LCP),
+ * and it leaked visitor IPs to a third party on an EU-facing site.
+ *
+ * Weights are deliberately narrow — the ones the design system actually uses.
+ * Adding a weight here costs every page on rxova.org, so add only on demand.
+ */
+
+/* Body, headings and UI. */
+@import '@fontsource/space-grotesk/400.css';
+@import '@fontsource/space-grotesk/500.css';
+@import '@fontsource/space-grotesk/600.css';
+@import '@fontsource/space-grotesk/700.css';
+
+/* Code, package names and install snippets. */
+@import '@fontsource/ibm-plex-mono/400.css';
+@import '@fontsource/ibm-plex-mono/500.css';

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @rxova/brand — design tokens, Starlight theme and shared chrome for rxova.org.
+ *
+ * Stylesheets and components are reached through their own subpath exports
+ * (`@rxova/brand/tokens.css`, `@rxova/brand/components/SiteFooter.astro`) so this
+ * entry point stays importable from `astro.config.mjs` under plain Node.
+ */
+
+export {
+  RXOVA_ORIGIN,
+  PROJECTS,
+  getProject,
+  docsUrl,
+  siteUrl,
+  type Project,
+  type ProjectId,
+} from './sites.ts'
+
+export { sharedStarlightConfig, type SharedStarlightOptions } from './starlight.ts'

package/src/sites.ts

@@ -0,0 +1,96 @@
+/**
+ * The rxova.org site map.
+ *
+ * rxova.org is an aggregator: an Astro landing at `/`, plus each project's docs
+ * built in its own repo and mounted as a static tree under `/packages/<name>/`.
+ * That means four surfaces live on one origin at four different base paths, so
+ * **every cross-project link must be absolute**. A relative href would resolve
+ * against the local base and produce `/packages/journey/packages/react-inputs/`.
+ *
+ * This module is imported from `astro.config.mjs` under Node, so it must never
+ * import CSS or a component.
+ */
+
+/** Canonical origin. Override for a staging deploy (e.g. https://web.rxova.org). */
+export const RXOVA_ORIGIN = process.env.RXOVA_ORIGIN ?? 'https://rxova.org'
+
+export type ProjectId = 'journey' | 'react-inputs' | 'use-everywhere'
+
+export interface Project {
+  id: ProjectId
+  /** Display name, used in the header, the switcher and the landing cards. */
+  label: string
+  /** Path the aggregator mounts this project's docs at. Leading and trailing slash. */
+  mount: `/${string}/`
+  tagline: string
+  repo: string
+  /** The package a newcomer should install first. */
+  npm: string
+  /** npm package names, most prominent first. */
+  packages: string[]
+}
+
+export const PROJECTS: readonly Project[] = [
+  {
+    id: 'journey',
+    label: 'Journey',
+    mount: '/packages/journey/',
+    tagline: 'Declarative journey graphs for non-linear UI flows.',
+    repo: 'https://github.com/rxova/journey',
+    npm: 'https://www.npmjs.com/package/@rxova/journey-core',
+    packages: ['@rxova/journey-core', '@rxova/journey-react', '@rxova/journey-devtools-bridge'],
+  },
+  {
+    id: 'react-inputs',
+    label: 'react-inputs',
+    mount: '/packages/react-inputs/',
+    tagline: 'The tricky React inputs, done right.',
+    repo: 'https://github.com/rxova/react-inputs',
+    npm: 'https://www.npmjs.com/package/@rxova/react-inputs',
+    packages: [
+      '@rxova/react-inputs',
+      '@rxova/react-intl-currency-input',
+      '@rxova/react-otp-input',
+      '@rxova/react-rating-input',
+    ],
+  },
+  {
+    id: 'use-everywhere',
+    label: 'use-everywhere',
+    mount: '/packages/use-everywhere/',
+    tagline: 'State and messages that exist in every tab, window, and worker.',
+    repo: 'https://github.com/rxova/use-everywhere',
+    npm: 'https://www.npmjs.com/package/use-everywhere',
+    packages: ['use-everywhere', '@use-everywhere/core'],
+  },
+] as const
+
+export function getProject(id: ProjectId): Project {
+  const project = PROJECTS.find((p) => p.id === id)
+  if (!project) throw new Error(`[@rxova/brand] unknown project id: ${id}`)
+  return project
+}
+
+/** Absolute URL to a project's docs root. */
+export function docsUrl(id: ProjectId): string {
+  return `${RXOVA_ORIGIN}${getProject(id).mount}`
+}
+
+/** Absolute URL to a path on the umbrella site, e.g. `/privacy`. */
+export function siteUrl(path = '/'): string {
+  return `${RXOVA_ORIGIN}${path.startsWith('/') ? path : `/${path}`}`
+}
+
+/**
+ * Which project a page belongs to, inferred from Astro's `BASE_URL`.
+ *
+ * Component overrides can't be given props, so the shared chrome works this out
+ * for itself rather than making every repo declare it twice (once in the
+ * Starlight config, once in the override). Returns `undefined` on a standalone
+ * build where the base is `/` and there is nothing to infer from — the current
+ * marker is simply omitted, which is correct off the aggregator.
+ */
+export function projectFromBase(base: string): ProjectId | undefined {
+  const normalised = base.endsWith('/') ? base : `${base}/`
+  return PROJECTS.find((p) => p.mount === normalised)?.id
+}

package/src/starlight.css

@@ -0,0 +1,183 @@
+/**
+ * Maps rxova tokens onto Starlight's theme variables.
+ *
+ * Load this from a Starlight site's `customCss`, which Astro appends after
+ * Starlight's own stylesheets — so these declarations win without !important.
+ *
+ * Every --rx-* neutral already flips between light and dark (see tokens.css),
+ * which is why one mapping block covers both modes. Starlight's own defaults
+ * are dark-in-:root / light-in-[data-theme='light']; we don't need that split
+ * because its inline head script always stamps an explicit data-theme before
+ * first paint.
+ *
+ * Starlight's gray ramp runs 1 (highest contrast) -> 7 (lowest), which is the
+ * same direction as our text -> surface ladder, so the mapping is monotonic in
+ * both modes.
+ */
+
+@import './tokens.css';
+
+:root {
+  /* Accent. */
+  --sl-color-accent: var(--rx-primary);
+  --sl-color-accent-low: color-mix(in srgb, var(--rx-primary) 20%, var(--rx-bg));
+  --sl-color-accent-high: var(--rx-primary-lightest);
+  --sl-color-text-accent: var(--rx-primary);
+
+  /* Neutral ladder. "white" and "black" are Starlight's names for the two
+     contrast extremes, not literal colours — they invert with the theme. */
+  --sl-color-white: var(--rx-fg);
+  --sl-color-gray-1: var(--rx-fg);
+  --sl-color-gray-2: var(--rx-muted);
+  --sl-color-gray-3: var(--rx-faint);
+  --sl-color-gray-4: var(--rx-rule-strong);
+  --sl-color-gray-5: var(--rx-rule);
+  --sl-color-gray-6: var(--rx-tag-bg);
+  --sl-color-gray-7: var(--rx-card);
+  --sl-color-black: var(--rx-bg);
+
+  /* Surfaces. Nav and sidebar sit flush with the page — the hairline does the
+     separating, not a fill change. */
+  --sl-color-bg: var(--rx-bg);
+  --sl-color-bg-nav: var(--rx-bg);
+  --sl-color-bg-sidebar: var(--rx-bg);
+  --sl-color-bg-inline-code: var(--rx-tag-bg);
+  --sl-color-bg-badge: var(--rx-tag-bg);
+
+  --sl-color-hairline: var(--rx-rule);
+  --sl-color-hairline-light: var(--rx-rule);
+  --sl-color-hairline-shade: var(--rx-rule-strong);
+  --sl-color-backdrop-overlay: color-mix(in srgb, var(--rx-bg) 80%, transparent);
+
+  /* Type. */
+  --sl-font: var(--rx-font-sans);
+  --sl-font-mono: var(--rx-font-mono);
+
+  --sl-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
+  --sl-shadow-md: 0 4px 12px -4px rgb(0 0 0 / 0.12);
+  --sl-shadow-lg: var(--rx-shadow-soft);
+}
+
+/* Starlight ships a slightly cooler focus ring; align it with the accent. */
+:root {
+  --sl-color-focus: var(--rx-primary);
+}
+
+/* --- Shared chrome ------------------------------------------------------- */
+
+/* The gradient is the brand's only chroma, so it earns exactly two placements:
+   the hairline under the site header, and the current-project dot in the
+   project switcher. Adding a third dilutes both. */
+.site-title::after {
+  content: none;
+}
+
+header.header {
+  border-bottom: 1px solid var(--sl-color-hairline);
+  background: var(--sl-color-bg-nav);
+}
+
+/* Site title: the rxova mark sits beside the project wordmark. */
+.rx-site-title {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  color: var(--rx-fg);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  text-decoration: none;
+}
+
+.rx-site-title a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.rx-site-title a:hover {
+  color: var(--rx-fg);
+}
+
+.rx-site-title img {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--rx-radius-sm);
+}
+
+.rx-site-title__sep {
+  width: 1px;
+  height: 1.1rem;
+  background: var(--rx-rule-strong);
+}
+
+.rx-site-title__project {
+  color: var(--rx-muted);
+  font-weight: 500;
+}
+
+/* Project switcher. */
+.rx-switcher {
+  position: relative;
+}
+
+.rx-switcher__current::before {
+  content: '';
+  display: inline-block;
+  width: 0.5rem;
+  height: 0.5rem;
+  margin-inline-end: 0.5rem;
+  border-radius: var(--rx-radius-pill);
+  background: var(--rx-gradient);
+}
+
+/* --- Footer -------------------------------------------------------------- */
+
+.rx-footer {
+  margin-top: 4rem;
+  padding: 2.5rem 0 2rem;
+  border-top: 1px solid var(--rx-rule);
+  color: var(--rx-muted);
+  font-size: 0.875rem;
+}
+
+.rx-footer__columns {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr));
+  gap: 2rem;
+}
+
+.rx-footer__title {
+  margin-bottom: 0.75rem;
+  color: var(--rx-fg);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.rx-footer__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.45rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rx-footer__list a {
+  color: var(--rx-muted);
+  text-decoration: none;
+}
+
+.rx-footer__list a:hover {
+  color: var(--rx-fg);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.rx-footer__legal {
+  margin-top: 2.5rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--rx-rule);
+  color: var(--rx-faint);
+  font-size: 0.8125rem;
+}

package/src/starlight.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared Starlight configuration for the rxova docs sites.
+ *
+ * Each project's `astro.config.mjs` supplies only what is genuinely its own —
+ * its sidebar, its extra plugins — and spreads the rest from here, so the three
+ * doc sites cannot drift apart in the ways that made them feel like three
+ * unrelated products.
+ *
+ * Imported from `astro.config.mjs` under Node: no CSS, no component imports.
+ *
+ * The return type is structural rather than Starlight's own `StarlightUserConfig`.
+ * Spreading into `starlight({ ... })` still type-checks the merged object at the
+ * call site, and this way a Starlight minor release cannot break every consumer
+ * at once over a type-only change.
+ */
+
+import { RXOVA_ORIGIN, getProject, type ProjectId } from './sites.ts'
+
+export interface SharedStarlightOptions {
+  /** Which project's docs this site is. */
+  project: ProjectId
+  /** Starlight sidebar config — the one thing every site defines itself. */
+  sidebar: unknown[]
+  /** Extra stylesheets, appended after the brand ones so they win. */
+  customCss?: string[]
+  /** Extra Starlight component overrides, merged over the shared ones. */
+  components?: Record<string, string>
+  /** Path under the repo root that holds the docs site, for the edit link. */
+  editLinkBase?: string
+}
+
+export function sharedStarlightConfig({
+  project,
+  sidebar,
+  customCss = [],
+  components = {},
+  editLinkBase = 'apps/docs',
+}: SharedStarlightOptions) {
+  const self = getProject(project)
+
+  return {
+    title: self.label,
+    description: self.tagline,
+    // One origin, one tab icon. Each site must have this file in `public/` —
+    // Starlight resolves `favicon` against the site's own static directory, so
+    // it cannot come from this package.
+    favicon: '/favicon.svg',
+
+    // No `logo` here on purpose: the SiteTitle override renders the mark from
+    // this package's own assets, so adopting the shared chrome does not also
+    // mean copying an image into three repos and keeping it in sync.
+
+    social: [
+      { icon: 'github' as const, label: 'GitHub', href: self.repo },
+      { icon: 'npm' as const, label: 'npm', href: self.npm },
+    ],
+
+    editLink: {
+      baseUrl: `${self.repo}/edit/main/${editLinkBase}/`,
+    },
+
+    // Order matters: fonts, then tokens+mapping, then per-site overrides.
+    customCss: ['@rxova/brand/fonts.css', '@rxova/brand/starlight.css', ...customCss],
+
+    components: {
+      // The rxova mark + project wordmark, with the mark linking back to the
+      // umbrella site. This is the only "you are inside rxova.org" affordance
+      // on a docs page, so it ships shared rather than per-repo.
+      SiteTitle: '@rxova/brand/components/SiteTitle.astro',
+      // Appends the cross-project switcher to the social icons. Without it the
+      // three docs sites are three islands under one domain.
+      SocialIcons: '@rxova/brand/components/SocialIcons.astro',
+      // Starlight's default footer (pagination, edit link, last updated) plus
+      // the shared four-column site footer beneath it.
+      Footer: '@rxova/brand/components/Footer.astro',
+      ...components,
+    },
+
+    head: [
+      {
+        tag: 'meta' as const,
+        attrs: { property: 'og:image', content: `${RXOVA_ORIGIN}/og/${project}.png` },
+      },
+      {
+        tag: 'meta' as const,
+        attrs: { name: 'twitter:card', content: 'summary_large_image' },
+      },
+    ],
+
+    // Pagefind ships with Starlight and replaces the third-party search plugin
+    // journey was carrying.
+    pagefind: true,
+
+    sidebar,
+  }
+}

package/src/tokens.css

@@ -0,0 +1,119 @@
+/**
+ * rxova design tokens — the single source of truth for every rxova.org surface.
+ *
+ * Seeded from the original landing page (rxova-website/site/src/styles/global.css),
+ * which was the de-facto brand before this package existed.
+ *
+ * The palette is a warm monochrome: warm near-black ink on warm paper, with the
+ * logo's blue -> violet -> magenta gradient as the ONLY chroma in the system.
+ * Resist adding a second accent hue — the restraint is the identity.
+ *
+ * Every neutral flips between light and dark, so downstream mappings (see
+ * starlight.css) can reference a token once and get both modes for free.
+ */
+
+:root,
+:root[data-theme='light'] {
+  color-scheme: light;
+
+  /* Surfaces, ordered background -> foreground. */
+  --rx-bg: #ffffff;
+  --rx-card: #fbfaf7;
+  --rx-tag-bg: #f0ede6;
+  --rx-rule: #e7e3db;
+  --rx-rule-strong: #d5d0c6;
+
+  /* Text, ordered faintest -> strongest. */
+  --rx-faint: #8b867c;
+  --rx-muted: #605c54;
+  --rx-fg: #14140f;
+
+  /* Accent ramp: the gradient's violet mid-stop, for links and focus. */
+  --rx-primary: #6b3df0;
+  --rx-primary-dark: #5a2fd6;
+  --rx-primary-darker: #4a27b8;
+  --rx-primary-darkest: #3c1f96;
+  --rx-primary-light: #8159f3;
+  --rx-primary-lighter: #9375f5;
+  --rx-primary-lightest: #b7a3f9;
+
+  --rx-glow-tint: rgb(107 61 240 / 0.14);
+  --rx-shadow-soft: 0 20px 60px -30px rgb(107 61 240 / 0.35);
+}
+
+:root[data-theme='dark'] {
+  color-scheme: dark;
+
+  --rx-bg: #100f0d;
+  --rx-card: #17150f;
+  --rx-tag-bg: #201e18;
+  --rx-rule: #262420;
+  --rx-rule-strong: #3b3830;
+
+  --rx-faint: #7b766c;
+  --rx-muted: #a8a294;
+  --rx-fg: #f2efe8;
+
+  /* Lightened so the accent keeps AA contrast on a dark surface. */
+  --rx-primary: #9375f5;
+  --rx-primary-dark: #8159f3;
+  --rx-primary-darker: #6b3df0;
+  --rx-primary-darkest: #5a2fd6;
+  --rx-primary-light: #b7a3f9;
+  --rx-primary-lighter: #cbbcfb;
+  --rx-primary-lightest: #e0d7fd;
+
+  --rx-glow-tint: rgb(242 239 232 / 0.06);
+  --rx-shadow-soft: 0 20px 60px -30px rgb(0 0 0 / 0.6);
+}
+
+/* OS preference wins only when no explicit choice has been stored. */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    color-scheme: dark;
+
+    --rx-bg: #100f0d;
+    --rx-card: #17150f;
+    --rx-tag-bg: #201e18;
+    --rx-rule: #262420;
+    --rx-rule-strong: #3b3830;
+
+    --rx-faint: #7b766c;
+    --rx-muted: #a8a294;
+    --rx-fg: #f2efe8;
+
+    --rx-primary: #9375f5;
+    --rx-primary-dark: #8159f3;
+    --rx-primary-darker: #6b3df0;
+    --rx-primary-darkest: #5a2fd6;
+    --rx-primary-light: #b7a3f9;
+    --rx-primary-lighter: #cbbcfb;
+    --rx-primary-lightest: #e0d7fd;
+
+    --rx-glow-tint: rgb(242 239 232 / 0.06);
+    --rx-shadow-soft: 0 20px 60px -30px rgb(0 0 0 / 0.6);
+  }
+}
+
+/* Mode-independent tokens. */
+:root {
+  /* The logo gradient. Use it for rules, hero accents and the switcher dot —
+     never for body text, where it cannot meet a contrast ratio. */
+  --rx-accent-a: #0a84ff;
+  --rx-accent-b: #6b3df0;
+  --rx-accent-c: #e6199b;
+  --rx-gradient: linear-gradient(90deg, var(--rx-accent-a), var(--rx-accent-b), var(--rx-accent-c));
+
+  --rx-font-sans:
+    'Space Grotesk', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --rx-font-mono:
+    'IBM Plex Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+
+  --rx-radius: 12px;
+  --rx-radius-sm: 6px;
+  --rx-radius-pill: 999px;
+
+  /* Prose measure for the landing; wider bound for marketing sections. */
+  --rx-max: 44rem;
+  --rx-max-wide: 72rem;
+}