/balise-ui-states

name: balise-ui-states
description: Audits, designs, implements, and verifies the relevant missing states of interfaces and flows, including ideal, empty, partial, loading, success, error, offline, permission, stale, optimistic, and interaction states. Use for Figma files, screenshots, specifications, prototypes, frontend code, design systems, or rendered products that cover only the happy path, leave users without feedback or recovery, or need an implementation-ready state model.

UI States

Complete the state system around an interface without mechanically generating every possible state. Treat states as a temporal model with triggers, preserved context, exits, recovery, and transitions—not as a gallery of disconnected screens.

Operating contract

• Preserve source designs, components, code, data, and behavior unless the user asks for direct edits.
• Scope work to the selected surface or requested flow. Ask one focused question only when the missing product fact would materially change the result.
• Reuse existing components, tokens, variables, copy conventions, error models, and state-management patterns.
• Distinguish **observed**, **implemented**, **statically verified**, **runtime verified**, **proposed**, and **unknown**.
• Never invent API behavior, permissions, timings, progress percentages, persistence guarantees, or recovery semantics as facts.
• Prefer the smallest state boundary that communicates the real operation. Do not block an entire screen for a component-level update.
• Keep user work and valid data when errors occur. Never use a reset as the default recovery.
• Do not claim accessibility, production behavior, or backend correctness from a static frame alone.

Choose the mode

Infer the mode from the request. State the choice briefly when it changes what will be edited.

| Mode | Action | | --- | --- | | **Audit** | Inventory current states, identify material gaps, and prioritize them without editing. | | **Design** | Create a proposed state matrix, transitions, and copy in a design artifact. | | **Implement** | Add the state model to source code while preserving project architecture. | | **Repair** | Correct incomplete, misleading, inaccessible, or dead-end states already present. | | **Verify** | Exercise implemented states and report evidence, gaps, and untested paths. | | **Complete** | Audit, design or implement, then verify within the available surface. |

Load only the needed references

• Read [state-taxonomy.md](references/state-taxonomy.md) when choosing states or distinguishing empty, partial, error, access, and sync conditions.
• Read [transitions-and-recovery.md](references/transitions-and-recovery.md) for async work, retries, optimistic updates, rollbacks, timeouts, or multi-step flows.
• Read [accessibility-runtime.md](references/accessibility-runtime.md) when implementing or verifying focus, announcements, disabled controls, reduced motion, or runtime behavior.
• Read [figma-patterns.md](references/figma-patterns.md) for Figma component, variant, Auto Layout, prototype, and annotation decisions.
• Read [implementation-handoff.md](references/implementation-handoff.md) for source discovery, state machines, API dependencies, acceptance tests, or engineering handoff.
• Use [state-contract-template.md](assets/state-contract-template.md) when a durable state inventory or handoff is requested.

Workflow

1. Frame the product moment

Identify:

• the selected screen, component, control, or flow;
• the user goal and the product value expressed by the ideal state;
• what happens immediately before and after the surface;
• data sources, user actions, permissions, network work, and persistence involved;
• the question being tested and the intended audience for the result.

Do not start with a universal checklist. A static settings page, a search result, a collaborative editor, and a payment submission require different matrices.

2. Inspect the real system

For design artifacts, inspect adjacent frames, sections, components, variants, properties, variables, libraries, prototype links, annotations, and naming conventions.

For code, locate the canonical component, route, state owner, data-fetching layer, mutations, form validation, error boundary, translations, analytics, tests, and design tokens. Trace rendered copy and behavior back to their source before editing.

Record what already exists. Similar-looking frames do not prove distinct runtime states; similarly, an absent frame does not prove an implementation is missing.

3. Build a proportional state matrix

Start with the ideal state as the value and hierarchy reference. Add a state only when its trigger is plausible and its omission could create confusion, loss, blocked progress, or implementation ambiguity.

Evaluate these families:

1. **Value:** ideal, first-use empty, user-cleared, no results, partial. 2. **Processing:** initial loading, inline loading, progress, updating, success. 3. **Failure:** validation, recoverable error, terminal error, timeout, offline. 4. **Access:** signed out, permission denied, restricted, request pending. 5. **Synchronization:** stale, optimistic, queued, conflict, rollback. 6. **Interaction:** default, hover, focus, active, selected, disabled, dirty.

Mark each candidate **required**, **conditional**, **already covered**, **not applicable**, or **unknown**. Explain required and unknown decisions; do not create not-applicable variants.

4. Define the state contract

For every required state, specify:

• trigger and scope;
• data and content shown;
• what remains visible and interactive;
• primary and secondary actions;
• user input or work preserved;
• exit condition and next state;
• retry, fallback, rollback, or escalation path;
• accessibility behavior;
• product or engineering dependency;
• evidence level.

An error without recovery, a loading state without scope, or a success state without a durable consequence is incomplete.

###