AI_template/docs/frontend/ui-ux-guidelines.md

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

---

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.