ping-mee-self-service-platform/_bmad-output/ux-designs/ux-ping-mee-self-service-platform-2026-10-15/EXPERIENCE.md

---
name: ping-mee Portal
status: final
updated: 2026-10-15
sources:
  - _bmad-output/prds/prd-ping-mee-self-service-platform-2026-10-15/prd.md
  - _bmad-output/architecture/architecture-ping-mee-self-service-platform-2026-10-15/ARCHITECTURE-SPINE.md
---

# ping-mee Portal — Experience Spine

## Foundation

Responsive web, server-rendered pages. Desktop and phone both work. UI system: Fluent 2 web components (version 3), built into the image. `DESIGN.md` is the visual identity reference and names the brand layer; this spine is the behavior. Users are family and friends who are not technical, so every page does one job and explains it. Languages: German and English. German has two address forms, formal "Sie" (default) and informal "du".

## Information Architecture

| Surface | Reached from | Purpose | Who |
|---|---|---|---|
| Startseite (dashboard) | Landing page, menu | Active announcements, account card, last announcements | everyone |
| Profil | Menu, account card | Edit first name, last name, display name, e-mail, telephone, mobile | everyone |
| Profilbild | Menu | Upload, crop, remove; shows Pending | everyone |
| Passwort | Menu | Change password | everyone |
| Ankündigungen | Menu, dashboard | Read current and past announcements | everyone |
| Benachrichtigungen | Menu | Opt in or out of announcement e-mails | everyone |
| E-Mail bestätigen / rückgängig | Link in an e-mail | Confirm or undo an e-mail change | link holder |
| Ankündigungen verwalten | Menu group "Veröffentlichen" | List, write, schedule, edit, withdraw | Publishers |
| Darstellung | Menu group "Administration" | Accent colour with contrast check, background image | Admins |
| Einstellungen | same | Portal name, session limits, throttle limits, audit retention | Admins |
| Protokoll | same | Read the audit log | Admins |
| Status | same | Backup age, failed e-mails, background jobs | Admins |
| Profile menu | Avatar, upper right | Theme, language, address form (German only), sign-out | everyone |

On phones the left menu opens from a menu button. Dialogs never stack more than one level deep. Every stated need has a surface, and every surface is reached by a flow below.

→ Composition reference: `mockups/key-dashboard.html`, `mockups/key-password.html`, `mockups/key-picture-pending.html`, `mockups/key-announcement-editor.html`, `mockups/key-admin-appearance.html`, `mockups/key-admin-status.html`, `mockups/key-admin-audit.html`. Spine wins on conflict.

## Voice and Tone

Microcopy. Brand posture lives in `DESIGN.md`. All text is translatable and kept in one translation file with three registers: German formal, German informal, English. The e-mails use the portal-wide default register. [ASSUMPTION: a per-device choice cannot reach server-sent mail.]

| Do | Don't |
|---|---|
| "Ihre Änderungen wurden gespeichert." | "Operation erfolgreich." |
| "Ihr neues Bild erscheint innerhalb von etwa 2 Stunden." | "Der Sync-Task läuft periodisch." |
| "Zu viele Versuche. Bitte warten Sie einige Minuten." | "HTTP 429" |
| "Das ist gerade nicht möglich. Bitte versuchen Sie es später erneut." | Directory, LDAP, token or other system words |
| Say what the action does and what happens next. | Leave the user guessing after a click. |
| Short sentences, one idea each. | Long explanations before the form. |

The informal setting changes only the form of address ("Sie" becomes "du", with matching verbs and possessives) and applies only to German.

## Component Patterns

Behavioral. Visual specs live in `DESIGN.md.Components`.

| Component | Use | Behavioral rules |
|---|---|---|
| Announcement banner | Dashboard | Shows every active announcement, newest first, severity in colour, icon and word. Cannot be dismissed while active. |
| Account card | Dashboard | Shows picture (with Pending chip if waiting), name, username, e-mail, telephone, "Passwort zuletzt geändert" from AD. Link to Profil. |
| Form | Profil, Passwort, Profilbild | Explains the effect of the action above the first field. Validates on submit, shows errors next to the field and in a summary at the top. Primary button shows a spinner while working and is disabled. |
| Password rules | Passwort | The rules read from the domain's password policy are listed before the user types. [New requirement: the portal reads the policy from AD.] |
| Sensitive action | Passwort, E-Mail change | Asks for the current password in the same form. Never remembers it. |
| Picture editor | Profilbild | Choose a file, crop to a square and adjust in the browser, then save. Accepts JPEG, PNG, HEIC, WebP up to 10 MB; says why when it refuses a file. |
| Rich text editor | Ankündigungen verwalten | Toolbar: bold, italic, heading, list, link. The text shows as the finished result. Stored as Markdown, sanitized when shown. |
| Importance | Announcement editor | Always set; default "Information". Cannot be left empty. |
| Recipient summary | Announcement editor | States how many users get the e-mail and why others do not (opted out, no address). |
| Contrast check | Darstellung | Shows contrast for light and dark. Below 4.5:1 shows a warning; saving stays possible. |
| Profile menu | Every page | Theme, language, address form (shown only in German), sign-out. Choices are stored per device and apply immediately. |
| Filter chips | Protokoll | One selected at a time; "Alle" by default. |

## State Patterns

| State | Surface | Treatment |
|---|---|---|
| Saved | Any form | A success message at the top: what was saved and what happens next. |
| Validation error | Any form | Message under the field, linked to it, plus a summary; focus moves to the summary. |
| Password rejected by policy | Passwort | The reason in plain words, for example "Das Passwort ist zu kurz." Nothing is changed. |
| Too many attempts | Passwort, E-Mail change, links, upload | "Zu viele Versuche. Bitte warten Sie einige Minuten." No technical detail; the pause is not shown in numbers. |
| Pending | Profilbild, dashboard | Yellow chip "Wird aktualisiert" and the two-hour note. If it lasts longer than the configured time: "Das dauert länger als erwartet." |
| Loading | Buttons | Spinner on the button; the page stays usable. Cold page loads are plain server-rendered pages with no skeleton. |
| Empty | Ankündigungen, lists | A friendly line, for example "Derzeit gibt es keine Ankündigungen." |
| Unavailable | Any action needing AD, the share or mail | "Das ist gerade nicht möglich. Bitte versuchen Sie es später erneut." Nothing changes. |
| Session ended | Any page | The next action leads to sign-in with "Aus Sicherheitsgründen wurden Sie abgemeldet." [ASSUMPTION] |
| Not allowed | Publisher or Admin page for a normal user | The page does not exist for them: no menu entry; a direct address shows "Dazu fehlt Ihnen die Berechtigung." |
| Link used or expired | Confirm and undo pages | "Dieser Link ist abgelaufen oder wurde schon verwendet." with a way back to the portal. |
| Contrast warning | Darstellung | Warning box with the reason; "Trotzdem speichern" and "Andere Farbe wählen". |
| Backup older than 26 hours / failed mail | Status | The value turns red with a sentence saying what it means. |
| No account match | Sign-in | A generic refusal; no hint whether the name exists. |

## Interaction Primitives

- **Keyboard:** everything works with the keyboard; the focus outline is always visible; a "Zum Inhalt springen" link is the first tab stop. Escape closes the profile menu and dialogs.
- **Touch:** targets are at least 44 px; no hover-only controls.
- **Preferences per device:** theme (Hell, Dunkel, System; default System), language (default from the browser; switchable), and the German address form (default formal). They live in the profile menu from the avatar in the upper right and take effect without leaving the page. They are not stored on the server.
- **Confirmation links:** a link opens a page that names the change; only a button press applies it.
- **Banned:** infinite scroll, hover-only actions, dialogs stacked more than one deep, countdown timers visible to ordinary users, any action that runs on opening a link.

## Accessibility Floor

Behavioral. Visual contrast lives in `DESIGN.md`. Target: WCAG 2.1 AA.

- Full keyboard use and a skip link.
- Colour is never the only signal; banners carry an icon and a word.
- Form errors are linked to their fields and announced to screen readers.
- Headings are in order; each page has one main heading.
- Labels are visible, never only placeholders.
- Text can be enlarged to 200 percent without loss of content.
- The Admin accent colour is checked for contrast before it can be applied, with a warning.

## Responsive & Platform

Two layouts. Wide: left menu plus content. Narrow (phones): content only, with the menu behind a menu button; label/value rows stack; the two-column card grids become one column. The break is around 720 px. [ASSUMPTION: exact breakpoint decided at build.] Dark and light follow the system by default.

## Inspiration & Anti-patterns

Inspiration: the Microsoft 365 admin center's settings pages (calm, one topic per page, explanations beside controls). Anti-patterns: dense admin tables for ordinary users; long walls of help text; jargon from directory services; many accent colours.

## Key Flows

Journeys mirror the PRD (UJ-1 to UJ-4).

- **UJ-1. Lena changes her password before it leaks.** Lena signs in through authentik and lands on the dashboard. She opens Passwort. The page tells her the effect (other devices are signed out, she gets an e-mail) and lists the rules. She enters her current password and the new one twice and presses "Passwort ändern". *Climax:* the page says her password was changed. *Resolution:* she receives a confirmation e-mail. *Edge:* a rule is broken; the reason shows in plain words and nothing changes.
- **UJ-2. Tom sets a profile picture from his iPhone.** On Profilbild Tom picks a HEIC photo, crops it square and saves. *Climax:* the page shows his current picture with the chip "Wird aktualisiert" and the two-hour note. *Resolution:* when the sync has run, the chip disappears. *Edge:* a 14 MB file is refused with a reason before upload.
- **UJ-3. Ebbe announces a maintenance window.** In Ankündigungen verwalten Ebbe writes a title, sets importance to Warnung, writes the text in the editor, sets the maintenance window and an expiry, and schedules it for the next morning. The recipient summary shows who will be e-mailed. *Climax:* at the scheduled time the banner appears on every dashboard and the e-mail goes out. *Resolution:* after the move he withdraws it. *Edge:* he corrects the end time and chooses "Benutzer erneut benachrichtigen".
- **UJ-4. Marie sees an e-mail change she did not make.** Marie opens the undo link from the notice at her old address. The page names the change and shows one button. *Climax:* she presses "Änderung rückgängig machen" and her old address is back. *Resolution:* she is told to change her password, her sessions end, and the Admin is notified.

## Open items

- The password rules text depends on reading the domain policy from AD; this is a new requirement for the PRD (FR-5) and the architecture spine (AD-2 read allow-list).
- The WYSIWYG editor changes PRD FR-16 and AD-16; the editor library is chosen at build and must be built into the image.
- Severity is required with the default "Information" (PRD FR-17 listed it as optional).
- The Einstellungen page was not mocked; it is a labelled list of fields with an explanation beside each.
- The session-ended message and the exact phone breakpoint are assumptions.