# UX Patterns & Conventions

Recurring interaction patterns applied consistently everywhere they occur. Consistency here is what makes the automation catalog in `../architecture/01-product-vision.md` feel like one coherent system instead of a bag of unrelated features bolted together — the direct application of "consistency over feature quantity."

## 1. The automation suggestion pattern

Every piece of Automation Engine or Merchant Health output — regardless of which flow it appears in (Home, Products, Marketing) — follows the same three-part shape:

1. **What was detected**, stated as a plain-language fact ("Five products are missing descriptions," not "Data quality score: 73%").
2. **Why it matters**, only when not obvious ("Products without descriptions rank lower in search and convert less often") — omitted when the "why" is self-evident.
3. **A specific action**, never just information. The action is a button, not a suggestion to go figure it out: "Add descriptions," "Review abandoned carts," "Launch this discount."

Every suggestion is **acceptable or dismissible**, never silently auto-applied if it touches money, pricing, or customer-facing content (see rule 3 below). Dismissed suggestions don't reappear identically — the system should learn that context, not nag.

## 2. Empty states teach, they don't just report absence

An empty Orders list, an empty Products catalog, or a Reports page with no data yet should never just say "No data." Each empty state names the next concrete step ("Add your first product to start selling") and links directly to it. This is the onboarding flow's philosophy (`02-core-user-flows.md`, #1) extended to every list view, not just the first-run experience.

## 3. Confirmation is reserved for irreversible or money-impacting actions

Per the principles resolution in `../architecture/02-principles-and-tradeoffs.md`: automation can detect and recommend freely and immediately, but the merchant retains the final say on anything that touches money, pricing, or customer-facing content, unless they've explicitly configured otherwise. Concretely:

- **No confirmation needed:** dismissing a suggestion, editing a draft, viewing any report, accepting an auto-generated SEO description before saving (still part of an unsaved edit).
- **Confirmation required:** issuing a refund, publishing a discount, sending a campaign to customers, deleting a product with existing orders, changing a payment/shipping configuration.
- **Never silently automatic:** anything in the "confirmation required" list. Automation can pre-fill and suggest these, but a human click always finalizes them.

This rule prevents two failure modes at once: confirmation fatigue (asking "are you sure?" for harmless actions trains merchants to click through everything) and unwanted surprises (an automation silently changing a price or emailing a customer without the merchant's knowledge).

## 4. Progressive disclosure for anything technical

Per "business language before technical language" and "workflow before settings": a screen's default state shows only what most merchants need. Anything technical (tax jurisdiction edge cases, advanced shipping rules, raw event logs) is reachable but not front-and-center — behind an "Advanced" affordance, not hidden entirely, and never required to complete a common task.

## 5. Deep-linking from recommendations to context

Every actionable item anywhere in the product (a Home recommendation, a Reports insight, a suggested campaign) links directly into the exact filtered/scoped view needed to act on it — never to a generic section the merchant has to re-filter themselves. Demonstrated concretely in `02-core-user-flows.md` flow #5 (Store Health review): clicking "five products missing descriptions" opens Products pre-filtered to those five, not the full product list.

## 6. One way to do a thing

Per "opinionated defaults over endless customization": where traditional commerce platforms often offer three ways to configure the same behavior (a rule builder, a settings toggle, and a plugin), CommerceDex offers one well-designed way. If a merchant asks "how do I do X," there should be exactly one obvious answer, not "it depends which method you prefer."

## 7. Status language is consistent across sections

The same words mean the same thing everywhere: "Active," "Draft," "Scheduled," "Completed," "Needs attention" carry identical meaning and visual treatment whether they describe an order, a campaign, a product, or a health recommendation. A merchant should never have to re-learn status vocabulary when moving between Orders and Marketing.