# Dealspace UI/UX Specification

**Version:** 0.1 — 2026-02-28  
**Status:** Pre-implementation. Companion to SPEC.md.

---

## 1. Design Philosophy

**Workers see their inbox. Deal managers see the deal.**

The UI surface is role-determined. Same platform, completely different experience:
- **Worker** (seller_member, buyer_member): Task inbox only
- **Admin** (ib_admin, seller_admin, buyer_admin): Full deal context
- **IB member**: Workstream-scoped deal view

No hamburger menus. No collapsible sidebars. No "power user mode." The interface adapts to the role — users don't configure their way to productivity.

---

## 2. Information Architecture

### 2.1 Screen Inventory

| Screen | Who Sees It | Purpose |
|--------|-------------|---------|
| Task Inbox | Everyone | Personal work queue — what needs attention |
| Request Detail | Everyone | Thread view, status, routing chain |
| Deal Overview | IB admin, seller_admin | Full picture: workstreams, completion %, activity |
| Workstream View | IB member, admins | Requests/answers in one workstream |
| Data Room | buyer_admin, buyer_member | Published answers, document browser |
| Request Submission | buyer_admin, buyer_member | Submit new requests |
| Team Management | All admins | Invite, roles, permissions |
| Project Settings | ib_admin | Workstreams, themes, notifications |

### 2.2 Navigation Model

```
┌─────────────────────────────────────────────────────────────┐
│ [Project ▾]                    [Inbox (3)]  [Avatar ▾]      │
├─────────────────────────────────────────────────────────────┤
│ Finance │ Legal │ IT │ HR │ Operations │ [Data Room]        │  ← workstream tabs (admin/IB only)
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                      CONTENT AREA                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**Workers (seller_member, buyer_member):**
- No project selector (they see one project's tasks)
- No workstream tabs (their inbox spans all assigned workstreams)
- Just: header + inbox

**Admins/IB:**
- Project selector (one-line dropdown, not a sidebar)
- Workstream tabs (always visible when in a project)
- Full navigation

### 2.3 URL Structure

```
/inbox                              # Personal task inbox (all projects)
/p/:projectID                       # Deal overview (admin) or inbox (worker)
/p/:projectID/ws/:workstream        # Workstream view
/p/:projectID/r/:requestID          # Request detail
/p/:projectID/dataroom              # Data room (buyers)
/p/:projectID/dataroom/submit       # Submit request (buyers)
/p/:projectID/team                  # Team management
/p/:projectID/settings              # Project settings (ib_admin only)
```

---

## 3. Role-Based Views

### 3.1 IB Admin

**Default view:** Deal Overview
- Completion % per workstream (donut charts)
- Recent activity feed
- Pending vetting queue
- Buyer requests needing attention

**Full access to:**
- All workstream tabs
- All requests/answers
- Team management for all parties
- Project settings
- Audit log

### 3.2 IB Member

**Default view:** Workstream View (for assigned workstreams)
- Request lists in their workstreams
- Vetting queue for answers submitted to them
- Can publish to data room

**No access to:**
- Other workstreams
- Project-level settings
- Other parties' internal routing

### 3.3 Seller Admin

**Default view:** Team inbox (all requests assigned to seller org)
- Group by: Workstream | Assignee | Due Date
- Delegation controls
- Completion tracking

**Access:**
- All requests directed to seller
- Seller team management
- No buyer visibility
- No data room

### 3.4 Seller Member (e.g., accountant)

**Default view:** Personal Task Inbox
- ONLY tasks assigned to them
- Clear due dates
- Simple: task → upload → done

**No access to:**
- Other team members' tasks
- Deal-level metrics
- Buyer anything
- Data room

### 3.5 Buyer Admin

**Default view:** Data Room
- Published answers organized by workstream
- "Request Info" button
- Team's pending requests

**Access:**
- Data room (published only)
- Submit requests
- Buyer team management
- No seller visibility
- No pre-dataroom content

### 3.6 Buyer Member

**Default view:** Personal Task Inbox (their requests)
- Status of requests they submitted
- Data room read access

**No access to:**
- Submit new requests (unless granted)
- Team management
- Other members' requests

---

## 4. The Task Inbox (Core View)

The most important screen. This is where work happens.

### 4.1 Layout

```
┌─────────────────────────────────────────────────────────────┐
│ MY TASKS                                        [View ▾]    │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🔴 FIN-042  Audited financials FY2024      Due: Mar 15  │ │
│ │    Project Alpha  •  Finance  •  From: J. Smith (IB)    │ │
│ │    "Please provide audited statements for..."          │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🟡 LEG-018  Board meeting minutes 2025     Due: Mar 20  │ │
│ │    Project Alpha  •  Legal  •  From: M. Chen (CFO)      │ │
│ │    "Board approval documentation needed"                │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ⚪ IT-007   Network architecture diagram    Due: Mar 22  │ │
│ │    Project Beta  •  IT  •  From: L. Park (IB)           │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 4.2 Task Card Elements

| Element | Purpose |
|---------|---------|
| Priority indicator | 🔴 High, 🟡 Normal, ⚪ Low (color-coded dot) |
| Reference | FIN-042 — workstream prefix + number |
| Title | Primary description |
| Due date | Absolute date, turns red when overdue |
| Project | Which deal (shows only if multi-project) |
| Workstream | Finance, Legal, etc. |
| From | Who routed it to you |
| Preview | First line of request body (truncated) |

### 4.3 View Options

- **All** — everything assigned to you
- **Overdue** — past due date
- **Due Today** — due within 24h
- **Waiting** — tasks you forwarded, pending return

### 4.4 Batch Actions

Select multiple → Mark done, Forward, Change priority

### 4.5 Empty State

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                    ✓  You're all caught up                  │
│                                                             │
│              No tasks need your attention right now.        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 5. Request Detail View

The thread behind every task.

### 5.1 Layout

```
┌─────────────────────────────────────────────────────────────┐
│ ← Back to Inbox                                             │
├─────────────────────────────────────────────────────────────┤
│ FIN-042  Audited financials FY2024                    🔴    │
│ Project Alpha  •  Finance  •  Due: March 15, 2026          │
├─────────────────────────────────────────────────────────────┤
│ ROUTING                                                     │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Acme Capital (Buyer) → IB Analyst → CFO → ★ YOU        │ │
│ │                                           │              │ │
│ │                                    [Mark Done]           │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ THREAD                                                      │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ J. Smith (IB) — Feb 25, 10:30am                         │ │
│ │ Please provide audited financial statements for FY2024.  │
│ │ We need P&L, balance sheet, and cash flow.              │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ M. Chen (CFO) — Feb 26, 2:15pm                          │ │
│ │ @accountant Can you pull these from the ERP?            │ │
│ │ Attaching last year's format for reference.             │ │
│ │ 📎 fy2023-financials-format.xlsx                        │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ YOUR RESPONSE                                               │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Write a message...                                      │ │
│ │                                                         │ │
│ │                                    [📎] [Send]          │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 5.2 Routing Chain Visibility

| Role | Sees |
|------|------|
| Worker | Just: "From: CFO" and "Returns to: CFO when done" |
| Seller admin | Full internal chain within seller org |
| IB admin | Complete chain including external origin |

Workers don't need to see the full buyer→IB→CFO→accountant chain. They see their immediate context: who gave it to them, who it goes back to.

### 5.3 Actions by Role

| Role | Available Actions |
|------|-------------------|
| Worker | Reply, Upload, Mark Done |
| Seller admin | Above + Forward, Reassign, Change Due Date |
| IB member | Above + Approve, Reject, Publish |
| IB admin | Full control |

### 5.4 Status Transitions

```
Worker marks done
    → Task moves to return_to person's inbox
    → Worker sees "Sent to CFO for review" confirmation
    
CFO approves
    → Task moves to IB analyst's inbox
    → Status: "Pending vetting"
    
IB approves
    → Answer published to data room
    → All linked buyers notified
    → Status: "Published"
```

---

## 6. Data Room View (Buyer-Facing)

### 6.1 Layout

```
┌─────────────────────────────────────────────────────────────┐
│ DATA ROOM                              [Request Info]       │
├─────────────────────────────────────────────────────────────┤
│ Finance │ Legal │ IT │ HR │ Operations                      │
├─────────────────────────────────────────────────────────────┤
│ FINANCE                                                     │
│ ├── Financial Statements                                    │
│ │   ├── 📄 Audited Financials FY2024.pdf         2.3 MB   │ │
│ │   ├── 📄 Audited Financials FY2023.pdf         2.1 MB   │ │
│ │   └── 📄 Management Accounts Q1 2025.xlsx      845 KB   │ │
│ ├── Tax Documents                                           │
│ │   ├── 📄 Corporate Tax Returns 2024.pdf        1.8 MB   │ │
│ │   └── 📄 Tax Compliance Cert.pdf               234 KB   │ │
│ └── Revenue Analysis                                        │
│     └── 📄 Revenue Breakdown by Segment.xlsx     1.2 MB   │ │
└─────────────────────────────────────────────────────────────┘
```

### 6.2 Features

- **Workstream tabs** — filter documents by category
- **Folder structure** — mirrors request list organization
- **Quick actions** — Download, Preview (in-browser with watermark)
- **Search** — full-text search across all published documents
- **Request Info** — submit a new request for information

### 6.3 Document Preview

In-browser preview with dynamic watermark:
```
John Smith · Acme Capital · Feb 28, 2026 10:30 AM · CONFIDENTIAL
```

Watermark rendered at serve time. No "clean" version ever served.

---

## 7. Navigation Components

### 7.1 Project Selector

```html
<select class="project-select">
  <option>Project Alpha — TargetCo Acquisition</option>
  <option>Project Beta — MergeCo Deal</option>
</select>
```

- One line. Always visible. Never a sidebar.
- Workers (single project): selector hidden
- Multi-project users: dropdown in header

### 7.2 Workstream Tabs

```html
<nav class="workstream-tabs">
  <a href="#" class="active">Finance</a>
  <a href="#">Legal</a>
  <a href="#">IT</a>
  <a href="#">HR</a>
  <a href="#">Operations</a>
</nav>
```

- Horizontal tabs below header
- Active state: underline + bold
- Badge shows pending count per workstream

### 7.3 Global Header

```html
<header class="global-header">
  <div class="logo">Dealspace</div>
  <select class="project-select">...</select>
  <nav class="global-nav">
    <a href="/inbox" class="inbox-link">
      Inbox <span class="badge">3</span>
    </a>
    <div class="user-menu">
      <img src="avatar.jpg" class="avatar" />
      <span class="user-name">J. Smith</span>
    </div>
  </nav>
</header>
```

---

## 8. Status Indicators

### 8.1 Priority

| Priority | Indicator | CSS Class |
|----------|-----------|-----------|
| High | 🔴 Red dot | `.priority-high` |
| Normal | 🟡 Amber dot | `.priority-normal` |
| Low | ⚪ Gray dot | `.priority-low` |

### 8.2 Due Date States

| State | Styling |
|-------|---------|
| Future | Normal text, muted color |
| Due Today | Bold, warning color |
| Overdue | Bold, error color, badge |

### 8.3 Request Status

| Status | Badge | Color |
|--------|-------|-------|
| Open | OPEN | Gray |
| Assigned | ASSIGNED | Blue |
| Answered | ANSWERED | Amber |
| Vetted | VETTED | Purple |
| Published | PUBLISHED | Green |
| Closed | CLOSED | Gray muted |

### 8.4 Workstream Badges

Show count of items needing attention:
```html
<a href="#">Finance <span class="badge">5</span></a>
```

Badge colors:
- Red: overdue items
- Amber: due today
- Gray: pending but not urgent

---

## 9. Theme System

### 9.1 Core Principle

Zero hardcoded colors. Every visual property references a CSS custom property.

### 9.2 Property Taxonomy

```css
/* Surface colors */
--color-bg-primary       /* Main background */
--color-bg-secondary     /* Cards, panels */
--color-bg-tertiary      /* Nested elements */
--color-bg-inverse       /* Inverted sections */

/* Text colors */
--color-text-primary     /* Body text */
--color-text-secondary   /* Muted text */
--color-text-tertiary    /* Placeholders */
--color-text-inverse     /* On dark backgrounds */

/* Border colors */
--color-border-primary   /* Default borders */
--color-border-secondary /* Subtle dividers */

/* Semantic colors */
--color-accent           /* Primary action, links */
--color-accent-hover     /* Hover state */
--color-success          /* Published, done */
--color-warning          /* Due today, caution */
--color-error            /* Overdue, rejected */
--color-info             /* Informational */

/* Priority indicators */
--color-priority-high
--color-priority-normal
--color-priority-low

/* Status badges */
--color-status-open
--color-status-assigned
--color-status-answered
--color-status-vetted
--color-status-published
--color-status-closed

/* Component-specific */
--color-header-bg
--color-header-text
--color-sidebar-bg
--color-card-bg
--color-card-border
--color-input-bg
--color-input-border
--color-input-focus

/* Shadows */
--shadow-sm
--shadow-md
--shadow-lg

/* Spacing (not colors, but themeable) */
--radius-sm
--radius-md
--radius-lg
```

### 9.3 Built-in Themes

**Light (default)**
- Clean white backgrounds
- Dark text on light
- Subtle gray borders

**Dark**
- Dark gray backgrounds
- Light text on dark
- Reduced contrast borders

**High Contrast**
- True black/white
- Bold borders
- Maximum readability

### 9.4 Per-Project Themes

Projects can override:
- `--color-accent` (brand primary)
- `--color-header-bg` (branded header)
- Logo replacement

Applied via:
```html
<html class="theme-light" data-project="alpha">
```

### 9.5 Theme Switching

No JavaScript framework required:
```javascript
document.documentElement.className = 'theme-dark';
```

User preference stored in localStorage, synced to server on login.

---

## 10. Responsive Behavior

### 10.1 Breakpoints

| Name | Width | Behavior |
|------|-------|----------|
| Desktop | ≥1024px | Full layout |
| Tablet | 768-1023px | Condensed sidebar |
| Mobile | <768px | Stacked, bottom nav |

### 10.2 Mobile Adaptations

- Workstream tabs → horizontal scroll
- Task cards → full width
- Thread view → stacked messages
- Data room → accordion folders

### 10.3 Touch Targets

Minimum 44x44px for all interactive elements.

---

## 11. Accessibility

### 11.1 Requirements

- WCAG 2.1 AA compliance
- Keyboard navigation (all actions)
- Screen reader support (ARIA labels)
- Focus indicators (visible, high contrast)
- Color not sole indicator (icons + color)

### 11.2 High Contrast Mode

Built-in theme with:
- 7:1 contrast ratio (AAA)
- Bold borders
- No gradient backgrounds
- Underlined links

---

## 12. Implementation Notes

### 12.1 No Framework

Plain HTML + CSS + minimal JS. No React, Vue, or Tailwind runtime.

Tailwind-style utility classes are fine for mockups, but production CSS should be:
- Custom properties for theming
- Semantic class names
- Minimal specificity

### 12.2 Template Structure

```
portal/
  templates/
    base.html           # Shell: head, header, footer
    inbox.html          # Task inbox
    request.html        # Request detail
    deal.html           # Deal overview (admin)
    workstream.html     # Workstream view
    dataroom.html       # Buyer data room
    settings.html       # Project settings
  static/
    themes.css          # All theme definitions
    components.css      # Reusable component styles
    layout.css          # Grid, spacing
    main.js             # Minimal interactivity
```

### 12.3 Form Handling

Standard form submissions. No SPA routing. Progressive enhancement only.

---

## 13. Mockup Files

- `portal/templates/task-inbox.html` — The worker's primary view
- `portal/templates/request-detail.html` — Thread + routing + actions
- `portal/static/themes.css` — Full theme variable definitions

---

*This document defines UI/UX. Implementation follows the patterns. When in doubt, simpler wins.*
