Skip to content

feat(apidocs): suite switcher, audit fixes and a stylesheet that follows good-css - #30

Merged
Sam Gammon (sgammon) merged 6 commits into
mainfrom
feat/apidocs-polish
Nov 22, 2026
Merged

Sam Gammon (sgammon) merged 6 commits into
mainfrom
feat/apidocs-polish

Conversation

@sgammon

Copy link
Copy Markdown
Member

Finishes the page chrome and brings the three local audits to full score, with the exceptions listed below.

What changed

  • Top bar. It holds only site-level things: the navigator toggle, brand, version, a switcher between sibling suites, search and the theme switch. The five index links (Overview, Packages, All types, Index, Deprecated) move to a "Reference" block at the top of the navigator. The switcher becomes a menu when the bar cannot fit it, and is the first block of the phone drawer. Nothing wraps or overflows from 320 px up; a test sweeps the widths.
  • Agent readiness. A social image per preset, the overview's packages and guides in JSON-LD, 404.html and 404.md, lastmod in the sitemap from a build-date input, guidance in llms.txt, and YAML frontmatter on the Markdown twins. A member row's summary sentence is drawn from an attribute, so the page text says it once.
  • Stylesheet. Logical properties, OKLCH colors, hover styles only for hover-capable pointers, press states, :focus-visible, and motion only when the reader has not asked for less. Pages mirror correctly under dir="rtl".
  • Fixes. Kotlin exceptions are recognised as exceptions. Relative footer links resolve from the site root. The navigator filter works on guides-only sites. The phone drawer scrolls. On a narrow page a member's summary goes under its signature.

Verified

  • bun test in packages/apidocs: 330 pass, 4 skip. The Astro sample app's suite: 37 pass.
  • Lighthouse 100 on all 40 static runs. On the Astro sample every page is 100 except the largest type page on mobile, which measured 100, 98 and 98 for performance in three runs.
  • Local agent-readiness score: 97 on a plain static host (the ceiling without content negotiation), 100 with negotiation and on the Astro sample.
  • good-css: every mechanical rule passes for both presets.
  • Pixel comparison of the stylesheet conversion at five widths: the largest difference is 6 of 255 on alpha tints, with no shifts.

Exceptions, recorded beside the code and in AUDITS.md

  • The load bar's long animation stays: it shows progress.
  • overflow: hidden stays on six elements that need it for ellipsis or line clamping.
  • The Elide preset's type sizes stay exact pixel values so JetBrains Mono sits on the pixel grid; fluid sizing applies to spacing and the neutral scale.

Not verified

  • Checked in Chromium only. The switcher's layout, :dir(), oklch() and logical properties are untested in Safari and Firefox.
  • The switcher's collapsed menu is tested only in the Astro-shaped markup.
  • Two right-to-left details remain: package suffixes show their dot on the wrong side, and the load bar runs left to right.

…move to the navigator

The top bar now holds only what belongs to the whole site: the navigator toggle, the
brand, the version (or the Astro version menu), a switcher between sibling
documentation sites, search and the theme switch. Between 1101 and 1180px it
overflowed by 31 to 78px, and below 1100px the sibling links were hidden, so a phone
could not reach the other suites at all.

- The theme's header links are the sibling sites. ThemeLink gains `current`; without
  it, the entry whose URL is the site's own root (or its baseUrl) is current. The
  switcher is a row of the sites with the current one marked, or, where the bar has
  no room, one <details> menu button that names the current site (closed by Escape
  and an outside click with the script). Where the navigator is a drawer, the drawer
  lists the sites first and the bar shows the row only when it fits.
- No width is written down. Hidden copies of the labels form a wrapping row whose
  height (one line or more) places the visible row or the menu, so the layout alone
  decides, with or without JavaScript. A small script at the end of the bar, run
  before first paint and on resize, sizes the switcher to what it shows, so a menu
  leaves no dead space, and hides the other form from the keyboard and assistive
  technology. The order in which the bar gives way is in apidocs.css: the search
  field narrows (19rem to 10rem, then 5rem in a drawer layout), the switcher gives
  way, the product name ends in an ellipsis.
- Overview, Packages, All types, Index and Deprecated are at the top of the
  navigator, under the filter: as many as the site has, one line when at most two,
  else rows under "Reference" (any three need 223 to 238px against a 223px line at
  the narrowest navigator, measured in Chromium at both presets).
- Footer theme links are resolved from the site root, as header links are; a path
  from the server root ("/x/") is written as given in both.
- The navigator's filter is there on guides-only sites and narrows guides; it never
  filters the sites, the indexes or the packages.
- Fixes found on the way: the drawer took its content's height and sat behind the
  top bar, unscrollable (align-self: start on a fixed box); links in the deprecated
  index's summaries were not underlined (axe link-in-text-block).
- Astro: the persisted top bar and navigator still update per page. The navigator's
  blocks keep their order around the kept filter field, the kept filter text is
  applied to the new rows before the scroll position is put back, and a top bar from
  another site is sized before it paints. The sample app's sites switch between
  each other.
- The dev bar can show none, one, three or five sibling sites.

Tests: test/topbar.test.ts sweeps 320 to 1600px in steps of 20 in the static and the
Astro markup, with 0, 1, 3 and 5 sites, with and without a version menu, and with a
long product name (nothing wraps, overflows or is cut off); the menu with and without
JavaScript; no layout shift at 1440, 1000 and 360px. axe now covers every page kind
in light and dark. The Astro app's suite sweeps its own pages and checks the current
index link and site across navigations. bun test: 306 pass, 4 skip; the Astro app:
32 pass.

Signed-off-by: Sam Gammon <sam@elide.dev>
…, lastmod, llms.txt guidance

Works down the local agent-readiness audit (Ora's checks, as Is Agentic scores them).

- Link previews: a theme's socialImage ({ asset or url, width, height, alt }) gives
  og:image, its size and alt text, and a large Twitter card; nothing without one.
  Both presets have a 1200x630 image, generated by scripts/gen-social.ts into
  artwork/ with sharp (Elide's dark lockup on its dark surface; the neutral preset's
  mark, which is also its new favicon, so a browser's /favicon.ico request no longer
  logs a 404 on neutral sites). socialImage: null leaves it out. Astro bundles the
  images and og:image names the bundled file.
- JSON-LD: every page's item has a url (absolute with a baseUrl, else relative, as
  the breadcrumbs are); the overview lists its guides and packages as hasPart.
- 404.html and 404.md: the page shell with links to the overview, the indexes and
  llms.txt, noindex, no canonical; with a baseUrl they link from it (<base href>), so
  a host can serve them at any depth. Not in llms.txt or the sitemap. The Astro route
  renders the same page (status 404) for a missing path, or its Markdown, with links
  under the base (notFoundText); notFound()'s wording matches.
- sitemap.xml lastmod from the theme's lastModified (a W3C date), set by the runner's
  and the guides command's --last-modified; never from the clock, absent otherwise.
- llms.txt has a "When to use this" section: the theme's whenToUse, or one sentence
  from the module's name, version and description.
- Markdown twins open with YAML frontmatter (title, description, kind, id, module,
  version, canonical when known), values quoted with <, > and & escaped.
  llms-full.txt joins the twins without it; copy as Markdown copies the page without
  it; Astro twins name the Astro URL as canonical.
- Page token budget: a member row's summary sentence is drawn from a data attribute
  (::before), since the entry inside carries the same sentence as text; the members
  filter still matches it. The largest Java sample page goes from 102,861 to 89,287
  characters of text. The audit had counted the markup inside <pre> as text (175,174
  for that page); it now parses <pre> like any element.
- Audit: Lighthouse also runs on a guide page; the type picks no longer include
  guides and the root index pages; built sites get the run's date as lastModified;
  the Markdown-fallback check reads the heading after the frontmatter.

Agent readiness, measured: 93/94 before on every sample site; now 97 with the static
host profile (agent-friendly-404 is 1/2 there: answering Accept: text/markdown with
404.md is content negotiation, which a static host does not do) and 100 with
--host agent. bun test: 322 pass, 4 skip; the Astro app: 37 pass.

Signed-off-by: Sam Gammon <sam@elide.dev>
isThrowable looked only for java.lang.Throwable among a type's ancestors, so in a
Kotlin model, whose ids are Dokka DRIs, exceptions were grouped with ordinary
classes and drew the class glyph. It now accepts java.lang.Throwable,
kotlin/Throwable///PointingToDeclaration/ and the Java class as a Kotlin model reaches
it, java.lang/Throwable///PointingToDeclaration/, by exact id: a class that merely
has "Throwable" in its name is not an exception.

The Kotlin sample gains ShapeParseException (ancestors kotlin/Exception,
kotlin/Throwable, kotlin/Any as DRIs), now grouped under Exceptions with the
exception glyph. Unit tests cover a Java model, a Kotlin model (both DRI forms), a
name that contains "Throwable", and the sample's page; the Astro app runs axe on it.

Signed-off-by: Sam Gammon <sam@elide.dev>
…s, OKLCH, fluid spacing, guarded hover

Converts src/styles/apidocs.css, the Astro stylesheet and the Elide preset's tokens to
the nine mechanical good-css rules; the local CSS audit goes from 0 to 100 on both
presets.

- Logical properties throughout (inset-*, margin-/padding-block and -inline,
  border-inline-start, logical corner radii, text-align: start/end). Left to right
  nothing moves; with dir="rtl" the page mirrors (navigator on the right, rail on
  the left), code stays left to right there, and a closed member row's chevron
  points to the start of the line.
- Colors as oklch(): the neutral defaults converted exactly from their hex values;
  the Elide preset's converted from @elide/tokens when it loads (src/color.ts:
  lightness to 0.001%, chroma to 0.00001, hue to 0.001 degree; within 0.08 of an
  8-bit step on a random sample; a gray's hue is none). test/color.test.ts checks
  every token against its former hex value and that text contrast is unchanged.
- Fluid spacing: custom properties with clamp() (narrow value up to 480px, wide from
  1000px) for the content's gutter and padding, the top bar's padding and gaps and
  the declaration specimen's padding, in place of the 860px steps. The type scale
  stays exact: the neutral preset's title and specimen sizes are fluid between two
  scale steps, and the Elide preset keeps exact JetBrains Mono sizes, stepped at
  860px as a token switch (noted exception).
- :hover only inside (hover: hover) and (pointer: fine), with an :active state for
  every hover target; :focus-visible for the skip link; motion (the member fade, the
  reading bar, view transitions) only inside prefers-reduced-motion: no-preference;
  overflow: clip in place of hidden, except where an ellipsis or a line clamp needs
  hidden; text-rendering: optimizeLegibility removed.
- Noted exceptions, each with its reason beside the code and in AUDITS.md, which the
  audit now reads ("good-css exception (rule-id): reason" before a declaration or
  its rule): the load bar's 6s and 420ms animations (progress, not a transition);
  overflow: hidden for five ellipses and one line clamp; and layout changes where
  the navigator becomes a drawer, which are arrangements, not stepped sizes.

Pixel comparison against the previous commit, 112 screenshots per run (both presets,
the guides suite; seven pages; light and dark; 1440, 1180, 1101, 1024 and 360px):
largest per-channel difference 6/255 (neutral dark, alpha-blended tints), at most 2
elsewhere, no shift. At 860 and 600px the page changes where intended: spacing is
fluid there now. bun test: 330 pass, 4 skip.

Signed-off-by: Sam Gammon <sam@elide.dev>
…SON-LD has a name

Lighthouse flagged target-size (accessibility 97) on the Java sample's LegacyShape
page at desktop size, before and after the top bar work: the navigator had scrolled to
put the current row a third of the way down, leaving a row half under the sticky
filter field, a target partly covered by another. axe counts the field's input as
the covering target.

- The client scrolls the navigator only when the current row is out of view, as the
  head script already did; a fresh visit to a page whose row is in view leaves the
  navigator at its top.
- When it must scroll, apidocsNavTop (defined in the head script, used by the
  client and the Astro client) picks the position nearest the third at which the
  field sits over a gap between rows (a heading, the space between sections), with the
  current row in view, and clamps it to the navigator's scroll range first.
- A guide's JSON-LD (TechArticle) names it, so a guides-only overview passes the
  json-ld check's name test (3.2 of 4 before).

axe target-size over every page of the Java (both presets), Kotlin and guides sites,
at Lighthouse's desktop and mobile viewports: no findings (3 pages each on two sites
before the second change). bun test: 330 pass, 4 skip; the Astro app: 37 pass.

Signed-off-by: Sam Gammon <sam@elide.dev>
At phone width a member row had no room for the signature and the summary sentence side by side: the signature broke inside identifiers and the sentence was clipped against the row's badge. Below 640px the sentence goes under the signature, which takes the full line and breaks between words.

Verified: bun test passes (330 pass, 4 skip); the Shapes sample page was checked by eye at 360px.
@github-actions

Copy link
Copy Markdown

React Doctor found 38 new issues in 8 files · 38 warnings · score 44 / 100 (Critical) · 1 fixed · vs main

38 warnings

scripts/audit.ts

  • ⚠️ L87 Array lookup inside a loop js-set-map-lookups
  • ⚠️ L109 await inside a loop async-await-in-loop
  • ⚠️ L132 await inside a loop async-await-in-loop

scripts/audit/agentic.ts

  • ⚠️ L357 Array lookup inside a loop js-set-map-lookups
  • ⚠️ L500 fetch Response consumed without status check no-fetch-response-used-without-status-check
  • ⚠️ L510 await inside a loop async-await-in-loop

scripts/audit/css.ts

  • ⚠️ L190 Array lookup inside a loop js-set-map-lookups

scripts/audit/html.ts

  • ⚠️ L162 Array lookup inside a loop js-set-map-lookups

scripts/audit/remote.ts

  • ⚠️ L48 await inside a loop async-await-in-loop
  • ⚠️ L55 await inside a loop async-await-in-loop

scripts/gen-social.ts

  • ⚠️ L18 Array index result dereferenced without a guard no-array-index-deref-without-bounds-or-empty-guard

src/components/chrome.tsx

  • ⚠️ L322 React function has high control-flow complexity no-high-complexity-react-function
  • ⚠️ L516 Unknown DOM property no-unknown-property
  • ⚠️ L518 Unknown DOM property no-unknown-property
  • ⚠️ L519 Unknown DOM property no-unknown-property
  • ⚠️ L520 Unknown DOM property no-unknown-property
  • ⚠️ L521 Array index used as a key no-array-index-as-key
  • ⚠️ L523 Unknown DOM property no-unknown-property
  • ⚠️ L524 Unknown DOM property no-unknown-property
  • ⚠️ L525 Unknown DOM property no-unknown-property
  • ⚠️ L528 Unknown DOM property no-unknown-property
  • ⚠️ L529 Array index used as a key no-array-index-as-key
  • ⚠️ L534 Unknown DOM property no-unknown-property
  • ⚠️ L712 React function has high control-flow complexity no-high-complexity-react-function
  • ⚠️ L727 Unknown DOM property no-unknown-property
  • ⚠️ L728 Unknown DOM property no-unknown-property
  • ⚠️ L729 Unknown DOM property no-unknown-property
  • ⚠️ L731 Array index used as a key no-array-index-as-key
  • ⚠️ L731 Unknown DOM property no-unknown-property
  • ⚠️ L731 Unknown DOM property no-unknown-property
  • ⚠️ L744 Unknown DOM property no-unknown-property
  • ⚠️ L749 Unknown DOM property no-unknown-property
  • ⚠️ L750 Unknown DOM property no-unknown-property
  • ⚠️ L751 Unknown DOM property no-unknown-property
  • ⚠️ L753 Unknown DOM property no-unknown-property
  • ⚠️ L753 Unknown DOM property no-unknown-property

src/pages.tsx

  • ⚠️ L42 Unknown DOM property no-unknown-property
  • ⚠️ L45 Unknown DOM property no-unknown-property

Reviewed by React Doctor for commit e0b47b4. See inline comments for fixes.

servers.push(server);
const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };
// The build's date, as the doclet passes it (--last-modified): the audit may read the clock; the renderer never does.
const theme = { lastModified: new Date().toISOString().slice(0, 10), ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs


const require = createRequire(import.meta.url);
const lockup = readFileSync(require.resolve("@elide/brand/assets/svg/elide-full-blend-dark.svg"), "utf8");
const [, , w, h] = /viewBox="([\d.\s]+)"/.exec(lockup)![1]!.trim().split(/\s+/).map(Number) as [number, number, number, number];

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-array-index-deref-without-bounds-or-empty-guard (warning)

This dereferences an array index result that can be undefined at runtime (empty list, no regex match, or a short split), which throws Cannot read properties of undefined. Guard with a length/emptiness check or optional chaining before the access.

Fix → An array index read is typed T but is T | undefined at runtime, so dereferencing it on an empty list, a non-matching regex, or a short split throws. Add a length/emptiness check or optional chaining before the access.

Docs

const label = currentSuiteLabel(list);
return (
<div class="suites">
<div class="suites-fit">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<div class="suites">
<div class="suites-fit">
{/* Empty and zero-wide, so that even a first label wider than the switcher moves to a second line. */}
<span class="suites-probe" aria-hidden="true" />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<div class="suites-fit">
{/* Empty and zero-wide, so that even a first label wider than the switcher moves to a second line. */}
<span class="suites-probe" aria-hidden="true" />
{list.map((entry, i) => <span key={i} class="suites-ghost" data-current={entry.current ? "" : undefined} aria-hidden="true">{entry.label}</span>)}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

)
: (
<section class="nav-section nav-reference">
<h2 class="nav-heading"><span>Reference</span></h2>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

: (
<section class="nav-section nav-reference">
<h2 class="nav-heading"><span>Reference</span></h2>
<ul class="nav-list">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<h2 class="nav-heading"><span>Reference</span></h2>
<ul class="nav-list">
{indexes.map(entry => (
<li key={entry.page}><a class="nav-row" href={entry.href} aria-current={entry.current ? "page" : undefined}><span class="nav-label">{entry.label}</span></a></li>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

return (
<Shell title={`Not found (${moduleTitle()})`} description={description} crumbs={[]} toc={[]} jsonLd={{ "@context": "https://schema.org", "@type": "WebPage", name: "Not found", description }}
meta={{ kind: "notfound" }}>
<header class="page-head">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<header class="page-head">
<h1>Not found</h1>
</header>
<div class="prose">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Bundle Report

Bundle size has no change ✅

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 6 potential issues.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Devin Review

Comment on lines +34 to +41
if (resolved.kind === "missing" && prefersMarkdown(accept)) {
return new Response(notFoundText(site.model, site.base, theme), { status: 404, headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept", "cache-control": "public, max-age=60" } });
}
if (resolved.kind === "missing") {
Astro.response.status = 404;
Astro.response.headers.set("cache-control", "public, max-age=60");
}
const page = resolved.kind === "missing" ? "404" : resolved.page;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Broken Markdown controls on Astro 404s

On an Astro error page, Route.astro serves HTML again when readers follow the 404.md link. The copy button also follows that link on a 404 instead of copying Markdown.

Learn more

The error page uses the regular page shell, which builds Markdown actions and links from the page name in PageActions. resolvePage recognizes a Markdown file only when its name is in the model's ordinary page map. The separate not-found page is not in that map, so a browser requesting the file reaches the HTML error branch. The copy control also rejects any non-2xx response before reading the body.

Example: Open /java/2.0/com/example/geo/Nope and choose “This page as Markdown.” /java/2.0/404.md returns the same HTML shell with status 404.

Recommended fix: Serve the explicit 404.md resource as Markdown with status 200, while retaining status 404 and Vary: Accept for negotiated responses at genuinely missing URLs.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +284 to +289
.suites-row { position: absolute; inset-inline-start: 0; inset-block-start: calc((32px - 100%) * 1000); display: flex; align-items: center; height: 32px; max-width: 100%; overflow: clip; column-gap: 2px; }
.suites-row a { padding-block: 5px; padding-inline: 9px; border-radius: var(--apidocs-radius); color: var(--apidocs-muted); white-space: nowrap; }
@media (hover: hover) and (pointer: fine) { .suites-row a:hover { color: var(--apidocs-fg); background: var(--apidocs-subtle); text-decoration: none; } }
.suites-row a:active { color: var(--apidocs-fg); background: var(--apidocs-subtle); text-decoration: none; }
.suites-row a[aria-current="true"] { color: var(--apidocs-accent); background: var(--apidocs-accent-soft); font-weight: 600; }
.suite-menu { position: absolute; inset-inline-start: 0; inset-inline-end: 0; inset-block-start: min(0px, calc((100% - 64px) * 1000)); height: 32px; }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Invisible keyboard stops in suite switcher

With JavaScript off, .suites-fit moves the unused switcher controls offscreen but leaves them focusable. Keyboard users tab to controls they cannot see.

Learn more

The two versions of the switcher are real interactive controls in SuiteSwitcher. Positioning one above the page does not remove it from sequential focus or the accessibility tree. The visibility rules depend on a data-fit value set by the boot script, so they do not apply without JavaScript.

Example: Open a wide documentation page with JavaScript disabled and tab through the site links. After the visible links, focus moves to the offscreen menu button.

Recommended fix: Make the inactive variant non-interactive in CSS without depending on the boot script. If layout cannot switch visibility reliably without JavaScript, show just one accessible disclosure by default and enable the dynamic row when JavaScript runs. Test the actual tab order with JavaScript disabled.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

html(NOT_FOUND, site.language, <NotFoundPage />);
out[`${NOT_FOUND}.md`] = frontmatter(site, { title: "Not found", kind: "notfound" }) + notFoundMarkdown(site, theme.baseUrl ?? "", indexPages(site));

out["llms.txt"] = llms(site, pages, guides, symbols, indexes, theme.whenToUse);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Usage guidance leaks across documentation sites

With shared models and different guidance, llms supplies content that wholeSite caches by model and symbol mode. The first site requested determines the guidance both sites serve.

Learn more

The Astro integration imports the configured model modules and stores a separate theme per site. Sites pointing at the same module share its exported model object; the sample Java versions already do this. renderText serves the cached llms.txt, whose content now depends on the theme's whenToUse. The key in wholeSite accounts for symbols but not the new input.

Example: Configure the Java release to say “Use this for production” and Java main to say “Use this for development.” Request the release's llms.txt first. Java main then serves the production guidance as well.

Recommended fix: Include the normalized whenToUse value in the cache key for llms.txt, or generate that file separately. Test two requests using the same model object, the same symbol mode, and different guidance.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +353 to +354
{/* The not-found page is served at whatever URL was missing, so its skip link names no file. */}
<a class="skip" href={meta?.kind === "notfound" ? "#content" : `${name}.html#content`}>Skip to content</a>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Static 404 skip link leaves page

On a static 404 with baseUrl configured, Shell sends the skip link to the site root. The <base> element resolves #content against that root, not the missing URL.

Learn more

The static error shell sets a <base> element so that assets and recovery links resolve correctly at any URL depth. That element also controls how browsers resolve fragment-only links. A skip link must target the same document to move focus to its main content.

Example: A static host serves the error page at https://docs.example.com/api/old/Type with a base of https://docs.example.com/api/. Activating the skip link navigates to https://docs.example.com/api/#content instead of staying on old/Type.

Recommended fix: Avoid <base> on the static error page by emitting its resource URLs and recovery links relative to the configured site root explicitly. Keep the skip link fragment-only and test it with the error document served at a nested missing URL.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +473 to +476
const marked = links.some(link => link.current);
const isOwnRoot = (url: string) => {
if (["", "./", ".", "index.html", "./index.html"].includes(url.trim())) return true;
if (!theme.baseUrl) return false;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Missing current site for empty URL

When a header link uses url: "", suites never receives that entry. safeTheme drops the empty string before the switcher can mark it current.

Learn more

The header-link contract allows an empty URL to identify the current site. safeUrl distinguishes an allowed empty string from a rejected URL by returning undefined only for rejection. safeTheme treats both results as a rejection before static or Astro rendering reaches the switcher.

Example: Configure User guide with its external URL and API reference with an empty URL. The switcher renders only User guide, with no current site marked.

Recommended fix: Preserve empty URLs for header entries by checking safeUrl against undefined. Add an end-to-end render test for an empty current-site URL rather than testing only the switcher helper.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +159 to +162
// For an agent deciding whether this is the reference it needs: the theme's words, or one sentence from the module's.
const what = guidesOnly ? "documentation" : "API reference";
const summary = overviewSummary(site);
lines.push("## When to use this", "", whenToUse?.trim() || `Use this ${what} when you write, read or review code that uses ${md(m.name)}${m.version ? ` ${md(m.version)}` : ""}.${summary ? ` ${md(summary)}` : ""}`, "");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Guidance links abort hosted documentation audits

When custom usage guidance links to sibling Markdown, llms exposes that link to mirrorSite. The mirror mistakes it for a local page and aborts when its extensionless URL fails.

Learn more

A publisher can supply arbitrary Markdown in the new ‘When to use this’ section. The remote audit command uses mirrorSite to discover generated pages before running checks. mirrorSite treats every relative .md destination as a generated page, requests an extensionless HTML URL, and throws unless that request returns 200.

Example: Add Read [the integration notes](https://github.com/elide-dev/components/blob/e0b47b499aa556e5d1b33f879cd0ad716a735967/../integration.md "../integration.md") first to the theme's usage guidance. The Markdown link works, but audit --url requests ../integration as a documentation page and stops when that route does not exist.

Recommended fix: Discover generated pages from the renderer's inventory sections or API model, not arbitrary prose links. Keep custom Markdown in the guidance and add a remote audit test that includes a sibling Markdown link.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@sgammon

Copy link
Copy Markdown
Member Author

React Doctor reports 38 warnings and no errors (Preact class/SVG attributes flagged as unknown properties, loops in the audit scripts); none is a defect in the rendered pages, so I left them as they are. The check passes. Chromatic's UI Tests status needs the visual changes accepted as the baseline; the owner has accepted them and the repository auto-accepts on main.

@sgammon
Sam Gammon (sgammon) merged commit 0e5bdf2 into main Nov 22, 2026
10 of 11 checks passed
@sgammon
Sam Gammon (sgammon) deleted the feat/apidocs-polish branch November 22, 2026 06:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant