From d48e9d88ea97568e5bf9b78ea6e3b051b1403322 Mon Sep 17 00:00:00 2001
From: Cory Dransfeldt <cdransfeldt@adobe.com>
Date: Fri, 1 Aug 2025 16:33:37 -0700
Subject: [PATCH] docs(avatar): update a11y docs

---
 packages/avatar/README.md | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/packages/avatar/README.md b/packages/avatar/README.md
index 649fd9b1a2f..fcb39c19e2b 100644
--- a/packages/avatar/README.md
+++ b/packages/avatar/README.md
@@ -1,6 +1,8 @@
-## Description
+## Overview
 
-An `<sp-avatar>` is a great way to feature a visual representation of a user.
+An `<sp-avatar>` is a thumbnail representation of an entity, such as a user or an organization. Avatars can have a defined image, which is usually uploaded by a user.
+
+[View the design documentation for this component.](https://spectrum.adobe.com/page/avatar/)
 
 ### Usage
 
@@ -8,23 +10,27 @@ An `<sp-avatar>` is a great way to feature a visual representation of a user.
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/avatar?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/avatar)
 [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-swzc3ix8)
 
-```
+```zsh
 yarn add @spectrum-web-components/avatar
 ```
 
 Import the side effectful registration of `<sp-avatar>` via:
 
-```
+```js
 import '@spectrum-web-components/avatar/sp-avatar.js';
 ```
 
 When looking to leverage the `Avatar` base class as a type and/or for extension purposes, do so via:
 
-```
+```js
 import { Avatar } from '@spectrum-web-components/avatar';
 ```
 
-## Sizes
+### Options
+
+#### Sizes
+
+Avatar sizes scale exponentially, based on the Spectrum type scale. These range from `size-50` to `size-700`. An avatar can also be customized to fit appropriately for your context. The default size is `size-100`.
 
 <sp-tabs selected="100" auto label="Size Attribute Options">
 <sp-tab value="50">50</sp-tab>
@@ -137,6 +143,16 @@ import { Avatar } from '@spectrum-web-components/avatar';
 </sp-tab-panel>
 </sp-tabs>
 
-## Accessibility
+### States
+
+#### Generic avatars
+
+Use branded generic avatars when a user has not set their avatar image. These images are designed to be abstracted from all genders, locales, and cultures.
+
+#### Disabled
+
+An avatar in a disabled state shows that an avatar exists, but is not available or a user is not active in that circumstance. This can be used to maintain layout continuity and communicate that an avatar may become available or active later.
+
+### Accessibility
 
 The `label` attribute of the `<sp-avatar>` will be passed into the `<img>` element as the `alt` tag for use in defining a textual representation of the image displayed.