@cdx-ui/components 0.0.1-beta.8 → 0.0.1-beta.80

package/src/components/Checkbox/index.tsx

@@ -1,11 +1,18 @@
 import { forwardRef, type ReactNode } from 'react';
-import { Pressable, Text, type TextProps, View, type ViewProps } from 'react-native';
+import { Text, View, type TextProps, type ViewProps } from 'react-native';
 import { Check, CheckIndeterminateSmall } from '@cdx-ui/icons';
-import { createCheckbox, type ICheckboxProps } from '@cdx-ui/primitives';
-import { cn, useStyleContext, withStyleContext } from '@cdx-ui/utils';
+import {
+  CheckboxRoot as CheckboxRootPrimitive,
+  CheckboxGroup as CheckboxGroupPrimitive,
+  Slot,
+  dataAttributes,
+  mergeDataAttributes,
+  useCheckboxContext,
+  type ICheckboxProps,
+} from '@cdx-ui/primitives';
+import { cn } from '@cdx-ui/utils';
 import { Icon, IconProps } from '../Icon';
 import {
-  type CheckboxVariantProps,
   checkboxGroupVariants,
   checkboxIconVariants,
   checkboxIndicatorVariants,
@@ -13,49 +20,33 @@ import {
   checkboxRootVariants,
 } from './styles';
 
-const SCOPE = 'CHECKBOX';
-
-const Root = withStyleContext(Pressable, SCOPE);
-
-const useCheckboxStyleContext = () => useStyleContext(SCOPE) as CheckboxVariantProps;
-
-const CheckboxPrimitive = createCheckbox({
-  Root,
-  Indicator: View,
-  Icon: View,
-  Label: Text,
-  Group: View,
-});
-
 // =============================================================================
 // CHECKBOX ROOT
 // =============================================================================
 
-export interface CheckboxProps extends ICheckboxProps, CheckboxVariantProps {
+export interface CheckboxProps extends ICheckboxProps {
   className?: string;
   children?: ReactNode;
 }
 
 const CheckboxRoot = forwardRef<View, CheckboxProps>(
-  ({ size = 'default', className, isIndeterminate, children, style, ...props }, ref) => {
-    const computedClassName = cn(checkboxRootVariants({ size }), className);
+  ({ className, isIndeterminate, children, style, ...props }, ref) => {
+    const computedClassName = cn(checkboxRootVariants(), className);
 
     return (
-      <CheckboxPrimitive
+      <CheckboxRootPrimitive
         ref={ref as any}
         className={computedClassName}
         isIndeterminate={isIndeterminate}
         style={style}
-        context={{ size }}
         {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'checkbox' }))}
       >
         <CheckboxIndicator>
-          <CheckboxPrimitive.Icon>
-            <CheckboxIcon as={isIndeterminate ? CheckIndeterminateSmall : Check} />
-          </CheckboxPrimitive.Icon>
+          <CheckboxIconSlot isIndeterminate={isIndeterminate} />
         </CheckboxIndicator>
         {children}
-      </CheckboxPrimitive>
+      </CheckboxRootPrimitive>
     );
   },
 );
@@ -63,28 +54,56 @@ const CheckboxRoot = forwardRef<View, CheckboxProps>(
 CheckboxRoot.displayName = 'Checkbox';
 
 // =============================================================================
-// CHECKBOX INDICATOR
+// CHECKBOX INDICATOR (styled-only, reads context for data-* styling)
 // =============================================================================
 
 export interface CheckboxIndicatorProps extends ViewProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CheckboxIndicator = forwardRef<View, CheckboxIndicatorProps>(
-  ({ className, children, style, ...props }, ref) => {
-    const { size } = useCheckboxStyleContext();
-    const computedClassName = cn(checkboxIndicatorVariants({ size }), className);
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const {
+      isChecked,
+      isDisabled,
+      isHovered,
+      isInvalid,
+      isReadOnly,
+      isPressed,
+      isFocused,
+      isIndeterminate,
+      isFocusVisible,
+    } = useCheckboxContext();
+
+    const computedClassName = cn(checkboxIndicatorVariants(), className);
+    const Comp = asChild ? Slot : View;
 
     return (
-      <CheckboxPrimitive.Indicator
-        ref={ref as any}
+      <Comp
+        ref={ref}
         className={computedClassName}
         style={style}
         {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({
+            slot: 'checkbox-indicator',
+            hover: isHovered,
+            checked: isChecked,
+            disabled: isDisabled,
+            focusVisible: isFocusVisible,
+            invalid: isInvalid,
+            readonly: isReadOnly,
+            active: isPressed,
+            focused: isFocused,
+            indeterminate: isIndeterminate,
+          }),
+        )}
       >
         {children}
-      </CheckboxPrimitive.Indicator>
+      </Comp>
     );
   },
 );
@@ -92,43 +111,74 @@ const CheckboxIndicator = forwardRef<View, CheckboxIndicatorProps>(
 CheckboxIndicator.displayName = 'Checkbox.Indicator';
 
 // =============================================================================
-// CHECKBOX ICON
+// CHECKBOX ICON (styled-only, reads context for conditional mount)
 // =============================================================================
 
 export interface CheckboxIconProps extends Omit<IconProps, 'children'> {}
 
 const CheckboxIcon = ({ className, style, ...props }: CheckboxIconProps) => {
-  const { size } = useCheckboxStyleContext();
-  const computedClassName = cn(checkboxIconVariants({ size }), className);
-
-  return <Icon className={computedClassName} style={style} {...props} />;
+  const computedClassName = cn(checkboxIconVariants(), className);
+
+  return (
+    <Icon
+      className={computedClassName}
+      style={style}
+      {...props}
+      {...mergeDataAttributes(props, dataAttributes({ slot: 'checkbox-icon' }))}
+    />
+  );
 };
 
 CheckboxIcon.displayName = 'Checkbox.Icon';
 
+// Internal helper that reads context for conditional rendering
+const CheckboxIconSlot = ({
+  isIndeterminate: isIndeterminateProp,
+}: {
+  isIndeterminate?: boolean;
+}) => {
+  const { isChecked, isIndeterminate } = useCheckboxContext();
+  const showIcon = isChecked || isIndeterminateProp || isIndeterminate;
+
+  if (!showIcon) return null;
+
+  return (
+    <CheckboxIcon as={isIndeterminate || isIndeterminateProp ? CheckIndeterminateSmall : Check} />
+  );
+};
+
 // =============================================================================
-// CHECKBOX LABEL
+// CHECKBOX LABEL (styled-only)
 // =============================================================================
 
 export interface CheckboxLabelProps extends TextProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CheckboxLabel = forwardRef<Text, CheckboxLabelProps>(
-  ({ className, children, style, ...props }, ref) => {
-    const { size } = useCheckboxStyleContext();
-    const computedClassName = cn(checkboxLabelVariants({ size }), className);
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const { isDisabled } = useCheckboxContext();
+    const computedClassName = cn(checkboxLabelVariants(), className);
+    const Comp = asChild ? Slot : Text;
 
     return (
-      <CheckboxPrimitive.Label
-        ref={ref as any}
+      <Comp
+        ref={ref}
         className={computedClassName}
         style={style}
         {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({
+            slot: 'checkbox-label',
+            disabled: isDisabled,
+          }),
+        )}
       >
         {children}
-      </CheckboxPrimitive.Label>
+      </Comp>
     );
   },
 );
@@ -136,7 +186,7 @@ const CheckboxLabel = forwardRef<Text, CheckboxLabelProps>(
 CheckboxLabel.displayName = 'Checkbox.Label';
 
 // =============================================================================
-// CHECKBOX GROUP
+// CHECKBOX GROUP (wraps the primitive)
 // =============================================================================
 
 export interface CheckboxGroupProps extends ViewProps {
@@ -169,8 +219,8 @@ const CheckboxGroup = forwardRef<View, CheckboxGroupProps>(
     const computedClassName = cn(checkboxGroupVariants({ direction }), className);
 
     return (
-      <CheckboxPrimitive.Group
-        ref={ref as any}
+      <CheckboxGroupPrimitive
+        ref={ref}
         className={computedClassName}
         style={style}
         value={value ?? []}
@@ -178,10 +228,10 @@ const CheckboxGroup = forwardRef<View, CheckboxGroupProps>(
         isDisabled={isDisabled}
         isInvalid={isInvalid}
         isReadOnly={isReadOnly}
-        {...viewProps}
+        {...mergeDataAttributes(viewProps, dataAttributes({ slot: 'checkbox-group' }))}
       >
         {children}
-      </CheckboxPrimitive.Group>
+      </CheckboxGroupPrimitive>
     );
   },
 );

package/src/components/Checkbox/styles.ts

@@ -1,92 +1,92 @@
 import { Platform } from 'react-native';
-import { cva, type VariantProps } from 'class-variance-authority';
-import {
-  COLOR_BG_PRIMARY,
-  COLOR_BORDER_STRONG,
-  COLOR_TEXT_PRIMARY,
-  DISABLED_CURSOR,
-  DISABLED_OPACITY,
-  TRANSITION_COLORS,
-} from '../../styles/primitives';
+import { cva } from 'class-variance-authority';
+import { DISABLED_CURSOR, DISABLED_OPACITY, TRANSITION_COLORS } from '../../styles/primitives';
 
-export const checkboxRootVariants = cva(
-  ['flex-row items-center', DISABLED_OPACITY, DISABLED_CURSOR],
-  {
-    variants: {
-      size: {
-        small: 'gap-2',
-        default: 'gap-2.5',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+// TODO: Handle text wrapping in the label
 
-export const checkboxIndicatorVariants = cva(
-  [
-    'items-center justify-center',
-    'rounded',
-    'border-2',
-    COLOR_BORDER_STRONG,
-    COLOR_BG_PRIMARY,
-    'data-[checked=true]:bg-slate-900 data-[checked=true]:border-slate-900',
-    'data-[indeterminate=true]:bg-slate-900 data-[indeterminate=true]:border-slate-900',
-    'data-[disabled=true]:opacity-50',
-    'data-[invalid=true]:border-red-500',
-    'data-[checked=true]:data-[invalid=true]:bg-red-500 data-[checked=true]:data-[invalid=true]:border-red-500',
-    'data-[indeterminate=true]:data-[invalid=true]:bg-red-500 data-[indeterminate=true]:data-[invalid=true]:border-red-500',
-    Platform.select({
-      web: [
-        TRANSITION_COLORS,
-        'data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:border-slate-400 data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:bg-slate-50',
-        'data-[focus-visible=true]:ring-2 data-[focus-visible=true]:ring-slate-400/50 data-[focus-visible=true]:ring-offset-2',
-        'data-[invalid=true]:data-[hover=true]:border-red-400',
-        'data-[invalid=true]:data-[focus-visible=true]:ring-red-400/50',
-      ].join(' '),
-      default: '',
-    }),
-  ],
-  {
-    variants: {
-      size: {
-        small: 'h-4 w-4',
-        default: 'h-5 w-5',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+export const checkboxRootVariants = cva([
+  'flex-row items-center gap-2.5',
+  DISABLED_OPACITY,
+  DISABLED_CURSOR,
+  // Suppress stray outline on the Pressable/label wrapper; focus ring is drawn on Checkbox.Indicator (Radio pattern).
+  'web:outline-none web:focus:outline-none web:focus-visible:outline-none',
+]);
 
-export const checkboxIconVariants = cva(['text-white'], {
-  variants: {
-    size: {
-      small: 'h-3 w-3',
-      default: 'h-3.5 w-3.5',
-    },
-  },
-  defaultVariants: {
-    size: 'default',
-  },
-});
+export const checkboxIndicatorVariants = cva([
+  'items-center justify-center',
+  'h-5 w-5',
+  'rounded',
+  'border-2 border-solid',
+  'data-[disabled=true]:opacity-50',
+  // Background — layered by specificity. checked=false acts as an explicit reset so the base bg
+  // reasserts when transitioning from checked/indeterminate on native (where absent attributes
+  // break data-[attr=false] selectors).
+  // IMPORTANT: On native (Uniwind), only the LAST data-[] condition in a compound chain is
+  // effectively evaluated. Place the most discriminating condition last to avoid false matches.
+  'data-[checked=false]:bg-surface-primary',
+  'data-[checked=true]:bg-surface-action-strong',
+  'data-[indeterminate=true]:bg-surface-action-strong',
+  // Border — invalid (later) beats checked/indeterminate.
+  'data-[checked=false]:border-content-secondary',
+  'data-[checked=true]:border-stroke-action',
+  'data-[indeterminate=true]:border-stroke-action',
+  'data-[invalid=true]:border-stroke-danger',
+  Platform.select({
+    web: [
+      // Invalid bg — compound selectors evaluate correctly on web.
+      'data-[invalid=true]:data-[checked=true]:bg-surface-danger-strong',
+      'data-[invalid=true]:data-[indeterminate=true]:bg-surface-danger-strong',
+      TRANSITION_COLORS,
+      // Hover — unchecked (Figma: border unchanged, bg overlay at opacity/hover)
+      'data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:bg-content-secondary/[0.08]',
+      // Hover — unchecked + invalid (overlay uses danger token)
+      'data-[hover=true]:data-[invalid=true]:data-[checked=false]:data-[indeterminate=false]:bg-surface-danger-strong/[0.08]',
+      // Hover — checked / indeterminate (bg + border darken together)
+      'data-[hover=true]:data-[checked=true]:bg-surface-action-strong-hover',
+      'data-[hover=true]:data-[checked=true]:border-[--color-surface-action-strong-hover]',
+      'data-[hover=true]:data-[indeterminate=true]:bg-surface-action-strong-hover',
+      'data-[hover=true]:data-[indeterminate=true]:border-[--color-surface-action-strong-hover]',
+      'data-[hover=true]:data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong-hover',
+      'data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-[--color-surface-danger-strong-hover]',
+      'data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:bg-surface-danger-strong-hover',
+      'data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-[--color-surface-danger-strong-hover]',
+      // Active — CSS :active pseudo-class (web root does not track press via data-active).
+      // data-[hover=true] guard ensures active beats hover by specificity (0,3,0 > 0,2,0).
+      'web:active:data-[hover=true]:data-[checked=true]:bg-surface-action-strong-active',
+      'web:active:data-[hover=true]:data-[checked=true]:border-[--color-surface-action-strong-active]',
+      'web:active:data-[hover=true]:data-[indeterminate=true]:bg-surface-action-strong-active',
+      'web:active:data-[hover=true]:data-[indeterminate=true]:border-[--color-surface-action-strong-active]',
+      'web:active:data-[hover=true]:data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong-active',
+      'web:active:data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-[--color-surface-danger-strong-active]',
+      'web:active:data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:bg-surface-danger-strong-active',
+      'web:active:data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-[--color-surface-danger-strong-active]',
+      // Focus ring
+      'web:data-[focus-visible=true]:outline-none',
+      'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-stroke-focus web:data-[focus-visible=true]:ring-offset-2',
+    ].join(' '),
+    default: [
+      // Invalid bg is NOT styled on native. Compound data-[] selectors cannot express
+      // "invalid AND checked" without false-matching other states (Uniwind only evaluates
+      // the last condition). Invalid state is communicated via border-stroke-danger (single
+      // condition, always correct). The fill stays action-strong for checked/indeterminate.
+      //
+      // Active — native tracks press via data-[active] from usePress.
+      // Place data-[active=true] last so the rule only fires during press.
+      // 'data-[checked=false]:data-[invalid=true]:bg-transparent',
+      'data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong',
+      'data-[checked=true]:data-[active=true]:bg-surface-action-strong-active',
+      'data-[checked=true]:data-[active=true]:data-[invalid=true]:bg-surface-danger-strong-active',
+      'data-[indeterminate=true]:data-[active=true]:bg-surface-action-strong-active',
+    ].join(' '),
+  }),
+]);
 
-export const checkboxLabelVariants = cva(
-  [COLOR_TEXT_PRIMARY, 'data-[disabled=true]:text-slate-400'],
-  {
-    variants: {
-      size: {
-        small: 'text-sm',
-        default: 'text-base',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+export const checkboxIconVariants = cva(['text-white', 'h-5 w-5']);
+
+export const checkboxLabelVariants = cva([
+  'text-content-primary text-base',
+  'data-[disabled=true]:text-content-tertiary',
+]);
 
 export const checkboxGroupVariants = cva([], {
   variants: {
@@ -99,5 +99,3 @@ export const checkboxGroupVariants = cva([], {
     direction: 'column',
   },
 });
-
-export type CheckboxVariantProps = VariantProps<typeof checkboxRootVariants>;

package/src/components/Chip/index.tsx

@@ -1,32 +1,62 @@
-import { forwardRef, type ReactNode } from 'react';
-import { View, Text as RNText, type ViewProps, type TextProps } from 'react-native';
-import { cn, useStyleContext, withStyleContext } from '@cdx-ui/utils';
+import { forwardRef, useMemo, type ReactNode } from 'react';
+import { Text, View, type TextProps } from 'react-native';
+import {
+  ChipRoot as ChipRootPrimitive,
+  Slot,
+  dataAttributes,
+  mergeDataAttributes,
+  type IChipProps,
+} from '@cdx-ui/primitives';
+import { cn, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
+import { Avatar, type AvatarProps } from '../Avatar';
 import { Icon, type IconProps } from '../Icon';
-import { chipRootVariants, chipLabelVariants, chipIconVariants, ChipVariants } from './styles';
+import { positionToDataIcon, type IconSlotPosition } from '../../utils/positionToDataIcon';
+import {
+  chipAvatarVariants,
+  chipIconVariants,
+  chipLabelVariants,
+  chipRootVariants,
+  type ChipVariantProps,
+} from './styles';
 
 const SCOPE = 'CHIP';
 
-const Root = withStyleContext(View, SCOPE);
-
-const useChipStyleContext = () => useStyleContext(SCOPE) as ChipVariants;
+const useChipStyleContext = () => useStyleContext(SCOPE) as ChipVariantProps;
 
 // =============================================================================
-// STYLED ROOT COMPONENT
+// ROOT
 // =============================================================================
 
-export interface ChipProps extends ViewProps, ChipVariants {
-  children?: ReactNode;
+export interface ChipProps extends IChipProps, ChipVariantProps {
   className?: string;
+  children?: ReactNode;
 }
 
 const ChipRoot = forwardRef<View, ChipProps>(
-  ({ children, color = 'default', className, style, ...props }, ref) => {
-    const computedClassName = cn(chipRootVariants({ color }), className);
+  (
+    { children, variant = 'tint', size = 'default', color = 'default', className, style, ...props },
+    ref,
+  ) => {
+    const parent = useParentContext();
+    const ctx = useMemo(
+      () => ({ ...parent, [SCOPE]: { variant, size, color } }),
+      [parent, variant, size, color],
+    );
+
+    const computedClassName = cn(chipRootVariants({ variant, size, color }), className);
 
     return (
-      <Root ref={ref} className={computedClassName} style={style} context={{ color }} {...props}>
-        {children}
-      </Root>
+      <ParentContext.Provider value={ctx}>
+        <ChipRootPrimitive
+          ref={ref}
+          className={computedClassName}
+          style={style}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'chip' }))}
+        >
+          {children}
+        </ChipRootPrimitive>
+      </ParentContext.Provider>
     );
   },
 );
@@ -34,24 +64,31 @@ const ChipRoot = forwardRef<View, ChipProps>(
 ChipRoot.displayName = 'Chip';
 
 // =============================================================================
-// STYLED LABEL COMPONENT
+// LABEL
 // =============================================================================
 
 export interface ChipLabelProps extends TextProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
-const ChipLabel = forwardRef<RNText, ChipLabelProps>(
-  ({ className, children, style, ...props }, ref) => {
-    const { color } = useChipStyleContext();
-
-    const computedClassName = cn(chipLabelVariants({ color }), className);
+const ChipLabel = forwardRef<Text, ChipLabelProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const { size, variant, color } = useChipStyleContext();
+    const computedClassName = cn(chipLabelVariants({ size, variant, color }), className);
+    const Comp = asChild ? Slot : Text;
 
     return (
-      <RNText ref={ref} className={computedClassName} style={style} {...props}>
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'chip-label' }))}
+      >
         {children}
-      </RNText>
+      </Comp>
     );
   },
 );
@@ -59,33 +96,100 @@ const ChipLabel = forwardRef<RNText, ChipLabelProps>(
 ChipLabel.displayName = 'Chip.Label';
 
 // =============================================================================
-// STYLED ICON COMPONENT
+// ICON
 // =============================================================================
 
-export interface ChipIconProps extends Omit<IconProps, 'children'> {}
-
-const ChipIcon = ({ className, style, as, ...props }: ChipIconProps) => {
-  const { color } = useChipStyleContext();
+export interface ChipIconProps extends Omit<IconProps, 'children' | 'as'> {
+  asChild?: boolean;
+  /**
+   * Forge icon component to render. Required unless `asChild` is set, in which
+   * case the consumer's substituted element is rendered instead.
+   */
+  as?: IconProps['as'];
+  /**
+   * Position hint that emits `data-icon="inline-start"` or `data-icon="inline-end"`.
+   * CVA uses this attribute to apply leading/trailing margin offsets logically
+   * (RTL-aware). Omit when the icon is freely positioned within a custom layout.
+   */
+  position?: IconSlotPosition;
+}
 
-  const computedClassName = cn(chipIconVariants({ color }), className);
+const ChipIcon = ({ asChild, className, style, as, position, ...props }: ChipIconProps) => {
+  const { size, color } = useChipStyleContext();
+  const computedClassName = cn(chipIconVariants({ size, color }), className);
 
-  return <Icon as={as} className={computedClassName} style={style} {...props} />;
+  if (asChild) {
+    return (
+      <Slot
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ slot: 'chip-icon' }),
+          positionToDataIcon(position),
+        )}
+      />
+    );
+  }
+
+  if (!as) {
+    return null;
+  }
+
+  return (
+    <Icon
+      as={as}
+      className={computedClassName}
+      style={style}
+      {...props}
+      {...mergeDataAttributes(
+        props,
+        dataAttributes({ slot: 'chip-icon' }),
+        positionToDataIcon(position),
+      )}
+    />
+  );
 };
 
 ChipIcon.displayName = 'Chip.Icon';
 
 // =============================================================================
-// COMPOUND COMPONENT EXPORT
+// AVATAR
+// =============================================================================
+
+export interface ChipAvatarProps extends Omit<AvatarProps, 'size'> {}
+
+const ChipAvatar = ({ className, style, children, ...props }: ChipAvatarProps) => {
+  const { size } = useChipStyleContext();
+  // chipAvatarVariants sets w/h and the leading-edge negative margin.
+  // Avatar renders with size="sm" (its smallest named size) but chipAvatarVariants
+  // overrides the w/h via tailwind-merge so the chip size wins.
+  const computedClassName = cn(chipAvatarVariants({ size }), className);
+
+  return (
+    <Avatar size="sm" className={computedClassName} style={style} {...props}>
+      {children}
+    </Avatar>
+  );
+};
+
+ChipAvatar.displayName = 'Chip.Avatar';
+
+// =============================================================================
+// COMPOUND EXPORT
 // =============================================================================
 
 type ChipCompoundComponent = typeof ChipRoot & {
   Label: typeof ChipLabel;
   Icon: typeof ChipIcon;
+  Avatar: typeof ChipAvatar;
 };
 
 export const Chip = Object.assign(ChipRoot, {
   Label: ChipLabel,
   Icon: ChipIcon,
+  Avatar: ChipAvatar,
 }) as ChipCompoundComponent;
 
-export { type ChipVariants } from './styles';
+export { type ChipVariantProps } from './styles';