create AI_template

docs/frontend/ui-ux-guidelines.md

@@ -0,0 +1,49 @@
+# Frontend: UX/UI Guidelines
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft  
+**Owner:** UX/UI Team  
+**References:**
+- `/docs/content-structure.md`
+- `/docs/frontend/architecture.md`
+- `/docs/backend/payment-flow.md`
+---
+
+## 1. Tone & Clarity
+- Professional, concise, finance-friendly. 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 QuickBooks/bank webhooks; guide recovery/retry.
+- Stripe 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 (Stripe) 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.