fix(a11y): inconsistent focus states (#385)

Author: najlaskr

.changeset/focus-accessibility-sync.md

@@ -0,0 +1,13 @@
+---
+"@cloudflare/kumo": patch
+"@cloudflare/kumo-docs-astro": patch
+---
+
+Improved focus and keyboard accessibility styles across Kumo components and docs navigation.
+
+- Added the `kumo-focus` semantic token to the theme generator config and generated `theme-kumo.css` output.
+- Updated focus ring behavior across interactive components (including `Button`, `Input`, `InputGroup`, `Select`, `Checkbox`, `Radio`, `Switch`, `Sidebar`, `Tabs`, `Menubar`, and related controls) for more consistent and visible keyboard focus visibility.
+- Text-entry controls use a lighter opacity `kumo-focus` ring to keep pointer and keyboard focus visually consistent where browsers apply `:focus-visible` heuristics to typed-input controls.
+- Refined `Select` and `Input` styling/state combinations to align focus visuals with current semantic token usage.
+- Updated docs `SidebarNav` keyboard-focus affordances (links, section toggles, search trigger) and adjusted collapsible list overflow so focus rings remain visible.
+- Replace raw colors in `Select` with kumo semantic tokens.

packages/kumo-docs-astro/src/components/SidebarNav.tsx

@@ -103,7 +103,7 @@ declare const __BUILD_COMMIT__: string;
 declare const __BUILD_DATE__: string;
 
 const LI_STYLE =
-  "block rounded-lg text-kumo-strong hover:text-kumo-default hover:bg-kumo-tint p-2 my-[.05rem] cursor-pointer transition-colors no-underline relative z-10";
+  "block rounded-lg text-kumo-strong hover:text-kumo-default hover:bg-kumo-tint p-2 my-[.05rem] cursor-pointer transition-colors no-underline relative z-10 focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-kumo-brand";
 const LI_ACTIVE_STYLE = "font-semibold text-kumo-default bg-kumo-tint";
 
 interface SidebarNavProps {
@@ -127,6 +127,9 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
 
   const toggleSidebar = () => setSidebarOpen((v) => !v);
   const toggleMobileMenu = () => setMobileMenuOpen((v) => !v);
+  const preventPointerFocus = (e: React.MouseEvent<HTMLElement>) => {
+    e.preventDefault();
+  };
 
   // Keyboard shortcut: Cmd+K / Ctrl+K + custom event from headers
   useEffect(() => {
@@ -195,7 +198,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
     <>
       <button
         onClick={() => setSearchOpen(true)}
-        className="mb-3 flex w-full items-center gap-2 rounded-lg bg-kumo-control px-3 py-2 text-sm text-kumo-subtle ring-1 ring-kumo-hairline transition-all hover:ring-kumo-hairline"
+        className="mb-3 flex w-full items-center gap-2 rounded-lg bg-kumo-control px-3 py-2 text-sm text-kumo-subtle ring-1 ring-kumo-line transition-all hover:ring-kumo-hairline focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-kumo-brand"
       >
         <MagnifyingGlassIcon size={16} className="shrink-0" />
         <span>Search...</span>
@@ -206,6 +209,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
           <li key={item.href}>
             <a
               href={item.href}
+              onMouseDown={preventPointerFocus}
               className={cn(
                 LI_STYLE,
                 isActivePath(activePath, item.href) && LI_ACTIVE_STYLE,
@@ -223,7 +227,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         {/* Components Section */}
         <button
           type="button"
-          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint"
+          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-kumo-brand"
           onClick={() => setComponentsOpen(!componentsOpen)}
         >
           <span>Components</span>
@@ -237,14 +241,15 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         </button>
         <ul
           className={cn(
-            "flex flex-col gap-px overflow-hidden transition-all duration-300 ease-in-out mt-1",
+            "mt-1 flex flex-col gap-px overflow-y-hidden overflow-x-visible transition-all duration-300 ease-in-out",
             componentsOpen ? "max-h-[2000px] opacity-100" : "max-h-0 opacity-0",
           )}
         >
           {componentItems.map((item) => (
             <li key={item.href}>
               <a
                 href={item.href}
+                onMouseDown={preventPointerFocus}
                 className={cn(
                   LI_STYLE,
                   "pl-4",
@@ -262,7 +267,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       <div className="mb-4">
         <button
           type="button"
-          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint"
+          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-kumo-brand"
           onClick={() => setChartsOpen(!chartsOpen)}
         >
           <span>Charts</span>
@@ -276,14 +281,15 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         </button>
         <ul
           className={cn(
-            "flex flex-col gap-px overflow-hidden transition-all duration-300 ease-in-out mt-1",
+            "mt-1 flex flex-col gap-px overflow-y-hidden overflow-x-visible transition-all duration-300 ease-in-out",
             chartsOpen ? "max-h-[500px] opacity-100" : "max-h-0 opacity-0",
           )}
         >
           {chartItems.map((item) => (
             <li key={item.href}>
               <a
                 href={item.href}
+                onMouseDown={preventPointerFocus}
                 className={cn(
                   LI_STYLE,
                   "pl-4",
@@ -301,7 +307,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         {/* Blocks Section */}
         <button
           type="button"
-          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint"
+          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-kumo-brand"
           onClick={() => setBlocksOpen(!blocksOpen)}
         >
           <span>Blocks</span>
@@ -315,14 +321,15 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         </button>
         <ul
           className={cn(
-            "flex flex-col gap-px overflow-hidden transition-all duration-300 ease-in-out mt-1",
+            "mt-1 flex flex-col gap-px overflow-y-hidden overflow-x-visible transition-all duration-300 ease-in-out",
             blocksOpen ? "max-h-[500px] opacity-100" : "max-h-0 opacity-0",
           )}
         >
           {blockItems.map((item) => (
             <li key={item.href}>
               <a
                 href={item.href}
+                onMouseDown={preventPointerFocus}
                 className={cn(
                   LI_STYLE,
                   "pl-4",

packages/kumo/scripts/theme-generator/config.ts

@@ -330,6 +330,16 @@ export const THEME_CONFIG: ThemeConfig = {
         },
       },
     },
+    "kumo-focus": {
+      newName: "",
+      description: "Primary focus ring/border color",
+      theme: {
+        kumo: {
+          light: "var(--color-kumo-neutral-950, oklch(15% 0 0))",
+          dark: "var(--color-kumo-neutral-150, oklch(93.5% 0 0))",
+        },
+      },
+    },
     "kumo-shadow-edge": {
       newName: "",
       description: "Tight spread shadow color for control thumbs/knobs",

packages/kumo/src/components/button/button.tsx

@@ -48,7 +48,7 @@ export const KUMO_BUTTON_VARIANTS = {
   variant: {
     primary: {
       classes:
-        "bg-kumo-brand !text-white hover:bg-kumo-brand-hover focus:bg-kumo-brand-hover disabled:bg-kumo-brand/50",
+        "bg-kumo-brand !text-white hover:bg-kumo-brand-hover disabled:bg-kumo-brand/50",
       description: "High-emphasis button for primary actions",
     },
     secondary: {
@@ -130,6 +130,7 @@ export function buttonVariants({
     // Base styles
     "group flex w-max shrink-0 items-center font-medium select-none",
     "border-0 shadow-xs",
+    "focus:outline-none focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand",
     "cursor-pointer",
     // Disabled state
     "disabled:cursor-not-allowed disabled:text-kumo-subtle",
@@ -244,7 +245,6 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
         ref={ref}
         className={cn(
           buttonVariants({ variant, size, shape }),
-          "focus:opacity-100 focus-visible:ring-1 focus-visible:ring-kumo-hairline *:in-focus:opacity-100", // Focus styles
           disabled && "cursor-not-allowed opacity-50",
           className,
         )}

packages/kumo/src/components/checkbox/checkbox.tsx

@@ -17,7 +17,7 @@ export const KUMO_CHECKBOX_VARIANTS = {
   variant: {
     default: {
       classes:
-        "[&:focus-within>span]:ring-kumo-hairline [&:hover>span]:ring-kumo-hairline",
+        "[&:focus-within>span]:ring-kumo-focus [&:hover>span]:ring-kumo-hairline",
       description: "Default checkbox appearance",
     },
     error: {
@@ -260,10 +260,10 @@ const CheckboxBase = forwardRef<HTMLButtonElement, CheckboxProps>(
         disabled={disabled}
         onCheckedChange={onCheckedChange}
         className={cn(
-          "relative flex h-4 w-4 items-center justify-center rounded-sm border-0 bg-kumo-base ring after:absolute after:-inset-x-3 after:-inset-y-2",
+          "relative flex h-4 w-4 items-center justify-center rounded-sm border-0 bg-kumo-base ring focus:outline-none after:absolute after:-inset-x-3 after:-inset-y-2",
           variant === "error" ? "ring-kumo-danger" : "ring-kumo-hairline",
           !disabled &&
-            "hover:ring-kumo-hairline focus-visible:ring-kumo-hairline",
+            "hover:ring-kumo-hairline focus:ring-kumo-focus focus:ring-2 focus-visible:ring-2 focus-visible:ring-kumo-brand",
           "data-[checked]:bg-kumo-contrast data-[checked]:ring-kumo-contrast data-[indeterminate]:bg-kumo-contrast data-[indeterminate]:ring-kumo-contrast",
           disabled && "cursor-not-allowed opacity-50",
           className,
@@ -359,7 +359,7 @@ const CheckboxItem = forwardRef<HTMLButtonElement, CheckboxItemProps>(
             "peer relative flex h-4 w-4 items-center justify-center rounded-sm border-0 bg-kumo-base ring after:absolute after:-inset-x-3 after:-inset-y-2",
             variant === "error" ? "ring-kumo-danger" : "ring-kumo-hairline",
             !disabled &&
-              "group-hover:ring-kumo-hairline hover:ring-kumo-hairline focus-visible:ring-kumo-hairline",
+              "group-hover:ring-kumo-hairline hover:ring-kumo-hairline focus:ring-kumo-focus focus:ring-2 focus-visible:ring-2 focus-visible:ring-kumo-brand",
             "data-[checked]:bg-kumo-contrast data-[checked]:ring-kumo-contrast data-[indeterminate]:bg-kumo-contrast data-[indeterminate]:ring-kumo-contrast",
           )}
         >

packages/kumo/src/components/clipboard-text/clipboard-text.tsx

@@ -249,7 +249,7 @@ export const ClipboardText = forwardRef<HTMLDivElement, ClipboardTextProps>(
         ref={buttonRef}
         size={sizeConfig.buttonSize}
         variant="ghost"
-        className="rounded-none border-l! border-kumo-hairline! px-3 relative overflow-hidden transition-all duration-200"
+        className="rounded-none border-l! border-kumo-line! px-3 relative overflow-hidden transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand"
         onClick={copyToClipboard}
         aria-label={copyAction}
       >

packages/kumo/src/components/command-palette/command-palette.tsx

@@ -767,7 +767,7 @@ function PanelInput({
         placeholder={placeholder}
         className={cn(
           "flex-1 border-none bg-transparent text-base kumo-input-placeholder",
-          "outline-none focus-visible:outline-none",
+          "outline-none focus:ring-kumo-focus/50 focus:ring-[1.5px]",
           className,
         )}
         onKeyDown={handleKeyDown}

packages/kumo/src/components/date-range-picker/date-range-picker.tsx

@@ -604,7 +604,7 @@ function DateRangeMonthHeader({
           aria-label="Edit month and year"
           defaultValue={`${month} ${year}`}
           className={cn(
-            "w-full rounded-md border-none bg-transparent py-1.5 text-center font-semibold text-kumo-default transition-all duration-200 focus:outline-none",
+            "w-full rounded-md border-none bg-transparent py-1.5 text-center font-semibold text-kumo-default transition-all duration-200 focus:outline-none focus:ring-kumo-focus/50 focus:ring-[1.5px]",
             sizeConfig.textSize,
           )}
           onBlur={(e) => {

packages/kumo/src/components/dropdown/dropdown.tsx

@@ -65,7 +65,7 @@ const DropdownMenuSubTrigger = React.forwardRef<
     className={cn(
       "flex cursor-default items-center rounded-sm text-base outline-hidden select-none", // base styles
       "px-2 py-1.5", // spacing
-      "focus:bg-kumo-tint", // focus state
+      "focus:bg-kumo-tint focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand", // focus state
       "data-[state=open]:bg-kumo-tint", // open state
       inset && "pl-8", // conditional inset
       className,
@@ -237,7 +237,7 @@ const DropdownMenuItem = React.forwardRef<
       <DropdownMenuPrimitive.Item
         ref={ref}
         className={cn(
-          "relative flex cursor-default items-center rounded-md px-2 py-1.5 text-base outline-hidden select-none focus:text-kumo-default data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-kumo-overlay",
+          "relative flex cursor-default items-center rounded-md px-2 py-1.5 text-base outline-hidden select-none focus:text-kumo-default focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-kumo-overlay",
           inset && "pl-8",
           dropdownVariants({ variant }),
           className,
@@ -301,7 +301,7 @@ const DropdownMenuLinkItem = React.forwardRef<
         ref={ref}
         className={cn(
           "relative flex cursor-default items-center rounded-md px-2 py-1.5 text-base outline-hidden select-none",
-          "focus:text-kumo-default data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-kumo-overlay",
+          "focus:text-kumo-default focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-kumo-overlay",
           "text-inherit no-underline",
           inset && "pl-8",
           dropdownVariants({ variant }),
@@ -325,7 +325,7 @@ const DropdownMenuCheckboxItem = React.forwardRef<
   <DropdownMenuPrimitive.CheckboxItem
     ref={ref}
     className={cn(
-      "relative flex cursor-default items-center rounded-sm py-1.5 pr-2 pl-8 text-base outline-hidden transition-colors select-none focus:bg-kumo-tint focus:text-kumo-default data-disabled:pointer-events-none data-disabled:opacity-50",
+      "relative flex cursor-default items-center rounded-sm py-1.5 pr-2 pl-8 text-base outline-hidden transition-colors select-none focus:bg-kumo-tint focus:text-kumo-default focus:ring-kumo-focus/50 focus-visible:ring-2 focus-visible:ring-kumo-brand data-disabled:pointer-events-none data-disabled:opacity-50",
       className,
     )}
     checked={checked}

packages/kumo/src/components/input/input.test.tsx

@@ -70,7 +70,7 @@ describe("Input", () => {
   it("renders with default variant 'default'", () => {
     render(<Input aria-label="Test" />);
     expect(screen.getByRole("textbox").className).toContain(
-      "focus:ring-kumo-hairline",
+      "focus:ring-kumo-focus/50",
     );
   });
 
@@ -172,7 +172,7 @@ describe("Input", () => {
 
   it("applies focusIndicator class when true", () => {
     const classes = inputVariants({ focusIndicator: true });
-    expect(classes).toContain("focus:ring-kumo-hairline");
+    expect(classes).toContain("focus:ring-kumo-focus/50");
   });
 
   // Variants export