Avatar: Add colored fallbacks with foreground tinting

packages/ui/CHANGELOG.md

@@ -19,6 +19,7 @@
 
 ### Enhancements
 
+-   `Avatar`: Use `color` for fallback backgrounds with contrasting text and icons ([#84824](https://github.com/WordPress/gutenberg/pull/84824)).
 -   `Avatar`: Add an optional `color` prop for an internal ring, preserving the avatar's layout size and neutral fallbacks while leaving room for an external focus ring ([#84822](https://github.com/WordPress/gutenberg/pull/84822)).
 -   `SelectControl`: Add a `trigger` slot and `SelectControl.Trigger` subcomponent for customizing trigger props ([#84828](https://github.com/WordPress/gutenberg/pull/84828)).
 -   `Link`: Use a small border radius for consistent focus rings in the default variant ([#84697](https://github.com/WordPress/gutenberg/pull/84697)).
@@ -32,6 +33,7 @@
 
 ### Bug Fixes
 
+-   `Avatar`: Use the strong neutral stroke color for the person fallback to provide sufficient non-text contrast ([#84824](https://github.com/WordPress/gutenberg/pull/84824)).
 -   `Tabs`: Expand vertical tab interaction backgrounds and focus rings across the row ([#84821](https://github.com/WordPress/gutenberg/pull/84821)).
 -   Keep the `Link` new-tab indicator with the preceding text when wrapping ([#84806](https://github.com/WordPress/gutenberg/pull/84806)).
 -   `Select`: Keep long popup lists scrollable when item alignment falls back to anchored positioning or the popup opens through touch ([#84682](https://github.com/WordPress/gutenberg/pull/84682)).

packages/ui/src/avatar/dev-warnings.ts

@@ -0,0 +1,38 @@
+import warning from '@wordpress/warning';
+import type { RootProps } from './types';
+
+export function warnAvatarColor( color: RootProps[ 'color' ] ): void {
+	if ( color === undefined ) {
+		return;
+	}
+
+	// Skip comments and strings, and keep custom-property names as whole tokens.
+	// This is a best-effort scan; it does not decode CSS escapes or resolve var().
+	const tokens = color.match(
+		/\/\*[\s\S]*?(?:\*\/|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|(?:[-\w\u0080-\uFFFF]|\\(?:[\da-fA-F]{1,6}[ \t\r\n\f]?|[^\r\n\f]))+/g
+	);
+	if ( tokens?.some( ( token ) => token.toLowerCase() === 'currentcolor' ) ) {
+		warning(
+			'Avatar.Root: `color` contains `currentColor`, which can produce insufficient contrast in colored fallbacks. Use a color that does not depend on the foreground.'
+		);
+		return;
+	}
+
+	if ( typeof CSS === 'undefined' || ! CSS.supports ) {
+		return;
+	}
+
+	if ( ! CSS.supports( 'color', color ) ) {
+		warning(
+			'Avatar.Root: The browser does not support the `color` value. Use a valid CSS color supported by this browser.'
+		);
+	} else if (
+		// Browsers without relative colors retain the neutral fallback.
+		CSS.supports( 'color', 'rgb(from red r g b / 1)' ) &&
+		! CSS.supports( 'color', `rgb(from ${ color } r g b / 1)` )
+	) {
+		warning(
+			'Avatar.Root: `color` cannot be used as a colored fallback fill. Use an explicit CSS color instead of a CSS-wide keyword such as `inherit`.'
+		);
+	}
+}

packages/ui/src/avatar/root.tsx

@@ -2,6 +2,7 @@ import { Avatar as _Avatar } from '@base-ui/react/avatar';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import type { RootProps } from './types';
+import { warnAvatarColor } from './dev-warnings';
 import resetStyles from '../utils/css/resets.module.css';
 import defenseStyles from '../utils/css/global-css-defense.module.css';
 import styles from './style.module.css';
@@ -27,6 +28,10 @@ export const Root = forwardRef< HTMLSpanElement, RootProps >(
 		{ size = 'md', shape = 'circle', color, className, style, ...props },
 		ref
 	) {
+		if ( process.env.NODE_ENV !== 'production' ) {
+			warnAvatarColor( color );
+		}
+
 		const customProperties =
 			color === undefined
 				? style