Prologue

A while ago, I decided to develop a fully accessible main navigation component in React and write a series of articles documenting the steps it took to create a non-trivial accessible component.

In my last article, functionality for keyboard handling on a single list was added, and I discussed how a lot of keyboard handling was to aid those who perceive through a screen and operate through the keyboard; a combination I realized has not been commonly considered by many of the developers I've worked with.

This article focuses once again on the screen's perceivability, with design considerations at the forefront.

Note: This article is one of a series demonstrating how to build a React navigational component from scratch while considering accessibility through the process. The articles are accompanied by a GitHub repository with releases tied to one or more articles; each building on the previous, until a fully implemented navigation component is complete.

Each release and its associated tag contain fully runnable code for the article. The code discussed in this article is available in the release. and may be downloaded at release 0.4.0.

Examples have been updated in this release, enabling keyboard handling for a single list. Examples include a vertically aligned single list and horizontally aligned components with links and buttons for verifying operability.

While code examples are written in JavaScript for brevity, all actual code is written in Typescript and targets React 19.x. Examples use Next.js 16.x, which is not required to run the navigation component.

The design requirements for this release are available.

Follow along either by downloading the release and running the examples while examining the codebase, or by activating the link accompanying each code snippet to view the full file on GitHub.

This article is fairly long. It contains code and explanations. The code for this release is displayed, and the corresponding GitHub source is linked. Use these anchor links to move to the items of interest.

Content Links

• Introduction
• Layout
  • Top Row Layout
  • SubList Layout
    • Sharing Information
    • SubNavigation
• Appearance
  • Buttons and Links
  • SubLists
• Summary

Introduction

With an accessible HTML structure and the ability to transform objects into navigation, attention can finally be turned to styling. In this article, I'm focusing on the layout of the horizontal navigation, and then I'll apply some styling to buttons and links to achieve consistency and fit within the layout.

For all its promise, CSS has been notoriously difficult to create and maintain, relying on long chains of selectors to achieve specificity. These long selector chains hinder understanding and maintainability. Switching to nested CSS alongside structural HTML elements and implementing the @layer rule has been a boon, making it much simpler to create and maintain consistent layouts.

Any layout, whether component or page, needs to handle resizing without breaking proportions and styling, whether through browser zoom or when a user changes the base font size. Without a solid layout, any resizing required by WCAG success criteria 1.4.4 Resize Text is not achievable.

The image above, using the browser default font size of 16px, is unstyled except for the styling applied to the individual base components.

Even unstyled, resizing text doesn't break much, and a basic layout has been achieved thanks to the minimal CSS and theming applied to the base components. There's some shifting going on, but that will be handled as styles are applied.

Return to Content Links

Layout

Layouts are styled first, and while padding and positioning might need work later, even a rough layout helps.

Desktop navigation typically requires a top row laid out horizontally, with any sublists displayed vertically. So layouts for the top row and the sublist need to be styled separately.

Top Row Layout

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        --min-list-width: var(--sp-px);
        padding: calc(var(--sp-px) * 16) 0;

        & > ul {
            align-items: normal;
            justify-items: flex-start;
            column-gap: calc(var(--sp-px) * 24);

            & > li {
                display: flex;
                align-content: center;
                align-items: center;
                position: relative;

                & > button,
                & > a[href] {
                    padding-left: 0;
                }
            }
        }
    }
}

GitHub (release 0.4.0) - styledHorizontal.css

A horizontal navigation can be considered a system component, so its styling is placed in the system-component layer. In a nested CSS structure, everything can be styled with a single class applied to the top-level element, in this case <nav />. Top and bottom padding are applied to the nav element to provide some space. A design token --min-list-width, to be discussed later, is set purely as a default.

Working on the top row first, rules are set for the nav element's only direct descendant, the topmost unordered list; The list element already sets display: flex and the basics for both horizontal and vertical displays, so the only necessary rules here are around alignment and setting a 24 relative-pixel column gap. Only list items that are directly descended from the element's top unordered list are given position: relative and have some flex alignment rules applied. The top-row buttons and links remove any left padding.

Now, a straight, horizontal line can be drawn at the element's base to verify that the top row links and the button text are aligned. Spacing is consistent across the top row, and with a 24 relative-pixel column gap, there is plenty of room between the focusable elements to meet WCAG success Criterion 2.5.8, Target Size (minimum).

Return to Content Links

SubList Layout

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        /* Top Row nav > ul > li */

        & > ul {
            ... & > li {
                position: relative;

                ...
                    /* sub navigation (not top row) */

                & > ul {
                    min-width: calc(var(--sp-px) * var(--min-list-width));
                    padding: 0;
                    position: absolute;
                    top: calc(var(--sp-px) * 36);
                    width: fit-content;
                    z-index: 3;

                    & li {
                        width: 100%;

                        &:first-child {
                            padding-top: calc(var(--sp-px) * 8);
                        }

                        &:last-child {
                            padding-bottom: calc(var(--sp-px) * 8);
                        }
                        & button,
                        & a[href] {
                            display: flex;
                            flex-direction: row;
                            flex-wrap: nowrap;
                            justify-content: flex-start;
                            padding:
                                    calc(var(--sp-px) * 8)
                                    calc(var(--sp-px) * 16)
                                    0
                                    calc(var(--sp-px) * 8);
                        }
                    }

                    & ul {
                        padding: 0 calc(var(--sp-px) * 16) 0 0;
                        position: relative;

                        & > li {
                            padding-left: calc(var(--sp-px) * 16);
                        }
                    }
                }
            }
        }
    }
}

GitHub (release 0.4.0) - styledHorizontal.css

Sharing Information

Subnavigation lists can be styled as a direct unordered list descended from any list item in the top row. These lists are positioned as absolute, tied to their top-row list item, which is set to a relative position. Subsequent unordered lists are repositioned as relative, and the first and last list items within the subnavigation list receive extra vertical padding. Most of the padding is applied to the button and the link, along with flex styling.

The unordered list containing all subnavigation beneath a top-row button has a minimum width set via the design token --min-list-width. While a default was added, the question becomes, where is this token actually set?

I touched on this technique when discussing the Icon component in my article on base components, using the style attribute to communicate information between JavaScript and CSS. In this case, I want to guarantee the minimum width for a sublist is the same as the width of its button in the top row. So modifications need to be made to the SubNavigation component.

SubNavigation

export default function SubNavigation({...}) {
   ...

  const [isSubListOpen, setIsSubListOpen] = useState(false);
  const [listWidth, setListWidth] = useState(1);

  …
  useLayoutEffect(() => {
    setListWidth( buttonRef.current!.offsetWidth);
  }, [buttonRef, setListWidth]);

  ...

  const listItemProps = {
    cx: cx,
    style: { "--min-list-width": listWidth } as CSSProperties,
  };

  …
}

GitHub (release 0.4.0) - SubNavigation.tsx

A listWidth is set up in state, and a useLayoutEffect calls a function to set the list width, passing the buttonRef and dispatch to a custom utility function. The result is sent to the ListItem's style attribute through the design token, and the sub-list defined in SubNavigation uses the token to set a min-width.

You'll note the use of useLayoutEffect in the code. It is a synchronous function that runs only after React has performed all DOM mutations, but before the browser repaints, making it useful for DOM measurements. In this case, I'm using the button's offsetWidth property as the value for the design token I'm passing to the list item's style attribute.

I'm not a fan of pushing a lot of styles through the style attribute, but I do find it useful to send information only available to JavaScript to CSS.

export const setSubListWidth = (refObject, setListWidth) => {
  setListWidth(refObject.current?.offsetWidth);
};

GitHub (release 0.4.0) - utilities.ts

The read-only offsetWidth property is available on any HTML element. It returns a pixel measurement of an element's width, including borders and padding. Sublists can use the returned width, as defined by the top-row button, to set a relative pixel width, guaranteeing the list appears at least as wide as the button that controls it.

While nothing appears to be broken at any browser font size, it's hard to tell whether the layout is correct without applying other styles.

Return to Content Links

Appearance

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        --min-list-width: var(--sp-px);
        padding: calc(var(--sp-px) * 16) 0;

        /* Top Row nav > ul > li */

        & > ul > ul {
            gap: unset;
        }

        & li {
            white-space: nowrap;

            & button,
            & a[href] {
                background-color: transparent;
                border-color: transparent;
                border-radius: 0;
                border-width: calc(var(--sp-px) * 1);
                color: var(--component-text-color);
                width: 100%;
                text-align: left;
            }
        }
    }
}

GitHub (release 0.4.0) - styledHorizontal.css

Buttons and Links

The component-level gap is unset for each ul directly descended from the top-level ul, and buttons and links have their appearance standardized. Background and border colors are set to transparent, allowing the elements to blend into the designated background color. A border-width is applied, along with a transparent border color, to prevent state changes from causing label shifting. Colors are applied through the theming system.

I want buttons and links to take up the entire list item, so the width is set to 100%. This increases the target size to that of the list item, which, while also visually appealing, conforms to WCAG success Criterion 2.5.8, Target Size (minimum).

Some changes to the underlying component styling are necessary. A gap originally set up in the styles associated with the list component is unset, and text alignment is reset to left instead of the original button style of center. Additionally, any item within a list item is set to keep text on a single line rather than wrap over multiple lines.

Return to Content Links

The styling is showing promise, but there's still more to do with the sublists.

SubLists

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */

        ...& > ul {
            ...
        }
        ...
        & > ul {
            & > li {
                & button,
                & a[href] {
                    font-weight: 500;
                }

                & > ul {
                    background-color: var(--theme-background);
                    border-color: var(--component-border-color);
                    border-style: solid;
                    border-width: calc(var(--sp-px) * 1);

                    & button,
                    & a[href] {
                        font-weight: 400;
                    }

                    & ul {
                        border-color: transparent;
                    }

                    & > li {
                        font-weight: normal;
                    }
                }
            }
        }
    }
}

GitHub (release 0.4.0) - styledHorizontal.css

A background for links and buttons is finally applied, so text under the absolutely positioned sublists no longer bleeds through. Font weights are applied along with a border.

Is it perfect? There's always more to do, but both the top row and the displayed sublists are readable, and each focusable element in the sublists has a target area larger than the minimum target size.

It also looks consistently proportioned when the browser font size is increased.

Return to Content Links

Summary

The initial layout of a horizontal navigation component is simplified by nesting the CSS under a single class and using direct descendant selectors to target the top row and its sublists. Layout is separated from appearance, and the component remains consistent in proportions and ratios when a larger browser font is applied.