From 93a032c90dbef9d022e3537fd08cce74a8b1d0a6 Mon Sep 17 00:00:00 2001
From: Gildas Garcia <1122076+djhi@users.noreply.github.com>
Date: Mon, 28 Sep 2026 09:56:54 +0200
Subject: [PATCH] Design System: Improve icon button example accessibility
 (#50783)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

The Icon only button example lacks some accessibility features:
- no `aria-label` for screen readers
- no tooltip for sighted users

## Solution

Add both with comments explaining the reasons

## Review instructions

See
https://design-system-imfc534k0-supabase.vercel.app/design-system/docs/components/button#only-an-icon

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified icon-only button guidance: use a tooltip for sighted users
and an accessible label for screen readers. When the tooltip repeats the
button’s label, prevent it from being announced twice.
* Added guidance to use a square button container and increase the tap
target by 8px. Updated the icon-button example to demonstrate a “View
logs” tooltip and accessible labeling.
* **New Features**
* Icon-only buttons now use a compact square layout with an expanded tap
target.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Danny White <3104761+dnywh@users.noreply.github.com>
---
 .../content/docs/components/button.mdx        | 14 ++++++++-----
 .../registry/default/example/button-icon.tsx  | 21 ++++++++++++++++---
 packages/ui/src/components/Button/Button.tsx  |  6 +++++-
 3 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/apps/design-system/content/docs/components/button.mdx b/apps/design-system/content/docs/components/button.mdx
index d4535fc407f..88b9355511f 100644
--- a/apps/design-system/content/docs/components/button.mdx
+++ b/apps/design-system/content/docs/components/button.mdx
@@ -100,13 +100,17 @@ Used for actions that are not as important as the primary action, or for actions
 
 <ComponentPreview name="button-link" />
 
-### Only an icon
+### Icon-only
 
-Displaying only an Icon in a button.
+Render an [icon](./icons) in a button without accompanying text. Ensure the button is accessible by:
 
-<Admonition type="note" title="This feature requires more support" className="mt-3">
-  We should update the button component to support this use case better.
-</Admonition>
+- Wrapping it in a [Tooltip](./tooltip) for sighted users.
+- Adding an `aria-label` prop for screen readers.
+- Setting its `aria-describedby` prop to `undefined` when the tooltip content repeats the label. Otherwise screen readers read the label twice.
+
+Consider also squaring off the button container as shown in the example below. For the default `tiny` size (`h-[26px]`), use `w-6.5` so the button is square.
+
+Compact icon-only buttons may also benefit from the `hit-area` utility. This increases their tap target slightly each side without changing the visual layout. See the [Table](./table#actions) component for more information.
 
 <ComponentPreview name="button-icon" />
 
diff --git a/apps/design-system/registry/default/example/button-icon.tsx b/apps/design-system/registry/default/example/button-icon.tsx
index e9cac7c1660..89600f1cce1 100644
--- a/apps/design-system/registry/default/example/button-icon.tsx
+++ b/apps/design-system/registry/default/example/button-icon.tsx
@@ -1,6 +1,21 @@
-import { ChevronRight } from 'lucide-react'
-import { Button } from 'ui'
+import { ExternalLink } from 'lucide-react'
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from 'ui'
 
 export default function ButtonIcon() {
-  return <Button variant="outline" icon={<ChevronRight className="h-4 w-4" />}></Button>
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="outline"
+          icon={<ExternalLink />}
+          // Match tooltip content for screen readers
+          aria-label="View logs"
+          // Tooltip repeats the label; clear describedby so screen readers don't hear it twice
+          // Skip this if the tooltip adds information beyond the label
+          aria-describedby={undefined}
+        ></Button>
+      </TooltipTrigger>
+      <TooltipContent>View logs</TooltipContent>
+    </Tooltip>
+  )
 }
diff --git a/packages/ui/src/components/Button/Button.tsx b/packages/ui/src/components/Button/Button.tsx
index cfba89ea915..ea4e7844d0a 100644
--- a/packages/ui/src/components/Button/Button.tsx
+++ b/packages/ui/src/components/Button/Button.tsx
@@ -119,6 +119,9 @@ const buttonVariants = cva(
       rounded: {
         true: 'rounded-full',
       },
+      iconOnly: {
+        true: 'hit-area-1 w-6.5',
+      },
     },
     // Match <Button size="tiny"> so raw buttonVariants({ variant }) keeps sizing.
     // Fixed icon shells that omit size must override padding (e.g. px-0 with h/w-[30px]).
@@ -182,7 +185,7 @@ export interface ButtonProps
   extends
     React.ButtonHTMLAttributes<HTMLButtonElement>,
     // omit 'disabled' as it is included in HTMLButtonElement
-    Omit<ButtonVariantProps, 'disabled'>,
+    Omit<ButtonVariantProps, 'disabled' | 'iconOnly'>,
     LoadingVariantProps {
   asChild?: boolean
   variant?: ButtonVariantProps['variant']
@@ -266,6 +269,7 @@ const Button = forwardRef<HTMLButtonElement, ButtonProps>(
             focusableWhenDisabled,
             block,
             rounded,
+            iconOnly: children == null || children === false,
           }),
           className
         )}