# Review & Edit — Substitution Structure — Claude Code Briefing

> This file is auto-generated by SKILL 0 and updated by SKILL 3 and SKILL 5.
> Last updated: 2026-05-18

---

## Project context
**Project name:** Review & Edit — Substitution Structure
**Product area:** Grocery delivery — substitutions
**Research round:** Structure usability test (Tab / Accordion / Filter)

**Google Drive:** My Drive/Research-to-Design/review-edit-structure-study/
**Local path:** ~/Desktop/Roy-Design-OS/review-edit-structure-study/

---

## Research findings
> Populated by SKILL 3 — 2026-05-18

**Winner: Tab structure** — best count comprehension (3/3), highest confidence (4.3) and clarity (4.7).

**Validated (must keep):**
- Tabs with few categories + simple interaction
- A visible count on every tab — strongest driver of comprehension; never hide it
- Inline edit per item (tap row → toggle → moves to matching tab)

**Must fix before shipping:**
- Re-label tabs around the customer's decision, not the system's eligibility model → "Replace" / "Don't replace"
- Replace "Ineligible" with plain language ("Can't be swapped — alcohol & medication")

**Should fix:**
- Keep the count persistent across every view (the Filter variant failed because the total vanished under the active filter — 0/3 stated it)

**Avoid:**
- Layout shift on interaction (the Accordion's expand/collapse motion cost orientation and confidence)

**Needs follow-up:**
- Whether an "All" tab is needed alongside Replace / Don't replace / can't-be-swapped
- Final copy for the can't-be-swapped explanation

---

## Design decisions
> Populated by SKILL 5 — 2026-05-19

**Final: Substitutions screen built on the two-tab decision model (Replace / Don't replace), with the summary bar merged into the tab bar.**

- Synthesized from Variant 2 (two-tab decision model) + Variant 1 (live summary bar).
- **Can't-swap** items are NOT in the Replace tab — they're a third, read-only summary segment (semantically correct; can't be acted on).
- **Find an item** field added — searches by name across all tabs (solves locating in long orders, which both variants struggled with).
- **Toggling shows a "Moved · Undo" toast** so an item is never silently lost when it changes tabs.
- Validated elements kept: decision tabs, always-visible counts, inline per-item edit, plain-language can't-swap.

Final design + engineer spec: `design/refined/substitutions-final.html`

---

## Design system
> Populated from design_system.md context document.

**Key tokens:**
- Primary CTA: #0071dc
- Border radius (cards): 12px
- Font family: -apple-system, BlinkMacSystemFont, sans-serif

**Component conventions:**
- Item row: thumbnail + name + status pill + edit affordance
- Status: "Replace" / "Don't replace"; Badge for "Ineligible"

---

## Prototype conventions
- Framework: React
- Styling: CSS modules with the design tokens above
- Component Library: plain React (no external UI dependency)

---

## What NOT to change
> Things that have been validated in research and should be preserved.
- The Tab structure (few categories, simple interaction)
- The always-visible per-tab count
- Inline per-item edit that moves the item to the matching tab

---

## Open questions
> Things still being decided — don't make assumptions on these.

---

## Synthesis instructions
> Project-specific instructions for SKILL 2. Applied on top of general synthesis rules.
> If empty, SKILL 2 will use the default synthesis format.