refactor: Create improved avatar docs

Author: pawelgrimm

src/avatar/avatar.mdx

@@ -0,0 +1,89 @@
+import { ArgTypes, Canvas, Description, Meta, Subtitle, Title } from '@storybook/addon-docs/blocks'
+
+import { Avatar } from './avatar'
+
+import * as AvatarStories from './avatar.stories'
+
+<Meta of={AvatarStories} />
+
+<Title />
+
+<Subtitle>Image, initials, and empty-state avatar primitive.</Subtitle>
+
+## Basic usage
+
+Use `Avatar` for people by default. Pass `size`, `name`, and an optional
+`image`; `name` supplies the default accessible label, the initials fallback,
+and the deterministic meta color used when initials render.
+
+<Canvas of={AvatarStories.Default} />
+
+## Initials fallback
+
+When `image` is not supplied, cannot be resolved, or every responsive image
+candidate fails, Avatar falls back to initials derived from `name`. Names are
+normalized before initials are generated.
+
+<Canvas of={AvatarStories.InitialsFallback} />
+
+## Workspace avatars
+
+Use `shape="rounded"` for workspace-like entities. Product code can wrap
+Avatar with a small convention component when a surface always represents the
+same kind of entity.
+
+<Canvas of={AvatarStories.WorkspaceAvatar} />
+
+## Image sources
+
+Pass a string for a single image URL, or a source map keyed by intrinsic image
+width. Source maps render native `srcSet` width descriptors and a `sizes` hint
+based on the selected avatar size.
+
+<Canvas of={AvatarStories.ImageSources} />
+
+## Sizes
+
+Avatar supports a fixed set of CSS pixel sizes. Use one of the supported
+numeric values instead of styling the avatar dimensions from the outside.
+
+<Canvas of={AvatarStories.Sizes} />
+
+## Accessibility
+
+Images default to `name` for alt text. Pass `alt` when the visual needs a more
+specific label, and pass `alt=""` when the avatar is decorative.
+
+<Canvas of={AvatarStories.Accessibility} />
+
+## Playground
+
+Use the controls to inspect the component API and common image/name
+combinations.
+
+<Canvas of={AvatarStories.Playground} />
+
+## API
+
+### `<Avatar />`
+
+<Description of={Avatar} />
+<ArgTypes of={Avatar} />
+
+## What the consumer owns
+
+- **Identity data** — choose the `name`, `image`, and any custom `alt` text.
+- **Source selection** — provide either one URL or a width-keyed source map.
+- **Entity convention** — choose `shape="circle"` for people and
+  `shape="rounded"` for workspace-like entities.
+- **Decorative usage** — pass `alt=""` when surrounding UI already names the
+  represented entity.
+- **Persistence and fetching** — Avatar does not load, cache, or persist remote
+  user/workspace data.
+
+## Accessibility
+
+- `name` becomes the default image `alt` text and initials `aria-label`.
+- `alt` overrides the accessible label for both image and initials rendering.
+- `alt=""` marks image and initials avatars as decorative.
+- An avatar with no `name` and no `image` renders as an empty decorative visual.