@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/data-kit/status.js

@@ -0,0 +1,49 @@
+import CircleCheck from '@lucide/svelte/icons/circle-check';
+import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
+import OctagonAlert from '@lucide/svelte/icons/octagon-alert';
+import Info from '@lucide/svelte/icons/info';
+import Circle from '@lucide/svelte/icons/circle';
+export const STATUSES = ['good', 'warn', 'bad', 'info', 'neutral'];
+const isStatus = (v) => STATUSES.includes(v);
+/** Model data in, a known status out; anything unrecognised is neutral. */
+export function toStatus(v) {
+    return isStatus(v) ? v : 'neutral';
+}
+/** Risk levels onto status. `critical` is `bad`; the widget adds the filled tile. */
+export const RISK_STATUS = {
+    low: 'good',
+    medium: 'warn',
+    high: 'bad',
+    critical: 'bad'
+};
+export const STATUS_ICONS = {
+    good: CircleCheck,
+    warn: TriangleAlert,
+    bad: OctagonAlert,
+    info: Info,
+    neutral: Circle
+};
+/** The word shown when the data gives none. */
+export const STATUS_WORDS = {
+    good: 'Good',
+    warn: 'Warning',
+    bad: 'Alert',
+    info: 'Info',
+    neutral: 'Note'
+};
+/** text: readable ink; tint: a 12% wash for pills and tiles; fill: dots and bars. */
+export const STATUS_CLASS = {
+    good: { text: 'text-ripple-success-text', tint: 'bg-ripple-success/12', fill: 'bg-ripple-success' },
+    warn: { text: 'text-ripple-warning-text', tint: 'bg-ripple-warning/12', fill: 'bg-ripple-warning' },
+    bad: { text: 'text-ripple-error-text', tint: 'bg-ripple-error/12', fill: 'bg-ripple-error' },
+    info: { text: 'text-ripple-info-text', tint: 'bg-ripple-info/12', fill: 'bg-ripple-info' },
+    neutral: { text: 'text-ripple-muted-foreground', tint: 'bg-ripple-muted', fill: 'bg-ripple-muted-foreground' }
+};
+/** The fill as a CSS value, for SVG marks and inline custom properties. */
+export const STATUS_VAR = {
+    good: 'var(--ripple-success)',
+    warn: 'var(--ripple-warning)',
+    bad: 'var(--ripple-error)',
+    info: 'var(--ripple-info)',
+    neutral: 'var(--ripple-muted-foreground)'
+};

package/dist/widgets/data-kit/tint.d.ts

@@ -0,0 +1,3 @@
+export declare function nameHue(name: string): number;
+/** Inline style for an initials chip: a soft tint fill and a readable ink. */
+export declare function nameTint(name: string): string;

package/dist/widgets/data-kit/tint.js

@@ -0,0 +1,19 @@
+// tint.ts: a deterministic, low-chroma tint per name for initials fallbacks
+// (avatar, avatar-group, people pickers). The same name always gets the same
+// hue; the brand-blue band is skipped so an initials chip never reads as a
+// link or a live state. Both colours blend with the surface tokens, so the
+// ink keeps 4.5:1 on the tint in light and dark.
+export function nameHue(name) {
+    let h = 0;
+    for (const ch of name)
+        h = (h * 31 + ch.codePointAt(0)) >>> 0;
+    const hue = h % 300;
+    // Skip 225..285 (the accent's blue band) by folding it past the band.
+    return hue < 225 ? hue : hue + 60;
+}
+/** Inline style for an initials chip: a soft tint fill and a readable ink. */
+export function nameTint(name) {
+    const h = nameHue(name.trim().toLowerCase() || '?');
+    return (`background-color:color-mix(in oklab, oklch(0.7 0.09 ${h}) 22%, var(--ripple-surface));` +
+        `color:color-mix(in oklab, oklch(0.55 0.12 ${h}) 45%, var(--ripple-surface-foreground))`);
+}

package/dist/widgets/data-kit/types.d.ts

@@ -0,0 +1,23 @@
+/** The one status vocabulary. Colour comes from status.ts, never from data. */
+export type Status = 'good' | 'warn' | 'bad' | 'info' | 'neutral';
+/** The answer up front: one model-written sentence, at most 140 chars. */
+export type Verdict = {
+    text: string;
+    status?: Status;
+};
+/** `good` says which direction is good; without it the trend is neutral. */
+export type Trend = {
+    dir: 'up' | 'down' | 'flat';
+    text?: string;
+    good?: 'up' | 'down';
+};
+/** A stat tile's data. `kind` maps to an icon through the widget's own map. */
+export type Stat = {
+    id?: string;
+    label: string;
+    value: number | string;
+    unit?: string;
+    status?: Status;
+    trend?: Trend;
+    kind?: string;
+};

package/dist/widgets/data-kit/types.js

@@ -0,0 +1,5 @@
+// widgets/data-kit/types.ts — the shared data shapes of the data widgets
+// (design doc 2026-10-09 §3, "Shared types"). Import types from here, not from
+// the kit barrel: the barrel also exports components, and a type imported
+// through it can resolve to a component's props type (see repo CLAUDE.md).
+export {};

package/dist/widgets/design-system/DesignSystemEditor.svelte

@@ -0,0 +1,157 @@
+<!--
+  DesignSystemEditor.svelte — SP-3 (Pillar 2) the design-system token editor widget.
+  A controlled L2 surface for editing a BrandPack's tokens: a color role per row
+  (light/dark slot chosen by `mode`), font families, type-scale sizes, and the
+  radius / spacing / shadow steps. Every edit emits the next BrandPack via
+  `onChange`; the host (the lab, or any consumer) holds the brand in $state and
+  feeds it to `<Ripple brand={...}>` for a live re-skin. PURE controlled component:
+  it imports the L1 schema constants only — no Ripple import — so registering it in
+  the widget map can't create an import cycle. The live preview lives in the host.
+  @created 2026-06-28 — SP-3 chunk 11 (design-system editor widget).
+-->
+<script lang="ts">
+  import {
+		BRAND_COLOR_ROLES,
+		BRAND_TYPE_STEPS,
+		BRAND_RADIUS_STEPS,
+		BRAND_SPACE_STEPS,
+		BRAND_SHADOW_STEPS,
+		type BrandPack,
+		type ColorToken
+  } from '@ripple-ui/core';
+
+  type FontKey = 'sans' | 'serif' | 'mono';
+  type StepGroup = 'radius' | 'space' | 'shadow';
+  const FONT_KEYS: readonly FontKey[] = ['sans', 'serif', 'mono'];
+
+  interface Props {
+    /** The brand being edited (controlled — the host owns the source of truth). */
+    brand: BrandPack;
+    /** Called with the next BrandPack on every edit. */
+    onChange?: (next: BrandPack) => void;
+    /** Which color slot the swatches read/write. */
+    mode?: 'light' | 'dark';
+    class?: string;
+  }
+  let { brand, onChange, mode = 'light', class: className = '' }: Props = $props();
+
+  function clone(b: BrandPack): BrandPack {
+    // JSON round-trip, NOT structuredClone: the brand is plain JSON (token values
+    // are strings/numbers), so this is lossless AND proxy-safe. structuredClone
+    // throws DataCloneError on the Svelte `$state` proxy the host passes as
+    // `brand`, which silently swallowed every edit (the live "color not applying"
+    // bug). JSON.stringify reads through the proxy's traps and yields a plain object.
+    return JSON.parse(JSON.stringify(b)) as BrandPack;
+  }
+
+  function setColor(role: string, slot: 'light' | 'dark', value: string) {
+    const next = clone(brand);
+    next.tokens ??= {};
+    next.tokens.color ??= {};
+    const existing: ColorToken = next.tokens.color[role] ?? { light: value };
+    next.tokens.color[role] = { ...existing, [slot]: value };
+    onChange?.(next);
+  }
+  function setFont(key: FontKey, value: string) {
+    const next = clone(brand);
+    next.tokens ??= {};
+    next.tokens.typography ??= {};
+    next.tokens.typography.fontFamily ??= {};
+    next.tokens.typography.fontFamily[key] = value;
+    onChange?.(next);
+  }
+  function setScaleSize(step: string, value: string) {
+    const next = clone(brand);
+    next.tokens ??= {};
+    next.tokens.typography ??= {};
+    next.tokens.typography.scale ??= {};
+    const s = next.tokens.typography.scale[step] ?? { size: value, lineHeight: '1.5' };
+    next.tokens.typography.scale[step] = { ...s, size: value };
+    onChange?.(next);
+  }
+  function setStep(group: StepGroup, step: string, value: string) {
+    const next = clone(brand);
+    next.tokens ??= {};
+    next.tokens[group] ??= {};
+    (next.tokens[group] as Record<string, string>)[step] = value;
+    onChange?.(next);
+  }
+
+  const colorVal = (role: string, slot: 'light' | 'dark') => brand.tokens?.color?.[role]?.[slot] ?? '';
+  const fontVal = (key: FontKey) => brand.tokens?.typography?.fontFamily?.[key] ?? '';
+  const scaleVal = (step: string) => brand.tokens?.typography?.scale?.[step]?.size ?? '';
+  const stepVal = (group: StepGroup, step: string) =>
+    (brand.tokens?.[group] as Record<string, string> | undefined)?.[step] ?? '';
+
+  // Native <input type=color> needs a hex; non-hex tokens (oklch/hsl) keep their
+  // raw value in the text box and show a neutral chip so the picker still renders.
+  const asHex = (v: string) => (/^#[0-9a-fA-F]{3,8}$/.test(v) ? v : '#888888');
+</script>
+
+{#snippet tokenRow(label: string, value: string, set: (v: string) => void, color: boolean)}
+  <div class="flex items-center gap-2">
+    {#if color}
+      <input
+        type="color"
+        class="h-6 w-6 shrink-0 cursor-pointer rounded border border-border bg-transparent p-0"
+        value={asHex(value)}
+        oninput={(e) => set((e.currentTarget as HTMLInputElement).value)}
+        aria-label={`${label} color`}
+      />
+    {/if}
+    <input
+      type="text"
+      class="min-w-0 flex-1 rounded border border-border bg-background px-2 py-1 font-mono text-xs"
+      value={value}
+      placeholder="—"
+      oninput={(e) => set((e.currentTarget as HTMLInputElement).value)}
+      aria-label={label}
+    />
+    <span class="w-44 shrink-0 truncate text-xs text-muted-foreground">{label}</span>
+  </div>
+{/snippet}
+
+<div class={`ds-editor flex max-h-full flex-col gap-4 overflow-auto p-3 text-sm ${className}`}>
+  <header class="flex items-center justify-between">
+    <div class="font-semibold">{brand.name}</div>
+    <div class="text-xs text-muted-foreground">v{brand.version} · editing {mode}</div>
+  </header>
+
+  <section class="flex flex-col gap-1.5">
+    <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Colors</h3>
+    {#each BRAND_COLOR_ROLES as role (role)}
+      {@render tokenRow(role, colorVal(role, mode), (v) => setColor(role, mode, v), true)}
+    {/each}
+  </section>
+
+  <section class="flex flex-col gap-1.5">
+    <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Typography</h3>
+    {#each FONT_KEYS as fk (fk)}
+      {@render tokenRow(`font ${fk}`, fontVal(fk), (v) => setFont(fk, v), false)}
+    {/each}
+    {#each BRAND_TYPE_STEPS as step (step)}
+      {@render tokenRow(`text ${step}`, scaleVal(step), (v) => setScaleSize(step, v), false)}
+    {/each}
+  </section>
+
+  <section class="flex flex-col gap-1.5">
+    <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Radius</h3>
+    {#each BRAND_RADIUS_STEPS as step (step)}
+      {@render tokenRow(step, stepVal('radius', step), (v) => setStep('radius', step, v), false)}
+    {/each}
+  </section>
+
+  <section class="flex flex-col gap-1.5">
+    <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Spacing</h3>
+    {#each BRAND_SPACE_STEPS as step (step)}
+      {@render tokenRow(step, stepVal('space', step), (v) => setStep('space', step, v), false)}
+    {/each}
+  </section>
+
+  <section class="flex flex-col gap-1.5">
+    <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Shadow</h3>
+    {#each BRAND_SHADOW_STEPS as step (step)}
+      {@render tokenRow(step, stepVal('shadow', step), (v) => setStep('shadow', step, v), false)}
+    {/each}
+  </section>
+</div>

package/dist/widgets/design-system/DesignSystemEditor.svelte.d.ts

@@ -0,0 +1,13 @@
+import { type BrandPack } from '@ripple-ui/core';
+interface Props {
+    /** The brand being edited (controlled — the host owns the source of truth). */
+    brand: BrandPack;
+    /** Called with the next BrandPack on every edit. */
+    onChange?: (next: BrandPack) => void;
+    /** Which color slot the swatches read/write. */
+    mode?: 'light' | 'dark';
+    class?: string;
+}
+declare const DesignSystemEditor: import("svelte").Component<Props, {}, "">;
+type DesignSystemEditor = ReturnType<typeof DesignSystemEditor>;
+export default DesignSystemEditor;

package/dist/widgets/design-system/brand-defaults.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file widgets/design-system/brand-defaults.ts
+ * @description Starter BrandPacks for the design-system editor (SP-3 chunk 11).
+ *   PURE TS (L1) — no Svelte — so the same defaults seed the editor, tests, and a
+ *   future React/Vue adapter. `defaultBrandPack()` returns a full, well-formed
+ *   indigo pack (light + dark slots, a type scale, radius / space / shadow / motion
+ *   steps) so the editor opens with sensible values and every control has a value
+ *   to bind. `emptyBrandPack()` is identity-only — applying it is a render no-op,
+ *   demonstrating "absent/empty brand = today's look exactly".
+ * @created 2026-06-28 — SP-3 chunk 11 (editor defaults).
+ */
+import type { BrandPack } from '@ripple-ui/core';
+/** A valid pack that declares no tokens — applying it emits zero CSS vars. */
+export declare function emptyBrandPack(): BrandPack;
+/**
+ * A full indigo starter pack. Hex values so the editor's native color inputs
+ * round-trip cleanly. Approximates a polished light/dark theme distinct enough
+ * from the bare default that applying it is a visible re-skin.
+ */
+export declare function defaultBrandPack(): BrandPack;

package/dist/widgets/design-system/brand-defaults.js

@@ -0,0 +1,96 @@
+/**
+ * @file widgets/design-system/brand-defaults.ts
+ * @description Starter BrandPacks for the design-system editor (SP-3 chunk 11).
+ *   PURE TS (L1) — no Svelte — so the same defaults seed the editor, tests, and a
+ *   future React/Vue adapter. `defaultBrandPack()` returns a full, well-formed
+ *   indigo pack (light + dark slots, a type scale, radius / space / shadow / motion
+ *   steps) so the editor opens with sensible values and every control has a value
+ *   to bind. `emptyBrandPack()` is identity-only — applying it is a render no-op,
+ *   demonstrating "absent/empty brand = today's look exactly".
+ * @created 2026-06-28 — SP-3 chunk 11 (editor defaults).
+ */
+/** A valid pack that declares no tokens — applying it emits zero CSS vars. */
+export function emptyBrandPack() {
+    return { id: 'empty', name: 'No brand', version: '1.0.0', tokens: {} };
+}
+/**
+ * A full indigo starter pack. Hex values so the editor's native color inputs
+ * round-trip cleanly. Approximates a polished light/dark theme distinct enough
+ * from the bare default that applying it is a visible re-skin.
+ */
+export function defaultBrandPack() {
+    return {
+        id: 'starter-indigo',
+        name: 'Indigo Starter',
+        version: '1.0.0',
+        tokens: {
+            color: {
+                primary: { light: '#4f46e5', dark: '#818cf8' },
+                primaryForeground: { light: '#ffffff', dark: '#0b1020' },
+                background: { light: '#ffffff', dark: '#0b1020' },
+                foreground: { light: '#0f172a', dark: '#e2e8f0' },
+                surface: { light: '#ffffff', dark: '#131a2e' },
+                surfaceForeground: { light: '#0f172a', dark: '#e2e8f0' },
+                muted: { light: '#f1f5f9', dark: '#1e293b' },
+                mutedForeground: { light: '#64748b', dark: '#94a3b8' },
+                secondary: { light: '#f1f5f9', dark: '#1e293b' },
+                secondaryForeground: { light: '#0f172a', dark: '#e2e8f0' },
+                accent: { light: '#eef2ff', dark: '#1e1b4b' },
+                accentForeground: { light: '#3730a3', dark: '#c7d2fe' },
+                border: { light: '#e2e8f0', dark: '#243049' },
+                ring: { light: '#4f46e5', dark: '#818cf8' },
+                destructive: { light: '#dc2626', dark: '#f87171' },
+                destructiveForeground: { light: '#ffffff', dark: '#0b1020' },
+                success: { light: '#16a34a', dark: '#4ade80' },
+                warning: { light: '#d97706', dark: '#fbbf24' },
+                info: { light: '#2563eb', dark: '#60a5fa' }
+            },
+            typography: {
+                fontFamily: {
+                    sans: 'Inter, ui-sans-serif, system-ui, sans-serif',
+                    serif: 'Georgia, ui-serif, serif',
+                    mono: 'ui-monospace, SFMono-Regular, Menlo, monospace'
+                },
+                scale: {
+                    xs: { size: '0.75rem', lineHeight: '1rem' },
+                    sm: { size: '0.875rem', lineHeight: '1.25rem' },
+                    base: { size: '1rem', lineHeight: '1.5rem' },
+                    lg: { size: '1.125rem', lineHeight: '1.75rem' },
+                    xl: { size: '1.25rem', lineHeight: '1.75rem', weight: 600 },
+                    '2xl': { size: '1.5rem', lineHeight: '2rem', weight: 600 },
+                    '3xl': { size: '1.875rem', lineHeight: '2.25rem', weight: 700 },
+                    '4xl': { size: '2.25rem', lineHeight: '2.5rem', weight: 700 }
+                }
+            },
+            space: {
+                xs: '0.25rem',
+                sm: '0.5rem',
+                md: '1rem',
+                lg: '1.5rem',
+                xl: '2rem',
+                '2xl': '3rem'
+            },
+            radius: {
+                none: '0px',
+                sm: '0.25rem',
+                md: '0.625rem',
+                lg: '0.875rem',
+                xl: '1.25rem',
+                full: '9999px'
+            },
+            shadow: {
+                sm: '0 1px 2px 0 rgb(15 23 42 / 0.06)',
+                md: '0 4px 12px -2px rgb(15 23 42 / 0.10)',
+                lg: '0 12px 32px -8px rgb(15 23 42 / 0.18)',
+                xl: '0 24px 56px -16px rgb(15 23 42 / 0.24)'
+            },
+            motion: {
+                duration: { fast: '120ms', base: '220ms', slow: '420ms' },
+                easing: {
+                    standard: 'cubic-bezier(0.2, 0, 0, 1)',
+                    emphasized: 'cubic-bezier(0.3, 0, 0, 1.2)'
+                }
+            }
+        }
+    };
+}

package/dist/widgets/design-system/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file widgets/design-system/index.ts
+ * @description Barrel for the SP-3 design-system widget pack: the token-editor
+ *   widget (`DesignSystemEditor`) plus the starter BrandPacks. Registered in the
+ *   widget map under `design-system` and exported from the package so a host can
+ *   mount `<DesignSystemEditor brand onChange>` directly.
+ * @created 2026-06-28 — SP-3 chunk 11.
+ */
+export { default as DesignSystemEditor } from './DesignSystemEditor.svelte';
+export { defaultBrandPack, emptyBrandPack } from './brand-defaults.js';

package/dist/widgets/design-system/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file widgets/design-system/index.ts
+ * @description Barrel for the SP-3 design-system widget pack: the token-editor
+ *   widget (`DesignSystemEditor`) plus the starter BrandPacks. Registered in the
+ *   widget map under `design-system` and exported from the package so a host can
+ *   mount `<DesignSystemEditor brand onChange>` directly.
+ * @created 2026-06-28 — SP-3 chunk 11.
+ */
+export { default as DesignSystemEditor } from './DesignSystemEditor.svelte';
+export { defaultBrandPack, emptyBrandPack } from './brand-defaults.js';

package/dist/widgets/display/ArticleMeta.svelte

@@ -0,0 +1,84 @@
+<!-- src/lib/widgets/display/ArticleMeta.svelte
+     Byline row: author (photo, or initials on a name tint when the photo is
+     missing or fails), optional role, then date and read time. Date and read
+     time are one nowrap unit, so a wrap moves both and never orphans one. -->
+<script lang="ts">
+  import { safeStyle, safeUrl } from '@ripple-ui/core';
+  import { nameTint } from '../data-kit/tint.js';
+  import { cn } from '../../utils.js';
+  import { asText } from '../text-coerce';
+  import CalendarIcon from '@lucide/svelte/icons/calendar';
+  import ClockIcon from '@lucide/svelte/icons/clock';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    author?: string;
+    avatar?: string;
+    role?: string;
+    date?: string;
+    readTime?: string;
+  }
+
+  let {
+    id, class: className, style,
+    author, avatar, role, date, readTime
+  }: Props = $props();
+
+  let failedAvatar = $state<string>();
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  // `author` is string-typed but a binding can deliver a number — coerce before
+  // .split so initials derivation never crashes the canvas.
+  function authorInitials(name?: unknown): string {
+    const text = asText(name);
+    if (!text) return '';
+    return text
+      .split(' ')
+      .map((p) => p[0]?.toUpperCase() ?? '')
+      .slice(0, 2)
+      .join('');
+  }
+</script>
+
+<div
+  {id}
+  class={cn('flex flex-wrap items-center gap-3 text-sm text-muted-foreground', className)}
+  style={styleString}
+>
+  {#if author}
+    <div class="flex items-center gap-2">
+      {#if avatar && failedAvatar !== avatar && safeUrl(avatar, { kind: 'resource' })}
+        <img src={safeUrl(avatar, { kind: 'resource' })} alt={author} class="size-8 shrink-0 rounded-full object-cover" onerror={() => (failedAvatar = avatar)} />
+      {:else}
+        <div class="flex size-8 shrink-0 items-center justify-center rounded-full text-xs font-semibold" style={safeStyle(nameTint(asText(author)))}>
+          {authorInitials(author)}
+        </div>
+      {/if}
+      <div class="flex flex-col leading-tight">
+        <span class="text-foreground font-medium">{author}</span>
+        {#if role}<span class="text-xs">{role}</span>{/if}
+      </div>
+    </div>
+  {/if}
+  {#if date || readTime}
+  <span class="inline-flex items-center gap-3 whitespace-nowrap">
+  {#if date}
+    <span class="inline-flex items-center gap-1">
+      <CalendarIcon size={13} />
+      <span>{date}</span>
+    </span>
+  {/if}
+  {#if readTime}
+    <span class="inline-flex items-center gap-1">
+      <ClockIcon size={13} />
+      <span>{readTime}</span>
+    </span>
+  {/if}
+  </span>
+  {/if}
+</div>

package/dist/widgets/display/ArticleMeta.svelte.d.ts

@@ -0,0 +1,13 @@
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    author?: string;
+    avatar?: string;
+    role?: string;
+    date?: string;
+    readTime?: string;
+}
+declare const ArticleMeta: import("svelte").Component<Props, {}, "">;
+type ArticleMeta = ReturnType<typeof ArticleMeta>;
+export default ArticleMeta;

package/dist/widgets/display/Avatar.svelte

@@ -0,0 +1,87 @@
+<!--
+  Avatar.svelte — Ripple avatar widget.
+  Updated 2026-06-08 (design polish):
+    - Clean fallback: derive tasteful initials from `alt` (e.g. "Ada Lovelace" -> "AL")
+      when no explicit `fallback` is given, instead of a bare "?". A neutral
+      person glyph is the last resort, never a stray "?".
+    - Fixed the "stray floating colored dots" glitch: Avatar.Root paints an
+      `after:` blend-mode border (mix-blend-darken/lighten) meant for stacked
+      AvatarGroup rings; on a lone avatar over a colored card it renders as a
+      faint colored ring/dot artifact. We suppress that pseudo-border on the
+      standalone widget (`after:hidden`) and instead give the avatar a crisp,
+      theme-driven ring. The AvatarGroup composite keeps its own ring path.
+    - Fallback styled with theme tokens (muted surface, medium weight) so it
+      reads as an intentional placeholder in light/dark.
+-->
+<script lang="ts">
+  import { safeStyle, safeUrl } from '@ripple-ui/core';
+  import { cn } from '../../utils.js';
+  import * as Avatar from '../../components/ui/avatar/index.js';
+  import { asText } from '../text-coerce';
+  import { nameTint } from '../data-kit/tint.js';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    src?: string;
+    alt?: string;
+    fallback?: string;
+  }
+
+  let {
+    id, class: className, style, src, alt = '',
+    fallback
+  }: Props = $props();
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  // Derive tasteful initials from the name when no explicit fallback is given.
+  const initials = $derived.by(() => {
+    if (fallback) return asText(fallback);
+    // `alt` is string-typed but a binding can deliver a number — coerce before
+    // .trim/.split so initials derivation never crashes the canvas.
+    const parts = asText(alt).trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return '';
+    const first = parts[0]?.[0] ?? '';
+    const last = parts.length > 1 ? (parts[parts.length - 1]?.[0] ?? '') : '';
+    return (first + last).toUpperCase();
+  });
+</script>
+
+<Avatar.Root
+  {id}
+  class={cn(
+    // Suppress the blend-mode pseudo-border (the source of the stray dots on a
+    // lone avatar) and use a crisp, theme-driven ring instead.
+    'after:hidden ring-1 ring-border/70',
+    className
+  )}
+  style={styleString}
+>
+  <Avatar.Image src={safeUrl(src, { kind: 'resource' })} {alt} />
+  <Avatar.Fallback
+    class="bg-ripple-track text-ripple-muted-foreground font-medium tracking-tight"
+    style={safeStyle(initials ? nameTint(asText(alt) || initials) : '')}
+  >
+    {#if initials}
+      {initials}
+    {:else}
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="size-[55%]"
+        aria-hidden="true"
+      >
+        <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
+        <circle cx="12" cy="7" r="4" />
+      </svg>
+    {/if}
+  </Avatar.Fallback>
+</Avatar.Root>

package/dist/widgets/display/Avatar.svelte.d.ts

@@ -0,0 +1,12 @@
+import * as Avatar from '../../components/ui/avatar/index.js';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    src?: string;
+    alt?: string;
+    fallback?: string;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;