Accessibility

Neighborhood aims to meet WCAG 2.2 level AA (opens in new tab) . Components handle much of the work, such as focus styles, keyboard support and color contrast, but an accessible site also depends on how each page is written and put together.

What components handle

• Visible focus. Every interactive part shows a focus outline when reached by keyboard. Its color changes with the surface, so it stays visible on inverse sections, and it stays visible in Windows High Contrast.
• Color contrast. Every brand theme’s text, link, control and focus colors meet WCAG AA on each surface. A check in the token build fails if a change would break that.
• Keyboard support:
  • Dialog: focus moves into it, Tab stays inside it, Escape closes it, and focus returns to what opened it. The rest of the page can’t be reached while it’s open.
  • Select: arrow keys, Home and End move through options, typing jumps to a match, Enter or Space selects, and Escape or Tab closes the list.
  • Radio Group: one Tab stop for the group; arrow keys move between options and select them.
  • Search with Autosuggest: the down arrow moves from the search field into the suggestions, and Escape returns to the field.
  • Carousel: arrow keys move between slides while the carousel has focus, and the previous, next and pagination controls are buttons. Without loop, the previous and next buttons are disabled at the first and last slide.
  • Accordion: each header is a button inside a heading, so Enter and Space open and close it, and screen reader users can jump between sections by heading.
  • Filters (mobile): the drawer works as a dialog. Escape closes it, Tab stays inside it, and focus returns to the toggle when it closes.
  • Pagination: the current page stays focusable, and Previous and Next stay in place, disabled, at the ends.
• Form fields. Labels, help text and error text are connected to each field. Errors are announced when they appear, required fields show a marker, and an invalid field with no error text gets a default message. Fields also work inside a native <form>; see Use components in forms.
• Landmarks and structure. Navbar, Pagination and Breadcrumb render navigation landmarks (Pagination and Breadcrumb are labeled), Search renders a search landmark, and lists are announced as lists.
• Announcements. Screen readers hear result counts when filters, search suggestions or search results update, upload changes, and loading spinners.
• Links that open a new tab with external tell screen reader users so.
• Autoplaying video is muted and can always be paused. Captions and descriptions can be added with <track> elements inside nbhd-video.
• Autoplaying carousels show a play/pause button next to the pagination. Rotation pauses while the pointer is over the slides, and stops when keyboard focus enters the carousel. It starts paused for visitors who have reduced motion turned on.
• Target size. Small controls, such as carousel dots and the search clear button, have a click area of at least 24 by 24 pixels.

What each site owns

• Alt text. Images are treated as decorative unless you set alt. Give every image that carries meaning an alt that says what it shows or does, and set alt="" for images that are purely decorative. During development, the console warns about an image with no alt at all.
• Heading order. Text’s tag sets the heading level and variant sets the look, so you can choose them separately. Components with built-in headings (Accordion, Autosuggest, Filters, Pagination Search) have a heading-level setting. Use one h1 per page, and don’t skip levels. Content and media explains how.
• Link and button text. Write labels that make sense on their own: “Shop faucets”, not “Click here”. If several CTAs share the same text, give each an aria-label that starts with the visible text, such as “Learn more about showers”.
• Icon-only buttons. Give every icon-only button an aria-label. During development, the console warns when one is missing.
• Form labels. Give every field a label. When a design has no visible label, set aria-label instead. Group related radios in a Radio Group with its own label.
• Error messages. Set error-text to say what’s wrong and how to fix it, such as “Enter an email address like name@example.com”. The default message only says that the field has an error.
• Video captions. For video with speech, add a captions <track>, use a YouTube or Vimeo video with captions, or provide a transcript next to it.
• Text over images. Heroes and featured cards darken the image behind their text, but a very light image can still be hard to read. Check the text against the image you choose.
• More than one navigation. If a page has several navbars or navigation areas, give each an aria-label, such as “Main” or “Footer”. Leave out the word “navigation”; screen readers already say it.
• Small screens. Use the navbar’s mobile-hidden only when the page offers the same links another way on small screens. With a sticky navbar, set scroll-padding-top on the page to the navbar’s height so it doesn’t cover focused elements.
• Your own colors. If you use colors outside the surfaces, check their contrast: 4.5:1 for body text, and 3:1 for large text and interface elements. Surfaces and color has details.

Test as you go

• Storybook’s Accessibility panel runs automated checks on every story. Check the components you use, on your brand.
• Use the keyboard only. Tab through the page: every link, button and field should be reachable, show a visible focus outline and work with Enter or Space.
• Zoom to 200%. Text should stay readable, without content overlapping or getting cut off.
• Try a screen reader on key pages, such as VoiceOver on macOS or NVDA on Windows.

Automated checks find only some issues, so the keyboard and screen reader checks matter. If you find an accessibility issue in a component, report it.