UX Review Package Guide

Sprint 22 adds a local UX review package for manual and AI-assisted review. Generate it with pnpm ux:review while the local dashboard and docs app are running.

The package is written to ux-review-package/ and includes route map, navigation map, page inventory, desktop screenshots, and mobile screenshots. It must be generated from local seed/sample data only. If a route cannot load or sign-in fails, pnpm ux:review fails with an actionable restart/credential message instead of silently producing a partial package.

Sprint 23 Staging Review Coverage

The route inventory now covers the main staging-readiness surfaces:

• Workspace, Command Center, CRM, deals, quote/BOQ, proposal summaries, tasks, approvals, notifications, settings, customization, and docs.
• Agents, Agent Drafts, Communication Outbox, Finance, Projects, Support, Inventory, Imports, Data Quality, Documents, Manager Rehearsal, and System QA.
• First available seeded detail records for Company, Lead, Opportunity, Quote, and Proposal Summary.
• Settings Roles and Settings Permissions for RBAC review.

Detail screenshots are resolved from local list pages. If seed data is missing, the script falls back to the corresponding list page instead of inventing a route.

UX Review Focus

When reviewing screenshots, check:

• Mobile shell: page title, notification bell, user menu, and compact drawer appear before long navigation lists.
• Global navigation: authenticated pages expose workspace-level navigation, and module tabs remain secondary.
• Command Center: Today’s Priority and high-priority work remain near the top, with section jumps for dense mobile review.
• Settings Customization: sections are grouped for pipeline labels, deal types, quote revision reasons, task templates, and safety boundaries.
• Deals: action badges identify follow-up, quote-sent, proposal-missing, budget-revision, approval-pending, and quote-set-ready conditions.
• Quote margin: missing cost data shows a review label and Data Quality link instead of a misleading 0%.

External Review Policy

ChatGPT and external assistants cannot directly review localhost, private LAN IPs, or phone-only URLs. Until safe staging exists, UX review should use:

• local screenshots
• screen recordings
• ux-review-package
• audit reports
• Codex local browser/smoke tests

External assistant review starts only after staging deployment using a safe staging URL such as https://staging-app.submicrons.net.

Sprint 24 Staging Package Metadata

The generator now writes ux-review-package/metadata.json with the source app URL, docs URL, generation time, capture mode, and safety flags. For staging review, run the package from the approved staging URL only after confirming the environment contains sample/demo data and no real customer imports.

If staging is not deployed yet, the local package remains the review fallback. Record that limitation in the Sprint 24 staging QA report instead of copying private files into the package.

Safety

• Do not copy .env files, private imports, production exports, or real customer data into the package.
• Screenshots are local review artifacts only.
• The script does not deploy, send messages, connect integrations, or call external services.
• If manager or normal-staff credentials are not available, role-specific screenshots may be skipped.

Retest

Run pnpm ux:review:dry to verify route inventory generation without screenshots. Run pnpm ux:review for full screenshot capture after pnpm dev is serving the dashboard and pnpm dev:docs is serving the docs app.