Skip to content

The Open Standard for Generative UI

docs: add Examples and Demos tabs with top-level URLs (#1240)

Visharad Kashyapc3a6996c6f84
diff --git a/README.md b/README.md
index 793b7993d..804556fc9 100644
--- a/README.md
+++ b/README.md
@@ -199,7 +199,7 @@ Good places to start:
- [openui.com](https://openui.com) for the full docs
- [Quickstart](https://www.openui.com/docs/agent/getting-started/quickstart) to scaffold a working app
- [`examples/README.md`](./examples/README.md) to find a focused reference implementation
-- [Cookbooks](https://www.openui.com/docs/cookbooks) for complete walkthroughs with [runnable code](./examples/cookbooks)
+- [Cookbooks](https://www.openui.com/cookbooks) for complete walkthroughs with [runnable code](./examples/cookbooks)
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) if you want to contribute
## Community
diff --git a/docs/README.md b/docs/README.md
index 1bf42a54c..bf757d054 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -159,9 +159,16 @@ Active component-preview specific modules are located under `app/components/` an
### Navigation
`components/docs-navbar.tsx` provides the shared docs header, search, theme control, mobile
-sidebar trigger, and three top-level tabs: **Docs** (`/docs`), **Cookbooks** (`/docs/cookbooks`),
-and **API Reference** (`/docs/api-reference`). Cookbooks and API Reference stay active on their
-respective child pages, and each sidebar lists its folder's pages directly.
+sidebar trigger, and five top-level tabs: **Docs** (`/docs`), **Cookbooks** (`/cookbooks`),
+**Examples** (`/examples`), **Demos** (`/demos`), and **API Reference** (`/docs/api-reference`).
+Each tab stays active on its child pages, and each tab's sidebar comes from its folder's
+`meta.json`. Examples is a single page whose `meta.json` links to its sections, and Demos is a
+single page of cards with no sidebar.
+
+All tabs share one content source in `content/docs`. The loader in `lib/source.ts` serves the
+`cookbooks`, `examples`, and `demos` folders from their own top-level paths instead of `/docs`,
+and `components/docs-shell.tsx` gives those routes the same docs layout. API Reference stays under
+`/docs` because package READMEs and the rest of the docs link to it there.
Within the Docs tab there are two sidebar modes. The global sidebar introduces the documentation
through Start, Build, and Production groups. Links with chevrons enter a nested section sidebar
diff --git a/docs/app/(home)/lab/page.tsx b/docs/app/(home)/lab/page.tsx
index 476efac6b..41efe3e22 100644
--- a/docs/app/(home)/lab/page.tsx
+++ b/docs/app/(home)/lab/page.tsx
@@ -1,24 +1,11 @@
-import {
- ArrowUpRight,
- Bot,
- Code2,
- MonitorSmartphone,
- Package,
- PlugZap,
- Plus,
- Server,
- Sparkles,
- Wrench,
-} from "lucide-react";
+import { labProjects } from "@/lib/lab-projects";
+import { ArrowUpRight, Plus } from "lucide-react";
import type { Metadata } from "next";
-import type { ComponentType } from "react";
import { BevelButton } from "../components/Button/BevelButton";
import { PageHero, PageHeroAccent } from "../components/PageHero/PageHero";
import { Footer } from "../sections/Footer/Footer";
import styles from "./page.module.css";
-type ProjectStatus = "Official" | "Community";
-
const TYPE_ACCENT: Record<string, "blue" | "green" | "purple" | "orange" | "slate"> = {
Tool: "purple",
Plugin: "blue",
@@ -31,278 +18,6 @@ const TYPE_ACCENT: Record<string, "blue" | "green" | "purple" | "orange" | "slat
Article: "purple",
};
-interface ProjectLink {
- label: string;
- href: string;
- external?: boolean;
-}
-
-interface ProjectItem {
- name: string;
- description: string;
- type: string;
- status: ProjectStatus;
- accent: "blue" | "green" | "purple" | "orange" | "slate";
- icon: ComponentType<{ className?: string; strokeWidth?: number }>;
- links: ProjectLink[];
-}
-
-const projects: ProjectItem[] = [
- {
- name: "Curio",
- description:
- "An open-source reading companion that uses OpenUI generative UI to explore words and phrases without leaving the text.",
- type: "App",
- status: "Community",
- accent: "green",
- icon: MonitorSmartphone,
- links: [
- { label: "GitHub", href: "https://github.com/JoseEstevez520/curio", external: true },
- { label: "Website", href: "https://curio-landing-phi.vercel.app", external: true },
- ],
- },
- {
- name: "OpenUI Forge",
- description:
- "A coding-assistant toolkit for generating and wiring OpenUI integrations across common AI stacks.",
- type: "Tool",
- status: "Community",
- accent: "purple",
- icon: Wrench,
- links: [
- { label: "GitHub", href: "https://github.com/OthmanAdi/openui-forge", external: true },
- { label: "Website", href: "https://spruce-prism-8yya.here.now/", external: true },
- ],
- },
- {
- name: "GAIA",
- description:
- "A proactive personal AI assistant for inboxes, calendars, tools, and workflows built with OpenUI.",
- type: "App",
- status: "Community",
- accent: "green",
- icon: Bot,
- links: [
- { label: "GitHub", href: "https://github.com/theexperiencecompany/gaia", external: true },
- { label: "Website", href: "https://heygaia.io/", external: true },
- ],
- },
- {
- name: "Noetic",
- description:
- "An agent framework integration for returning OpenUI interfaces through a streaming output codec, durable surface layer, and transport.",
- type: "Framework",
- status: "Community",
- accent: "orange",
- icon: Sparkles,
- links: [
- {
- label: "Docs",
- href: "https://noetic.tools/docs/framework/generative-ui",
- external: true,
- },
- ],
- },
- {
- name: "Field Theory UI",
- description:
- "A local-first web interface for exploring X/Twitter bookmarks with OpenUI-powered interactive dashboards.",
- type: "App",
- status: "Community",
- accent: "green",
- icon: MonitorSmartphone,
- links: [
- { label: "GitHub", href: "https://github.com/Gitmaxd/field-theory-ui", external: true },
- ],
- },
- {
- name: "Open WebUI Plugin",
- description: "Bring OpenUI-rendered interactive responses into Open WebUI chat workflows.",
- type: "Plugin",
- status: "Community",
- accent: "blue",
- icon: PlugZap,
- links: [
- { label: "GitHub", href: "https://github.com/thesysdev/openwebui-plugin", external: true },
- {
- label: "Guide",
- href: "https://openwebui.com/posts/generative_ui_plugin_for_open_webui_6c017d62",
- external: true,
- },
- { label: "Open", href: "https://github.com/open-webui/open-webui", external: true },
- ],
- },
- {
- name: "Ollama Integration",
- description:
- "Use OpenUI with local Ollama models through an OpenAI-compatible route or an Open WebUI workflow.",
- type: "Provider",
- status: "Community",
- accent: "green",
- icon: Bot,
- links: [
- {
- label: "Article",
- href: "https://dev.to/shogun444/i-tested-openui-with-ollama-models-heres-what-actually-worked-45m7",
- external: true,
- },
- {
- label: "GitHub",
- href: "https://github.com/shogun444/openui-ollama-localsetup",
- external: true,
- },
- { label: "Ollama", href: "https://ollama.com", external: true },
- ],
- },
- {
- name: "Genui VS Code Extension",
- description:
- "Preview '.openui' files live in VS Code and Open VSX-compatible editors while agents write OpenUI Lang.",
- type: "Extension",
- status: "Community",
- accent: "blue",
- icon: Code2,
- links: [
- {
- label: "VS Code",
- href: "https://marketplace.visualstudio.com/items?itemName=Ginaphi.generative-ui",
- external: true,
- },
- {
- label: "Open VSX",
- href: "https://open-vsx.org/extension/ginaphi/generative-ui",
- external: true,
- },
- ],
- },
- {
- name: "OpenClaw OS Plugin",
- description: "Use OpenUI inside OpenClaw OS through the external OpenClaw plugin package.",
- type: "Plugin",
- status: "Official",
- accent: "orange",
- icon: Sparkles,
- links: [
- {
- label: "GitHub",
- href: "https://github.com/thesysdev/openclaw-os/tree/main/packages/claw-plugin",
- external: true,
- },
- { label: "Website", href: "/openclaw-os", external: true },
- ],
- },
- {
- name: "AppLess",
- description:
- "An experimental no-app phone experience that streams OpenUI-generated native interfaces on iOS and Android.",
- type: "App",
- status: "Official",
- accent: "green",
- icon: MonitorSmartphone,
- links: [{ label: "GitHub", href: "https://github.com/thesysdev/appless", external: true }],
- },
- {
- name: "OpenUI Plotly",
- description:
- "Scaffold a Next.js generative UI chat with typed Plotly chart components for data-heavy responses.",
- type: "Package",
- status: "Community",
- accent: "purple",
- icon: Package,
- links: [
- {
- label: "npm",
- href: "https://www.npmjs.com/package/@vishxrad/openui-plotly?activeTab=readme",
- external: true,
- },
- ],
- },
- {
- name: "Vue Lang",
- description: "Define OpenUI component libraries and render OpenUI Lang responses in Vue 3.",
- type: "Framework",
- status: "Official",
- accent: "green",
- icon: Code2,
- links: [
- {
- label: "GitHub",
- href: "https://github.com/thesysdev/openui/tree/main/packages/vue-lang",
- external: true,
- },
- { label: "npm", href: "https://www.npmjs.com/package/@openuidev/vue-lang", external: true },
- ],
- },
- {
- name: "Svelte Lang",
- description: "Define OpenUI component libraries and render OpenUI Lang responses in Svelte 5.",
- type: "Framework",
- status: "Official",
- accent: "orange",
- icon: Code2,
- links: [
- {
- label: "GitHub",
- href: "https://github.com/thesysdev/openui/tree/main/packages/svelte-lang",
- external: true,
- },
- {
- label: "npm",
- href: "https://www.npmjs.com/package/@openuidev/svelte-lang",
- external: true,
- },
- ],
- },
- {
- name: "React Native Example",
- description: "A mobile chat example showing OpenUI rendered in a React Native application.",
- type: "Example",
- status: "Official",
- accent: "slate",
- icon: MonitorSmartphone,
- links: [
- {
- label: "GitHub",
- href: "https://github.com/thesysdev/openui/tree/main/examples/app-frameworks/react-native",
- external: true,
- },
- {
- label: "Docs",
- href: "/docs/openui-lang/examples/app-frameworks/react-native",
- external: true,
- },
- ],
- },
- {
- name: "FastAPI Backend Example",
- description:
- "A full-stack example streaming OpenUI Lang from a Python FastAPI backend into a Vite + React frontend.",
- type: "Example",
- status: "Community",
- accent: "green",
- icon: Server,
- links: [
- {
- label: "GitHub",
- href: "https://github.com/thesysdev/openui/tree/main/examples/app-frameworks/fastapi",
- external: true,
- },
- ],
- },
- {
- name: "AI Native Dashboard",
- description:
- "An OpenUI-powered infinite canvas for generating movable, resizable dashboard widgets from natural language.",
- type: "App",
- status: "Community",
- accent: "green",
- icon: Sparkles,
- links: [
- { label: "GitHub", href: "https://github.com/jaibhasin/AI-Native-Dashboard", external: true },
- ],
- },
-];
-
const DISCORD_URL = "https://discord.gg/suzHfJnpw";
export const metadata: Metadata = {
@@ -370,7 +85,7 @@ export default function LabPage() {
<div className={styles.contentSection}>
<section className={styles.directorySection} id="directory">
<div className={styles.grid}>
- {projects.map((item) => {
+ {labProjects.map((item) => {
return (
<article
className={styles.card}
diff --git a/docs/app/(home)/sections/HeroSection/HeroSection.tsx b/docs/app/(home)/sections/HeroSection/HeroSection.tsx
index 28569ee76..3d4f8dcdf 100644
--- a/docs/app/(home)/sections/HeroSection/HeroSection.tsx
+++ b/docs/app/(home)/sections/HeroSection/HeroSection.tsx
@@ -231,7 +231,7 @@ function CommandTabs({
function DesktopPlaygroundButton({ className = "" }: { className?: string }) {
return (
<PillLink
- href="/demos"
+ href="/openui-vs-json"
className={`${styles.desktopPlaygroundButton} ${className}`.trim()}
arrow={<TrailingArrow />}
>
diff --git a/docs/app/cookbooks/[[...slug]]/page.tsx b/docs/app/cookbooks/[[...slug]]/page.tsx
new file mode 100644
index 000000000..21c2b6884
--- /dev/null
+++ b/docs/app/cookbooks/[[...slug]]/page.tsx
@@ -0,0 +1,31 @@
+import { DocsPageView, getDocsPageMetadata } from "@/components/docs-page";
+import { source } from "@/lib/source";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+
+function getPage(slug: string[] = []) {
+ return source.getPage(["cookbooks", ...slug]);
+}
+
+export default async function Page(props: PageProps<"/cookbooks/[[...slug]]">) {
+ const page = getPage((await props.params).slug);
+ if (!page) notFound();
+
+ return <DocsPageView page={page} />;
+}
+
+export async function generateStaticParams() {
+ return source
+ .generateParams()
+ .filter((params) => params.slug[0] === "cookbooks")
+ .map((params) => ({ slug: params.slug.slice(1) }));
+}
+
+export async function generateMetadata(
+ props: PageProps<"/cookbooks/[[...slug]]">,
+): Promise<Metadata> {
+ const page = getPage((await props.params).slug);
+ if (!page) notFound();
+
+ return getDocsPageMetadata(page);
+}
diff --git a/docs/app/cookbooks/layout.tsx b/docs/app/cookbooks/layout.tsx
new file mode 100644
index 000000000..2a7bd8357
--- /dev/null
+++ b/docs/app/cookbooks/layout.tsx
@@ -0,0 +1,5 @@
+import { DocsShell } from "@/components/docs-shell";
+
+export default function Layout({ children }: LayoutProps<"/cookbooks">) {
+ return <DocsShell>{children}</DocsShell>;
+}
diff --git a/docs/app/demos/layout.tsx b/docs/app/demos/layout.tsx
index d061b81dc..342670a0a 100644
--- a/docs/app/demos/layout.tsx
+++ b/docs/app/demos/layout.tsx
@@ -1,16 +1,4 @@
-import { WebsiteThemeProvider } from "@/components/website-theme-provider";
-import { createPageMetadata } from "@/lib/page-metadata";
-import type { ReactNode } from "react";
-import "./layout.css";
-
-export const metadata = createPageMetadata({
- pathname: "/demos",
- title: "OpenUI vs JSON",
- description: "See how OpenUI runs 3x faster with 67% fewer tokens than JSON.",
- image: "/nav/vsjson-light.webp",
- imageAlt: "OpenUI versus JSON preview",
-});
-
-export default function DemosLayout({ children }: { children: ReactNode }) {
- return <WebsiteThemeProvider>{children}</WebsiteThemeProvider>;
+import { DocsShell } from "@/components/docs-shell";
+export default function Layout({ children }: LayoutProps<"/demos">) {
+ return <DocsShell>{children}</DocsShell>;
}
diff --git a/docs/app/demos/page.tsx b/docs/app/demos/page.tsx
index da43d4605..28405a925 100644
--- a/docs/app/demos/page.tsx
+++ b/docs/app/demos/page.tsx
@@ -1,221 +1,13 @@
-"use client";
+import { DocsPageView, getDocsPageMetadata } from "@/components/docs-page";
+import { source } from "@/lib/source";
+import { notFound } from "next/navigation";
-import { DemoCreditsDialog } from "@/components/DemoCreditsDialog";
-import { isDemoCreditsErrorPayload } from "@/lib/demo-credits";
-import { Send, Square } from "lucide-react";
-import { useTheme } from "next-themes";
-import { useCallback, useRef, useState } from "react";
-import { CodePanel } from "./components/CodePanel/CodePanel";
-import { Header } from "./components/Header/Header";
-import { PreviewPanel } from "./components/PreviewPanel/PreviewPanel";
-import { MODELS, STARTER_PROMPTS, type Model, type Status, type Theme } from "./constants";
+const page = source.getPage(["demos"]);
-export default function DemosPage() {
- const { theme, setTheme } = useTheme();
- const [prompt, setPrompt] = useState("");
- const [model, setModel] = useState<Model>("anthropic/claude-sonnet-4.6");
- const [code, setCode] = useState("");
- const [parsedJson, setParsedJson] = useState<string | null>(null);
- const [status, setStatus] = useState<Status>("idle");
- const [errorMsg, setErrorMsg] = useState("");
- const [showPlaygroundCreditsDialog, setShowPlaygroundCreditsDialog] = useState(false);
+export default function Page() {
+ if (!page) notFound();
- const textareaRef = useRef<HTMLTextAreaElement>(null);
- const abortRef = useRef<AbortController | null>(null);
-
- const currentTheme: Theme =
- theme === "light" || theme === "dark" || theme === "system" ? theme : "system";
-
- const cycleTheme = () => {
- setTheme(currentTheme === "system" ? "light" : currentTheme === "light" ? "dark" : "system");
- };
-
- const handlePromptChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
- setPrompt(e.target.value);
- e.target.style.height = "auto";
- e.target.style.height = `${e.target.scrollHeight}px`;
- };
-
- const handleChipClick = (text: string) => {
- setPrompt(text);
- textareaRef.current?.focus();
- };
-
- const handleSubmit = useCallback(async () => {
- if (!prompt.trim() || status === "streaming") return;
-
- abortRef.current?.abort();
- const controller = new AbortController();
- abortRef.current = controller;
-
- setCode("");
- setParsedJson(null);
- setErrorMsg("");
- setShowPlaygroundCreditsDialog(false);
- setStatus("streaming");
-
- try {
- const res = await fetch("/api/playground/stream", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ model, prompt: prompt.trim() }),
- signal: controller.signal,
- });
-
- if (!res.ok) {
- const err = await res.json().catch(() => ({}));
- if (isDemoCreditsErrorPayload((err as { error?: unknown }).error)) {
- setShowPlaygroundCreditsDialog(true);
- setStatus("idle");
- return;
- }
-
- throw new Error(
- (err as { error?: { message?: string } }).error?.message ?? `Server error ${res.status}`,
- );
- }
-
- const reader = res.body!.getReader();
- const decoder = new TextDecoder();
-
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
-
- const raw = decoder.decode(value, { stream: true });
- for (const line of raw.split("\n")) {
- const trimmed = line.trim();
- if (!trimmed.startsWith("data:")) continue;
- const data = trimmed.slice(5).trim();
- if (data === "[DONE]") {
- setStatus("done");
- return;
- }
- let parsed: {
- error?: unknown;
- choices?: Array<{ delta?: { content?: string }; finish_reason?: string }>;
- };
- try {
- parsed = JSON.parse(data);
- } catch {
- // skip malformed chunks
- continue;
- }
-
- const content = parsed.choices?.[0]?.delta?.content;
- if (content) setCode((prev) => prev + content);
- }
- }
- setStatus("done");
- } catch (err: unknown) {
- if (err instanceof Error && err.name === "AbortError") {
- setStatus("idle");
- return;
- }
- setErrorMsg(err instanceof Error ? err.message : "Unknown error");
- setStatus("error");
- }
- }, [model, prompt, status]);
-
- const handleStop = () => {
- abortRef.current?.abort();
- setStatus("idle");
- };
-
- const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
- if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
- e.preventDefault();
- handleSubmit();
- }
- };
-
- const isDisabled = status === "streaming";
-
- return (
- <div className="app">
- <Header
- theme={currentTheme}
- onThemeToggle={cycleTheme}
- hasApiKey={false}
- onChangeKey={() => {}}
- />
-
- <div className="app-body">
- <div className="content-wrapper">
- <div className="prompt-section">
- <h1 className="prompt-heading">What do you want to build?</h1>
-
- <div className="prompt-container">
- <textarea
- ref={textareaRef}
- className="prompt-textarea"
- placeholder="Describe the UI you want to generate…"
- value={prompt}
- onChange={handlePromptChange}
- onKeyDown={handleKeyDown}
- disabled={isDisabled}
- rows={2}
- />
- <div className="prompt-actions">
- <select
- className="model-select"
- aria-label="Model"
- value={model}
- onChange={(e) => setModel(e.target.value as Model)}
- disabled={isDisabled}
- >
- {MODELS.map((m) => (
- <option key={m} value={m}>
- {m}
- </option>
- ))}
- </select>
-
- {status === "streaming" ? (
- <button className="stop-btn" onClick={handleStop}>
- <Square size={12} fill="currentColor" />
- Stop
- </button>
- ) : (
- <button className="send-btn" onClick={handleSubmit} disabled={!prompt.trim()}>
- <Send size={14} />
- Generate
- </button>
- )}
- </div>
- </div>
-
- <div className="chips-row">
- {STARTER_PROMPTS.map((p) => (
- <button
- key={p}
- className="chip"
- onClick={() => handleChipClick(p)}
- disabled={isDisabled}
- >
- {p}
- </button>
- ))}
- </div>
- </div>
-
- {status === "error" && errorMsg && <div className="error-banner">{errorMsg}</div>}
-
- <div className="split-screen">
- <CodePanel code={code} status={status} parsedJson={parsedJson} />
- <PreviewPanel
- code={code}
- isStreaming={status === "streaming"}
- onParseResult={(r) => setParsedJson(r ? JSON.stringify(r, null, 2) : null)}
- theme={currentTheme}
- />
- </div>
- </div>
- </div>
- <DemoCreditsDialog
- open={showPlaygroundCreditsDialog}
- onClose={() => setShowPlaygroundCreditsDialog(false)}
- />
- </div>
- );
+ return <DocsPageView page={page} />;
}
+
+export const metadata = page ? getDocsPageMetadata(page) : {};
diff --git a/docs/app/docs/[[...slug]]/page.tsx b/docs/app/docs/[[...slug]]/page.tsx
index d3e2d7970..7187bd8a7 100644
--- a/docs/app/docs/[[...slug]]/page.tsx
+++ b/docs/app/docs/[[...slug]]/page.tsx
@@ -1,63 +1,27 @@
-import { LLMCopyButton, ViewOptions } from "@/components/ai/page-actions";
-import { gitConfig } from "@/lib/layout.shared";
-import { getPageImage, source } from "@/lib/source";
-import { getMDXComponents } from "@/mdx-components";
-import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
-import { createRelativeLink } from "fumadocs-ui/mdx";
+import { DocsPageView, getDocsPageMetadata } from "@/components/docs-page";
+import { isTopLevelSection, source } from "@/lib/source";
import type { Metadata } from "next";
import { notFound } from "next/navigation";
+// Sections like cookbooks live at their own top-level path, so /docs does not serve them.
+function getPage(slug: string[] | undefined) {
+ return isTopLevelSection(slug) ? undefined : source.getPage(slug);
+}
+
export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
- const params = await props.params;
- const page = source.getPage(params.slug);
+ const page = getPage((await props.params).slug);
if (!page) notFound();
- const MDX = page.data.body;
-
- return (
- <DocsPage toc={page.data.toc} full={page.data.full}>
- {!page.data.customHeader && (
- <>
- <DocsTitle>{page.data.title}</DocsTitle>
- <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
- <div className="flex flex-row gap-2 items-center border-b pb-6">
- <LLMCopyButton markdownUrl={`${page.url}.mdx`} />
- <ViewOptions
- markdownUrl={page.url}
- githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs/content/docs/${page.path}`}
- />
- </div>
- </>
- )}
- <DocsBody>
- <MDX
- components={getMDXComponents({
- // this allows you to link to other pages with relative file paths
- a: createRelativeLink(source, page),
- })}
- />
- </DocsBody>
- </DocsPage>
- );
+ return <DocsPageView page={page} />;
}
export async function generateStaticParams() {
- return source.generateParams();
+ return source.generateParams().filter((params) => !isTopLevelSection(params.slug));
}
export async function generateMetadata(props: PageProps<"/docs/[[...slug]]">): Promise<Metadata> {
- const params = await props.params;
- const page = source.getPage(params.slug);
+ const page = getPage((await props.params).slug);
if (!page) notFound();
- return {
- title: page.data.title,
- description: page.data.description,
- alternates: {
- canonical: page.url,
- },
- openGraph: {
- images: getPageImage(page).url,
- },
- };
+ return getDocsPageMetadata(page);
}
diff --git a/docs/app/docs/layout.tsx b/docs/app/docs/layout.tsx
index 64d4581d6..c6bc45cdf 100644
--- a/docs/app/docs/layout.tsx
+++ b/docs/app/docs/layout.tsx
@@ -1,13 +1,5 @@
-import { C1DocsDialog } from "@/components/C1DocsDialog";
-import { DocsRouteLayout } from "@/components/docs-route-layout";
-import { WebsiteThemeProvider } from "@/components/website-theme-provider";
-import { source } from "@/lib/source";
+import { DocsShell } from "@/components/docs-shell";
export default function Layout({ children }: LayoutProps<"/docs">) {
- return (
- <WebsiteThemeProvider>
- <C1DocsDialog />
- <DocsRouteLayout tree={source.getPageTree()}>{children}</DocsRouteLayout>
- </WebsiteThemeProvider>
- );
+ return <DocsShell>{children}</DocsShell>;
}
diff --git a/docs/app/examples/layout.tsx b/docs/app/examples/layout.tsx
new file mode 100644
index 000000000..a18e31aa9
--- /dev/null
+++ b/docs/app/examples/layout.tsx
@@ -0,0 +1,5 @@
+import { DocsShell } from "@/components/docs-shell";
+
+export default function Layout({ children }: LayoutProps<"/examples">) {
+ return <DocsShell>{children}</DocsShell>;
+}
diff --git a/docs/app/examples/page.tsx b/docs/app/examples/page.tsx
new file mode 100644
index 000000000..bdb6a70a8
--- /dev/null
+++ b/docs/app/examples/page.tsx
@@ -0,0 +1,13 @@
+import { DocsPageView, getDocsPageMetadata } from "@/components/docs-page";
+import { source } from "@/lib/source";
+import { notFound } from "next/navigation";
+
+const page = source.getPage(["examples"]);
+
+export default function Page() {
+ if (!page) notFound();
+
+ return <DocsPageView page={page} />;
+}
+
+export const metadata = page ? getDocsPageMetadata(page) : {};
diff --git a/docs/app/global.css b/docs/app/global.css
index c7ebddb82..8e09f17b2 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -91,7 +91,12 @@ body {
#nd-sidebar > .flex.flex-col.gap-3.p-4.pb-2,
#nd-sidebar-mobile > .flex.flex-col.gap-3.p-4.pb-2 {
- padding: 2rem 0 0.5rem 1rem !important;
+ padding: 1rem 0 0.5rem 1rem !important;
+}
+
+/* Without a banner the desktop sidebar header is empty, so it only adds space above the page tree. */
+#nd-sidebar > .flex.flex-col.gap-3.p-4.pb-2:not(:has(> :nth-child(2))) {
+ padding-top: 0 !important;
}
/* Sidebar page-tree scroll viewport; the right gutter keeps active rows and dividers off the edge */
diff --git a/docs/app/openui-vs-json/layout.tsx b/docs/app/openui-vs-json/layout.tsx
new file mode 100644
index 000000000..fb1adf282
--- /dev/null
+++ b/docs/app/openui-vs-json/layout.tsx
@@ -0,0 +1,16 @@
+import "@/app/demos/layout.css";
+import { WebsiteThemeProvider } from "@/components/website-theme-provider";
+import { createPageMetadata } from "@/lib/page-metadata";
+import type { ReactNode } from "react";
+
+export const metadata = createPageMetadata({
+ pathname: "/openui-vs-json",
+ title: "OpenUI vs JSON",
+ description: "See how OpenUI runs 3x faster with 67% fewer tokens than JSON.",
+ image: "/nav/vsjson-light.webp",
+ imageAlt: "OpenUI versus JSON preview",
+});
+
+export default function DemosLayout({ children }: { children: ReactNode }) {
+ return <WebsiteThemeProvider>{children}</WebsiteThemeProvider>;
+}
diff --git a/docs/app/openui-vs-json/page.tsx b/docs/app/openui-vs-json/page.tsx
new file mode 100644
index 000000000..80beed2e4
--- /dev/null
+++ b/docs/app/openui-vs-json/page.tsx
@@ -0,0 +1,227 @@
+"use client";
+
+import { CodePanel } from "@/app/demos/components/CodePanel/CodePanel";
+import { Header } from "@/app/demos/components/Header/Header";
+import { PreviewPanel } from "@/app/demos/components/PreviewPanel/PreviewPanel";
+import {
+ MODELS,
+ STARTER_PROMPTS,
+ type Model,
+ type Status,
+ type Theme,
+} from "@/app/demos/constants";
+import { DemoCreditsDialog } from "@/components/DemoCreditsDialog";
+import { isDemoCreditsErrorPayload } from "@/lib/demo-credits";
+import { Send, Square } from "lucide-react";
+import { useTheme } from "next-themes";
+import { useCallback, useRef, useState } from "react";
+
+export default function DemosPage() {
+ const { theme, setTheme } = useTheme();
+ const [prompt, setPrompt] = useState("");
+ const [model, setModel] = useState<Model>("anthropic/claude-sonnet-4.6");
+ const [code, setCode] = useState("");
+ const [parsedJson, setParsedJson] = useState<string | null>(null);
+ const [status, setStatus] = useState<Status>("idle");
+ const [errorMsg, setErrorMsg] = useState("");
+ const [showPlaygroundCreditsDialog, setShowPlaygroundCreditsDialog] = useState(false);
+
+ const textareaRef = useRef<HTMLTextAreaElement>(null);
+ const abortRef = useRef<AbortController | null>(null);
+
+ const currentTheme: Theme =
+ theme === "light" || theme === "dark" || theme === "system" ? theme : "system";
+
+ const cycleTheme = () => {
+ setTheme(currentTheme === "system" ? "light" : currentTheme === "light" ? "dark" : "system");
+ };
+
+ const handlePromptChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+ setPrompt(e.target.value);
+ e.target.style.height = "auto";
+ e.target.style.height = `${e.target.scrollHeight}px`;
+ };
+
+ const handleChipClick = (text: string) => {
+ setPrompt(text);
+ textareaRef.current?.focus();
+ };
+
+ const handleSubmit = useCallback(async () => {
+ if (!prompt.trim() || status === "streaming") return;
+
+ abortRef.current?.abort();
+ const controller = new AbortController();
+ abortRef.current = controller;
+
+ setCode("");
+ setParsedJson(null);
+ setErrorMsg("");
+ setShowPlaygroundCreditsDialog(false);
+ setStatus("streaming");
+
+ try {
+ const res = await fetch("/api/playground/stream", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ model, prompt: prompt.trim() }),
+ signal: controller.signal,
+ });
+
+ if (!res.ok) {
+ const err = await res.json().catch(() => ({}));
+ if (isDemoCreditsErrorPayload((err as { error?: unknown }).error)) {
+ setShowPlaygroundCreditsDialog(true);
+ setStatus("idle");
+ return;
+ }
+
+ throw new Error(
+ (err as { error?: { message?: string } }).error?.message ?? `Server error ${res.status}`,
+ );
+ }
+
+ const reader = res.body!.getReader();
+ const decoder = new TextDecoder();
+
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+
+ const raw = decoder.decode(value, { stream: true });
+ for (const line of raw.split("\n")) {
+ const trimmed = line.trim();
+ if (!trimmed.startsWith("data:")) continue;
+ const data = trimmed.slice(5).trim();
+ if (data === "[DONE]") {
+ setStatus("done");
+ return;
+ }
+ let parsed: {
+ error?: unknown;
+ choices?: Array<{ delta?: { content?: string }; finish_reason?: string }>;
+ };
+ try {
+ parsed = JSON.parse(data);
+ } catch {
+ // skip malformed chunks
+ continue;
+ }
+
+ const content = parsed.choices?.[0]?.delta?.content;
+ if (content) setCode((prev) => prev + content);
+ }
+ }
+ setStatus("done");
+ } catch (err: unknown) {
+ if (err instanceof Error && err.name === "AbortError") {
+ setStatus("idle");
+ return;
+ }
+ setErrorMsg(err instanceof Error ? err.message : "Unknown error");
+ setStatus("error");
+ }
+ }, [model, prompt, status]);
+
+ const handleStop = () => {
+ abortRef.current?.abort();
+ setStatus("idle");
+ };
+
+ const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+ if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
+ e.preventDefault();
+ handleSubmit();
+ }
+ };
+
+ const isDisabled = status === "streaming";
+
+ return (
+ <div className="app">
+ <Header
+ theme={currentTheme}
+ onThemeToggle={cycleTheme}
+ hasApiKey={false}
+ onChangeKey={() => {}}
+ />
+
+ <div className="app-body">
+ <div className="content-wrapper">
+ <div className="prompt-section">
+ <h1 className="prompt-heading">What do you want to build?</h1>
+
+ <div className="prompt-container">
+ <textarea
+ ref={textareaRef}
+ className="prompt-textarea"
+ placeholder="Describe the UI you want to generate…"
+ value={prompt}
+ onChange={handlePromptChange}
+ onKeyDown={handleKeyDown}
+ disabled={isDisabled}
+ rows={2}
+ />
+ <div className="prompt-actions">
+ <select
+ className="model-select"
+ aria-label="Model"
+ value={model}
+ onChange={(e) => setModel(e.target.value as Model)}
+ disabled={isDisabled}
+ >
+ {MODELS.map((m) => (
+ <option key={m} value={m}>
+ {m}
+ </option>
+ ))}
+ </select>
+
+ {status === "streaming" ? (
+ <button className="stop-btn" onClick={handleStop}>
+ <Square size={12} fill="currentColor" />
+ Stop
+ </button>
+ ) : (
+ <button className="send-btn" onClick={handleSubmit} disabled={!prompt.trim()}>
+ <Send size={14} />
+ Generate
+ </button>
+ )}
+ </div>
+ </div>
+
+ <div className="chips-row">
+ {STARTER_PROMPTS.map((p) => (
+ <button
+ key={p}
+ className="chip"
+ onClick={() => handleChipClick(p)}
+ disabled={isDisabled}
+ >
+ {p}
+ </button>
+ ))}
+ </div>
+ </div>
+
+ {status === "error" && errorMsg && <div className="error-banner">{errorMsg}</div>}
+
+ <div className="split-screen">
+ <CodePanel code={code} status={status} parsedJson={parsedJson} />
+ <PreviewPanel
+ code={code}
+ isStreaming={status === "streaming"}
+ onParseResult={(r) => setParsedJson(r ? JSON.stringify(r, null, 2) : null)}
+ theme={currentTheme}
+ />
+ </div>
+ </div>
+ </div>
+ <DemoCreditsDialog
+ open={showPlaygroundCreditsDialog}
+ onClose={() => setShowPlaygroundCreditsDialog(false)}
+ />
+ </div>
+ );
+}
diff --git a/docs/app/sitemap.ts b/docs/app/sitemap.ts
index 1f8d37e96..f26504e5b 100644
--- a/docs/app/sitemap.ts
+++ b/docs/app/sitemap.ts
@@ -3,7 +3,7 @@ import { integrations } from "./(home)/integrations/data";
const STATIC_PATHS = [
"/",
- "/demos",
+ "/openui-vs-json",
"/compare",
"/lab",
"/integrations",
diff --git a/docs/components/docs-navbar.tsx b/docs/components/docs-navbar.tsx
index c3c8b072d..2e113443e 100644
--- a/docs/components/docs-navbar.tsx
+++ b/docs/components/docs-navbar.tsx
@@ -1,6 +1,12 @@
"use client";
-import { API_REFERENCE_URL, COOKBOOKS_URL, isPathWithin } from "@/lib/docs-navigation";
+import {
+ API_REFERENCE_URL,
+ COOKBOOKS_URL,
+ DEMOS_URL,
+ EXAMPLES_URL,
+ isPathWithin,
+} from "@/lib/docs-navigation";
import { siteConfig } from "@/lib/layout.shared";
import { SidebarTrigger } from "fumadocs-ui/components/sidebar/base";
import { useSearchContext } from "fumadocs-ui/contexts/search";
@@ -16,6 +22,8 @@ import { ThemeToggle } from "./theme-toggle";
const tabs = [
{ title: "Docs", url: "/docs" },
{ title: "Cookbooks", url: COOKBOOKS_URL },
+ { title: "Examples", url: EXAMPLES_URL },
+ { title: "Demos", url: DEMOS_URL },
{ title: "API Reference", url: API_REFERENCE_URL },
];
@@ -72,13 +80,10 @@ function SearchBar() {
);
}
-export function DocsNavbar() {
+export function DocsNavbar({ showSidebarTrigger = true }: { showSidebarTrigger?: boolean }) {
const pathname = usePathname();
- const activeTabUrl = isPathWithin(pathname, COOKBOOKS_URL)
- ? COOKBOOKS_URL
- : isPathWithin(pathname, API_REFERENCE_URL)
- ? API_REFERENCE_URL
- : "/docs";
+ const activeTabUrl =
+ tabs.find((tab) => tab.url !== "/docs" && isPathWithin(pathname, tab.url))?.url ?? "/docs";
const { resolvedTheme } = useTheme();
// resolvedTheme is undefined during SSR and the first client render, so gate the
// theme-derived variant behind a mount flag (matching SiteMarketingHeader) to
@@ -109,22 +114,24 @@ export function DocsNavbar() {
</div>
}
leading={
- <SidebarTrigger className={styles.sidebarToggle} aria-label="Browse documentation">
- <svg
- width="20"
- height="20"
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="2"
- strokeLinecap="round"
- strokeLinejoin="round"
- >
- <line x1="3" y1="6" x2="21" y2="6" />
- <line x1="3" y1="12" x2="21" y2="12" />
- <line x1="3" y1="18" x2="21" y2="18" />
- </svg>
- </SidebarTrigger>
+ showSidebarTrigger ? (
+ <SidebarTrigger className={styles.sidebarToggle} aria-label="Browse documentation">
+ <svg
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ >
+ <line x1="3" y1="6" x2="21" y2="6" />
+ <line x1="3" y1="12" x2="21" y2="12" />
+ <line x1="3" y1="18" x2="21" y2="18" />
+ </svg>
+ </SidebarTrigger>
+ ) : undefined
}
end={
<div className={styles.actions}>
diff --git a/docs/components/docs-page.tsx b/docs/components/docs-page.tsx
new file mode 100644
index 000000000..b1bd2eba5
--- /dev/null
+++ b/docs/components/docs-page.tsx
@@ -0,0 +1,53 @@
+import { LLMCopyButton, ViewOptions } from "@/components/ai/page-actions";
+import { gitConfig } from "@/lib/layout.shared";
+import { getPageImage, source } from "@/lib/source";
+import { getMDXComponents } from "@/mdx-components";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
+import { createRelativeLink } from "fumadocs-ui/mdx";
+import type { Metadata } from "next";
+
+type DocsSourcePage = NonNullable<ReturnType<typeof source.getPage>>;
+
+/** Renders a docs content page. Shared by `/docs` and the top-level sections like `/cookbooks`. */
+export function DocsPageView({ page }: { page: DocsSourcePage }) {
+ const MDX = page.data.body;
+
+ return (
+ <DocsPage toc={page.data.toc} full={page.data.full}>
+ {!page.data.customHeader && (
+ <>
+ <DocsTitle>{page.data.title}</DocsTitle>
+ <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
+ <div className="flex flex-row gap-2 items-center border-b pb-6">
+ <LLMCopyButton markdownUrl={`${page.url}.mdx`} />
+ <ViewOptions
+ markdownUrl={page.url}
+ githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs/content/docs/${page.path}`}
+ />
+ </div>
+ </>
+ )}
+ <DocsBody>
+ <MDX
+ components={getMDXComponents({
+ // this allows you to link to other pages with relative file paths
+ a: createRelativeLink(source, page),
+ })}
+ />
+ </DocsBody>
+ </DocsPage>
+ );
+}
+
+export function getDocsPageMetadata(page: DocsSourcePage): Metadata {
+ return {
+ title: page.data.title,
+ description: page.data.description,
+ alternates: {
+ canonical: page.url,
+ },
+ openGraph: {
+ images: getPageImage(page).url,
+ },
+ };
+}
diff --git a/docs/components/docs-route-layout.tsx b/docs/components/docs-route-layout.tsx
index 82fc961a2..98763a49b 100644
--- a/docs/components/docs-route-layout.tsx
+++ b/docs/components/docs-route-layout.tsx
@@ -1,15 +1,15 @@
"use client";
import { DocsNavbar } from "@/components/docs-navbar";
+import { DocsSidebarActions } from "@/components/docs-sidebar-actions";
import {
GLOBAL_DOCS_TREE,
NESTED_DOCS_SECTIONS,
- getApiReferenceTree,
- getCookbooksTree,
getGlobalActiveItemUrl,
getNestedDocsTree,
getNestedRootForEntryUrl,
getSidebarModeForPathname,
+ getTabTree,
type NestedDocsRoot,
type SidebarModeOverride,
} from "@/lib/docs-navigation";
@@ -101,21 +101,23 @@ export function DocsRouteLayout({ tree, children }: DocsRouteLayoutProps) {
const navigationContext = useMemo(() => ({ enterNested, showGlobal }), [enterNested, showGlobal]);
const nestedRoot = sidebarMode.kind === "nested" ? sidebarMode.root : undefined;
- const isApiReference = sidebarMode.kind === "api-reference";
- const isCookbooks = sidebarMode.kind === "cookbooks";
+ // Demos is a single page of cards, so it has no sidebar.
+ const hasSidebar = sidebarMode.kind !== "demos";
+ const tabFolder =
+ sidebarMode.kind === "global" || sidebarMode.kind === "nested" ? undefined : sidebarMode.kind;
const activeTree = useMemo(() => {
- if (isCookbooks) return getCookbooksTree(tree);
- if (isApiReference) return getApiReferenceTree(tree);
+ if (tabFolder) return getTabTree(tree, tabFolder);
return nestedRoot ? getNestedDocsTree(tree, nestedRoot) : GLOBAL_DOCS_TREE;
- }, [isCookbooks, isApiReference, nestedRoot, tree]);
+ }, [tabFolder, nestedRoot, tree]);
return (
<DocsNavigationContext.Provider value={navigationContext}>
<DocsLayout
tree={activeTree}
{...baseOptions()}
- nav={{ component: <DocsNavbar /> }}
+ nav={{ component: <DocsNavbar showSidebarTrigger={hasSidebar} /> }}
sidebar={{
+ enabled: hasSidebar,
tabs: false,
collapsible: false,
className:
@@ -123,6 +125,7 @@ export function DocsRouteLayout({ tree, children }: DocsRouteLayoutProps) {
? "[&_button[aria-expanded]]:!text-fd-foreground [&_button[aria-expanded]+div]:mb-4"
: undefined,
banner: nestedRoot ? <NestedSidebarHeader root={nestedRoot} /> : undefined,
+ footer: <DocsSidebarActions />,
components: sidebarMode.kind === "global" ? { Item: GlobalSidebarItem } : undefined,
}}
searchToggle={{ enabled: false }}
diff --git a/docs/components/docs-shell.tsx b/docs/components/docs-shell.tsx
new file mode 100644
index 000000000..d5b508533
--- /dev/null
+++ b/docs/components/docs-shell.tsx
@@ -0,0 +1,15 @@
+import { C1DocsDialog } from "@/components/C1DocsDialog";
+import { DocsRouteLayout } from "@/components/docs-route-layout";
+import { WebsiteThemeProvider } from "@/components/website-theme-provider";
+import { source } from "@/lib/source";
+import type { ReactNode } from "react";
+
+/** The docs chrome (navbar tabs and sidebar) shared by `/docs` and the top-level sections. */
+export function DocsShell({ children }: { children: ReactNode }) {
+ return (
+ <WebsiteThemeProvider>
+ <C1DocsDialog />
+ <DocsRouteLayout tree={source.getPageTree()}>{children}</DocsRouteLayout>
+ </WebsiteThemeProvider>
+ );
+}
diff --git a/docs/components/docs-sidebar-actions.module.css b/docs/components/docs-sidebar-actions.module.css
new file mode 100644
index 000000000..56f97aeef
--- /dev/null
+++ b/docs/components/docs-sidebar-actions.module.css
@@ -0,0 +1,104 @@
+.sidebarActions {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ gap: 0.375rem;
+}
+
+.sidebarAction {
+ display: flex;
+ min-width: 0;
+ flex-direction: column;
+ align-items: center;
+ gap: 0.3125rem;
+ border: 1px solid var(--docs-card-border);
+ border-radius: 0.625rem;
+ padding: 0.5625rem 0.25rem 0.5rem;
+ color: var(--docs-text-secondary);
+ text-decoration: none;
+ transition:
+ background-color 150ms ease,
+ border-color 150ms ease,
+ color 150ms ease;
+}
+
+.sidebarAction:hover {
+ border-color: var(--docs-card-border-hover);
+ background: var(--docs-hover-bg);
+ color: var(--docs-text-heading);
+}
+
+.sidebarAction svg {
+ width: 1rem;
+ height: 1rem;
+ flex-shrink: 0;
+}
+
+.sidebarActionLabel {
+ max-width: 100%;
+ overflow: hidden;
+ font-size: 0.75rem;
+ font-weight: 500;
+ line-height: 1.2;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+/* The detail card renders in a portal outside the docs layout, so it uses Fumadocs tokens. */
+.detailCard {
+ z-index: 50;
+ display: flex;
+ width: 15rem;
+ flex-direction: column;
+ gap: 0.375rem;
+ border: 1px solid var(--color-fd-border);
+ border-radius: 0.75rem;
+ padding: 0.75rem 0.875rem;
+ background: var(--color-fd-popover);
+ box-shadow: 0 12px 32px rgb(0 0 0 / 14%);
+ color: var(--color-fd-popover-foreground);
+ animation: detail-in 120ms ease-out;
+}
+
+.detailTitle {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ color: var(--color-fd-foreground);
+ font-size: 0.875rem;
+ font-weight: 600;
+}
+
+.detailTitle svg,
+.detailHost svg {
+ width: 0.875rem;
+ height: 0.875rem;
+ flex-shrink: 0;
+}
+
+.detailDescription {
+ color: var(--color-fd-muted-foreground);
+ font-size: 0.8125rem;
+ line-height: 1.5;
+}
+
+.detailHost {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.25rem;
+ color: var(--color-fd-muted-foreground);
+ font-family: var(--font-geist-mono), ui-monospace, monospace;
+ font-size: 0.75rem;
+}
+
+@keyframes detail-in {
+ from {
+ opacity: 0;
+ transform: translateY(4px);
+ }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .detailCard {
+ animation: none;
+ }
+}
diff --git a/docs/components/docs-sidebar-actions.tsx b/docs/components/docs-sidebar-actions.tsx
new file mode 100644
index 000000000..253ad8781
--- /dev/null
+++ b/docs/components/docs-sidebar-actions.tsx
@@ -0,0 +1,101 @@
+"use client";
+
+import { siteConfig } from "@/lib/layout.shared";
+import * as Tooltip from "@radix-ui/react-tooltip";
+import { ArrowRight, ArrowUpRight, Bot, LifeBuoy, MessageCircle } from "lucide-react";
+import Link from "next/link";
+import type { ComponentType } from "react";
+import styles from "./docs-sidebar-actions.module.css";
+
+type SidebarAction = {
+ label: string;
+ title: string;
+ description: string;
+ href: string;
+ icon: ComponentType<{ "aria-hidden"?: boolean }>;
+};
+
+const SIDEBAR_ACTIONS: SidebarAction[] = [
+ {
+ label: "AI setup",
+ title: "Coding agent setup",
+ description:
+ "Connect the OpenUI docs to your coding agent through MCP, the agent skill, or LLM-friendly formats.",
+ href: "/docs/mcp",
+ icon: Bot,
+ },
+ {
+ label: "Discord",
+ title: "Ask on Discord",
+ description: "Get help from the OpenUI team and community, and share what you're building.",
+ href: siteConfig.discordUrl,
+ icon: MessageCircle,
+ },
+ {
+ label: "Talk to us",
+ title: "Stuck? Talk to us",
+ description:
+ "Tell us what's blocking you or what we should improve, and we'll help you on a call.",
+ href: "https://zcal.co/t/thesys/demo",
+ icon: LifeBuoy,
+ },
+];
+
+function isExternal(href: string) {
+ return href.startsWith("https://");
+}
+
+function destination(href: string) {
+ return isExternal(href) ? new URL(href).hostname.replace(/^www\./, "") : href;
+}
+
+/** Links pinned to the bottom of every docs sidebar, with details on hover or focus. */
+export function DocsSidebarActions() {
+ return (
+ <Tooltip.Provider delayDuration={150} skipDelayDuration={300} disableHoverableContent>
+ <nav className={styles.sidebarActions} aria-label="Get started and get help">
+ {SIDEBAR_ACTIONS.map(({ label, title, description, href, icon: Icon }) => (
+ <Tooltip.Root key={label}>
+ <Tooltip.Trigger asChild>
+ {isExternal(href) ? (
+ <a
+ className={styles.sidebarAction}
+ href={href}
+ target="_blank"
+ rel="noopener noreferrer"
+ aria-label={title}
+ >
+ <Icon aria-hidden />
+ <span className={styles.sidebarActionLabel}>{label}</span>
+ </a>
+ ) : (
+ <Link className={styles.sidebarAction} href={href} aria-label={title}>
+ <Icon aria-hidden />
+ <span className={styles.sidebarActionLabel}>{label}</span>
+ </Link>
+ )}
+ </Tooltip.Trigger>
+ <Tooltip.Portal>
+ <Tooltip.Content
+ side="top"
+ sideOffset={8}
+ collisionPadding={12}
+ className={styles.detailCard}
+ >
+ <span className={styles.detailTitle}>
+ <Icon aria-hidden />
+ {title}
+ </span>
+ <span className={styles.detailDescription}>{description}</span>
+ <span className={styles.detailHost}>
+ {destination(href)}
+ {isExternal(href) ? <ArrowUpRight aria-hidden /> : <ArrowRight aria-hidden />}
+ </span>
+ </Tooltip.Content>
+ </Tooltip.Portal>
+ </Tooltip.Root>
+ ))}
+ </nav>
+ </Tooltip.Provider>
+ );
+}
diff --git a/docs/components/showcase/cards.tsx b/docs/components/showcase/cards.tsx
new file mode 100644
index 000000000..6e008c25f
--- /dev/null
+++ b/docs/components/showcase/cards.tsx
@@ -0,0 +1,87 @@
+import { ArrowUpRight } from "lucide-react";
+import Link from "next/link";
+import styles from "./showcase.module.css";
+
+export type CardLinkItem = { label: string; href: string; external?: boolean };
+
+/** A card with a light/dark screenshot, used for featured projects and demos. */
+export type ShowcaseItem = {
+ name: string;
+ tagline: string;
+ description: string;
+ image: { light: string; dark: string };
+ links: CardLinkItem[];
+};
+
+/** A text-only card, used for community projects, chat conversations, and tools. */
+export type LinkCardItem = {
+ name: string;
+ description: string;
+ tag?: string;
+ links: CardLinkItem[];
+};
+
+export function CardLink({ label, href, external }: CardLinkItem) {
+ if (external) {
+ return (
+ <a className={styles.cardLink} href={href} target="_blank" rel="noopener noreferrer">
+ {label}
+ <ArrowUpRight aria-hidden className={styles.cardLinkIcon} />
+ </a>
+ );
+ }
+
+ return (
+ <Link className={styles.cardLink} href={href}>
+ {label}
+ </Link>
+ );
+}
+
+export function ShowcaseGrid({ items }: { items: ShowcaseItem[] }) {
+ return (
+ <div className={styles.featuredGrid}>
+ {items.map((item) => (
+ <article key={item.name} className={styles.featuredCard}>
+ <div className={styles.featuredMedia}>
+ {/* eslint-disable-next-line @next/next/no-img-element */}
+ <img className={styles.imageLight} src={item.image.light} alt="" loading="lazy" />
+ {/* eslint-disable-next-line @next/next/no-img-element */}
+ <img className={styles.imageDark} src={item.image.dark} alt="" loading="lazy" />
+ </div>
+ <div className={styles.featuredBody}>
+ <span className={styles.eyebrow}>{item.tagline}</span>
+ <h3 className={styles.cardTitle}>{item.name}</h3>
+ <p className={styles.cardDescription}>{item.description}</p>
+ <div className={styles.cardLinks}>
+ {item.links.map((link) => (
+ <CardLink key={link.label} {...link} />
+ ))}
+ </div>
+ </div>
+ </article>
+ ))}
+ </div>
+ );
+}
+
+export function LinkCardGrid({ items }: { items: LinkCardItem[] }) {
+ return (
+ <div className={styles.grid}>
+ {items.map((item) => (
+ <article key={item.name} className={styles.card}>
+ <div className={styles.cardHeader}>
+ <h4 className={styles.cardTitle}>{item.name}</h4>
+ {item.tag ? <span className={styles.tag}>{item.tag}</span> : null}
+ </div>
+ <p className={styles.cardDescription}>{item.description}</p>
+ <div className={styles.cardLinks}>
+ {item.links.map((link) => (
+ <CardLink key={link.label} {...link} />
+ ))}
+ </div>
+ </article>
+ ))}
+ </div>
+ );
+}
diff --git a/docs/components/showcase/demos.tsx b/docs/components/showcase/demos.tsx
new file mode 100644
index 000000000..eb6c2796c
--- /dev/null
+++ b/docs/components/showcase/demos.tsx
@@ -0,0 +1,40 @@
+import { ShowcaseGrid, type ShowcaseItem } from "./cards";
+
+const DEMOS: ShowcaseItem[] = [
+ {
+ name: "OpenUI Chat",
+ tagline: "Chat assistant",
+ description:
+ "A ChatGPT-like assistant powered by OpenUI Cloud. Start a live conversation or replay a curated one.",
+ image: { light: "/nav/chat-light.webp", dark: "/nav/chat-dark.webp" },
+ links: [{ label: "Open demo", href: "/chat" }],
+ },
+ {
+ name: "AI Dashboards",
+ tagline: "Live GitHub data",
+ description:
+ "Enter a GitHub username and ask questions about their activity. Each answer is an interactive dashboard.",
+ image: { light: "/nav/dashboard-light.webp", dark: "/nav/dashboard-dark.webp" },
+ links: [{ label: "Open demo", href: "/demo/github" }],
+ },
+ {
+ name: "Compare",
+ tagline: "Side by side",
+ description:
+ "See the same answers rendered as Markdown, with OpenUI OSS, and with OpenUI Cloud, side by side.",
+ image: { light: "/nav/compare-light.webp", dark: "/nav/compare-dark.webp" },
+ links: [{ label: "Open demo", href: "/compare" }],
+ },
+ {
+ name: "OpenUI vs JSON",
+ tagline: "Playground",
+ description:
+ "Generate UI from a prompt and watch OpenUI Lang stream against JSON, with up to 67% fewer tokens.",
+ image: { light: "/nav/vsjson-light.webp", dark: "/nav/vsjson-dark.webp" },
+ links: [{ label: "Open demo", href: "/openui-vs-json" }],
+ },
+];
+
+export function Demos() {
+ return <ShowcaseGrid items={DEMOS} />;
+}
diff --git a/docs/components/showcase/examples.tsx b/docs/components/showcase/examples.tsx
new file mode 100644
index 000000000..32a4aa7ba
--- /dev/null
+++ b/docs/components/showcase/examples.tsx
@@ -0,0 +1,92 @@
+import { EXAMPLE_CATEGORIES } from "@/lib/example-categories";
+import { EXAMPLES_REPO_URL, getExamplesInCategory } from "@/lib/examples-catalog";
+import { labProjects } from "@/lib/lab-projects";
+import { BookOpen } from "lucide-react";
+import Link from "next/link";
+import { CardLink, LinkCardGrid, ShowcaseGrid, type ShowcaseItem } from "./cards";
+import { RunLocally } from "./run-locally";
+import styles from "./showcase.module.css";
+
+const FEATURED_PROJECTS: ShowcaseItem[] = [
+ {
+ name: "OpenClaw OS",
+ tagline: "Agent workspace",
+ description:
+ "The default workspace for OpenClaw. Agents generate interactive apps and artifacts that stay updated with live data.",
+ image: { light: "/nav/openclaw-light.webp", dark: "/nav/openclaw-dark.webp" },
+ links: [
+ { label: "Website", href: "/openclaw-os" },
+ { label: "GitHub", href: "https://github.com/thesysdev/openclaw-os", external: true },
+ ],
+ },
+ {
+ name: "AppLess",
+ tagline: "Phone OS concept",
+ description:
+ "An experimental phone with no apps. Ask for what you need and OpenUI streams a native interface for it on iOS and Android.",
+ image: { light: "/nav/appless-light.webp", dark: "/nav/appless-dark.webp" },
+ links: [{ label: "GitHub", href: "https://github.com/thesysdev/appless", external: true }],
+ },
+];
+
+export function FeaturedProjects() {
+ return <ShowcaseGrid items={FEATURED_PROJECTS} />;
+}
+
+export function RepoExamples() {
+ return (
+ <div className={styles.categories}>
+ {EXAMPLE_CATEGORIES.map((category) => {
+ const examples = getExamplesInCategory(category.id);
+ if (examples.length === 0) return null;
+
+ return (
+ <section key={category.id} aria-labelledby={category.id}>
+ <h3 id={category.id} className={styles.categoryTitle}>
+ {category.title}
+ </h3>
+ <p className={styles.categoryDescription}>{category.description}</p>
+ <div className={styles.grid}>
+ {examples.map((example) => (
+ <article key={example.name} className={styles.card}>
+ <h4 className={styles.cardTitle}>{example.title}</h4>
+ <p className={styles.cardDescription}>{example.description}</p>
+ <div className={styles.cardLinks}>
+ <RunLocally title={example.title} name={example.name} envKey={example.envKey} />
+ <CardLink label="Source" href={example.sourceUrl} external />
+ {example.guideUrl ? (
+ <Link className={styles.cardLink} href={example.guideUrl}>
+ <BookOpen aria-hidden className={styles.cardLinkIcon} />
+ Guide
+ </Link>
+ ) : null}
+ </div>
+ </article>
+ ))}
+ </div>
+ </section>
+ );
+ })}
+ </div>
+ );
+}
+
+export function CommunityProjects() {
+ // Community work that was merged into `examples/` already has a card above.
+ const projects = labProjects.filter(
+ (project) =>
+ project.status === "Community" &&
+ !project.links.some((link) => link.href.startsWith(EXAMPLES_REPO_URL)),
+ );
+
+ return (
+ <LinkCardGrid
+ items={projects.map((project) => ({
+ name: project.name,
+ description: project.description,
+ tag: project.type,
+ links: project.links.map((link) => ({ ...link, external: true })),
+ }))}
+ />
+ );
+}
diff --git a/docs/components/showcase/run-locally.tsx b/docs/components/showcase/run-locally.tsx
new file mode 100644
index 000000000..435bdd3c4
--- /dev/null
+++ b/docs/components/showcase/run-locally.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { Popover, PopoverContent, PopoverTrigger } from "fumadocs-ui/components/ui/popover";
+import { useCopyButton } from "fumadocs-ui/utils/use-copy-button";
+import { Check, Copy, SquareTerminal } from "lucide-react";
+import { Fragment } from "react";
+import styles from "./showcase.module.css";
+
+type RunLocallyProps = {
+ title: string;
+ name: string;
+ envKey?: string;
+};
+
+/** Shows the exact `openui create` command for an example and what it will ask for. */
+export function RunLocally({ title, name, envKey }: RunLocallyProps) {
+ const command = `npx @openuidev/cli@latest create --example ${name}`;
+ const [copied, onCopy] = useCopyButton(() => navigator.clipboard.writeText(command));
+
+ return (
+ <Popover>
+ <PopoverTrigger className={styles.runButton}>
+ <SquareTerminal aria-hidden className={styles.cardLinkIcon} />
+ Run locally
+ </PopoverTrigger>
+ <PopoverContent align="start" className={styles.runPopover}>
+ <p className={styles.runTitle}>Run {title} locally</p>
+ <div className={styles.runCommand}>
+ {/* Wrap only between words so a flag like `--example` never splits across lines. */}
+ <code>
+ {command.split(" ").map((word, index) => (
+ <Fragment key={index}>
+ {index > 0 ? " " : null}
+ <span className={styles.runWord}>{word}</span>
+ </Fragment>
+ ))}
+ </code>
+ <button
+ type="button"
+ className={styles.runCopy}
+ aria-label={copied ? "Copied command" : "Copy command"}
+ onClick={onCopy}
+ >
+ {copied ? <Check aria-hidden /> : <Copy aria-hidden />}
+ </button>
+ </div>
+ <p className={styles.runNote}>
+ {envKey ? (
+ <>
+ The CLI copies the example into a new folder and asks for your <code>{envKey}</code>,
+ which it saves to <code>.env</code>.
+ </>
+ ) : (
+ <>
+ The CLI copies the example into a new folder. This one needs more than one API key, so
+ set them as its README describes.
+ </>
+ )}
+ </p>
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/docs/components/showcase/showcase.module.css b/docs/components/showcase/showcase.module.css
new file mode 100644
index 000000000..e1bc4fa10
--- /dev/null
+++ b/docs/components/showcase/showcase.module.css
@@ -0,0 +1,246 @@
+.featuredGrid,
+.grid {
+ display: grid;
+ gap: 1rem;
+ margin: 1.25rem 0 0;
+}
+
+/* At most two columns, so four featured cards form a 2x2 grid instead of 3 + 1. */
+.featuredGrid {
+ grid-template-columns: repeat(
+ auto-fit,
+ minmax(min(100%, max(22rem, calc((100% - 1rem) / 2))), 1fr)
+ );
+}
+
+.grid {
+ grid-template-columns: repeat(auto-fill, minmax(min(100%, 18rem), 1fr));
+}
+
+.featuredCard,
+.card {
+ display: flex;
+ min-width: 0;
+ flex-direction: column;
+ border: 1px solid var(--docs-card-border);
+ border-radius: 0.875rem;
+ background: var(--color-fd-card);
+ transition: border-color 150ms ease;
+}
+
+.featuredCard:hover,
+.card:hover {
+ border-color: var(--docs-card-border-hover);
+}
+
+.featuredCard {
+ overflow: hidden;
+}
+
+.featuredMedia {
+ aspect-ratio: 7 / 4;
+ border-bottom: 1px solid var(--docs-card-border);
+ background: var(--docs-hover-bg);
+}
+
+.featuredMedia img {
+ display: block;
+ width: 100%;
+ height: 100%;
+ margin: 0;
+ border-radius: 0;
+ object-fit: cover;
+}
+
+.imageDark {
+ display: none !important;
+}
+
+:global(.dark) .imageLight {
+ display: none !important;
+}
+
+:global(.dark) .imageDark {
+ display: block !important;
+}
+
+.featuredBody {
+ display: flex;
+ flex: 1;
+ flex-direction: column;
+ padding: 1.125rem 1.25rem 1.25rem;
+}
+
+.eyebrow {
+ margin-bottom: 0.25rem;
+ color: var(--docs-text-muted);
+ font-size: 0.75rem;
+ font-weight: 500;
+ letter-spacing: 0.02em;
+ text-transform: uppercase;
+}
+
+.card {
+ padding: 1rem 1.125rem 1.125rem;
+}
+
+.cardHeader {
+ display: flex;
+ align-items: baseline;
+ justify-content: space-between;
+ gap: 0.75rem;
+}
+
+.cardTitle {
+ margin: 0 !important;
+ color: var(--docs-text-heading);
+ font-size: 0.975rem !important;
+ font-weight: 600;
+ line-height: 1.4;
+}
+
+.featuredCard .cardTitle {
+ font-size: 1.125rem !important;
+}
+
+.cardDescription {
+ flex: 1;
+ margin: 0.375rem 0 0 !important;
+ color: var(--docs-text-secondary);
+ font-size: 0.875rem;
+ line-height: 1.55;
+}
+
+.tag {
+ flex-shrink: 0;
+ border: 1px solid var(--docs-card-border);
+ border-radius: 999px;
+ padding: 0.0625rem 0.5rem;
+ color: var(--docs-text-muted);
+ font-size: 0.6875rem;
+ font-weight: 500;
+}
+
+.cardLinks {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 1rem;
+ margin-top: 0.875rem;
+}
+
+.cardLink,
+.runButton {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.25rem;
+ color: var(--docs-text-heading) !important;
+ font-size: 0.8125rem;
+ font-weight: 500;
+ text-decoration: none !important;
+}
+
+.cardLink:hover,
+.runButton:hover {
+ text-decoration: underline !important;
+ text-underline-offset: 3px;
+}
+
+.runButton {
+ cursor: pointer;
+}
+
+/* The popover renders in a portal outside the docs layout, so it uses Fumadocs tokens. */
+.runPopover {
+ width: min(30rem, calc(100vw - 2rem));
+ padding: 0.875rem !important;
+ background: var(--color-fd-popover) !important;
+}
+
+.runTitle {
+ margin: 0;
+ color: var(--color-fd-foreground);
+ font-weight: 600;
+}
+
+.runCommand {
+ display: flex;
+ align-items: flex-start;
+ gap: 0.5rem;
+ margin-top: 0.625rem;
+ border: 1px solid var(--color-fd-border);
+ border-radius: 0.5rem;
+ padding: 0.5rem 0.5rem 0.5rem 0.75rem;
+ background: var(--color-fd-muted);
+}
+
+.runCommand code {
+ flex: 1;
+ color: var(--color-fd-foreground);
+ font-family: var(--font-geist-mono), ui-monospace, monospace;
+ font-size: 0.75rem;
+ font-variant-ligatures: none;
+ line-height: 1.6;
+}
+
+.runWord {
+ white-space: nowrap;
+}
+
+.runCopy {
+ display: inline-flex;
+ flex-shrink: 0;
+ align-items: center;
+ justify-content: center;
+ width: 1.5rem;
+ height: 1.5rem;
+ border-radius: 0.375rem;
+ color: var(--color-fd-muted-foreground);
+ cursor: pointer;
+}
+
+.runCopy:hover {
+ background: var(--color-fd-accent);
+ color: var(--color-fd-foreground);
+}
+
+.runCopy svg {
+ width: 0.875rem;
+ height: 0.875rem;
+}
+
+.runNote {
+ margin: 0.625rem 0 0;
+ color: var(--color-fd-muted-foreground);
+ font-size: 0.8125rem;
+ line-height: 1.5;
+}
+
+.runNote code {
+ font-family: var(--font-geist-mono), ui-monospace, monospace;
+ font-size: 0.75rem;
+ color: var(--color-fd-foreground);
+}
+
+.cardLinkIcon {
+ width: 0.875rem;
+ height: 0.875rem;
+ color: var(--docs-text-muted);
+}
+
+.categories {
+ display: flex;
+ flex-direction: column;
+ gap: 2.25rem;
+ margin-top: 1.5rem;
+}
+
+.categoryTitle {
+ margin: 0 !important;
+ scroll-margin-top: 7rem;
+}
+
+.categoryDescription {
+ margin: 0.25rem 0 0 !important;
+ color: var(--docs-text-secondary);
+ font-size: 0.9375rem;
+}
diff --git a/docs/components/site-primary-nav.tsx b/docs/components/site-primary-nav.tsx
index 6a0b8bd26..8b8e9ebaa 100644
--- a/docs/components/site-primary-nav.tsx
+++ b/docs/components/site-primary-nav.tsx
@@ -175,7 +175,7 @@ export const PRIMARY_SITE_NAV_ITEMS: NavItem[] = [
title: "OpenUI vs JSON",
description:
"Compare OpenUI Lang with JSON-based UI generation: 3× faster with up to 67% fewer tokens.",
- href: "/demos",
+ href: "/openui-vs-json",
icon: Code,
},
],
diff --git a/docs/content/docs/demos/index.mdx b/docs/content/docs/demos/index.mdx
new file mode 100644
index 000000000..e46cb5d50
--- /dev/null
+++ b/docs/content/docs/demos/index.mdx
@@ -0,0 +1,9 @@
+---
+title: Demos
+description: Live demos of OpenUI you can try in the browser.
+full: true
+---
+
+import { Demos } from "@/components/showcase/demos";
+
+<Demos />
diff --git a/docs/content/docs/demos/meta.json b/docs/content/docs/demos/meta.json
new file mode 100644
index 000000000..a5310fbef
--- /dev/null
+++ b/docs/content/docs/demos/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Demos",
+ "root": true,
+ "pages": ["index"]
+}
diff --git a/docs/content/docs/examples/index.mdx b/docs/content/docs/examples/index.mdx
new file mode 100644
index 000000000..4f2d81fd9
--- /dev/null
+++ b/docs/content/docs/examples/index.mdx
@@ -0,0 +1,29 @@
+---
+title: Examples
+description: Projects built with OpenUI, runnable examples from the repository, and work from the community.
+full: true
+---
+
+import { CommunityProjects, FeaturedProjects, RepoExamples } from "@/components/showcase/examples";
+
+## Featured projects
+
+Full products the OpenUI team builds in the open to show what generative UI can do beyond chat.
+
+<FeaturedProjects />
+
+## Runnable examples
+
+Every example in the [`examples/`](https://github.com/thesysdev/openui/tree/main/examples) folder is a standalone app. Scaffold any of them with the OpenUI CLI. **Run locally** on a card shows the exact command and the API key that example needs:
+
+```bash
+npx @openuidev/cli@latest create --example <name>
+```
+
+<RepoExamples />
+
+## Community projects
+
+Apps, tools, and integrations built by the OpenUI community. To add yours, [open an issue](https://github.com/thesysdev/openui/issues) with a link and a short description.
+
+<CommunityProjects />
diff --git a/docs/content/docs/examples/meta.json b/docs/content/docs/examples/meta.json
new file mode 100644
index 000000000..f8a2c6589
--- /dev/null
+++ b/docs/content/docs/examples/meta.json
@@ -0,0 +1,15 @@
+{
+ "title": "Examples",
+ "root": true,
+ "pages": [
+ "[Featured projects](/examples#featured-projects)",
+ "---Runnable examples---",
+ "[Agent frameworks](/examples#agent-frameworks)",
+ "[App frameworks](/examples#app-frameworks)",
+ "[Design systems](/examples#design-systems)",
+ "[Harnesses](/examples#harnesses)",
+ "[Miscellaneous](/examples#miscellaneous)",
+ "---Community---",
+ "[Community projects](/examples#community-projects)"
+ ]
+}
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 3c50bc0b7..6fcc05369 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -8,6 +8,8 @@
"build-agents",
"agent",
"cookbooks",
+ "examples",
+ "demos",
"production",
"gateway",
"autofix",
diff --git a/docs/lib/docs-navigation.test.ts b/docs/lib/docs-navigation.test.ts
index d5ff3f1a0..04c3f56e7 100644
--- a/docs/lib/docs-navigation.test.ts
+++ b/docs/lib/docs-navigation.test.ts
@@ -3,14 +3,13 @@ import assert from "node:assert/strict";
import { describe, it } from "node:test";
import {
GLOBAL_DOCS_TREE,
- getApiReferenceTree,
- getCookbooksTree,
getDefaultSidebarMode,
getGlobalActiveItemUrl,
getNestedDocsTree,
getNestedRootForEntryUrl,
getNestedRootForPathname,
getSidebarModeForPathname,
+ getTabTree,
} from "./docs-navigation";
describe("global docs navigation", () => {
@@ -187,10 +186,21 @@ describe("nested docs navigation", () => {
{
type: "page",
name: "Conversational analytics",
- url: "/docs/cookbooks/conversational-analytics",
+ url: "/cookbooks/conversational-analytics",
},
],
},
+ {
+ type: "folder",
+ name: "Examples",
+ root: true,
+ $ref: { folder: "examples" },
+ children: [
+ { type: "page", name: "Featured projects", url: "/examples#featured-projects" },
+ { type: "separator", name: "Community" },
+ { type: "page", name: "Community projects", url: "/examples#community-projects" },
+ ],
+ },
{
type: "folder",
name: "API Reference",
@@ -234,21 +244,28 @@ describe("nested docs navigation", () => {
],
};
- it("gives top-level cookbook and API tabs their own sidebars", () => {
- for (const pathname of ["/docs/cookbooks", "/docs/cookbooks/conversational-analytics"]) {
- assert.deepEqual(getDefaultSidebarMode(pathname), { kind: "cookbooks" });
+ it("gives the Cookbooks, Examples, Demos, and API Reference tabs their own sidebars", () => {
+ const tabs = [
+ ["/cookbooks", "cookbooks"],
+ ["/cookbooks/conversational-analytics", "cookbooks"],
+ ["/examples", "examples"],
+ ["/demos", "demos"],
+ ["/docs/api-reference", "api-reference"],
+ ] as const;
+ for (const [pathname, kind] of tabs) {
+ assert.deepEqual(getDefaultSidebarMode(pathname), { kind });
assert.equal(getNestedRootForPathname(pathname), undefined);
assert.equal(getGlobalActiveItemUrl(pathname), undefined);
}
assert.deepEqual(
- getSidebarModeForPathname("/docs/cookbooks/conversational-analytics", {
+ getSidebarModeForPathname("/cookbooks/conversational-analytics", {
pathname: "/docs/openui-lang",
mode: { kind: "global" },
}),
{ kind: "cookbooks" },
);
- assert.deepEqual(getDefaultSidebarMode("/docs/cookbooks-other"), { kind: "global" });
- assert.deepEqual(getCookbooksTree(fullTree), {
+ assert.deepEqual(getDefaultSidebarMode("/cookbooks-other"), { kind: "global" });
+ assert.deepEqual(getTabTree(fullTree, "cookbooks"), {
type: "root",
$id: "docs:cookbooks",
name: "Cookbooks",
@@ -256,11 +273,21 @@ describe("nested docs navigation", () => {
{
type: "page",
name: "Conversational analytics",
- url: "/docs/cookbooks/conversational-analytics",
+ url: "/cookbooks/conversational-analytics",
},
],
});
- assert.deepEqual(getApiReferenceTree(fullTree), {
+ assert.deepEqual(getTabTree(fullTree, "examples"), {
+ type: "root",
+ $id: "docs:examples",
+ name: "Examples",
+ children: [
+ { type: "page", name: "Featured projects", url: "/examples#featured-projects" },
+ { type: "separator", name: "Community" },
+ { type: "page", name: "Community projects", url: "/examples#community-projects" },
+ ],
+ });
+ assert.deepEqual(getTabTree(fullTree, "api-reference"), {
type: "root",
$id: "docs:api-reference",
name: "API Reference",
diff --git a/docs/lib/docs-navigation.ts b/docs/lib/docs-navigation.ts
index 8a0abc202..fc99e183c 100644
--- a/docs/lib/docs-navigation.ts
+++ b/docs/lib/docs-navigation.ts
@@ -1,11 +1,12 @@
import type * as PageTree from "fumadocs-core/page-tree";
+export type TabFolder = "cookbooks" | "examples" | "demos" | "api-reference";
+
export type NestedDocsRoot = "openui-lang" | "build-agents" | "gateway" | "reliability";
export type SidebarMode =
| { kind: "global" }
- | { kind: "cookbooks" }
- | { kind: "api-reference" }
+ | { kind: TabFolder }
| {
kind: "nested";
root: NestedDocsRoot;
@@ -51,7 +52,9 @@ export const NESTED_DOCS_SECTIONS: Record<NestedDocsRoot, NestedSection> = {
};
export const API_REFERENCE_URL = "/docs/api-reference";
-export const COOKBOOKS_URL = "/docs/cookbooks";
+export const COOKBOOKS_URL = "/cookbooks";
+export const EXAMPLES_URL = "/examples";
+export const DEMOS_URL = "/demos";
const promotedGlobalUrls = new Set([
"/docs",
@@ -131,6 +134,8 @@ export function getNestedRootForPathname(pathname: string): NestedDocsRoot | und
export function getDefaultSidebarMode(pathname: string): SidebarMode {
if (isPathWithin(pathname, COOKBOOKS_URL)) return { kind: "cookbooks" };
+ if (isPathWithin(pathname, EXAMPLES_URL)) return { kind: "examples" };
+ if (isPathWithin(pathname, DEMOS_URL)) return { kind: "demos" };
if (isPathWithin(pathname, API_REFERENCE_URL)) return { kind: "api-reference" };
if (pathname === "/docs/overview" || promotedGlobalUrls.has(pathname)) {
@@ -167,25 +172,14 @@ function findNestedFolder(nodes: PageTree.Node[], treeFolder: string): PageTree.
return undefined;
}
-export function getApiReferenceTree(tree: PageTree.Root): PageTree.Root {
- const folder = findNestedFolder(tree.children, "api-reference");
- if (!folder) throw new Error('Docs folder "api-reference" was not found in the page tree.');
-
- return {
- type: "root",
- $id: "docs:api-reference",
- name: folder.name,
- children: folder.children,
- };
-}
-
-export function getCookbooksTree(tree: PageTree.Root): PageTree.Root {
- const folder = findNestedFolder(tree.children, "cookbooks");
- if (!folder) throw new Error('Docs folder "cookbooks" was not found in the page tree.');
+/** The sidebar for a top-level tab (Cookbooks, Examples, Demos, API Reference) is its content folder. */
+export function getTabTree(tree: PageTree.Root, treeFolder: TabFolder): PageTree.Root {
+ const folder = findNestedFolder(tree.children, treeFolder);
+ if (!folder) throw new Error(`Docs folder "${treeFolder}" was not found in the page tree.`);
return {
type: "root",
- $id: "docs:cookbooks",
+ $id: `docs:${treeFolder}`,
name: folder.name,
children: folder.children,
};
diff --git a/docs/lib/example-categories.ts b/docs/lib/example-categories.ts
new file mode 100644
index 000000000..c7772ea99
--- /dev/null
+++ b/docs/lib/example-categories.ts
@@ -0,0 +1,42 @@
+/**
+ * Sections of the Examples tab, matching the top-level folders in `examples/`. Cookbook apps are
+ * left out because they have their own tab.
+ */
+
+export type ExampleCategoryId =
+ "agent-frameworks" | "app-frameworks" | "design-systems" | "harnesses" | "miscellaneous";
+
+export type ExampleCategory = {
+ id: ExampleCategoryId;
+ title: string;
+ description: string;
+};
+
+export const EXAMPLE_CATEGORIES: ExampleCategory[] = [
+ {
+ id: "agent-frameworks",
+ title: "Agent frameworks",
+ description:
+ "Agent runtimes and orchestration frameworks that produce or stream OpenUI output.",
+ },
+ {
+ id: "app-frameworks",
+ title: "App frameworks",
+ description: "Application frameworks and platforms that host an OpenUI client or server.",
+ },
+ {
+ id: "design-systems",
+ title: "Design systems",
+ description: "Component systems adapted into an OpenUI component library.",
+ },
+ {
+ id: "harnesses",
+ title: "Harnesses",
+ description: "Coding-agent harnesses presented through an OpenUI interface.",
+ },
+ {
+ id: "miscellaneous",
+ title: "Miscellaneous",
+ description: "Specialized libraries, capabilities, and backend services.",
+ },
+];
diff --git a/docs/lib/examples-catalog.ts b/docs/lib/examples-catalog.ts
new file mode 100644
index 000000000..2c6edc1d9
--- /dev/null
+++ b/docs/lib/examples-catalog.ts
@@ -0,0 +1,51 @@
+import catalog from "../../examples/examples.json";
+import type { ExampleCategoryId } from "./example-categories";
+
+/**
+ * The Examples tab is generated from `examples/examples.json`, the same manifest
+ * `openui create --example` reads, so a new example appears in both places at once.
+ */
+
+export const EXAMPLES_REPO_URL = "https://github.com/thesysdev/openui/tree/main/examples";
+
+/** Docs pages that walk through an example, keyed by its path in `examples/`. */
+const EXAMPLE_GUIDES: Record<string, string> = {
+ "agent-frameworks/langgraph-platform": "/docs/agent/agent-runtimes/langgraph-platform",
+ "agent-frameworks/vercel-ai-sdk": "/docs/agent/agent-runtimes/vercel-ai-sdk",
+ "agent-frameworks/vercel-eve": "/docs/agent/agent-runtimes/vercel-eve",
+ "app-frameworks/angular": "/docs/api-reference/angular-lang",
+ "design-systems/shadcn": "/docs/openui-lang/examples/design-systems/shadcn",
+ "harnesses/pi": "/docs/agent/agent-runtimes/pi",
+ "miscellaneous/html-artifact": "/docs/agent/guides/open-ended-html",
+ "miscellaneous/react-email": "/docs/openui-lang/examples/miscellaneous/react-email",
+};
+
+export type RepoExample = {
+ /** The name `openui create --example` accepts: the last segment of the path. */
+ name: string;
+ title: string;
+ description: string;
+ category: ExampleCategoryId;
+ sourceUrl: string;
+ guideUrl?: string;
+ /** The key the CLI asks for while scaffolding. Omitted when the example needs several. */
+ envKey?: string;
+};
+
+export const REPO_EXAMPLES: RepoExample[] = catalog.examples.map((example) => {
+ const [category, name] = example.path.split("/") as [ExampleCategoryId, string];
+
+ return {
+ name,
+ title: example.title,
+ description: example.description,
+ category,
+ sourceUrl: `${EXAMPLES_REPO_URL}/${example.path}`,
+ guideUrl: EXAMPLE_GUIDES[example.path],
+ envKey: example.envKey,
+ };
+});
+
+export function getExamplesInCategory(category: ExampleCategoryId): RepoExample[] {
+ return REPO_EXAMPLES.filter((example) => example.category === category);
+}
diff --git a/docs/lib/lab-projects.ts b/docs/lib/lab-projects.ts
new file mode 100644
index 000000000..4840f9c01
--- /dev/null
+++ b/docs/lib/lab-projects.ts
@@ -0,0 +1,287 @@
+import {
+ Bot,
+ Code2,
+ MonitorSmartphone,
+ Package,
+ PlugZap,
+ Server,
+ Sparkles,
+ Wrench,
+} from "lucide-react";
+import type { ComponentType } from "react";
+
+/** Official and community projects built around OpenUI, shown on /lab and /docs/examples. */
+
+export type ProjectStatus = "Official" | "Community";
+
+export interface ProjectLink {
+ label: string;
+ href: string;
+ external?: boolean;
+}
+
+export interface ProjectItem {
+ name: string;
+ description: string;
+ type: string;
+ status: ProjectStatus;
+ accent: "blue" | "green" | "purple" | "orange" | "slate";
+ icon: ComponentType<{ className?: string; strokeWidth?: number }>;
+ links: ProjectLink[];
+}
+
+export const labProjects: ProjectItem[] = [
+ {
+ name: "Curio",
+ description:
+ "An open-source reading companion that uses OpenUI generative UI to explore words and phrases without leaving the text.",
+ type: "App",
+ status: "Community",
+ accent: "green",
+ icon: MonitorSmartphone,
+ links: [
+ { label: "GitHub", href: "https://github.com/JoseEstevez520/curio", external: true },
+ { label: "Website", href: "https://curio-landing-phi.vercel.app", external: true },
+ ],
+ },
+ {
+ name: "OpenUI Forge",
+ description:
+ "A coding-assistant toolkit for generating and wiring OpenUI integrations across common AI stacks.",
+ type: "Tool",
+ status: "Community",
+ accent: "purple",
+ icon: Wrench,
+ links: [
+ { label: "GitHub", href: "https://github.com/OthmanAdi/openui-forge", external: true },
+ { label: "Website", href: "https://spruce-prism-8yya.here.now/", external: true },
+ ],
+ },
+ {
+ name: "GAIA",
+ description:
+ "A proactive personal AI assistant for inboxes, calendars, tools, and workflows built with OpenUI.",
+ type: "App",
+ status: "Community",
+ accent: "green",
+ icon: Bot,
+ links: [
+ { label: "GitHub", href: "https://github.com/theexperiencecompany/gaia", external: true },
+ { label: "Website", href: "https://heygaia.io/", external: true },
+ ],
+ },
+ {
+ name: "Noetic",
+ description:
+ "An agent framework integration for returning OpenUI interfaces through a streaming output codec, durable surface layer, and transport.",
+ type: "Framework",
+ status: "Community",
+ accent: "orange",
+ icon: Sparkles,
+ links: [
+ {
+ label: "Docs",
+ href: "https://noetic.tools/docs/framework/generative-ui",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "Field Theory UI",
+ description:
+ "A local-first web interface for exploring X/Twitter bookmarks with OpenUI-powered interactive dashboards.",
+ type: "App",
+ status: "Community",
+ accent: "green",
+ icon: MonitorSmartphone,
+ links: [
+ { label: "GitHub", href: "https://github.com/Gitmaxd/field-theory-ui", external: true },
+ ],
+ },
+ {
+ name: "Open WebUI Plugin",
+ description: "Bring OpenUI-rendered interactive responses into Open WebUI chat workflows.",
+ type: "Plugin",
+ status: "Community",
+ accent: "blue",
+ icon: PlugZap,
+ links: [
+ { label: "GitHub", href: "https://github.com/thesysdev/openwebui-plugin", external: true },
+ {
+ label: "Guide",
+ href: "https://openwebui.com/posts/generative_ui_plugin_for_open_webui_6c017d62",
+ external: true,
+ },
+ { label: "Open", href: "https://github.com/open-webui/open-webui", external: true },
+ ],
+ },
+ {
+ name: "Ollama Integration",
+ description:
+ "Use OpenUI with local Ollama models through an OpenAI-compatible route or an Open WebUI workflow.",
+ type: "Provider",
+ status: "Community",
+ accent: "green",
+ icon: Bot,
+ links: [
+ {
+ label: "Article",
+ href: "https://dev.to/shogun444/i-tested-openui-with-ollama-models-heres-what-actually-worked-45m7",
+ external: true,
+ },
+ {
+ label: "GitHub",
+ href: "https://github.com/shogun444/openui-ollama-localsetup",
+ external: true,
+ },
+ { label: "Ollama", href: "https://ollama.com", external: true },
+ ],
+ },
+ {
+ name: "Genui VS Code Extension",
+ description:
+ "Preview '.openui' files live in VS Code and Open VSX-compatible editors while agents write OpenUI Lang.",
+ type: "Extension",
+ status: "Community",
+ accent: "blue",
+ icon: Code2,
+ links: [
+ {
+ label: "VS Code",
+ href: "https://marketplace.visualstudio.com/items?itemName=Ginaphi.generative-ui",
+ external: true,
+ },
+ {
+ label: "Open VSX",
+ href: "https://open-vsx.org/extension/ginaphi/generative-ui",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "OpenClaw OS Plugin",
+ description: "Use OpenUI inside OpenClaw OS through the external OpenClaw plugin package.",
+ type: "Plugin",
+ status: "Official",
+ accent: "orange",
+ icon: Sparkles,
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/thesysdev/openclaw-os/tree/main/packages/claw-plugin",
+ external: true,
+ },
+ { label: "Website", href: "/openclaw-os", external: true },
+ ],
+ },
+ {
+ name: "AppLess",
+ description:
+ "An experimental no-app phone experience that streams OpenUI-generated native interfaces on iOS and Android.",
+ type: "App",
+ status: "Official",
+ accent: "green",
+ icon: MonitorSmartphone,
+ links: [{ label: "GitHub", href: "https://github.com/thesysdev/appless", external: true }],
+ },
+ {
+ name: "OpenUI Plotly",
+ description:
+ "Scaffold a Next.js generative UI chat with typed Plotly chart components for data-heavy responses.",
+ type: "Package",
+ status: "Community",
+ accent: "purple",
+ icon: Package,
+ links: [
+ {
+ label: "npm",
+ href: "https://www.npmjs.com/package/@vishxrad/openui-plotly?activeTab=readme",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "Vue Lang",
+ description: "Define OpenUI component libraries and render OpenUI Lang responses in Vue 3.",
+ type: "Framework",
+ status: "Official",
+ accent: "green",
+ icon: Code2,
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/thesysdev/openui/tree/main/packages/vue-lang",
+ external: true,
+ },
+ { label: "npm", href: "https://www.npmjs.com/package/@openuidev/vue-lang", external: true },
+ ],
+ },
+ {
+ name: "Svelte Lang",
+ description: "Define OpenUI component libraries and render OpenUI Lang responses in Svelte 5.",
+ type: "Framework",
+ status: "Official",
+ accent: "orange",
+ icon: Code2,
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/thesysdev/openui/tree/main/packages/svelte-lang",
+ external: true,
+ },
+ {
+ label: "npm",
+ href: "https://www.npmjs.com/package/@openuidev/svelte-lang",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "React Native Example",
+ description: "A mobile chat example showing OpenUI rendered in a React Native application.",
+ type: "Example",
+ status: "Official",
+ accent: "slate",
+ icon: MonitorSmartphone,
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/thesysdev/openui/tree/main/examples/app-frameworks/react-native",
+ external: true,
+ },
+ {
+ label: "Docs",
+ href: "/docs/openui-lang/examples/app-frameworks/react-native",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "FastAPI Backend Example",
+ description:
+ "A full-stack example streaming OpenUI Lang from a Python FastAPI backend into a Vite + React frontend.",
+ type: "Example",
+ status: "Community",
+ accent: "green",
+ icon: Server,
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/thesysdev/openui/tree/main/examples/app-frameworks/fastapi",
+ external: true,
+ },
+ ],
+ },
+ {
+ name: "AI Native Dashboard",
+ description:
+ "An OpenUI-powered infinite canvas for generating movable, resizable dashboard widgets from natural language.",
+ type: "App",
+ status: "Community",
+ accent: "green",
+ icon: Sparkles,
+ links: [
+ { label: "GitHub", href: "https://github.com/jaibhasin/AI-Native-Dashboard", external: true },
+ ],
+ },
+];
diff --git a/docs/lib/showcase-content.test.ts b/docs/lib/showcase-content.test.ts
new file mode 100644
index 000000000..b13e05fab
--- /dev/null
+++ b/docs/lib/showcase-content.test.ts
@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import { EXAMPLE_CATEGORIES } from "./example-categories";
+
+const contentRoot = join(import.meta.dirname, "../content/docs");
+
+function sidebarLinks(folder: string): string[] {
+ const meta = JSON.parse(readFileSync(join(contentRoot, folder, "meta.json"), "utf8")) as {
+ pages: string[];
+ };
+ return meta.pages.flatMap((entry) => entry.match(/\((?<url>[^)]+)\)$/)?.groups?.url ?? []);
+}
+
+describe("showcase sidebars", () => {
+ // The Examples sidebar links to sections that RepoExamples renders from EXAMPLE_CATEGORIES.
+ it("links to every example category", () => {
+ const links = sidebarLinks("examples");
+ for (const category of EXAMPLE_CATEGORIES) {
+ assert.ok(
+ links.includes(`/examples#${category.id}`),
+ `Missing sidebar link for ${category.id}`,
+ );
+ }
+ });
+});
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 5edcb0c88..730a5d727 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -5,9 +5,17 @@ import { blogPosts, docs } from "fumadocs-mdx:collections/server";
export const BASE_URL = "https://www.openui.com";
+/** Docs sections served from their own top-level path, like `/cookbooks`, instead of under `/docs`. */
+export const TOP_LEVEL_SECTIONS = ["cookbooks", "examples", "demos"];
+
+export function isTopLevelSection(slugs: string[] | undefined): boolean {
+ return TOP_LEVEL_SECTIONS.includes(slugs?.[0] ?? "");
+}
+
// See https://fumadocs.dev/docs/headless/source-api for more info
export const source = loader({
baseUrl: "/docs",
+ url: (slugs) => (isTopLevelSection(slugs) ? `/${slugs.join("/")}` : `/docs/${slugs.join("/")}`),
source: docs.toFumadocsSource(),
plugins: [lucideIconsPlugin()],
});
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 1307472e1..df4636999 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -36,11 +36,22 @@ const config = {
async redirects() {
return [
// The Cookbooks overview is temporarily removed; open the only cookbook instead.
+ {
+ source: "/cookbooks",
+ destination: "/cookbooks/conversational-analytics",
+ permanent: false,
+ },
{
source: "/docs/cookbooks",
- destination: "/docs/cookbooks/conversational-analytics",
+ destination: "/cookbooks/conversational-analytics",
permanent: false,
},
+ // Cookbooks, Examples, and Demos moved from /docs to their own top-level paths.
+ {
+ source: "/docs/:section(cookbooks|examples|demos)/:path*",
+ destination: "/:section/:path*",
+ permanent: true,
+ },
{
source: "/docs/gateway/api/autofix",
destination: "/docs/autofix",
@@ -290,7 +301,7 @@ const config = {
},
{
source: "/playground",
- destination: "/demos",
+ destination: "/openui-vs-json",
permanent: true,
},
{
@@ -328,6 +339,14 @@ const config = {
source: "/docs/:path*.mdx",
destination: "/llms.mdx/docs/:path*",
},
+ {
+ source: "/:section(cookbooks|examples|demos)/:path*.mdx",
+ destination: "/llms.mdx/docs/:section/:path*",
+ },
+ {
+ source: "/:section(examples|demos).mdx",
+ destination: "/llms.mdx/docs/:section",
+ },
];
},
};
diff --git a/examples/README.md b/examples/README.md
index bb5520f20..3418e9e0c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -6,14 +6,14 @@ Each example has one primary home. Complete workflows with a companion tutorial
## Categories
-| Category | Use it for |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| [`agent-frameworks`](./agent-frameworks) | Agent runtimes and orchestration frameworks that produce or stream OpenUI output |
-| [`app-frameworks`](./app-frameworks) | Application frameworks or platforms that host an OpenUI client or server |
-| [`cookbooks`](./cookbooks) | Complete runnable workflows paired with step-by-step tutorials in the [Cookbooks docs](https://www.openui.com/docs/cookbooks) |
-| [`design-systems`](./design-systems) | Component systems adapted into an OpenUI component library |
-| [`harnesses`](./harnesses) | Coding-agent harnesses presented through an OpenUI interface |
-| [`miscellaneous`](./miscellaneous) | Distinct capabilities, specialized libraries, and backend services that do not justify another top-level category |
+| Category | Use it for |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [`agent-frameworks`](./agent-frameworks) | Agent runtimes and orchestration frameworks that produce or stream OpenUI output |
+| [`app-frameworks`](./app-frameworks) | Application frameworks or platforms that host an OpenUI client or server |
+| [`cookbooks`](./cookbooks) | Complete runnable workflows paired with step-by-step tutorials in the [Cookbooks docs](https://www.openui.com/cookbooks) |
+| [`design-systems`](./design-systems) | Component systems adapted into an OpenUI component library |
+| [`harnesses`](./harnesses) | Coding-agent harnesses presented through an OpenUI interface |
+| [`miscellaneous`](./miscellaneous) | Distinct capabilities, specialized libraries, and backend services that do not justify another top-level category |
`miscellaneous` is intentionally flat. If several examples develop the same stable integration seam, promote that seam to a top-level category instead of adding nested miscellaneous taxonomies.
@@ -41,9 +41,9 @@ Each example has one primary home. Complete workflows with a companion tutorial
### Cookbooks
-| Example | Demonstrates | Tutorial |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [Conversational analytics](./cookbooks/conversational-analytics) | Formula 1 lap-time analysis with OpenUI Gateway, streamed charts, and visible tool calls | [Walkthrough](https://www.openui.com/docs/cookbooks/conversational-analytics) |
+| Example | Demonstrates | Tutorial |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| [Conversational analytics](./cookbooks/conversational-analytics) | Formula 1 lap-time analysis with OpenUI Gateway, streamed charts, and visible tool calls | [Walkthrough](https://www.openui.com/cookbooks/conversational-analytics) |
### Design systems
diff --git a/examples/cookbooks/README.md b/examples/cookbooks/README.md
index 6feaf000a..837356c34 100644
--- a/examples/cookbooks/README.md
+++ b/examples/cookbooks/README.md
@@ -1,10 +1,10 @@
# OpenUI cookbooks
-Runnable examples for the [Cookbooks docs](https://www.openui.com/docs/cookbooks). Read a cookbook for the walkthrough, then run or adapt its example here.
+Runnable examples for the [Cookbooks docs](https://www.openui.com/cookbooks). Read a cookbook for the walkthrough, then run or adapt its example here.
-| Cookbook | Example | Docs |
-| ------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Conversational analytics | [Next.js, OpenUI Gateway, and SQLite](./conversational-analytics) | [Explore Formula 1 lap times through conversation](https://www.openui.com/docs/cookbooks/conversational-analytics) |
+| Cookbook | Example | Docs |
+| ------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Conversational analytics | [Next.js, OpenUI Gateway, and SQLite](./conversational-analytics) | [Explore Formula 1 lap times through conversation](https://www.openui.com/cookbooks/conversational-analytics) |
## Run an example
diff --git a/examples/cookbooks/conversational-analytics/README.md b/examples/cookbooks/conversational-analytics/README.md
index 1085a7bda..1825fbdd7 100644
--- a/examples/cookbooks/conversational-analytics/README.md
+++ b/examples/cookbooks/conversational-analytics/README.md
@@ -1,6 +1,6 @@
# Conversational analytics
-A runnable companion to the [conversational analytics cookbook](https://www.openui.com/docs/cookbooks/conversational-analytics). Ask a question, inspect the database tool call, and watch a chart or table take shape as the answer streams.
+A runnable companion to the [conversational analytics cookbook](https://www.openui.com/cookbooks/conversational-analytics). Ask a question, inspect the database tool call, and watch a chart or table take shape as the answer streams.
The example uses recorded lap times from the **2024 Miami Grand Prix**, provided by [OpenF1](https://openf1.org/docs/). It runs on Next.js, Agent Interface, OpenUI Gateway, and Node's built-in SQLite module.