# Design Brief — Review & Edit: Substitution Structure

> Design-ready reference. Distilled from the substitution-structure synthesis (9 participants, 3 variants) and project context. Written for the designer generating the next round — constraints and decisions, not a research recap.

---

## What we're designing

The "Substitutions" screen on the Review Order flow: where a customer reviews and edits which of their grocery items can be replaced if out of stock. The open question this round answered was **structure** — how to organize the items so a customer can see the state of their whole order and act on it.

## What the research settled

**Use the Tab structure, reorganized around the customer's decision.**
Tabs with always-visible counts won every comprehension and confidence measure. But the bigger result was about *framing*: the categories had been named for the system's eligibility model, and that's what confused people across all three structures. The fix is to name the tabs for the decision the customer is actually making.

---

## Design constraints

### ✅ Must keep (validated — do not change without new evidence)
- **Tab structure** with **few categories** and a **simple interaction**.
- **A visible count on every tab.** This was the single strongest driver of comprehension, confidence, and clarity. Never hide it.
- **Inline edit per item** (tap a row → toggle substitution → it moves to the matching tab).

### 🔴 Must fix before shipping
- **Re-label the tabs around the customer's decision, not the system's data model.**
  Use **"Replace" / "Don't replace"** instead of an eligibility framing.
- **Replace "Ineligible" with plain language.** e.g. *"Can't be swapped"* — and say why inline (*alcohol & medication can't be substituted*). The word "ineligible" read as corporate and was unclear until tapped.

### 🟡 Should fix
- **Keep the count persistent across every view.** The filtered list failed because the running total disappeared under the active filter — 0/3 could state the count. Whatever the final layout, the total must stay on screen.

### 🟢 Needs follow-up (don't assume — confirm before building)
- Final tab set: do we need an **"All"** tab in addition to Replace / Don't replace / can't-be-swapped, or is it redundant?
- Exact copy for the can't-be-swapped explanation (legal/CS to confirm wording).
- Behaviour when an item moves between tabs — confirm there's no jarring reflow (the accordion's motion was a confidence cost; don't reintroduce it).

---

## Open questions
- Should the can't-be-swapped group be a full tab, or a quieter inline note under the affected items?
- Is there a count edge case (e.g. 0 items in a tab) that needs an empty state?

## Design system
Tokens are in `research/inputs/context/design_system.md` and mirrored in the project `CLAUDE.md`. Build the variants on those tokens.