community-ade/docs/ui-components.md

Community ADE Approval System - Dashboard UI Specifications

Overview

This document defines the UI components and specifications for the Delta-V2 Dashboard's Approval System integration. The dashboard provides human operators with visibility and control over the approval workflow.

---

Design System

Color Palette

Token	Hex	Usage
--color-primary	#3B82F6	Primary actions, links
--color-primary-dark	#2563EB	Hover states
--color-success	#10B981	Approved, completed, success states
--color-warning	#F59E0B	Pending, medium risk, warnings
--color-danger	#EF4444	Rejected, high risk, errors
--color-info	#6366F1	Info states, low risk
--color-neutral-100	#F3F4F6	Backgrounds
--color-neutral-200	#E5E7EB	Borders
--color-neutral-700	#374151	Body text
--color-neutral-900	#111827	Headings

State Colors

State	Background	Border	Text	Icon
DRAFT	#F3F4F6	#D1D5DB	#6B7280	Edit icon
SUBMITTED	#DBEAFE	#93C5FD	#1E40AF	Upload icon
REVIEWING	#FEF3C7	#FCD34D	#92400E	Eye icon
APPROVED	#D1FAE5	#6EE7B7	#065F46	Check icon
APPLYING	#E0E7FF	#A5B4FC	#3730A3	Play icon (animated)
COMPLETED	#D1FAE5	#10B981	#065F46	CheckCircle icon
REJECTED	#FEE2E2	#FCA5A5	#991B1B	X icon
CANCELLED	#F3F4F6	#9CA3AF	#4B5563	Slash icon

Typography

Level	Font	Size	Weight	Line Height
H1	Inter	24px	600	1.3
H2	Inter	20px	600	1.3
H3	Inter	16px	600	1.4
Body	Inter	14px	400	1.5
Small	Inter	12px	400	1.5
Mono	JetBrains Mono	13px	400	1.5

---

Layout Structure

┌─────────────────────────────────────────────────────────────────────────────┐
│  HEADER                                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  Logo    Search    [🔔 Notifications]    [👤 User Menu]            │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────────────────┤
│  SIDEBAR    │  MAIN CONTENT                                                  │
│             │                                                                │
│  Dashboard  │  ┌────────────────────────────────────────────────────────┐  │
│  Tasks      │  │  PAGE HEADER                                           │  │
│  Approvals  │  │  [Title]              [Primary Action] [Secondary]    │  │
│  ─────────  │  └────────────────────────────────────────────────────────┘  │
│  Locks      │                                                                │
│  Audit Log  │  ┌────────────────────────────────────────────────────────┐  │
│  ─────────  │  │  CONTENT AREA                                          │  │
│  Settings   │  │                                                        │  │
│             │  │  [Cards / Tables / Forms / Modals as needed]          │  │
│             │  │                                                        │  │
│             │  └────────────────────────────────────────────────────────┘  │
│             │                                                                │
└─────────────┴────────────────────────────────────────────────────────────────┘

---

Component Specifications

1. Navigation Components

Sidebar Navigation

interface SidebarProps {
  activeSection: 'dashboard' | 'tasks' | 'approvals' | 'locks' | 'audit' | 'settings';
  badgeCounts: {
    approvals: number;  // Pending approvals for current user
    locks: number;      // Active locks requiring attention
  };
  user: {
    name: string;
    role: string;
    avatarUrl?: string;
  };
}

Features:

• Collapsible on mobile (drawer)
• Badge indicators for pending items
• Keyboard navigation support (Arrow keys, Enter)
• Active state highlighting

Menu Items:

• Dashboard (overview stats)
• Tasks (all tasks)
• Approvals (queue) - with badge count
• Locks (lock manager)
• Audit Log
• Settings

---

2. Dashboard Components

Stats Overview Card

interface StatsCardProps {
  title: string;
  value: number | string;
  trend?: {
    direction: 'up' | 'down' | 'neutral';
    value: string;
    label: string;
  };
  icon: IconComponent;
  color: 'primary' | 'success' | 'warning' | 'danger' | 'info';
  linkTo?: string;
}

Layout:

┌────────────────────────────┐
│  [Icon]                    │
│                            │
│  Title                     │
│  ┌────────────────────┐    │
│  │ VALUE              │    │
│  └────────────────────┘    │
│  ▲ 12% vs last week        │
└────────────────────────────┘

Dashboard Stats:

1. Pending My Approval (count + link)
2. Tasks in Review (count)
3. Active Locks (count)
4. Completed Today (count + success rate)

---

Approval Queue Widget

interface ApprovalQueueWidgetProps {
  approvals: Array<{
    id: string;
    taskId: string;
    taskType: string;
    taskDescription: string;
    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
    requestedBy: string;
    requestedAt: string;
    dueAt?: string;
    priority: 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
  }>;
  onApprove: (id: string) => void;
  onReject: (id: string) => void;
  onView: (id: string) => void;
  maxItems?: number;
}

Features:

• Expandable list (default show 5, "View All" link)
• Inline quick actions (Approve/Reject with confirmation)
• Color-coded risk badges
• Relative timestamps ("2 hours ago")
• Urgent items highlighted with red border

---

Activity Feed

interface ActivityFeedProps {
  events: Array<{
    id: string;
    type: 'task_created' | 'task_submitted' | 'approval_requested' | 
          'approval_responded' | 'task_executing' | 'task_completed' | 
          'lock_acquired' | 'lock_released';
    actor: {
      id: string;
      name: string;
      avatarUrl?: string;
    };
    target: {
      type: 'task' | 'approval' | 'lock';
      id: string;
      name: string;
    };
    metadata?: Record<string, unknown>;
    timestamp: string;
  }>;
  maxItems?: number;
  pollInterval?: number;
}

Features:

• Real-time updates via WebSocket
• Collapsible event details
• Click to navigate to related resource
• Infinite scroll or pagination

---

3. Task Components

Task List Table

interface TaskListTableProps {
  tasks: TaskResponse[];
  columns: Array<{
    key: string;
    title: string;
    sortable?: boolean;
    width?: string;
  }>;
  selectedIds: string[];
  onSelect: (ids: string[]) => void;
  onRowClick: (task: TaskResponse) => void;
  onSort: (key: string, order: 'asc' | 'desc') => void;
  pagination: {
    page: number;
    limit: number;
    total: number;
    onChange: (page: number) => void;
  };
  filters: TaskFilters;
  onFilterChange: (filters: TaskFilters) => void;
}

interface TaskFilters {
  state?: TaskState[];
  author?: string;
  resourceType?: ResourceType;
  riskLevel?: RiskLevel;
  dateRange?: { from: Date; to: Date };
  tags?: string[];
}

Columns:

Column	Width	Sortable	Content
Checkbox	40px	No	Multi-select
State	120px	Yes	Badge with icon
Task	300px	Yes	Description + type tag
Author	150px	Yes	Avatar + name
Risk	100px	Yes	Score + level badge
Resources	200px	Yes	Icon list (hover for details)
Created	150px	Yes	Relative time
Actions	100px	No	Menu button

Features:

• Batch actions toolbar (appears on selection)
• Column resizing
• Export to CSV/JSON
• Saved filter presets

---

Task State Badge

interface TaskStateBadgeProps {
  state: TaskState;
  size?: 'sm' | 'md' | 'lg';
  showIcon?: boolean;
  pulse?: boolean;  // Animate for APPLYING state
}

Visual States:

• DRAFT: Gray, edit icon
• SUBMITTED: Blue, upload icon
• REVIEWING: Yellow, eye icon
• APPROVED: Green with border, check icon
• APPLYING: Indigo, animated spinner + play icon
• COMPLETED: Solid green, check-circle icon
• REJECTED: Red, X icon
• CANCELLED: Gray strikethrough, slash icon

---

Risk Score Indicator

interface RiskScoreProps {
  score: number;  // 0-100
  size?: 'sm' | 'md' | 'lg';
  showLabel?: boolean;
  showFactors?: boolean;
}

Visual Design:

┌────────────────────────────────┐
│ ┌──────────┐                   │
│ │    75    │  HIGH RISK        │
│ │  ┌──┐    │                   │
│ │  │██│    │  • Critical resource │
│ │  │██│    │  • Wide blast radius │
│ │  │░░│    │  • No rollback    │
│ └──┴──┴────┘                   │
└────────────────────────────────┘

• Circular progress indicator
• Color gradient: Green (0) → Yellow (50) → Red (100)
• Tooltip showing risk factors on hover

---

Task Detail View

interface TaskDetailViewProps {
  task: TaskResponse;
  activeTab: 'overview' | 'preview' | 'approvals' | 'execution' | 'audit';
  onTabChange: (tab: string) => void;
  onAction: (action: 'submit' | 'cancel' | 'retry') => void;
}

Layout:

┌─────────────────────────────────────────────────────────────────┐
│  Breadcrumbs > Task: Database Migration                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  [State Badge]  Task Title                              │   │
│  │  Created by John Doe • 2 hours ago • Ticket: PROJ-123   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Overview] [Preview] [Approvals] [Execution] [Audit]          │
│  ─────────────────────────────────────────────────────────      │
│                                                                 │
│  TAB CONTENT                                                    │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  ACTION BAR (contextual based on state)                        │
│  [Submit for Approval] [Save Draft] [Cancel]                   │
└─────────────────────────────────────────────────────────────────┘

---

Preview Panel

interface PreviewPanelProps {
  preview: PreviewResult;
  onRefresh: () => void;
  lastUpdated: string;
}

Content:

• Validation status (valid/invalid with error list)
• Change list with diff view
• Affected services diagram
• Estimated execution time
• Rollback capability indicator

Diff View Component:

┌─────────────────────────────────────────────────────────────┐
│  Resource: database/prod-db-01                              │
│  Action: MODIFY                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌────────────────┐                    │
│  │ BEFORE         │  │ AFTER          │                    │
│  │                │  │                │                    │
│  │ instance:      │  │ instance:      │                    │
│  │   type: db.m5  │  │   type: db.r6  │ ◄── Changed        │
│  │   size: large  │  │   size: xlarge │ ◄── Changed        │
│  │   storage: 100 │  │   storage: 100 │                    │
│  │                │  │                │                    │
│  └────────────────┘  └────────────────┘                    │
└─────────────────────────────────────────────────────────────┘

---

4. Approval Components

Approval Card

interface ApprovalCardProps {
  approval: {
    id: string;
    task: {
      id: string;
      title: string;
      type: string;
      description: string;
      risk: RiskAssessment;
      resources: ResourceRef[];
      preview: PreviewResult;
    };
    requestedBy: {
      id: string;
      name: string;
      avatarUrl?: string;
      team?: string;
    };
    requestedAt: string;
    dueAt?: string;
    priority: 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
    delegationChain?: string[];
  };
  onApprove: (id: string, reason?: string) => void;
  onReject: (id: string, reason: string) => void;
  onRequestChanges: (id: string, feedback: string) => void;
  onDelegate: (id: string, delegateTo: string) => void;
}

Layout:

┌─────────────────────────────────────────────────────────────────┐
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ [Avatar] Requested by Sarah Chen • Platform Team       │   │
│  │ 2 hours ago • Due in 2 days                            │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Database Migration - Shard Addition                           │
│  [INFRASTRUCTURE] [HIGH PRIORITY]                              │
│                                                                 │
│  Add new read replica to handle increased traffic...           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ RISK SCORE: 65/100 [MEDIUM]                             │   │
│  │ • Production database affected                          │   │
│  │ • 15-minute estimated downtime                          │   │
│  │ • Automatic rollback available                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  AFFECTED RESOURCES:                                           │
│  [DB] prod-db-01  [SVC] api-service  [SVC] worker-queue        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ CHANGES PREVIEW (3 changes)                    [View ▼] │   │
│  │ • Modify database instance size                        │   │
│  │ • Update service configuration                         │   │
│  │ • Scale worker replicas                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [✓ Approve]  [✗ Reject]  [💬 Request Changes]  [➡ Delegate] │
│                                                                 │
│  Reason (required for rejection):                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

Batch Approval Panel

interface BatchApprovalPanelProps {
  selectedApprovals: string[];
  approvals: Array<{
    id: string;
    taskTitle: string;
    riskLevel: string;
  }>;
  onBatchAction: (action: 'approve' | 'reject', options: BatchOptions) => void;
  onClearSelection: () => void;
}

interface BatchOptions {
  applyImmediately: boolean;
  skipValidation: boolean;
  continueOnError: boolean;
}

Features:

• Slide-out panel from right
• Summary of selected items
• Risk level aggregation ("3 Low, 2 High risk")
• Bulk action with confirmation
• Apply immediately toggle

---

Delegation Settings Panel

interface DelegationSettingsProps {
  policies: DelegationPolicy[];
  availableDelegates: Array<{
    id: string;
    name: string;
    role: string;
    avatarUrl?: string;
  }>;
  onCreatePolicy: (policy: Omit<DelegationPolicy, 'id'>) => void;
  onUpdatePolicy: (id: string, updates: Partial<DelegationPolicy>) => void;
  onDeletePolicy: (id: string) => void;
}

Features:

• Visual policy builder
• Condition preview ("When task is INFRASTRUCTURE and risk > 50")
• Chain visualization
• Active/Inactive toggle

---

5. Lock Components

Lock Monitor Dashboard

interface LockMonitorProps {
  locks: Array<{
    id: string;
    resourceType: 'task' | 'resource' | 'agent';
    resourceId: string;
    mode: 'exclusive' | 'shared';
    holder: {
      agentId: string;
      agentName: string;
      acquiredAt: string;
      expiresAt: string;
      purpose?: string;
    };
    queue: Array<{
      agentId: string;
      position: number;
      waitTime: number;
    }>;
    ttl: number;
  }>;
  deadlocks: DeadlockInfo[];
  onForceRelease: (lockId: string, reason: string) => void;
  onRefresh: () => void;
}

Layout:

┌─────────────────────────────────────────────────────────────────┐
│  LOCK MONITOR                                      [↻ Refresh] │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Active Locks    │ │ Waiting Agents  │ │ Detected Dead-  │   │
│  │ 24              │ │ 7               │ │ locks 0         │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ACTIVE LOCKS                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Type     Resource        Holder      TTL    Queue  Act  │   │
│  │ ──────────────────────────────────────────────────────── │   │
│  │ task     task-123        agent-01    23s    2      [⋯]  │   │
│  │ resource db/prod-01      agent-03    45s    0      [⋯]  │   │
│  │ task     task-456        agent-02    12s    1      [⋯]  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  LOCK QUEUE                                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Position  Agent       Waiting For    Est. Time         │   │
│  │ ──────────────────────────────────────────────────────── │   │
│  │ 1         agent-04    task-123         ~15s             │   │
│  │ 2         agent-05    task-123         ~30s             │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

Lock Detail Modal

interface LockDetailModalProps {
  lock: LockInfo;
  isOpen: boolean;
  onClose: () => void;
  onForceRelease: (reason: string) => void;
  onExtendTTL: (seconds: number) => void;
}

Content:

• Lock metadata
• Holder information with heartbeat status
• Queue visualization (if waiters exist)
• Action buttons (Extend, Force Release - admin only)
• Lock history/timeline

---

Deadlock Alert

interface DeadlockAlertProps {
  deadlocks: DeadlockInfo[];
  onResolve: (deadlockId: string, strategy: 'abort_youngest' | 'abort_shortest') => void;
  onDismiss: (deadlockId: string) => void;
}

Visual Design:

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️  DEADLOCK DETECTED                                          │
├─────────────────────────────────────────────────────────────────┤
│  Circular wait detected between:                                │
│                                                                 │
│  agent-01 ──holds──► lock:task:123                              │
│     ▲                                      │                    │
│     └────────waits─────────────────────────┘                    │
│                                                                 │
│  agent-02 ──holds──► lock:resource:db/prod-01                   │
│     ▲                                      │                    │
│     └────────waits─────────────────────────┘                    │
│                                                                 │
│  [Resolve: Abort Youngest]  [Resolve: Abort Shortest]          │
└─────────────────────────────────────────────────────────────────┘

---

6. Form Components

Task Creation Form

interface TaskCreationFormProps {
  initialValues?: Partial<TaskConfig>;
  resourceTypes: ResourceType[];
  availableResources: Array<{
    type: ResourceType;
    id: string;
    name: string;
  }>;
  onSubmit: (values: TaskConfig) => Promise<void>;
  onPreview: (values: TaskConfig) => Promise<PreviewResult>;
  onSaveDraft: (values: Partial<TaskConfig>) => Promise<void>;
}

Sections:

1. Basic Info: Type, Description, Priority
2. Resources: Multi-select with type filtering
3. Parameters: Dynamic form based on task type
4. Advanced: Timeout, Rollback strategy, Tags
5. Preview: Side panel showing changes before submit

---

Approval Response Form

interface ApprovalResponseFormProps {
  approvalId: string;
  action: 'approve' | 'reject' | 'request_changes';
  requireReason: boolean;
  onSubmit: (values: { action: string; reason?: string }) => void;
  onCancel: () => void;
}

Features:

• Quick select buttons for common rejection reasons
• Character counter for reason field
• File attachment for supporting docs

---

7. Feedback Components

Toast Notifications

interface ToastProps {
  id: string;
  type: 'success' | 'error' | 'warning' | 'info';
  title: string;
  message?: string;
  action?: {
    label: string;
    onClick: () => void;
  };
  duration?: number;
  onClose: (id: string) => void;
}

Events:

• Approval submitted
• Task approved/rejected
• Lock acquired/released
• Error notifications

---

Confirmation Dialogs

interface ConfirmationDialogProps {
  isOpen: boolean;
  title: string;
  message: string;
  confirmLabel: string;
  cancelLabel: string;
  danger?: boolean;
  requireText?: string;  // Type to confirm (for destructive actions)
  onConfirm: () => void;
  onCancel: () => void;
}

Use Cases:

• Force release lock
• Cancel running task
• Batch approve high-risk items
• Delete delegation policy

---

8. Real-time Components

Live Update Indicator

interface LiveIndicatorProps {
  status: 'connected' | 'disconnected' | 'reconnecting';
  lastUpdate?: string;
}

Visual:

• Green pulse dot when connected
• Yellow when reconnecting
• Red when disconnected with retry button

---

WebSocket Status Bar

interface WebSocketStatusProps {
  connectionState: 'connecting' | 'open' | 'closed' | 'error';
  pendingEvents: number;
  onReconnect: () => void;
}

---

Responsive Breakpoints

Breakpoint	Width	Layout Changes
Mobile	< 640px	Single column, sidebar becomes drawer, table becomes cards
Tablet	640-1024px	Two columns where applicable, condensed sidebar
Desktop	1024-1440px	Full layout, fixed sidebar
Wide	> 1440px	Expanded content area, more data visible

---

Accessibility Requirements

ARIA Labels

• All interactive elements have descriptive labels
• Live regions for real-time updates
• Role="status" for async operations

Keyboard Navigation

• Tab order follows visual flow
• Escape closes modals/drawers
• Enter activates buttons, Space toggles checkboxes
• Arrow keys navigate tables and lists

Screen Reader Support

• State changes announced via aria-live
• Complex visualizations have text alternatives
• Risk scores read as "High risk: 75 out of 100"

Color Contrast

• Minimum 4.5:1 for normal text
• Minimum 3:1 for large text and icons
• States distinguishable without color

---

Performance Targets

Metric	Target
Initial Load	< 2s
Time to Interactive	< 3s
List Scroll	60fps
Modal Open	< 100ms
Real-time Update	< 500ms latency
Form Submit	< 200ms feedback

---

Integration Points

API Integration

• REST API for CRUD operations
• WebSocket for real-time events
• Server-Sent Events fallback

External Services

• Auth provider for user info
• File storage for attachments
• Search service for full-text search

Browser APIs

• Notifications API for approval alerts
• Idle Detection for auto-refresh pause
• Page Visibility for connection management