Avatar: Add srcTransformer and statusIcon props

[liuliu-dev]

Closes https://github.com/github/core-ux/issues/2493

Adds two new props to Avatar that close gaps identified in the Primer audit, eliminating the need for the @github-ui/github-avatar and @github-ui/status-avatar wrapper packages:

• srcTransformer — (src: string, size: number) => string, transforms the image URL before rendering (e.g. appending ?size= for HiDPI support)
• statusIcon — React.ReactNode, renders an overlay positioned at the bottom-right of the avatar

Changelog

New

• Avatar: srcTransformer prop to transform image URLs before rendering
• Avatar: statusIcon slot to render a status icon overlay
  

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 06aa69a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

[github-actions]

Uh oh! @liuliu-dev, at least one image you shared is missing helpful alt text. Check your pull request body to fix the following violations:

• Images should have meaningful alternative text (alt text) at line 16

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

[primer-integration]

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/21389

[Copilot]

Pull request overview

Adds two new customization hooks to Avatar (srcTransformer and statusIcon) to remove the need for external wrapper components, along with supporting styles, tests, Storybook coverage, docs metadata, and a minor-version changeset.

Changes:

• Added srcTransformer prop to allow transforming the resolved image URL prior to render.
• Added statusIcon prop to render a bottom-right overlay icon via a new wrapper/container structure.
• Added CSS, unit tests, Storybook stories, docs.json entries, and a minor changeset for the new API.

Show a summary per file

File	Description
packages/react/src/Avatar/Avatar.tsx	Adds srcTransformer support and conditionally wraps the <img> to render statusIcon.
packages/react/src/Avatar/Avatar.test.tsx	Adds unit tests validating srcTransformer behavior and statusIcon rendering/ref forwarding.
packages/react/src/Avatar/Avatar.module.css	Introduces container + overlay styles for the status icon.
packages/react/src/Avatar/Avatar.features.stories.tsx	Adds Storybook examples for srcTransformer and statusIcon.
packages/react/src/Avatar/Avatar.docs.json	Registers the new feature stories and documents the new props.
.changeset/clear-groups-cross.md	Declares a minor release for the new Avatar props.

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[liuliu-dev]

The style prop applies to the <img> not the container

[primer-integration]

Integration test results from github/github-ui:

  CI Passed
  VRT Passed
  Projects Passed

All checks passed!

[joshblack]

I think the audit might need a pass before we take a stab at implementing things in it, there were some things that stood out as strange when going over it 🤔

I think this PR has one example of this with srcTransformer. I'm not sure why it made that suggestion as, if we implement this, they would still need the component downstream to use this prop for the behavior they have. If we want to replace the component itself, we would have to emulate that (e.g. how they compute avatarUrl)

This is similar with statusIcon since they would still have the downstream package because hover cards are built into it that one.

[liuliu-dev]

@joshblack thanks for taking a look! yeah I was uncertain when working on the srcTransformer change, since it won't actually allow us to delete the package. The 235 sites would still need something to pass the transformer. I thought of making the image size doubling the default behavior (like GitHubAvatar does), but worried that it wouldn't work for people outside GitHub using Primer.

Same with statusIcon, I didn't notice the hovercard in that package, thanks for calling that out!

I think closing might be the right call, what do you think?