chore(website): report Nimbus scaffold defects flagged in #42 upstream #43

Summary

AI reviewers (cubic, Greptile) on #42 flagged 25 defects in files that the Nimbus scaffolder (@cloudflare/create-nimbus-docs, templates-v0.7.13, @cloudflare/nimbus-docs 0.18.1) generated into website/src/. #42 keeps those files byte-identical to upstream so nimbus-docs outdated / nimbus-docs diff --apply upgrades stay clean, so they were declined there rather than patched locally.

The findings look valid. Several affect this site directly: search result a11y, breadcrumb separators read aloud, the code-block language badge on hover, mobile heading offset under the sticky TOC bar, and the empty-slug TOC link.

Proposed handling

1. Re-check each item against the latest Nimbus templates (bunx @cloudflare/nimbus-docs outdated). Some may already be fixed upstream.
2. Report the remaining ones to https://github.com/cloudflare/nimbus.
3. Pick the fixes up with nimbus-docs diff --apply. Patch locally only when a defect visibly hurts this site and upstream doesn't respond.

Findings

• src/components/ui/search/search.client.ts:69 — P2: The role="option" element contains focusable <a> links (the title link and sub-result links). Options must have presentational children, so screen readers will not expose these links correctly. Put the link inside a non-option wrapp (thread)
• src/components/ui/dialog/dialog.client.ts:12 — P2: Backdrop close checks only the click target, so drag-selecting search text that starts in the input and releases on the backdrop closes the search dialog. Record the pointerdown target and close only when the press also started on t (thread)
• src/layouts/DocsLayout.astro:29 — P2: Draft pages are marked noindex in BaseLayout, but this searchability check ignores draft, so drafts still appear in Pagefind results by default. Include draft in the default exclusion. (thread)
• src/styles/globals.css:434 — P2: The hover rule .nb-code-figure:hover::before has lower specificity than the badge rule it targets, so opacity: 0 never applies and the language badge stays visible on hover. Add :hover to the badge selector so it wins the cascade. (thread)
• src/components/ui/aside/Aside.astro:21 — P2: An unrecognized type falls back to the Note colors and label, but no icon renders because the icon checks compare the raw type. Normalize the type once and use it for both the config lookup and the icon branches. (thread)
• src/styles/prose.css:60 — P2: Unlayered prose rules beat Tailwind v4 utilities, so the comment's claim that mt-6/my-4 overrides work is wrong. The margin: 0; font-size: inherit boundary rule will also flatten classed text-*/mt-* utilities on p/h1–h6 in (thread)
• src/components/ui/image-zoom/ImageZoom.astro:41 — P2: The > img child combinator misses images wrapped in <picture>. The trigger's direct child is then the <picture>, so the sizing rule never applies in aspect-ratio Frames. Use a descendant selector so the rule reaches the img. The w (thread)
• src/components/ui/banner/banner.client.ts:20 — P2: Dismissed banners flash on full page loads: this script removes them only after the deferred module runs, so the banner paints first and then disappears. Apply the stored dismissal in a blocking is:inline script in Banner.astro, as (thread)
• src/components/ui/steps/Steps.astro:70 — P2: Tight list items with inline markup break the step layout. Only direct element children get grid-column: 2, so bare text nodes (for example Run <code>npm install</code>.) are auto-placed into column 1 under the number circle. Use a (thread)
• src/components/ui/button/variants.ts:33 — P2: The destructive variant hardcodes text-white on bg-danger. In dark mode --nb-danger is a light salmon red (about rgb(255,100,103)), so the label is roughly 2.9:1 contrast, below WCAG AA. Fix the dark-mode foreground pairing in ` (thread)
• src/components/ui/search/providers/pagefind.ts:47 — P2: The versioning comment describes an opt-in that this provider does not implement. search accepts no filter argument and always excludes deprecated-version pages, so readers on a deprecated version cannot find their docs through search (thread)
• src/components/ui/toc/toc.client.ts:169 — P2: At the page bottom, this selects the last TOC entry even when its heading has no DOM target, so an emoji-only final heading is shown as active despite having no scroll target. Select the last observed heading index instead. (thread)
• src/components/ui/tabs/Tabs.astro:28 — P2: Manual tabs render their triggers outside the always-generated empty tablist, leaving the tab semantics and indicator disconnected. Make the generated list optional or provide a slot for caller-supplied triggers. (thread)
• src/components/ui/search/search.client.ts:171 — P3: Home and End are intercepted even when there are no results, so they can't move the caret in the query input. Only prevent default when there are options to navigate, e.g. guard both branches with options.length > 0. (thread)
• src/components/ui/theme-toggle/ThemeToggle.astro:26 — P3: The hardcoded data-nb-state="light" and aria-pressed="false" are wrong for users in dark mode until the deferred client script runs. The pre-paint script in BaseLayout runs in <head> before the button exists, so it never correct (thread)
• src/components/ui/code/Code.astro:36 — P3: The as Props cast is justified by a shiki version skew that website/bun.lock does not contain. The lockfile resolves a single shiki/@shikijs/types 4.5.0. Remove the cast and let astro check validate this boundary. Keep it only (thread)
• src/components/ui/code/Code.astro:18 — P3: defaultColor: false overrides any defaultColor the caller passes, while caller theme/themes are respected. Fall back to false only when the caller omits it. (thread)
• src/components/ui/page-actions/page-actions.client.ts:22 — P3: The error branch of showState doesn't reset the icons. If a previous copy succeeded within the last 1.5s, the check icon stays visible next to "Couldn't copy". Set both icon states from one flag so each state shows the right icon. (thread)
• src/pages/nimbus-api/coordinates.json.ts:15 — P3: This Cache-Control header has no effect: the route is prerendered with output: 'static', which drops endpoint response headers, and no public/_headers file sets the policy. Either remove the header and its comment, or add `website (thread)
• src/components/ui/steps/Steps.astro:31 — P3: The custom counter ignores the native start attribute on a markdown <ol>. A list written as 3. renders starting at 1 because only the start prop feeds --steps-start. Read the start attribute on the ol (or document that onl (thread)
• src/components/ui/button/Button.astro:19 — P3: The doc comment points to \~/components/ui/link-button, but this repo only defines the @/ alias. Change the path to @/components/ui/link-button so the reference can be copied and resolved. (thread)
• src/components/ui/breadcrumbs/Breadcrumbs.astro:38 — P3: The / separators are read aloud by screen readers because they are not hidden from the accessibility tree. Add aria-hidden="true" to each separator span; the collapsed and tail separators need the same change. (thread)
• src/components/ui/tabs/tabs.client.ts:33 — P3: Use setAttribute("role", "tab") here. It matches the other attributes set in this function and the role="tab" markup in TabsTrigger.astro. (thread)
• src/components/ui/toc/TOC.astro:62 — P3: The desktop TOC renders empty-slug headings as href="#", so selecting one jumps to the top instead of a section. Filter headings without slugs before rendering, as MobileTOC does. (thread)
• src/styles/prose.css:93 — Section headings hide behind navigation On phones and tablets below 80rem, section jumps place headings behind the sticky “Jump to section” bar. The 5rem offset clears the header, but the header and mobile TOC together occupy about `7. (thread)

Source: #42