Interaction Specimen Builder

Set the specimen contract

State one testable interaction question before editing files. Record:

• the user action or transition under test;
• the current failure or uncertainty;
• the states that must remain recognizable;
• the real content, assets, tokens, and components to reuse;
• the target viewports and input methods;
• one observable success condition and one failure condition;
• the project areas that must remain unchanged.

Ask one focused question only when a missing answer changes the state model or acceptance result. Otherwise proceed with labeled assumptions.

Keep the scope to one interaction question. Split a second independent question into another specimen.

Inspect the source behavior

Inspect the relevant route, component, styles, tokens, assets, content, and existing tests. Run the current experience when possible. Capture the starting state and identify:

• the production entry and navigation path;
• existing state ownership and event handlers;
• breakpoint, pointer, keyboard, and motion behavior;
• content or asset constraints;
• dependencies that make isolation difficult.

Use project-native tooling. Load the relevant Figma skill for a Figma specimen, or the relevant framework and browser-testing skills for a coded specimen.

Choose an isolated surface

Prefer the smallest reversible surface supported by the project:

1. a dedicated Figma exploration page, branch, or prototype flow when the source is in Figma;
2. an existing Storybook story or specimen harness;
3. a dedicated development-only route;
4. an explicit component variant or feature-flagged preview;
5. a separate prototype folder when the production stack cannot isolate the behavior safely.

Name the surface after the interaction question. Keep it directly addressable so reviewers can revisit the same state.

Do not alter approved Figma pages, replace the production route, change the default export or navigation entry, or modify live component behavior. Do not redesign surrounding page sections. Avoid new dependencies unless the existing stack cannot express the interaction and the user accepts the cost.

Define the state model

Model the interaction before styling. Define:

• named states, including initial, intermediate, completed, interrupted, and error states when relevant;
• events that enter and exit each state;
• transition guards and cancellation behavior;
• focus ownership and screen-reader announcements;
• persisted values and reset behavior;
• viewport or input-mode differences;
• motion duration, easing, sequencing, and reduced-motion substitution.

Represent the model as a compact transition table or diagram. Avoid timeouts as the sole source of truth when a user event, media event, or explicit state can drive the transition.

Build the minimum credible specimen

Reuse real copy, media, data, tokens, and production components. Label any unavoidable placeholder. Preserve the existing information hierarchy outside the interaction under test.

Implement only enough context to judge:

• state legibility;
• cause-and-effect between input and response;
• transition continuity;
• interruption and recovery;
• input parity;
• behavior at the required viewports.

Add a reset control and, when useful, direct state controls or a comparison toggle. Keep diagnostic controls outside the production-shaped surface.

Cover input and motion behavior

Support every relevant path:

• Keyboard: provide logical tab order, visible focus, expected Enter/Space/Escape/arrow behavior, and focus restoration.
• Pointer: provide clear targets and avoid hover-only access.
• Touch: use reachable targets, resolve gesture conflicts, and provide a tap alternative for precision gestures.
• Reduced motion: honor prefers-reduced-motion; replace spatial travel, parallax, autoplay, and long sequencing with immediate or low-motion state changes.

Maintain the same task outcome across input modes. Document deliberate differences in composition or pacing.

Validate and collect evidence

Read references/specimen-acceptance.md before validation. Test the named success and failure conditions at each required viewport and input mode.

Collect:

• the isolated URL, story, or command;
• a state-transition record;
• screenshots for key states;
• a short recording when timing or continuity is under review;
• keyboard, touch, and reduced-motion results;
• console and runtime results;
• remaining risks and the integration recommendation.

Mark a check as pass, fail, or not tested. Never infer a pass without evidence.

Stop at the decision

Stop when the specimen answers the named interaction question with reviewable evidence. Present:

• Question
• Specimen surface
• States tested
• Evidence
• Result
• Trade-off
• Recommendation
• Decision needed

Do not integrate the specimen into production until the user explicitly approves that next action.

Stop early and report the blocker when:

• isolation requires changing a production entry;
• the real asset, content, or state contract is unavailable;
• the interaction expands into an information-architecture or full-page redesign;
• required behavior depends on an unapproved dependency;
• two acceptance criteria conflict and materially change the result.