Skip to content

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.md
new file mode 100644
index 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.json
index 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.ts
index 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.tsx
index 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.css
index 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 declares
reset, xds-base, xds-theme so product styles always win. */
diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsx
index 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.md
index 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 bare
Add 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.md
index 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 bare
Add 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.md
index 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 bare
Add 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.md
index 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 bare
Add 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.md
index 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 bare
Add 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.ts
index 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.md
index 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 bare
Add 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.