State Forge

Mission

Design the interface for reality, not only the demo state.

Quality depends on how the system behaves across its reachable state space.

State machine

For each interactive surface identify state, trigger, next state, visible change, available actions, failure, and recovery.

Reachability

A state deserves design when it can actually occur through user action, data, network, permissions, time, navigation, or restoration.

State categories

Content: populated, empty, partial, missing, stale.

Process: idle, loading, progress, success, cancelled.

Failure: validation, network, permission, unavailable resource, conflict.

Interaction: focused, hovered, pressed, disabled, selected, dragging.

Environment: offline, constrained storage, reduced motion, narrow viewport, zoomed, restored session.

Empty

Explain why it is empty when useful, whether it is expected, and what can happen next. Do not fill empty space with decorative copy.

Loading

Make clear what is loading, what remains usable, how long it may take when knowable, and whether cancellation is possible.

Errors

Communicate problem, consequence, and next action. Avoid dead-end errors when recovery is possible.

Long content

Test long headings, labels, descriptions, large values, many items, and nested content. Decide intentionally whether to wrap, truncate, scroll, collapse, expand, or resize.

Overflow

Never allow accidental clipping, hidden actions, invisible horizontal scrolling, overlapping controls, or broken focus.

Stale/conflicting data

Determine freshness, refresh behavior, conflict handling, and whether local edits survive.

Permission

Differentiate unavailable, unauthorized, forbidden, and not configured states. Tell users what can be done next.

Recovery

Prefer:

error → explanation → action → restored context

over dead ends.

State matrix

For meaningful components:

Stress protocol

Where relevant exercise empty, long, loading, error, disabled, focus, repeated interaction, interruption, narrow layout, and restored state.

Reference artifact

Use references/state-report.md to inventory reachable states with their triggers, designed behavior, exercised coverage, and recovery.

Completion criteria

Reachable states have explicit behavior, important failures have recovery, and the interface has been inspected beyond the happy path.

Expert Review Protocol

First pass: understand

Before changing anything, identify the actual user outcome, the existing system, the relevant constraints, and the evidence available.

Do not begin by choosing a visual treatment.

Second pass: compare

Ask:

• What is the simplest credible solution?
• What is the strongest alternative?
• What does the current solution cost?
• What behavior does each option teach the user?
• Which decision is easiest to reverse?
• Which failure would be most expensive?

Choose deliberately.

Third pass: stress

Do not review only the happy path.

Apply pressure through:

• repetition
• interruption
• missing content
• long content
• slow operations
• narrow space
• large text
• keyboard use
• touch use
• focus changes
• error recovery
• restoration

Use only scenarios that are relevant to the surface.

Fourth pass: inspect the implementation

When code exists, verify that the implementation preserves the interface decision.

Look for:

• duplicated sources of truth
• styling that bypasses the system
• state that can become stale
• behavior that differs from adjacent components
• abstractions that obscure rather than simplify
• dependencies that are not earning their cost
• performance work performed without evidence

Fifth pass: critique the result

Ask:

If this were shipped tomorrow, what would users notice that the builder has stopped noticing?

Look for:

• friction
• ambiguity
• inconsistency
• unnecessary movement
• weak recovery
• hidden state
• visual noise
• inaccessible behavior
• fragile edge cases

Sixth pass: distinguish polish from substance

A useful change improves one or more of:

• understanding
• speed
• confidence
• recovery
• accessibility
• consistency
• maintainability

If a change improves none of these and only adds decoration, treat it as suspect.

Seventh pass: verify

A claim is complete only when an appropriate form of evidence supports it.

Use:

• direct interaction
• tests
• runtime inspection
• visual comparison
• accessibility checks
• performance measurement
• source inspection

Do not claim a check that did not occur.

Completion standard

Stop when:

1. the intended outcome is achieved
2. important states are handled
3. meaningful failure modes were considered
4. the interface fits its surrounding system
5. important claims are verified
6. remaining imperfections are lower-value than the risk of further change

The goal is not maximal polish.

The goal is a result that is difficult to improve without changing the underlying decision.