UX Personas
Status: v1.0 · Owner: Design Lead + Product Owner · Gate input: G1 Derived from the SFMS domain (ISO 41001 Smart FM), the KTC reference engagement, and the role/RBAC model in
Phase_2.md.
Personas are the lens for every design decision. When a screen is ambiguous, we ask: "What does Mei need here? What does Daniel need here?" Each persona maps to one or more RBAC roles (owner, admin, member, viewer) so design and permissions stay aligned.
The six personas below are ordered by how much time they spend in the product daily — design effort is weighted accordingly.
P1 — "Tomás" · Maintenance Technician (field) ★ highest daily usage
| Role | member (work-order execution scope) |
| Primary device | Phone (Android mid-range / older iPhone), sometimes a rugged tablet |
| Context | On-site: plant rooms, rooftops, basements. Bad lighting, gloves, noise, intermittent or no signal. |
| Frequency | All day, in short bursts between physical tasks |
| Tech comfort | Moderate. Wants the app to get out of the way. |
Goals
- See my work orders for today, sorted by priority and location.
- Execute an inspection checklist quickly, attach a photo, capture a signature, scan an asset QR.
- Submit even with no signal and trust it will sync.
Pains
- Tiny tap targets and dense desktop tables crammed onto a phone.
- Losing work because the connection dropped.
- Not knowing whether something saved.
What "good" looks like for Tomás
- Bottom-nav Tasks lands directly on his queue. One tap to open, one prominent action to start.
- Offline is explicit and reassuring: a clear "Saved on device · will sync" badge, never a silent failure.
- Camera, signature, and scan are one tap each with large controls. Touch targets ≥ 44px.
Design implications: drives Phase 8 mobile patterns, offline state design, the work-order execution flow, and the sticky action bar. If Tomás's flow isn't excellent, the product isn't.
P2 — "Mei" · Facility Manager / FM Supervisor ★ high daily usage
| Role | admin (site/building scope) |
| Primary device | Desktop (dual monitor) + phone for approvals on the move |
| Context | FM office, occasional walk-arounds; runs the daily/weekly ops rhythm (PDCA). |
| Frequency | Several focused sessions per day |
| Tech comfort | High for FM tooling; not a developer. |
Goals
- Glance at site health: open work orders by priority, SLA breaches, anomalies, planned-vs-reactive ratio.
- Assign and reassign work; approve requests from her phone.
- Build/tune dashboards for her team and for the monthly review.
- Trust the KPIs she reports upward (MTTR, MTBF, SLA compliance).
Pains
- Dashboards that need an engineer to change.
- KPIs she can't drill into or doesn't trust the provenance of.
- Approvals that pile up because they're buried.
What "good" looks like for Mei
- A landing dashboard with PDCA KPI cards that are glanceable and clickable straight to the underlying records.
- A drag-and-drop dashboard editor she can actually use — curated inspector copy, sensible defaults, no JSON.
- Mobile approvals inbox with one-tap approve/reject and swipe actions.
Design implications: primary driver of Phase 5 dashboard editor UX, KPI card design, drill-through, and the approval inbox. Maps to the "FM Ops" dashboard template.
P3 — "Daniel" · Platform / Tenant Administrator
| Role | owner / admin (tenant-wide) |
| Primary device | Desktop |
| Context | Sets up the tenant: users, roles, branding, connectors, gateways, AI settings, security policy. |
| Frequency | Heavy during onboarding, then periodic |
| Tech comfort | High — semi-technical; comfortable with API keys, OIDC, integrations. |
Goals
- Stand up the tenant fast: invite users, define roles, apply brand kit, connect a BMS gateway, import the asset ledger.
- Keep it secure and auditable: MFA enforcement, API-key rotation, audit review.
- Configure AI provider, budgets, and no-egress policy.
Pains
- Onboarding that's a maze of disconnected settings.
- Bulk imports that fail opaquely on row 4,000.
- No clear audit trail.
What "good" looks like for Daniel
- A guided onboarding checklist ("brand → users → roles → connect data → import ledger") with progress.
- Import wizards with preview, dry-run, and a downloadable error report (per
Phase_3.md§5.6). - Admin screens (Users, Roles, API Keys, Audit, Settings) that share one consistent layout and a clear audit story.
Design implications: Phase 2 admin screens, Phase 3 import wizards + reconciliation UI, tenant settings/branding UI, AI settings.
P4 — "Priya" · Operations Centre Operator (NOC / managed service)
| Role | member / viewer (possibly cross-tenant with explicit consent) |
| Primary device | Multi-monitor wall + War Room display |
| Context | Monitors many sites/tenants live; first responder to alerts and anomalies. |
| Frequency | Continuous (shift-based) |
| Tech comfort | High operationally. |
Goals
- Watch live telemetry, alert feeds, and workflow status across sites on a wall.
- Spot anomalies fast; trigger or hand off response.
- Run TV mode and War Room without babysitting.
Pains
- Dashboards that drift, leak memory over a 24h shift, or hide the alert that matters.
- Cross-tenant views that aren't clearly labelled (whose alarm is this?).
What "good" looks like for Priya
- TV mode: zero chrome, auto-rotate playlist, high-contrast, readable at distance, stable for 24h+ (soak-tested).
- War Room: multi-pane, each pane clearly labelled with tenant/site, alert feed always visible.
Design implications: Phase 5 TV + War Room modes, alert feed widget, high-contrast/distance-legibility rules, cross-tenant labelling safeguards.
P5 — "Akiko" · Executive / Asset Owner (read-mostly)
| Role | viewer |
| Primary device | Laptop + phone |
| Context | Wants the monthly story: cost, compliance, uptime, risk. Doesn't operate the system. |
| Frequency | Weekly/monthly |
| Tech comfort | Low patience for tooling; high expectations for clarity. |
Goals
- An Executive Summary dashboard: cost per asset/sqm, uptime, SLA compliance, planned-vs-reactive trend.
- Pull or receive a clean monthly KPI report (PDF/Excel).
- Ask plain-language questions ("how did reactive work trend this quarter?") and get a cited answer.
Pains
- Operational noise; too many numbers without a narrative.
What "good" looks like for Akiko
- A calm, executive-themed dashboard template; few numbers, big, trended, with context.
- AI chat that answers in plain language with citations (Phase 6 RAG).
- Scheduled report that just arrives, branded.
Design implications: Executive Summary dashboard template, report templates, AI chat tone/citations, i18n (EN/JA) quality.
P6 — "Sam" · Integration Developer (partner / third party)
| Role | API consumer via tenant-scoped API key |
| Primary device | Desktop / IDE |
| Context | Builds an integration against the Atlas API; never sees the product UI much. |
| Frequency | During integration, then maintenance |
| Tech comfort | Developer. |
Goals
- Discover the API, authenticate, and get a working call in minutes.
- Generate a typed SDK; rely on a stable, versioned contract.
Pains
- Stale or incomplete API docs; drift between spec and reality.
What "good" looks like for Sam
- Scalar / Swagger UI at
/api/docswith "Try it out", a quickstart, and the@gp/atlas-sdkready to import. - Spec is the source of truth (CI-enforced no drift, per
Phase_2.md).
Design implications: developer-portal UX (Scalar theming, quickstart page), API-key management screen, error-response design.
Persona → role → primary surface map
| Persona | RBAC role | Primary surfaces | Phase that serves them |
|---|---|---|---|
| Tomás (Technician) | member | Mobile Tasks, WO execution, offline, approvals | P4, P8 |
| Mei (FM Supervisor) | admin | Dashboards, WO management, approvals, KPIs | P4, P5, P7 |
| Daniel (Tenant Admin) | owner/admin | Onboarding, admin screens, imports, settings | P2, P3 |
| Priya (NOC Operator) | member/viewer | TV mode, War Room, alert feed | P5 |
| Akiko (Executive) | viewer | Executive dashboard, reports, AI chat | P4, P5, P6 |
| Sam (Developer) | API key | Developer portal, SDK, API keys | P2 |
Accessibility & inclusivity personas (cross-cutting)
These are not separate users — they are conditions any persona may have, and they are mandatory design constraints, not edge cases:
- Low vision / colour-vision-deficient: never rely on colour alone (status uses icon + label + colour). Contrast ≥ 4.5:1 text, ≥ 3:1 UI/graphics.
- Keyboard-only / switch users: full keyboard parity; visible focus rings; logical tab order; skip links.
- Screen-reader users (NVDA, VoiceOver): semantic landmarks, ARIA on custom widgets, live-region announcements for async results.
- Motor-impaired / gloved field users: 44px targets, forgiving hit areas, no precision drag required for core tasks (drag is an enhancement, not the only path).
- Bilingual (EN/JA) users: layouts tolerate longer Japanese strings; no truncation of critical labels; locale-correct dates/numbers/units.
These map directly to the WCAG 2.2 AA gate and the UX_patterns.md accessibility section.