# State documentation template

Copy this table into your flows document (UX_FLOWS.md) and fill it in for each screen or component.

| State | When it appears | What the user sees | What they can do | Microcopy | Accessibility |
|---|---|---|---|---|---|
| Empty | The first time the user arrives, or when there is no content yet. | A message that explains the empty state | Create the first item | You don't have any projects yet / Create your first one to see your metrics here. / [Create project] | Product best practice. No direct WCAG criterion. |
| Loading | Between the user requesting data and it arriving, typically 1 to 10 seconds. | The content's structure as a skeleton | Wait; cancel if it takes long | Loading projects… | WCAG 4.1.3 (AA): status messages must be perceivable without receiving focus. |
| Error | The network or server fails and the action doesn't complete. | What failed and what was kept | Retry or save a draft | We couldn't save your changes / The connection dropped. What you typed is still here. / [Try again]  [Save draft] | Nielsen's heuristic 9: help users recognize, diagnose, and recover from errors. |
| Disabled | An action isn't available yet because something is missing. | The inactive control and what's missing | Complete the requirement | Enter a name to continue | WCAG 1.4.13 (AA) if you use a tooltip. WCAG 1.4.3 exempts inactive components from contrast requirements. |
| Focus | The user navigates with a keyboard or another input device. | A visible ring on the active element | Navigate with the keyboard | (No text: it's a visual state) | WCAG 2.4.7 (AA) focus visible. WCAG 2.2 adds 2.4.11 (AA): focus not obscured. |
| Overflow | The content is longer (or shorter) than expected. | Text truncated per the defined rule | See the full text (hover and focus) | (Define the rule per component: 1 line with ellipsis, or up to 2 lines) | Related: WCAG 1.4.10 (AA) reflow, no two-dimensional scrolling at 320 px. |
| No results | A search or filter finds no matches. | The search term and a suggestion | Clear filters or change the search | No results for “red sneakers” / Try another word or remove a filter. / [Clear filters] | WCAG 4.1.3 (AA): changes in results must be announced to screen readers without moving focus. |
| Validation | The user types a value the system can't accept. | The error next to the field, as text | Fix the value | Enter an email with @, for example ana@mail.com | WCAG 3.3.1 (A) and 3.3.3 (AA); 1.4.1 (A): don't use color alone to communicate the error. |
| Success | The user completes an action and needs to know it worked. | Confirmation of what was done | Move on to the next step | Changes saved / [View project] | WCAG 4.1.3 (AA): status messages must be announced without moving focus. |
| Offline | The device loses the network or the server doesn't respond. | The offline notice and the last saved content | Retry or continue with what's available | You're offline. Showing what you last saved. / [Try again] | Product best practice. No direct WCAG criterion. |
| Session expired | The session is about to end or already ended. | A notice with the time remaining | Stay signed in or sign out | Your session is about to end / It will close in 2 minutes. We saved your changes as a draft. / [Stay signed in]  [Sign out] | WCAG 2.2.1 (A): warn and let users extend the time, with the exceptions the criterion defines. |
| Selected | The user chooses one or more options from a list or group. | An indicator that doesn't rely on color alone | Change or clear the selection | ✓ Selected | WCAG 1.4.1 (A): don't use color alone. WCAG 1.4.11 (AA): 3:1 contrast for interface components. |

Fill in one row per state and per component. If a state doesn't apply, write “Not applicable” and say why.