Complete ui states

Statecraft

The happy path is a demo. Recovery is the product.

Make each reachable UI state understandable, recoverable, reproducible, and consistent with the existing design. Own behavior, not visual direction. Do not redesign a product unless the user also asks for design work.

Core rules

• Map states from real dependencies and user actions. Do not paste a universal checklist onto every component.
• Treat a surface as a user-visible outcome such as search results, an uploader, a checkout step, or a settings form. Do not create a state map for every implementation component.
• Distinguish empty, blocked, conflict, degraded, failed, uncertain, and still-working conditions. Never present failure as empty or success.
• Preserve user input, selections, and previously usable data whenever doing so is safe.
• Treat "saved", "uploaded", "sent", and similar labels as durability claims. Do not report server success for work that exists only in memory or local storage.
• Explain what happened, what remains safe, and what the user can do next.
• Treat partial success as recoverable work, not merely a warning. Preserve completed items, retain the failed page or item identity, and expose a scoped action that can finish the missing work without repeating successes.
• Make retries safe. Prevent duplicate submissions and never imply a destructive action failed when its outcome is unknown.
• Define what repeated or overlapping actions mean: latest wins, first wins, queue, merge, or block. Never let a late result silently replace a newer one.
• Apply the overlap policy across different actions that write the same surface, not only repeated copies of one action. Refresh, filter, pagination, retry, and reconnect may still race with each other.
• Merge paged, retried, or resumed collections by stable item identity. Do not append duplicate logical items when response ranges overlap.
• Keep the submitted snapshot separate from edits made while it is in flight. A late acknowledgement may settle only the revision it actually represents.
• Separate view lifetime from operation lifetime. Closing a modal, navigating, reloading, and reconnecting must have explicit behavior when work can continue beyond the current view.
• Use the project's existing state, test, mock, component, and styling patterns before adding anything.
• Avoid new dependencies unless the existing stack cannot reproduce or verify a required state.
• Keep technical errors in logs. Show users plain, specific, actionable language.
• Keep accessibility and truthful feedback ahead of decorative motion.
• Treat a recovery method as incomplete until the rendered interface exposes and wires the action. Controller-only capability is not user recovery.
• Verify that the recovery control exists in real markup, has an accessible name, supports native keyboard activation, and handles missing optional elements intentionally.
• Preserve existing markup and event boundaries when they can support the behavior. Add or replace visual structure only when the requested state cannot be expressed accessibly otherwise.

1. Select the task mode

Choose one mode from the request:

• Build: implement the requested interface and its reachable states.
• Repair: trace the broken transition, fix the root state-model or recovery problem, and preserve existing behavior.
• Audit: inspect and report gaps without changing files unless the user explicitly asks for fixes.

Do not turn an audit into an implementation task.

2. Write the State Read

Before editing, write one short line:

State Read: <surface> depends on <dependencies>; the costly failure is <risk>; preserve <user work>; recovery must <action>.

Example:

State Read: checkout depends on inventory and payment; duplicate or uncertain charges are costly; preserve the cart; recovery must clarify whether payment happened before offering retry.

For a small repair, keep this line in working notes. For a larger build or audit, show it to the user.

3. Build the reachability map

Identify each meaningful surface and include only conditions that can actually happen:

• Idle: nothing has started yet.
• Pending: initial load, background refresh, or user action is in progress.
• Ready: usable content or a completed result exists.
• Empty: the request succeeded but produced no content.
• Degraded: stale or partial content remains usable.
• Blocked: authentication, permission, rate limit, prerequisite, or policy prevents progress.
• Conflict: two accepted versions or edits require reconciliation before work can safely continue.
• Error: the operation is confirmed to have failed.
• Uncertain: a consequential operation may have succeeded, but its outcome cannot yet be confirmed.
• Success: a user action completed and needs confirmation.

For detailed selection guidance, read references/state-model.md.

When work can outlive a request or view, or multiple writers can change the same data, read references/continuity.md.

For each included state, record:

1. Trigger: how the state becomes reachable.
2. Feedback: what the user sees or hears.
3. Preservation: what input, content, or progress remains.
4. Next action: retry, edit, sign in, request access, go back, cancel, or another real recovery.
5. Evidence: how the state can be reproduced and checked.

Use a compact table in working notes for small tasks. For multi-surface or high-risk flows, create a temporary JSON map and run:

python scripts/validate_state_map.py path/to/state-map.json --phase plan

Do not add a Statecraft artifact to the user's repository unless it is useful to the project or the user asks for it.

4. Define the recovery contract

For every non-ready state, answer:

• What happened?
• Is existing work or data safe?
• What can the user do now?
• What will retry repeat?
• Could the original action have succeeded despite the error?
• What happens if the user starts the action again before the first attempt settles?

Treat unknown outcomes separately from confirmed failures, especially for payments, publishing, deletion, booking, and account changes.

Never make safety a dead end. When an action stays blocked because its outcome is uncertain, preserve its operation identifier and provide a real reconciliation path: bounded polling, a status check the user can repeat, automatic resumption, or a support/status handoff. Disabling the action forever is not recovery.

Read references/recovery-patterns.md when writing recovery behavior or messages.

5. Implement without flattening the experience

• Keep the last usable content during a background refresh when it is not misleading.
• When a page or batch is only partly successful, keep its request identity, completed items, and missing scope. Retry or resume only the unresolved portion and deduplicate the merged result by stable identity.
• Match loading placeholders to the final structure when that structure is known.
• Place validation errors near their cause and keep entered values.
• Disable only actions that could create invalid or duplicate work.
• Keep cancel and navigation available when they are safe.
• Show empty states only after a successful empty response.
• Make durable failures persistent; do not rely on a disappearing toast as the only explanation.
• Give success feedback when the result is not otherwise obvious.
• Wire every promised next action through the actual view and event boundary. If state contains canRetry, canRecheck, or an equivalent capability, render and connect the corresponding control.
• Keep stable status and alert containers in the initial markup when dynamic announcements matter; update their content instead of introducing the live region only after the event.
• Use explicit state variants when several booleans could create impossible combinations.
• Cancel superseded reads when supported, or tag attempts and ignore stale completions. Do not depend on responses arriving in request order.
• Coordinate operations that share a result collection. Either block incompatible combinations or give refresh, filter, pagination, and recovery a common authority/merge rule so one completion cannot erase another action's valid result.
• Never overwrite dirty local work with a refresh or reconnect response. Reconcile versions first and preserve both sides of a real conflict.
• Promise resume only when the required operation identity, progress, and input are actually durable. Explain when a reload requires reselection or another user step.
• Create operation identifiers before the first asynchronous boundary, keep them unique in their scope, and make terminal results monotonic. A late pending result cannot reopen a completed, rejected, or cancelled operation.
• Preserve the project's visual tokens, component language, spacing, and motion preferences in every state.

6. Make every state reproducible

Use the lightest mechanism the project already supports:

• Existing component stories or preview routes.
• Existing network mocks, fixtures, or test interceptors.
• Focused unit or integration tests.
• A local development toggle when no test harness exists and the toggle can remain private to development.

Never depend on random network failures or manual timing to reach a state.

Exercise recovery from the same boundary the user uses. Calling an internal controller method proves logic, not that the button, link, or keyboard action reaches it.

Prefer the project's real DOM or browser harness for the final boundary check. A hand-written element stub can prove data flow, but it cannot prove semantic markup, keyboard behavior, focus, or live announcements.

Read references/verification.md before testing a multi-step, destructive, payment, upload, or background-refresh flow.

7. Verify transitions, not screenshots alone

Select the relevant transitions from the reachability map:

• idle -> pending -> ready
• pending -> error -> retry -> ready
• ready -> background refresh -> degraded or ready
• form error -> edit -> successful resubmission
• action -> duplicate click or repeated request
• partial page or batch -> scoped retry -> complete result without duplicate items
• refresh and pagination -> both completion orders -> valid combined result or an explicitly blocked action
• overlapping reads -> newer result remains authoritative after an older response arrives
• edit -> save begins -> newer edit -> older acknowledgement
• local-only work -> reconnect -> reconcile -> saved or conflict
• pending work -> close, navigate, or reload -> resume or truthful interruption
• pending -> cancel or navigate away
• blocked -> prerequisite resolved -> retry
• unknown outcome -> status check -> confirmed result
• status check unavailable -> later recheck -> confirmed result
• uncertain operation -> newer user intent -> late status result cannot replace that intent

Check keyboard focus, status announcements, preserved input, narrow layouts, long messages, and reduced motion where relevant.

Pair with Taste Skill or another visual skill

Use both skills when the user wants a polished interface:

• Let the visual skill own composition, typography, color, imagery, and motion language.
• Let Statecraft own reachability, truthful feedback, recovery, state transitions, and evidence.
• Render loading, empty, blocked, error, and success states at the same visual quality as the ready state.
• Reuse the chosen design system and tokens. Do not introduce a generic error-card aesthetic.
• Prefer clarity, accessibility, and preserved work when a visual flourish conflicts with recovery.

Statecraft must also work alone. Never require Taste Skill to complete a functional UI task.

Completion gate

Before finishing, confirm:

• Every implemented state is reachable, and every important reachable state is represented.
• Empty, error, blocked, degraded, pending, and success are not confused.
• Consequential unknown outcomes use an uncertain state instead of pretending success or failure.
• Each interruption explains what happened and offers a valid next action.
• Every promised next action is visible or otherwise discoverable, wired to behavior, and tested through the UI boundary.
• Recovery controls exist in actual markup and have an accessible name and native interaction semantics.
• User input, progress, and usable data survive where safe.
• Partial results keep completed work, identify what remains, and expose a scoped recovery that cannot duplicate completed items.
• Success labels describe the real durability boundary and only the revision that was acknowledged.
• Dirty local work cannot be replaced by a late response, refresh, reconnect, or conflicting server version.
• Long-running work has explicit close, navigation, reload, and resume behavior.
• Persisted recovery data is scoped to the current user, tenant, and resource.
• Retry cannot silently duplicate destructive or expensive work.
• An uncertain operation can be reconciled later without creating a new operation.
• Repeated actions have an explicit policy, and late results cannot overwrite newer intent.
• Paged, retried, and resumed collections merge by stable identity.
• Dynamic feedback is available visually and to assistive technology.
• Required states are reproducible without luck.
• Relevant transitions were tested, not only static appearances.
• The normal path still works.
• Any unverified behavior is reported honestly.

For a build or repair, report the states covered, the important recovery decisions, and the checks run. For an audit, rank gaps by user harm and explain the smallest useful fix.