user-persona
Displays user personas in an Agile-friendly visual format with avatar, quote, goals, frustrations, and behaviors.
Overview
A web component for displaying user personas in a structured, visual card format. Includes an auto-generated avatar with initials and a deterministic color derived from the name hash, a quote block, and slotted sections for biography, goals, frustrations, and behaviors. Ideal for design documentation, sprint planning boards, and stakeholder presentations.
<user-persona name="Sarah Chen" role="Product Manager" age="34" location="San Francisco, CA" quote="I need tools that help me stay organized across multiple projects."> <p slot="bio">Sarah has 8 years of experience in product management at mid-size SaaS companies.</p> <ul slot="goals"> <li>Streamline team communication</li> <li>Track project progress efficiently</li> </ul> <ul slot="frustrations"> <li>Too many disconnected tools</li> <li>Difficulty getting stakeholder buy-in</li> </ul> <ul slot="behaviors"> <li>Checks dashboards first thing each morning</li> <li>Prefers async communication over meetings</li> </ul></user-persona>Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | "Unnamed Persona" |
Full name of the persona |
role |
string | — | Job title or role description |
age |
string | — | Age displayed as "[value] years old" |
location |
string | — | Geographic location shown with a pin icon |
avatar |
string (URL) | — | Custom avatar image URL. When omitted, initials are generated from the name. |
quote |
string | — | Representative quote displayed in an italic block with a decorative quotation mark |
compact |
boolean | — | Reduces padding, font sizes, and avatar size for denser layouts |
src |
string (URL) | — | URL to JSON file containing persona data. Loads and populates all fields. |
Slots
| Slot | Expected Content | Description |
|---|---|---|
bio |
<p> or text |
Background information about the persona |
goals |
<ul> or <ol> |
What the persona wants to achieve. Displayed with a green accent icon. |
frustrations |
<ul> or <ol> |
Pain points and frustrations. Displayed with a red accent icon. |
behaviors |
<ul> or <ol> |
Behavioral patterns and habits. Displayed with a purple accent icon. |
Scalar attributes (name, role, age, location, quote) can also be provided as named slots for SSR-friendly authoring. Attributes take priority when both are present.
Avatar Behavior
When no avatar URL is provided, the component generates an avatar automatically:
- Initials — extracted from the first letter of each word in the name, capped at two characters (e.g., "Sarah Chen" becomes "SC")
- Background color — a deterministic HSL hue is computed from a hash of the name string, ensuring the same name always produces the same color
To use a custom image instead, set the avatar attribute to any image URL. The image renders as a circular background-image with center/cover sizing.
<user-persona name="Sarah Chen" role="Product Manager" avatar="https://example.com/team/sarah.jpg"> <p slot="bio">Uses a custom photo instead of generated initials.</p></user-persona>Compact Variant
Add the compact attribute for a denser layout with smaller padding, reduced font sizes, and a 56px avatar (down from 80px). Useful when displaying multiple personas side by side or in a dashboard grid.
<user-persona name="Alex Rivera" role="Frontend Developer" age="28" location="Austin, TX" quote="I want clean APIs and minimal boilerplate." compact> <ul slot="goals"> <li>Ship features faster</li> <li>Reduce build complexity</li> </ul> <ul slot="frustrations"> <li>Breaking changes in dependencies</li> </ul></user-persona>JSON Loading
Load persona data from a JSON file using the src attribute. All fields are mapped to attributes or cached for rendering.
<user-persona src="/api/personas/sarah.json"></user-persona>{ "name": "Sarah Chen", "role": "Senior Product Manager", "age": "34", "location": "San Francisco, CA", "avatar": "https://example.com/sarah.jpg", "quote": "I need tools that help me stay organized.", "bio": "Sarah has 8 years of experience in product management.", "goals": ["Streamline communication", "Track progress efficiently"], "frustrations": ["Too many disconnected tools", "Unclear ownership"], "behaviors": ["Checks Slack 30+ times per day", "Prefers async communication"]}Slot-Based Authoring
All scalar values can be provided as slotted children instead of attributes. This enables server-rendered HTML where the persona data is inline content rather than attributes.
<user-persona> <span slot="name">Sarah Chen</span> <span slot="role">Senior Product Manager</span> <span slot="age">34</span> <span slot="location">San Francisco, CA</span> <span slot="quote">I need tools that help me stay organized.</span> <p slot="bio">Sarah has 8 years of experience in product management.</p> <ul slot="goals"> <li>Streamline communication</li> <li>Track progress efficiently</li> </ul> <ul slot="frustrations"> <li>Too many disconnected tools</li> </ul></user-persona>CSS Custom Properties
| Variable | Default | Description |
|---|---|---|
--user-persona-bg |
#ffffff / #1e1e1e |
Card background color |
--user-persona-text |
#1a1a1a / #e8e8e8 |
Primary text color |
--user-persona-muted |
#666666 / #888888 |
Secondary/muted text color |
--user-persona-border |
#e0e0e0 / #333333 |
Card and section border color |
--user-persona-accent |
#0066cc / #6b9fff |
Accent color for role text and bio icon |
--user-persona-card-bg |
#f8f9fa / #252525 |
Section card background (quote block, content sections) |
--user-persona-radius |
16px |
Outer card border radius |
--user-persona-avatar-size |
80px |
Avatar width and height (56px in compact mode) |
--user-persona-goals |
#22c55e / #4ade80 |
Goals section accent color |
--user-persona-frustrations |
#ef4444 / #f87171 |
Frustrations section accent color |
--user-persona-behaviors |
#8b5cf6 |
Behaviors section accent color |
Events
| Event | Detail | When |
|---|---|---|
persona-ready |
{ name, role, age, location } |
Fires after the component renders for the first time |
Accessibility
- The outer card uses
role="article"with anaria-labelof "User persona: [name]" - The avatar element has
role="img"witharia-label="Avatar for [name]" - The decorative quotation mark uses
aria-hidden="true"so screen readers skip it - Each content section has a visible heading for screen reader navigation
- Respects
prefers-reduced-motion: reduceby disabling all transitions - Responsive layout stacks to a single column at narrow viewports (<600px)
Related
<user-story>— Agile user story cards referencing personas<user-journey>— Journey maps that link back to persona definitions<empathy-map>— Empathy maps linked viapersona-id<impact-effort>— Prioritization matrix for triaging stories<story-map>— Horizontal story mapping for sprint planning- UX Planning Pack — loads all six UX components together