From 1dfcbae5491bf0efdbfd7a71ce9367cafdea81f2 Mon Sep 17 00:00:00 2001
From: Taesu <166604494+bytaesu@users.noreply.github.com>
Date: Sun, 11 Jan 2026 16:37:55 +0900
Subject: [PATCH] docs: improve accessibility (#7253)

---
 docs/components/builder/index.tsx        |  7 ++++++-
 docs/components/features.tsx             | 16 +++++++++++-----
 docs/components/github-stat.tsx          |  9 ++++++++-
 docs/components/landing/hero.tsx         | 14 ++++++++++++--
 docs/components/landing/testimonials.tsx |  9 +++++++--
 docs/components/logo.tsx                 |  2 ++
 docs/components/nav-bar.tsx              |  2 ++
 docs/components/nav-link.tsx             | 11 ++++++++++-
 docs/components/theme-toggle.tsx         |  2 ++
 9 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/docs/components/builder/index.tsx b/docs/components/builder/index.tsx
index 1556d91d69..e0fbcb89cb 100644
--- a/docs/components/builder/index.tsx
+++ b/docs/components/builder/index.tsx
@@ -39,6 +39,7 @@ const frameworks = [
 				width="2em"
 				height="2em"
 				viewBox="0 0 15 15"
+				aria-hidden="true"
 			>
 				<path
 					fill="currentColor"
@@ -58,6 +59,7 @@ const frameworks = [
 				width="2em"
 				height="2em"
 				viewBox="0 0 256 256"
+				aria-hidden="true"
 			>
 				<g fill="none">
 					<rect width="256" height="256" fill="#242938" rx="60"></rect>
@@ -78,6 +80,7 @@ const frameworks = [
 				width="2em"
 				height="2em"
 				viewBox="0 0 256 256"
+				aria-hidden="true"
 			>
 				<g fill="none">
 					<rect width="256" height="256" fill="#FF3E00" rx="60"></rect>
@@ -111,7 +114,7 @@ const frameworks = [
 				viewBox="0 0 500 500"
 				fill="none"
 				xmlns="http://www.w3.org/2000/svg"
-				role="presentation"
+				aria-hidden="true"
 			>
 				<path
 					d="M233.205 430.856L304.742 425.279C304.742 425.279 329.208 421.295 343.569 397.659L293.041 385.443L233.205 430.856Z"
@@ -439,6 +442,7 @@ export function Builder() {
 														width="1em"
 														height="1em"
 														viewBox="0 0 24 24"
+														aria-hidden="true"
 													>
 														<path
 															fill="currentColor"
@@ -471,6 +475,7 @@ export function Builder() {
 														width="1em"
 														height="1em"
 														viewBox="0 0 24 24"
+														aria-hidden="true"
 													>
 														<g fill="none">
 															<path d="m12.593 23.258l-.011.002l-.071.035l-.02.004l-.014-.004l-.071-.035q-.016-.005-.024.005l-.004.01l-.017.428l.005.02l.01.013l.104.074l.015.004l.012-.004l.104-.074l.012-.016l.004-.017l-.017-.427q-.004-.016-.017-.018m.265-.113l-.013.002l-.185.093l-.01.01l-.003.011l.018.43l.005.012l.008.007l.201.093q.019.005.029-.008l.004-.014l-.034-.614q-.005-.018-.02-.022m-.715.002a.02.02 0 0 0-.027.006l-.006.014l-.034.614q.001.018.017.024l.015-.002l.201-.093l.01-.008l.004-.011l.017-.43l-.003-.012l-.01-.01z"></path>
diff --git a/docs/components/features.tsx b/docs/components/features.tsx
index 54537c8ff5..29fbf440d7 100644
--- a/docs/components/features.tsx
+++ b/docs/components/features.tsx
@@ -95,7 +95,7 @@ export default function Features({ stars }: { stars: string | null }) {
 							<div className="mt-2">
 								<div className="max-w-full">
 									<div className="flex gap-3 ">
-										<p
+										<h3
 											className="max-w-lg text-xl font-normal tracking-tighter md:text-2xl"
 											dangerouslySetInnerHTML={{
 												__html: feature.title,
@@ -105,7 +105,13 @@ export default function Features({ stars }: { stars: string | null }) {
 								</div>
 								<p className="mt-2 text-sm text-left text-muted-foreground">
 									{feature.description}
-									<a className="ml-2 underline" href="/docs" target="_blank">
+									<a
+										className="ml-2 underline"
+										href="/docs"
+										target="_blank"
+										rel="noopener noreferrer"
+										aria-label={`Learn more about ${feature.label}`}
+									>
 										Learn more
 									</a>
 								</p>
@@ -125,9 +131,9 @@ export default function Features({ stars }: { stars: string | null }) {
 									Own your auth
 								</p>
 							</div>
-							<p className="max-w-md mx-auto mt-4 text-4xl font-normal tracking-tighter text-center md:text-4xl">
-								<strong>Roll your own auth with confidence in minutes!</strong>
-							</p>
+							<h2 className="max-w-md mx-auto mt-4 text-4xl font-bold tracking-tighter text-center md:text-4xl">
+								Roll your own auth with confidence in minutes!
+							</h2>
 							<div className="flex mt-[10px] z-20 justify-center items-start">
 								<TechStackDisplay
 									skills={[
diff --git a/docs/components/github-stat.tsx b/docs/components/github-stat.tsx
index 79e11008ae..904ec64c26 100644
--- a/docs/components/github-stat.tsx
+++ b/docs/components/github-stat.tsx
@@ -11,11 +11,18 @@ export function GithubStat({ stars }: { stars: string | null }) {
 	return (
 		<a
 			href="https://github.com/better-auth/better-auth"
+			target="_blank"
+			rel="noopener noreferrer"
+			aria-label={`Star Better Auth on GitHub - ${kFormatter(result)} stars`}
 			className="flex mt-4 border border-input shadow-sm hover:bg-accent hover:text-accent-foreground rounded-none h-10 p-5 ml-auto z-50 overflow-hidden items-center text-sm font-medium focus-visible:outline-none  disabled:pointer-events-none disabled:opacity-50 bg-transparent dark:text-white text-black px-4 py-2 max-w-[14.8rem] whitespace-pre md:flex group relative w-full justify-center gap-2 transition-all duration-300 ease-out  hover:ring-black"
 		>
 			<span className="absolute right-0 -mt-12 h-32 w-8 translate-x-12 rotate-12 dark:bg-white/60 bg-black/60 opacity-10 transition-all duration-1000 ease-out group-hover:-translate-x-40"></span>
 			<div className="flex items-center ml-2">
-				<svg className="w-4 h-4 fill-current" viewBox="0 0 438.549 438.549">
+				<svg
+					className="w-4 h-4 fill-current"
+					viewBox="0 0 438.549 438.549"
+					aria-hidden="true"
+				>
 					<path d="M409.132 114.573c-19.608-33.596-46.205-60.194-79.798-79.8-33.598-19.607-70.277-29.408-110.063-29.408-39.781 0-76.472 9.804-110.063 29.408-33.596 19.605-60.192 46.204-79.8 79.8C9.803 148.168 0 184.854 0 224.63c0 47.78 13.94 90.745 41.827 128.906 27.884 38.164 63.906 64.572 108.063 79.227 5.14.954 8.945.283 11.419-1.996 2.475-2.282 3.711-5.14 3.711-8.562 0-.571-.049-5.708-.144-15.417a2549.81 2549.81 0 01-.144-25.406l-6.567 1.136c-4.187.767-9.469 1.092-15.846 1-6.374-.089-12.991-.757-19.842-1.999-6.854-1.231-13.229-4.086-19.13-8.559-5.898-4.473-10.085-10.328-12.56-17.556l-2.855-6.57c-1.903-4.374-4.899-9.233-8.992-14.559-4.093-5.331-8.232-8.945-12.419-10.848l-1.999-1.431c-1.332-.951-2.568-2.098-3.711-3.429-1.142-1.331-1.997-2.663-2.568-3.997-.572-1.335-.098-2.43 1.427-3.289 1.525-.859 4.281-1.276 8.28-1.276l5.708.853c3.807.763 8.516 3.042 14.133 6.851 5.614 3.806 10.229 8.754 13.846 14.842 4.38 7.806 9.657 13.754 15.846 17.847 6.184 4.093 12.419 6.136 18.699 6.136 6.28 0 11.704-.476 16.274-1.423 4.565-.952 8.848-2.383 12.847-4.285 1.713-12.758 6.377-22.559 13.988-29.41-10.848-1.14-20.601-2.857-29.264-5.14-8.658-2.286-17.605-5.996-26.835-11.14-9.235-5.137-16.896-11.516-22.985-19.126-6.09-7.614-11.088-17.61-14.987-29.979-3.901-12.374-5.852-26.648-5.852-42.826 0-23.035 7.52-42.637 22.557-58.817-7.044-17.318-6.379-36.732 1.997-58.24 5.52-1.715 13.706-.428 24.554 3.853 10.85 4.283 18.794 7.952 23.84 10.994 5.046 3.041 9.089 5.618 12.135 7.708 17.705-4.947 35.976-7.421 54.818-7.421s37.117 2.474 54.823 7.421l10.849-6.849c7.419-4.57 16.18-8.758 26.262-12.565 10.088-3.805 17.802-4.853 23.134-3.138 8.562 21.509 9.325 40.922 2.279 58.24 15.036 16.18 22.559 35.787 22.559 58.817 0 16.178-1.958 30.497-5.853 42.966-3.9 12.471-8.941 22.457-15.125 29.979-6.191 7.521-13.901 13.85-23.131 18.986-9.232 5.14-18.182 8.85-26.84 11.136-8.662 2.286-18.415 4.004-29.263 5.146 9.894 8.562 14.842 22.077 14.842 40.539v60.237c0 3.422 1.19 6.279 3.572 8.562 2.379 2.279 6.136 2.95 11.276 1.995 44.163-14.653 80.185-41.062 108.068-79.226 27.88-38.161 41.825-81.126 41.825-128.906-.01-39.771-9.818-76.454-29.414-110.049z"></path>
 				</svg>
 				<span className="ml-2 text-black dark:text-white">Star on GitHub</span>
diff --git a/docs/components/landing/hero.tsx b/docs/components/landing/hero.tsx
index acf0f739ba..b74358c516 100644
--- a/docs/components/landing/hero.tsx
+++ b/docs/components/landing/hero.tsx
@@ -39,6 +39,7 @@ export default function Hero() {
 												width="0.8em"
 												height="0.8em"
 												viewBox="0 0 24 24"
+												aria-hidden="true"
 											>
 												<path
 													fill="currentColor"
@@ -52,10 +53,10 @@ export default function Hero() {
 									</div>
 								</div>
 
-								<p className="text-zinc-800 dark:text-zinc-300 tracking-tight text-2xl md:text-3xl text-pretty">
+								<h1 className="text-zinc-800 dark:text-zinc-300 tracking-tight text-2xl md:text-3xl text-pretty">
 									The most comprehensive authentication framework for
 									TypeScript.
-								</p>
+								</h1>
 							</div>
 
 							<div className="relative flex items-center gap-2 w-full sm:w-[90%] border border-white/10">
@@ -80,12 +81,15 @@ export default function Hero() {
 										<Link
 											href="https://www.npmjs.com/package/better-auth"
 											target="_blank"
+											rel="noopener noreferrer"
+											aria-label="View better-auth package on npm"
 										>
 											<svg
 												xmlns="http://www.w3.org/2000/svg"
 												width="1em"
 												height="1em"
 												viewBox="0 0 128 128"
+												aria-hidden="true"
 											>
 												<path
 													fill="#cb3837"
@@ -100,12 +104,15 @@ export default function Hero() {
 										<Link
 											href="https://github.com/better-auth/better-auth"
 											target="_blank"
+											rel="noopener noreferrer"
+											aria-label="View better-auth repository on GitHub"
 										>
 											<svg
 												xmlns="http://www.w3.org/2000/svg"
 												width="1em"
 												height="1em"
 												viewBox="0 0 256 256"
+												aria-hidden="true"
 											>
 												<g fill="none">
 													<rect
@@ -326,13 +333,16 @@ function CodePreview() {
 									<Link
 										href="https://demo.better-auth.com"
 										target="_blank"
+										rel="noopener noreferrer"
 										className="shadow-md  border shadow-primary-foreground mb-4 ml-auto mr-4 mt-auto flex cursor-pointer items-center gap-2 px-3 py-1 transition-all ease-in-out hover:opacity-70"
+										aria-label="View Better Auth demo"
 									>
 										<svg
 											xmlns="http://www.w3.org/2000/svg"
 											width="1em"
 											height="1em"
 											viewBox="0 0 24 24"
+											aria-hidden="true"
 										>
 											<path
 												fill="currentColor"
diff --git a/docs/components/landing/testimonials.tsx b/docs/components/landing/testimonials.tsx
index 5d61a81d93..3d09688228 100644
--- a/docs/components/landing/testimonials.tsx
+++ b/docs/components/landing/testimonials.tsx
@@ -226,7 +226,7 @@ const TestimonialItem = ({
 										<img
 											src={testimonial.avatar}
 											className="w-10 h-10 rounded-full"
-											alt="avatar"
+											alt={`${testimonial.name} avatar`}
 										/>
 										<div className="flex flex-col items-start justify-start flex-1 gap-0">
 											<h5 className="text-base font-medium md:text-md">
@@ -239,7 +239,12 @@ const TestimonialItem = ({
 									</div>
 									<div className="w-[1px] bg-black/20 dark:bg-white/20" />
 									<div className="flex items-center justify-center max-w-full mx-auto">
-										<Link href={testimonial.link} target="_blank">
+										<Link
+											href={testimonial.link}
+											target="_blank"
+											rel="noopener noreferrer"
+											aria-label={`View ${testimonial.name}'s testimonial on X`}
+										>
 											{testimonial.social}
 										</Link>
 									</div>
diff --git a/docs/components/logo.tsx b/docs/components/logo.tsx
index 2ee577c488..ba963995d7 100644
--- a/docs/components/logo.tsx
+++ b/docs/components/logo.tsx
@@ -9,6 +9,8 @@ export const Logo = (props: SVGProps<any>) => {
 			fill="none"
 			className={cn("w-5 h-5", props.className)}
 			xmlns="http://www.w3.org/2000/svg"
+			aria-label="Better Auth logo"
+			role="img"
 		>
 			<path
 				fillRule="evenodd"
diff --git a/docs/components/nav-bar.tsx b/docs/components/nav-bar.tsx
index ac7fdf9893..3e4758b5f9 100644
--- a/docs/components/nav-bar.tsx
+++ b/docs/components/nav-bar.tsx
@@ -113,12 +113,14 @@ export const Navbar = () => {
 							href="https://github.com/better-auth/better-auth"
 							className="bg-muted/20"
 							external
+							aria-label="View Better Auth repository on GitHub"
 						>
 							<svg
 								xmlns="http://www.w3.org/2000/svg"
 								width="1.4em"
 								height="1.4em"
 								viewBox="0 0 496 512"
+								aria-hidden="true"
 							>
 								<path
 									fill="currentColor"
diff --git a/docs/components/nav-link.tsx b/docs/components/nav-link.tsx
index eb2b23be0d..d6807027cc 100644
--- a/docs/components/nav-link.tsx
+++ b/docs/components/nav-link.tsx
@@ -9,9 +9,16 @@ type Props = {
 	children: React.ReactNode;
 	className?: string;
 	external?: boolean;
+	"aria-label"?: string;
 };
 
-export const NavLink = ({ href, children, className, external }: Props) => {
+export const NavLink = ({
+	href,
+	children,
+	className,
+	external,
+	"aria-label": ariaLabel,
+}: Props) => {
 	const segment = useSelectedLayoutSegment();
 	const isActive =
 		segment === href.slice(1) || (segment === null && href === "/");
@@ -26,6 +33,8 @@ export const NavLink = ({ href, children, className, external }: Props) => {
 					isActive ? "text-foreground" : "text-muted-foreground",
 				)}
 				target={external ? "_blank" : undefined}
+				rel={external ? "noopener noreferrer" : undefined}
+				aria-label={ariaLabel}
 			>
 				{children}
 			</Link>
diff --git a/docs/components/theme-toggle.tsx b/docs/components/theme-toggle.tsx
index 4c7e69eab7..40e533bee5 100644
--- a/docs/components/theme-toggle.tsx
+++ b/docs/components/theme-toggle.tsx
@@ -67,6 +67,7 @@ const LightThemeIcon = () => {
 			height="1em"
 			viewBox="0 0 24 24"
 			className="size-5"
+			aria-hidden="true"
 		>
 			<g
 				fill="none"
@@ -197,6 +198,7 @@ const DarkThemeIcon = () => {
 			height="1em"
 			viewBox="0 0 24 24"
 			className="size-5"
+			aria-hidden="true"
 		>
 			<path
 				fill="currentColor"