Context
AppCMS brand image slots allow users to upload a new asset or apply one from the library.
For resizable slots, persisting the source image alone is not sufficient to make the final rendered image deterministic across clients. Until resize is executed, downstream generated variants may still point to older outputs. This created ambiguity where users could believe the update was complete, then refresh and still observe previous imagery.
We needed an explicit runtime contract that communicates this intermediate state and prevents silent false-success expectations.
Decision
For resizable brand image slots, the system now treats "asset changed" and "resize completed" as two distinct states.
- After a successful upload or library-apply action on a resizable slot, that slot is marked as resize-pending.
- Resize-pending must be visible at slot level through persistent UI state (status badge and emphasized resize affordance).
- A warning message must explicitly state that resize is required and that a refresh before resizing may still show the previous resized image.
- Resize-pending is cleared only when resize succeeds, when the slot asset is deleted, or when brand data is refetched.
- Non-resizable slots do not participate in this contract.
Consequences
- Users receive explicit feedback that the update is incomplete until resize runs.
- Slot-level visibility localizes the warning to the affected field instead of creating global ambiguity.
- The flow intentionally adds one required action for resizable slots, trading convenience for correctness and predictability.
- Because resize-pending is UI-runtime state, it is not a durable backend flag and depends on local session flow.
Notes
- This ADR covers interaction contract and state semantics, not resize algorithm details.
- Related behavior is covered by targeted tests in the AppCMS brand image hook and slot UI suites.