Gatsby a11y helpers #26376

madalynrose · 2020-08-11T19:30:36Z

Description

This PR creates a solution for #21059.

There is currently a working bare-bones prototype that gives developers control around client-side routing behavior that Gatsby can hook into.

As it stands we have two components. They are based heavily on @reach/skip-nav and their current implementation is fairly simplistic.

RouteAnnouncement

Gatsby looks for this element when it navigates to a new page in cache-dir/navigation.js and outputs its contents to Gatsby's Route Announcer.

This component can be used multiple times in a site (e.g. implemented to always use page title in a general Layout.js file and then overridden in specific pages or posts for custom announcements) and Gatsby will use the most specific instance. If the announcement should be different from the title of the page, Gatsby makes it easy to change without visually displaying that custom text with the visuallyHidden flag.

Source

/**
 * Announce
 *
 * Renders a wrapping div around content to announce on client side route change
 *
 */
export const RouteAnnouncement: React.FC<RouteAnnouncementProps> = ({
  children,
  visuallyHidden = false,
  useTitle = false,
  ...props
}) => {
  const hiddenStyle: React.CSSProperties = {
    position: `absolute`,
    top: `0`,
    width: `1`,
    height: `1`,
    padding: `0`,
    overflow: `hidden`,
    clip: `rect(0, 0, 0, 0)`,
    whiteSpace: `nowrap`,
    border: `0`,
  }

  const initialStyle: React.CSSProperties = {}

  return (
    <div
      {...props}
      data-gatsby-route-announcement={true}
      data-gatsby-route-announcement-use-title={useTitle}
      style={visuallyHidden ? hiddenStyle : initialStyle}
    >
      {children}
    </div>
  )
}

Examples

const layout = ({ children }) => {
  return (
    <div>
      <Header/>
      <RouteAnnouncement useTitle={true}/>
      <main>{children}</main>
      <Footer/>
    </div>
  )
}

const blogPost = ({ data }) => {
  { title, html } = data.post
  return (
    <Layout>
      <RouteAnnouncement><h1>{title}</h1></RouteAnnouncement>
      <PostContent content={html} />
    </Layout>
  )
}

//if we want to announce something just for screen reader users because the title or h1 on the page isn't very descriptive we can!
const specialPage = ({ data }) => {
  { title, html } = data.post
  return (
    <Layout>
      <RouteAnnouncement visuallyHidden={true}>welcome to the special page!</RouteAnnouncement>
      <h1>Hello!</h1>
      <GenericContent />
    </Layout>
  )
}

RouteFocus

Source

/**
 * RouteFocus
 *
 * Renders a div that should wrap a small, interactive element (ideally a skip link) 
 * placed at the top of the page that Gatsby will detect and send focus to on 
 * client side route changes
 */
export const RouteFocus: React.FC<RouteFocusProps> = ({
  children,
  ...props
}) => {
  return (
    <div
      {...props}
      data-gatsby-csr-focus={true}
    >
      {children}
    </div>
  );
};

Example

const Layout = ({children}) => (
  <>
    <RouteFocus><SkipNavLink /></RouteFocus>
    <Header /> //main navigation lives here
    <SkipNavContent/>
     <main>{children}</main>
    <Footer />
  </>
)

TODO

Validation!

Let's set developers up for accessibility success by highlighting common mistakes. We'll likely do this validation inside of a util plugin shipped with Gatsby rather than in the components themselves so we can leverage a11y testing libraries to make our assertions without bloating the component package.

input to <RouteAnnouncement> must meet guidelines for page Titles to emulate the behavior of static browser route changes (e.g. check length of text to ensure it doesn't overwhelm)
<RouteFocus> must wrap an interactive element, ideally a skip link, per @marcysutton's research

Robustness

use refs and hooks/Providers to surface the most specific instance of <RouteAnnouncement>

Related Issues

Fixes #21059 & #20801
Related to #19290

laurieontech

Left some comments on the README. Overall looks great!

laurieontech · 2020-09-11T15:15:16Z