From 68552f66585eae912c2ef086a82236e8ceaedab5 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Thu, 3 Sep 2026 06:53:17 -0700 Subject: [PATCH 01/26] docs: design for the docs page improvements Six changes to /docs: a working Run rail item on the index, search in place of the Scope card, one breadcrumb trail instead of four, visible links in docs prose, CTA buttons in the callouts that exist to send people somewhere, and the search footer on every content page. Two findings from the running dev server shaped it: Tailwind Typography is inert in this app, so every docs prose link renders as plain body text rather than only the callout ones, and /workspace/langgraph/streaming 404s because that capability's canonical destination is its docs route. Co-Authored-By: Claude Opus 5 --- ...026-09-03-docs-page-improvements-design.md | 255 ++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-03-docs-page-improvements-design.md diff --git a/docs/superpowers/specs/2026-09-03-docs-page-improvements-design.md b/docs/superpowers/specs/2026-09-03-docs-page-improvements-design.md new file mode 100644 index 000000000..cfd0c2d10 --- /dev/null +++ b/docs/superpowers/specs/2026-09-03-docs-page-improvements-design.md @@ -0,0 +1,255 @@ +# Docs page improvements — design + +Date: 2026-09-03 +Status: approved, ready for planning + +Six changes to the `/docs` experience: a working Run rail item on the docs +index, search in place of the Scope card, one breadcrumb trail instead of four, +visible links in docs prose, call-to-action buttons in the callouts that exist +to send people somewhere, and the search footer on every docs content page. + +## Findings that shaped the design + +Two things were verified against the running dev server before designing, and +both changed the shape of the work. + +**Docs prose links carry no styling at all.** `MdxRenderer` wraps content in +`docs-prose prose prose-slate` and sets `--tw-prose-links` to the accent color, +but Tailwind Typography is not active in this app: a stylesheet walk in the +loaded page found zero rules matching `.prose`. The custom property is set and +nothing reads it. Computed styles on `/docs/ag-ui/getting-started/introduction` +were `color: rgb(28, 28, 28)`, `text-decoration-line: none`, `font-weight: 400` +for a link in a paragraph, and `rgb(70, 70, 70)` for a link inside a callout. +The reported problem was callout links; the actual problem is every link in +every docs page, and callouts only make it most visible because their body text +is already muted. + +**`/workspace/langgraph/streaming` returns 404.** The capability has a +`docsPath`, so `getWorkspaceDestinationPath()` resolves its canonical +destination to the docs route, and `generateStaticParams()` in +`apps/website/src/app/workspace/[product]/[topic]/page.tsx` deliberately skips +entries whose destination is not their own `workspacePath`. The working Run URL +for that capability is `/docs/langgraph/guides/streaming?mode=run`, which loads +and reports `runtime ready`. The Run href must therefore be derived from the +registry, not written as a literal path. + +A third finding scoped the work rather than changing it. In +`libs/workspace-react/src/lib/components/control-plane/cockpit-control-plane.tsx`, +the host's `renderContextPane` is used only while the active mode is `Docs`; +Run, Code and API render `CockpitSidebar` instead. The "Capability" scope +visible in Run mode belongs to the cockpit sidebar and is not touched here. + +## 1. Run on the docs index points at the default example + +`DocsControlPlane` hardcodes `disabled` on the Run, Code and API rail items, +with a `disabledReason` explaining that the page has no workspace capability. +That is true of a docs page with no example. It is misleading on `/docs`, which +is not a capability page at all: there is no page-specific example to run, so +the canonical example is the only meaningful target. + +On `/docs` only, Run becomes a link. Its href is resolved from the registry at +module scope: + +```ts +const DEFAULT_EXAMPLE = resolveWorkspacePath('/workspace/langgraph/streaming'); +const DEFAULT_EXAMPLE_RUN_HREF = DEFAULT_EXAMPLE + ? getCanonicalWebsiteWorkspaceHref(DEFAULT_EXAMPLE, 'Run') + : null; +``` + +This yields `/docs/langgraph/guides/streaming?mode=run` today and stays correct +if that capability's docs path moves. When the lookup returns `null` — the +capability was renamed or removed — Run falls back to today's disabled state +rather than rendering a dead link. + +Code and API stay disabled on `/docs`. Run semantics on capability doc pages are +unchanged: there, Run means "run the example on this page", and a docs-only page +correctly has none. + +## 2. Scope becomes search + +The `Scope` section at the top of `DocsContextContent` repeats the breadcrumb +trail, and item 3 gives that trail a single owner. It is replaced by a search +trigger in the same position: a full-width button styled as an input, carrying a +magnifier icon, the label `Search docs`, and a `⌘K` hint that is hidden where a +pointer is coarse. + +The trigger calls the existing `openSearch()`, so the mobile-drawer handoff +(`onSearchHandoff`, then `onNavigate` plus a `requestAnimationFrame`-deferred +dispatch) keeps working unchanged. + +The `Search docs` icon button then leaves the `Actions` bar, where it would be a +second control for the same thing. `Actions` renders only when at least one +action remains — otherwise `/docs`, whose only action was search, would show an +empty section with a heading. + +## 3. One breadcrumb trail, owned by the shell header + +A doc page currently renders the same trail four times: + +| Source | Renders | +| --- | --- | +| `workspace-shell.tsx` header | `Ag Ui / Getting Started / Overview` (mono, muted) | +| `DocsBreadcrumb` | `Docs / AG-UI / Getting Started / Introduction` | +| `DocsPageHeader` | `AG-UI · GETTING STARTED` | +| `DocsContextContent` Scope card | `AG-UI / Getting Started / Introduction` | + +The Scope card goes away under item 2. Of the remaining three, the shell header +keeps the trail, because it is the one position that belongs to the shell rather +than to the article, and it is where a reader already looks for location. + +Today that header derives its label from the manifest identity, which is why it +reads `Ag Ui` and `Overview` — the manifest's `toLabel()` casing and its +`page: 'overview'`, neither of which matches what the docs tree calls the +library or the page. It also renders as a muted mono `

`, which is decoration, +not navigation. + +`WorkspaceShell` gains an optional prop: + +```ts +readonly contextTrail?: readonly WorkspaceCrumb[]; +``` + +where `WorkspaceCrumb` is `{ label: string; href?: string }`, declared in +`libs/workspace-react/src/lib/workspace-contracts.ts` and re-exported from the +package index alongside the other shell contracts. When supplied, +the header renders a `