Components
Side Navigation - Design decisions
What is an ADR?
We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.
ADR 001 - Mobile component considerations
- Decision date: June 18, 2025
Context
We are building a navigation component intended for use on the web. During early planning, we evaluated whether we should also create a corresponding native mobile component to support consistency across platforms.
Decision
After discussions with the mobile team, it was determined that a native mobile navigation component is not required for the MVP. The mobile team confirmed that they do not have an immediate need for it, so we will focus efforts solely on the web implementation.
Consequences
For responsive web experiences, the side navigation will transition into a top-level accordion-style menu on smaller screen sizes, instead of a drawer. This will allow the component to remain accessible and functional. We chose this because the design system has this as an established interaction pattern.
ADR 002 - USWDS considerations
- Decision date: June 18, 2025
Context
The VA.gov Design System typically leverages components and patterns provided by the U.S. Web Design System (USWDS) to maintain consistency with federal design standards and reduce duplication of effort.
Decision
We reviewed the USWDS side navigation component but decided not to fully adopt their implementation. VA.gov’s existing design and user experience for side navigation already diverge from USWDS patterns. The component has the same structure and the design is influenced by USWDS but the colors are different on the links and we added the addition of categories (spokes).
Markup change from USWDS: We used <div> elements with list roles instead of standard semantic HTML list elements because of technical limitations in how the navigation component is built as a web component. Since the component is made up of multiple sub-components, each with its own shadow root, the child <li> elements are unable to reference or communicate with a parent <ul>. This means the typical semantic relationship between list items and their parent list cannot be established, so we applied appropriate ARIA roles to <div> elements to maintain accessibility.
ADR 003 - Side nav linking to an anchor on the same page
- Date raised: June 11, 2025
Context
During the architecture review, a question was raised about whether the side navigation component should support menu options that link to anchors within the same page (i.e., in-page navigation).
Decision
We decided not to support anchor link functionality in V1 of the component. This decision was based on the absence of a clear use case for in-page navigation within the MVP scope. All expected use cases for V1 involve navigating between distinct pages, not within a single page.
Consequences
- No known MVP use cases require in-page anchor links
- Reduces complexity for the initial release
- Keeps the component focused on page-to-page navigation for now, with the option to revisit this feature in future iterations if a need arises
ADR 004 - The nav region needs an accessible name
Context
The side navigation needs an accessible name to help users who rely on screen readers or other assistive technologies understand what the navigation is for.
Decision
To ensure a consistent and recognizable experience for all users, we decided to use the name “Related pages menu” across all implementations of the side navigation. This text is applied as both visible and invisible text, helping all users identify the navigation’s purpose no matter where they encounter it on the website.
ADR 005 - Two levels deep
- Decision date: June 23, 2025
Context
The initial version of the side navigation component is being created to support a new category in Profile: Communication Settings, which includes two child links. Currently, the VA.gov side navigation supports up to five levels of nesting. However, the Profile use case only requires one level of depth at this time.
Decision
For this implementation, the side navigation will support up to two levels deep. This approach aligns with the immediate needs of the Profile use case and avoids complexity in the MVP.
Consequences
We may expand support for deeper nesting in a future iteration based on broader requirements. If future enhancements change the design or structure of the component, the Profile team will be responsible for adopting those updates as needed.
ADR 006 - Focus style
Context
Focus style for the Side Navigation component is pending discussion and decision.
Decision
Decision pending.
ADR 007 - Categories / Spokes
- Decision date: June 14, 2025
Context
In the current structure of VA.gov facility pages, we utilize what we’ve referred to as categories or spokes to organize links and content. These items are not treated as headings because they do not have a corresponding parent page — they are simply used to group related links or sections for ease of navigation and scanning.
This design is intentional and distinguishes category/spoke items from traditional navigation items that are nested under a parent route or page. It allows flexibility in organizing links without requiring additional content creation or page hierarchy.
Decision
We will include categories/spokes as an option in the Side Navigation component for Profile and will continue having it as an option for facility pages which have similar layouts.
- There is no parent page for these groupings
- These are visual and organizational aids
- This pattern is already in use on facility pages and supports user understanding without breaking accessibility or hierarchy rules
Consequences
This decision maintains consistency across VA.gov facility pages.
ADR 008 - Will not implement accordion expand / collapse in navigation
- Decision date: June 14, 2025
Context
During development of the new side navigation component, a question was raised about whether the navigation should support accordion-style expand/collapse behavior for nested links. For the MVP version of the side navigation, this functionality is not required.
Decision
We will not implement accordion-style expand/collapse behavior in the side navigation for the MVP release.
Rationale:
- Not needed for MVP use cases — current navigation structures are flat
- Unclear behavior expectations — especially around keyboard navigation, focus management, and screen reader handling
- Accessibility concerns — expandable/collapsible regions introduce complexity and risk unless implemented with careful ARIA and focus patterns
- Usability concerns — accordion patterns in navigation can create confusion and require extra interactions for users to discover content
Consequences
The MVP will have a simple, static side navigation with all links shown. Future enhancements can revisit accordion behavior if a strong use case arises.
ADR 009 - Composability implementation API
Context
The component’s API follows a composability pattern to allow flexible assembly of navigation items.
Decision
See the
ADR 010 - Automatically adding #content anchor to URLs
- Decision date: June 14, 2025
Context
When navigating to a new page or reloading content on VA.gov, the URL automatically includes the anchor #content. This behavior ensures that keyboard and screen reader users are directed immediately to the main content area, skipping repetitive navigation and banner elements.
Decision
We will automatically add #content to the URL when routing or updating the page. This ensures consistency with VA.gov behavior and improves accessibility by maintaining a consistent experience across VA.gov applications.
ADR 011 - Adding props for customizing mobile header, aria-label, and exposing accordion parts
Context
Props were added for customizing the mobile header and aria-label. Additional props were added for experimenting with the sidenav component as a stepper component. This includes exposing va-accordion parts for styling customization.
Decision
We added props for the nav element aria-label and optional mobile header-specific content, and exposed va-accordion parts for styling customization.
See