# Frontend: UX/UI Guidelines

---
**Phase:** Phase 0 (Planning)  
**Status:** Draft  
**Owner:** UX/UI Team  
**References:**
- `/docs/content-structure.md`
- `/docs/frontend/architecture.md`
- `/docs/backend/payment-flow.md`
---

> This guide reflects a **pipeline / human‑review** archetype. For chat‑first or generation tools, keep the same principles (clarity, accessibility, safe actions) but replace the concrete flows and terminology per `/docs/archetypes.md`.

## 1. Tone & Clarity
- Professional and concise. Emphasize trust (audit log, reasoning traces, secure billing and webhooks).
- Avoid jargon without tooltips; show why a decision was made (rule hit, similarity, LLM reasoning).

## 2. Responsiveness
- Mobile-friendly for quick approvals; ensure tables/lists are scrollable and readable on small screens.
- Keep primary actions within easy reach; preserve context when opening drawers/modals.

## 3. Accessibility
- WCAG 2.2 AA: contrasts, focus states, keyboard navigation.
- Semantic HTML and ARIA for complex components (tables with controls, dialogs, toasts, dropdowns).

## 4. Key UX Flows
### Categorization & Approvals
- Show status per row (ingested/categorized/needs approval/approved/error).
- Detail drawer: raw data, matched rule, scores, `reasoning_trace`, history; clear “Approve/Override” CTAs.
- Prevent double actions; show optimistic state carefully; always provide “undo” or clear revert guidance.

### Rules
- Rule creation/edit with preview/test on sample set; highlight impact and conflicts.
- Require confirmation when enabling a high-priority rule; surface last editor and timestamp.

### Onboarding & Integrations
- Display connection status/health for external providers and their webhooks; guide recovery/retry.
- Payment plan selection and post-checkout status must be clear and recoverable.

### Reports & Exports
- Show date range, currency, timezone; indicate processing state and download links when ready.

## 5. Payments & Billing UX
- Use provider trust markers and keep users on provider-hosted flows.
- Post-return states: success, pending, failed; include retry/contact support options.

## 6. Support & Errors
- For webhook/ingestion errors, show actionable next steps (retry, rotate secret, re-connect).
- Keep errors human-readable; include trace IDs for support.