Aug 14, 2025 · Aug 12, 2025 · Aug 13, 2025 · Aug 13, 2025 · Aug 13, 2025 · Aug 14, 2025
diff --git a/site/src/components/Abbr/Abbr.stories.tsx b/site/src/components/Abbr/Abbr.stories.tsx
 component: Abbr,
 decorators: [
 (Story) => (
 <>
 <div className="max-w-prose text-base">
 <p>Try the following text out in a screen reader!</p>
 <Story />
 </>
 </div>
 ),
 ],
 };
 },
 decorators: [
 (Story) => (
 <p className="max-w-2xl">
 <p>
 The physical pain of getting bonked on the head with a cartoon mallet
 lasts precisely 593{" "}
 lasts precisely 593
 <span className="underline decoration-dotted">
 <Story />
 </span>
diff --git a/site/src/components/Abbr/Abbr.test.tsx b/site/src/components/Abbr/Abbr.test.tsx
 import { render, screen } from "@testing-library/react";
 import { Abbr, type Pronunciation } from "./Abbr";
 import { Abbr } from "./Abbr";

 type AbbreviationData = {
 abbreviation: string;
 title: string;
 expectedLabel: string;
 };

 type AssertionInput = AbbreviationData & {
 pronunciation: Pronunciation;
 };

 function assertAccessibleLabel({
 abbreviation,
 title,
 expectedLabel,
 pronunciation,
 }: AssertionInput) {
 const { unmount } = render(
 <Abbr title={title} pronunciation={pronunciation}>
 {abbreviation}
 </Abbr>,
 );

 screen.getByLabelText(expectedLabel, { selector: "abbr" });
 unmount();
 }

 describe(Abbr.name, () => {
 it("Has an aria-label that equals the titleifthe abbreviation is shorthand", () => {
 it("Omits abbreviation from screen-reader outputifit is shorthand", () => {
 const sampleShorthands: AbbreviationData[] = [
 {
 abbreviation: "ms",
 ];

 for (const shorthand of sampleShorthands) {
 assertAccessibleLabel({ ...shorthand, pronunciation: "shorthand" });
 const { unmount } = render(
 <Abbr title={shorthand.title} pronunciation="shorthand">
 {shorthand.abbreviation}
 </Abbr>,
 );

 // The <abbr> element doesn't have any ARIA role semantics baked in,
 // so we have to get a little bit more creative with making sure the
 // expected content is on screen in an accessible way
 const element = screen.getByTitle(shorthand.title);
 expect(element).toHaveTextContent(shorthand.expectedLabel);
 unmount();
 }
 });

 it("Has an aria label with title and 'flattened' pronunciation if abbreviation is acronym", () => {
 it("Adds title and 'flattened' pronunciation if abbreviation is acronym", () => {
 const sampleAcronyms: AbbreviationData[] = [
 {
 abbreviation: "NASA",
 ];

 for (const acronym of sampleAcronyms) {
 assertAccessibleLabel({ ...acronym, pronunciation: "acronym" });
 const { unmount } = render(
 <Abbr title={acronym.title} pronunciation="acronym">
 {acronym.abbreviation}
 </Abbr>,
 );

 const element = screen.getByTitle(acronym.title);
 expect(element).toHaveTextContent(acronym.expectedLabel);
 unmount();
 }
 });

 it("Has an aria label with title and initialized pronunciation if abbreviation is initialism", () => {
 it("Adds title and initialized pronunciation if abbreviation is initialism", () => {
 const sampleInitialisms: AbbreviationData[] = [
 {
 abbreviation: "FBI",
 ];

 for (const initialism of sampleInitialisms) {
 assertAccessibleLabel({ ...initialism, pronunciation: "initialism" });
 const { unmount } = render(
 <Abbr title={initialism.title} pronunciation="initialism">
 {initialism.abbreviation}
 </Abbr>,
 );

 const element = screen.getByTitle(initialism.title);
 expect(element).toHaveTextContent(initialism.expectedLabel);
 unmount();
 }
 });
 });
diff --git a/site/src/components/Abbr/Abbr.tsx b/site/src/components/Abbr/Abbr.tsx
 import type { FC, HTMLAttributes } from "react";
 import { cn } from "utils/cn";

 exporttype Pronunciation = "shorthand" | "acronym" | "initialism";
 type Pronunciation = "shorthand" | "acronym" | "initialism";

 type AbbrProps = HTMLAttributes<HTMLElement> & {
 children: string;
 title: string;
 pronunciation?: Pronunciation;
 className?: string;
 };

 /**
 children,
 title,
 pronunciation = "shorthand",
 className,
 ...delegatedProps
 }) => {
 return (
 <abbr
 // Title attributes usually aren't natively available to screen readers;
 // always have to supplement with aria-label
 // Adding title to make things a little easier for sighted users,
 // but titles aren't always exposed via screen readers. Still have
 // to inject the actual text content inside the abbr itself
 title={title}
 aria-label={getAccessibleLabel(children, title, pronunciation)}
 className={cn(
 "decoration-inherit",
 children === children.toUpperCase()
 ? "tracking-wide"
 : "tracking-normal",
 "no-underline tracking-normal",
 children === children.toUpperCase() && "tracking-wide",
 className,
 )}
 {...delegatedProps}
 >
 <span aria-hidden>{children}</span>
 <span className="sr-only">
 {getAccessibleLabel(children, title, pronunciation)}
 </span>
 </abbr>
 );
 };
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,10 +6,10 @@ const meta: Meta<typeof Abbr> = {
		component: Abbr,
		decorators: [
		(Story) => (
		<>
		<div className="max-w-prose text-base">
		<p>Try the following text out in a screen reader!</p>
		<Story />
		</>
		</div>
		),
		],
		};
Expand All		@@ -25,9 +25,9 @@ export const InlinedShorthand: Story = {
		},
		decorators: [
		(Story) => (
		<p className="max-w-2xl">
		<p>
		The physical pain of getting bonked on the head with a cartoon mallet
		lasts precisely 593{" "}
		lasts precisely 593
		<span className="underline decoration-dotted">
		<Story />
		</span>
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,34 +1,14 @@
		import { render, screen } from "@testing-library/react";
		import { Abbr, type Pronunciation } from "./Abbr";
		import { Abbr } from "./Abbr";

		type AbbreviationData = {
		abbreviation: string;
		title: string;
		expectedLabel: string;
		};

		type AssertionInput = AbbreviationData & {
		pronunciation: Pronunciation;
		};

		function assertAccessibleLabel({
Copy link MemberAuthor ParkreinerAug 13, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Got rid of the test helper because it felt like we were binding all our tests to a shallow abstraction
		abbreviation,
		title,
		expectedLabel,
		pronunciation,
		}: AssertionInput) {
		const { unmount } = render(
		<Abbr title={title} pronunciation={pronunciation}>
		{abbreviation}
		</Abbr>,
		);

		screen.getByLabelText(expectedLabel, { selector: "abbr" });
		unmount();
		}

		describe(Abbr.name, () => {
		it("Has an aria-label that equals the titleifthe abbreviation is shorthand", () => {
		it("Omits abbreviation from screen-reader outputifit is shorthand", () => {
		const sampleShorthands: AbbreviationData[] = [
		{
		abbreviation: "ms",
Expand All		@@ -43,11 +23,22 @@ describe(Abbr.name, () => {
		];

		for (const shorthand of sampleShorthands) {
		assertAccessibleLabel({ ...shorthand, pronunciation: "shorthand" });
		const { unmount } = render(
		<Abbr title={shorthand.title} pronunciation="shorthand">
		{shorthand.abbreviation}
		</Abbr>,
		);

		// The <abbr> element doesn't have any ARIA role semantics baked in,
		// so we have to get a little bit more creative with making sure the
		// expected content is on screen in an accessible way
		const element = screen.getByTitle(shorthand.title);
		expect(element).toHaveTextContent(shorthand.expectedLabel);
		unmount();
		}
		});

		it("Has an aria label with title and 'flattened' pronunciation if abbreviation is acronym", () => {
		it("Adds title and 'flattened' pronunciation if abbreviation is acronym", () => {
		const sampleAcronyms: AbbreviationData[] = [
		{
		abbreviation: "NASA",
Expand All		@@ -67,11 +58,19 @@ describe(Abbr.name, () => {
		];

		for (const acronym of sampleAcronyms) {
		assertAccessibleLabel({ ...acronym, pronunciation: "acronym" });
		const { unmount } = render(
		<Abbr title={acronym.title} pronunciation="acronym">
		{acronym.abbreviation}
		</Abbr>,
		);

		const element = screen.getByTitle(acronym.title);
		expect(element).toHaveTextContent(acronym.expectedLabel);
		unmount();
		}
		});

		it("Has an aria label with title and initialized pronunciation if abbreviation is initialism", () => {
		it("Adds title and initialized pronunciation if abbreviation is initialism", () => {
		const sampleInitialisms: AbbreviationData[] = [
		{
		abbreviation: "FBI",
Expand All		@@ -91,7 +90,15 @@ describe(Abbr.name, () => {
		];

		for (const initialism of sampleInitialisms) {
		assertAccessibleLabel({ ...initialism, pronunciation: "initialism" });
		const { unmount } = render(
		<Abbr title={initialism.title} pronunciation="initialism">
		{initialism.abbreviation}
		</Abbr>,
		);

		const element = screen.getByTitle(initialism.title);
		expect(element).toHaveTextContent(initialism.expectedLabel);
		unmount();
		}
		});
		});
Original file line number	Diff line number	Diff line change
		@@ -1,12 +1,13 @@
		import type { FC, HTMLAttributes } from "react";
		import { cn } from "utils/cn";

		exporttype Pronunciation = "shorthand" \| "acronym" \| "initialism";
		type Pronunciation = "shorthand" \| "acronym" \| "initialism";

		type AbbrProps = HTMLAttributes<HTMLElement> & {
		children: string;
		title: string;
		pronunciation?: Pronunciation;
		className?: string;
		};

		/**
Expand All		@@ -22,23 +23,26 @@ export const Abbr: FC<AbbrProps> = ({
		children,
		title,
		pronunciation = "shorthand",
		className,
		...delegatedProps
		}) => {
		return (
		<abbr
		// Title attributes usually aren't natively available to screen readers;
		// always have to supplement with aria-label
		// Adding title to make things a little easier for sighted users,
		// but titles aren't always exposed via screen readers. Still have
		// to inject the actual text content inside the abbr itself
		title={title}
		aria-label={getAccessibleLabel(children, title, pronunciation)}
		className={cn(
		"decoration-inherit",
		children === children.toUpperCase()
		? "tracking-wide"
		: "tracking-normal",
		"no-underline tracking-normal",
Copy link Member aslilacAug 13, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I wish we understood where the underline is coming from. these kinds of conflicts are so annoying. can we at least add a TODO to clean this up one day? Copy link MemberAuthor ParkreinerAug 14, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. So, the funny thing is,`abbr` elements have an underline by default in normal HTML – it's MUI that somehow overrode it I actually don't think we should do anything – once MUI is out, we should be much closer to "normal" CSS, and this behavior would be 100% expected
		children === children.toUpperCase() && "tracking-wide",
		className,
		)}
		{...delegatedProps}
		>
		<span aria-hidden>{children}</span>
		<span className="sr-only">
		{getAccessibleLabel(children, title, pronunciation)}
		</span>
		</abbr>
		);
		};
Expand Down