From 378fa2908deea71dbc81949105395f2787b10b7f Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Mon, 14 Apr 2025 17:18:59 +0200
Subject: [PATCH] Add Avatar docs

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/app/(docs)/components/avatar/page.mdx | 75 +++++++++++++++++++
 .../src/app/(docs)/components/avatar/props.ts | 19 +++++
 canon-docs/src/snippets/stories-snippets.tsx  | 12 +++
 canon-docs/src/utils/data.ts                  |  5 ++
 4 files changed, 111 insertions(+)
 create mode 100644 canon-docs/src/app/(docs)/components/avatar/page.mdx
 create mode 100644 canon-docs/src/app/(docs)/components/avatar/props.ts

diff --git a/canon-docs/src/app/(docs)/components/avatar/page.mdx b/canon-docs/src/app/(docs)/components/avatar/page.mdx
new file mode 100644
index 0000000000..b46caf8d62
--- /dev/null
+++ b/canon-docs/src/app/(docs)/components/avatar/page.mdx
@@ -0,0 +1,75 @@
+import { PropsTable } from '@/components/PropsTable';
+import { Snippet } from '@/components/Snippet';
+import { Tabs } from '@/components/Tabs';
+import { CodeBlock } from '@/components/CodeBlock';
+import { AvatarSnippet } from '@/snippets/stories-snippets';
+import { avatarPropDefs } from './props';
+
+# Avatar
+
+An avatar component with a fallback for initials.
+
+<Snippet
+  align="center"
+  py={4}
+  preview={<AvatarSnippet story="Default" />}
+  code={`<Avatar src="https://avatars.githubusercontent.com/u/1540635?v=4" name="Charles de Dreuille" />`}
+/>
+
+<Tabs.Root>
+  <Tabs.List>
+    <Tabs.Tab>Usage</Tabs.Tab>
+    <Tabs.Tab>Theming</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel>
+    <CodeBlock
+      code={`import { Avatar } from '@backstage/canon';
+
+<Avatar src="https://avatars.githubusercontent.com/u/1540635?v=4" name="Charles de Dreuille" />`}
+    />
+  </Tabs.Panel>
+  <Tabs.Panel>
+    We recommend starting with our [global tokens](/theme/theming) to customize the library and align it with
+    your brand. For additional flexibility, you can use the provided class names for each element listed below.
+    - `canon-AvatarRoot`
+    - `canon-AvatarRoot[data-size='small']`
+    - `canon-AvatarRoot[data-size='medium']`
+    - `canon-AvatarRoot[data-size='large']`
+    - `canon-AvatarImage`
+    - `canon-AvatarFallback`
+  </Tabs.Panel>
+</Tabs.Root>
+
+## API reference
+
+<PropsTable data={avatarPropDefs} />
+
+## Examples
+
+### Sizes
+
+Avatar sizes can be set using the `size` prop.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<AvatarSnippet story="Sizes" />}
+  code={`<Flex gap="4" direction="column">
+    <Avatar src="https://avatars.githubusercontent.com/u/1540635?v=4" name="Charles de Dreuille" size="small" />
+    <Avatar src="https://avatars.githubusercontent.com/u/1540635?v=4" name="Charles de Dreuille" size="medium" />
+    <Avatar src="https://avatars.githubusercontent.com/u/1540635?v=4" name="Charles de Dreuille" size="large" />
+  </Flex>`}
+/>
+
+### Fallback
+
+If the image is not available, the avatar will show the initials of the name.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<AvatarSnippet story="Fallback" />}
+  code={`<Avatar src="https://avatars.githubusercontent.com/u/15406AAAAAAAAA" name="Charles de Dreuille" />`}
+/>
diff --git a/canon-docs/src/app/(docs)/components/avatar/props.ts b/canon-docs/src/app/(docs)/components/avatar/props.ts
new file mode 100644
index 0000000000..e86c67a41e
--- /dev/null
+++ b/canon-docs/src/app/(docs)/components/avatar/props.ts
@@ -0,0 +1,19 @@
+import { classNamePropDefs, stylePropDefs } from '@/utils/propDefs';
+import type { PropDef } from '@/utils/propDefs';
+
+export const avatarPropDefs: Record<string, PropDef> = {
+  src: {
+    type: 'string',
+  },
+  name: {
+    type: 'string',
+  },
+  size: {
+    type: 'enum',
+    values: ['small', 'medium', 'large'],
+    default: 'medium',
+    responsive: true,
+  },
+  ...classNamePropDefs,
+  ...stylePropDefs,
+};
diff --git a/canon-docs/src/snippets/stories-snippets.tsx b/canon-docs/src/snippets/stories-snippets.tsx
index 6b54f5dc4d..83cc866050 100644
--- a/canon-docs/src/snippets/stories-snippets.tsx
+++ b/canon-docs/src/snippets/stories-snippets.tsx
@@ -15,6 +15,7 @@ import * as FlexStories from '../../../packages/canon/src/components/Flex/Flex.s
 import * as SelectStories from '../../../packages/canon/src/components/Select/Select.stories';
 import * as MenuStories from '../../../packages/canon/src/components/Menu/Menu.stories';
 import * as LinkStories from '../../../packages/canon/src/components/Link/Link.stories';
+import * as AvatarStories from '../../../packages/canon/src/components/Avatar/Avatar.stories';
 
 export const BoxSnippet = ({ story }: { story: keyof typeof BoxStories }) => {
   const stories = composeStories(BoxStories);
@@ -141,3 +142,14 @@ export const LinkSnippet = ({ story }: { story: keyof typeof LinkStories }) => {
 
   return StoryComponent ? <StoryComponent /> : null;
 };
+
+export const AvatarSnippet = ({
+  story,
+}: {
+  story: keyof typeof AvatarStories;
+}) => {
+  const stories = composeStories(AvatarStories);
+  const StoryComponent = stories[story as keyof typeof stories];
+
+  return StoryComponent ? <StoryComponent /> : null;
+};
diff --git a/canon-docs/src/utils/data.ts b/canon-docs/src/utils/data.ts
index 48274ea1a2..d1e9277e57 100644
--- a/canon-docs/src/utils/data.ts
+++ b/canon-docs/src/utils/data.ts
@@ -66,6 +66,11 @@ export const layoutComponents: Page[] = [
 ];
 
 export const components: Page[] = [
+  {
+    title: 'Avatar',
+    slug: 'avatar',
+    status: 'alpha',
+  },
   {
     title: 'Button',
     slug: 'button',