Avatar

In review

Live · web

Fallback ladder: image → initials → icon

Image

Initials

NockerlIcon

Broken src → initials

Sizes: xs · sm · md · lg · xl

RSRSRSRSRS

Shape: circle (Android default) vs rounded square

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

active

streaming

attention

idle

offline

disabled

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

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

SOJL+3

SOJLRSCD+1

NockerlAvatar tapped 0 times. The island is live.

Code

// 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 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

Prop	Type	Default	Description
`src`	`string`		Image URL. When set (and it loads) it wins over the initials/icon fallback.
`name`	`string`		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`		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`		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`		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	Description
`NockerlAvatar(name:image:)`	`View`	The disc. Resolves `image` → initials(`name`) → person icon, clipped to a Circle with a top catch-light + hairline ring.
`.avatarSize(_:)`	`AvatarSize`	Diameter ramp `.xs .sm .md .lg .xl` (24 / 32 / 40 / 48 / 64 pt).
`.avatarShape(_:)`	`AvatarShape`	`.circle` (default) or `.rounded` (control radius).
`.presence(_:)`	`Presence`	Bottom-right status dot in a surface-colored notch; `.streaming` reuses `PulsingDot`. Status colors only.
`NockerlAvatarStack(people:max:)`	`View`	Overlapping group; appends a `+N` overflow chip past `max`.

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.