johan
/
dealspace
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dealspace/UI-SPEC.md

633 lines
22 KiB
Markdown
Raw Blame History

# 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.*
Reference in New Issue View Git Blame Copy Permalink