> ## Documentation Index
> Fetch the complete documentation index at: https://docs.findmydata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UX redesign — personas & activities

> Grounding artifact for the Find My Data UI redesign: who uses the platform, what they need to do, and how that should shape the information architecture.

# UX redesign — personas & activities

**Status:** the redesign this document grounded is **complete and shipped** —
the "Registry" interface, released 26.7.19.0–.2 (see `STATUS.md` §"UI redesign —
Registry" and the sibling specs [`domain-owner-ia.md`](domain-owner-ia.md),
[`design-language.md`](design-language.md),
[`relational-views.md`](relational-views.md)). This document remains the
**persona reference**: who uses the platform, what each role needs to do, and
the authorization facts any future UI work must respect. It is grounded in the
**actual** role/capability model in
[`packages/shared/src/capabilities.ts`](../../packages/shared/src/capabilities.ts),
not an idealized one.

***

## 0. What the authorization model means for UX

Three facts about the system shape every design decision:

1. **Five visible roles, but enforcement is by *capability*, not role.** A person
   can hold several roles at once. The UI should **compose from what a user *can
   do*** (their capabilities) and gracefully hide the rest — not hardcode one
   fixed screen-set per role.
2. **Capabilities are *scoped*: `tenant`-wide or `domain`-only.** The Domain Owner
   sees **only their domains'** data; the UI must make scope obvious and make
   cross-domain leakage impossible.
3. **The content boundary defines who sees what.** Some roles **deliberately never
   see content**: admins run the machine, auditors read the trail. Only the Domain
   Owner (and the Approver, partially) touch evidence — and even then, excerpts are
   **redacted**. "Never show content to a role that shouldn't see it" is a hard
   rule, not a preference.

The five roles: `platform_admin`, `governance_admin`, `domain_owner`,
`remediation_approver`, `auditor`.

***

## 1. Data Domain Owner — the core persona

*The accountable business owner of a data domain (HR, Finance, Legal…). Everything
they see is **domain-scoped**. Their job: know what sensitive data they own, turn
the system's guesses into ground truth, and drive it to a safe state.*

**Capabilities (all `domain`-scoped):** `governance.taxonomy.read`,
`asset.metadata.read`, `asset.evidence.summary.read`, `asset.evidence.excerpt.read`,
`asset.source.open`, `review.read`, `review.decide`, `review.batch`, `finding.read`,
`analyst.query`, `model.dataset.contribute`, `action.draft`, `action.submit`,
`scan.job.read`.

Activity clusters (the natural "jobs to be done"):

### A. Orient — "what needs me right now?" *(daily entry point)*

* Review decisions waiting on me
* New / critical findings in my domain
* Actions I've drafted and their status
* What changed recently (new sensitive data, new exposure)

### B. Understand my landscape — "what am I accountable for?"

* Inventory of information types in my domain (SSNs, background checks, salaries…) and where they live
* Sensitivity / risk distribution; exposure (org-wide links, external sharing)
* Label coverage & gaps ("what's unlabeled?")
* Provenance mix — owner-confirmed vs model-inferred vs unreviewed
* Trend over time (are we getting more or less exposed?)

### C. Review & confirm classifications — the core loop *(judgment → truth)*

* Work the review queue, one candidate at a time
* See evidence: summary + **redacted** excerpts; why the model thinks so
* Open the source document in place
* Decide: *mine* / *not a match* / *need more evidence*; batch-decide similar items
* See how a decision **propagates** to related/duplicate items ("byte-identical copies")

### D. Investigate & answer questions — the analyst

* Ask scoped questions ("all SSNs shared org-wide in my domain")
* Drill into a single asset: versions, permissions/exposure, duplicates, fingerprints, risk breakdown

### E. Act — drive to a safe state

* Turn a finding into a **drafted** remediation action (relabel, restrict sharing…)
* Submit it for approval; track status
* *(drafts & submits, but does **not** approve — segregation of duties)*

### F. Improve the model *(light-touch)*

* Contribute confirmed examples to training datasets — mostly a byproduct of C-review

**What a Domain Owner cares most about (their motivations):**

1. *"Am I exposed?"* — over-shared, unlabeled, or high-risk sensitive data
2. *"What's waiting on me?"* — minimize review burden; make each decision fast and confident
3. *"Can I prove we're in control?"* — coverage, attestation, a trend that's improving
4. *"Fix it"* — a clear, low-friction path from problem → remediation

***

## 2. Governance Admin — the program steward *(tenant-wide)*

*Owns the taxonomy, the ownership program, and detector quality across the tenant.*

**Capabilities:** taxonomy read/propose/approve/admin, `governance.policy.read/ingest`,
`governance.owner.assign/attest`, `governance.usage.read`, `model.dataset.curate`,
`model.release.propose/approve`, `finding.read`, `tenant.profile.read/write`,
`identity.directory.read`.

* **Taxonomy & policy** — define/approve information types & business domains; ingest policy
* **Ownership program** — assign domains to owners, drive attestation, watch coverage
* **Model/detector lifecycle** — curate datasets, propose/approve detector & model releases
* **Program oversight** — tenant-wide findings, AI usage & cost, adoption
* *Cares about:* consistent classification, every domain owned & attested, model quality trending up

## 3. Platform Admin — the operator *(tenant-wide; runs the machine, sees no content)*

**Capabilities:** `connector.configure/test`, full `scan.job.*`, `operations.read`,
`tenant.profile.read/write`, `identity.directory.read`, taxonomy/usage read.
*Deliberately NO evidence/review/excerpt.*

* **Connect sources** — configure/test connectors (M365, OneDrive, Azure Blob/Files, SMB, SQL, Google Drive, Box) with least-privilege selections
* **Run & control scans** — create / pause / resume / cancel / retry / monitor jobs
* **Operate** — fleet health, throughput metrics, change-notification subscriptions
* **Tenant & identity setup** — tenant profile, identity directory, sign-in config
* *Cares about:* sources connected, scans healthy and current, nothing over-permissioned

## 4. Remediation Approver — the change gate *(tenant-wide; narrow & high-stakes)*

**Capabilities:** `finding.read`, `action.approve`, `action.cancel`,
`asset.metadata.read` (all tenant). *No drafting; no broad evidence/excerpt access.*

* **Approve / reject** remediation actions in an approval queue
* See the context behind each proposed change: the finding + target asset metadata + risk
* *Cares about:* is this change safe, correct, and authorized before it touches real content?

## 5. Auditor — read-only assurance *(tenant-wide; no mutation, no excerpts)*

**Capabilities:** `audit.read`, taxonomy read, `governance.policy.read`,
`finding.read`, `scan.job.read`, `operations.read`, `governance.usage.read`.

* **Audit trail** — who did what, when (immutable log)
* **Control evidence** — findings, taxonomy/policy state, scan coverage, operations, AI usage
* *Cares about:* provable governance, segregation of duties, compliance evidence

***

## 6. Cross-cutting design principles

* **Compose by capability, not role.** Surface actions a user *can* do; hide the
  rest. One person may be owner + approver — the nav should reflect the union of
  their capabilities, cleanly.
* **Scope must be visible and safe.** A Domain Owner should always feel "this is
  *my* domain." Never risk showing another domain's content or counts.
* **Persona ≠ page.** The Domain Owner's six clusters (A–F) are the primary IA
  candidate; the other four personas are narrower and may fold into fewer surfaces.
* **Content boundary is a hard constraint.** Redacted excerpts only; roles without
  evidence capability never see content, anywhere.
* **Confidence over completeness.** The review loop (cluster C) is the product's
  center of gravity — reducing decision friction is the highest-leverage UX win.

***

## 7. Current UI surface (the redesign baseline)

Today's `packages/web` pages and their nav gating (from `App.tsx`), grouped as the
sidebar currently groups them:

| Nav group            | Page (route)                     | Shown to                           | Primarily serves                 |
| -------------------- | -------------------------------- | ---------------------------------- | -------------------------------- |
| —                    | Home (`/home`)                   | everyone                           | all (role-shaped summary)        |
| **Find & Confirm**   | My Data Landscape (`/landscape`) | domain owners                      | Domain Owner (B)                 |
|                      | Review (`/review`)               | domain owners                      | Domain Owner (C)                 |
| **Connect & Govern** | Findings (`/findings`)           | everyone                           | Owner (E) / Approver / Auditor   |
|                      | Analyst (`/analyst`)             | domain owners                      | Domain Owner (D)                 |
|                      | Actions (`/actions`)             | everyone                           | Owner (E) / Approver (4)         |
|                      | Governance (`/governance`)       | governance\_admin, auditor         | Governance Admin (2)             |
|                      | Model releases (`/models`)       | governance\_admin                  | Governance Admin (2)             |
| **Administer**       | Setup & config (`/setup`)        | platform\_admin, governance\_admin | Platform Admin (3)               |
| **Operate**          | Operations (`/operations`)       | platform\_admin, auditor           | Platform Admin (3) / Auditor (5) |
| —                    | Audit trail (`/audit`)           | auditor                            | Auditor (5)                      |
| (detail)             | Asset detail (`/assets/:id`)     | capability-gated                   | Domain Owner (D)                 |
| (auth)               | Login (`/login`)                 | —                                  | —                                |

**Observations to carry into the redesign** (not yet decisions):

* The current sidebar groups by *system concern* ("Connect & Govern") rather than
  by *the user's job*. Findings/Analyst/Actions are all Domain-Owner work but sit
  under a governance-flavored group — a likely reorganization target.
* Nav is gated on `me.roles` / `ownedDomains.length` today; moving to
  capability-driven composition (principle #6.1) would make multi-role users and
  future roles cleaner.
* Home is the one shared surface and already tries to be role-shaped — a strong
  candidate to become the true capability-composed "orient" hub.

***

## 8. Open questions / next step

Start with the **Data Domain Owner**: map clusters A–F to a concrete
navigation + screen structure, decide what the "orient" landing surfaces first,
and how scope (which domain) is expressed. Then work outward to the narrower
personas, checking each activity is addressed and nothing is orphaned.

**Update 2026-07-18:** done — the resulting IA (object-first minimal nav,
`/d/:domainId` path scope, capability-composed sidebar, seven-module orient
home) is specified in [`domain-owner-ia.md`](domain-owner-ia.md), with three
open decisions flagged at its end. Mockups: "FMD owner IA mockups" artifact.

**Update 2026-07-18 (round 2):** visual identity + review input decided — the
**Registry** design language (archive paper / iron-gall ink / ledger green,
pencil-vs-ink provenance grammar, seal motif, Besley + Libre Franklin + IBM
Plex Mono, 1.25px stroke icon system) and the **Ask, Then Refine** decision
control (three plain-speech cards, numbered shortcuts removed, earned keyboard
hints). Spec: [`design-language.md`](design-language.md); mockups artifact
version `v2-registry-identity`.

**Update 2026-07-18 (round 3):** relational visualizations decided — two
engraved plates ship in the Registry register: **Plate IV "the Family Plate"**
(the reach of one decision: relation channels I/II/III, apparatus margin,
exposure ticks, propagation-stays-pencil honesty rule; review batch drawer +
asset-detail Family tab) and **Plate II "the Reach Plate"** (info types →
audience-reach bands, red rule = beyond the organisation; landscape hero),
plus a condensed home strip. Spec: [`relational-views.md`](relational-views.md);
artifact version `v3-relational-plates`. Next step: resolve the open decisions,
then implement: token sheet + nav shell + scope boundary → orient home →
review workbench → plates (A first — receipt mode needs zero new backend).