# Avatar: API

## Пропсы корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на корневой элемент `div` аватара. Даёт доступ к DOM-узлу, например для фокуса или измерений. |
| `size` | `AvatarSize` | `'md'` | Нет | Определяет размер аватара. Влияет и на контейнер, и на вложенное содержимое (изображение, инициалы и т. д.). |
| `variant` | `AvatarVariant` | `'primary'` | Нет | Визуальный вариант аватара. Позволяет различать роли, типы или контексты. 'primary': визуальный стиль по умолчанию; 'secondary': альтернативный или менее заметный стиль |

Также принимает все атрибуты `<div>`.

## Дочерние части

- `AvatarImage`: изображение.
- `AvatarFallback`: текстовый запасной вариант.
- `AvatarIcon`: запасная иконка.

### `AvatarIcon`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconSize` | — | Нет | Предопределённый токен размера иконки. Может быть переопределён явными шириной и высотой. |
| `ref` | `Ref<SVGSVGElement>` | — | Нет | Ref на SVG-элемент |
| `strokeWidth` | `number` | — | Нет | Толщина обводки линий и фигур SVG (в px или pt). |
| `children` | `ReactNode` | — | Нет | Содержимое иконки (обязательно). Принимает: иконки из `~/icons`; собственный встроенный SVG; компоненты иконок сторонних библиотек (например, Lucide, Tabler) |

Также принимает все HTML-атрибуты.

### `AvatarFallback`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `TextSize` | — | Нет | Визуальный размер текста, обычно соответствует типографической шкале дизайн-системы. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит текст как дочерний компонент через `Slot`. Полезно для совместимости с нативными элементами или другими компонентами. |
| `fontWeight` | `400 \| 500 \| 600 \| 700 \| 900` | — | Нет | Насыщенность шрифта текста. Распространённые значения: 400: обычный; 500: средний; 600: полужирный; 700: жирный; 900: сверхжирный |
| `ref` | `Ref<HTMLSpanElement>` | — | Нет | Ref на нижележащий `<span>` или элемент в слоте. Полезен для измерений, фокуса или работы с DOM. |

Также принимает все атрибуты `<span>`.

### `AvatarImage`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLImageElement>` | — | Нет | Ref на нативный элемент `<img>`. Полезен для прямого доступа к DOM, отслеживания загрузки или анимаций. |
| `fallbackSrc` | `string` | — | Нет | URL резервного изображения, которое показывается, если основное не загрузилось. Позволяет аватару корректно деградировать, когда основной источник недоступен. |

Также принимает все атрибуты `<img>`.

## Типы

- `AvatarProps`
- `AvatarImageProps`
- `AvatarFallbackProps`
- `AvatarIconProps`
- `AvatarSize`
- `AvatarVariant`

## Модель состояния

- С точки зрения API компонента `Avatar` не имеет состояния.
- Что показывать — изображение, запасной текст или иконку, — определяет содержимое, которое передаёт потребитель.