# 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.md`
- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md`
- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md`
- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md`
- `layout.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/architecture-rules.md`
- existing shadcn/ui patterns in CRM detail/report/dashboard pages
- `src/features/crm/dashboard/components/crm-dashboard.tsx`
- `src/features/crm/customers/components/customer-detail.tsx`
- `src/features/crm/reports/components/pipeline-report-view.tsx`
- `ui-ux-pro-max` design-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

1. Each workspace must make the next decision obvious within the first screenful.
2. Filters should stay compact, reusable, and URL-aware where sharing matters.
3. Empty states must explain the missing condition and the next useful action.
4. Loading states should preserve layout using skeletons.
5. Use text and icons in addition to color for status or urgency.
6. Preserve current CRM terminology helpers and do not create a second terminology registry.
7. 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.