10 KiB
10 KiB
Task AR.2 Workspace UI/UX Design Note - 2026-07-07
Purpose
This note satisfies the AR.2 governance requirement that major workspace surfaces must have a UI/UX design note before implementation begins.
This is not final visual design. It is the approved interaction and composition baseline for future workspace implementation tasks.
Inputs Reviewed
docs/business/relationship-sales-workspace-blueprint-v1.mddocs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.mddocs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.mddocs/implementation/task-ar.2-epic-technical-design-2026-07-07.mdlayout.mddocs/standards/ui-ux-rules.mddocs/standards/architecture-rules.md- existing shadcn/ui patterns in CRM detail/report/dashboard pages
src/features/crm/dashboard/components/crm-dashboard.tsxsrc/features/crm/customers/components/customer-detail.tsxsrc/features/crm/reports/components/pipeline-report-view.tsxui-ux-pro-maxdesign-system and UX searches
UI/UX Direction
Visual direction
- preserve the existing dashboard shell and
PageContainer - extend the current CRM card, tab, filter, and table language
- use a restrained enterprise visual system
- prefer Minimalism + Swiss-style structure over decorative redesign
- keep CRM operational surfaces dense enough for work, but not noisy
Style summary from ui-ux-pro-max
- enterprise / operational dashboard fit
- Minimalism & Swiss Style is the best match
- use clear type hierarchy, subtle hover, minimal shadow, clean borders
- keep high contrast and strong layout rhythm
Layout behavior
- summary and action modules first
- active work queue second
- contextual history and related-record panels next
- keep page composition modular and card-based
- use bento-style composition only where it improves scanning, not as decoration
Chart guidance
- use bullet charts for compact performance-vs-target manager/executive KPIs
- use line highlights for anomaly or risk spikes
- use gauge only for isolated single target KPIs, not crowded summary rows
Shared Design Rules Across All New Workspaces
- Each workspace must make the next decision obvious within the first screenful.
- Filters should stay compact, reusable, and URL-aware where sharing matters.
- Empty states must explain the missing condition and the next useful action.
- Loading states should preserve layout using skeletons.
- Use text and icons in addition to color for status or urgency.
- Preserve current CRM terminology helpers and do not create a second terminology registry.
- New workspace routes must feel connected to the existing CRM nav, not like a parallel product.
Surface 1: Customer Workspace
Page purpose
Relationship execution hub for sales and managers.
Primary user role
Sales first, managers second.
Layout structure
- top header with customer code, status, owner, and quick actions
- main left column:
- overview summary
- relationship health
- upcoming work
- activities
- timeline
- related leads/opportunities/quotations
- right column:
- owner card
- quick metrics
- recent meetings / visits
- system metadata
Key actions
- edit customer
- manage owner
- add contact
- add activity
- jump to open opportunity or quotation
Empty state
- if no open work: explain that the relationship exists but has no upcoming action
- primary CTA should be create activity or open opportunity depending on access
Loading state
- keep the existing detail-shell rhythm with card skeletons
Permission-aware visibility
- contacts and sharing controls remain permission-gated
- quotation-related commercial values must obey pricing visibility
Responsive behavior
- mobile stacks left and right columns
- tabs remain usable without horizontal clipping
- quick actions wrap into compact rows
Relation to current nav
- stays on
/dashboard/crm/customers/[id] - this is an extension of current customer detail, not a new disconnected route
Surface 2: Calendar Workspace
Page purpose
Time-based operational workspace for activities, reminders, milestones, and approval due signals.
Primary user role
All operational roles, with manager emphasis in agenda view.
Layout structure
- page header and lens switcher
- compact filter bar
- calendar body with:
- day/week/month/agenda tabs
- side summary rail for selected date or selected item
Key actions
- change lens
- filter by user/team/branch/entity/activity type
- open linked record
- create activity from selected slot, when permitted
Empty state
- no scheduled work in period
- explain whether filters or true no-work condition caused it
Loading state
- skeleton for toolbar and calendar grid/list shell
Permission-aware visibility
- personal lens defaults to owned and assigned work
- manager lens shows only permitted team work
- milestone rows do not leak unauthorized quotation data
Responsive behavior
- agenda becomes the mobile-friendly default
- month view should degrade carefully on small widths
Relation to current nav
- new route under
/dashboard/crm/calendar
Surface 3: My Day
Page purpose
Personal action home screen for the logged-in user.
Primary user role
Sales and marketing; managers can still use it as a personal operating view.
Layout structure
- high-priority queue at the top:
- overdue
- due today
- urgent meetings
- pending approvals
- lower sections:
- hot projects requiring action
- urgent quotations
- relationship alerts
- upcoming schedule snapshot
Key actions
- mark activity complete
- reschedule
- open source record
- open today's calendar
Empty state
- celebrate cleared queue but provide a useful next action, such as reviewing upcoming work
Loading state
- summary and queue skeletons
Permission-aware visibility
- approvals and quotation urgency must obey approval/pricing boundaries
Responsive behavior
- priority queue stays first on mobile
- cards collapse into a single-column task feed
Relation to current nav
- new route under
/dashboard/crm/my-day
Surface 4: Manager Workspace
Page purpose
Operational control tower for team execution quality.
Primary user role
Manager.
Layout structure
- summary band:
- team overdue
- idle opportunities
- pending approvals
- forecast at risk
- main body:
- team calendar / agenda
- hot projects
- approval queue
- workload balance
- relationship risk alerts
Key actions
- drill into overdue item
- reassign or escalate
- jump to approval blocker
- review tomorrow risk
Empty state
- if no risks or overdue work, show healthy-state copy plus forecast review CTA
Loading state
- KPI band skeleton
- agenda/table skeleton
Permission-aware visibility
- use team/branch/product scope rules
- no UI should imply broader access than current security model grants
Responsive behavior
- mobile prioritizes risk list and agenda over wider comparison panels
- workload balance and comparison charts move below action queues
Relation to current nav
- new route under
/dashboard/crm/manager
Surface 5: Executive Workspace
Page purpose
Strategic monitoring workspace for executives.
Primary user role
Executive or high-level decision maker.
Layout structure
- top KPI row with limited count
- trend and exception cards next
- strategic accounts and pipeline/risk summaries below
Key actions
- drill into strategic account
- open executive report slice
- inspect risk trend
Empty state
- not likely full empty; if limited access, explain scope instead of showing blank business panels
Loading state
- stable KPI and trend skeletons
Permission-aware visibility
- commercial values and strategic summaries follow pricing visibility and report context rules
Responsive behavior
- mobile reduces chart count and shows stacked summary cards
- avoid forcing dense wide tables on first view
Relation to current nav
- new route under
/dashboard/crm/executive
Surface 6: Activity Workspace or Major Activity Views
Page purpose
Shared operational work management across customers, leads, opportunities, and quotations.
Primary user role
All operational roles.
Layout structure
- filter bar
- queue/list view first
- optional board or grouped sections later if justified
- detail drawer or detail route for context
Key actions
- create activity
- complete
- reschedule
- reassign
- open linked record
Empty state
- distinguish between no activities and filters producing no result
Loading state
- data-table skeleton or list skeleton, not blank feed
Permission-aware visibility
- show source record badges, but hide or redact unauthorized commercial details
Responsive behavior
- mobile uses stacked activity cards rather than wide data tables where needed
Recommended Visual Patterns by Surface
| Surface | Best Current Pattern to Extend |
|---|---|
| Customer Workspace | customer detail tabs + side cards |
| Calendar Workspace | dashboard filter bar + new calendar composition |
| My Day | dashboard summary + operational queue cards |
| Manager Workspace | dashboard bento rhythm + report table density |
| Executive Workspace | dashboard summary + report cards with fewer but stronger blocks |
| Activity Views | report/list filter pattern + CRM detail drawer pattern |
Anti-patterns to Avoid
- giant marketing-style hero sections inside dashboard workspaces
- visual redesign that breaks nearby CRM pages
- overusing charts when a ranked list or action queue is clearer
- blank states without next actions
- status communicated by color alone
- new workspace nav under
/dashboard/workspaces - layout shift on loading or button pending states
Handoff Requirement
Any future implementation task for these surfaces must cite this design note and explicitly state:
- which surface it implements
- whether it preserves this design note or intentionally deviates
- why any deviation is needed
Verification
- Documentation-only design note.
- No runtime code, route, schema, API, or permission behavior changed.
Outcome
AR.2 now has an approved UI/UX baseline for Customer Workspace, Calendar Workspace, My Day, Manager Workspace, Executive Workspace, and major Activity views, aligned with current CRM patterns and the required ui-ux-pro-max design process.