fix(theme): make shared focus outlines themeable

.changeset/focus-outline-consistency.md

@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Consolidate general interactive focus outlines so components share the same accent-colored ring geometry.
+@cixzhang

packages/cli/clients/cli/commands/build-theme.registry.test.mjs

@@ -60,7 +60,10 @@ function renderedClassLiterals() {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (entry.name.endsWith('.tsx') && !entry.name.endsWith('.test.tsx')) {
+      } else if (
+        (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) &&
+        !entry.name.includes('.test.')
+      ) {
         const text = fs.readFileSync(full, 'utf8');
         for (const re of [
           /themeProps\(\s*'([^']+)'/g,
@@ -110,6 +113,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `    'side-nav-item': { base: { borderRadius: '12px' } },\n` +
         `    'chat-composer': { base: { padding: '10px' } },\n` +
         `    'chat-message-bubble': { 'variant:ghost': { borderRadius: '18px' } },\n` +
+        `    'focus-outline': { base: { outlineOffset: '4px' } },\n` +
         `  },\n` +
         `};\n`,
     );
@@ -122,6 +126,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
     expect(css).toContain('.astryx-side-nav-item');
     expect(css).toContain('.astryx-chat-composer');
     expect(css).toContain('.astryx-chat-message-bubble.ghost');
+    expect(css).toContain('.astryx-focus-outline');
   });
 
   it('emits .astryx-text-input (the rendered class), not the dead .astryx-textinput', async () => {

packages/core/src/Avatar/Avatar.tsx

@@ -31,6 +31,7 @@ import {AvatarSizeContext} from './AvatarSizeContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
@@ -152,16 +153,7 @@ const styles = stylex.create({
   // Visible focus ring for the name-tooltip tab stop, matching the repo-wide
   // focus-visible outline treatment (see Timestamp, Token, Thumbnail). Only
   // applied when a tooltip is active so keyboard users can reveal it.
-  focusable: {
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
+  focusable: {},
   // Reset the intrinsic styling of the interactive element (<a>/<button>) so it
   // is a transparent, correctly-sized wrapper around the avatar visuals. The
   // element carries the focus-visible accent ring for keyboard users.
@@ -178,22 +170,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     // Match the avatar's circular shape so the focus ring hugs it.
     borderRadius: radiusVars['--radius-full'],
-    outlineWidth: {
-      default: 0,
-      ':focus-visible': 2,
-    },
-    outlineStyle: {
-      default: 'none',
-      ':focus-visible': 'solid',
-    },
-    outlineColor: {
-      default: null,
-      ':focus-visible': colorVars['--color-accent'],
-    },
-    outlineOffset: {
-      default: 0,
-      ':focus-visible': 2,
-    },
   },
 });
 
@@ -580,7 +556,7 @@ export function Avatar({
   // `<a>`/`<button>` and the static `<div>` carry the exact same box.
   const rootStylexProps = mergeProps(
     themeProps('avatar', {size: resolvedSize}),
-    stylex.props(
+    focusOutlineProps.focusVisible(
       styles.wrapper,
       isInteractive && styles.interactive,
       !isInteractive && showTooltip && !avatarGroup && styles.focusable,

packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -26,6 +26,7 @@ import {mergeProps} from '../utils';
 import {useAvatarGroup} from './AvatarGroupContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 const BORDER_WIDTH = 2;
@@ -93,14 +94,6 @@ const styles = stylex.create({
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']}), linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
     },
     // Focus ring via focus-visible
-    outline: {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: null,
-      ':focus-visible': '2px',
-    },
   },
   overlap: {
     marginInlineStart: 'var(--_avatar-group-overlap)',
@@ -170,7 +163,7 @@ export function AvatarGroupOverflow({
         data-avatar-item=""
         {...mergeProps(
           themeProps('avatar-group-overflow'),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.base,
             styles.button,
             styles.overlap,

packages/core/src/Button/Button.doc.mjs

@@ -163,7 +163,6 @@ export const docs = {
     ],
     vars: [
       {name: '--_button-radius', description: 'Border radius', default: 'var(--radius-element)', private: true},
-      {name: '--button-focus-offset', description: 'Focus ring outline offset', default: '3px'},
       {name: '--button-icon-only-aspect', description: 'Aspect ratio for icon-only buttons', default: '1 / 1'},
     ],
     derived: [
@@ -245,7 +244,6 @@ export const docsZh = {
     ],
     vars: [
       {name: '--_button-radius', description: '圆角半径', default: 'var(--radius-element)', private: true},
-      {name: '--button-focus-offset', description: '焦点环轮廓偏移', default: '3px'},
       {name: '--button-icon-only-aspect', description: '纯图标按钮的宽高比', default: '1 / 1'},
     ],
     derived: [

packages/core/src/Button/Button.tsx

@@ -45,6 +45,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -178,7 +179,7 @@ const elevationStyles = stylex.create({
  * Variant styles using backgroundImage for layered colors
  * Pseudo-classes are nested within properties per StyleX recommendation
  * Overlay is stacked on top of base color using multiple linear-gradients
- * Focus outline color matches variant (destructive uses negative color)
+ * Focus outline is shared across variants for consistent keyboard affordance.
  */
 const variants = stylex.create({
   primary: {
@@ -191,15 +192,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   secondary: {
     backgroundColor: colorVars['--color-neutral'],
@@ -211,15 +203,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   ghost: {
     backgroundColor: 'transparent',
@@ -231,15 +214,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   destructive: {
     backgroundColor: colorVars['--color-error'],
@@ -251,15 +225,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-error']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
 });
 
@@ -695,7 +660,7 @@ export function Button({
   const edgeCompAttr = isFlat ? {[EDGE_COMP_ATTR]: ''} : null;
 
   // Shared StyleX props for both button and link rendering
-  const sharedStylexProps = stylex.props(
+  const sharedStylexProps = focusOutlineProps.focusVisible(
     styles.base,
     sizeStyles[size],
     variants[variant],
@@ -712,8 +677,7 @@ export function Button({
       (variant === 'primary' || variant === 'destructive') &&
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.onSolidHorizontal
-        : groupStyles.onSolidVertical),
-    // Standalone floating buttons only — a grouped button's elevation is owned
+        : groupStyles.onSolidVertical), // Standalone floating buttons only — a grouped button's elevation is owned
     // by the ButtonGroup so the shared surface lifts as one unit.
     !buttonGroup && elevationStyles[elevation],
     width != null && dynamicStyles.width(width),

packages/core/src/Calendar/Calendar.tsx

@@ -58,6 +58,7 @@ import {
   DATE_FORMAT_MONTH_YEAR,
 } from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -1102,7 +1103,7 @@ function DayCell({
             // the default rendering.
             marker: markerState,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             dayCellStyles.day,
             dayCellTheme.day,
             isOutside && dayCellStyles.dayOutside,

packages/core/src/Calendar/styles.ts

@@ -258,14 +258,6 @@ export const dayCellTheme = stylex.create({
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
 
   // Outside days (adjacent months)

packages/core/src/ClickableCard/ClickableCard.tsx

@@ -46,6 +46,7 @@ import {useClickableContainer} from '../hooks/useClickableContainer';
 import type {BaseProps} from '../BaseProps';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
@@ -57,13 +58,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     textDecoration: 'none',
     color: 'inherit',
-    outlineOffset: '2px',
-  },
-  focusWithin: {
-    ':has(:focus-visible)': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: '2px',
-    },
   },
   // Hover overlay — guarded by @media (hover: hover) so touch devices
   // don't show a stuck hover state. Active/pressed state works everywhere.
@@ -307,14 +301,15 @@ export function ClickableCard({
       padding={padding}
       variant={variant}
       elevation={elevation}
-      {...mergeProps(themeProps('clickable-card', {variant}), {
-        className: classNameProp,
+      {...mergeProps(
+        themeProps('clickable-card', {variant}),
+        focusOutlineProps.focusWithin(),
+        classNameProp,
         style,
-      })}
+      )}
       xstyle={
         [
           styles.interactive,
-          styles.focusWithin,
           hasBorder ? styles.bordered : styles.borderless,
           !isDisabled && styles.overlay,
           !isDisabled && styles.hoverOnPointer,

packages/core/src/CodeBlock/CodeBlock.tsx

@@ -45,6 +45,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
 
@@ -214,14 +215,6 @@ const styles = stylex.create({
     // Restore a keyboard-only focus ring with the standard token/offset so this
     // disclosure control matches the rest of the system (Collapsible, TabMenu);
     // otherwise it falls back to the inconsistent UA default outline.
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   code: {
     display: 'block',
@@ -867,7 +860,7 @@ export function CodeBlock({
               }
             : undefined
         }
-        {...stylex.props(
+        {...focusOutlineProps.focusVisible(
           styles.header,
           canCollapse && styles.headerCollapsible,
         )}>

packages/core/src/Collapsible/Collapsible.tsx

@@ -46,6 +46,7 @@ import {getIcon} from '../Icon/globalIconRegistry';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 const styles = stylex.create({
   root: {
@@ -73,14 +74,6 @@ const styles = stylex.create({
     paddingBlock: 0,
     // `all: unset` above wipes the UA focus outline; restore a keyboard-only
     // focus ring using the standard token/offset (WCAG 2.4.7).
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   // Capsize: trim leading from text triggers
   triggerLabel: {
@@ -327,7 +320,7 @@ export function Collapsible({
           themeProps('collapsible-trigger', {
             density: density ?? undefined,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.trigger,
             density != null && triggerDensity[density],
             isDisabled && styles.triggerDisabled,