@wordpress/components 33.0.0 → 33.1.1-next.v.202605131006.0

package/build-types/view/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/view/component.tsx"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEd,CAAC;AAEJ,eAAe,IAAI,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/view/component.tsx"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEd,CAAC;eAEW,IAAI"}

package/build-types/view/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/view/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE1B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,IAAI,CAiB5B,CAAC;AACF,eAAe,IAAI,CAAC;AAMpB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,IAAI,CAAwB,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/view/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE1B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,IAAI,CAiB5B,CAAC;eACa,IAAI;AAMnB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,IAAI,CAAwB,CAAC"}

package/build-types/visually-hidden/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/component.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAoBnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,gHAG1B,CAAC;AAEF,eAAe,cAAc,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/component.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAoBnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,gHAG1B,CAAC;eAEa,cAAc"}

package/build-types/visually-hidden/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEpC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAmBtC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,cAAc,CAanD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAE,OAAO,cAAc,CAW9D,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAE,OAAO,cAAc,CAWpE,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEpC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAmBtC,CAAC;eACa,IAAI;AAEnB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,cAAc,CAanD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAE,OAAO,cAAc,CAW9D,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAE,OAAO,cAAc,CAWpE,CAAC"}

package/build-types/z-stack/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/z-stack/component.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAkD3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,wGAAgD,CAAC;AAEpE,eAAe,MAAM,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/z-stack/component.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAkD3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,wGAAgD,CAAC;eAErD,MAAM"}

package/build-types/z-stack/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/z-stack/stories/index.story.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAO3D,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAE5B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,MAAM,CAmB9B,CAAC;AACF,eAAe,IAAI,CAAC;AAsCpB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,MAAM,CAAwB,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/z-stack/stories/index.story.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAO3D,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAE5B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,MAAM,CAmB9B,CAAC;eACa,IAAI;AAsCnB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,MAAM,CAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "33.0.0",
+	"version": "33.1.1-next.v.202605131006.0+2a3d07cab",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -64,29 +64,30 @@
 		"@types/highlight-words-core": "1.2.1",
 		"@types/react": "^18.3.27",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.45.0",
-		"@wordpress/base-styles": "^7.0.0",
-		"@wordpress/compose": "^7.45.0",
-		"@wordpress/date": "^5.45.0",
-		"@wordpress/deprecated": "^4.45.0",
-		"@wordpress/dom": "^4.45.0",
-		"@wordpress/element": "^6.45.0",
-		"@wordpress/escape-html": "^3.45.0",
-		"@wordpress/hooks": "^4.45.0",
-		"@wordpress/html-entities": "^4.45.0",
-		"@wordpress/i18n": "^6.18.0",
-		"@wordpress/icons": "^13.0.0",
-		"@wordpress/is-shallow-equal": "^5.45.0",
-		"@wordpress/keycodes": "^4.45.0",
-		"@wordpress/primitives": "^4.45.0",
-		"@wordpress/private-apis": "^1.45.0",
-		"@wordpress/rich-text": "^7.45.0",
-		"@wordpress/warning": "^3.45.0",
+		"@wordpress/a11y": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/base-styles": "^8.0.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/compose": "^7.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/date": "^5.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/deprecated": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/dom": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/element": "^6.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/escape-html": "^3.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/hooks": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/html-entities": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/i18n": "^6.18.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/icons": "^13.0.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/is-shallow-equal": "^5.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/keycodes": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/primitives": "^4.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/private-apis": "^1.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/rich-text": "^7.45.1-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/style-runtime": "^0.1.2-next.v.202605131006.0+2a3d07cab",
+		"@wordpress/warning": "^3.45.1-next.v.202605131006.0+2a3d07cab",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
 		"csstype": "^3.2.3",
-		"date-fns": "^3.6.0",
+		"date-fns": "^4.1.0",
 		"deepmerge": "^4.3.0",
 		"fast-deep-equal": "^3.1.3",
 		"framer-motion": "^11.15.0",
@@ -99,7 +100,7 @@
 		"react-colorful": "^5.6.1",
 		"react-day-picker": "^9.7.0",
 		"remove-accents": "^0.5.0",
-		"uuid": "^9.0.1"
+		"uuid": "^14.0.0"
 	},
 	"devDependencies": {
 		"@ariakit/test": "^0.4.13",
@@ -107,7 +108,7 @@
 		"@storybook/react-vite": "^10.2.8",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@types/jest": "^29.5.14",
-		"@wordpress/jest-console": "^8.45.0",
+		"@wordpress/jest-console": "^8.45.1-next.v.202605131006.0+2a3d07cab",
 		"snapshot-diff": "^0.10.0",
 		"storybook": "^10.2.8",
 		"timezone-mock": "^1.3.6"
@@ -119,5 +120,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "8c229eaed0e88c9827e2da3d73a78f9ddd77714b"
+	"gitHead": "8804fa29bc78a1d98e5a4d40c3e180ddd907016c"
 }

package/src/alignment-matrix-control/stories/index.story.tsx

@@ -34,7 +34,7 @@ const meta: Meta< typeof AlignmentMatrixControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/angle-picker-control/stories/index.story.tsx

@@ -30,7 +30,7 @@ const meta: Meta< typeof AnglePickerControl > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/autocomplete/autocompleter-ui.tsx

@@ -96,7 +96,6 @@ export function AutocompleterUI( {
 	// ensuring a fresh mount (and stable hook identity) when the completer changes.
 	const useItems =
 		autocompleter.useItems ?? getDefaultUseItems( autocompleter );
-	// eslint-disable-next-line react-compiler/react-compiler
 	const [ items ] = useItems( filterValue );
 	const popoverAnchor = useAnchor( {
 		editableContentElement: contentRef.current,

package/src/base-control/stories/index.story.tsx

@@ -26,7 +26,7 @@ const meta: Meta< typeof BaseControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `Field` in `@wordpress/ui`, but continue using for now.',
 		},

package/src/border-box-control/stories/index.story.tsx

@@ -26,7 +26,7 @@ const meta: Meta< typeof BorderBoxControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/border-control/stories/index.story.tsx

@@ -29,7 +29,7 @@ const meta: Meta< typeof BorderControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/button/stories/index.story.tsx

@@ -53,7 +53,7 @@ const meta: Meta< typeof Button > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `Button` in `@wordpress/ui`, but continue using for now.',
 		},

package/src/button/style.scss

@@ -252,6 +252,8 @@
 		font-weight: $font-weight-regular;
 		color: $components-color-accent;
 		text-decoration: underline;
+		text-underline-offset: 0.2em;
+		text-decoration-thickness: from-font;
 
 		@media not (prefers-reduced-motion) {
 			transition-property: border, background, color;

package/src/checkbox-control/stories/index.story.tsx

@@ -36,7 +36,7 @@ const meta: Meta< typeof CheckboxControl > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `CheckboxControl` in `@wordpress/ui`, but continue using for now.',
 		},

package/src/color-indicator/stories/index.story.tsx

@@ -24,7 +24,7 @@ const meta: Meta< typeof ColorIndicator > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

package/src/color-palette/index.tsx

@@ -50,16 +50,25 @@ function SinglePalette( {
 	colors,
 	onChange,
 	value,
+	selectedSlug,
 	...additionalProps
 }: SinglePaletteProps ) {
 	const colorOptions = useMemo( () => {
-		return colors.map( ( { color, name }, index ) => {
+		return colors.map( ( { color, name, slug }, index ) => {
 			const colordColor = colord( color );
-			const isSelected = value === color;
+			// When a non-empty selectedSlug is provided, selection is decided
+			// strictly by slug — entries without a slug or with a different slug
+			// are not selected, even when their color value matches `value`.
+			// This correctly handles mixed palettes where some entries have slugs
+			// and others don't. Fall back to color value matching otherwise
+			// (including when selectedSlug is an empty string).
+			const isSelected = selectedSlug
+				? slug === selectedSlug
+				: value === color;
 
 			return (
 				<CircularOptionPicker.Option
-					key={ `${ color }-${ index }` }
+					key={ slug ?? `${ color }-${ index }` }
 					isSelected={ isSelected }
 					selectedIconProps={
 						isSelected
@@ -79,12 +88,14 @@ function SinglePalette( {
 					}
 					style={ { backgroundColor: color, color } }
 					onClick={
-						isSelected ? clearColor : () => onChange( color, index )
+						isSelected
+							? clearColor
+							: () => onChange( color, index, slug )
 					}
 				/>
 			);
 		} );
-	}, [ colors, value, onChange, clearColor ] );
+	}, [ colors, value, selectedSlug, onChange, clearColor ] );
 
 	return (
 		<CircularOptionPicker.OptionGroup
@@ -101,6 +112,7 @@ function MultiplePalettes( {
 	colors,
 	onChange,
 	value,
+	selectedSlug,
 	headingLevel,
 }: MultiplePalettesProps ) {
 	const instanceId = useInstanceId( MultiplePalettes, 'color-palette' );
@@ -121,10 +133,11 @@ function MultiplePalettes( {
 						<SinglePalette
 							clearColor={ clearColor }
 							colors={ colorPalette }
-							onChange={ ( newColor ) =>
-								onChange( newColor, index )
+							onChange={ ( newColor, _colorIndex, slug ) =>
+								onChange( newColor, index, slug )
 							}
 							value={ value }
+							selectedSlug={ selectedSlug }
 							aria-labelledby={ id }
 						/>
 					</VStack>
@@ -185,6 +198,7 @@ function UnforwardedColorPalette(
 		enableAlpha = false,
 		onChange,
 		value,
+		selectedSlug,
 		__experimentalIsRenderedInSidebar = false,
 		headingLevel = 2,
 		'aria-label': ariaLabel,
@@ -208,9 +222,10 @@ function UnforwardedColorPalette(
 			extractColorNameFromCurrentValue(
 				value,
 				colors,
-				hasMultipleColorOrigins
+				hasMultipleColorOrigins,
+				selectedSlug
 			),
-		[ value, colors, hasMultipleColorOrigins ]
+		[ value, colors, hasMultipleColorOrigins, selectedSlug ]
 	);
 
 	const renderCustomColorPicker = () => (
@@ -241,6 +256,7 @@ function UnforwardedColorPalette(
 		clearColor,
 		onChange,
 		value,
+		selectedSlug,
 	};
 
 	const actions = !! clearable && (

package/src/color-palette/stories/index.story.tsx

@@ -21,13 +21,14 @@ const meta: Meta< typeof ColorPalette > = {
 	argTypes: {
 		as: { control: false },
 		onChange: { action: 'onChange', control: false },
+		selectedSlug: { control: false },
 		value: { control: false },
 	},
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},
@@ -39,17 +40,21 @@ type ColorPaletteStory = StoryObj< typeof ColorPalette >;
 const Template = ( {
 	onChange,
 	value,
+	selectedSlug,
 	...args
 }: React.ComponentProps< typeof ColorPalette > ) => {
 	const [ color, setColor ] = useState< string | undefined >( value );
+	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
 
 	return (
 		<ColorPalette
 			{ ...args }
 			value={ color }
-			onChange={ ( newColor ) => {
+			selectedSlug={ slug }
+			onChange={ ( newColor, index, newSlug ) => {
 				setColor( newColor );
-				onChange?.( newColor );
+				setSlug( newSlug );
+				onChange?.( newColor, index, newSlug );
 			} }
 		/>
 	);
@@ -102,6 +107,19 @@ export const MultipleOrigins: ColorPaletteStory = {
 	},
 };
 
+export const DuplicateColors: ColorPaletteStory = {
+	render: Template,
+	args: {
+		colors: [
+			{ name: 'Dark Background', slug: 'dark-background', color: '#000' },
+			{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
+			{ name: 'Brand', slug: 'brand', color: '#0073aa' },
+		],
+		value: '#000',
+		selectedSlug: 'dark-text',
+	},
+};
+
 export const CSSVariables: ColorPaletteStory = {
 	render: ( args ) => (
 		<div

package/src/color-palette/test/index.tsx

@@ -93,7 +93,11 @@ describe( 'ColorPalette', () => {
 
 		// Expect the green color to have been selected
 		expect( onChange ).toHaveBeenCalledTimes( 1 );
-		expect( onChange ).toHaveBeenCalledWith( EXAMPLE_COLORS[ 1 ].color, 1 );
+		expect( onChange ).toHaveBeenCalledWith(
+			EXAMPLE_COLORS[ 1 ].color,
+			1,
+			undefined
+		);
 	} );
 
 	it( 'should call onClick with undefined, when the clearButton onClick is triggered', async () => {
@@ -262,4 +266,151 @@ describe( 'ColorPalette', () => {
 			} )
 		).toBeInTheDocument();
 	} );
+
+	describe( 'duplicate colors in palette', () => {
+		const DUPLICATE_COLOR_PALETTE = [
+			{ name: 'Dark Background', slug: 'dark-background', color: '#000' },
+			{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
+		];
+
+		it( 'should render all swatches even when two entries share the same color value', () => {
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value={ undefined }
+					onChange={ jest.fn() }
+				/>
+			);
+
+			expect( screen.getAllByRole( 'option' ) ).toHaveLength( 2 );
+		} );
+
+		it( 'should select by slug when selectedSlug is provided, marking only the matching entry', () => {
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value="#000"
+					selectedSlug="dark-text"
+					onChange={ jest.fn() }
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			// "dark-background" is index 0, "dark-text" is index 1.
+			// With selectedSlug="dark-text", only the second swatch should be selected.
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'false' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should fall back to color-value selection and mark all matching duplicates when no selectedSlug is provided', () => {
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value="#000"
+					onChange={ jest.fn() }
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			// Both entries share the same color value, so both appear selected
+			// when no slug-specific selection is provided.
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should treat an empty-string selectedSlug as no slug and fall back to color-value selection', () => {
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value="#000"
+					selectedSlug=""
+					onChange={ jest.fn() }
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should display the slug-matched entry name in the custom color button label', () => {
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value="#000"
+					selectedSlug="dark-text"
+					onChange={ jest.fn() }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Custom color picker. The currently selected color is called "Dark Text" and has a value of "#000".',
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should pass slug as third argument to onChange when a swatch is clicked', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value={ undefined }
+					onChange={ onChange }
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			await user.click( options[ 1 ] );
+			// Second entry: color=#000, index=1, slug='dark-text'
+			expect( onChange ).toHaveBeenCalledWith( '#000', 1, 'dark-text' );
+		} );
+
+		it( 'should clear the selection when the selected swatch is clicked', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<ColorPalette
+					colors={ DUPLICATE_COLOR_PALETTE }
+					value="#000"
+					selectedSlug="dark-background"
+					onChange={ onChange }
+				/>
+			);
+
+			// Click the selected swatch — should call onChange with undefined.
+			await user.click(
+				screen.getByRole( 'option', { selected: true } )
+			);
+			expect( onChange ).toHaveBeenCalledWith( undefined );
+		} );
+
+		it( 'should handle mixed palettes with some entries having slugs and others not', () => {
+			const MIXED_PALETTE = [
+				{ name: 'Brand White', slug: 'brand-white', color: '#fff' },
+				{ name: 'Plain White', color: '#fff' },
+				{ name: 'Brand Black', slug: 'brand-black', color: '#000' },
+			];
+
+			render(
+				<ColorPalette
+					colors={ MIXED_PALETTE }
+					value="#fff"
+					selectedSlug="brand-white"
+					onChange={ jest.fn() }
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			// Only the entry with slug="brand-white" should be selected.
+			// The unslugged "Plain White" entry should NOT be selected, even though
+			// its color matches the value prop.
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'false' );
+			expect( options[ 2 ] ).toHaveAttribute( 'aria-selected', 'false' );
+		} );
+	} );
 } );

package/src/color-palette/test/utils.ts

@@ -23,6 +23,24 @@ describe( 'ColorPalette: Utils', () => {
 			] );
 			expect( result ).toBe( 'Blue' );
 		} );
+
+		test( 'should prefer selectedSlug over color matching when duplicate colors exist', () => {
+			const result = extractColorNameFromCurrentValue(
+				'#000',
+				[
+					{
+						name: 'Dark Background',
+						slug: 'dark-background',
+						color: '#000',
+					},
+					{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
+				],
+				false,
+				'dark-text'
+			);
+
+			expect( result ).toBe( 'Dark Text' );
+		} );
 	} );
 
 	describe( 'normalizeColorValue', () => {

package/src/color-palette/types.ts

@@ -12,6 +12,7 @@ import type { HeadingSize } from '../heading/types';
 export type ColorObject = {
 	name: string;
 	color: NonNullable< CSSProperties[ 'color' ] >;
+	slug?: string;
 };
 
 export type PaletteObject = {
@@ -24,9 +25,22 @@ type PaletteProps = {
 	clearColor: () => void;
 	/**
 	 * Callback called when a color is selected.
+	 * The third argument is the slug of the selected palette entry, when available.
 	 */
-	onChange: ( newColor?: string, index?: number ) => void;
+	onChange: ( newColor?: string, index?: number, slug?: string ) => void;
 	value?: string;
+	/**
+	 * The slug of the currently selected palette entry.
+	 *
+	 * When set to a non-empty string, selection is determined by slug rather
+	 * than by color value — this correctly handles palettes where two entries
+	 * share the same color. Palette entries without a slug will not appear
+	 * selected in this mode, even if their color value matches `value`.
+	 *
+	 * An empty string is treated the same as `undefined`: selection falls
+	 * back to matching by color value.
+	 */
+	selectedSlug?: string;
 	actions?: ReactNode;
 	headingLevel?: HeadingSize;
 };
@@ -43,7 +57,10 @@ export type CustomColorPickerDropdownProps = DropdownProps & {
 	isRenderedInSidebar: boolean;
 };
 
-export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
+export type ColorPaletteProps = Pick<
+	PaletteProps,
+	'onChange' | 'selectedSlug'
+> & {
 	/**
 	 * Whether the palette should have a clearing button.
 	 *

package/src/color-palette/utils.ts

@@ -32,7 +32,8 @@ const isSimpleCSSColor = ( value: string ): boolean => {
 export const extractColorNameFromCurrentValue = (
 	currentValue?: ColorPaletteProps[ 'value' ],
 	colors: ColorPaletteProps[ 'colors' ] = [],
-	showMultiplePalettes: boolean = false
+	showMultiplePalettes: boolean = false,
+	selectedSlug?: ColorPaletteProps[ 'selectedSlug' ]
 ) => {
 	if ( ! currentValue ) {
 		return '';
@@ -50,7 +51,18 @@ export const extractColorNameFromCurrentValue = (
 		? ( colors as PaletteObject[] )
 		: [ { colors: colors as ColorObject[] } ];
 	for ( const { colors: paletteColors } of colorPalettes ) {
-		for ( const { name: colorName, color: colorValue } of paletteColors ) {
+		for ( const {
+			name: colorName,
+			color: colorValue,
+			slug,
+		} of paletteColors ) {
+			if ( selectedSlug ) {
+				if ( slug === selectedSlug ) {
+					return colorName;
+				}
+				continue;
+			}
+
 			const normalizedColorValue = currentValueIsSimpleColor
 				? colord( colorValue ).toHex()
 				: colorValue;

package/src/color-picker/hex-input.tsx

@@ -20,7 +20,7 @@ import InputControlPrefixWrapper from '../input-control/input-prefix-wrapper';
 
 export const HexInput = ( { color, onChange, enableAlpha }: HexInputProps ) => {
 	const handleChange = ( nextValue: string | undefined ) => {
-		if ( ! nextValue ) {
+		if ( nextValue === undefined ) {
 			return;
 		}
 		const hexValue = nextValue.startsWith( '#' )

package/src/color-picker/stories/index.story.tsx

@@ -27,7 +27,7 @@ const meta: Meta< typeof ColorPicker > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},