Auro Tail - Technical Research Document

[chrisfalaska]

auro-tail - Technical Research Document (formerly "auro-avatar")

Creation Date: 2025-08-11
Template Version: v1
Status: Draft → Reviewable → Accepted | Abandoned

Role	Name	Status
Author(s)	Chris Friedberg	Completed
Owning Team	Auro	REVIEWED 9/22/25
Designer(s)	Nick King	REVIEWED 9/12/25
Product Manager	Megan Renner
Accountable EM	Lindsey O'Sullivan
Technical Design Shepherd	Jason Baker
Auro Engineer	Your Name Here	NOT REVIEWED

Project Proposal: ADO

Product Requirements:

• Figma design
• Tail art

Prototype: GitHub

Overview

The auro-avatar component combines a tail art graphic with a circular avatar bubble, creating a unified "Auro Avatar."

A related sub-component, auro-avatar-group, allows distinct placement of multiple auro-avatar components within predefined grouped layouts.

Problem Statement

Airline branding and partner identification requires a consistent visual component that can display airline tail graphics within circular avatar containers.

This component must support Alaska Airlines Group (AAG) brands as well as partner airlines ("OA," or "other airlines"), with optional badges, borders, and grouping capabilities.

Goals and Non-Goals

Goals

• Create a reusable avatar component that displays airline tail graphics
• Support AAG airlines (Alaska, Hawaiian) and partner airlines (OA)
• Enable optional OneWorld alliance badge display
• Provide flexible sizing options
• Support grouped avatar layouts
• Implement optional linking functionality with click events for consumers
• Maintain accessibility with proper ARIA labels

Non-Goals

• Support for non-airline avatars or generic user profiles
• Custom badge or arbitrary badge types beyond OneWorld
• Animation

Success Criteria and Measurement

• Proper display of all supported airline variants
• SSR-compatible
• Accessibility compliance with screen readers
• Performance benchmarks for tail graphic loading (only load what is needed)

Relevant Background, Prior Art or Supporting Material

This component builds upon existing Auro design system patterns and extends the concept of branded avatars to include airline tail graphics.

The component follows Lit-based web component architecture, with SSR support, consistent with other Auro components.

High-Level Approach

The solution consists of three main components:

• auro-avatar - Individual avatar with tail graphic, optional badge, and linking
• auro-avatar-group - Container for grouping multiple avatars with layout options
• AvatarTails - A library of tail SVGs

Project Architecture and Its Components

auro-avatar

The primary component that renders airline tail graphics within a circular container.

Property	Type	Default	Description
variant	AirlineVariant	'as'	Airline code (as, ha, ph, etc)
badge	BadgeVariant	undefined	Optional badge type (oneworld, etc)
size	AvatarSize	'lg'	Avatar size (2xl, xl, lg, md, sm, xs)
outline	boolean	false	Show outline around tail (OA only)
borderWidth	string | number	undefined	Border width (px only)
borderColor	string	undefined	Border color CSS value (any valid color type accepted)
href	string	undefined	Optional hyperlink URL / label

Size

Size	Label Support	Badge Support
2xl	✅	✅
xl	✅	✅
lg	✅	✅
md	✅	✅
sm	❌	❌
xs	❌	❌

Variants

Based on tailConfig (see AvatarTails):

Variant	Airline Name	Outline	Drop-shadow
as	Alaska Airlines	❌	✅
ha	Hawaiian Airlines	❌	✅
ph, etc	Other airline (OA)	✅	❌

Gradient

A smooth transition between colors used as the background of the avatar bubble.

Three gradient styles are available for the avatar and are rendered using CSS custom properties:

• Hawaiian ("pink")
• Alaska ("blue")
• Other Airline ("gray")
  • Partner tails always require the OA gradient

Note: Gradients are theme-independent and will always be the same color regardless of theme.

Badge

Displays a badge / logo.

• Displays in bottom-right corner, overlapping the avatar
• Hidden on sm and xs sizes
• Not displayed when avatar is within auro-avatar-group
• Appear in predefined dimension steps based on avatar size prop
• Do not scale fluidly or responsively

Badge sizes

Badge sizes based on avatar size prop:

• 2xl
• xl
• lg
• md
• sm: Not displayed
• xs: Not displayed

Available badges

• oneworld

OneWorld badge

It should always be the version with a gradient background and white outline (this is the official oneworld logo mark; any other variation is not permitted).

Border

Optional border ring around the avatar bubble.

• Accepts only pixel values (px), either as numbers or "Npx" strings
• Other units (rem, em, %, CSS variables) are ignored
• Default width: 4px whenborderColor is specified
• Default color: XXXX when borderWidth is specified
• Controlled via CSS custom properties
• Displays if either are set:
  • border-width=""
  • border-color=""
• Can be used in combination

Outline

Optional outline that appears around the tail graphic.

• Outlines apply only for partner (OA) tails only
• AAG tails (AS & HA) do not feature outlines
• tail-outline-width and tail-outline-color are predefined and not customizable

Drop-shadow

Applies a subtle drop shadow behind the avatar tail graphic.

This is applied only to the following tails (not optional):

• Hawaiian tail (HA)
• Alaska tail (AS)
• Applies to all avatar sizes

Label / href

An optional link that uses auro-hyperlink to display the airline name as a clickable link.

When href prop is provided:

• Wraps avatar and airline name in auro-hyperlink
• Prop is named this way for parity with auro-hyperlink API
• Airline name derived from the variant value
• Entire avatar becomes clickable
• Dispatches href-click custom event (cancelable)
• Only available on md size and larger
• Not displayed when avatar is within auro-avatar-group
• Not user-customizable (only displays airline name)

Applies to the following sizes only:

• 2xl (body-lg type class)
• xl (body-default)
• lg (body-sm)
• md (body-xs)

https://www.figma.com/design/hSk45itvMVOyCjkheCrLn4/Avatar-Tail?node-id=3420-5897&t=63aVFfu6hFs91z8A-0

Example:

variant="ha" & href="/url/" will render -> "Hawaiian Airlines"

Events

href-click

Allows custom logic before navigation occurs.

• Bubbles: true
• Composed: true
• Cancelable: true
• Call event.preventDefault() to cancel navigation

auro-avatar-group

The auro-avatar-group component is designed for displaying multiple avatars in a group layout with specific behavioral constraints and visual treatments.

Limitations

• Maximum Display Count: Only 2 avatars will be displayed in any group
• Hidden Content: Any additional avatars beyond the first 2 will be hidden
• Size Override: The group's size property will override individual avatar size properties
• Updates child avatar sizes to match the group size
• Suppressed Features:
  • When avatars are within an avatar group:
    • Badge logos will not be shown
    • Labels/links will not be displayed

Variants

Horizontal

Avatars overlap with configurable border treatment.

Visual Specifications:

• Overlap: Avatars should overlap each other.

  • "Overlap" is the negative distance between the Avatar Tails
  • Dependent on the "size" prop, and is not adjustable
    • lg: 10px
    • md: 6px
    • sm: 2px
    • xs: 2px
  • Figma spec

• Border Width

  • Dependent on the "size" prop, and not adjustable
    • lg: 4px
    • md: 4px
    • sm: 3px
    • xs: 3px
  • Figma spec

• Default Border Color: White

• Border color: Customizable

Size Dimensions (2 paired avatars)

Uses the corresponding auro-avatar sizes, shown below:

• lg: 105px × 60px
• md: 84px × 84px
• sm: 56px × 56px
• xs: 42px × 42px

Diagonal

Avatars positioned diagonally without overlap.

Visual Specifications:

• No Overlapping: Avatars must not overlap in diagonal variant
• No outline-color
• No outline-border

Size Dimensions (2 paired avatars)

Uses the corresponding auro-avatar sizes, shown below:

• lg: 105px × 105px
• md: 84px × 84px
• sm: 56px × 56px
• xs: 42px × 42px

Figma spec

Props

Property	Attribute	Type	Values	Default	Notes
Layout	layout	String	'horizontal' | 'diagonal'	'horizontal'
Size	size	String (AvatarGroupSize)	'lg' | 'md' | 'sm' | 'xs'	'lg'	Overrides individual avatar sizes within the group
Border Color	border-color	String	-	White (for Horizontal layout)	Affects all borders within the group

AvatarTails

The AvatarTails library provides a collection of partner tail SVGs.

Repository Strategy

Option A: Maintain in auro-avatar repository

Condition: If tail SVGs are exclusively used within the auro-avatar component.

Benefits:

• Co-located with auro-avatar repository
• Simplified dependency management
• Direct integration with avatar components
• Source of Truth: tailNameMap serves as the authoritative mapping for tail codes

Option B: Migrate to auro-icon repository

Condition: If tail SVGs have broader usage across multiple components.

Requirements:

• Must ship with TypeScript definitions (.d.ts files)
• Each tail graphic as separate module for optimal tree-shaking
• Minimize consumer bundle impact

Bundle Optimization Requirements

Consumers must not be forced to load the entire tails icon library when only using specific tail logos.

Preferred: Selective import

import { alaskaTail, hawaiianTail } from '@auro-avatar/avatar-tails';

Avoid: Full library import

import * as AllTails from '@auro-avatar/avatar-tails';

Implementation Details

CSS Custom Properties

Auro Avatar uses CSS custom properties for dynamic styling:

--border-display: block | none
--border-color: <color-value>
--border-width: <px-value>
--border-padding: <px-value>

Accessibility

• Proper ARIA labeling with airline names and badge information
• Role="img" on avatar containers
• Badge images marked with aria-hidden="true"
• Screen reader friendly airline name announcements

Open Questions

1. Link Sanitization: Should href values be sanitized? Does Auro Library provide sanitization utilities? Is this an Auro concern or consumer?

2. Icon Library Location: Should tail graphics be maintained in auro-avatar repository or moved to shared Icons repository?

3. Bundle Optimization: How can we ensure optimal tree-shaking for tail graphics that aren't used?

4. Animation Support: Are there plans for animation?

5. AAG Outline: Is there an AAG tail with an outline (would complicate outline prop)?

Risks

• Tail Graphic Maintenance: Adding new partner airlines requires code updates
• Bundle Size: Including all tail graphics will impact bundle size and the component should be optimized to allow loading of only the tails required for the application

Milestones

∆ Are there specific engineering milestones beyond those in the PRD? Are there engineering dependencies for the PRD milestones that should be explicitly called out? Can this project be broken up into incremental deliverables, and what will they look like? Will future milestones depend on the outcome of previous milestones and their success?

Milestone 1

∆ Describe the first milestone or deliverable of the system

Security

∆ Review the security section of the TDD Checklist and provide any additional information (which is not covered elsewhere in the TDD) that arises from the questions and/or instructions embedded within that section.

Privacy and Data Collection

∆ Review the privacy and data collection section of the TDD Checklist and provide any additional information (which is not covered elsewhere in the TDD) that arises from the questions and/or instructions embedded within that section

Ownership and Documentation

Code owners	Auro Design System
Code location	∆ Link or expected location
Documentation	∆ Link or expected location

[chrisfalaska]

09/22/25 — Developer TRD Review

The new Avatar API is very different from the current auro-avatar component.

Key Decisions

• Create new auro-tail repository
• Deprecate the tail prop from auro-avatar
• TypeScript is out of scope

[chrisfalaska]

PR: AlaskaAirlines/auro-tail#6

[chrisfalaska]

Clarification: Tail icons will continue to be imported from auro-icon rather than duplicated in auro-tail to avoid maintaining two separate icon sets.