CURRENT / Sources & referenceSource status

Current

Opening the reference…

From prototype to a usable interface · Current

Workflow · Documented baseline v4

From prototype to a usable interface

Build a reading-list interface through six detailed checkpoints, from task framing to browser evidence and handoff.

6 detailed checkpoints. Work at your own pace.

Complete runnable project

Start with the finished reading-list app.

Run it locally, inspect the code, and follow this workflow to adapt it. The kit includes persistence, backup and recovery, nine tests, and maintenance history.

Open the complete project kit →

The worked scenario

What you’ll build

Take a reading-list concept through task framing, interaction states, implementation, and browser review. The result is a save-and-return flow, not just a polished screenshot.

For: Designers who build and developers translating a product brief into an interface.

Authored examples, reviewed 2026-10-16. Verify commands and integrations in your own environment.

Download the complete guide ↓

Before you start

One user task and representative content, including a long title and URL.
A design workspace or a small browser prototype.
A local implementation with disposable test data.
A browser and an agreed way to record findings.

Skills used in this workflow

Make these choices first

Prototype or build directly?

Prototype when the flow is uncertain or stakeholders need to compare arrangements. Build a small browser slice when the interaction and constraints are already clear.

When is the interface ready?

When the user completes the task and recovers from its important failures in the actual implementation. Visual polish alone is insufficient.

Step 1 of 6

Frame the task and its states

A screen becomes useful when it supports both completion and recovery.

Start with

One target user, an existing page or wireframe, and a specific task.

What to do

Use a reading list as the worked example: save a URL, recognize success, and reopen it later. Name the reader and the context in which they use it.
Write the starting condition and successful visible result. List empty, loading, saved, duplicate, invalid-URL, and server-error states.
Choose the smallest version: title and source link only. Exclude generated summaries and sharing until saving reliably works.

Worked example

State inventory

Empty → show URL field and a concrete example
Submitting → retain input; prevent duplicate submit
Saved → show title + link; announce success
Duplicate → show the existing item
Invalid URL → explain the accepted format at the field
Server error → retain input; offer retry

The inventory is a product contract. A visual prototype should demonstrate each state, not just populated content.

Give this task to your agent

Adapt the project details before using this instruction.

Agent instruction

Use frame-a-feature for a reading list. Draft the save-and-return journey with seven states, concrete UI copy, and Given/When/Then checks. Keep the feature local and identify data that would need account ownership later.

Your output

A task brief and a state inventory.

Ready to move on when

Every state has a next action and a clear transition back to the task.

The design has a beautiful happy path but no error recovery.

Sketch the invalid and failed submission states next to the successful one before adding visual polish.

View the stack

Definition of done

What a complete result includes

Each input has a visible label and actionable errors.
Failed submissions preserve user input.
Saving survives a reload.
The keyboard path has visible, useful focus.
Tested narrow layouts have no document-level overflow.
The handoff names tested and untested accessibility behavior.

Record evidence against each criterion in acceptance.md. A completed step is not proof that an integration works.

Reusable starting point

Take the working files with you.

Start with a brief, keep a verification record, and hand off the work with its assumptions. Preview each file before downloading. Skill files include their installation instructions below.

Download brief ↓

Files in this workflow

brief.mdA concrete task brief with decisions and acceptance cases.Download brief.md ↓

Preview file

brief.md

# From prototype to a usable interface: task brief

## Worked scenario
Take a reading-list concept through task framing, interaction states, implementation, and browser review. The result is a save-and-return flow, not just a polished screenshot.

## Adapt to your project
User and situation:
Input example:
Expected visible result:
Non-goals:
Ownership and data boundary:
Budget and constraints:

## Acceptance criteria
- [ ] Each input has a visible label and actionable errors.
- [ ] Failed submissions preserve user input.
- [ ] Saving survives a reload.
- [ ] The keyboard path has visible, useful focus.
- [ ] Tested narrow layouts have no document-level overflow.
- [ ] The handoff names tested and untested accessibility behavior.

## Record a case
Given:
When:
Then:
Evidence:

## Workflow checkpoints
### 1. Frame the task and its states
Output: A task brief and a state inventory.
Check: Every state has a next action and a clear transition back to the task.

### 2. Choose a flow before styling
Output: A task-tested flow and a short list of revisions.
Check: A reader can identify where to enter the URL, whether it saved, and where to find it again.

### 3. Build semantic interaction states
Output: A working form with useful status and error feedback.
Check: The field's purpose and error are available without relying on color or placeholder text.

### 4. Exercise small screens and long content
Output: Responsive fixes with before/after evidence.
Check: There is no whole-page horizontal scroll and no clipped submit or recovery action in the tested layouts.

### 5. Automate the important user outcomes
Output: A small regression suite and its recorded results.
Check: The test observes the saved item after a reload, not just a successful HTTP response.

### 6. Hand off the implementation evidence
Output: A design-to-development handoff and acceptance checklist.
Check: Another person can reproduce the main task and the remaining issues without a narrated walkthrough.

Included

acceptance.mdA completion checklist and verification record.Download acceptance.md ↓
Preview file

Sources & further reading

Official documentation supports the technical guidance. The scenario, prompts, and checklists are original implementation examples.

W3C form notifications ↗
Associate actionable error messages with controls and communicate submission outcomes.
Playwright testing practices ↗
Use observable behavior, user-facing locators, and retrying assertions in browser tests.

acceptance.md

# From prototype to a usable interface: acceptance

- [ ] Each input has a visible label and actionable errors.
- [ ] Failed submissions preserve user input.
- [ ] Saving survives a reload.
- [ ] The keyboard path has visible, useful focus.
- [ ] Tested narrow layouts have no document-level overflow.
- [ ] The handoff names tested and untested accessibility behavior.

## Verification record
Date / environment:
Revision:
Command or manual steps:
Expected / actual:
Outcome:
Unrun checks:
Known limitations:

handoff.mdTransfer the work with its assumptions and test evidence.Download handoff.md ↓

Preview file

handoff.md

# Implementation handoff

Task / owner:
Baseline / patch identity:
Contract version:
Changed files:
Decisions and assumptions:
Commands actually run and outcomes:
Manual journeys checked:
Known failures and unrun checks:
Integration dependencies:
Rollback notes:

Included

frame-a-feature.mdAgent skill: Turn an idea into a buildable brief. Save as frame-a-feature/SKILL.md in your agent's configured skills directory.Download frame-a-feature.md ↓

Preview file

frame-a-feature.md

---
name: frame-a-feature
description: "Define an implementable feature brief with observable acceptance cases. Use before building a new feature or narrowing an ambiguous product request."
---

# Turn an idea into a buildable brief

A scoped brief, an explicit non-goal list, and examples a developer can turn into tests.

## Inputs
The user problem, existing product, delivery constraints, and one example of success.

## Understand the existing product
Read relevant product notes and the current implementation. Name the user, triggering situation, present workaround, and desired result. Reuse decisions already made. Ask only about missing information that would materially change the implementation.

## Make the slice testable
Write one happy-path example using concrete input and expected visible output. Add the most consequential failure and repeat-action cases. Distinguish missing information from a chosen default. Define what is deliberately excluded from this iteration.

## Produce the handoff
Return: problem; example journey; input/output contract; affected screens and states; ownership/storage boundary; acceptance cases; unknowns. Each acceptance case must contain Given, When, and Then. Avoid specifying a framework or paid service unless the project requires it.

## Check the brief
A reader must be able to determine whether the example succeeded without asking what 'good' means. If an unknown blocks implementation, identify the smallest decision needed. Do not turn the brief into authorization to publish, purchase, or change access.

## Example request
Use frame-a-feature to scope a source-linked reading list. Readers save a URL and return to it later. Keep the first version local; produce a brief and acceptance cases before implementation.

Included

review-an-interface.mdAgent skill: Review an interface through real tasks. Save as review-an-interface/SKILL.md in your agent's configured skills directory.Download review-an-interface.md ↓

Preview file

review-an-interface.md

---
name: review-an-interface
description: "Evaluate and improve a working interface using keyboard tasks, responsive layouts, recovery states, and concrete evidence. Use for an implemented page or flow ready for browser review."
---

# Review an interface through real tasks

Prioritized reproducible findings and a retested task path.

## Inputs
A working URL, the target task, expected states, and permitted test data.

## Follow the user task
Start from the entry page. Complete the primary action without relying on source-code knowledge. Record confusing labels, blocked paths, and missing feedback. Use disposable data and preserve existing user state.

## Check interaction states
Exercise loading, empty, populated, invalid, failed, and retried states where the app supports them. Verify entered values survive a failed submission. Keyboard focus should follow a useful order and remain visible. Error messages should explain the next action and relate to their controls.

## Inspect responsive behavior
Check a narrow viewport and the normal desktop layout. Read long titles and error messages. Distinguish deliberate local horizontal scrolling from whole-page overflow. Ensure the selected tab remains discoverable. Do not infer accessibility conformance from a screenshot alone.

## Close the loop
For each finding provide steps, expected/actual behavior, impact, and evidence. If fixes are requested, make the smallest coherent change and repeat the affected journey. Restore viewport and test data. State untested assistive technologies or browsers explicitly.

## Example request
Use review-an-interface on the reading-list page. Test saving a URL, a duplicate save, a failed request, and returning to the list. Check keyboard use and 320px/390px widths. Restore any test changes.

Included