Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(topnav): give the logo link an accessible name (#3565)

Cindy Zhang7b1512d42aeb
diff --git a/.changeset/topnav-heading-logo-link-name.md b/.changeset/topnav-heading-logo-link-name.md
new file mode 100644
index 0000000000..16cec07df4
--- /dev/null
+++ b/.changeset/topnav-heading-logo-link-name.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TopNavHeading: give the logo an accessible name when it links to a destination. The logo image is decorative, so a logo wrapped in `headingHref` produced an unnamed link (axe: link-name). It is now labelled from `heading` (or a new optional `logoLabel` prop for logo-only headings). (#3343)
+
+@cixzhang
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index 993808adf6..e513c684a8 100644
--- a/packages/core/src/TopNav/TopNav.test.tsx
+++ b/packages/core/src/TopNav/TopNav.test.tsx
@@ -200,6 +200,56 @@ describe('TopNavHeading', () => {
expect(screen.getByTestId('logo')).toBeInTheDocument();
});
+ describe('logo link accessible name', () => {
+ const logo = <img src="/logo.png" alt="" />;
+
+ // A logo image is decorative; when the logo is wrapped in a link the link
+ // itself needs an accessible name, otherwise axe reports link-name.
+ it('names the logo link in the independent-links config', () => {
+ render(
+ <TopNavHeading
+ logo={logo}
+ superheading="Suite"
+ superheadingHref="/suite"
+ heading="Product"
+ headingHref="/product"
+ />,
+ );
+ // No link should have an empty accessible name.
+ for (const link of screen.getAllByRole('link')) {
+ expect(link).toHaveAccessibleName();
+ }
+ // The logo link is named from the heading.
+ expect(
+ screen.getAllByRole('link', {name: 'Product'}).length,
+ ).toBeGreaterThanOrEqual(1);
+ });
+
+ it('names the logo link in the menu + hrefs config', () => {
+ render(
+ <TopNavHeading
+ logo={logo}
+ superheading="Suite"
+ superheadingHref="/suite"
+ heading="Product"
+ headingHref="/product"
+ menu={<a href="#menu">Menu item</a>}
+ />,
+ );
+ for (const link of screen.getAllByRole('link')) {
+ expect(link).toHaveAccessibleName();
+ }
+ });
+
+ it('names a logo-only link via logoLabel', () => {
+ render(<TopNavHeading logo={logo} headingHref="/home" logoLabel="Home" />);
+ expect(screen.getByRole('link', {name: 'Home'})).toHaveAttribute(
+ 'href',
+ '/home',
+ );
+ });
+ });
+
it('renders as anchor when href is provided', () => {
render(<TopNavHeading heading="Home" href="/" />);
const link = screen.getByRole('link');
diff --git a/packages/core/src/TopNav/TopNavHeading.tsx b/packages/core/src/TopNav/TopNavHeading.tsx
index 290def340d..de8e9a19a0 100644
--- a/packages/core/src/TopNav/TopNavHeading.tsx
+++ b/packages/core/src/TopNav/TopNavHeading.tsx
@@ -214,6 +214,12 @@ export interface TopNavHeadingProps extends BaseProps<HTMLElement> {
* Can be an image, NavIcon, or any ReactNode.
*/
logo?: ReactNode;
+ /**
+ * Accessible name for the logo when it links somewhere (`headingHref`) and
+ * has no adjacent text to name it (for example a logo-only heading). Defaults
+ * to `heading` when available. Ignored when the logo is not a link.
+ */
+ logoLabel?: string;
/**
* Product/app name.
*/
@@ -295,6 +301,7 @@ export interface TopNavHeadingProps extends BaseProps<HTMLElement> {
export function TopNavHeading({
as,
logo,
+ logoLabel,
heading,
headingHref: headingHrefProp,
href,
@@ -314,6 +321,10 @@ export function TopNavHeading({
const LinkComponent = useLinkComponent(as);
// Support both headingHref and legacy href
const headingHref = headingHrefProp ?? href;
+ // When the logo is wrapped in a link it needs its own accessible name (the
+ // logo image itself is decorative). Prefer an explicit logoLabel, fall back
+ // to the heading text. axe: link-name.
+ const logoLinkLabel = logoLabel ?? heading;
const rootRef = useRef<HTMLElement>(null);
@@ -425,6 +436,7 @@ export function TopNavHeading({
<Element
ref={ref as React.Ref<HTMLAnchorElement & HTMLDivElement>}
href={headingHref}
+ aria-label={headingHref ? logoLabel : undefined}
data-testid={testId}
{...mergeProps(
themeProps('top-nav-heading'),
@@ -533,6 +545,7 @@ export function TopNavHeading({
(headingHref ? (
<LinkComponent
href={headingHref}
+ aria-label={logoLinkLabel}
onClick={(e: React.MouseEvent) => e.stopPropagation()}
{...stylex.props(styles.logo)}>
{logo}
@@ -593,7 +606,10 @@ export function TopNavHeading({
{...props}>
{logo &&
(headingHref ? (
- <LinkComponent href={headingHref} {...stylex.props(styles.logo)}>
+ <LinkComponent
+ href={headingHref}
+ aria-label={logoLinkLabel}
+ {...stylex.props(styles.logo)}>
{logo}
</LinkComponent>
) : (