VB Project Planning

<empathy-map>

Four-quadrant empathy map visualization (Says, Thinks, Does, Feels) with optional flip-to-edit interaction.

Overview

A web component that renders a four-quadrant empathy map — Says, Thinks, Does, and Feels — with optional Goals and Pain Points summary rows. Supports slotted HTML content, JSON loading via the src attribute, and a flip-to-edit mode for live editing directly in the browser. Designed for design workshops, sprint planning, and stakeholder presentations.

Attributes

Attribute Type Default Description
persona string — Persona name displayed in the header
persona-id string — ID of a <user-persona> element to link to (renders as an anchor)
src string (URL) — Path to a JSON file containing quadrant data, goals, and pain points
editable boolean — Enables flip-to-edit interaction on each quadrant
compact boolean — Reduces padding, font sizes, and icon sizes for denser layouts

Slots

Slot Expected Content Description
title <h2> or text Map heading displayed in the header. Defaults to "Empathy Map" when omitted.
summary <p> or text Brief description shown below the title.
says <ul> or <ol> Quotes and statements the persona makes. Displayed in the top-left quadrant with a blue accent.
thinks <ul> or <ol> Internal thoughts and beliefs. Displayed in the top-right quadrant with a purple accent.
does <ul> or <ol> Observable actions and behaviors. Displayed in the bottom-left quadrant with an amber accent.
feels <ul> or <ol> Emotional states. Items matching EMOTION_META keys get automatic emoji and color treatment. Displayed in the bottom-right quadrant with a red accent.
goals <ul> or <ol> Optional goals summary displayed below the quadrant grid
pain-points <ul> or <ol> Optional pain points summary displayed below the quadrant grid

Content values (title, summary) are provided as named slots. State attributes (persona, persona-id) remain on the element.

Editable Mode

Add the editable attribute to enable flip-to-edit on each quadrant. Each quadrant header displays an edit button that flips the card to reveal a textarea. Enter one item per line, then press the "Done" button or hit Escape to save and flip back.

When a quadrant is opened for editing, the front face becomes inert and the textarea receives focus. On close, the component updates its internal .quadrants data, re-renders the front face content, and dispatches an empathy-map:update event with the changed quadrant name and items.

You can also control editing programmatically:

Data Mode

Load quadrant data from a JSON file via the src attribute, or set the .quadrants property programmatically. The JSON schema supports top-level metadata plus quadrant arrays, goals, and pain points.

Emotion Recognition

Items in the "feels" quadrant are checked against the EMOTION_META dictionary. When an item's text matches a known emotion key (case-insensitive), it renders as a colored pill with the corresponding emoji. This is the same emotion vocabulary used by <user-journey>.

Emotion Key Emoji Color
delighted 😄 #16a34a
satisfied 😊 #22c55e
hopeful 🙂 #84cc16
curious 🤔 #eab308
neutral 😐 #94a3b8
uncertain 😕 #f97316
confused 😵 #fb923c
frustrated 😤 #ef4444
angry 😠 #dc2626

Items that do not match a known emotion key render as plain text. You can mix recognized emotions with freeform text in the same quadrant.

CSS Custom Properties

Variable Default Description
--empathy-map-bg #ffffff Background color (used for editor and button backgrounds)
--empathy-map-text #1a1a1a Primary text color
--empathy-map-border #e0e0e0 Card border and grid gap color
--empathy-map-muted #666666 Secondary/muted text for labels and summary
--empathy-map-accent #0066cc Accent color for focus rings and interactive elements
--empathy-map-card #f8f9fa Card and quadrant background color
--empathy-map-radius 16px Outer card border radius
--empathy-map-says #3b82f6 Says quadrant accent color (top border)
--empathy-map-thinks #8b5cf6 Thinks quadrant accent color (top border)
--empathy-map-does #f59e0b Does quadrant accent color (top border)
--empathy-map-feels #ef4444 Feels quadrant accent color (top border)

Events

Event Detail When
empathy-map:ready { title, persona } Fires after the component finishes rendering (including after JSON load)
empathy-map:update { quadrant, items } Fires when a quadrant is closed after editing, with the quadrant name and updated items array
empathy-map:upgraded — Once after first connect. Wait for this before assigning .data from a framework.
empathy-map:data-changed { data, source: 'property' } After .data assignment.

JavaScript API

<empathy-map> follows the HTML-first + JS-first dual-mode contract. Reactive consumers (Montane, Lit, Solid, etc.) should wait for empathy-map:upgraded before assigning .data. The individual .quadrants, .goals, and .painPoints setters remain for fine-grained updates; use .data when you have the whole record.

PropertyTypeDescription
.data { title?, persona?, personaId?, summary?, quadrants?, goals?, painPoints? } Whole-record assignment. Idempotent; round-trips through the getter.
.quadrants { says, thinks, does, feels } Replace just the four quadrant arrays.
.goals / .painPoints string[] Replace just the goals / pain-points list.

Accessibility

  • The outer card renders as an <article> element for semantic grouping
  • Each quadrant is a <section> with a visible heading for screen reader navigation
  • Decorative quadrant icons use aria-hidden="true"
  • In editable mode, the edit button has an aria-label of "Edit [quadrant name]"
  • When a quadrant flips to edit, the front face becomes inert and focus moves to the textarea
  • The textarea has an aria-label describing its purpose
  • Respects prefers-reduced-motion: reduce by disabling flip transitions
  • Uses container-type: inline-size and stacks to a single column at narrow viewports (<500px)
  • Print styles hide edit buttons and editor faces for clean print output

Related
↑