Skip to content

feat(docs): update navigation components for improved accessibility and structure #3517

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hannahiss wants to merge 2 commits into
base: ouds/main
Choose a base branch
from
Open

feat(docs): update navigation components for improved accessibility and structure #3517

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1234bb5
feat(docs): update navigation components for improved accessibility a…
hannahiss Apr 16, 2026
5017408
Merge branch 'ouds/main' into ouds/main-mobile-overflow
hannahiss Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 18 additions & 23 deletions site/src/components/header/SubNav.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,27 @@
---
import { getVersionedDocsPath } from '@libs/path'

const slug = Astro.url.pathname.split('/')[4]

const sidebarMap = {
'getting-started': 'Getting started',
foundation: 'Foundation',
components: 'Components',
utilities: 'Utilities',
layout: 'Layout'
}
Comment on lines +4 to +12
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

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

sidebarMap[slug] only covers a subset of top-level docs sections, so on pages like /about/* or other slugs not listed, the UI will render Browse docs: with an empty section label (and the visually-hidden label will also be empty). Consider adding the missing sections (e.g. about) and/or providing a fallback label + conditional rendering of the colon only when a section title is available.

Copilot uses AI. Check for mistakes.
---

<!--OUDS mod: doesn’t exist anymore in Bootstrap-->
<nav class="bd-subnavbar py-small d-lg-none" aria-label="Secondary navigation">
<div class="container-fluid container-max-width d-flex justify-content-end">
<button
class="btn btn-default btn-icon"
type="button"
data-bs-toggle="offcanvas"
data-bs-target="#bdSidebar"
aria-controls="bdSidebar"
aria-label="Toggle docs navigation"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
class="bi"
fill="currentColor"
viewBox="0 0 16 16"
aria-hidden="true"
>
<path
fill-rule="evenodd"
d="M1 8a.5.5 0 0 1 .5-.5h13a.5.5 0 0 1 0 1h-13A.5.5 0 0 1 1 8zM7.646.146a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1-.708.708L8.5 1.707V5.5a.5.5 0 0 1-1 0V1.707L6.354 2.854a.5.5 0 1 1-.708-.708l2-2zM8 10a.5.5 0 0 1 .5.5v3.793l1.146-1.147a.5.5 0 0 1 .708.708l-2 2a.5.5 0 0 1-.708 0l-2-2a.5.5 0 0 1 .708-.708L7.5 14.293V10.5A.5.5 0 0 1 8 10z"
></path>
</svg>
<div class="container-fluid container-max-width d-flex justify-content-start">
Copy link
Copy Markdown
Member

@louismaximepiton louismaximepiton Apr 17, 2026

Choose a reason for hiding this comment

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

To discuss, but I'd have kept the button on the right I think

Suggested change
<div class="container-fluid container-max-width d-flex justify-content-start">
<div class="container-fluid container-max-width d-flex justify-content-end">

<button class="btn btn-default" type="button" data-bs-toggle="offcanvas"
data-bs-target="#bdSidebar" aria-controls="bdSidebar">
<svg aria-hidden="true">
<use xlink:href={`${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#outgoing')}`}></use>
</svg>
<span class="d-none d-sm-inline">Browse docs: {sidebarMap[slug]}</span>
<span class="d-sm-none">Browse docs</span><span class="visually-hidden">{sidebarMap[slug]}</span>
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

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

On the mobile label, Browse docs and the visually-hidden section name are rendered in adjacent spans with no separating whitespace, which can be announced as a single word by screen readers. Add a separator (space/punctuation) in the accessible name, or restructure to render a single combined label with parts visually hidden per breakpoint.

Suggested change
<span class="d-sm-none">Browse docs</span><span class="visually-hidden">{sidebarMap[slug]}</span>
<span class="d-sm-none">Browse docs</span><span class="visually-hidden">: {sidebarMap[slug]}</span>

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@louismaximepiton louismaximepiton Apr 17, 2026

Choose a reason for hiding this comment

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

Maybe Browse [slug] would be better here ?

</button>
</div>
</nav>
2 changes: 1 addition & 1 deletion site/src/components/home/MastHead.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import Code from '@components/shortcodes/Code.astro'
/>
</div>

<div class="d-flex mb-scaled-medium gap-medium">
<div class="d-grid d-md-flex col-12 col-sm-7 me-auto mb-scaled-medium gap-medium">
<a href={getVersionedDocsPath('getting-started/introduction')} class="btn btn-strong">
<svg class="bi me-small" aria-hidden="true">
<use xlink:href={getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#book-half')}></use>
Expand Down
2 changes: 1 addition & 1 deletion site/src/layouts/DocsLayout.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ const multipleComponents = componentsVersions.length > 1 ? 's' : ''
frontmatter.toc && headings && headings.length > 0 && (
<h2 class="mb-none" id="docs-toc">
<button
class="btn btn-default p-md-none mb-small mb-md-none text-decoration-none bd-toc-toggle d-md-none"
class="btn btn-default p-md-none mb-small mb-md-none text-decoration-none d-md-none"
type="button"
data-bs-toggle="collapse"
data-bs-target="#tocContents"
Expand Down
13 changes: 0 additions & 13 deletions site/src/scss/_toc.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,19 +53,6 @@
}
}

.bd-toc-toggle {
display: flex;
align-items: center;
border-width: 1px; // OUDS mod

@include media-breakpoint-down(sm) {
justify-content: space-between;
width: 100%;
}

// OUDS mod: no `@include media-breakpoint-down(md)`
}

.bd-toc-collapse {
@include media-breakpoint-down(md) {
nav {
Expand Down
4 changes: 4 additions & 0 deletions site/static/orange-compact/docs/[version]/assets/img/ouds-web-sprite.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions site/static/orange/docs/[version]/assets/img/ouds-web-sprite.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions site/static/sosh/docs/[version]/assets/img/ouds-web-sprite.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading