@vibe-labs/design-components-avatars

Avatar component tokens, styles, and TypeScript types for the Vibe Design System.

Installation

npm install @vibe-labs/design-components-avatars

@import "@vibe-labs/design-components-avatars";

import { AvatarSizes, AvatarStatuses } from "@vibe-labs/design-components-avatars/types";
import type { AvatarSize, AvatarStatus, AvatarStyleProps } from "@vibe-labs/design-components-avatars/types";

Contents

Tokens

CSS custom properties defined in @layer vibe.tokens (file: avatar.css).

Sizes

Token	Value
--avatar-size-xs	1.5rem
--avatar-size-sm	2rem
--avatar-size-md	2.5rem
--avatar-size-lg	3.5rem
--avatar-size-xl	5rem

Initials Font Sizes

--avatar-font-size-xs · --avatar-font-size-sm · --avatar-font-size-md · --avatar-font-size-lg · --avatar-font-size-xl — mapped to the typography scale.

Appearance

Token	Default	Description
--avatar-font-weight	--font-semibold	Initials weight
--avatar-bg	--surface-elevated	Fallback background
--avatar-color	--text-primary	Fallback text color
--avatar-border-width	2px	Ring / group border width
--avatar-border-color	--surface-base	Ring / group border color
--avatar-group-overlap	-0.5rem	Negative margin for stacked groups

Generated Styles

Component classes generated into @layer vibe.components using attribute-based selectors (file: avatar.g.css).

Elements

Class	Description
.avatar	Circular container supporting image or initials
.avatar-initials	Uppercase text fallback displayed inside the circle
.avatar-status	Positioned indicator dot (bottom-right, 25% of size)
.avatar-group	Horizontal stack with overlap and border separation
.avatar-overflow	"+N" count badge appended at the end of a group

Variants

Size (data-size): xs · sm · md (default) · lg · xl

Status (data-status on .avatar-status): online · offline · busy · away

Status	Color
online	success
offline	neutral
busy	danger
away	warning

Modifiers

data-ring on .avatar — adds outer ring via box-shadow.

TypeScript Types

AvatarSizes    // ["xs", "sm", "md", "lg", "xl"]
AvatarStatuses // ["online", "offline", "busy", "away"]

type AvatarSize
type AvatarStatus

interface AvatarStyleProps { size?: AvatarSize; ring?: boolean }
interface AvatarStatusStyleProps { status?: AvatarStatus }
interface AvatarGroupStyleProps { label?: string }

Dist Structure

File	Description
index.css	Barrel — imports tokens + generated styles
avatar.css	Token definitions
avatar.g.css	Generated component styles
index.js / index.d.ts	TypeScript types + runtime constants

Dependencies

Requires tokens from @vibe-labs/design (surfaces, typography, colors, borders, radii).

Build

npm run build

---

Usage Guide

Import

@import "@vibe-labs/design-components-avatars";

import type { AvatarStyleProps } from "@vibe-labs/design-components-avatars/types";

Variants

Size

Set data-size on .avatar: xs · sm · md (default) · lg · xl

Status

Set data-status on .avatar-status: online · offline · busy · away

Modifiers

• data-ring on .avatar — adds an outer ring via box-shadow

Examples

Basic avatar with image

<!-- Image avatar at medium size (default) -->
<div class="avatar">
  <img src="/avatar.jpg" alt="Jane Doe" />
</div>

Avatar with initials fallback

<!-- Initials shown when no image is available -->
<div class="avatar" data-size="lg">
  <span class="avatar-initials">JD</span>
</div>

Avatar with status indicator

<!-- Online status dot shown bottom-right -->
<div class="avatar" data-size="md">
  <img src="/avatar.jpg" alt="Jane Doe" />
  <span class="avatar-status" data-status="online"></span>
</div>

<!-- All status variants -->
<div class="avatar"><span class="avatar-status" data-status="online"></span></div>
<div class="avatar"><span class="avatar-status" data-status="offline"></span></div>
<div class="avatar"><span class="avatar-status" data-status="busy"></span></div>
<div class="avatar"><span class="avatar-status" data-status="away"></span></div>

Avatar with ring

<!-- Ring variant — useful for selected/active states -->
<div class="avatar" data-ring>
  <img src="/avatar.jpg" alt="Selected user" />
</div>

Avatar group (stacked)

<!-- Stacked group of avatars with overlap -->
<div class="avatar-group" aria-label="Team members">
  <div class="avatar" data-size="sm"><img src="/a.jpg" alt="Alice" /></div>
  <div class="avatar" data-size="sm"><img src="/b.jpg" alt="Bob" /></div>
  <div class="avatar" data-size="sm"><img src="/c.jpg" alt="Carol" /></div>
  <!-- Overflow count badge -->
  <div class="avatar avatar-overflow" data-size="sm">+4</div>
</div>

With Vue

Use @vibe-labs/design-vue-avatars for <SbAvatar>, <SbAvatarStatus>, and <SbAvatarGroup> components that bind AvatarStyleProps to the underlying HTML attributes automatically.