On this page
Scott
A UI state matrix maps the conditions that change an interface to what a person sees, can do, and keeps from the previous step. It helps a team distinguish loading, empty, error, partial, and success states before those cases turn into missing screens or ambiguous behavior.
Use Pixso UI design collaboration to keep the matrix, frames, and review decisions together. This example maps a project document upload, including a rejected file and a request whose result is not yet known.
1. Start with the task and its signals
Write one sentence describing the user goal, then list the signals that change the interface: data availability, request status, permissions, connectivity, viewport, and user input. This keeps a state matrix tied to a decision rather than a collection of generic component names.
The sample task is: “Upload the project brief and supporting documents, then confirm which files are available to the team.” In this example application, documents must be PDFs of 10 MB or less, an upload may contain several files, and each file has its own processing result. These are design requirements for the example, not Pixso upload limits.
Use three sample files throughout the design: brief.pdf (2 MB), research.pdf (4 MB), and notes.docx (1 MB). The last file should fail the format check. The two PDFs can succeed, fail, or remain unresolved independently. A single “upload failed” flag would lose information about the successful files.
2. Separate similar-looking states
An empty list may mean there are no records, a filter hides all records, or the request has not returned. A disabled control may reflect missing permission, an unmet prerequisite, or a temporary request. Give each cause its own row when the next action or message differs.
For uploads, distinguish transfer from processing. Reaching 100% transfer does not necessarily mean a file is available to the team. Also distinguish a confirmed rejection from a timeout: no response is not proof that the server rejected the file.
A completed matrix for the document upload
| State | Condition | Visible message and action | Preserve | Next state |
|---|---|---|---|---|
| First use | The document list loaded and contains no files | “No project documents yet.” Offer “Upload PDFs.” | Project context and upload requirements | File selection |
| Invalid selection | notes.docx fails the PDF check | “Choose a PDF for notes.docx.” Remove or replace that file. | The two valid PDF selections | Ready to upload |
| Uploading | Transfer has started for the selected PDFs | Show each filename and its transfer progress. Prevent another submission of the same selected batch. | File identities, project, and per-file progress | Processing or confirmed transfer failure |
| Processing | Transfer finished; availability has not been confirmed | “Processing research.pdf…” Do not label it ready. | The uploaded filename and request identity | Ready, rejected, or result unknown |
| Partial success | brief.pdf is ready; research.pdf was confirmed unsuccessful | “1 file ready. 1 file needs attention.” Explain the failed file and offer its recovery action. | The successful file and its team access | Retry only the failed file, or finish |
| Confirmed failure | The server confirms that the file was not stored | “research.pdf wasn't uploaded.” Offer “Retry upload.” | Other successful files; local selection where the browser permits it | Uploading |
| Result unknown | The response was lost and storage status is not known | “Checking whether research.pdf was uploaded…” Check its status before offering a fresh upload. | Filename and the request identity needed to reconcile the result | Ready or confirmed failure |
| Complete | Every submitted file has a confirmed result and the accepted files are ready | Summarize the actual outcome and expose the ready documents. Do not count rejected selections as uploaded. | Ready files and records of any confirmed failures left for later | View document or upload another batch |
| Permission denied | The server confirms that this person cannot upload to the project | “You don't have permission to add project documents.” Provide the project's access-request route if one exists. | Project context and any files already visible to the user | Access granted, or leave the upload task |
The matrix separates the selection from the submission. If notes.docx is rejected before upload, the result of submitting the remaining two PDFs is about two files, not three. Keep those counts consistent in the list, progress message, and final summary.
3. Connect rows to reviewable frames
Create frames for the first-use list, selected files, active transfer, processing, partial success, unknown result, and completed list. Use the same filenames and sizes in every frame. The matrix defines the conditions; the frames show whether people can understand them.
In Pixso, reuse a document row with a filename, status, and action area. Show brief.pdf as ready while research.pdf needs attention in the partial-success frame. Connect the “Retry upload” action only to the failed file's path. This makes the intended scope visible to reviewers without pretending the prototype performs a real upload.
Do not draw every theoretical combination. Two independent files can create many combinations, but you need separate frames only when the message, available action, retained information, or layout changes. The matrix can record equivalent combinations without duplicating the entire screen.
4. Design recovery and preservation
Every non-success state needs a useful next step or a clear reason why no action is available. Preserve confirmed results when another item fails. Keep the project and selected files visible while progress changes, and explain any information the user must provide again.
A retry is appropriate after a confirmed failure. After an unknown result, establish whether the first request succeeded before allowing another action that could create a duplicate. Engineering may handle this with request identifiers and duplicate-prevention rules; the design must show what the person sees while the result is reconciled.
Decide what happens after leaving or reloading the page. A browser may no longer expose the previously selected local file, so “Retry upload” may need to become “Choose the file again.” The interface should explain that requirement while preserving server-confirmed files. Do not promise cancellation, automatic resumption, or background uploads unless the application supports them.
5. Validate across width, input, and content
Review the same matrix with long filenames, narrow layouts, slower responses, keyboard navigation, and different permission levels. A filename should remain identifiable when its status wraps. Use text as well as color to distinguish ready, failed, and processing files.
Run a specific review task: select the three sample files, remove notes.docx after validation, submit the two PDFs, and recover from the failure of research.pdf. Ask the reviewer which files teammates can access and which action they would take next. If they retry the whole batch or think a processing file is ready, revise the status hierarchy or action labels.
For implementation, record focus behavior, how progress and completion are announced to assistive technology, and how status updates avoid repeatedly interrupting the user. A prototype communicates the intended flow; those runtime behaviors need verification in the actual application.
Keep the matrix next to the design it explains
Link each row to its frame and record the product rule that triggers it. When file types, permissions, or upload behavior change, update the affected states and messages together. This leaves the team with a concrete model of what can happen and how the interface responds.
