feat: Improve keyboard & screen-reader accessibility

assets/index.less

@@ -55,6 +55,11 @@
     border: @handler-border-size solid #fff;
     border-radius: 50%;
     box-shadow: 0 0 1px 1px rgba(0, 0, 0, 0.06);
+    &:focus-visible,
+    &:focus-within {
+      outline: 2px solid #1677ff;
+      outline-offset: 1px;
+    }
   }
   &-handler-sm {
     width: @sm-handler-size;

src/ColorPicker.tsx

@@ -10,6 +10,15 @@ import useColorState from './hooks/useColorState';
 import useComponent, { type Components } from './hooks/useComponent';
 import type { BaseColorPickerProps, ColorGenInput } from './interface';
 
+const defaultLocale: Required<BaseColorPickerProps>['locale'] = {
+  picker: 'Color picker',
+  pickerDescription: '2D slider',
+  hue: 'Hue',
+  alpha: 'Alpha',
+  saturation: 'Saturation',
+  brightness: 'Brightness',
+};
+
 const HUE_COLORS = [
   {
     color: 'rgb(255, 0, 0)',
@@ -67,8 +76,14 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
       disabledAlpha = false,
       disabled = false,
       components,
+      locale,
     } = props;
 
+    const mergedLocale = useMemo(
+      () => ({ ...defaultLocale, ...locale }),
+      [locale],
+    );
+
     // ========================== Components ==========================
     const [Slider] = useComponent(components);
 
@@ -134,6 +149,7 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
         <Picker
           onChange={handleChange}
           {...sharedSliderProps}
+          locale={mergedLocale}
           onChangeComplete={onChangeComplete}
         />
         <div className={`${prefixCls}-slider-container`}>
@@ -151,6 +167,7 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
               value={colorValue.getHue()}
               onChange={onHueChange}
               onChangeComplete={onHueChangeComplete}
+              aria-label={mergedLocale.hue}
             />
             {!disabledAlpha && (
               <Slider
@@ -165,6 +182,7 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
                 value={colorValue.a * 100}
                 onChange={onAlphaChange}
                 onChangeComplete={onAlphaChangeComplete}
+                aria-label={mergedLocale.alpha}
               />
             )}
           </div>

src/components/ColorBlock.tsx

@@ -1,34 +1,26 @@
 import { clsx } from 'clsx';
 import React from 'react';
 
-export type ColorBlockProps = {
+export type ColorBlockProps = React.HTMLAttributes<HTMLDivElement> & {
   color: string;
   prefixCls?: string;
-  className?: string;
-  style?: React.CSSProperties;
   /** Internal usage. Only used in antd ColorPicker semantic structure only */
   innerClassName?: string;
   /** Internal usage. Only used in antd ColorPicker semantic structure only */
   innerStyle?: React.CSSProperties;
-  onClick?: React.MouseEventHandler<HTMLDivElement>;
 };
 
 const ColorBlock: React.FC<ColorBlockProps> = ({
   color,
   prefixCls,
   className,
-  style,
   innerClassName,
   innerStyle,
-  onClick,
+  ...props
 }) => {
   const colorBlockCls = `${prefixCls}-color-block`;
   return (
-    <div
-      className={clsx(colorBlockCls, className)}
-      style={style}
-      onClick={onClick}
-    >
+    <div {...props} className={clsx(colorBlockCls, className)}>
       <div
         className={clsx(`${colorBlockCls}-inner`, innerClassName)}
         style={{ background: color, ...innerStyle }}

src/components/Handler.tsx

@@ -1,20 +1,108 @@
+import { omit } from '@rc-component/util';
 import { clsx } from 'clsx';
 import React from 'react';
 
 type HandlerSize = 'default' | 'small';
 
-const Handler: React.FC<{
+/** Keyboard keys (handled natively by `<input type="range">`) that mutate the value. */
+const VALUE_KEYS = [
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+  'ArrowDown',
+  'Home',
+  'End',
+  'PageUp',
+  'PageDown',
+];
+
+const isVerticalKey = (key: string) => key === 'ArrowUp' || key === 'ArrowDown';
+
+// The range input is a keyboard / screen-reader proxy only — the visible thumb
+// is the wrapping <div>. It must stay focusable and in the a11y tree, so it is
+// hidden with `opacity` (not `display`/`visibility`). These styles are inlined
+// rather than left to the stylesheet so consumers that don't ship our CSS
+// (e.g. antd's own styling) still get a hidden input out of the box.
+const RANGE_INPUT_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  width: '100%',
+  height: '100%',
+  margin: 0,
+  padding: 0,
+  opacity: 0,
+  pointerEvents: 'none',
+};
+
+interface HandlerAxis
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    'size' | 'value' | 'onChange'
+  > {
+  value: number;
+  onChange: (value: number) => void;
+  onChangeComplete: (value: number) => void;
+}
+
+export interface HandlerProps {
   size?: HandlerSize;
   color?: string;
   prefixCls?: string;
-}> = ({ size = 'default', color, prefixCls }) => {
+  disabled?: boolean;
+  x: HandlerAxis;
+  y?: HandlerAxis;
+}
+
+const Handler: React.FC<HandlerProps> = ({
+  size = 'default',
+  color,
+  prefixCls,
+  disabled,
+  x,
+  y,
+}) => {
+  // The browser ignores Up/Down on a horizontal range, so the vertical axis is
+  // handled here: clamp to its own [min, max] and emit through its callbacks.
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (!y || !isVerticalKey(event.key)) {
+      return;
+    }
+    event.preventDefault();
+    const step = Number(y.step ?? 1) || 1;
+    const min = Number(y.min ?? 0);
+    const max = Number(y.max ?? 100);
+    const delta = event.key === 'ArrowUp' ? step : -step;
+    y.onChange(Math.min(max, Math.max(min, y.value + delta)));
+  };
+
   return (
     <div
       className={clsx(`${prefixCls}-handler`, {
         [`${prefixCls}-handler-sm`]: size === 'small',
       })}
-      style={{ backgroundColor: color }}
-    />
+      style={{ position: 'relative', backgroundColor: color }}
+    >
+      <input
+        step={1}
+        {...omit(x, ['onChangeComplete'])}
+        type="range"
+        className={`${prefixCls}-handler-range`}
+        style={RANGE_INPUT_STYLE}
+        disabled={disabled}
+        onChange={event => x.onChange(Number(event.target.value))}
+        onKeyDown={y ? handleKeyDown : undefined}
+        onKeyUp={event => {
+          if (!VALUE_KEYS.includes(event.key)) {
+            return;
+          }
+          if (y && isVerticalKey(event.key)) {
+            y.onChangeComplete(y.value);
+          } else {
+            x.onChangeComplete(Number(event.currentTarget.value));
+          }
+        }}
+      />
+    </div>
   );
 };
 

src/components/Picker.tsx

@@ -2,7 +2,7 @@ import type { FC } from 'react';
 import React, { useRef } from 'react';
 import useColorDrag from '../hooks/useColorDrag';
 import type { BaseColorPickerProps, TransformOffset } from '../interface';
-import { calcOffset, calculateColor } from '../util';
+import { calcOffset, calculateColor, generateColor } from '../util';
 
 import { useEvent } from '@rc-component/util';
 import Handler from './Handler';
@@ -17,6 +17,7 @@ const Picker: FC<PickerProps> = ({
   prefixCls,
   onChangeComplete,
   disabled,
+  locale,
 }) => {
   const pickerRef = useRef();
   const transformRef = useRef();
@@ -43,6 +44,16 @@ const Picker: FC<PickerProps> = ({
     disabledDrag: disabled,
   });
 
+  // ===================== Keyboard (2-D handler) =====================
+  const hsb = color.toHsb();
+
+  // Build a new color from the current one with a single HSB channel changed.
+  const changeColor = (channel: 's' | 'b', percent: number) => {
+    const next = generateColor({ ...hsb, [channel]: percent / 100 });
+    colorRef.current = next;
+    onChange(next);
+  };
+
   return (
     <div
       ref={pickerRef}
@@ -52,7 +63,30 @@ const Picker: FC<PickerProps> = ({
     >
       <Palette prefixCls={prefixCls}>
         <Transform x={offset.x} y={offset.y} ref={transformRef}>
-          <Handler color={color.toRgbString()} prefixCls={prefixCls} />
+          <Handler
+            color={color.toRgbString()}
+            prefixCls={prefixCls}
+            disabled={disabled}
+            x={{
+              'aria-label': locale.picker,
+              'aria-roledescription': locale.pickerDescription,
+              'aria-valuetext': `${locale.saturation} ${Math.round(
+                hsb.s * 100,
+              )}%, ${locale.brightness} ${Math.round(hsb.b * 100)}%`,
+              min: 0,
+              max: 100,
+              value: hsb.s * 100,
+              onChange: percent => changeColor('s', percent),
+              onChangeComplete: () => onChangeComplete?.(colorRef.current),
+            }}
+            y={{
+              min: 0,
+              max: 100,
+              value: hsb.b * 100,
+              onChange: percent => changeColor('b', percent),
+              onChangeComplete: () => onChangeComplete?.(colorRef.current),
+            }}
+          />
         </Transform>
         <div
           className={`${prefixCls}-saturation`}

src/components/Slider.tsx

@@ -22,6 +22,7 @@ export interface BaseSliderProps {
   onChangeComplete: (value: number) => void;
   type: HsbaColorType;
   color: Color;
+  'aria-label'?: string;
 }
 
 const Slider: React.FC<BaseSliderProps> = props => {
@@ -33,6 +34,10 @@ const Slider: React.FC<BaseSliderProps> = props => {
     onChangeComplete,
     color,
     type,
+    min,
+    max,
+    value,
+    'aria-label': ariaLabel,
   } = props;
 
   const sliderRef = useRef<HTMLDivElement>(null);
@@ -103,6 +108,15 @@ const Slider: React.FC<BaseSliderProps> = props => {
             size="small"
             color={handleColor.toHexString()}
             prefixCls={prefixCls}
+            disabled={disabled}
+            x={{
+              'aria-label': ariaLabel,
+              min,
+              max,
+              value,
+              onChange,
+              onChangeComplete,
+            }}
           />
         </Transform>
         <Gradient colors={gradientList} type={type} prefixCls={prefixCls} />

src/interface.ts

@@ -40,6 +40,14 @@ export interface BaseColorPickerProps {
   color?: Color;
   prefixCls?: string;
   disabled?: boolean;
+  locale?: {
+    picker?: string;
+    pickerDescription?: string;
+    hue?: string;
+    alpha?: string;
+    saturation?: string;
+    brightness?: string;
+  };
   onChange?: (
     color: Color,
     info?: { type?: HsbaColorType; value?: number },