[FIR-296] Extend ff-avatar with numeric size, name initials, shape and tones

apps/playground/src/app/pages/catalog/avatar-page.ts

@@ -2,6 +2,7 @@ import { ChangeDetectionStrategy, Component } from '@angular/core';
 import {
   FfAvatarComponent,
   FfAvatarSize,
+  FfAvatarTone,
 } from '@fireflyframework/design-system';
 
 import { DemoSection } from '../../shared/demo-section';
@@ -29,6 +30,48 @@ import { DemoSection } from '../../shared/demo-section';
         }
       </app-demo-section>
 
+      <app-demo-section
+        heading="Numeric size"
+        description="size also accepts a literal pixel number for an arbitrary size; the initials font size scales proportionally."
+        [code]="snippets.numericSize"
+      >
+        @for (px of numericSizes; track px) {
+          <ff-avatar [size]="px" name="Jane Doe" [alt]="px + 'px avatar'" />
+        }
+      </app-demo-section>
+
+      <app-demo-section
+        heading="Initials from name"
+        description="Without an explicit initials input, initials are derived automatically from name (first + last word, uppercased)."
+        [code]="snippets.name"
+      >
+        <ff-avatar name="Madonna" alt="Madonna" />
+        <ff-avatar name="Jane Doe" alt="Jane Doe" />
+        <ff-avatar name="Maria Garcia Luque" alt="Maria Garcia Luque" />
+        <ff-avatar name="Jane Doe" initials="XX" alt="Explicit initials override" />
+        <span class="demo-label">← the last one keeps "XX": the explicit initials input wins over name</span>
+      </app-demo-section>
+
+      <app-demo-section
+        heading="Round / cornerRadius"
+        description="round defaults to true (fully rounded). Set it to false for a square avatar shaped by cornerRadius (falls back to --ff-radius-md)."
+        [code]="snippets.shape"
+      >
+        <ff-avatar name="Jane Doe" [size]="56" />
+        <ff-avatar name="Jane Doe" [size]="56" [round]="false" />
+        <ff-avatar name="Jane Doe" [size]="56" [round]="false" cornerRadius="20%" />
+      </app-demo-section>
+
+      <app-demo-section
+        heading="Tones"
+        description="All values of FfAvatarTone: decorative background palette, independent of the image/initials content."
+        [code]="snippets.tones"
+      >
+        @for (t of tones; track t) {
+          <ff-avatar [tone]="t" [initials]="t.slice(0, 2)" [alt]="'Tone ' + t" />
+        }
+      </app-demo-section>
+
       <app-demo-section
         heading="Image error fallback"
         description="A broken src falls back to the initials automatically."
@@ -43,9 +86,29 @@ import { DemoSection } from '../../shared/demo-section';
 export class AvatarPage {
   protected readonly sizes: readonly FfAvatarSize[] = ['sm', 'md', 'lg'];
 
+  protected readonly numericSizes: readonly number[] = [24, 48, 72, 96];
+
+  protected readonly tones: readonly FfAvatarTone[] = [
+    'primary',
+    'secondary',
+    'success',
+    'warning',
+    'error',
+    'info',
+    'neutral',
+  ];
+
   protected readonly snippets = {
     sizes: `<ff-avatar initials="JD" size="lg" />
 <ff-avatar src="https://example.com/photo.jpg" alt="Jane Doe" />`,
+    numericSize: `<ff-avatar name="Jane Doe" [size]="72" />`,
+    name: `<ff-avatar name="Jane Doe" />
+<ff-avatar name="Jane Doe" initials="XX" />`,
+    shape: `<ff-avatar name="Jane Doe" [size]="56" />
+<ff-avatar name="Jane Doe" [size]="56" [round]="false" />
+<ff-avatar name="Jane Doe" [size]="56" [round]="false" cornerRadius="20%" />`,
+    tones: `<ff-avatar tone="primary" initials="PR" />
+<ff-avatar tone="success" initials="SU" />`,
     fallback: `<ff-avatar src="broken.png" initials="JD" alt="Jane Doe" />`,
   };
 }

packages/design-system-contract/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- `AvatarContract`: `size` type widened to accept a literal pixel number; new `name`, `round`, `cornerRadius` and `tone` inputs; the `aria` clause documents that the resolved initials (explicit `initials`, else derived from `name`) drive the aria-label fallback
+
 ## [0.2.0] - 2026-07-21
 
 ### Added

packages/design-system-contract/src/lib/primitives/avatar.contract.ts

@@ -3,25 +3,36 @@ import type { DsComponentContract } from '../contract.types';
 /**
  * Contract of the `ff-avatar` primitive.
  *
- * Circular avatar displaying an image, falling back automatically to
- * `initials` (max 2 characters, uppercased) when `src` is empty or the
- * image fails to load.
+ * Circular (or square, via `round`) avatar displaying an image, falling back
+ * automatically to initials when `src` is empty or the image fails to load.
+ * Initials come from the explicit `initials` input when set, otherwise they
+ * are derived from `name` (first + last word, max 2 characters, uppercased).
+ * `size` accepts the predefined tokens or a literal pixel number, and `tone`
+ * applies a decorative background palette independent of the content.
  */
 export const AvatarContract: DsComponentContract = {
   selector: 'ff-avatar',
   category: 'primitive',
   inputs: {
     src: { type: 'string', required: false, default: "''" },
     initials: { type: 'string', required: false, default: "''" },
+    name: { type: 'string', required: false, default: "''" },
     alt: { type: 'string', required: false, default: "''" },
-    size: { type: "'sm' | 'md' | 'lg'", required: false, default: "'md'" },
+    size: { type: "'sm' | 'md' | 'lg' | number", required: false, default: "'md'" },
+    round: { type: 'boolean', required: false, default: 'true' },
+    cornerRadius: { type: 'string | undefined', required: false, default: 'undefined' },
+    tone: {
+      type: "'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'neutral' | undefined",
+      required: false,
+      default: 'undefined',
+    },
   },
   outputs: {},
   behavior: {
     hostAttributeOwnership: ['class', 'role', 'aria-label'],
     aria: [
       'host has role="img"',
-      'host aria-label is derived from alt (falling back to initials)',
+      'host aria-label is derived from alt (falling back to the resolved initials — explicit `initials` or derived from `name`)',
     ],
   },
 };

packages/design-system/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `ff-avatar`: `size` now also accepts a literal pixel number (proportional initials font size); `name` derives initials automatically (first + last word, uppercased) when the explicit `initials` input is unset; `round`/`cornerRadius` for a square shape with a custom corner radius; `tone` decorative background palette mirroring `ff-badge`'s `color` axis; new `FfAvatarTone` type
+
 ## [0.4.0] - 2026-07-21
 
 ### Added

packages/design-system/src/index.ts

@@ -54,7 +54,7 @@ export type { FfChipVariant, FfChipSize } from './lib/primitives/ff-chip';
 export { FfLinkComponent } from './lib/primitives/ff-link';
 export type { FfLinkVariant, FfLinkTarget } from './lib/primitives/ff-link';
 export { FfAvatarComponent } from './lib/primitives/ff-avatar';
-export type { FfAvatarSize } from './lib/primitives/ff-avatar';
+export type { FfAvatarSize, FfAvatarTone } from './lib/primitives/ff-avatar';
 export { FfTooltipComponent } from './lib/primitives/ff-tooltip';
 export type { FfTooltipPosition } from './lib/primitives/ff-tooltip';
 export { FfIconComponent, FF_ICONS, provideFfIcons } from './lib/primitives/ff-icon';

packages/design-system/src/lib/primitives/ff-avatar/ff-avatar.component.html

@@ -6,5 +6,5 @@
     (error)="onImgError()"
   />
 } @else {
-  <span class="ff-avatar__initials">{{ displayInitials }}</span>
+  <span class="ff-avatar__initials">{{ displayInitials() }}</span>
 }

packages/design-system/src/lib/primitives/ff-avatar/ff-avatar.component.scss

@@ -53,4 +53,55 @@
   &--lg .ff-avatar__initials {
     font-size: var(--ff-font-size-md);
   }
+
+  // A numeric `size` sets width/height inline on the host; the class only
+  // owns the initials font size, scaled proportionally from the component.
+  &--custom .ff-avatar__initials {
+    font-size: var(--ff-avatar-initials-size, var(--ff-font-size-sm));
+  }
+
+  // --- Shape ---
+
+  // `round="false"`: the corner radius comes from `cornerRadius` (component
+  // token with a fallback, same override pattern as the background/color).
+  &--square {
+    border-radius: var(--ff-avatar-radius, var(--ff-radius-md));
+  }
+
+  // --- Tones (decorative background palette, independent of content) ---
+
+  &--tone-primary {
+    background-color: var(--ff-avatar-tone-primary-bg, var(--ff-color-primary-100));
+    color: var(--ff-avatar-tone-primary-color, var(--ff-color-primary-700));
+  }
+
+  &--tone-secondary {
+    background-color: var(--ff-avatar-tone-secondary-bg, var(--ff-color-secondary-100));
+    color: var(--ff-avatar-tone-secondary-color, var(--ff-color-secondary-700));
+  }
+
+  &--tone-success {
+    background-color: var(--ff-avatar-tone-success-bg, var(--ff-color-success-100));
+    color: var(--ff-avatar-tone-success-color, var(--ff-color-success-700));
+  }
+
+  &--tone-warning {
+    background-color: var(--ff-avatar-tone-warning-bg, var(--ff-color-warning-100));
+    color: var(--ff-avatar-tone-warning-color, var(--ff-color-warning-700));
+  }
+
+  &--tone-error {
+    background-color: var(--ff-avatar-tone-error-bg, var(--ff-color-error-100));
+    color: var(--ff-avatar-tone-error-color, var(--ff-color-error-700));
+  }
+
+  &--tone-info {
+    background-color: var(--ff-avatar-tone-info-bg, var(--ff-color-info-100));
+    color: var(--ff-avatar-tone-info-color, var(--ff-color-info-700));
+  }
+
+  &--tone-neutral {
+    background-color: var(--ff-avatar-tone-neutral-bg, var(--ff-color-neutral-100));
+    color: var(--ff-avatar-tone-neutral-color, var(--ff-color-neutral-700));
+  }
 }

packages/design-system/src/lib/primitives/ff-avatar/ff-avatar.component.spec.ts

@@ -138,4 +138,158 @@ describe('FfAvatarComponent', () => {
     expect(initials).toBeTruthy();
     expect(initials.textContent.trim()).toBe('JD');
   });
+
+  describe('name → initials derivation', () => {
+    function initialsText(): string {
+      const el = fixture.nativeElement.querySelector('.ff-avatar__initials');
+      return el.textContent.trim();
+    }
+
+    it('should derive a single initial from a one-word name', () => {
+      fixture.componentRef.setInput('name', 'Madonna');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('M');
+    });
+
+    it('should derive first + last initials from a two-word name', () => {
+      fixture.componentRef.setInput('name', 'Jane Doe');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('JD');
+    });
+
+    it('should derive first + last initials from a compound (3+ word) name, ignoring middle words', () => {
+      fixture.componentRef.setInput('name', 'Maria Garcia Luque');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('ML');
+    });
+
+    it('should collapse extra/irregular whitespace between words', () => {
+      fixture.componentRef.setInput('name', '  Jane    Doe  ');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('JD');
+    });
+
+    it('should uppercase derived initials', () => {
+      fixture.componentRef.setInput('name', 'jane doe');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('JD');
+    });
+
+    it('should derive initials from unicode names', () => {
+      fixture.componentRef.setInput('name', 'Émile Zola');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('ÉZ');
+    });
+
+    it('should render empty initials for an empty name', () => {
+      fixture.componentRef.setInput('name', '');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('');
+    });
+
+    it('should render empty initials for a whitespace-only name', () => {
+      fixture.componentRef.setInput('name', '   ');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('');
+    });
+
+    it('should let the explicit initials input override the name derivation', () => {
+      fixture.componentRef.setInput('name', 'Jane Doe');
+      fixture.componentRef.setInput('initials', 'XX');
+      fixture.detectChanges();
+
+      expect(initialsText()).toBe('XX');
+    });
+  });
+
+  describe('numeric size', () => {
+    it('should apply the "custom" size class for a numeric size', () => {
+      fixture.componentRef.setInput('size', 72);
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.classList.contains('ff-avatar--custom')).toBe(true);
+    });
+
+    it('should set inline width/height for a numeric size', () => {
+      fixture.componentRef.setInput('size', 72);
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.style.width).toBe('72px');
+      expect(hostEl.style.height).toBe('72px');
+    });
+
+    it('should not set inline width/height for a predefined size', () => {
+      fixture.componentRef.setInput('size', 'lg');
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.style.width).toBe('');
+      expect(hostEl.style.height).toBe('');
+    });
+
+    it('should set a proportional initials font size for a numeric size', () => {
+      fixture.componentRef.setInput('size', 100);
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.style.getPropertyValue('--ff-avatar-initials-size').trim()).toBe('40px');
+    });
+  });
+
+  describe('round / cornerRadius', () => {
+    it('should default to round (no square modifier class)', () => {
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.classList.contains('ff-avatar--square')).toBe(false);
+    });
+
+    it('should apply the square modifier class when round is false', () => {
+      fixture.componentRef.setInput('round', false);
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.classList.contains('ff-avatar--square')).toBe(true);
+    });
+
+    it('should set the corner radius custom property when provided', () => {
+      fixture.componentRef.setInput('round', false);
+      fixture.componentRef.setInput('cornerRadius', '12px');
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.style.getPropertyValue('--ff-avatar-radius').trim()).toBe('12px');
+    });
+
+    it('should keep the round shape when cornerRadius is set but round stays true', () => {
+      fixture.componentRef.setInput('cornerRadius', '12px');
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.classList.contains('ff-avatar--square')).toBe(false);
+    });
+  });
+
+  describe('tone', () => {
+    it('should not apply a tone class by default', () => {
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.className).not.toContain('ff-avatar--tone-');
+    });
+
+    it('should apply the matching tone class when set', () => {
+      fixture.componentRef.setInput('tone', 'success');
+      fixture.detectChanges();
+
+      const hostEl = fixture.nativeElement as HTMLElement;
+      expect(hostEl.classList.contains('ff-avatar--tone-success')).toBe(true);
+    });
+  });
 });