Interface Plan

Question-driven spec refinement. Use before building to surface interaction and craft concerns early.

When to Use

Starting a new feature
Refining a user story
Before writing any code

How It Works

User describes what they want to build
You ask questions that surface principle violations before they're coded
Output: refined spec with interaction concerns addressed

Principles Reference

Before asking questions, understand the Laws of Interface Quality:

Reversibility — Every action should be undoable or recoverable
Forgiveness — Software should assume human error and prevent harm
Persistence — User work should survive navigation, refresh, failure, and closing
Transparency — System state should be visible and understandable at all times
Escape — Users should always have a way out of any state
Consistency — The same action should work the same way everywhere
Craft — The interface should show intentional choices, not defaults
Recognition — Show users what they need, don't make them remember

See principles/interaction.md for full details.

Question Framework

For each feature, work through these categories.

Intent Questions (ask first)

Before any implementation questions, establish intent:

Who is this human? Not "users." The actual person. Where are they when they open this? What's on their mind?
What must they accomplish? Not "use the feature." The verb. What action, what outcome?
What should this feel like? Say it in words that mean something. "Clean and modern" means nothing. Warm like a notebook? Cold like a terminal? Dense like a trading floor? Calm like a reading app?

If you can't answer these with specifics, ask the user. Don't guess.

Craft Questions (decisions to make early)

These decisions shape everything downstream. Make them explicit:

Depth strategy: Borders-only, subtle shadows, layered shadows, or surface color shifts? Pick ONE.
Typography: What typeface fits the feel? Don't default — select.
Color temperature: Warm, cool, neutral? What colors exist in this product's world?
Information density: Spacious or dense? What serves the user's task?

Where Defaults Hide

Defaults sneak into these areas. Name them before they win:

Area	The Trap	Ask Instead
Typography	"Pick something readable"	What typeface fits this product's personality?
Navigation	"Build sidebar, add links"	How should users think about this space?
Data display	"Show the number"	What does this number mean? What will they do with it?
Token names	"Implementation detail"	Do these names evoke the product or a template?

Reversibility Questions

Will users need to recover deleted items? How long should recovery be available?
Are there bulk operations? What happens if they select the wrong items?
Can changes be undone? History, version control, undo button?

Forgiveness Questions

What happens if users double-click submit?
Can they put bad data in and recover gracefully?
Are destructive actions distinguishable from safe ones?

Persistence Questions

If they refresh mid-form, what happens?
If the API fails, is their input preserved?
Should there be a draft/autosave?

Transparency Questions

How will they know it worked?
What does the loading state look like?
If it fails, what do they see? What can they do?

Escape Questions

Can they cancel at any point?
If there's a modal, how do they close it?
For multi-step flows, can they go back?

Consistency Questions

Does this action work the same way elsewhere in the app?
Are we following platform conventions (iOS/Android/web)?
Will users expect this to behave like similar features they've used?

Recognition Questions

Can users see their options, or must they remember commands?
Should we show recent items, suggestions, or search?
How do users find this feature if they forget where it is?

Output Format

Return a refined spec that includes:

## Feature: [Name]

### Intent
- **Who:** [The actual person using this]
- **Task:** [What they must accomplish]
- **Feel:** [How it should feel — specific, not generic]

### Craft Decisions
- **Depth:** [borders-only / subtle shadows / layered / surface shifts]
- **Typography:** [Selected typeface and why]
- **Density:** [spacious / balanced / dense]

### Happy Path
[Normal flow]

### Interaction Safeguards

**Reversibility:**
- [How delete/changes are recoverable]

**Forgiveness:**
- [How double-submit is prevented]
- [How errors preserve input]

**Persistence:**
- [What survives refresh/failure]

**Transparency:**
- [Loading, success, error feedback]

**Escape:**
- [How users can exit any state]

**Consistency:**
- [How this matches existing patterns]

### Questions Still Open
- [Anything that needs user decision]

Example

User says: "I want to add a delete button to each item in my list."

Plan mode response:

A few questions before we build this:

Reversibility:

Should deleted items go to trash (recoverable) or be permanently removed?

If permanent, do you want a confirmation dialog, undo toast, or both?

Forgiveness:

Should the delete button be visually distinct from other actions (red, icon only, positioned separately)?

Transparency:

What feedback should users see after deleting? Toast notification? List animation?

Bulk operations:

Will you eventually support multi-select delete? If so, we should design for it now.

After user answers:

## Feature: Delete Items

### Happy Path
Click delete → confirmation dialog → item removed → toast confirmation

### Interaction Safeguards

**Reversibility:**
- Soft delete to trash (recoverable 30 days)
- Confirmation dialog: "Delete [item name]? [Cancel] [Delete]"
- Undo toast for 5 seconds after deletion

**Forgiveness:**
- Delete button: outline style, smaller than primary actions
- Positioned right side, away from edit/view buttons

**Persistence:**
- N/A (list is server state)

**Transparency:**
- Loading: button shows spinner during API call
- Success: toast "Item deleted" with undo link
- Error: toast "Couldn't delete. Try again." + item stays in list

**Escape:**
- Confirmation dialog has Cancel button and closes on ESC/backdrop

Key Principles

Ask, don't assume — Surface decisions before coding
Name the principle — "For reversibility..." helps users learn
Offer good defaults — Suggest the safest approach as default
Keep it conversational — This is planning, not auditing

interface-plan