DEV Community: ShaynaProductions

Laying it all out on the Vertical

ShaynaProductions — Tue, 02 Jun 2026 12:15:00 +0000

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, I covered creating the underlying data structures for supporting keyboard handling between components.

This article, along with its accompanying release, focuses on the design and styling of a navigation component whose first row is laid out vertically, consistent with mobile navigation.

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.5.1.

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.

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
Focusable Element Standardization
Separators and Weights
Summary

Introduction

Earlier, I went through creating layouts for a navigation component suitable for desktop or laptop widths. This time, I want to focus on a layout for the same component that is suitable for mobile devices.

Between my insistence that all my flow-control elements (those that always begin on a new line when the default positioning of static is applied) default to no specific width of their own and my use of nested CSS to style, I'm finding it much easier to achieve layouts.

In my experience, the longer a website has existed, the more fragile its CSS becomes. Whether the CSS is styled in separate sheets or inside the components, it becomes a struggle to keep everything consistent. Multiple classes are chained together, and name-spaces are prepended onto them in an attempt to stop one style from stepping onto another. Styling within a component seems simpler, but is it really?

Structural HTML doesn't just help screen readers; it's also useful when styling the screen. There's something freeing about styling an entire component with a single class and using descendant and sibling selectors. Styles become easier to trace, and I'm no longer puzzling over which styles are targeted, a situation that tends to hinder debugging style issues, especially if a styling library is misconfigured and production-level obfuscation is applied in development. Add layer rules, ensure browser styling is consistent, and working with CSS becomes a smooth flow rather than a fight.

The selectors I used in the horizontal layout are still applicable to this vertical layout; the only differences are the initial class and the rules within the selectors. In this case, the top row will be vertically aligned rather than horizontally. The pattern is still one of disclosure, but it should follow the keyboard rules for an accordion rather than a menu.

Initially unstyled, the navigation component, while not yet polished, still reflects the basic shape I'm looking for. Thanks to the [data-orientation="vertical"] passed to the vertically aligned menu, the List component sets up the initial layout right away.

Spacing is a mess, buttons are ugly, and nothing really lines up. However, even with these issues, it's still operable and understandable.

Return to Content Links

Layout

Top Row Layout

Recall that everything in React eventually becomes plain old HTML, and the structure defined for the navigation output details the styling order in Nested CSS.

<nav>
    <ul>
        <li><a href="#" id="item-one">Item One</a></li>
        <li><a href="#" id="item-two">Item Two</a></li>
        <li>
            <button id="item-three">Item Three</button>
            <ul id="subnav-1">
                <li><a href="#" id="item-four">Item Four</a></li>
                <li><a href="#" id="item-five">Item Five</a></li>
                <li>
                    <button id="item-six">Item Six</button>
                    <ul>
                        <li><a href="#" id="item-seven">Item Seven</a></li>
                        <li><a href="#" id="item-eight">Item Eight</a></li>
                    </ul>
                </li>
            </ul>
        </li>
    </ul>
</nav>

HTML Structure, Top row targeted in the CSS.

@layer system-component {
  nav.vertical-navigation {
    /* Layout */
    padding: calc(var(--sp-px) * 16);

    /* Top Row nav > ul > li  */

    & > ul {
      & > li {
        & > button,
        & > a[href] {
          padding-left: 0;
          justify-content: flex-start;
        }
      }
    }
  }
}

GitHub (release 0.5.1) - styledVertical.css

Since the nav element has only one direct descendant, almost everything except padding is targeted by the unordered list's enclosing styles, which are directly contained within the nav element. Direct descendants always use a > and so anything contained within the direct unordered list will be styled accordingly, while nothing outside will be affected.

The styling in this bit only targets the top row through another direct descendant, & > li {} is set and then buttons and links that are direct descendants of the top row list items are set to justify the content within to a left alignment (flex-start), which overcomes the button's default alignment of center.

Return to Content Links

SubList Layout

The subnavigation lists and focusable elements are next.

& > ul {
… /* Top Row */
        & > ul {
          & li {
            width: 100%;
          }

          & > li {
            & button,
            & a[href] {
              flex-wrap: nowrap;
              justify-content: flex-start;
              padding: calc(var(--sp-px) * 16);
            }
          }

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

Any unordered lists that are the direct descendants of the top row list items are then targeted. List items are given a width of 100% to help with the target size, and buttons and links that are direct descendants of the sub-lists are given some padding to visually distinguish them from the primary list, with the content left-aligned.

Styling based on elements, descendants and siblings maps CSS onto the structure, increasing readability and maintainability. It's easier to figure out where something is being applied, which makes fixes much easier.

Return to Content Links

Focusable Element Standardization


& li {
    & a[href]{
        display: inline-block;
    }
  & button,
  & a[href] {
    background-color: transparent;
    border-color: transparent;
    border-radius: 0;
    border-width: calc(var(--sp-px) * 2);
    color: var(--component-text-color);
      min-height: calc(var(--sp-px) * 16);
      padding-top: calc(var(--sp-px) * 4);
      padding-bottom: calc(var(--sp-px) * 4);
    width: 100%;
    text-align: left;
  }
}

Styling outside of components makes it easier to apply CSS consistently. Consider that buttons and links live in their own navigation components. Buttons are contained in the SubNavigation component while links live in the NavigationItem. When CSS is applied either via Tailwind classes or within the component itself, the styles need to be applied separately and maintained consistently. It's frustrating, and at some point, a developer may overlook that changes in one file require changes in another.

In this case, I can target buttons and links together to maintain consistency. Spacing is made consistent by setting the link element to display: inline-block, which allows width and a minimum height to be applied, along with some top and bottom padding.

Buttons and links are given a 100% width. By expanding the button's width to fill the entire list item, the target size increases, making it easier for someone using a pointer of any sort, mouse, finger or tracking device to actually interact with a particular button.

Removing the default background and border colors and standardizing the padding work wonders, moving the layout from ugly to more professional.

Return to Content Links

Separators and Weights

The font weights are inconsistent between the buttons and links, and some separation is needed to clarify the difference between the primary and subsequent lists.

& > ul {
  & li:has(button) {
    border-bottom-width: calc(var(--sp-px) * 2);
    border-bottom-color: var(--component-border-color);
    border-bottom-style: solid;
    padding: calc(var(--sp-px) * 4) inherit;

    &:has(button[aria-expanded="true"]) {
      border-bottom-color: transparent;
      & > button {
        border-bottom-color: var(--component-border-color);
      }
    }
  }

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

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

Have you ever wanted to style an element base on something it contains or an attribute a child element exposes? Modern CSS supports it through the :has pseudo-selector.

If the list item contains a button, it is given a bottom border that disappears when the button within it is expanded. When the button is expanded, the list border is set back to transparent and the bottom border moves to the button.

The :has () pseudo-selector allows for the application of a style to a parent element based on specific attributes of a child element. In this case, whether the button has exposed the attribute, aria-expanded="true". When it does, both the parent and the child can be styled together by moving the colored border from the bottom of the list to the bottom of the button.

&:has(button[aria-expanded="true"]) styles the list item when it has a button with the attribute aria-expanded="true". I prefer using existing attributes rather than creating new classes. It creates a more readable, understandable stylesheet and better details the required state than something applied as a class.

Return to Content Links

Summary

Testing with larger browser font sizes confirms proportions and ratios are consistent.

Structural HTML, Layers and Nested CSS are natural allies, creating an understandable, traceable and maintainable set of styles. The stylesheet can be stored alongside the component and configured to affect only the component itself.

In my next article in this series, I'll be implementing keyboard navigation using the up and down arrow keys to shift focus between components.

Are You My Parent?: Scaffolding in the architecture necessary for keyboard handling between components.

ShaynaProductions — Thu, 28 May 2026 12:15:00 +0000

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, I demonstrated how structural HTML and Nested CSS go hand in hand, allowing for readable, maintainable stylesheets as work progressed on the beginnings of a styled navigation component suitable for desktop.

This article and its release focus on setting up for future success by adding the underlying data handling needed to support shifting focus between lists and components.

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.5.1.

You can view the requirements for the Parent Provider Release along with previous requirements.

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.

Content Links

Introduction
Acceptance Criteria
Who is my Parent?
- NavigationListProvider
- useNavigationList
- NavigationList
Setting up the Navigation Provider
- NavigationProvider
- useNavigation
- Navigation
- NavigationItem
- SubNavigation
Summary

Introduction

There comes a point in developing a non-trivial component when handling data becomes a prime consideration, and this time has arrived in the navigation component.

Whether a link or a button, a focusable item residing in a list item is unaware of its siblings or anything about the list it is not part of. One list has no way of knowing what another list contains.

Keyboard handling for a single list was implemented using a context provider to hold an array of focusable elements associated with that list. It meant the current element holding focus could send a request to the hook associated with the context provider to shift focus from itself to another element in the same list without knowing anything else.

Thinking ahead to the functionality required to move between components using the up and down arrow keys, along with Tab, requires each element to be able to traverse a series of lists to find the correct item to shift focus or execute other situations, such as where to place focus when a user closes the component using the keyboard.

Whether a link or a button, each focusable item resides in an array held by the NavigationListProvider. A SubNavigation component holds the button that controls the sublist along the sublist itself, meaning each list can be associated with a parent and know whether its sublist is open.

A tree data structure where the button serves as the intermediary is the logical step, so the following acceptance criteria were determined.

Acceptance Criteria

AC-1 - Every focusable element should have access to the button controlling its list.
AC-2 - A navigation context provider should hold an array of navigation objects.
AC-3 - Each focusable element should register itself in the appropriate navigation object within the array.
AC-4 - Each subnavigation button should register itself in its own navigation object as the controlling element.

At the end, the object array should resolve to the following shape:

[
{   
    parentEl: null,
    isSublistOpen: true,
    subList: [Community, Tales, Reference, About]
},
{
    parentEl: Community,
    isSublistOpen: false,
    subList: [Musings, Forum]
},
{   
    parentEl: Tales
    isSublistOpen: false,
    subList: [Search, All Stories, All Commentary,  Find Your Next Story]
 },
{
    parentEl: Search, 
    isSubListOpen: false, 
    subList: [Basic Search, Advanced Search]
},
{
    parentEl: Find Your Next Story, 
    isSublistOpen: false, 
    subList: [By Storyteller, By Era]
},
{
    parentEl: Reference, 
    isSubListOpen: false, 
    subList: [Appendices, Characters, Glossary]
},
{
    parentEl: About, 
    isSublistOpen: false, 
    subList: [ About the Site, Contact Us, Privacy Policy, Accessibility, Donate,]
    }
]

Note that every button is listed twice, once in a sublist and as a parent element. The first list will always be the first object in the array.

Creating the underlying data structure and the functionality to register elements within it is the focus of this release.

Return to Content Links

Who is my Parent?

AC-1 - Every focusable element should have access to the button controlling its list.

As the current architecture stands, a button can control a list but has no information about its items. At the same time, no item within a list currently has any way of finding or focusing on anything outside its own list. The solution is for each item to know its parent and to access a data structure that returns the next focusable item.

Since the NavigationList component already has access to its parent and a provider, it should be fairly simple to extend it to hold a reference to its parent, which will be a button for any list held in the Subnavigation component, or null when the NavigationListProvider is initialized from the NavigationList component.

NavigationListProvider

 export function NavigationListProvider({ children, value }) {
    const { parentRef } = value;
    const [state, dispatch] = useReducer(navigationListReducer, {
        parentRef: parentRef,
        items: [],
    });

    const getCurrentListItems = ...;

    const getParentEl = useCallback(() => {
        return state.parentRef.current;
    }, [state.parentRef]);

    const registerItemInCurrentList = ...;

    return (
        <NavigationListContext.Provider
            value={{
                getCurrentListItems,
                getParentEl,
                registerItemInCurrentList,
            }}
        >
            {children}
        </NavigationListContext.Provider>
    );
}

GitHub (release 0.5.1) - NavigationListProvider.tsx

The parent reference joins the empty items array within the reducer's state. There's no need to dispatch a call to the reducer; simply returning the current property from the parentRef held in state is enough.

useNavigationList

export function useNavigationList() {
    const navigationListContextObj = use(NavigationListContext);
    const { getCurrentListItems, getParentEl, registerItemInCurrentList } =
        returnTrueElementOrUndefined(
            !!navigationListContextObj,
            navigationListContextObj,
        );

    const currentListItems = getCurrentListItems();
    const parentEl = getParentEl();

...

    return {
        currentListItems,
        parentEl,
        ...
    };
}

GitHub (release 0.5.1) - useNavigationList.tsx

The getParentEl function is passed through to the navigation list hook, which masks the get() as a variable, as a nicety and passes it through.

To guarantee data is fresh, provider functions must be called to retrieve any data held by the provider. Passing the data itself to the hook will never refresh it, and while that might be fine for a parent reference that never changes, other information retrieved needs to be up to date, so getParentEl is created for consistency.

NavigationList

export default function NavigationList({
    ...
        parentRef,
    ...rest
}){
    const listContext = {
        parentRef: parentRef,
    };
    const listProps = ...'

    return (
        <NavigationListProvider value={listContext}>
            <List key={`list-$id`} {...listProps}>
                {children}
            </List>
        </NavigationListProvider>
    );
}

GitHub (release 0.5.1) - Navigation.tsx

All that's necessary is to pass the parentRef into any NavigationList and send it to the context provider.

With a parentRef now available to any NavigationItem or SubNavigation component, I can now begin development on a new context provider to hold an array of objects, each representing a different list.

Return to Content Links

Setting up the Navigation Provider

AC-2 - A navigation context provider should hold an array of navigation objects.

A navigation component is composed of one or more lists, so an array of objects is appropriate. Each object should hold the parent element and another array containing the items in the specific list. Knowing whether a list is opened or closed is going to come in handy, so a navigation object's shape can be stated as an object:

navigationObject = {
storedParentEl, /* parentRef.current */
storedList, /* [] - an array of Focusable Elements (links and buttons) held in the list controlled by the parent */
ssSubListOpen /* boolean - reflects the current state of the stored list's visibility.  */
}

One object for each list held in the navigation component will be stored in the array. Each list will have access to its parent, and each item within the storedList will be able to ascertain the list's visible state.

It's time to insert a new context provider into the component.

NavigationProvider

A top-level context provider that wraps all the nested components that make up the lists displayed in the navigation component is required to hold all the returned data. When it's complete, the entire data structure for every link and navigation button will be stored in a reducer.

export function NavigationProvider({ children, value }) {
    const { data } = value;
    const navigationObject = {
        storedParentEl: data.storedParentEl,
        isSubListOpen: data.isSubListOpen,
        storedList: [],
    };

    const [state, dispatch] = useReducer(navigationReducer, {
        NavigationArray: [navigationObject],
    });

    const setIsListOpen = useCallback((isListOpen, parentEl) => {
        dispatch({ type: "SET_IS_LIST_OPEN", parentEl, isListOpen });
    }, []);

    const setListItems = useCallback((navigationList, parentEl) => {
        dispatch({
            type: "SET_LIST_ITEMS",
            parentEl,
            navigationList: navigationList,
        });
    }, []);

    const registerButtonAsParent =  (isListOpen, parentEl) => {
        dispatch({ type: "SET_PARENT", parentEl, isListOpen });
    };

    const registerItemInNavigationArray =  (navigationList, parentEl) => {
        setListItems(navigationList, parentEl);
    };

    return (
        <NavigationContext.Provider
            value={{
                registerButtonAsParent,
                registerItemInNavigationArray,
                setIsListOpen,
                setListItems,
            }}
        >
            {children}
        </NavigationContext.Provider>
    );
}

Since updates are interdependent and registration occurs across different components, a reducer is used again to enable more granular state management. By using a reducer, each dispatch is applied to the latest state, actions can be processed in order, and all transitions are immutable.

navigationReducer

export function navigationReducer(
    state,
    action,
){
    switch (action.type) {
        case "SET_PARENT": {
            const exists = state.navigationArray.some(
                (obj) => obj.storedParentEl === action.parentEl,
            );
            if (exists) return state;

            const navObj= {
                storedParentEl: action.parentEl,
                isSubListOpen: action.isListOpen,
                storedList: [],
            };

            return {
                ...state,
                navigationArray: [...state.navigationArray, navObj],
            };
        }

        case "SET_IS_LIST_OPEN": {
            const index = state.navigationArray.findIndex(
                (obj) => obj.storedParentEl === action.parentEl,
            );
            const current = state.navigationArray[index];
            if (current.isSubListOpen === action.isListOpen) return state;

            const next = state.navigationArray.slice();
            next[index] = { ...current, isSubListOpen: action.isListOpen };

            return { ...state, navigationArray: next };
        }

        case "SET_LIST_ITEMS": {
            const index = state.navigationArray.findIndex(
                (obj) => obj.storedParentEl === action.parentEl,
            );

            const current = state.navigationArray[index];
            const currentList = returnArray(current.storedList);
            const nextList = action.navigationList;

            if (arraysEqual(currentList, nextList)) return state;

            const next = state.navigationArray.slice();
            next[index] = { ...current, storedList: nextList };

            return { ...state, navigationArray: next };
        }

        default: {
            return state;
        }
    }
}

GitHub (release 0.5.1) - navigationReducer.ts

Reducers are typically handled as switch statements, based on their action types. Unlike setters derived from useState, reducers can rely on specific conditions to determine whether to update the reducer state they are responsible for.

SET_PARENT - checks for the existence of the passed-in parent element within the navigation array. If it doesn't exist, a new navigation object is created with the parent, an empty sublist, and whether the sublist is visible, and it is stored in the array.

SET_IS_LIST_OPEN - updates the boolean value on the object where the parent element matches the passed-through parent, only if the value has changed.

SET_LIST_ITEMS - updates the storedList within the object whose parent element matches the passed-through parent, only when the stored list doesn't match the list being passed through.

useNavigation

export function useNavigation() {
    const navigationContextObj = use(NavigationContext);
    const {
        registerItemInNavigationArray,
        registerButtonAsParent,
        setIsListOpen,
        setListItems,
    } = returnTrueElementOrUndefined(
        !!navigationContextObj,
        navigationContextObj,
    );

    return {
        registerItemInNavigationArray,
        registerButtonAsParent,
        setIsListOpen,
        setListItems,
    };
}

GitHub (release 0.5.1) - useNavigation.ts

The public functions are returned from the NavigationProvider and passed through by a new hook, useNavigation.

Navigation

The context provider needs to be established within the navigation component.

  export default function Navigation({ isOpen = true, ...}){
    const parentRef = useRef(null);

    const navigationProps = {...};

   const navigationContextProps = {
      data: {
        isSubListOpen: isOpen,
        storedParentEl: null,
        storedList: [],
      },
   };

const navigationListProps: NavigationListProps = {
        ...,
        parentRef,
    };

  return (
    <>
      <NavigationProvider value={navigationContextProps}>
        <nav {...navigationProps}>
          <NavigationList {...navigationListProps}>{children}</NavigationList>
        </nav>
      </NavigationProvider>
    </>
  );
}

GitHub (release 0.5.1) - Navigation.tsx.

When initializing the first object to be stored in the array, not much is known. There are no items in the list, and the parent element for the top row will always be null. All that is really known is whether the list is open, which, for a horizontally aligned, uncontrolled component, is always true.

A parentRef is provided to be passed through to the NavigationList component, and an initial object is formed, which will always be the first object in the array. The top-level list will never have a controlling element, and the storedList is always sent in as an empty array to be filled during the registration process. Every other list is rendered in the SubNavigation component, and so has a valid parent element: the button that controls it.

With the provider in place, it's time to register the information.

NavigationItem

AC-3 - Each focusable element should register itself in the appropriate navigation object within the array.

export default function NavigationItem({...}) {
    const {
        currentListItems,
        parentEl,
        ...
    } = useNavigationList();

    const { registerItemInNavigationArray } = useNavigation();
    const currentPath = ...;

    const linkRef = useRef(null);
    const prevCurrentListItems = usePrevious(currentListItems);

    useEffect(() => {
        if (linkRef.current !== null) {
            registerItemInCurrentList(linkRef.current);
        }
    }, [linkRef, registerItemInCurrentList]);

    useEffect(() => {
        const prevList = prevCurrentListItems || [];
        if (
            linkRef.current !== null &&
            currentListItems.length > 0 &&
            !arraysEqual(currentListItems, prevList)
        ) {
            registerItemInNavigationArray(currentListItems, parentEl);
        }
    }, [
        currentListItems,
        linkRef,
        parentEl,
        prevCurrentListItems,
        registerItemInNavigationArray,
    ]);

...
    return (
        <ListItem key={id} {...listItemProps}>
            <Link {...linkProps}>{label}</Link>
        </ListItem>
    );
}

GitHub (release 0.5.1) - NavigationItem.tsx

Within the NavigationItem component, a new useEffect hook is added that passes the currentItemsList and the parent element retrieved from the useNavigationList hook into the navigationArray held by the NavigationProvider.

Effectively, this useEffect should run the registration function only once under very specific conditions. The issue is that the first time this hook is called, the linkRef will return null because the link element hasn't yet been initialized and needs to run after initial rendering. Which means it will run when the dependency array changes. I can leverage React's batch updates and send over the list of focusable elements maintained by the navigation list context provider rather than continuously updating it.

A usePrevious hook retrieves the previous makeup of the currentListItems array, which is the single list array stored in the NavigationListProvider. The function that registers the item into the navigation array is only run when the link element is known and no longer null, and the list actually contains a non-empty array that does not match the previous list.

The same registration needs to be added to the SubNavigation component to register the button into the navigation array as a focusable element.

Subnavigation

AC-4 - Each subnavigation button should register itself in its own navigation object as the controlling element.

export default function SubNavigation({...}) {
    const {
        currentListItems,
        parentEl,
        ...
    } = useNavigationList();

    const {
        registerButtonAsParent,
        registerItemInNavigationArray,
        setIsListOpen,
    } = useNavigation();

    const buttonRef = useRef(null);
    const [buttonEl, setButtonEl] = useState(null);
    ...

    const closeSubNavigation = useCallback(() => {
        setIsListOpen(false, buttonEl);
        setIsSubListOpen(false);
    }, [buttonEl, setIsListOpen, setIsSubListOpen]);

    const openSubNavigation = useCallback(() => {
        setIsListOpen(true, buttonEl);
        setIsSubListOpen(true);
    }, [buttonEl, setIsListOpen, setIsSubListOpen]);

    useEffect(() => {
        if (buttonRef.current !== null) {
            registerItemInCurrentList(buttonRef.current);
            registerButtonAsParent(isSubListOpen, buttonRef.current);
        }
    }, [
        buttonRef,
        isSubListOpen,
        registerButtonAsParent,
        registerItemInCurrentList,
    ]);

    useEffect(() => {
        const prevList = prevCurrentListItems || [];
        if (
            buttonRef.current !== null &&
            currentListItems.length > 0 &&
            !arraysEqual(currentListItems, prevList)
        ) {
            registerItemInNavigationArray(currentListItems, parentEl);
        }
    }, [
        currentListItems,
        parentEl,
        prevCurrentListItems,
        registerItemInNavigationArray,
    ]);

...

    const handlePress = () => {
        if (isSubListOpen) {
            closeSubNavigation();
        } else {
            openSubNavigation();
        }
    };

    ...

    const navigationListProps: NavigationListProps = {
        ...
            parentRef: buttonRef,
        ...
};
    return (  ...  );
}

GitHub (release 0.5.1) - Subnavigation.tsx

The handlePress function is refactored to call a function based on the current sublist's visibility, rather than toggling its open state. Both the sublist visibility held in the component's state and the call to update the object in the NavigationProvider's reducer are set to true or false in the same function.

When the button element has been rendered, not only is it registered in the current list, but the button is registered as a parent within the navigation array; and finally, when the button element meets the same conditions as the link did earlier, it registers itself into the correct navigation array as a focusable element along with the parent it retrieves from the NavigationListProvider.

Return to Content Links

Summary

Consistent data registration and updating of each list's open state has been the priority of this release. There isn't anything visible on the screen, but a console.log(state.navigationArray) placed in the registerItemInNavigationArray function will show the completed array.

With the scaffolding complete, attention in the next release can turn to making those up and down arrow keys actually work. In the meantime, I'll be turning back to styling the navigation component for a vertical layout in the next article.

Laying it all Out

ShaynaProductions — Tue, 26 May 2026 12:15:00 +0000

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.

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.

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.

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.

Single List Keyboard Handling

ShaynaProductions — Thu, 21 May 2026 12:15:00 +0000

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, the focus was actually on creating the components and adding a transformation utility to convert JavaScript objects into actual navigation. The base navigation component at this stage supports screen reader functionality through structured HTML and WAI-ARIA attributes, the ability to open and close a list through pointers and the Enter and Space keys.

This article, along with its accompanying release, focuses on basic keyboard handling for screen/keyboard users in a single list.

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.

You can view the requirements for the Single List Keyboard Release along with previous requirements.

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.

Content Links

Introduction
Acceptance Criteria
Holding Data in a Provider
- NavigationListProvider
- navigationListReducer
- useNavigation
Registering a Focusable Element
- NavigationList
- NavigationItem
- SubNavigation
Keyboard Handler
- useNavigationList
- NavigationItem
  - handleCommonKeyDown
- SubNavigation
Summary

Introduction

This article is the first of three detailing keyboard handling in a universally accessible navigation component; It is also the simplest.

In my experience, many developers seem to expect keyboard handling to be a browser feature, and it's been rare on the contracts I've worked on to see code that handles much custom keyboard input. Keyboard handling works well with native browser elements, but not as well with custom widgets, where developers need to handle code navigation requirements.

While most developers seem to understand that a keyboard is necessary for screen reader users, the fact that many people use a keyboard alongside a screen to navigate isn't always obvious. Users of screen readers have a variety of key combinations they may use to navigate through structures such as headings, links, form elements and tables. Users who navigate the screen with a pointer can simply move their cursor to a specific element and click. Unfortunately, the keyboard flexibility is limited for screen/keyboard users, who are the only ones who must navigate a page linearly. Navigation is not as easy for someone who can see a screen and depends on a keyboard for both input and navigation.

Those who use a screen and keyboard have expectations that developers should not only be aware of, but should strive to match. For those developers who work with a screen, testing how focus moves within a component is actually easy; just use the keyboard. Developers should always ensure a component is fully navigable with the Tab/Shift+Tab key combinations, which are required for both screen and screen reader users, and that any custom keyboard handling for screen users is implemented and works correctly.

To do so, developers need to receive acceptance criteria that detail what happens when a key is used.

When developers don't receive information about keyboard handling requirements when implementing a custom widget, efforts to bring the code into compliance with accessibility standards can run into snags. Keyboard handling can be compromised, and what actually gets implemented might be more focused on the letter of the law than the spirit, as is demonstrated by the following video.

Since the focus of this navigation component is accessibility, the acceptance criteria must specify what happens on each key press.

Return to Content Links

Acceptance Criteria

Single List Keyboard Handling

AC 1 - Pressing the HOME Key should take a user to the first item in the current List.
AC 2 - Pressing the END Key should take a user to the last item in the current list.
AC 3 - Pressing the LEFT-ARROW key should take a user to the previous item in the current list.
AC 4 - If focus is already on the first item in the current list, pressing the LEFT-ARROW key should take the user to the last item in the current list.
AC 5 - Pressing the RIGHT-ARROW Key should take a user to the next item in the current list.
AC 6 - If focus is already on the last item in the current list, pressing the RIGHT-ARROW Key should take a user to the first item in the current list.

The keyboard support section in the Disclosure Navigation pattern in the APG requires interpretation. The guide references moving buttons to buttons and links to links. Both are focusable elements, and depending on where each lies, navigation can move from a button to a link, or from a link to a button, within a single list.

Hand-eye coordination is key in this instance. We expect the cursor to move in the direction indicated by the arrow keys. When the cursor moves to an unexpected location, it's jarring; if it disappears entirely, the site can appear broken.

Return to Content Links

Holding Data in a Provider

Navigation in a sublist requires a focusable element, in this case either a button or a link, to be able to determine its sibling in a list and move according to the acceptance criteria.

Each link and button in a list is rendered in its own component, with no real way to know about, much less access, the others.

Data for each focusable item in a particular list can be stored in a context provider, along with functions to register and retrieve the collective data. Since each focusable element is part of a list, the best data structure to hold the information is an array.

NavigationListProvider

Context providers hold data along with functions for retrieving and setting it. Each list works with its own copy of the provider, and the data in its array consists of each individual link or button element within the list items it contains. Each focusable element, whether a button or a link, can only focus on siblings contained in the list it resides in.

export function NavigationListProvider({ children }) {
  const [state, dispatch] = useReducer(navigationListReducer, {
    items: [],
  });

  const getCurrentListItems = useCallback(() => {
      return state.items;
    }, [state.items]);

  const registerItemInCurrentList =  useCallback((focusableEl) => {
      dispatch({ type: "REGISTER_ITEM", item: focusableEl });
    }, []);

  return (
    <NavigationListContext.Provider
      value={{
        getCurrentListItems,
        registerItemInCurrentList,
      }}
    >
      {children}
    </NavigationListContext.Provider>
  );
}
NavigationListProvider.context = NavigationListContext;

GitHub (release 0.4.0) - NavigationListProvider.tsx

Given the nature of the data, useReducer is a better solution than useState. A reducer still uses the state object but can manage more complex logic. Since state updates to the NavigationListProvider affect multiple components and changes might depend on others, it makes sense to use the provided reducer hook rather than the state hook.

navigationListReducer

export function navigationListReducer(
  state,
  action,
) {
  switch (action.type) {
    case "REGISTER_ITEM": {
      if (state.items.includes(action.item)) return state;
      return { ...state, items: [...state.items, action.item] };
    }
    default: {
      return state;
    }
  }
}

GitHub (release 0.4.0) - navigationListReducer.ts

Like most reducers, actions are held in a switch, even though there is only one action type, REGISTER_ITEM. When called, a focusable element (action.item) is passed through and checked to determine if it already exists in the array. If not, it is added in.

A context provider is not exposed to public components; instead, a hook is used to execute functionality that can be passed through the registration function and to add additional functionality when necessary.

useNavigationList

export function useNavigationList() {
  const navigationListContextObj = use(NavigationListContext);
  const { registerItemInCurrentList } =
    returnTrueElementOrUndefined(
      !!navigationListContextObj,
      navigationListContextObj,
    );

  return {
    registerItemInCurrentList,
  };
}

A common pattern for a hook associated with a context provider is to load the provider's public functions and either use them in the hook or pass them through to another component. For the moment, the registration function is just passed through, so it may be imported into the navigation components.

Return to Content Links

Registering a Focusable Element

In order for the array to be used with keyboard handling, the focusable elements must be registered (added) into the data array. The first step is to wrap each list within its own context provider.

NavigationList

export default function NavigationList({...) {
  const listProps= {...};

  return (
    <NavigationListProvider>
      <List key={`list-$id`} {...listProps}>
        {children}
      </List>
    </NavigationListProvider>
  );
}

GitHub (release 0.4.0) - NavigationList.tsx

With the NavigationListProvider now wrapping the List component, each list item can access any other list item stored in its copy of the data array. It's important to understand that each list maintains its own array of items and cannot access items across lists.

NavigationItem

export default function NavigationItem({...}) {
  const {
    registerItemInCurrentList,
  } = useNavigationList();

  const currentPath = ...;

  const linkRef = useRef(null);

  useEffect(() => {
    if (linkRef.current !== null) {
      registerItemInCurrentList(linkRef.current);
    }
  }, [ linkRef, registerItemInCurrentList]);


  const listItemProps = { ... };

  const linkProps = {
    ... ,
    ref: linkRef,
    ...rest,
  };

  return ( ... );
}

GitHub (release 0.4.0) - NavigationItem.tsx

Code that has already been discussed in previous releases is represented by ellipses; only new code is given.

Focusable elements are stored in ref objects, but reading the element through ref.current can lead to unreliable code during renders. Since the elements held in the ref object are just pointers to the DOM elements, it's safe to extract them and store them separately as read-only.

References to elements are not populated right away; the focusable element, in this case a link, needs to be rendered before the information is available, so the useEffect() that registers the link into the currentlistitems array only runs when the ref. current is not null.

SubNavigation

export default function SubNavigation({...}) {
  const {
    registerItemInCurrentList,
  } = useNavigationList();

  const buttonRef = useRef(null);

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

  useEffect(() => {
    if (buttonRef.current !== null) {
        registerItemInCurrentList(buttonRef.current);
    }
  }, [buttonRef, registerItemInCurrentList]);

  const handlePress = () => {
    setIsSubListOpen(!isSubListOpen);
  };
    ...
    ref: buttonRef,
  };
  ...
}

GitHub (release 0.4.0) - SubNavigation.tsx

The code to register a button is almost identical to the code registering a link. The only difference is that the reference being passed is a button element.

Return to Content Links

Keyboard Handler

With the data structure set up and items registered, it's finally time to shift the focus to handling the appropriate keys, and attention turns back to the acceptance criteria.

AC 1 - Pressing the HOME Key should take a user to the first item in the current List.
AC 2 - Pressing the END Key should take a user to the last item in the current list.
AC 3 - Pressing the LEFT-ARROW key should take a user to the previous item in the current list.
AC 4 - If focus is already on the first item in the current list, pressing the LEFT-ARROW key should take the user to the last item in the current list.
AC 5 - Pressing the RIGHT-ARROW Key should take a user to the next item in the current list.
AC 6 - If focus is already on the last item in the current list, pressing the RIGHT-ARROW Key should take a user to the first item in the current list.

The only keys being handled now are home, end, and the left and right arrows. If the focus is on the first element in the list and the left arrow key is pressed, then focus should jump to the last element in the list, and the opposite should happen if the focus is on the last element and the right key is pressed. Focus should move to the first element.

useNavigationList

Since the functionality needs to access data stored in the context provider, the functions are created in the hook.

 export function useNavigationList() {
  const navigationListContextObj = use(NavigationListContext);
  const { getCurrentListItems, registerItemInCurrentList } =
    returnTrueElementOrUndefined(
      !!navigationListContextObj,
      navigationListContextObj,
    );

  const currentListItems = getCurrentListItems();

  const _getCurrentIndex = useCallback(
      (currentlyFocusedEl) => {
        return currentListItems.indexOf(currentlyFocusedEl);
      },
      [currentListItems],
    );

    const shiftFocus= ( focusableEl) => {
      focusableEl.focus({ preventScroll: true });
    };

    const setFirstFocus = () => {
      shiftFocus(currentListItems[0]);
    };

    const setLastFocus = () => {
      shiftFocus(currentListItems[currentListItems.length - 1]);
    };

    const setNextFocus = ( currentlyFocusedEl) => {
      const newIndex = _getCurrentIndex(currentlyFocusedEl) + 1;
      if (newIndex >= currentListItems.length) {
        setFirstFocus();
      } else {
        shiftFocus(currentListItems[newIndex]);
      }
    };

    const setPreviousFocus = ( currentlyFocusedEl) => {
      const newIndex = _getCurrentIndex(currentlyFocusedEl) - 1;
      if (newIndex < 0) {
        setLastFocus();
      } else {
        shiftFocus(currentListItems[newIndex]);
      }
    };

    return {
      registerItemInCurrentList,
      setFirstFocus,
      setLastFocus,
      setNextFocus,
      setPreviousFocus,
      shiftFocus,
    };
}

GitHub (release 0.4.0) - useNavigationList.tsx

A reminder that the code discussed earlier is represented by ellipses; only the new code is shown.

It's useful to know when a private or public function is used, and I do so by prefacing private functions with an underscore.

To provide a fresh copy of the data to the hook, don't call the data directly; it won't refresh. Instead, a getter is retrieved from the context provider, getCurrentListItems(). You'll note an alias for currentListItems that calls the getter each time. When used this way, the code always returns an updated copy of the array, making it more natural to work with.

A custom function, shiftFocus(), is used instead of implementing focus within each publicly called function to standardize how scrolling is handled. In these cases, scrolling should be prevented when navigation is displayed in a horizontal layout to prevent extraneous shifts when sublists open and close.

The rest of the code is self-explanatory; focus is shifted depending on the key pressed: Home and End, sends focus to the first or last children in the list, while the right or left arrow key sets focus depending on where the currently focused element is; If the focus is at the end of the list when setNextFocus is called, focus then moves to the first element and if the focus is at the beginning of the list when setPreviousFocus is called, focus moves to the end. Otherwise, focus shifts to the respective sibling on either side of the current element.

With the focus functions created, it's time to use them.

NavigationItem

export default function NavigationItem({ ... }) {
  const {
    registerItemInCurrentList,
    setFirstFocus,
    setLastFocus,
    setNextFocus,
    setPreviousFocus,
  } = useNavigationList();
  const currentPath = ...;
  …

 const handleKeyDown = (e) => {
      const linkEl = linkRef.current;

      switch (e.key) {
        case Keys.HOME:
        case Keys.END:
        case Keys.LEFT:
        case Keys.RIGHT:
          e.preventDefault();
          e.stopPropagation();
          break;
      }

      handleCommonKeyDown(
        e,
        linkEl,
        setFirstFocus,
        setLastFocus,
        setNextFocus,
        setPreviousFocus,
      );
    };
  …

  const linkProps = {
    ...
    onKeyDown: handleKeyDown,
    ref: linkRef,
    ...rest,
  };

  return (..);
}

The setters from the hook are retrieved, and a handleKeyboard function is created. Rather than setting preventDefault and stopPropagation in each case statement, I use a switch that sets them on all the keys at once. And because both links and buttons handle these keys in the same way, a common keyboard handler is created and called rather than duplicating the code across components.

When calling a function outside the render, everything necessary must be passed in, including all the hook calls.

handleCommonKeyDown

export const handleCommonKeyDown = (
  e,
  currentlyFocusedEl,
  setFirstFocus,
  setLastFocus,
  setNextFocus,
  setPreviousFocus
) => {
  switch (e.key) {
    case Keys.HOME:
      setFirstFocus();
      break;
    case Keys.END:
      setLastFocus();
      break;
    case Keys.LEFT:
      setPreviousFocus(currentlyFocusedEl);
      break;
    case Keys.RIGHT:
      setNextFocus(currentlyFocusedEl);
      break;
  }
};

GitHub (release 0.4.0) - handleCommonKeyDown.tsx

The common key handler is quite straightforward; each specific key triggers a function in the hook to decide the next item to shift to.

SubNavigation

export function SubNavigation({...}) {
    const {
        currentListItems,
        parentRef,
        registerListItem,
        setFirstFocus,
        setLastFocus,
        setNextFocus,
        setPreviousFocus
    } = useNavigationList();
   const {
        registerListItem, 
        setFirstFocus, 
        setLastFocus, 
        setNextFocus, 
        setPreviousFocus} = useNavigationList();

   const buttonRef = useRef(null);
    ...

  useEffect(() => {
    const currentButtonEl = buttonRef.current;
    if (currentButtonEl !== null) {
       registerItemInCurrentList(currentButtonEl);
    }
  } , [buttonEl, buttonRef, isSubListOpen, registerItemInCurrentList]);

    const handleKeyDown = (e) => {
        const buttonEl = buttonRef.current;

        switch (e.key) {
            case Keys.HOME:
            case Keys.END:
            case Keys.LEFT:
            case Keys.RIGHT:
                e.preventDefault();
                break;
        }

        handleCommonKeyDown(
          e, 
          buttonEl, 
          setFirstFocus, 
          setLastFocus, 
          setNextFocus, 
          setPreviousFocus
       );

    ...

    const buttonProps: ButtonProps = {
        ...
        onKeyDown: handleKeyDown,
        onPress: handlePress,
        ref: buttonRef,
        ...
    };

    ...
    return ( ...)
}

GitHub (release 0.4.0) - SubNavigation.tsx

Notice how stopPropagation() is not included in the top switch. This is because the button component I use from react-aria-components already calls stopPropagation() itself, so I don't need to set it. This may differ from the button component you are working with. Otherwise, the code for SubNavigation is similar to that already seen in NavigationItem.

Return to Content Links

Summary

Handling link references to multiple components becomes straightforward when a provider holds the data and the functions that call and manipulate it. A hook passes through necessary provider functions as well as its own to provide keyboard handling within a single list.

With all the code added to support single-list keyboard handling, the question arises: Does it work?

Part of the issue with demonstrating keyboard handling is the inability to show which key is being used as focus moves. It's one of the reasons keyboard accessibility is so hard to demonstrate during sprint demos. I'll be providing videos I make that detail what I am doing and which keys I'm pressing as I guide you through the enhancements.

I'll be back with another article soon, focusing on CSS design and applying a layout to the default horizontal navigation.

Structure and Transformation: First Steps in Navigation Implementation

ShaynaProductions — Tue, 19 May 2026 13:25:33 +0000

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 the last article, the focus was on wiring a theme into the foundational components that render valid HTML elements. This article focuses on creating the navigation structure and on transforming objects into a navigation component suitable for further work by developers for operability and by designers for perceivability.

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.3.1. A page showcasing these base components may be run locally through this release.

You can view the requirements for the Structure and Transformation Release along with previous requirements.

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 return to the discussions of the individual components.

Content Links

Introduction
Acceptance Criteria
Structure
- NavigationList
- NavigationItem
- SubNavigation
- Navigation
- navigation.css
Transformation
Summary

Introduction

Non-trivial component development requires progressively enhancing code through a layered approach. Each release builds on the previous release, adding accessibility, functionality, and even some styling to the earlier work. Consider building these components on a feature branch and merging into main only after they are complete.

With the base components completed, attention turns to the components necessary to render the nested structure of unordered lists contained in the landmark element. Screen reader accessibility and minimal target functionality via button activation are also added, resulting in a fully rendered navigation component that can be displayed in examples and used in testing.

All examples display the default choice for an uncontrolled component with full aria capabilities, along with some slight styling to provide developers with visual indications of placement. When run locally, the home page exposes three ugly, yet operable examples for development and testing. Taken together, the three examples cover all of the scenarios necessary to create a robust, uncontrolled navigation component.

Acceptance Criteria

Structure and Transformation Release

AC 1 - The Navigation Component should be contained in a landmark region
AC 2 - The navigation should be presented as a nested structure of unordered lists within the landmark region
AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 4 - Buttons are associated with a sublist and indicate if the sublist is open or closed.
AC 5 - The navigation component should be able to be presented as horizontal (desktop - default).
AC 6 - When navigation is displayed in a horizontal layout, the first row of focusable elements should display as open by default.
AC 7 - The navigation component should be able to be presented as vertical (mobile presentation).
AC 8 - A visual indicator is used to represent the state of the sublist's expanded status.
AC 9 - A link should contain a method of informing users which link corresponds to the current page for both screen and screen readers.
AC 10 - A sublist may be toggled to open or close when the button associated with it is pressed.
AC 11 - The state of a list's visible or hidden state should be easily perceived by any user
AC 12 - Unexpanded sublists should be hidden from the screen, but available through the DOM when they are closed.
AC 13 -A JavaScript object containing a properly formed object should be able to be transformed into properly formed ListItems and Subnavigation lists.

While most of the requirements were known during the initial requirements gathering phase, two more have been added.

AC 12 represents the decision to render unopen lists in the DOM while restricting their visibility on a screen. This decision and the reasons for it were made in the initial requirements gathering phase.

AC 13 requires a utility function that can take a JavaScript object and output a fully formed set of navigation lists and links to form the nested structure necessary.

Return to Content Links

Structure

Given the requirements, the following components are necessary and will be built in the following order:

NavigationList: A wrapper around the List component that allows for children and designates whether the list itself is displayed on the screen.
NavigationItem: Renders a Navigation Link within a ListItem and reveals the link referring to the current page. (aria-current).
SubNavigation: Renders both a button and its accompanying sublist within a listItem. Handles displaying or hiding the sublist on the screen when the button is pressed.
Navigation: Renders the entire navigation lists and sublists within a HTML element.

NavigationList

Acceptance Criteria Realized

AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 5 - The navigation component should be able to be presented horizontally (desktop presentation).
AC 7 - The navigation component should be able to be presented as vertical (mobile presentation).
AC 12 - Unexpanded sublists should be hidden from the screen, but available through the DOM when they are closed.

export default function NavigationList({
  children,
  cx,
  id,
  isOpen,
  ...rest
}) {
  const listProps = {
    ...rest,
    id,
    cx: classNames({ srOnly: !isOpen }, cx),
  };

  return (
    <List key={`list-$id`} {...listProps}>
      {children}
    </List>
  );
}

GitHub (release 0.3.1) - NavigationList.tsx

A NavigationList wraps around the previously created List component, which renders the structural HTML (AC 3). An unordered list (ul) has a default role of "list".

While not detailed in the code, an orientation prop is passed to the List component via …rest, that indicates whether the list is displayed horizontally or vertically (AC 5 and 7). This was placed into the List component during the base component functionality phase.

The isOpen prop controls the screen visibility of the specific list by applying the .srOnly class when the list is unexpanded and removing it when isOpen is true, satisfying AC 12. A screen reader-only class hides the content from the screen while still making it available to screen readers.

Because the transform utility iterates over an array, a key is passed to the List component.

Return to Content Links

NavigationItem

Acceptance Criteria Realized

AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 9 - A link should contain a method of informing users which link corresponds to the current page for both screen and screen readers.

export default function NavigationItem({
  cx,
  href,
  id,
  label,
  ...rest
}) {
  const currentPath = usePathname();

  const pageURL = href.substring(0, 2) === "/#" ? currentPath + href : href;

  const listItemProps: Omit<ListItemProps, "children"> = {
    cx: cx,
    id: id,
  };
  const linkProps: Omit<LinkProps, "children"> = {
    "aria-current": returnTrueElementOrUndefined(currentPath === href, "page"),
    "aria-label": `${label} navigation`,
    href: pageURL,
    ...rest,
  };

  return (
    <ListItem key={id} {...listItemProps}>
      <Link {...linkProps}>{label}</Link>
    </ListItem>
  );
}

GitHub (release 0.3.1) - NavigationItem.tsx

While not a detailed requirement, and mostly useful for tests and examples, the system does check for anchors passed through, and if an anchor is the only href aspect passed through, the path of the currently loaded page is prepended to the URL, which is ultimately passed to the link. Care should be taken that any objects used in production do not allow the passage of "/#".

When a link is identical to the page currently loaded, the aria-current prop should be set to "page" (AC 9) but otherwise should be undefined. I'm using the NextJS function usePathname() to achieve this; your solution may be different.

Even though nothing in the acceptance criteria requires it, an experienced developer will add information to the link about its purpose. Adding "navigation" to the label helps satisfy WCAG 2.4.9 Link Purpose by guaranteeing anyone using a screen reader understands that the links in the elements list/rotor are navigation-related. The label is prepended to the "navigation" description, satisfying WCAG 2.5.3 Label in Name for those who use their voice to interact with the component.

Once again, a key is added to the ListItem component call since a ListItem can be rendered through an array map iteration.

Return to Content Links

SubNavigation

Acceptance Criteria Realized

AC 4 - Buttons are associated with a sublist and indicate if the sublist is open or closed.
AC 8 - A visual indicator is used to represent the state of the sublist's expanded status.
AC 10 - A sublist may be toggled to open or close when the button associated with it is pressed.
AC 11 - The state of a list's visible or hidden state should be easily perceived by any user

export default function SubNavigation({
  children,
  cx,
  id,
  label,
  testId,
}) {
  const [isSubListOpen, setIsSubListOpen] = useState<boolean>(false);

  const handlePress = () => {
    setIsSubListOpen(!isSubListOpen);
  };

  const buttonProps = {
    "aria-controls": id,
    "aria-expanded": isSubListOpen,
    "aria-label": `${label} subnavigation`,
    onPress: handlePress,
  };

  const iconProps = {
    IconComponent: ChevronRightIcon,
    isSilent: true,
  };

  const listItemProps = {
    cx: cx,
  };

  const navigationListProps = {
    id: id,
    isOpen: isSubListOpen,
    testId: testId && `${testId}-list`,
  };
  return (
    <ListItem key={id} {...listItemProps}>
      <Button {...buttonProps}>
        {label}
        <Icon {...iconProps} />
      </Button>
      <NavigationList key={`list-${id}`} {...navigationListProps}>
        {children}
      </NavigationList>
    </ListItem>
  );
}

GitHub (release 0.3.1) - SubNavigation.tsx

The entire subnavigation component is wrapped in a ListItem, which contains a Button and a NavigationList. This is the basis for creating a properly nested list within the navigation component. As with the NavigationItem component, the ListItem must include a key to meet React's requirements when generating the navigation from a JavaScript object.

A button that controls another element, in this case the NavigationList component, associates itself with the NavigationList via the aria-controls attribute, which links to the NavigationList's id. Buttons also use the aria-expanded attribute to denote whether the item it controls is visible (aria-expanded ="true") or hidden (aria-expanded="false"). It's one of the few aria attributes where both true and false give meaning, and so it is always a boolean value. Additionally, an icon is included as a child of Button, indicating to screen-viewing users that the item is not a link and, when toggled, rotating between 0 and 90 degrees to indicate the list's visibility, satisfying AC 8. The actual visibility of the list can also be said to achieve AC 8.

Along with their link counterparts, buttons are available in a different collection of a screen reader's list elements/rotor, and appending "subnavigation" satisfies the same WCAG success criterion.

Return to Content Links

Navigation

Acceptance Criteria Realized

AC 1 - The Navigation Component should be contained in a landmark region.
AC 2 - The navigation should be presented as a nested structure of unordered lists within the landmark region.
AC 6 - When navigation is displayed in a horizontal layout, the first row of focusable elements should display as open by default.

export default function Navigation({
  children,
  cx,
  isOpen = true,
  label,
  orientation = "horizontal",
  ...rest
}) {
  const navigationProps = {
    "aria-label": label,
    className: cx,
  };

  const navigationListProps = {
    ...rest,
    isOpen,
    orientation,
  };

  return (
    <>
      <nav {...navigationProps}>
        <NavigationList {...navigationListProps}>{children}</NavigationList>
      </nav>
    </>
  );
}

GitHub (release 0.3.1) - Navigation.tsx

The navigation component wraps the first call to the NavigationList component within the landmark, indicating that the component represents navigation and includes a label that identifies it to a screen reader. (AC 1). An uncontrolled component will always return the initial state of the top row as open and set an orientation of horizontal on the first row (AC 6), which is passed through to the NavigationList.

Minimal styling is applied to the navigation component to rotate the icon when a button is toggled.

navigation.css

@layer common-components {
    nav {
        & svg {
            left: calc(var(--sp-px) * 8);
            position: relative;
        }

        & button[aria-expanded="true"] svg {
            rotate: 90deg;
        }
    }
}

GitHub (release 0.3.1) - navigation.css

Most styling of a navigation component will take place elsewhere, but spacing and rotation of the icon are best handled within the component itself. As I mentioned before, I find it useful to style based on aria attributes rather than adding a class, letting my CSS add a small accessibility enforcement.

Return to Content Links

Transformation

When a developer manually creates navigation code can look similar to:

<Navigation>
    <NavigationItem id="item-one" href="/one" label="Item One" />
    <NavigationItem id="item-two" href="/two" label="Item Two" />
    <SubNavigation id="Sub-One" label="Sub Nav One" >
        <NavigationItem id="item-three" href="/tree" label="Item Three" />
    </SubNavigation>
</Navigation>

Of course, creating all the variants for examples and testing can be tedious, and realistically, the component's information will be read from a JavaScript object, whether from a static JSON file or an API via GraphQL. I also like standardizing examples across testing and browsers to make it easier to identify and fix issues.

[{
    "label": "Tales",
    "id": "tales-menu",
    "href": "",
    "menu": [
        {
            "label": "Search",
            "id": "search-menu",
            "href": "#",
            "menu": [
                {
                    "label": "Basic Search",
                    "id": "basic-search",
                    "href": "/#basicsearch"
                },
                {
                    "label": "Advanced Search",
                    "id": "advanced-search",
                    "href": "/#advsearch"
                }
            ]
        },
        {
            "label": "All Stories",
            "id": "all-stories",
            "href": "/#all-stories"
        },
        {
            "label": "All Commentary",
            "id": "all-commentary",
            "href": "/#all-commentary"
        },
        {
            "label": "Find Your Next Story",
            "id": "find-next-story",
            "href": "",
            "menu": [
                {
                    "label": "By Storyteller",
                    "id": "by-storyteller",
                    "href": "/#by-storyteller"
                },
                {
                    "label": "By Era",
                    "id": "by-era",
                    "href": "/#by-era"
                }
            ]
        }
    ]
},]

JSON Navigation Example GitHub (release 0.3.1) - multiple-lists-buttons.json

A subset of the multiple-lists-buttons.json file is detailed above. Upon examination, any link will have a valid href, and any button will contain a menu array. While the href attribute on a button isn't used, it must still be present to conform to the object type. Theoretically, subnavigation objects may be nested indefinitely, but for testing purposes, only two levels are featured.

The transform utility will take a full object and return the appropriately nested components to be rendered within the Navigation component.

Acceptance Criteria Realized

AC 13 - A JavaScript object containing a properly formed object should be able to be transformed into properly formed ListItems and Subnavigation lists.

export function transformNavigation(
    navigationArray,
    testId,
) {
    return navigationArray.map((item) => (
        <Fragment key={`navigation-${item.id}`}>
            {item.menu ? (
                <SubNavigation
                    key={item.id}
                    id={item.id}
                    label={item.label}
                    testId={testId && `${testId}-${item.id}`}
                >
                    {transformNavigation(item.menu, testId)}
                </SubNavigation>
            ) : (
                <NavigationItem
                    id={item.id}
                    key={item.id}
                    label={item.label}
                    href={item.href}
                    testId={testId && `${testId}-${item.id}`}
                />
            )}
        </Fragment>
    ));
}

GitHub (release 0.3.1) - transformNavigation

The transform utility is recursive, calling itself for objects contained in a menu array. Other than recursion, it's fairly straightforward. Loop through the object; if it contains a menu, render the Subnavigation component, then call itself to render the children defined in the menu object. If the item mapped does not have a menu, render a NavigationItem component.

When run in examples, the transformation returns a full navigation menu. And while it's obvious that a lot of work still needs to be done, there's now a solid foundation to work with.

Return to Content Links

Summary

With the transform utility, examples are now available in the release with just enough CSS to make operability feasible. Work can begin on horizontal and vertical menu styling.

At this moment, the navigation component meets screen reader perceivability requirements. It can be used via the keyboard with the Tab Key and the Enter or Space keys to toggle the sublist availability. All links and buttons are available in the screen reader elements list and correctly denote their purpose. Not bad for just a skeleton; in fact, I know several teams that would consider the navigation component complete at this point. I'm not one of them, though.

Next up will be the first of three releases dedicated solely to keyboard handling, concentrating on keyboard navigation through a single list.

Theming in the Modern Age

ShaynaProductions — Thu, 14 May 2026 12:15:00 +0000

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 the last article, the focus was on the operability of foundational components that render valid HTML elements. This article focuses on screen perceivability and the foundational aspects around theming, design and CSS.

CSS is used to illustrate design concepts. To that end, the theming system I'm using is solely composed of stylesheets.

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.2.1. A page showcasing these base components may be run locally through this release.

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.

Introduction

In modern web development, theming systems are everywhere. Many of them integrate directly with JavaScript frameworks and support component styling by converting JavaScript objects into CSS with preprocessors like Styled Components or CSS-in-JS. Not surprisingly, I have thoughts around this.

A tightly integrated theming system tied directly to JavaScript, such as Material-UI or Radix-UI, along with the requirement to write CSS within component files, can cause issues when upgrading or even moving to a different framework.

This tight integration breaks the principle of separation of concerns. A theming system should sit alongside the project it affects and be available no matter the framework or language used. To my mind, a theming system should work just as well in a static HTML site as it does within a front-end framework such as Angular or React and work seamlessly when something in the stack needs to change.

Modern CSS has evolved in leaps and bounds over the last few years. Psuedo-selectors such as :has() and :not() make targeting parent elements based on their children's attributes, or lack thereof, a reality. It's worth revisiting if you haven't looked at it in a while.

I've had a love/hate relationship with CSS for a long time. I love the cascade aspect of CSS, but most styling frameworks seem to give it up in favor of writing styles directly in JSX or TSX files, with everything applied as classes. This approach adds complexity and reduces maintainability, especially when tracing style issues across components. I find it harder to maintain consistent styling when CSS can't be applied consistently across components. Is it doable? Yes. Is it easy and intuitive? No.

For most of my career, CSS has seemed like something I fight rather than something that just works. Dealing with browser inconsistencies and the battle between the styles set by third-party component libraries, the desires of the various design teams I've worked with, alongside the requirement to keep all styling in components and style everything in a class, has been my reality for years. Working with designs created by those who've rarely considered specificity or cross-browser styles has been challenging. Not to mention the issues of overriding a component library's styles to conform to another's vision.

My vision for a theming system is one built on modern CSS, which, for the most part, sits alongside my React components. I've built it on four pillars.

Primitive components: are those components where the focus by the developers has been on operability and functionality, not on perceivability. These components are released without any CSS styles and are styled only by the browser in which it is run.
Sanitization scripts: to standardize styles across browsers and, in many cases, removing most of the visual styling, goes a long way toward reducing the headache of trying to make something look the same way across browsers.
CSS Cascade Layers: widely supported across browsers, allows for defining explicit contained layers of specificity, reducing the need for long strings of classes and the use of !important.
CSS Nesting: allows for writing more modular, maintainable and readable CSS. It's similar to SASS nesting, using the same & operator, but it also supports all the newer pseudo-element selectors, which sadly SASS hasn't kept up with.

Primitive Components

Open source primitive component libraries abound. Radix, React Aria Components, Reach, Reakit and AriaKit all provide unstyled components that emphasize operability and accessibility. There's no fighting over opinionated CSS because there is no opinion on how to style these components other than those of the people responsible for the design.

My current implementation uses react-aria-components, an underlying primitives library provided by Adobe.

Primitive libraries, which feature operable components with no styling applied, have reduced the need to reconcile component-agnostic styling with corporate directives. I will admit I was intimidated by the idea of adding all the styling necessary to components, but the payoff has been worth it.

Santitization Scripts

A good set of sanitization scripts goes a long way towards sane styling. Sanitization scripts remove the inconsistencies across browsers, and the one I use removes most visual styling altogether.

Developing a vanilla theming system using modern CSS, along with robust sanitization scripts and primitive components that are initially operable but not perceivable, has changed the way I think about the HTML elements I work with every day. The first time I loaded a sanitized, unstyled, empty button onto a page, I thought I did something wrong. My screen was blank; the only way I knew a button was loaded was by checking the DOM. I added a border width and style, still nothing. It was only when I applied a color to the border that a small box appeared. I added text to my button, and to my amazement, it was flexible: it had no specified height or width, and no padding or margins; it hugged its content tightly.

Standardizing on box-size: border-box made a huge difference. Suddenly, setting a specific width meant the element's width never changed. Border widths and padding sizes are part of the set width. True consistency is achievable.

CSS Cascade Layers

CSS Layers applies an order of precedence based on an @rule, reducing the need for specificity. Styles lower in the layer hierarchy are easily overridden by styles in higher layers, reducing the need for !important declarations and long, hard-to-follow selectors.

@layer reset, system, default-theme, base-component, common-component, system-component, main;

GitHub (release 0.2.1) - Theming System - layers.css

Layers within a theming system are self-defined. We determine which layers exist and which layers are higher in precedence. Layers are applied from left to right; any overrides in a layer defined to the right are applied without additional specificity or the need for !important.

In my layer system, I begin with reset, which contains my sanitization scripts that remove all padding and borders and standardize elements across browsers.

Anything defined in the reset layer may be overridden by the other layers, including the system layer, which holds design tokens for colors and underlying choices, such as the creation of my relative pixel base size and global srOnly class.

@layer system {
  :root {
    --sizing-base: 1rem;
    --sp-px: calc(var(--sizing-base) * 0.0625);
    --shadow-opacity: 0.3;
    --overlay-opacity: 0.2;
  }
  .srOnly {
    border: 0;
    clip: rect(1px, 1px, 1px, 1px); /* 1 */
    clip-path: inset(50%); /* 2 */
    height: 1px;
    margin: -1px;
    overflow: hidden !important;
    padding: 0;
    position: absolute !important;
    width: 1px;
    white-space: nowrap !important; /* 3 */
  }
}

GitHub (release 0.2.1) - Theming System - base.css

While layers reduce the need for the keyword, !important, it still has its uses. In the case of my srOnly class, the properties overflow, position and whitespace may not be overwritten no matter what. Since those three properties define removing the class applied element from the screen, they are integral to the style.

Layers address many of the issues around specificity and are well worth the time to get to know them. They form an integral part of my theming system.

CSS Nesting

Nested CSS, a fully supported feature of CSS, mimics SASS in some ways, and when implemented inside @layer, removes the need for chaining selectors and allows for more modularity. When base components render into actual structured HTML elements, the need for adding a class to everything disappears.

I think the mindset around CSS usage has suffered from the overuse of classes, and I blame Macromedia for their decision when creating Dreamweaver to make everything a class, which in turn has influenced a generation of developers. Trying to debug conflicting styles when everything is styled via a string of classes to provide enough specificity has turned many stylesheets into a morass where developers fear to tread.

When nested CSS is used alongside HTML elements rather than classes, everything starts to make sense.

@layer main {
  #base-components {
    & > ul.general {
      align-items: flex-start;
      column-gap: calc(var(--sp-px) * 16);
      display: flex;
      flex-direction: row;
      list-style: inside;
      width: 100%;

      & li {
        border-width: var(--component-border-width);
        border-style: solid;
        border-color: transparent transparent transparent var(--purple-3);
        list-style: none;
        padding-left: calc(var(--sp-px) * 16);
        padding-bottom: calc(var(--sp-px) * 16);
        width: 30%;
        &:first-child {
          border-left-color: transparent;
        }

        & a {
          text-decoration: underline;
        }
      }
    }

    & > ul:not(.general) {
      display: flex;
      gap: calc(var(--sp-px) * 16);
      position: relative;
      flex-wrap: wrap;
      list-style: none;

      & > li {
        padding: 0 calc(var(--sp-px) * 16);
        width: 47%;
      }

      & > li div {
        border-width: calc(var(--sp-px) * 8);
        padding: calc(var(--sp-px) * 32);
        mask: radial-gradient(
            calc(var(--sp-px) * 21) at 50% calc(var(--sp-px) * 21),
            #0000 calc(100% - var(--sp-px) * 1),
            #000) 50% calc(-1 * var(--sp-px) * 21) / calc(var(--sp-px) * 38.85) 100%;
      }
    }
  }
}

GitHub (release 0.2.1) - baseComponentsPage.css

The example above is a snippet styling the base components example page in the demo. Notice how everything cascades from a single id, using descendant selectors to drill down into elements and apply styling. All widths and gaps are either percentages or derived as relative pixels using the technique I described in a previous article, Spacing Considerations In Acessible Design.

With these four pillars in place, everything I dreaded about working with CSS disappeared. Instead of fighting CSS specificity and trying to debug why a particular style was being overridden and from where within a sea of CSS within components, something changed. CSS flowed, it was easy and best of all, it just worked.

Colors

Perceivable colors that automatically work in both light and dark modes, and that provide sufficient color contrast between foreground and background, are not hard to achieve, especially when each color is separated into a set of colors sharing the same hue, varying only saturation and lightness.

Using human-readable color spaces such as LCH or HSL is preferable to hex codes or RGB because colors can be computed from a given hue. Both are human-readable and fully supported across browsers. I've used both in this theming system across two colors: gray uses HSL, and purple uses LCH. I'm starting to prefer HSL for the many generators available and its ease of readability, which is easier to understand than LCH.

Colors are stored in color files, each of which can define 7 or 12 design tokens that differ mostly in saturation and lightness. Definitions in the color files can be set to automatically change based on a user's light or dark mode preference.

@layer system {
  /*Based off hue 151 */
  :root {
    /*Light Desaturated - Background */
    --raw-purple-1: 96.73% 0.00508 325.62;
    --raw-purple-2: 90.813% 0.02278 321.35;
    --raw-purple-3: 84.919% 0.03759 320.35;

    /* Light Saturated */
    --raw-purple-4: 79.126% 0.0733 320.93;
    --raw-purple-5: 73.236% 0.0934 321.48;
    --raw-purple-6: 67.281% 0.10972 321.13;

    /* Medium */
    --raw-purple-7: 62.241% 0.10499 321.38;

    --raw-purple-8: 55.082% 0.09248 321.86;
    --raw-purple-9: 48.822% 0.08156 321.03;

    /* Dark */
    --raw-purple-10: 42.402% 0.07362 322.08;
    --raw-purple-11: 36.178% 0.06256 322.17;
    --raw-purple-12: 29.673% 0.05099 322.32;

    --purple-1: oklch(var(--raw-purple-1));
    --purple-2: oklch(var(--raw-purple-2));
    --purple-3: oklch(var(--raw-purple-3));
    --purple-4: oklch(var(--raw-purple-4));
    --purple-5: oklch(var(--raw-purple-5));
    --purple-6: oklch(var(--raw-purple-6));
    --purple-7: oklch(var(--raw-purple-7));
    --purple-8: oklch(var(--raw-purple-8));
    --purple-9: oklch(var(--raw-purple-9));
    --purple-10: oklch(var(--raw-purple-10));
    --purple-11: oklch(var(--raw-purple-11));
    --purple-12: oklch(var(--raw-purple-12));
  }

  @media (prefers-color-scheme: dark) {
    :root {
      /*Light Desaturated - Background */
      --raw-purple-12: 96.73% 0.00508 325.62;
      --raw-purple-11: 90.813% 0.02278 321.35;
      --raw-purple-10: 84.919% 0.03759 320.35;

      /* Light Saturated */
      --raw-purple-9: 79.126% 0.0733 320.93;
      --raw-purple-8: 73.236% 0.0934 321.48;
      --raw-purple-7: 67.281% 0.10972 321.13;
      /* Medium */
      --raw-purple-6: 62.241% 0.10499 321.38;

      --raw-purple-5: 55.082% 0.09248 321.86;
      --raw-purple-4: 48.822% 0.08156 321.03;

      /* Dark */
      --raw-purple-3: 42.402% 0.07362 322.08;
      --raw-purple-2: 36.178% 0.06256 322.17;
      --raw-purple-1: 29.673% 0.05099 322.32;
    }
  }
}

GitHub (release 0.2.1) - Theming System - purple.css

The color file for purple, shown above, defines the same colors in both light and dark color schemes as the raw variables, which are then defined using oklch(). This enables an automatic dark color scheme and allows using the --raw variables when opacity needs to be adjusted. My initial foray into this was discovering the custom palettes available through Radix-UI, though I don't use their generator at all.

A color sheet created in this manner also allows for easily achievable color contrast. Formulas for non-vibrant colors achieve color contrast with variables -1 through -4 when paired with any color in the -8 through -12 range. You can see this in a palette color theming system called primer prism.

Design Tokens for Theming

CSS variables are not just for setting colors. They are flexible and mutable, allowing themselves to be set and reset to affect only those elements contained in a selector. Design tokens can be used by base components, tying them into the design system in a way that goes far beyond simple color selection.

<div id="initial">
  <div>
    <div>
      <div></div>
    </div>
  </div>
</div>
<div id="secondary">
  <div>
    <div>
      <button>Hello World</button>
    </div>
  </div>
</div>

Consider the HTML code above. Two series of nested empty divs, with the second series also holding a button in the innermost div.

#initial {
  --theme-background: var(--red-1);
  width: calc(var(--sp-px) * 160);
  & div {
    background-color: var(--theme-background);
    padding: calc(var(--sp-px) * 20);
  }

  > div {
    border: 1px solid var(--theme-border-color);
    & > div {
      --theme-background: var(--purple-2);
      & > div {
        --theme-background: var(--gray-3);
      }
    }
  }
}

The CSS sets the —theme-background token to a light red and applies it to every div in the DOM, along with padding. Using Nested CSS and the descendant selector, I can target the individual divs nested within each other and change the theme background.

#secondary {
  --theme-background: var(--gray-1);
  position: relative;
  left: 25%;
  top: calc(var(--sp-px) * -160);
  margin-top: calc(var(--sp-px) * 20);
  width: calc(var(--sp-px) * 180);

  & div {
    background-color: var(--theme-background);
    padding: calc(var(--sp-px) * 20);
  }
  & > div {
    --theme-background: var(--gray-3);
    & > div {
      --theme-background: var(--red-3);
      & button {
        --button-background: var(--purple-6);
        --button-color: var(--gray-1);
        padding: calc(var(--sp-px) * 20);
      }
    }
  }
}

In the secondary example, a button is targeted by a —button-background token, along with setting the text color to a lighter value.

Variables set at a specific point in the DOM affect only the items contained within it.

Component Theming

The theming I'm using in the repository is pared down to the bare minimum, and isn't the best representation of what it will eventually become. But it's sufficient to demonstrate the power of plain CSS and Structural HTML.

/* Button*/
button {
  /* Common widths and spacing */
  --button-padding: calc(var(--sp-px) * 4) calc(var(--sp-px) * 12);
  --button-border-radius: calc(var(--sp-px) * 8);
  --button-border-width: calc(var(--sp-px) * 2);
  --button-font-size: inherit;
  --button-font-weight: 500;
  --button-line-height: 1.4;
  --button-letter-spacing: normal;

  /* theme - Solid */
  --button-background: var(--purple-2);
  --button-background-disabled: var(--gray-3);
  --button-background-interactive: var(--purple-3);
  --button-background-pressed: var(--purple-4);

  --button-border-color: var(--gray-5);
  --button-border-color-disabled: var(--gray-3);
  --button-border-color-interactive: var(--gray-9);
  --button-border-color-pressed: var(--button-border-color);

  --button-color: var(--gray-12);
  --button-color-disabled: var(--gray-10);
  --button-color-interactive: var(--purple-11);
  --button-color-pressed: var(--gray-11);

  --button-fill: var(--purple-12);
  --button-fill-disabled: var(--button-color-disabled);
  --button-fill-interactive: var(--button-color-interactive);
  --button-fill-pressed: var(--button-color-pressed);

  /* Ghost  */
  --button-ghost-background: transparent;
  --button-ghost-border: transparent;
}

GitHub (release 0.2.1) - component.css

I'm going to use the button component to demonstrate the theming. You'll notice that design tokens have been set up not only for background, border and text colors, but also for states. There are tokens to hold colors for interactive states, including :hover and :focus, and the pressed variables hold changes when the :active state is in place. Because buttons can hold icons, tokens for various fill states are also set.

With the base button tokens defined, it's time to add them to the actual component.

Component Styling

Component stylesheets live in the same folder as their component, and, since I'm using Next.js, are side-loaded into the globals.css file to ensure they are loaded only once. Not every base component needs to include specific styling; where styling is present, it should be generic. Styling for base components is applied in an @layer base-component{element{}} to ensure initial styling is available regardless of where the HTML element is located.

GitHub (release 0.2.1) - button.css

  button {
      /* Layout */
      align-content: center;
      align-items: center;
      display: flex;
      flex-wrap: wrap;
      justify-content: center;
      margin: 0;
      padding: var(--button-padding);
      width: fit-content;
  }

Every button starts with a flex layout that centers its content and initially sets its width to fit the content. Padding is wired in through the button-padding token since that can and will be changed regularly.

button {   /* continued */
  /* Text */
  font-size: var(--button-font-size);
  font-weight: var(--button-font-weight);
  letter-spacing: var(--button-letter-spacing);
  line-height: var(--button-line-height);
  text-decoration: none;

  /* Appearance */
  border-radius: var(--button-border-radius);
  border-style: solid;
  border-width: var(--button-border-width);
  cursor: pointer;
}

Text and appearance depend on more tokens, which can be overridden wherever necessary.

button {   /* continued */
/* Colors */
--svg-color: var(--button-color);
--svg-fill: var(--button-fill);

background-color: var(--button-background);
border-color: var(--button-border-color);
color: var(--button-color);  }

All colors associated with the button are set to the tokens by default. Either the background-color or the token may be overridden.

button {   /* continued */
    /* States - */
    &[aria-disabled="true"] {
      --button-background: var(--button-background-disabled);
      --button-border-color: var(--button-border-color-disabled);
      --button-color: var(--button-color-disabled);
      --svg-color: var(--button-color-disabled);
      --svg-fill: var(--button-fill-disabled);

      cursor: default;
    }

    &:focus-visible {
      outline: var(--focus-outline) var(--focus-outline-color);
      outline-offset: var(--focus-outline-offset);
    }
    &:focus,
    :hover {
      --button-background: var(--button-background-interactive);
      --button-border-color: var(--button-border-color-interactive);
      --button-color: var(--button-color-interactive);
      --svg-color: var(--button-color-interactive);
      --svg-fill: var(--button-fill-interactive);
    }
  }

When it comes to state changes, I prefer to style them using either aria- attributes or pseudo-classes such as :focus and :hover. Styling on aria- attributes reinforces accessibility. If the aria- attribute is required, why not style it through the attribute rather than adding in yet another class that needs to be deciphered?

In the article Foundational Accessibility Begins with the Base Components, I explained how the disabled attribute causes issues with screen readers and proposed a fix that used aria-disabled instead. The styles around the aria-disabled attribute are the last aspect necessary. Note how every line in the rule simply replaces the original token with one based on a disabled state. That's all that is necessary. It's the same with the focus and hover pseudo-classes.

Box-Sizing with Border-Box

My sanitization scripts apply the box-sizing: border-box rule to every element. This box-sizing rule defines the width and height to include content, padding, and borders. I've found this rule makes it easier to work with positioning and layout, since a component's width and height remain constant regardless of padding or borders.

When using "border-box", note that changing from "border: none" to "border: solid" or adjusting the border-width during a state change will shift the component's content. My solution is to set the border width in advance and use "color: transparent" to emulate a no-border effect. In this scenario, a user sees a borderless box since the transparent border sits on top of the background. During a state change, there is no shifting, since the border simply swaps colors. Make sure the border-width remains consistent.

Summary

Adding a theming system doesn't have to be complicated or require another package. Regardless of the theming system you use, wiring the components that render to HTML into your system will save a lot of time and headaches down the road.

With the base components added in and connected to the theming systems, the next step will be to create the actual components of the Navigation system.

Foundational Accessibility Begins with the Base Components

ShaynaProductions — Tue, 12 May 2026 12:15:00 +0000

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.

This article is part of the series and marks the first time code will be introduced and discussed. It's all about the base.

I define base components as components that wrap elements that ultimately render to plain HTML from React. If your base components don't take accessibility into consideration, achieving accessibility becomes infinitely harder. A website or application can only be as accessible as its base components allow.

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.2.1. A page showcasing these base components may be run locally through this release.

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.

Introduction

Universal accessibility depends on structural and semantic HTML. Semantics convey meaning to screen readers and other assistive technologies. No matter what language or framework is ultimately used, in the end, every user interface component ultimately renders into plain HTML Elements, which, for all intents and purposes, exposes the same information across browsers and devices. Whether a component or a page, your code can only be as accessible as the base components it is built on.

Why do developers love divs so much? Why is the use of divs and classes so prevalent when structural HTML conveys more information, and the underlying components are built within browsers to be accessible?

Divs are flexible, with no formatting applied. They have no specified height or width, and no padding or margins; they hug their content tightly. They make styling easier, since they aren't subject to the style choices of third-party component libraries or the underlying browser style sheets.

But what if almost every structural HTML component was available with styling stripped out? What if almost every HTML element could be set to be as flexible as a div, with no height or width, no specified borders and no padding. What if each HTML element hugged its content as tightly as a div does? Would you use it then?

An accessible website limits the use of <div />'s to containers for positioning or the creation of custom widgets. <div />, like its cousin <span /> conveys no semantic meaning. If a <div /> is used as the basis for a custom widget, it needs to pass both role and label.

In a previous article, Modalities of Accessibility, I discussed applying the first two principles of the Web Content Accessibility Guidelines through the lens of different peripherals. How something operates has little if anything to do with how it is perceived. When developing a component, I have no opinion on its styling; my focus is on ensuring it meets the stated operable requirements. Styling and design are separate concerns from coding for operability.

Base Components

Fixing and Expanding Accessibility and Functionality

Base components can be imported from a third-party library or written in-house. They wrap around and ultimately render a single HTML element. In either case, modifications can be made to fix issues, expand and enhance functionality, and make it easier for developers to achieve accessibility when using these components.

Using structural HTML and Accessible Rich Internet Applications (ARIA) is part of the toolkit when creating an accessible website, but knowing when to use those tools is just part of it. Developers need to know when it's appropriate to use an aria attribute and when it's not. There's a reason the phrase "No Aria is better than Bad Aria" is widely known.

In some cases, existing operability can actually interfere with accessibility. Consider the <button disabled="true" /> situation. Every browser/screen reader combination exhibits the same issue. If a button is disabled by setting the disabled attribute, it is invisible to a screen reader when the user navigates the screen when using Tab. Any button built will have this issue unless it is addressed in the base component. This issue will be examined when discussing the Button component.

The base components I'll be using in this demo will differ from the components you will have available to you. I'm using a combination of react-aria-components, a Next.js link, and even rolling a few of my own. Consider this article and release as roadmaps to help you enhance your own components.

<nav>
    <ul>
        <li><a href="#" id="item-one">Item One</a></li>
        <li><a href="#" id="item-two">Item Two</a></li>
        <li>
            <button id="item-three">Item Three</button>
            <ul id="subnav-1">
                <li><a href="#" id="item-four">Item Four</a></li>
                <li><a href="#" id="item-five">Item Five</a></li>
                <li>
                    <button id="item-six">Item Six</button>
                    <ul>
                        <li><a href="#" id="item-seven">Item Seven</a></li>
                        <li><a href="#" id="item-eight">Item Eight</a></li>
                    </ul>
                </li>
            </ul>
        </li>
    </ul>
</nav>

[HTML output structure for a navigation component]

When examining the agreed-upon HTML navigation structure, the following Base components are required.

<List /> - (renders <ul /> or <ol />)
<ListItem /> - (renders <li />) valid only when a direct child of <List />
<Button /> - (renders <button />
<Link /> - (renders <a href />

The Link component also contains other components:

<Icon /> - (renders a react-icon) - used in the <Link /> component.
<Text /> - (renders <p /> or <span />) wraps around text not directly contained within a component.

Additionally, I'll address the creation of a < Box /> component, as it requires special handling when creating composite widgets.

Some of these components (Button, Link, and Text) will wrap components from third-party libraries, and other components (List, ListItem, Box) will wrap HTML elements. Additional functionality, either security- or accessibility-focused, will be applied to most of these components.

Where do the accessibility requirements for these components come from? Some of the requirements are lifted from the Web Accessibility Checklist from Deque. Additional requirements are in place to enhance the developer experience and make it easier for them to apply accessibility features specific to the component.

The requirements can be found in the Accessible Base Component Requirements spreadsheet and are also listed in this article under the appropriate component.

A Word on Typing and Testing

The code in the repository is fully typed and tested against the acceptance criteria. Typing is removed from the example code presented in the articles for brevity, but the code required through typing is included. A test file is created alongside the component, and each test is initially set up to conform to one or more acceptance criteria. While I won't detail all the tests in the article, the first component discussed will present a test skeleton, and the full tests are a part of each release.

Text Component

GitHub (release 0.2.1) - components/base/Text

A paragraph has semantic meaning. It's a block of text containing related sentences with distinct beginnings and ends. On a screen, we can discern different paragraphs by the vertical margins between them. A screen reader uses <p /> as an indication to pause before reading the next paragraph. And while a <span /> has no semantic meaning, it's useful for styling or marking up text with attributes, such as language
changes, denoting an abbreviation or using another phrase control element to add semantic meaning into text content.

My text component wraps around its undocumented namesake in react-aria-components. The main thrust of the code is to provide enhancements that allow a screen reader to access information without displaying it on screen. Feel free to use the code I provide to enhance your own text component.

Acceptance Criteria - Text Component

Text AC 1 - Containing elements are restricted to <p> (default) and <span>.
Text AC 2 - Text may be hidden from view while still available to a screen reader.

Many component libraries, including react-aria-components, allow their Text component to be rendered as any of several HTML elements, which can be passed in. I'm not fond of the approach since the odds of creating a fully accessible component that works seamlessly as the element sent through aren't very good. The underlying react-aria-component will be used to keep consistency, while restricting it to paragraphs and spans.

In development, situations arise when an aria-label or aria-describedby cannot provide screen readers with an equitable experience, and additional text, not visible on the screen, is useful. A number of component libraries include a <Hidden /> or <VisuallyHidden /> component for these circumstances, but I've found it makes more sense to just expand the functionality of Text.

Testing Skeleton
As mentioned earlier, testing is integral to component development. The acceptance criteria are mapped to the test, and tests are fleshed out as the component is built. The initial test file for Text is shown below.

describe("<Text />", () => {
    it.skip("should be WCAG compliant as a Phrase control", async () => {
        /* Conforms to Text AC 1 */
    });

    it.skip("should be WCAG compliant as a Flow control", async () => {
        /* Conforms to Text AC 1 */
    });

    it.skip("should load as inline", () => {
        /* Conforms to Text AC 1 */
    });

    it.skip("should be visually hidden when isHidden is true", () => {
        /* Conforms to Text AC 2 */
    });
});

Most testing begins with a simple test to confirm a component is mounted, but I've found that substituting automated accessibility testing using jest/axe for the mount makes more sense. While automated accessibility testing can only catch objective issues, such as when interactive items are nested within one another or when something lacks a label, using it as a first test can still help catch issues early. Automated axe testing cannot evaluate subjective criteria, such as whether labels or text adequately convey the required information, but it's a step in the right direction.

Code

export default function Text({
    children,
    cx,
    isHidden,
    IsInline,
    testId,
    ...rest}
) {
    const textProps = {
        ...rest,
        className: classNames({ srOnly: isHidden }, cx),
        "data-testid": testId,
        elementType: isInline ? "span" : "p",
    };

    return <RACText {...textProps}>{children}</RACText>;
}

GitHub (release 0.2.1) - Text.tsx

Two props are added to enhance the underlying component:

When isHidden is set to true, a class of .srOnly is sent into the component, effectively removing the component from the screen, while still keeping it in the DOM.
The isInline property restricts rendering to < span /> or <p />. A span is considered phrase control, which means it can be used within text content and is typically used with a display: inline or one of its offshoots. Paragraphs are considered flow control and always start on a new line.

Any attribute passed to my components that isn't explicitly pulled out is sent to the HTML element. This allows any specific aria attributes to be passed through without having to specify each one. Linting will throw an error if a non-viable HTML attribute is passed in.

Icon Component

GitHub (release 0.2.1) - components/base/Icon folder

There are a variety of ways to add icons into your application. I use the react-icons library; your code might use another library, such as FontAwesome or hand-built SVGs. While the react-icons library can be used directly, I prefer to wrap the icons into their own component to extend its functionality. The <Icon /> component receives the icon it is to display and applies accessibility checks.

Acceptance Criteria

Icon AC 1 - When not decorative or duplicative of meaning, an icon shall have a label describing its function.
Icon AC 2 - When an icon is decorative or the meaning is already expressed by the element wrapping the icon, the icon shall be hidden from the screen reader.
Icon AC 3: Either a label or a directive to hide the icon from screen readers is required, not both.

Icons are images and, as such, need to be labeled when the information they convey isn't already available. If the meaning is already available through a parent element, such as an aria-label on a button that wraps the icon, then the icon should be hidden from screen readers since the information it conveys is already available. Any description of an icon should not describe what it looks like; rather, it should describe the
functionality it conveys.

AC 1 and AC 2 describe two competing requirements. Either a label is necessary and should be passed in, or the label is not necessary, and the icon should be silent and hidden from screen readers.

Code

export default function Icon({
  cx,
  IconComponent,
  isSilent,
  label,
  testId,
}) {
  let proceed = true;
  if (
    process.env.NODE_ENV === "test" ||
    process.env.NODE_ENV === "development"
  ) {
    if (!isSilent && !label) {
      console.error(
        "Dev Error: (Icon) - WCAG 1.1.1: Label must be provided when isSilent is not set.",
      );
      proceed = false;
    }

    if (isSilent && label) {
      console.error(
        "Dev Error: (Icon) - WCAG 1.1.1 Label may not be defined when isSilent is set to true.",
      );
      proceed = false;
    }
  }
  if (proceed) {
    const iconProps = {
      "aria-hidden": returnTrueElementOrUndefined(!!isSilent),
      "aria-label": label,
      className: classNames("svg-icon", cx),
      "data-testid": testId,
      role: "graphics-symbol",
    };

    return (
      <>
        <IconComponent {...iconProps} />
      </>
    );
  }
}

GitHub (release 0.2.1) - Icon.tsx

The acceptance criteria state that either a label is present or isSilent is true, which means neither prop can be required. Since both props are conditional, console errors are thrown when neither condition is met or when both conditions exist, and the component returns nothing in development or testing environments. To render an icon, a developer must meet the acceptance criteria conditions. Checks are ignored in production, so the icon will always be rendered.

It's fairly easy to set any icon without a label to aria-hidden; however, not every developer understands the need to ensure a label is present when an icon is not decorative and is not associated with text that will substitute for labeling. Simply hiding all labels when none are passed is a sure way to fail an accessibility audit. Instead, a developer is reminded to either explicitly set isSilent or to pass a label.

Adding a check like this and preventing rendering when conditions aren't met is necessary. I've seen developers ignore or actively try to suppress console error messages without actually fixing the issue when the component renders with the error. Exposing error messages in a development environment serves as a reminder to developers that accessibility needs to be considered.

An icon's role is "graphics-symbol," and so is explicitly set across any icon.

"aria-hidden" in IconProps calls returnTrueElementOrUndefined(), a custom function, to return undefined if isSilent is false. It's used because several aria attributes should not be sent when the boolean value is false.

To illustrate this point, consider a grouping of ten checkboxes, of which two are checked, exposing an aria-checked="true". When a Boolean value is passed, and the other eight are set to "false," then a screen reader will announce the check status for every item, resulting in aural clutter. ("Checkbox 1, checked. Checkbox 2, unchecked. Checkbox 3, unchecked.") By sending aria-checked only when true, only the selected checkboxes will be announced as checked, while the others will not. ("Checkbox 1, checked. Checkbox 2, Checkbox 3).

I wrote the "returnTrueElementOrUndefined" function to replace the alternative "aria-hidden": isSilent ? true : undefined scenario, which requires testing for both situations everywhere it's used. By utilizing this function, I'm relieved of the requirement to test every component for undefined scenarios.

You might be wondering why an aria-label is being used instead of using a <title />. One reason is that the title isn't easily exposed in the icon library I'm using. Depending on how it's used, SVG titles are primarily used for tooltips on mobile devices, and that implementation is inconsistent. A more consistent approach is to use the aria-label attribute.

List and ListItem Components

GitHub (release 0.2.1) - components/base/List folder

The entire navigation component will consist of unordered lists, links and buttons. This example wraps the HTML elements required for lists.

Acceptance Criteria

List AC 1 - Lists must be constructed using the appropriate semantic markup with either ul (default) or ol surrounding list items.
List AC 2 - The list may be displayed horizontally or vertically.

The HTML standard states that the only direct child element of either an unordered or ordered list is a list item (<li />). Checking for this will be handled by jest/axe testing.

The second acceptance criterion just makes it easier to render a list in either a vertical (default) or horizontal orientation.

Code

export default function List({
  children,
  cx,
  isOrdered = false,
  orientation = "vertical",
  testId,
  ...rest
}) {
  const listProps = {
    ...rest,
    "data-orientation": orientation,
    "data-testid": testId,
    className: cx,
  };

  return !isOrdered ? (
    <ul {...listProps}>{children}</ul>
  ) : (
    <ol {...listProps}>{children}</ol>
  );
}

GitHub (release 0.2.1) - List.tsx

Since lists may be ordered or unordered, the system returns the correct HTML element based on a boolean flag. Unordered lists are the default because they are used more frequently than their ordered counterparts. Lists can also be displayed horizontally or vertically, depending on a dataset prop.

For those who have an awareness of aria, you might be wondering why I'm including a data-orientation and not an aria-orientation. It's because the aria-orientation property is only used in specific roles, and neither list nor listitem supports the role.

export function ListItem({
  children,
  cx,
  testId,
  ...rest
}){

    const listItemProps = {
        ...rest,
        className: cx,
        "data-testid": testId,
    };
    return (
        <>
            <li {...listItemProps}>{children}</li>
        </>
    );
}

GitHub (release 0.2.1) - ListItem.tsx

The ListItem component simply wraps the <li /> element. Providing a simple component remains beneficial, as properties, such as cx instead of className, can be standardized.

Button Component

GitHub (release 0.2.1) -components/base/Button folder

Acceptance Criteria

AC 1 - Every button shall have an accessible label
AC 2 - Click, Space or Enter activates the button
AC 3 - When disabled, aria-disabled should be set to true and the event handler should be dissociated from the button.

Every button must have a label, either as text in its children or via an aria-label, especially when the button surrounds an image. Buttons should be activatable with a pointer or the keyboard.

The last acceptance criterion requires more explanation.

HTML allows the disabled attribute to be applied to many interactive elements. Most browsers handle it in a way that causes issues in screen readers. When interactive elements are marked as disabled through the disabled attribute, screen readers will only acknowledge their presence in the elements list/rotor forms control panel. A disabled element is not present at all when tabbing through a page's focusable elements.

This disparity creates a disconnect in perceivability between the screen and the screen reader. It forces a screen reader user to hunt for a disabled, focusable element in the elements list/rotor rather than navigating the DOM directly. This can be considered an equitable use failure, since a screen reader user would have to realize the button is missing and then jump back and forth between the element list/rotor and the page.

When someone is navigating visually, they can still see that a button exists, even if it is disabled. The visual styling, inability to click, and cursor changes help solidify their understanding.

A screen reader user who chooses to navigate a page or form using the tab key may have no idea the disabled control even exists. Instead, the button and its disabled state are only available through the elements list/rotor, and the user must know to check it.

Why do we disable focusable components rather than removing them? The message sent to someone viewing a screen is that something may require their attention to enable it. Perhaps a submit button that only enables when every field in the form meets the requirements (which I do not recommend). How can a user dependent upon screen reader software determine how to enable a button if they are unaware of its existence?

The solution to this issue is to reframe the disabled state by omitting the disabled attribute and event handler, and using the aria-disabled attribute instead. CSS can be styled based on the aria-disabled attribute, and the button will be available to both screen readers and the screen when a user navigates the DOM.

Code

export default function Button({
  children,
  cx,
  isDisabled,
  onPress,
  testId,
  ...rest
}) {
  const buttonProps = {
    ...rest,
    "aria-disabled": returnTrueElementOrUndefined(!!isDisabled),
    className: cx,
    "data-testid": testId,
    onPress: returnTrueElementOrUndefined(!isDisabled, onPress),
  };

  return <RACButton {...buttonProps}>{children}</RACButton>;
}

GitHub (release 0.2.1) - Button.tsx

When isDisabled is set to true, the "aria-disabled" attribute is set on the props, and onPress is removed.

The onPress property combines keyboard, click and pointer handlers and is specific to the component library I'm using and also demonstrates another use of returnTrueElementOrUndefined: it returns the onPress event only when the button isn't disabled. The isDisabled prop is a valid prop to send to the react-aria-component button, but since sending it triggers the disabled attribute on the button, it is never sent through.

If you are using another component library for your button, you might need to send a single handler to each of the onClick, onKeyDown and onPointerDown events to achieve the same effect.

Styling can be applied through the aria-disabled attribute in the stylesheet. Any focusable element should select state changes based on either the value of an aria or pseudo-classes. Additional data attributes may also be used if an appropriate pseudo-class or aria attribute isn't available.

Link Component

GitHub (release 0.2.1) - components/base/Link folder

Acceptance Criteria

AC 1 - Links must be constructed using an <a /> element with a valid href.
AC 2 - Links may only take a user to another location and may not be used for button-type functionality
AC 3 - A link must have programmatically discernible text.
AC 4 - The link should indicate if it will launch a new tab or window.
AC 5 - All hrefs should be sanitized before being exposed

The Link component wraps the link provided by Next/js, which itself extends the <a /> HTML component with a few router-based props.

SEO emphasizes the use of links, not buttons, for navigation. Links and buttons have different semantic meanings and cannot be used interchangeably. A link's sole purpose is to navigate a user to another page, either to a section on the same page they are already on (an anchor) or to an entirely new page, either within or outside the current site. A button executes a process on the current page and, when activated, may or may not redirect the user to another page upon completion.

When a link opens a new browser tab or window to load a new page, it should notify the user before the link is activated. Failure to do so, especially when a user relies on a screen reader, can leave them disoriented and unable to determine what has changed or even where they are relative to their last action. Typically, an icon with a label, or simply hidden text, should indicate that the link opens in a new browser tab or window before the user activates it.

For security, every href should be sanitized to strip out any malicious code inserted.

Code

export function Link({
  children,
  cx,
  href,
  newTabText = "opens in a new tab",
  openInNewTab,
  ref,
  suppressNewIcon,
  target,
  testId,
  ...rest
}) {
  const { getLinkTarget, getIsTargetSpecific, getNewTab, getSafeHref } =
    useLink();

  const safeHref = getSafeHref(href);
  // ...
}

GitHub (release 0.2.1) - Link.tsx

Most cybersecurity attacks start with a simple link, so securing links within the component that renders them is important. If you're not sure whether your link component sanitizes the href it receives, find out; if it doesn't, add a check to your component.

In this case, several utility functions are stored in the useLink hook, including getSafeHref.

export default function useLink() {
const getSafeHref  = (href) => {
  if (!!href && href.length > 0) {
    return sanitizeUrl(href);
  }
  return;
}; 
}

GitHub (release 0.2.1) - useLink.tsx - getSafeHref() - Line 44
If the href exists, then a third-party utility from braintree is used to remove any compromising content. It runs whenever an href is passed through.

 export function Link() {
    //...
 const linkTarget = getLinkTarget(openInNewTab, target);
  const isTargetSpecific = getIsTargetSpecific(linkTarget);
  //...
}

GitHub (release 0.2.1) - Link.tsx

Returning to the Link component, more calls are made to the hook, specifically regarding the criteria for opening in new browser tabs or windows and the required output.

A named or standard target can be passed to the link component. When a new browser tab or window is opened, any subsequent links to a named target will open in the same tab or window. Only when the target is not already available will a new tab open. Targets may include custom names or standardized keywords, which are always prefaced with an underscore.

const getLinkTarget = ( openInNewTab,  target ) => {
  if (target) {
    return target;
  } else {
    return openInNewTab ? "_blank" : "_self";
  }
};

GitHub (release 0.2.1) - useLink.tsx - getLinkTarget() - Line 15

A target is a separate entity from _blank, which requests a new browser tab, or _self, which loads the content into the active tab.

const getIsTargetSpecific = (linkTarget) => {
  const nonTargeted = ["_parent", "_self", "_top"];
  return nonTargeted.indexOf(linkTarget) === -1;
};

GitHub (release 0.2.1) - useLink.tsx - getIsTargetSpecific() - Line 8

Once a linkTarget is known, the system returns information to determine whether to open a new browser tab. Some standardized target types are not candidates, and they need to be accounted for.

 export function Link() {
    //...  

  const willOpenInNewTab = openInNewTab || isTargetSpecific;

const newTab = getNewTab(newTabText, !!suppressNewIcon || !!target);

  const linkProps = {
    ...rest,
    className: cx,
    "data-testid": testId,
    href: safeHref || "",
    target: linkTarget,
  };

  return (
    <NextLink {...linkProps}>
      {children}
      {willOpenInNewTab && newTab}
    </NextLink>
  );
}

GitHub (release 0.2.1) - Link.tsx

A tab will open in a new window only if the functionality is explicitly requested via openInNewTab or when the target is deemed specific.

const getNewTab = ( suppressNewIcon,  newTabText ) => {
  const iconProps = {
    IconComponent: NewWindowIcon,
    label: newTabText,
  };
  if (suppressNewIcon) {
    return (
      <Text isInline={true} isHidden={true}>
        {newTabText}
      </Text>
    );
  } else {
    return <Icon {...iconProps} />;
  }
};

GitHub (release 0.2.1) - useLink.tsx - getNewTab() - Line 25

While it's preferable to display information on-screen when a link opens a new tab, an icon may not always fit the system design. In that case, hidden text is placed in the DOM instead.

Box Component

GitHub (release 0.2.1) - components/base/Box folder

While I don't call < Box /> in the navigation component, I thought it was worth going through because it's such a common use case and, like the Icon component, can help guide developers toward proper ARIA usage.

Acceptance Criteria

AC 1 - If a role is not passed through on a div, then no aria may be present.
AC 2 - If a role is passed through on a div, then a label or reference to a label must be present unless the role is "presentation" or "none".

A Box can render as a < div />, denoting a flow control or a < span />, which is a phrase control. For the most part, both < div /> and < span /> are non-semantic elements, meaning they don't add anything to the conversation. They're useful for grouping and adding spacing between elements and denoting a custom widget with an explicit role.

Every structural HTML element other than < div /> or < span /> contains an inherent role. Composite widgets start with a < div /> to which a role has been explicitly applied. Think of dialog boxes, progress bars, and switches. A Box component must support the implementation of a composite widget, including ARIA, while ensuring ARIA is not applied when a role is absent.

Code

export default function Box(props) {
  const { children, cx, inline, isHidden, label, role, testId, ...rest } =  props;

  let proceed = true;
  if (
    (!inline &&
      process.env.NODE_ENV === "test") || process.env.NODE_ENV === "development"
  ) {
    const ariaLabelledby = props["aria-labelledby"];
    const ariaLabel = props["aria-label"];
    const ariaRole = props["aria-role"];
    const excludedRoles: AriaRole[] = ["presentation", "none"];

    // If the role or aria role doesn't exist or has no meaning, then no aria can be passed.
    if (!role && !ariaRole) {
      const ariaFound = Object.fromEntries(
        Object.entries(props).filter(([key]) => key.startsWith("aria-")),
      );
      if (Object.keys(ariaFound).length > 0) {
        console.error(
          "Dev Error: (Box) - Aria attributes may not be passed when no role is defined.",
        );
        proceed = false;
      }
    } else if (!label && !ariaLabel && !ariaLabelledby) {
      if(!excludedRoles.includes(role) && !excludedRoles.includes(ariaRole) )
      console.error(
        "Dev Error: (Box) - Must pass label, aria-label or aria-labelledby when a role is set.",
      );
      proceed = false;
    }

    // check for singular label
    if (role && ((label && ariaLabel) || (label && ariaLabelledby) || (ariaLabel && ariaLabelledby))) {
      console.error(
        "Dev Error: (Box) - Only one of  label, aria-label or aria-labelledby may be passed when a role is set.",
      );
      proceed = false;
    }
  } 
  // ...
}

GitHub (release 0.2.1) - Box.tsx

Like the Icon component, the Box component only renders in development and test environments when conditions that can't be enforced solely through Typescript are met. The idea remains the same: educate developers on what makes good accessibility.

Because aria attributes are not easily accessed through destructuring, and the component has no idea of what is being passed, the props component is passed through and destructured separately, while the system checks to see if any aria- prepended variables have been passed through.

  const componentProps = {
    ...rest,
    className: classNames({ srOnly: isHidden }, cx),
    "data-testid": testId,
    }
  const divProps ={
    "aria-label": label || props["aria-label"],
    "aria-labelledby": props["aria-labelledby"],
    role,
  };
  if (proceed) {
    return inline ? (
      <>
        <span {...componentProps}>{children}</span>
      </>
    ) : (
      <>
        <div {...componentProps} {...divProps}>{children}</div>
      </>
    );
}

GitHub (release 0.2.1) - Box.tsx

Labels can be passed in a few ways; one is through an exposed "label" prop, which generates an aria-label. An aria-label can still be passed through and used when the label is undefined. If another element is tagged as the label, the id of that element is passed via aria-labelledby. Only one of the three may be passed and used, so the earlier checks enforce that supposition.

Summary

Base components can enhance and enforce security and accessibility. Code can be added to enable developers to provide accessibility easily and to prevent common antithetical choices.

Spacing Considerations in Accessible Design

ShaynaProductions — Thu, 07 May 2026 12:15:00 +0000

Prologue

A while ago, I decided to develop a fully accessible main navigation component in React.

While a preliminary set of requirements has been assembled for the component itself, design requirements still need to be considered.

Most WCAG requirements regarding visual perceivability affect CSS and, by extension, design. If a design prototype in a system like Figma does not meet those visual requirements, it doesn't matter how clean the component code is; the visual aspect will not be accessible. This article considers design requirements, especially those related to WCAG success criterion 1.4.4, Resizing Text.

As I've mentioned before, development isn't the only engineering area where accessibility has to be considered. Whether it's a functional prototype in a tool such as Figma, or implementing the CSS from such a design, there are several success criteria from the Web Content Accessibility Guidelines that must be met, and so those criteria are pulled into the requirements matrix.

Unlike a developer who only needs to be aware of and develop the peripherals associated with perception (screen and screen reader) and operability (pointer and keyboard), team members responsible for the design and styling of a website, regardless of the tools they use, need to be conscious of both neurodiversity and variations of visual impairment.

Neurodiversity requires care when designing the overall site and pages to reduce sensory overload, shorten blocks of text, and maintain high color contrast. Keeping layouts and navigation consistent also enables these users to navigate a website or page effectively.

A user's vision may be corrected with visual aids, such as glasses, or other assistive technology, or it may not. Users may be able to identify the colors chosen, or they may not. Some users may experience difficulties with small text or low contrast and need support, particularly as they age. The Web Content Accessibility Guidelines (WCAG) requirements for vision are intended to support users who experience these issues. Other requirements, while still visual, are intended to support keyboard focus or to enable adequate targeting of interactive objects.

I want to group the requirements around sizing, as detailed in the requirements matrix, and discuss them.

Design Requirements

Text should be able to be resized without assistive technology up to 200 percent without the loss of content or functionality. WCAG 1.4.4 Resize Text (A).

Not every user can assimilate small text. Current recommendations are that most text on your page should have a font size of at least 16 pixels. Care should be taken to ensure not only that text can be enlarged, but also that, when a user enlarges a page, everything on it remains proportional regardless of the browser's font size.

Ensure no loss of content or functionality occurs when text spacing properties are set to specific values—WCAG 1.4.12 Text Spacing (AA).

Contrary to popular opinion, not every user will see your design the way you intended. Users can create their own stylesheets and override your styles. These should be implementable without breaking your entire site. Text spacing properties include the CSS properties line-height, letter-spacing, and word-spacing, along with the margins between paragraphs.

Any keyboard operation should make a focus indicator visible. WCAG 2.4.7 Focus Visible (AA).

When using a keyboard, the focus-visible pseudo-class is triggered as focus shifts to a focusable element, allowing a user to visually identify which element has focus. Styling should be applied, either globally or to a specific element, to help screen and keyboard users know where focus is on the screen.

The size of the target for pointer inputs should be at least 24 x 24 pixels or should have padding around it to conform to a spacing of 24 x 24 pixels between it and any other pointer input—(WCAG 2.5.8 Target Size (Minimum) (A)](https://www.w3.org/WAI/WCAG22/quickref/#target-size-minimum).

People don't have a fixed finger size. Small target areas are difficult for people with larger fingers or those with shaky hands, especially when targets overlap. Creating sufficient spacing between interactive elements ensures the intended target is actually triggered.

Although it isn't specifically mentioned in the WCAG guidelines, there should also be visual indications when an element is hovered over. Focus is for keyboards, hover is for pointers. In many cases, focus and hover states should be similar, if not identical, after all, they convey the same message.

All of these requirements can be implemented through a theming system. A well-designed theming system can automatically apply many of these accessibility features. Conversely, a poorly thought-out theming system can make styling harder to implement and break the accessibility of your screen display.

The repository I created for this series contains a slimmed-down version of the theming system I'm building. The theming system is built on standard CSS, defining colors and spacing and integrates with foundational components to support a default theme.

Theming systems should integrate with browser settings to enable automatic adjustments aligned with specific accessibility features, such as dark mode or font customization, especially sizing.

When using Zoom controls (Ctrl+/Ctrl-) to enlarge a page, every browser simply increases the pixel size. Actual font sizes are not affected. But what happens when the underlying font size itself changes?

Every browser sets a font size, which can be defined as 1rem (root em). Every browser sets the default font size to 16px. Almost every corporate and government website uses a design that assumes the font size is set to 16 pixels.

Why 16 pixels? As a geometric progression, the doubling of numbers: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 is a consistent progression within both computer hardware and software. Screens are designed to have pixel sizes evenly divisible by these numbers. The progression, though not a true Fibonacci sequence, is aesthetically pleasing and has become a de facto industry standard.

When a user changes the default font size, the 1rem unit also scales. Instead of 1rem being equivalent to 16 pixels, 1rem can be returned as a different number of pixels, depending on the browser's font-size setting.

Every browser has a setting to adjust the default font size. Chrome and Edge use a "small, medium, large" basic setting while also allowing more granular changes to font face and size. Firefox lets you choose the default font size, while Safari only lets you restrict the smallest font size. Realistically, there's no way to determine how many pixels actually make up 1rem on a user's browser.

I'm sure this realization comes as a surprise to many people, especially designers, and it can and does cause issues when a design or theming system doesn't account for a possible change in rem units.

Change the font size while browsing your site and see how it fares:

Chrome: Settings -> Appearance -> Font size
FireFox: Settings -> Language and Appearance -> Fonts
Edge: Settings -> Appearance -> Fonts -> Font Size
Safari: Settings -> Advanced -> Never use font sizes smaller than [select size]

The Sam's Club homepage is an example of what happens when the default font size changes and the application doesn't account for it. I increased the font size in Chrome to "very large," which set the rem value to 24px. The website mixes px and rem, which contributes to the issue.

[Screenshot of the Sam's Club home page using the default browser font size of 16px]

[Screenshot of the Sam's Club home page with the browser font size set to "very large" (24px)]

Notice the obvious changes in the header and the tags just below. Vertical spacing is no longer centered, and the dollar amount is obscured because it now sits on top of the bottom wheels, forming the cart icon.

Suddenly, a design is being driven by incorrect pixel values. After all, 0.5rem off a 24 pixel base font is 12px, not 8, and .25rem is 6px, not 4. Carefully designed ratios and proportions can and will be thrown off.

Having a user adjust the browser font size shouldn't disrupt your design, but when the system isn't designed for proportional scaling, the results are obvious and unprofessional.

Take your own site for a spin, reset the browser font size and see what happens. I'll wait.

Designing for user-defined font sizes is possible without sacrificing the base-16 design assumptions. Theming systems can accommodate this by standardizing the relative pixel value to 1/16 of a rem, regardless of the actual rem value.

@layer system {
    :root {
        --sizing-base: 1rem;
        --sp-px: calc(var(--sizing-base) * 0.0625);
    }}

base.css

I use the —sp namespace to ensure no other variable can override my choice, and a relative px is 1/16th of the browser's font size. Everything, depending on placement — padding, font-size, width, or positioning — uses calc(var(--sp-px) * #), where # is the number of pixels. This guarantees that the ratio and proportions remain consistent regardless of the user's chosen font size.

CSS cascade layers solve an issue with specificity by allowing themes to set layers of specificity and the order in which styles can be overridden. In this case, the system layer is near the bottom of the layers I've defined for my site, '@layer reset, system, default-theme, base-component, common-component, system-component, main;`; meaning it will be applied early in the process.

The more thought and functionality the theming system receives, the easier it will be to implement accessibility across design and development for designers and developers. As an added bonus, appearance can be guaranteed to be consistent and usable.

Next Steps

Before a clickable prototype can be created, base components must be created and updated, and their styles need to be tied to the theming system. The requirements for these components can be found in the accessibility requirements.

I'll be covering this in the next article.

Creating Initial Requirements for an Accessible Navigation Component

ShaynaProductions — Tue, 05 May 2026 12:15:00 +0000

Prologue

A while ago, I decided to develop a fully accessible main navigation component in React after a fruitless search through third-party component libraries, npm packages and even GitHub repositories.

A complex component needs requirements around all aspects of the component, and this article begins the process of defining those requirements.

Note: This article is one of a series demonstrating building a React navigation component from scratch while considering accessibility through the process. This article addresses requirements gathering and architectural decisions to be considered before code is written.

This article is fairly long, and so a set of content links is provided.

Content Links

Introduction
Wishlist
Gathering Requirements
- APG
- Deque Accessibility Checklist
Development Requirements
- Requirements Discussion
HTML Structure
Handling List Exposure
Next Steps

Introduction

This article is the second in a series in which I walk through the steps I've taken to create an accessible navigation component with React. In my previous article, I covered the basic requirements for evaluating third-party components while seeking an accessible navigation component.

When I didn't find any component that met even the minimal requirements, I decided to build my own, which means gathering even more requirements.

Whether you call them acceptance criteria or requirements, it means the same thing—instructions detailing what is required for a ticket to be considered complete. Acceptance criteria are a contract between those who assign the tickets, those who code and those who test.

I've seen very few tickets over the course of my career that offer detailed user stories. Many lack adequate acceptance criteria as well. And that might be well and good if developers and testers were fully conversant with accessibility and the requirements for any specific component.

That isn't our reality, and depending on an LLM to add in accessibility basically sets you up for failure. Detailed requirements require detailed knowledge. If your business analysts lack the knowledge, depending on your developers to bring it probably won't help.

I've seen more than my share of tickets where scrum masters have decided that marking "Must conform to WCAG" as the definition of done is adequate, with no further consideration of what that entails. Even worse is having that phrase show up as an acceptance criterion. What does a phrase like that mean for the development and testing of a specific component?

I'm not saying that every requirement for a complex widget whose development will span across sprints needs to be in place before the first ticket is written. But the most important and consequential requirements, the ones that will drive how a component is architected, have to be there before the first ticket is scheduled and ready to be picked up.

If I'm going to take the requirements I used to analyze third-party packages and expand them to create a universally accessible component, I have to consider exactly what I want from the navigation component of my dreams.

Wishlist

The ability for the component to display as either controlled (opened and closed from another component) or uncontrolled, so that I can use the same component when rendering for desktop and mobile.
The ability for the top row of the component to be displayed horizontally (desktop) or vertically (mobile).
The ability to render a JavaScript object into a properly formed navigation component.
The ability to render links and buttons, manage sublists within the same list, and support nesting down to at least two levels of navigation.

Back to Content Links

Gathering Requirements

Requirements for users of screen and pointer are fairly easy to come up with, and without specific acceptance criteria, would most likely be what is coded for a ticket with a user story of "As a user, I want to be able to access the main navigation and move to another page on the website."

But I want more. I want to be sure my navigation component is perceivable through both screen and screen reader and operable through pointers, keyboard and voice.

Wearing my business analyst hat (🖊), the first question that comes to mind is: Where can I find the starting requirements for a main navigation component?

APG

I'll start by returning to the disclosure navigation menu pattern available in the Aria Pattern Guide, also known as the APG.

The APG isn't as consistent as I would like; requirements have to be extrapolated rather than being considered canon. Accessibility features and keyboard support especially need to be considered holistically, not as blueprints.

The main list is wrapped in a < nav / > element.
Open dropdowns should close when Escape is pressed, or focus moves out of the navigation region.
There should be a visual indicator of the show/hide state.
Navigating through a horizontal navigation component should prevent the default page scroll behavior.
Navigating with arrow keys does not replace tabbing through the buttons and links.
Keyboard behavior
- See Keyboard support

Keyboard behavior, as written, is inconsistent and must be extrapolated. When the reference is from link to link or from button to button, it assumes the navigation must conform to the sample code displayed. Not every navigation will be this rigid; buttons opening sublists may, in fact, be somewhere within another sublist, not just on the top row. The requirement to change the current page when pressing the Enter Key or to display a visual indicator of the show/hide state is also a function of the example and not a specific requirement. However, it does highlight the need for a high-contrast theme (which is not included in this demonstration).

The Role, Property, State and TabIndex section is specific to the aria attributes necessary.

aria-controls - requires each button controlling a list to be linked to the list via an ID on the list.
aria-expanded (true/false) indicates the state of the list's visibility on the button.
aria-current (page) indicates a link associated with the current page.

Deque Accessibility Checklist

There's another list to refer to: Deque's accessibility checklist. I find the PDF useful because some requirements are scattered across topics, and I can search it.

The requirements I'm looking for are under site navigation, where three topics are listed: Consistency, Multiple Ways and Navigation Lists.

Consistency is achieved by developing a component that works in both desktop/laptop and mobile environments and delivers the same navigation across pages. The development of the component that can be activated in the header achieves this goal.

Multiple Ways requires that multiple ways to find other pages on the site be available. Developing a navigation component is one way.

These aren't requirements for this component, though they are important at the site-wide level. The requirements I need are in the last topic.

Navigation Lists have two basic requirements: Markup, which requires the navigation list to be contained within a <nav/> element; and a user must always have an indication of which page in the list is the page the user is currently viewing. The requirement specifies that indicators must be set up for both screen and screen reader users.

Back to Content Links

Development Requirements

Back when waterfall development was a thing, all requirements had to be gathered before any programming began. Agile, on the other hand, either crams requirements into a Confluence or SharePoint space, rarely acknowledges them on tickets, or skips detailing front-end requirements and relies on developers' expertise to build a component properly, usually based on a design document.

Acceptance criteria are the requirements that direct developers to the outcomes required and provide a clear path for testing them. In my experience, across government agencies and private companies, it's been rare to see any acceptance criteria that spell out accessibility requirements beyond the vaguely worded "must meet WCAG 2.x".

Why aren't accessibility requirements spelled out? My guess is that no criteria are given because it's rare for someone to understand accessibility and craft the specific requirements around it. It sets up a fail spiral, or at least creates a lot of hard-to-fix tech debt.

If a component will be developed over a series of sprints, I don't think all specific requirements need to be finalized before the first ticket is assigned; however, all accessibility requirements for a particular ticket should be fully defined before work begins.

Between the wishlist, evaluation requirements and the information I've extrapolated, I can begin assembling a list of requirements/acceptance criteria and specify which ticket each is associated with. Below is a list of headings indicating possible tickets to write, along with some of the requirements.

You'll note that the earliest ticket, Structure and Transformation, has the most requirements, while subsequent tickets are less precise, and some have no requirements yet, only the knowledge that they will be necessary. That's Agile: the requirements/acceptance criteria only need to be in place before ticket grooming.

A list of the initial development requirements may be found on the Requirements Matrix and are also given below.

You may skip to the requirements discussion if you are viewing the matrix.

Structure and Transformation

The Navigation Component should be contained in a landmark region. The navigation should be presented as a nested unordered list within the < nav/> landmark region.
Lists should present with a role of "list", list Items should present with a role of "listitem".
The navigation component should be able to be presented as horizontal (desktop - default) or vertical (mobile presentation).
When navigation is displayed as uncontrolled in a horizontal layout (the default behavior), the first row of focusable elements should display as open by default.
Buttons are associated with a sublist and indicate if the sublist is open or closed.
A visual indicator is used to represent the state of the sublist's expanded status.
A sublist may be toggled to open or close when the button associated with it is pressed.
The state of a list's visible or hidden state should be easily perceived by any user
A link should inform users if it corresponds to the current page for both screen and screen readers.
A JavaScript object containing a properly formed object should be able to be transformed into properly formed ListItems, Buttons and Subnavigation lists.

The structure and transformation requirements detail the main HTML structure and state changes when a sublist is closed or opened. After the requirements in this section are completed, a skeleton and pointer usable navigation component should be fully realized. Enough to be able to support concurrent design and styling work, and as a base for adding in all the rest of the requirements to enable full accessibility, including keyboard handling.

Back to Content Links

Single List Keyboard Handling

A Single List should implement Keyboard navigation with the following Keys: Home, End and the arrow keys.
Within a single list, the arrow keys should shift focus to the next (right arrow) or previous (left arrow) focusable element within the current list.
Within a single list, the Home key should shift focus to the first element on the current list.
Within a single list, the End Key should shift focus to the last element on the current list.

Keyboard handling begins with handling focus for just a single list. Nothing more.

Data Handling Between Components

No requirements detailed yet

While not much is known yet, it's clear that finding list items within list components will require a link or button in a list to access information, not only within the elements in the list it resides in, but also in other nested lists associated with focusable elements.

Keyboarding Between Components Up/Down

The Down Key should shift focus to the next element within a list and down between open sublists.
The Up Key should shift focus to the previous element within a list and up between open sublists.

Another keyboard ticket, this time for allowing focus to shift between list components, dependent on data handling.

Keyboarding Between Components Tab/Shift+Tab

The Shift+Tab Key should shift focus to the previous element within a list and up between open sublists.
The Tab Key should shift focus to the next element within a list and down between open sublists.

Tab and Shift+Tab should always move the focus to the next item in the DOM.

Back to Content Links

Data Handling For Closings

No requirements detailed yet

What happens when a list is closed? How does it handle other open lists? While not enough is known to begin creating requirements at this stage, it's possible some data will need to be passed between list items residing in different components. The requirements in the next section: Closings, Entries and Exits should help drive the requirements for data handling.

Closings, Entries and Exits

The Tab and Shift Tab Keys should allow exiting the component at both the first and last focusable elements.
When Escape is pressed anywhere in an uncontrolled navigation component, all open sublists close and focus shifts to the topmost parent.
When focus shifts outside the navigation component, all open sublists close.

A complete component allows for movement into and out of itself using the Tab Keys. Requirements are also necessary to determine what happens with any open sublists when a component is exited.

Controlled Navigation

When the controlling element is activated, and the navigation component is closed, the navigation component should open and set focus on the first child in the first row.

Rather than create two separate components for desktop and mobile, the goal is to combine them into a single component. There will be differences to handle when a button controls the navigation component and displays the top row vertically rather than horizontally. Any differences in display and keyboarding will need requirements moving forward.

Requirements Discussion

If it wasn't obvious before, this component won't be a simple one-sprint-and-done. It's going to take time, thought and resources. It's okay at this stage to know something needs to be done, even if you don't know the exact specifications. The component will need to manage data, but what the data is and how it should be managed still needs to be considered.

Grouping requirements allows similar work to be handled in a single ticket and layers accessibility into development through progressive enhancement, which is how these articles and the code will be structured.

Back to Content Links

Speaking of structure.

HTML Structure

When possible, a valid HTML structure should be decided upon before any code or design work is begun. Knowing what the rendered code should look like and working towards a skeleton component that provides the structure first means design and development can proceed concurrently, ensuring styling and operability can be easily integrated.

When it comes to development, operability has to come first. It doesn't matter how much time and effort have gone into making something look good if the underlying structure supporting it makes it harder to operate or style. A developer should be tasked with making sure the component works correctly before being required to make it look a certain way.

Conversely, those tasked with creating a design, especially if they're also familiar with CSS, can receive a skeleton component with basic functionality or just the HTML structure requirements for a Figma or other design system output, and ensure the design works with the structure.

In this case, the structure output should resemble the HTML below.

<nav>
    <ul>
        <li><a href="#" id="item-one">Item One</a></li>
        <li><a href="#" id="item-two">Item Two</a></li>
        <li>
            <button id="item-three">Item Three</button>
            <ul id="subnav-1">
                <li><a href="#" id="item-four">Item Four</a></li>
                <li><a href="#" id="item-five">Item Five</a></li>
                <li>
                    <button id="item-six">Item Six</button>
                    <ul>
                        <li><a href="#" id="item-seven">Item Seven</a></li>
                        <li><a href="#" id="item-eight">Item Eight</a></li>
                    </ul>
                </li>
            </ul>
        </li>
    </ul>
</nav>

The agreed-upon HTML structure must be considered valid; this can be verified by running the code through an HTML validator. I use the W3C Nu HTML Checker, which can test code from a URL or a file upload, as well as rendered code copied from a browser's dev tools.

Screenshot showing validated HTML structure

Back to Content Links

Handling List Exposure

Currently, the requirements specify opening and closing subnavigation lists but don't specify how to do so, leaving it to the developer assigned to the ticket. How the list is rendered makes a big difference to accessibility, so the determination and acceptance criteria for how sublists are rendered should be written before the first ticket is in progress.

There are three ways to disclose previously hidden subnavigation.

Choose only to render the subnavigation when it is open {open && (<ul>…</ul>}.
Choose to hide closed navigation lists using display: none.
Choose to hide the list from screen view, while still exposing it to screen readers using a screen reader-only class (.srOnly).

To adequately assess these choices, an informed understanding of how users interact with screen readers is necessary. Every screen reader provides multiple options for finding specific element types that are rendered on a page.

Navigate to a specific landmark role or heading and then use the tab key to move through the page from that particular point.
Pull up a list of similar structural elements and allow the user to move through the list regardless of where those elements are located on a page. This is called the elements list in NVDA and Jaws, while VoiceOver calls it a rotor.

Most disclosure patterns in React tend toward option 1: render the list only when it is visible. The second option, using display: none, effectively hides the closed sublist from both screen and screen readers, and is the behavior demonstrated in the example shown for the APG Navigation Disclosure pattern. Neither option exposes the full list of navigation links within the elements list/rotor and forces screen reader users to navigate the list in the same way a screen user does, by navigating to sublists and finally finding the link they want.

Within a screen reader, the elements list/rotor exposes all interactive and structural elements, such as landmarks and headings, available on a page when it loads or re-renders. This includes all the other links contained in the header and footer. Since screen reader users regularly use the elements list/rotor to navigate a site, is it equitable to only provide links if they are visible on the screen?

Option 3 makes the full list of navigation links available in the elements list/rotor as soon as the page is fully loaded. I would argue that the main navigation links should be fully accessible to screen readers at all times, enabling a screen reader user to seamlessly discover their next navigation target regardless of how they choose to find it.

A class that hides items from the screen while still keeping them available in the DOM should be globally available. The class is fairly common, and variations can be found through web searches. The one I use is:

.srOnly {
   .srOnly {
  border: 0;
  clip: rect(1px, 1px, 1px, 1px); 
  clip-path: inset(50%); 
  height: 1px;
  margin: -1px;
  overflow: hidden !important;
  padding: 0;
  position: absolute !important;
  width: 1px;
  white-space: nowrap !important;
}

Using this option adds some complexity for screen/keyboard users, so this architectural decision should be considered early in the process. A requirement detailing the decision has been added to the Structure and Transformation group.

Sublists should be hidden from the screen, but available through the DOM when they are closed.

Back to Content Links

Next Steps

I've created a repository, accessible-react-navigation-demo, to store the code that will be built. It's built on Yarn 4.1.2, Next.js 16.x, and React 19.x, using TypeScript. The code will be released as progressive enhancements, building off the prior release and adding functionality and accessibility throughout. Each release will be linked to an article that provides links to the code for that release, along with examples.

Why release this as a demonstration series rather than a third-party library ready for integration? I firmly believe that learning to work with accessibility is a process, and what better way to learn than to go through it?

Besides, I'm using third-party base components and hooks as well as a simplified, still-rough version of the theming system I'm currently building for my website, which likely aren't in your libraries.

The initial repository setup included everything necessary in package.json and configuration, and added code to implement testing using Jest and react-testing-library. I plan to aspire to 100% code coverage (with judicious use of ignore commands).

Before a clickable prototype can be delivered, any components that render HTML elements must be imported and updated to verify they meet accessibility requirements and to make it easier for developers to add accessibility while coding.

There's still more to get through before we begin coding the navigation component. I want to set this project up for success, and that means preliminary work must be in place before coding starts.

Hunting for an Accessible React Navigation Component

ShaynaProductions — Thu, 30 Apr 2026 12:15:00 +0000

Prologue
When I needed a main navigation component, I did what most developers do: I went looking for one. My requirements were simple: I wanted a navigation component that properly identified itself, that worked with both keyboard and mouse and was properly structured to support screen reader use.

I didn't find one.

So I ended up writing my own, and along the way, I thought it might be a good idea to document my progress to help educate others about what it takes to create an accessible complex widget.

I wrote the component as a demonstration to expose the process of thinking about accessibility at every step. The code base (excluding the third-party libraries I've used) can be copied and pasted into your code base, with changes made where appropriate (using your own base components and hooks, as well as your own theming and design system).

Through a series of releases and accompanying articles, I'll guide you through incorporating additional accessibility into your base components, then layering functionality and accessibility at every step until a fully accessible navigation component capable of displaying as a desktop or mobile menu is achieved.

The repository code is fully typed and tested to 100% code coverage (with the help of a few Istanbul ignore comments). Each release is tied to one or more articles and contains multiple example pages with code examples that link to the appropriately tagged release on GitHub.

Be warned, some of these articles are fairly long. This particular article marks the beginning of the process, focusing on what to look for when seeking a third-party component.

What do you look for when tasked to find a complex third-party component?

It's not uncommon for developers to hunt for existing components in third-party component libraries, the NPM library, or code in active repositories, then run examples and click around to confirm it meets the requirements for a particular need.

The challenge, of course, is that accessibility needs to be considered, but what kind of standards can be applied during an evaluation? A full audit of a component using something like Accessibility Insights might be useful, but only once a preliminary analysis indicates its potential.

The success criteria of the Web Content Accessibility Guidelines, also known as WCAG, serve as the ultimate arbiter but are deliberately written to encompass a wide range of technologies and, as I've mentioned before, are set as general guidelines rather than focusing on any one technology.

Fortunately, there are two other resources I am aware of: the ARIA Authoring Practices Guide, also known as the APG and the Web Accessibility Checklist maintained by DeQue.

The APG outlines best practices for labeling, keyboard navigation, and ARIA compliance in accessible components. However, its guidance is often based on simplified examples and should not be taken as the only way to achieve accessibility. The APG site is organized into patterns and practices, with most component information provided in patterns.

Deque's Web Accessibility Checklist can be helpful by specifying techniques for specific component types and linking them to WCAG Success Criteria or Best Practices.

I want to share how I went through the process when I needed a main navigation component while working on the revised version of the nudgestories website.

We often call a component like this a menu, and developers often adapt a menu component for this purpose. But is that really the right call? Are menus really usable for navigation? The first place I went to answer this question and gather requirements for evaluation was the APG, which lists an example of a menubar navigation pattern.

In this case, a prominent caution box appeared on the page, with the following warning.

Warnings exist for a reason, and the requirements for this pattern make it clear that the menubar adds unnecessary complexity to the main navigation component.

I then visited the recommended link for the Example Disclosure Navigation Menu and compiled a wish list of requirements to use in my evaluations.

Each pattern in the APG identifies the roles, along with the aria attributes, notes keyboard support and accessibility features. Keyboard and accessibility support are tied to the relatively simple examples, and the actual requirements must be extrapolated rather than simply accepted.

I identified my requirements using the concepts of Perceivability and Operability from WCAG, and mapped them to the corresponding success criteria, which can be viewed.

Requirements

Perceivable - The component should be perceivable to every person who encounters it.
- The Navigation Component should be contained in a <nav /> landmark region. (1.3.6 Identify Purpose)
- Navigation should be presented as a nested structure of unordered lists.(1.3.1 Info and Relationships)
- Lists should present with a role of "list" (inherent in an <ul /> element), items should present with a role of "listitem" (inherent in a < li /> element). (1.3.6 Identify Purpose)

The first three requirements explicitly specify the structural and semantic HTML elements required to develop the navigation component. If a component doesn't meet these foundational requirements, it's not worth my time looking any further. And while the component could be achieved with < div role="" />, native components have inherent functionality that isn't usually available when a role is simply applied to a div.

These three requirements are the easiest to look for and will allow me to identify any non-conforming components fairly easily. I'll just have to look at the rendered source code. If it meets these three requirements, I can continue the evaluation using additional requirements as listed below.

Perceivable - (continued)
- Buttons are associated with a sublist and indicate if the sublist is open or closed. (1.3.1 Info and Relationships)
- Any user should easily perceive the state of a list's visible or hidden state. (4.1.2 Name, Role, Value)
- A link must indicate it represents the current page through aria-current. (1.3.1 Info and Relationships / 4.1.2 Name, Role, Value)
- Buttons are associated with a sublist and indicate if the sublist is open or closed. (1.3.1 Info and Relationships)

The remaining perceivable requirements mandate that any information available to a screen user should also be identifiable through a screen reader.

Operable - The component should be operable to every person who encounters it.
- A sublist may be toggled to open or close when the button associated with it is pressed. (1.3.1 Info and Relationships)
- Any open dropdown closes when the entire component loses focus. (1.4.13 - Content on Hover or Focus)
- The component should allow keyboard navigation through the following keys: Enter, Escape, Space, Tab, Home, End and the arrow keys. (2.1.1 - Keyboard) (As extrapolated from APG Disclosure Navigation Keyboard Support)

The first two operable requirements don't specify how something is done; they only state that it must be done. But it's helpful to know that any interaction available through a pointing device should also be available when a keyboard is used.

Assessing Third-Party Components

When assessing third-party components, it's always a good idea to evaluate the libraries already in use for your site before adding another. In this case, the third-party component library I'm using is Adobe's react-aria-components, a primitives library containing unstyled UI components.

While there's always room for improvement, Adobe pays close attention to accessibility requirements. I've worked with several styled-component libraries before, and I like the freedom from having to fight opinionated CSS. You can read the principles Adobe used to create this library on the React Aria Quality page in their documentation.

React Aria doesn't have a specifically named navigation component, but it does have a menu component. Since "menu" and "navigation" are often used interchangeably, I'll evaluate this before moving forward.

The easiest way to begin the evaluation is to inspect the rendered HTML for an example.

Screenshot - React Aria Menu with Dev Tools open

The example menu doesn't look promising on the screen as it shows items associated with an application rather than navigation. And a peek at the source confirms that it does not conform to the HTML structure required by my evaluation. The output lacks the < nav> role and does not expose nested lists; further, the menuitem role on each div does not match my requirements for a listitem role.

When rejecting a component from a library already in use, there's bound to be pushback; someone in a standup meeting will point out that just because the example shows applications like menus, surely the code can be tweaked to display navigation. And why is it so important for the code to meet those unnecessary structural HTML requirements? After all, it does everything necessary, right?

To explain why this component is not appropriate, there needs to be an understanding of the differences between the menu/menuitem and list/listitem roles.

A menu pattern is typically used in desktop applications and their browser-based cousins (those with the role "application"). Think browser-based Google Sheets, or the online version of Microsoft Word or even Figma Design. Those require menus. A navigation component that only displays links and sublists that open when triggered by buttons doesn't need the complexity required of a menu. In fact, digging into the documentation further reveals much more complexity than is required for a navigation component; typeahead and multi-item selection are not indicated for one.

Well, my third-party component library isn't going to give me what I need, so I searched npm and GitHub for anything I could fork and came up short. I remember thinking that somewhere there must be a navigation component that does what I want, so I checked out other third-party libraries.

A library I use for common hooks, Mantine, also provides components, so I headed over to its site to take a look.

Their website does show a navbar component. The screen example doesn't meet my needs, and the rendered HTML doesn't meet my requirements.

Screenshot of the Mantine Navbar example.

Mantine actually does surround the code with a < nav / > element, but the rest of once again examining the HTML shows me their component doesn't nest buttons or links in lists or list items.

I began looking further afield, moving onto some of the better-known component libraries with a preference towards primitives:

Material-UI has attempted and abandoned several projects to create a primitives library, which makes me wary of consuming its current primitives library, Base-UI. It also lacks a navigation component, but does include a menu component.

Screenshot of Material UI Menu component example.

Examining the HTML showed many of the same issues as the Adobe React Aria component. Lack of a < nav / > surrounding the code, and while it does use an unordered list and list items, the roles are specifically set to menu and menu-item.

React Bootstrap includes a navbar component.

Screenshot of React Bootstrap NavBar detailing the lack of proper HTML structure.

The HTML structure is lacking: multiple links are wrapped in divs rather than being individually nested within list items in an unordered list.

Radix UI shows some initial promise, but the rendered HTML still doesn't conform to my structured HTML requirements.

Screenshot of Radix navigation menu.

Within the example, buttons are contained in an unordered list, which is contained in a nav element. But the failure comes when a button is activated, and the dropdown is not nested within the same list item as its parent button.

No component library I reviewed provides a navigation component that meets the first three perceivability requirements.

I have no choice but to create an accessible React navigation component that meets the criteria I've already identified. Are the requirements I've gathered enough? Probably not.

Join me next time as I begin assembling the initial requirements for creating a universally accessible main navigation component.

The Modalities of Accessibility

ShaynaProductions — Wed, 29 Apr 2026 12:15:00 +0000

There are nights when I have dreamt of a perfect world where, among other wishes, equitable access is a concern for everyone involved in developing a website. Unfortunately, the world I dream of is not the world we live in.

I remember a contract where a graphic designer took it upon themselves to develop a help module in React since no team had the capacity to take it on. During peer review, I discovered issues with the module in screen readers and a keyboard trap. When I raised them, the designer flat-out refused to fix them, telling me during a meeting called to address the situation, "I don't care about blind people."

I was shocked but not surprised. In the world we live in today, caring about accessibility often only happens when someone personally knows someone affected by a specific disability. In Agile development, a world of sprints, tickets, and the pressure to "move fast and break things," teams tend to push out incomplete components designed to work along the "happy path" and, when confronted with the fact that their work isn't available to those with disabilities, offer to come up with the plan to fix accessibility later.

The work of identifying specific disabilities and explaining how to address issues related to essential needs is often overlooked. The reality is that these issues rarely get resolved in a way that genuinely helps those who need it most. When accessibility is addressed at the end rather than built into the process from the start, the users who need it most end up suffering.

Let's face it, as developers and designers, we love the new, shiny aspects of our craft, and many of us, it seems, aren't conversant with the foundational structures that support accessibility. Making sure our content is available to everyone seems to be a feature everyone is content to let languish in the backlog.

Over the years, I've had the most success educating developers about accessibility when I've stopped leaning into guilt and compassion and focused on the nuts-and-bolts of what is necessary. And this means conceptualizing the Web Content Accessibility Guidelines differently.

Commonly referred to as WCAG, the guidelines are an international standard adopted by many countries. Within the United States, it has been adopted under Section 508 of the Rehabilitation Act, which requires federal websites operated by the Executive Branch to be accessible, and Section 504 of the same act, which requires organizations receiving federal funding or assistance to ensure their websites are accessible. This includes state agencies and publicly funded education systems, as well as public companies that receive federal financial assistance. Additionally, although not explicitly written into the law, U.S. courts have consistently upheld that websites run by private companies should also be subject to the same accessibility standards, through a variety of cases and appeals.

The WCAG guidelines and success criteria are deliberately vague to remain relevant in a rapidly changing environment. The same standards apply whether the medium is a PDF, a page, or an application. The guidelines can be intimidating, and given their organization, they don't always make much sense to a developer who's been given a ticket that simply lists "must meet WCAG 2.x" as an acceptance criterion. Where to start? How to implement?

WCAG seems to be a dark hole into which developers and designers fear to fall. I want to propose another way of looking at the requirements through the lens of modalities and our physical abilities.

The WCAG guidelines are grouped into four principles: Perceivable, Operable, Understandable, and Robust, collectively referred to as POUR. For the moment, I want to focus on the first two principles.

Perceivable

All the information we receive comes through our physical senses. Of the senses available to us, three —vision, hearing and touch— are used to consume digital information. We read text, look at images and videos on a screen, and hear music and speech through speakers. We can even experience the digital world through touch: the vibrations of a game controller or the raised dots from a braille printer. While many of us have access to all three senses, some have access to only two, and still others to only one.

The common denominator is that each of the three senses we use to perceive content on a computer is mediated by a peripheral device. We use screens, external or wired in to view, speakers, separate or integrated to hear, and still other devices such as a game controller or braille printer to feel.

So, perceivability can be achieved through peripherals, and to make content perceivable, we have to ensure it is available via a specific peripheral that accommodates one of the three senses.

WCAG's first principle is Perceivability. All information and user interface components must be presentable to users in ways they can perceive. We can accomplish this by making sure all content is seen and heard. Audio content should include transcripts for screens; video content should include descriptions and captions, along with transcriptions for those who cannot hear.

Screen readers are software programs that read the underlying content that ultimately displays on a screen. When coded structurally and semantically, the content on a screen can be perceived through different peripherals, such as audio from a speaker, or reduced to raised dots on a bar for reading through a braille printer.

When considered through this filter, it becomes obvious that our code needs to target two peripherals: screens and screen readers.

Most of the guidelines under the perceivability principle are mainly the responsibility of groups outside of front-end development. Media accessibility, be it text alternatives, transcriptions, audio descriptions and captioning, typically would be the responsibility of content producers and creators. It's not a developer's responsibility to oversee those requirements; it's just to write code that makes them available.

How something is perceived on the screen, from theming, colors, layout and displays is in the purview of the design team. It's their responsibility to ensure that those with vision impairments can perceive the same information as those with perfect vision.

Front-end developers do have some responsibility for perceivability. The underlying HTML, for example, should be semantic and well-structured. They are responsible for ensuring that metadata, such as state changes and relationships, is available to screen readers through HTML and ARIA attributes.

Operable

Just as we use peripherals associated with our physical senses to perceive, we use other peripherals associated with movement to operate and interact. Sites can be interacted with through peripherals, such as a mouse or trackpad (known as pointers); we also interact through keyboards, and increasingly we use our voice.

We can then specify that our sites must be operable via peripherals that support pointing devices, keyboards, and voice.

Front-end developers bear the greatest responsibility for operability, though designers have some considerations as well, particularly regarding resizing, image flashing, headings and labels.

Voice

Using our voice to control how we interact with websites is becoming increasingly common. Windows 11 and Macs have built-in programs, and some browsers offer plugins and settings for voice interaction. Not everyone using their voice to control a site has a disability; situational and convenience also rank high.

The most important aspect of operating a site via voice is ensuring that the words displayed on the screen are also programmatically associated with the component or element. This means the visual label and programmatic name must include the same words. It doesn't mean the words need to be exact; the preference is to append any differences rather than prepend them.

WCAG 2.5.3 Label in Name (A) requires that the visual label for a control be a trigger for speech activation.

Consider the following code.

First Name: <input name="firstname />

Wrong (contrived, but still bad)

In this case, the "First Name" field has no association with the input, so any voice-operating user will become frustrated when they cannot trigger the input to fill out the form.

<label for="firstName>First Name</label><input name="firstname" id="firstName />

Better

A user could enter their first name through their voice because the label is correctly hooked up to the input.

Since labels and displayed text are outside a developer's control, the responsibility for ensuring the component name matches the displayed label lies with whoever is responsible for text enhancements. A developer's responsibilities here are mainly to notice when something doesn't meet the requirement and to request an enhancement from the responsible parties, whether the design team or the content owner.

Any component where an aria label changes the wording shown must still include the visual wording for voice control to work, and whoever is responsible for the underlying wording and labeling must be aware of the issue.

Pointers

Pointers can include mice, trackpads, joysticks, and basically anything you can do with a finger or two or three. Many assistive technology devices mimic a simplified single-pointing device, usually a mouse event.

When implementing handlers, it's important to understand that some devices require mouse events, while others require pointer events, and to ensure your handler works in all cases. React supports a synthetic event handler onPointerDown that fires when a pointer is clicked on a tag or element.

Keyboard

When it comes to keyboard usage, there are really two distinct sets of considerations. Screen readers on desktop computers require keyboard use, which presents different considerations than those for users who rely on a screen and keyboard for navigation.

Keyboard with Screen Readers

Every screen reader uses specific keyboard keys for all of its operations. There are keyboard commands that allow users to bring up lists of interactive elements, move through tables, skip to the next heading or link, and move through forms.

Every screen reader uses different keys and key combinations for their users to navigate and interact with content, so care must be taken not to interfere with these keys when implementing your own. Reference guides for the most popular screen readers can be found at Deque University Screenreaders page.

For the most part, navigation outside the screen reader's key commands is handled by the Tab and Shift+Tab keys. Some screen readers limit the arrow keys to specific component types, such as select elements and radio groups, while others expose and allow their use in other custom components.

Keyboard with Screen

With all the focus on accessibility for people who are blind, those who use a keyboard and screen combination can sometimes feel left out. Several assistive technologies mimic a keyboard, including on-screen keyboards activated by a switch, head and eye tracking, and sip-and-puff devices.

Anyone using a screen should be able to navigate solely through the keyboard. Except for text inputs (single or multi-line), the most commonly used keys are Tab, Enter, Space, Escape and the arrow keys.

Both screen/pointer and screenreader/keyboard users have a variety of ways of navigating to the content they are interested in. Screen-using keyboard users are the only users forced to navigate a web page linearly. They can benefit from bypassing common elements, such as header elements or long lists of interactive elements.

When considering operability for these users, it's the interactive, focusable elements that deserve our attention.

The basic interactive elements within HTML are <a />, < button />, <input />, <select />, and < textarea />. HTML elements are coded to be accessible and should be used rather than rolling your own.

<div role="button" onClick={handleClick >Click Me < /button > does not in fact equal <button onClick={handleClick}>Hello</button>

Without a tabIndex=0, the div cannot retain focus. None of the basic accessibility and functionality of a native button is present in a div that calls itself a button, which makes it even more frustrating for a user. A div with a role of button that only uses the onClick event will not respond when a user presses the Space or Enter keys. Each event type must be handled when creating your own custom component from divs.

It is far better to use native HTML elements rather than cobbling together your own.

Understandable and Robust

POUR's last two principles, Understandable and Robust, must be understood within the modalities of perceivability and operability. For instance, when allowing a user to switch to a different language, the lang attribute in the < html/> tag must be updated. A screen reader must know which language to use to speak with the language's natural inflections and pronunciation, rather than sounding like someone just learning the language.

Similarly, if an error is identified and described to a user, it must be created in a way that is perceivable on the screen and through the screen reader.

Consider tying accessibility to peripherals rather than to user disabilities. A ticket clearly defining acceptance criteria based on a peripheral is much clearer to a front-end developer than having them memorize which disabilities require which interactions.

As professionals, it's our responsibility to ensure a website is fully perceivable on screen and with screen readers, and operable with pointing devices and keyboards. It shouldn't matter which devices a user chooses, or why they choose them, whether it's convenience or a disability. Our sites should just work.

This article sets the stage for what comes next. Applying responsibility and the modalities of accessibility when building an accessible component.

Join me as I start working on a universally accessible main navigation component for my site. I'll be building out a GitHub repository and discussing what it takes to build this component over a series I call "Guide to creating an accessible navigation component".

Are you ready? Buckle up.

Who is actually responsible for Web Accessibility?

ShaynaProductions — Tue, 28 Apr 2026 12:15:00 +0000

Who is responsible for making sure software is accessible? If your short answer is the front-end development team, I'm sorry to say that your software will never be universally accessible, because many accessibility decisions are made long before a developer begins working on a component. Architecture, design, and, yes, requirements all play a part in ensuring that whatever software is developed is perceivable and operable by people with differing characteristics.

In all the agile teams I've been a part of, the process of creating a feature or component typically involves the project owner assessing needs, which (if deemed necessary) are then handed off to the software architect, and then to the data and design team/member(s), which (with or without front-end developer input) provide a visual design. Tickets are dispatched to different teams, and development commences.

As a front-end developer, I am usually assigned stories with a design document or a Figma link, along with acceptance criteria. Rarely does any of this include accessibility information, and I haven't yet encountered someone well-versed in accessibility being included in the decisions made before tickets are written or handed off.

Even if accessibility is considered before tickets are written, suggestions about it are usually met with swift and sometimes fierce pushback because the changes necessary to implement them affect a delivery date that was committed to without considering what it takes to create an accessible feature. When tickets mention accessibility in the acceptance criteria, it's typically a generic bullet point: "must meet WCAG 2.x."

Front-end requirements tend to focus primarily on the physical sense of sight, with little input on how to make something perceivable to someone who lacks that sense. It's easier to demonstrate screen and mouse interactions during sprint demos and other agile ceremonies, since keyboard navigation doesn't translate well in either virtual or physical meetings, and screen reader demonstrations tend to be ineffective and leave stakeholders without a clear understanding of what has been achieved.

True accessibility cannot be achieved if the first reference to it appears in a front-end development ticket.

Trying to implement accessibility into a component when neither the design nor the back-end architecture has considered it will result in one of two outcomes: giving up after multiple test failures, or kludging the code to address impossible-to-fix issues aimed at passing an accessibility audit rather than helping actual users. A common example would be a requirement to describe user-uploaded images with an alt attribute when no database field is available to store the information. At best, a front-end developer can add generic alt text to pass an automated audit, but the actual requirement to describe an image so that someone who cannot see it has the same understanding as someone who can is never addressed.

Requiring a developer to navigate between an inaccessible Figma design and the requirements to pass an accessibility audit places an undue burden on the party least able to rectify the situation.

Implementing accessibility requires the knowledge and cooperation of everyone involved in the creation. From the project owners who define the business features to the back-end engineers who handle the data, as well as the designers, software architects, tech leads, content creators, developers, and testers. And while not everyone needs to be an expert in overall accessibility, they do need to know their responsibilities and gain expertise in those areas.

Real accessibility requires those who assess the needs and gather the requirements to include requirements mapped to the appropriate WCAG success criteria when determining how a particular feature should be perceived and operated.

Real accessibility requires the work of back-end engineers to ensure that dynamic images, charts, and graphs derived from database data also store and send the information necessary to describe those items.

Real accessibility requires reasonable time limits and budgets to account for accessibility requirements when determining roadmaps.

Real accessibility requires content owners to ensure that, if textual, the content they provide conforms to proper HTML semantic structure. If the content medium is audio/visual, it is accompanied by proper captioning, descriptions, transcriptions, and other related requirements for audio, images, and video.

Real accessibility requires those writing tickets to write user stories and acceptance criteria in a way that both developers and testers can follow.

Real accessibility requires those involved in design to truly understand the perceivable guidelines in the Web Content Accessibility Guidelines (WCAG) and apply them in their designs.

Real accessibility requires someone to be responsible for determining the phrasing of labels and text, including errors, descriptions, and headings that may or may not be visible on the screen.

Real accessibility requires developers who understand the importance of accessibility and their role in ensuring components are semantically structured. They should be able to implement WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) properties and states correctly, and be responsible for supporting proper keyboard handling within complex components.

Real accessibility requires testers who know how to test across different accessibility scenarios, who can use a screen reader and the accessibility tree to ensure a user who lacks the physical sense of sight has an equitable experience as one who can see a screen.

Real accessibility takes a company and community-wide effort. Whether it's a team-wide push or one person wearing all the hats, accessibility needs to be at the forefront of everyone's mind from the beginning of development to the very end.

Right now, I'm like many of you, trying to survive the fallout happening in IT. I'm currently partnering with a friend on a website that hosts a constantly expanding universe of short stories. My friend is the content owner and has implemented their requirements, and I'm responsible for everything else. As the sole requirements gatherer/software architect/developer/designer/tester, it's my responsibility to ensure accessibility is considered at every step of the process.

Hat Order

Hat order is important. A tester's hat does me no good if there's nothing to test yet, and I can't develop a component until I know what I'm supposed to be building. So, really, the first hat I have to put on after deciding what I'm going to build is that of a product owner.

Business Analyst/Requirements Gatherer 🖊

Whether it's a standalone component or a feature, accessibility needs to be quantified. Requirements should be linked to Acceptance Criteria, and, ideally, those related to accessibility should also be linked to WCAG success criteria and best practices.
Depending on company culture, requirements may be gathered in one place before any work begins, or gathered incrementally; however, all acceptance criteria for a particular user story should be in place a few sprints before design or development work begins.

Software Architect 👷🏼

A software architect is responsible for ensuring consistency throughout the website and for considering the architecture of a component and its relationship within the entire project. A software architect would be the first to review any requirements/acceptance criteria and add any necessary information. They would participate in design reviews to ensure the design itself is accessible and review pull requests for adherence to accessibility norms.

Content Creators/Producers 🎙️

Content creators are responsible for ensuring that all audio, video, and textual content available through the website or application is accessible to everyone through proper semantic structure, captioning, audio description, and transcription. Proper labeling of interactive content is necessary to enable operability via voice.

Designers 🎨

Designers are responsible for what is shown on the screen. There is no amount of development in the world that can overcome an inaccessible design. The design team is responsible for the color contrast ratio between the foreground and background, and for state changes that occur when focus or hover actions interact with an interactive object.

Depending on the team structure, they may or may not be responsible for the visual text labels and icon descriptions shown. If they are, they should also be responsible for labeling any text aimed toward screen readers.
The design can be created in a prototyping environment such as Figma and sent back to the developer for application. If it is feasible and the CSS can be decoupled from the scripting code, designers could apply the CSS themselves.

Backend Engineers ⌨️

Backend engineers are responsible for guaranteeing that the information necessary to describe an object whose data or location is stored in a database also includes fields to hold the descriptions. When raw data is used to generate a chart or other visually oriented component, textual descriptions based on the data are also generated and sent to the front end.

Frontend Developers 👩🏻‍💻

A frontend developer implements the actual component or feature, using their knowledge of Semantic HTML structure and WAI-ARIA to create a semantically structured component that is operable across keyboard and touch peripherals.

Developers are responsible for adhering to the acceptance criteria and ensuring the required WCAG guidelines are implemented. Developers should understand how browsers implement the accessibility tree and, ideally, test their code with screen readers and accessibility testing tools such as Accessibility Insights for Web.

Testers 👩🏻‍💻

Whether programmatic or human, a tester is responsible for making sure the tested item complies with the stated acceptance criteria. Screen readers and other accessibility testing tools, such as ZoomText or Accessibility Insights, may be used to test overall accessibility and specific acceptance criteria.

When everyone is responsible for accessibility, the burden is shared. Not everyone needs to be an expert in everything that makes up accessibility, but each role needs to be an expert in their particular area.

Accessibility as a Layered Process

While it's important to keep accessibility in mind from requirements gathering through testing, for the actual implementation, I've found it helps to build everything in layers over a series of sprints.

Conversations over architecture, accessibility and design need to happen early in the process. Once a base structure is agreed upon, a front-end developer can create a clickable, semantically structured prototype that includes the basic requirements for screen reader perceivability and deliver it, along with minimal CSS, to the design team, who will work on screen perceivability. This prototype should be clear enough visually to help the developer implement the remaining features.

When visual considerations take precedence, developers are more concerned with delivering something that matches the design than with how it operates. Minimal styling, even if it's ugly, helps developers focus on how the component operates, knowing the true design can be applied later in the process.

Depending on the complexity of the component or feature, multiple tickets may be created, each with acceptance criteria mapped to the requirements, creating a contract between what a developer creates and what testing accomplishes. Toward the end of the process, the design can be implemented and tested against the WCAG perceivability and operable navigability guidelines.

I'm going to demonstrate this process in a series of articles in which I implement a main navigation component that can be used for both desktop and mobile presentations.

Are you ready to follow me on this journey? Buckle Up.