Avatar

In review

Live · web

Fallback ladder: image → initials → icon

Image

AR

Initials

MP

Initials

NockerlIcon

Broken src → initials

Sizes: xs · sm · md · lg · xl

RSRSRSRSRS

Shape: circle (Android default) vs rounded square

JLJL

Presence: status dot, bottom-right (streaming pulses)

active

streaming

RS

attention

SO

idle

CD

offline

disabled

Interactive: the top-bar avatar (tab to it, click it)

JL

Group / stack: overlap + “+N” overflow chip

SOJL+3

SOJLRSCD+1

SO

NockerlAvatar tapped 0 times. The island is live.

Code

TypeScriptKotlinSwift

// Web: React, consuming @dizyx/nockerl-tokens. (Web is the laggard platform;
// this is the canonical API the published @dizyx/nockerl-react package exposes.)
import { NockerlAvatar, NockerlAvatarStack } from '@dizyx/nockerl-react';

export function SessionHeader() {
  return (
    <>
      {/* image → initials → icon, in that order */}
      <NockerlAvatar src={user.photoUrl} name="Ada Lovelace" size="md" presence="active" onClick={openSettings} />
      <NockerlAvatar name="Alex Rivera" size="md" />          {/* initials fallback */}
      <NockerlAvatar size="md" />                              {/* icon fallback (no name) */}

      {/* overlapping group with a "+N" overflow chip */}
      <NockerlAvatarStack people={members} max={4} size="sm" />
    </>
  );
}

com.dizyx.nockerl.design.components.NockerlAvatar

// (com.dizyx.nockerl.design on GitHub Packages Maven). A clipped disc with a strict
// fallback ladder: pass a painter, or fall back to initials(name) on the soft accent
// wash. presence is an optional palette-dot color, notched into the host surface.
import com.dizyx.nockerl.design.components.NockerlAvatar
import com.dizyx.nockerl.design.components.NockerlAvatarSize

NockerlAvatar(
    name = "Ada Lovelace",
    painter = painterResource(R.drawable.avatar_user),  // null → initials("AM")
    size = NockerlAvatarSize.MD,
    presence = LocalNockerlColors.current.dotActive,        // palette dot; fold state into a11y
    presenceRing = LocalNockerlColors.current.cardSurface1, // match the host surface
    contentDescription = "Ada Lovelace, active",                 // never color alone (law §13)
)

NockerlAvatar(name = "Alex Rivera", size = NockerlAvatarSize.MD)  // initials fallback ("AR")
NockerlAvatar(name = "", size = NockerlAvatarSize.SM)             // blank → "?" placeholder

// macOS: SwiftUI (canonical look). Nockerl Voice ships NO avatar component yet;
// the disc + presence dot follow the app's own vocabulary (a clipped Circle, and
// PulsingDot from UI/RecordingHUD.swift for the streaming state).
NockerlAvatar(name: "Ada Lovelace", image: user.photo)   // image → initials → icon
    .avatarSize(.md)
    .presence(.active)

NockerlAvatar(name: "Alex Rivera").avatarSize(.md)             // initials fallback

NockerlAvatarStack(people: members, max: 4).avatarSize(.sm)    // overlap + "+N"

Parameters

TypeScriptKotlinSwift

Prop	Type	Default	Description
src	string	n/a	Image URL. When set (and it loads) it wins over the initials/icon fallback.
name	string	n/a	Full name. Used for the accessible label and to derive the initials + tint.
size	NockerlAvatarSize	'md'	Pixel diameter ramp.
shape	NockerlAvatarShape	'circle'	Circle (the Android default) or a 12px rounded square.
presence	Presence	n/a	Presence/status dot, bottom-right. Status colors only, never the brand cyan.
disabled	boolean	false	Inert + desaturated (never invisible) state.
onClick	(e: React.MouseEvent<HTMLButtonElement>) => void	n/a	Makes the avatar a focusable button (e.g. the top-bar → settings tap target). Receives the MouseEvent so trigger callers can anchor to e.currentTarget.

Also accepts the native <button> attributes (e.g. onClick, disabled, id, aria-*, data-*), forwarded straight through, plus a forwarded ref.

AvatarStack takes people: { name; src? }[], max (default 4), and size. It overlaps the first max avatars and appends a +N overflow chip.

Parameter	Type	Default	Description
name *	String	n/a	The person/session name. Drives the initials ("Ada Lovelace" → "AL") and the default accessible name. A blank name renders the "?" placeholder glyph.
modifier	Modifier	Modifier	External modifier (placement, extra sizing).
painter	Painter?	null	Optional avatar image, drawn cropped to the silhouette. null → initials(name) on the soft accent wash. Takes a Painter (e.g. painterResource(…) or a Coil painter), with no image-loader dependency.
size	NockerlAvatarSize	SM	Diameter ramp XS · SM · MD · LG · XL (24 / 32 / 40 / 48 / 64 dp).
shape	Shape	CircleShape	Silhouette. CircleShape (shipped); the rounded-square variant is a proposed alternative.
presence	Color?	null	Optional presence-dot color (a dot* palette token), bottom-right, notched into the host surface. Decorative: fold the state into contentDescription, never color alone (law §13).
presenceRing	Color	cardSurface1	The notch-ring color. Match the HOST surface the avatar sits on so the dot reads anchored, not floating.
contentDescription	String?	null	Accessible name; defaults to name.

SwiftUI exposes the avatar as a View plus chained modifiers; presence and size come from the view modifiers rather than a flat parameter list.

Style	Type	Default	Description
NockerlAvatar(name:image:)	View	n/a	The disc. Resolves image → initials(name) → person icon, clipped to a Circle with a top catch-light + hairline ring.
.avatarSize(_:)	AvatarSize	n/a	Diameter ramp .xs .sm .md .lg .xl (24 / 32 / 40 / 48 / 64 pt).
.avatarShape(_:)	AvatarShape	n/a	.circle (default) or .rounded (control radius).
.presence(_:)	Presence	n/a	Bottom-right status dot in a surface-colored notch; .streaming reuses PulsingDot. Status colors only.
NockerlAvatarStack(people:max:)	View	n/a	Overlapping group; appends a +N overflow chip past max.

Cross-platform drift (tracked for reconciliation)

The look is approved off the shipped Android avatar; the rest is designed here and awaits sign-off:

• Component vs. inline: Android now ships NockerlAvatar (com.dizyx.nockerl.design.components), the published wrapper that folds the raw Image().clip(CircleShape) pattern (GlobalTopBar + AvatarSettingsSheet) into one disc with the ratified size ramp + image → initials ladder. Voice ships none; the Swift API above is intended.
• Fallbacks: the published Kotlin avatar covers image → initials (a blank name renders the "?" placeholder). A dedicated person-icon fallback is not yet shipped; it’s still a proposed rung across all platforms.
• Presence & stacks: the published Kotlin avatar takes an optional bottom-right presence dot (a palette-dot color, notched into the host surface). The overlapping +N stack is still designed-only: there is no NockerlAvatarStack on any platform yet.
• Shape: only circle is shipped (the published Kotlin default). rounded is proposed.