An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): add new themes and use generated theme registry (#2042)
Cindy Zhang811bc9e7f466
diff --git a/apps/docsite/README.md b/apps/docsite/README.mdnew file mode 100644index 0000000000..93ed5a0be4--- /dev/null+++ b/apps/docsite/README.md@@ -0,0 +1,119 @@+# XDS Docsite++The OSS documentation site for XDS. Built with Next.js and StyleX.++## Quick Start++```bash+yarn install # from repo root+yarn build # build all packages (themes need built exports)+cd apps/docsite+yarn generate # extract data from the monorepo into src/generated/+yarn dev # start the dev server+```++`yarn dev` and `yarn build` both run `generate` automatically via `predev`/`prebuild` scripts.++## How It Works++The docsite never hardcodes package lists, component catalogs, or theme maps.+Everything flows through a build-time **data pipeline** that extracts information+from the monorepo and writes typed TypeScript registries to `src/generated/`.++### The Pipeline++`scripts/generate-data.mjs` scans the monorepo and produces:++| Registry | Source | What it contains |+| ---------------------- | --------------------------------- | ------------------------------------------------------------- |+| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |+| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups — per package |+| `blockRegistry.ts` | CLI `templates/blocks/` | Showcase and example blocks with metadata |+| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |+| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |+| `themeRegistry.ts` | Installed `@xds/theme-*` packages | Built theme objects, keyed by package name |+| `showcaseRegistry.ts` | Blocks with `isShowcase` | Copied showcase source files |+| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |++The `src/generated/` directory is gitignored. Pages import from these registries+and render whatever the pipeline found — no manual wiring needed.++### The Rule++**All data comes from the pipeline. Never hardcode package names, component+lists, or theme objects in page code.** If you need data about the monorepo,+add it to `generate-data.mjs` and consume it from a registry.++This means:++- No `import {fooTheme} from '@xds/theme-foo/built'` in page files — use `themeObjects` from the generated `themeRegistry`+- No hand-maintained arrays of component names — use `componentRegistry`+- No `if (pkg === '@xds/core')` switches — let the pipeline classify packages++## Adding a New Theme++1. Create the theme package under `packages/themes/<name>/`+2. Add `"@xds/theme-<name>": "*"` to `apps/docsite/package.json` dependencies+3. Add `@import "@xds/theme-<name>/theme.css"` to `src/app/globals.css`+4. Load the theme's fonts (see below)+5. Run `yarn generate` — the theme appears in `themeRegistry.ts`, `packageRegistry.ts`, the sidebar, craft page, and package detail page automatically++> Only add **public** (non-private) theme packages to the docsite.++### Font loading++Themes reference fonts by name but don't bundle the font files. If the fonts+aren't loaded, the theme silently falls back to system fonts.++The docsite loads all custom typefaces from Google Fonts via a single `<link>`+tag in `src/app/layout.tsx`. When adding a new theme, check which fonts it+declares and add any missing families to that URL.++Each theme's own README documents exactly which fonts it needs and how to load+them. Check the theme's `## Fonts` section for the specific Google Fonts URL.++## Adding a New Package++1. Create the package under `packages/<name>/`+2. Add `"@xds/<name>": "*"` to `apps/docsite/package.json` dependencies+3. Run `yarn generate`++The package appears in the sidebar, the libraries section, and gets its own+`/packages/<name>` detail page. If the package contains `.doc.mjs` files,+its components are extracted into `componentRegistry.ts` as well.++## Project Structure++```+apps/docsite/+├── scripts/+│ └── generate-data.mjs # The data pipeline+├── src/+│ ├── generated/ # gitignored — pipeline output+│ ├── app/+│ │ ├── globals.css # CSS imports (reset, xds base, theme stylesheets)+│ │ ├── layout.tsx # Root layout+│ │ ├── providers.tsx # XDSTheme + client providers+│ │ ├── (docs)/ # Main docs routes (components, packages, docs)+│ │ └── craft/ # Craft landing (templates, themes, showcases)+│ └── components/ # Shared UI components+├── package.json+└── .gitignore # Excludes src/generated/+```++## Commands++| Command | What it does |+| ----------------- | ----------------------------------------------- |+| `yarn generate` | Run the data pipeline |+| `yarn dev` | Start Next.js dev server (auto-generates first) |+| `yarn build` | Production build (auto-generates first) |+| `yarn typecheck` | Run `tsc --noEmit` |+| `yarn test` | Run vitest |+| `yarn test:watch` | Run vitest in watch mode |++## Testing++Tests live in `src/__tests__/data-extraction.test.ts` and validate the generated+registries — package discovery, component extraction, theme wiring, etc. Run+`yarn generate` before running tests since they import from `src/generated/`.diff --git a/apps/docsite/package.json b/apps/docsite/package.jsonindex 3cd5088551..66c8227490 100644--- a/apps/docsite/package.json+++ b/apps/docsite/package.json@@ -18,10 +18,13 @@"@stylexjs/stylex": "^0.18.3","@xds/cli": "*","@xds/core": "*",+ "@xds/theme-chocolate": "*","@xds/theme-daily": "*","@xds/theme-default": "*",+ "@xds/theme-gothic": "*","@xds/theme-matcha": "*","@xds/theme-neutral": "*",+ "@xds/theme-stone": "*","next": "^15.5.15","react": "^19.2.5","react-dom": "^19.2.5"diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 861197eb74..5d76a00055 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -24,9 +24,12 @@ describe('packageRegistry', () => {expect(names).toContain('@xds/cli');expect(names).toContain('@xds/theme-default');expect(names).toContain('@xds/theme-neutral');+ expect(names).toContain('@xds/theme-chocolate');+ expect(names).toContain('@xds/theme-gothic');+ expect(names).toContain('@xds/theme-stone');+ expect(names).not.toContain('@xds/theme-brutalist');expect(names).not.toContain('@xds/lab');expect(names).not.toContain('@xds/build');- expect(names).not.toContain('@xds/theme-brutalist');expect(packages.length).toBeGreaterThanOrEqual(5);});diff --git a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx b/apps/docsite/src/app/(docs)/packages/[name]/page.tsxindex 20b546cbb6..cf42c14e36 100644--- a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx+++ b/apps/docsite/src/app/(docs)/packages/[name]/page.tsx@@ -21,11 +21,7 @@ import {ThemePackagePage,type InstallStep,} from '../../../../components/ThemePackagePage';-import {defaultTheme} from '@xds/theme-default/built';-import {neutralTheme} from '@xds/theme-neutral/built';-import {dailyTheme} from '@xds/theme-daily/built';-import {matchaTheme} from '@xds/theme-matcha/built';-import type {XDSDefinedTheme} from '@xds/core/theme';+import {themeObjects} from '../../../../generated/themeRegistry';import {PackageHeading} from './PackageHeading';import {PackageStubPage} from './PackageStubPage';import {ComponentPreviewCard} from './ComponentPreviewCard';@@ -34,13 +30,6 @@ function slugToPackageName(slug: string): string {return `@xds/${slug}`;}-const THEME_MAP: Record<string, XDSDefinedTheme> = {- '@xds/theme-default': defaultTheme,- '@xds/theme-neutral': neutralTheme,- '@xds/theme-daily': dailyTheme,- '@xds/theme-matcha': matchaTheme,-};-function getInstallSteps(pkgName: string): InstallStep[] {if (pkgName.includes('theme-')) {const shortName = pkgName.replace('@xds/theme-', '');@@ -94,7 +83,7 @@ export default async function PackagePage({const grouped = groupedComponents[pkg.name];if (isTheme) {- const theme = THEME_MAP[pkg.name];+ const theme = themeObjects[pkg.name];if (theme) {return (<XDSSection maxWidth="lg" padding={6}>diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.cssindex 209aa5ba79..1de6cc7b0a 100644--- a/apps/docsite/src/app/globals.css+++ b/apps/docsite/src/app/globals.css@@ -2,8 +2,11 @@@import "@xds/core/xds.css";@import "@xds/theme-default/theme.css";@import "@xds/theme-neutral/theme.css";+@import "@xds/theme-chocolate/theme.css";@import "@xds/theme-daily/theme.css";+@import "@xds/theme-gothic/theme.css";@import "@xds/theme-matcha/theme.css";+@import "@xds/theme-stone/theme.css";/* StyleX app styles injected here. useCSSLayers.before declaresreset, xds-base, xds-theme so product styles always win. */diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsxindex ac59711c8e..27cb8d6bb8 100644--- a/apps/docsite/src/app/layout.tsx+++ b/apps/docsite/src/app/layout.tsx@@ -11,6 +11,18 @@ export const metadata: Metadata = {export default function RootLayout({children}: {children: React.ReactNode}) {return (<html lang="en">+ <head>+ <link rel="preconnect" href="https://fonts.googleapis.com" />+ <link+ rel="preconnect"+ href="https://fonts.gstatic.com"+ crossOrigin="anonymous"+ />+ <link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Albert+Sans:wght@400;500;600;700&family=DM+Sans:wght@400;500;600;700&family=Figtree:wght@400;500;600;700&family=Fraunces:opsz,[email protected],400;9..144,500;9..144,600;9..144,700&family=Fustat:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Manufacturing+Consent&family=Montserrat:wght@400;500;600;700&family=PT+Serif:wght@400;700&family=Playwrite+US+Trad:[email protected]&display=swap"+ />+ </head><body><Providers>{children}</Providers></body>diff --git a/packages/themes/chocolate/README.md b/packages/themes/chocolate/README.mdindex 2efa0ddf12..5321bd1aee 100644--- a/packages/themes/chocolate/README.md+++ b/packages/themes/chocolate/README.md@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {chocolateTheme} from '@xds/theme-chocolate/built';function App() {- return (- <XDSTheme theme={chocolateTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={chocolateTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-chocolate` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-chocolate/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-chocolate/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| -------------------------------- | ------------------------------------------------------ |+| `@xds/theme-chocolate` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-chocolate/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-chocolate/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,5 +36,29 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-chocolate/theme.css";+@import '@xds/theme-chocolate/theme.css';```++## Fonts++This theme uses custom typefaces:++| Role | Font |+| ------- | -------------- |+| Body | Albert Sans |+| Heading | Fraunces |+| Code | JetBrains Mono |++**These fonts must be loaded separately.** The theme references them by name but does not bundle the font files.++Add this to your HTML `<head>`:++```html+<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Albert+Sans:wght@400;500;600;700&family=Fraunces:opsz,[email protected],400;9..144,500;9..144,600;9..144,700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" />+```++Without this, the theme falls back to system fonts.diff --git a/packages/themes/daily/README.md b/packages/themes/daily/README.mdindex e2f7ecbb59..20210295fa 100644--- a/packages/themes/daily/README.md+++ b/packages/themes/daily/README.md@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {dailyTheme} from '@xds/theme-daily/built';function App() {- return (- <XDSTheme theme={dailyTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={dailyTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-daily` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-daily/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-daily/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| ---------------------------- | ------------------------------------------------------ |+| `@xds/theme-daily` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-daily/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-daily/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,15 +36,39 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-daily/theme.css";+@import '@xds/theme-daily/theme.css';```This is required for component-level theme overrides (colors, radii, typography) to take effect.+## Fonts++This theme uses custom typefaces:++| Role | Font |+| ------- | -------------- |+| Body | Figtree |+| Heading | PT Serif |+| Code | JetBrains Mono |++**These fonts must be loaded separately.** The theme references them by name but does not bundle the font files.++Add this to your HTML `<head>`:++```html+<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=PT+Serif:wght@400;700&display=swap" />+```++Without this, the theme falls back to system fonts.+## Related Packages-| Package | Description |-|---------|-------------|-| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |+| Package | Description |+| ------------------------------------------------------------------------------------ | -------------------------------------- |+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system || [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |-| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |diff --git a/packages/themes/gothic/README.md b/packages/themes/gothic/README.mdindex 0fb18c4a3a..77018bd58c 100644--- a/packages/themes/gothic/README.md+++ b/packages/themes/gothic/README.md@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {gothicTheme} from '@xds/theme-gothic/built';function App() {- return (- <XDSTheme theme={gothicTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={gothicTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-gothic` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-gothic/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-gothic/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| ----------------------------- | ------------------------------------------------------ |+| `@xds/theme-gothic` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-gothic/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-gothic/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,5 +36,29 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-gothic/theme.css";+@import '@xds/theme-gothic/theme.css';```++## Fonts++This theme uses custom typefaces:++| Role | Font |+| ------- | --------------------- |+| Body | Fustat |+| Heading | Manufacturing Consent |+| Code | JetBrains Mono |++**These fonts must be loaded separately.** The theme references them by name but does not bundle the font files.++Add this to your HTML `<head>`:++```html+<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Fustat:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Manufacturing+Consent&display=swap" />+```++Without this, the theme falls back to system fonts.diff --git a/packages/themes/matcha/README.md b/packages/themes/matcha/README.mdindex 72f65d1800..71c1be263c 100644--- a/packages/themes/matcha/README.md+++ b/packages/themes/matcha/README.md@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {matchaTheme} from '@xds/theme-matcha/built';function App() {- return (- <XDSTheme theme={matchaTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={matchaTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-matcha` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-matcha/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-matcha/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| ----------------------------- | ------------------------------------------------------ |+| `@xds/theme-matcha` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-matcha/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-matcha/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,5 +36,29 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-matcha/theme.css";+@import '@xds/theme-matcha/theme.css';```++## Fonts++This theme uses custom typefaces:++| Role | Font |+| ------- | ----------------- |+| Body | DM Sans |+| Heading | Playwrite US Trad |+| Code | JetBrains Mono |++**These fonts must be loaded separately.** The theme references them by name but does not bundle the font files.++Add this to your HTML `<head>`:++```html+<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Playwrite+US+Trad:[email protected]&display=swap" />+```++Without this, the theme falls back to system fonts.diff --git a/packages/themes/neutral/README.md b/packages/themes/neutral/README.mdindex 936b3952ca..10650e5eeb 100644--- a/packages/themes/neutral/README.md+++ b/packages/themes/neutral/README.md@@ -1,6 +1,6 @@# @xds/theme-neutral-Muted, minimal aesthetic. Uses [Lucide](https://lucide.dev) icons.+Muted, minimal aesthetic with system fonts. Uses [Lucide](https://lucide.dev) icons.## Install@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {neutralTheme} from '@xds/theme-neutral/built';function App() {- return (- <XDSTheme theme={neutralTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={neutralTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-neutral` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-neutral/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-neutral/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| ------------------------------ | ------------------------------------------------------ |+| `@xds/theme-neutral` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-neutral/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-neutral/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,15 +36,17 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-neutral/theme.css";+@import '@xds/theme-neutral/theme.css';```This is required for component-level theme overrides (colors, radii, typography) to take effect.+This theme uses system fonts — no external font loading is required.+## Related Packages-| Package | Description |-|---------|-------------|-| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |+| Package | Description |+| ------------------------------------------------------------------------------------ | -------------------------------------- |+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system || [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |-| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.tsindex ca557d8112..eec73b606a 100644--- a/packages/themes/neutral/src/neutralTheme.ts+++ b/packages/themes/neutral/src/neutralTheme.ts@@ -3,7 +3,7 @@** A grayscale theme with neutral colors and modern aesthetics.* Uses oklch color space for perceptually uniform colors.- * Uses Geist font family for a clean, modern look.+ * Uses system font stack for a clean, native look.** Only overrides tokens that differ from the defaults.* Spacing, size, textSize, lineHeight, fontWeight, and transition@@ -38,21 +38,17 @@ export const neutralTheme = defineTheme({name: 'neutral',// Typography: same scale as default (base=14, ratio=1.2).- // Geist fonts for body/heading, Geist Mono for code.+ // System font stack for body/heading, monospace for code.// Neutral uses bold weights on h3/h4 for stronger subsection hierarchy.typography: {scale: {base: 14, ratio: 1.2},- body: {- family: 'Geist',- fallbacks:- '"Geist Fallback", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',- },heading: {weights: {3: 'bold', 4: 'bold'},},code: {- family: 'Geist Mono',- fallbacks: '"SF Mono", Monaco, Consolas, monospace',+ family: 'ui-monospace',+ fallbacks:+ '"SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New", monospace',},},diff --git a/packages/themes/stone/README.md b/packages/themes/stone/README.mdindex 72b346bf9f..3ee22b97f1 100644--- a/packages/themes/stone/README.md+++ b/packages/themes/stone/README.md@@ -17,21 +17,17 @@ import {XDSTheme} from '@xds/core/theme';import {stoneTheme} from '@xds/theme-stone/built';function App() {- return (- <XDSTheme theme={stoneTheme}>- {/* your app */}- </XDSTheme>- );+ return <XDSTheme theme={stoneTheme}>{/* your app */}</XDSTheme>;}```### Import paths-| Path | Use case |-|------|----------|-| `@xds/theme-stone` | Source build (StyleX compilation via `@xds/build`) |-| `@xds/theme-stone/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |-| `@xds/theme-stone/theme.css` | Pre-built CSS file (import in your stylesheet) |+| Path | Use case |+| ---------------------------- | ------------------------------------------------------ |+| `@xds/theme-stone` | Source build (StyleX compilation via `@xds/build`) |+| `@xds/theme-stone/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |+| `@xds/theme-stone/theme.css` | Pre-built CSS file (import in your stylesheet) |If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.@@ -40,5 +36,29 @@ If you're using `@xds/build` for StyleX source compilation, import from the bareAdd the theme CSS to your stylesheet:```css-@import "@xds/theme-stone/theme.css";+@import '@xds/theme-stone/theme.css';```++## Fonts++This theme uses custom typefaces:++| Role | Font |+| ------- | -------------- |+| Body | Figtree |+| Heading | Montserrat |+| Code | JetBrains Mono |++**These fonts must be loaded separately.** The theme references them by name but does not bundle the font files.++Add this to your HTML `<head>`:++```html+<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Montserrat:wght@400;500;600;700&display=swap" />+```++Without this, the theme falls back to system fonts.