Tabs - 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 - Tab definitions

• Date raised: December 8, 2023
• Decision date: April 15, 2025

Context

These definitions are based on the original component submissions and informed by terminology used in other design systems. They clarify the structure and elements within a tab component.

Decision

Tabs anatomy

• Tabs: The entire component consisting of multiple tab items, typically used to navigate between sections of content.
• Tab (Horizontal or Vertical Tab): An individual tab within the tabs component, arranged horizontally or vertically within the popover.
• Selected Tab: The currently active tab, either clicked or navigated to via keyboard.
• Unselected Tab: A tab that is not currently active.
• Divider: A horizontal line running beneath the tabs, typically full-width, that visually separates the tab row from the content below.
• Dropdown Button: A button within the tab row that triggers the display of additional tab items not shown in the primary row.
• Open: When the dropdown is open.
• Closed: When the dropdown is closed.
• Popover: A floating panel that appears when the dropdown button is activated, containing overflow tab items.
• Tab Count: The number displayed on the dropdown button indicating how many additional tab items are hidden in the popover.

Consequences

Clear and consistent naming reduces future design debt. Establishing terminology early helps streamline communication and decision-making across design and development teams.

ADR 002 - Behavior when tabs overflow off the screen

• Date raised: December 8, 2023
• Decision date: April 15, 2025

Context

When the experimental design was originally presented, three options were proposed to handle tab overflow on smaller screens:

1. Stack tabs vertically
2. Enable horizontal scrolling
3. Move excess tabs into a dropdown

Each approach had pros and cons. Prototypes were created for each approach.

Decision

Tab Overflow Behavior: Option 3 (Dropdown) was selected. This option offers a cleaner interface and supports future expandability. While research indicates dropdowns may limit discoverability, the team believes the specific use case here mitigates that risk.

Dropdown Text: The dropdown will be labeled “More”. Alternatives like “Menu” were considered, but a design system audit showed “More” is more common.

Dropdown button: The dropdown button will use a ghost version of the VADS button with a trailing icon that toggles directions when clicked, similar to the Additional Info component.

Dropdown Count: A numeric count will be added to the “More” button to show how many tabs are hidden (e.g., “More (3)”). This helps users understand that additional tabs exist.

Custom Dropdown vs. Browser Select: A custom dropdown will be implemented. The browser’s native select component limits styling and accessibility. Tabs require styling for active, hover, focus, and link states which are not supported in native dropdowns.

Flex layout: The tabs layout will switch from a left-aligned margin layout to a flex layout when the dropdown is used. When the dropdown is used we know that space is limited, so the flex layout shows more tabs on screen in constrained widths.

Minimum dropdown tab count: The dropdown should only be used if there are more than two overflow tabs. Avoid using a dropdown to replace a single tab.

Consequences

This solution has not yet been tested with users. Further usability research will be needed to validate whether users understand and use the dropdown effectively.

ADR 003 - Tab style choices

• Date raised: December 8, 2023
• Decision date: May 9, 2025

Context

The proposed experimental design included tabs already in production. A design discovery and audit were conducted to ensure alignment with the VA Design System and web best practices. Adjustments were made based on these findings. Tabs with similar overflow interactions were also reviewed from other design systems.

Decision

Tabs component

1. Divider: Gray line that spans all tabs in the same outline color as cards.
2. Space Between Tabs: 24px of space when a dropdown isn’t used. If the dropdown is used, the layout changes to a flex layout with space-between.
3. Indentation: The tabs component should have no left, right, or top and bottom margin, remaining flush with the edges of the page container.

General tab styles

1. Unselected Tab: No underline. Tabs are treated as navigation elements like side nav or main menu. The VA primary link color will be used with a normal font weight.
2. Hover State: Same gray background and hover style as VA side nav and VA links.
3. Selected Tab: 4px border on bottom for horizontal tabs and on the left side for vertical tabs in the VA primary color. The text styles will be bold text in the base text color.
4. Focus State: Matches standard VA focus state for buttons and links.
5. Text Overflow: Wraps to two lines if necessary.
6. Line Height: Matches line height used in buttons.

Tabs - Horizontal styles

1. Padding: 8px horizontal, 16px vertical (minimum 44px height and width).
2. Max Width: 144px (ensures two tabs fit on 320px screens).
3. Min Width: 64px (meets accessibility standards and optimal size for touch targets).

Tabs - Vertical styles

1. Spacing: 16px padding on all sides.
2. Divider: No divider is used between the tabs within the popover.
3. Text Overflow: Wraps to two lines if needed.
4. Max Width: 288px (minimum width of VADS components).
5. Min Width: 128px (width of dropdown button).

Dropdown button

1. Icon: Uses the expand_less/expand_more icons from the VADS, consistent with expandable alerts.
2. Spacing: Uses the VADS button to match spacing and design.
3. Text: Uses the word “More” (based on audit findings).
4. Hover/Active/Focus States: Use the same states as the tabs.
5. Dropdown Count: Numeric count shown in parentheses (e.g., “More (3)”). Badge design was considered but deferred for MVP.
6. Width: Set to 128px since the text within the button is fixed.

Popover

1. Padding: 8px (top and bottom).
2. Margin: 0px (top).
3. Border Radius: 8px on all corners.
4. Border & Shadow: Matches card component styles.
5. Max Width: 288px (standard VA minimum component width).
6. Min Width: 128px (the max width of the dropdown button).

Consequences

The tab component has many interactive and visual elements. Given the complexity, inconsistencies or unforeseen use cases may arise, and the design may need future refinement.

ADR 004 - Consistent popover styles

• Date raised: May 12, 2025
• Decision date: May 23, 2025

Context

We currently have 3 components that have a popover: Combo Box, Search Input with typeahead, and Tabs. With a growing list of popover components we decided to align to a single popover design to create consistency between components.

Decision

We will use the Combo Box popover design for the popover in the Tabs component.

Style changes to the popover:

1. Border color: vads-color-base-dark token
2. Border radius: No border radius
3. Shadow: No shadow

Consequences

We created a ticket to add a popover component to the Design System so that we can use it for future components and move all the current components like the Search Input and the Combo Box to the popover component.

Once the popover component is completed, we will need to revisit the tabs and move the tabs popover to the popover component, which might create additional work later on.

ADR 005 - Focus styles

• Date raised: April 1, 2025
• Decision date: June 2, 2025

Context

We’re updating focus styles across the VA to use a 4px bottom border for sufficient contrast on both light and dark backgrounds. However, tabs also use a 4px bottom border to indicate selection, making the focus and selected states too similar.

To differentiate focus from selection, we explored three options:

• Option 1: Increase the selected tab’s bottom border to 6px, keeping focus at 4px.
• Option 2: Add a 2px dark border around the tab on focus.
• Option 3: Use the USWDS blue outline for focus.

Decision

We chose Option 2: adding a 2px dark border around focused tabs. This provides clear differentiation while maintaining consistency with the overall design.

Consequences

This change introduces a new focus style for tabs, diverging from other components, which do not currently use an outer border for focus.

ADR 006 - Limiting tabs to 3 or less

• Date raised: July 2, 2025
• Decision date: July 14, 2025

Context

Following an accessibility review of the tabs component, concerns were raised about the overflow behavior — specifically the use of a “more” button to handle excess tabs. An audit of current tabs usage in production found no strong use cases requiring more than three tabs.

Decision

We will limit the initial implementation of the va-tabs component to three or fewer tabs. We will not implement a tab overflow solution (e.g., a “more” dropdown) in version 1.

We will still address accessibility and usability concerns for limited tabs at 400% zoom or in constrained viewports.

Consequences

There will most likely be a need to solve for more than 3 tabs in future. This could cause more time to develop and implement this interaction when the need arises.

ADR 007 - Adding horizontal scrolling for tab overflow

• Date raised: July 24, 2025
• Decision date: July 24, 2025

Context

At times, the tabs list will be wider than the viewport. This usually happens when users zoom in, resize text, or when teams create tab lists that are longer than recommended. To keep the component accessible, we needed to make sure users can always see and navigate to every tab item in the list.

Decision

After considering a mix of options including a collapsible menu, we chose horizontal scrolling to manage tab overflow. This solution is straightforward, accessible, and works well with screen readers and keyboard navigation. If users follow our guidance to limit tab count and keep labels short, horizontal scrolling will only be needed at high zoom levels or in constrained viewports.

Consequences

If teams need a tabs component that supports more tabs or longer labels, we may need to revisit this functionality.

ADR 008 - Switching from URL navigation to on-page navigation

• Date raised: July 13, 2025
• Decision date: July 22, 2025

Context

While defining accessibility requirements for the tabs component, we found important differences in how assistive technologies interact with different tabs implementations:

• In one interpretation, tabs act as horizontal navigation: tab items load new pages, are navigated using the Tab key, update the URL, and are not programmatically linked to their content.
• In the other, tabs organize page content: these tabs use arrow keys for keyboard navigation, show or hide content without refreshing the page, and the content panels are directly associated with the active tab.

Decision

We reviewed guidance from MDN and W3C/APG and decided to treat tabs as content rather than navigation. Tabs have specific accessibility expectations, including keyboard navigation, focus management, and the type of content shown. Because we chose not to build a navigation component, we did not add URL management to the tabs component. This follows common patterns seen in other implementations and prevents the complexity of recreating and maintaining native browser page load behavior.

Consequences

This approach makes the tabs component more accessible and easier to use. It avoids the complexity of managing URLs and page refreshes, and sets clear expectations for teams. Teams who need navigation features can use other components designed for that purpose.