# Change settings and preferences

**Flow key:** `settings-preferences`

## Outcome

An authorized user changes one scoped preference and sees predictable persistence, synchronization, defaults, conflicts, and rollback across devices.

## Actors

- User
- Settings/profile service
- Organization policy
- Connected devices

## Preconditions and entry points

- A synthetic account has known user, tenant, and device defaults.
- Managed versus editable settings and sync policy are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Preferences | theme dark, locale `en-US`, notifications enabled | unset/default, RTL locale, reduced motion, granular channels |
| Scope | user preference | device-only, workspace, organization-managed |
| Devices | browser A and browser B | offline device, stale version, mobile |
| Policy | user-editable | locked by admin, deprecated setting, feature flag off |
| Concurrency | one edit | two tabs/devices choose different values |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open settings. | Current effective value, source/default, scope, and managed state are accurate. |
| 2 | Change one preference. | Preview/description explains consequence and does not mutate unrelated settings. |
| 3 | Save or rely on explicit autosave. | One version commits with truthful success and undo/reset if promised. |
| 4 | Refresh and open another device/session. | Synchronization follows user/device/workspace scope and conflict policy. |
| 5 | Change locale/theme/accessibility preferences. | The current screen remains usable during transition. |
| 6 | Reset to default or admin changes policy. | Effective value and source update without leaving stale client state. |

## Alternate paths

- Immediate toggle
- Save/cancel form
- Device-local preference
- Organization-managed setting
- Reset all defaults

## Failure and recovery paths

- Autosave races rapid changes
- Network fails after optimistic UI
- Two devices conflict
- Deprecated value cannot load
- Managed setting remains mutable via API

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [form composition](../../items/controls/form-composition.md)
- [policy](../../items/automation/policy.md)
- [localization and internationalization](../../items/quality/localization-and-internationalization.md)
- [accessibility](../../items/quality/accessibility.md)

[Back to Engagement and support flows](index.md)
