Deprecate AvatarPair component - move to @primer/react/deprecated while maintaining backward compatibility (#6468)

Copilot · pksjce · jonrohan · web-flow · commit 1f531cb5c0fb · 2025-08-12T16:39:46.000Z
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: pksjce &lt;417268+pksjce@users.noreply.github.com&gt;
Co-authored-by: Pavithra Kodmad &lt;pksjce@github.com&gt;
Co-authored-by: Jon Rohan &lt;yes@jonrohan.codes&gt;
diff --git a/.changeset/metal-lamps-appear.md b/.changeset/metal-lamps-appear.md
@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Deprecate AvatarPair component - move to @primer/react/deprecated
diff --git a/e2e/components/AvatarPair.test.ts b/e2e/components/AvatarPair.test.ts
diff --git a/e2e/components/Skeletons.test.ts b/e2e/components/Skeletons.test.ts
@@ -13,11 +13,7 @@ const stories = [
     id: 'components-skeleton-skeletonavatar-features--in-a-stack',
     disableAnimations: true,
   },
-  {
-    title: 'SkeletonAvatar In An Avatar Pair',
-    id: 'components-skeleton-skeletonavatar-features--in-an-avatar-pair',
-    disableAnimations: true,
-  },
+
   {
     title: 'SkeletonAvatar Size',
     id: 'components-skeleton-skeletonavatar-features--size',
diff --git a/packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.json b/packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.json
@@ -18,9 +18,6 @@
     },
     {
       "id": "components-skeleton-skeletonavatar-features--in-a-stack"
-    },
-    {
-      "id": "components-skeleton-skeletonavatar-features--in-an-avatar-pair"
     }
   ],
   "importPath": "@primer/react/experimental",
diff --git a/packages/react/src/SkeletonAvatar/SkeletonAvatar.features.stories.tsx b/packages/react/src/SkeletonAvatar/SkeletonAvatar.features.stories.tsx
@@ -2,7 +2,6 @@ import type {Meta} from '@storybook/react-vite'
 import type {ComponentProps} from '../utils/types'
 import {SkeletonAvatar} from './SkeletonAvatar'
 import AvatarStack from '../AvatarStack'
-import AvatarPair from '../AvatarPair'
 
 export default {
   title: 'Components/Skeleton/SkeletonAvatar/Features',
@@ -51,10 +50,3 @@ export const InAStack = () => (
     <SkeletonAvatar />
   </AvatarStack>
 )
-
-export const InAnAvatarPair = () => (
-  <AvatarPair>
-    <SkeletonAvatar />
-    <SkeletonAvatar />
-  </AvatarPair>
-)
diff --git a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -232,6 +232,8 @@ exports[`@primer/react/deprecated > should not update exports without a semver c
   "type ActionListProps",
   "ActionMenu",
   "type ActionMenuProps",
+  "AvatarPair",
+  "type AvatarPairProps",
   "Dialog",
   "type DialogHeaderProps",
   "type DialogProps",
diff --git a/packages/react/src/__tests__/storybook.test.tsx b/packages/react/src/__tests__/storybook.test.tsx
@@ -15,7 +15,6 @@ const allowlist = [
   'Autocomplete',
   'Avatar',
   'AvatarStack',
-  'AvatarPair',
   'Breadcrumbs',
   'BranchName',
   'Blankslate',
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.docs.json b/packages/react/src/deprecated/AvatarPair/AvatarPair.docs.json
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.features.stories.tsx b/packages/react/src/deprecated/AvatarPair/AvatarPair.features.stories.tsx
@@ -1,6 +1,6 @@
 import type {Meta} from '@storybook/react-vite'
 import AvatarPair from './AvatarPair'
-import Avatar from '../Avatar'
+import Avatar from '../../Avatar'
 
 export default {
   title: 'Components/AvatarPair/Features',
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.figma.tsx b/packages/react/src/deprecated/AvatarPair/AvatarPair.figma.tsx
@@ -1,4 +1,4 @@
-import {AvatarPair} from '../../src'
+import AvatarPair from './AvatarPair'
 import figma from '@figma/code-connect'
 
 figma.connect(AvatarPair, 'https://www.figma.com/design/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=13006-42855', {
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.module.css b/packages/react/src/deprecated/AvatarPair/AvatarPair.module.css
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.stories.tsx b/packages/react/src/deprecated/AvatarPair/AvatarPair.stories.tsx
@@ -1,6 +1,6 @@
 import type {Meta} from '@storybook/react-vite'
 import AvatarPair from './AvatarPair'
-import Avatar from '../Avatar'
+import Avatar from '../../Avatar'
 
 export default {
   title: 'Components/AvatarPair',
diff --git a/packages/react/src/deprecated/AvatarPair/AvatarPair.tsx b/packages/react/src/deprecated/AvatarPair/AvatarPair.tsx
@@ -1,12 +1,18 @@
 import React, {type HTMLProps} from 'react'
-import type {AvatarProps} from '../Avatar'
-import Avatar from '../Avatar'
-import {SkeletonAvatar} from '../SkeletonAvatar'
+import type {AvatarProps} from '../../Avatar'
+import Avatar from '../../Avatar'
+import {SkeletonAvatar} from '../../SkeletonAvatar'
 import classes from './AvatarPair.module.css'
 import {clsx} from 'clsx'
 
+/**
+ * @deprecated AvatarPair is deprecated. Please see https://github.com/github/primer/issues/5533 for migration guidance.
+ */
 export type AvatarPairProps = HTMLProps<HTMLDivElement>
 
+/**
+ * @deprecated AvatarPair is deprecated. Please see https://github.com/github/primer/issues/5533 for migration guidance.
+ */
 const AvatarPair = ({children, className, ...rest}: AvatarPairProps) => {
   const avatars = React.Children.map(children, (child, i) => {
     if (!React.isValidElement(child)) {
diff --git a/packages/react/src/deprecated/AvatarPair/index.ts b/packages/react/src/deprecated/AvatarPair/index.ts
diff --git a/packages/react/src/deprecated/index.ts b/packages/react/src/deprecated/index.ts
@@ -42,3 +42,8 @@ export type {TabNavProps, TabNavLinkProps} from '../TabNav'
 export {default as Tooltip} from '../Tooltip/Tooltip'
 export type {TooltipProps} from '../Tooltip/Tooltip'
 // end of v37.0.0
+
+// Deprecated in v37.31.0 - https://github.com/github/primer/issues/5533
+export {default as AvatarPair} from './AvatarPair'
+export type {AvatarPairProps} from './AvatarPair'
+// end of v37.31.0
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
@@ -72,10 +72,11 @@ export {default as Autocomplete} from './Autocomplete'
 export type {AutocompleteMenuProps, AutocompleteInputProps, AutocompleteOverlayProps} from './Autocomplete'
 export {default as Avatar} from './Avatar'
 export type {AvatarProps} from './Avatar'
-export {default as AvatarPair} from './AvatarPair'
-export type {AvatarPairProps} from './AvatarPair'
 export {default as AvatarStack} from './AvatarStack'
 export type {AvatarStackProps} from './AvatarStack'
+// AvatarPair is deprecated. Use Avatar component instead. See https://github.com/github/primer/issues/5533
+export {default as AvatarPair} from './deprecated/AvatarPair'
+export type {AvatarPairProps} from './deprecated/AvatarPair'
 export {default as BranchName} from './BranchName'
 export type {BranchNameProps} from './BranchName'
 export {default as Breadcrumbs, Breadcrumb} from './Breadcrumbs'
diff --git a/script/generate-e2e-tests.js b/script/generate-e2e-tests.js
@@ -184,25 +184,7 @@ const components = new Map([
       ],
     },
   ],
-  [
-    'AvatarPair',
-    {
-      stories: [
-        {
-          id: 'components-avatarpair--default',
-          name: 'Default',
-        },
-        {
-          id: 'components-avatarpair-features--parent-circle',
-          name: 'Parent Circle',
-        },
-        {
-          id: 'components-avatarpair-features--parent-square',
-          name: 'Parent Square',
-        },
-      ],
-    },
-  ],
+
   [
     'BranchName',
     {

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@primer/react": minor
 +---
++
 +Deprecate AvatarPair component - move to @primer/react/deprecated
Original file line number	Diff line number	Diff line change
`@@ -18,9 +18,6 @@`
`18`	`18`	`},`
`19`	`19`	`{`
`20`	`20`	`"id": "components-skeleton-skeletonavatar-features--in-a-stack"`
`21`		`- },`
`22`		`- {`
`23`		`- "id": "components-skeleton-skeletonavatar-features--in-an-avatar-pair"`
`24`	`21`	`}`
`25`	`22`	`],`
`26`	`23`	`"importPath": "@primer/react/experimental",`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import {AvatarPair} from '../../src'`
	`1`	`+import AvatarPair from './AvatarPair'`
`2`	`2`	`import figma from '@figma/code-connect'`
`3`	`3`
`4`	`4`	`figma.connect(AvatarPair, 'https://www.figma.com/design/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=13006-42855', {`