# UI/UX Specification: ISO-20022 Combo Builder v2 ## Overview This document specifies the user interface and user experience for the Combo Builder v2, which enables users to compose multi-step financial workflows combining DeFi protocols and traditional banking rails (ISO-20022). The UI is inspired by Furucombo's Create page but extends it with compliance overlays, hybrid adapter support, and optional simulation. ## Design Principles 1. **Composability**: Drag-and-drop interface for building complex financial workflows 2. **Transparency**: Clear display of compliance status, fees, and execution risks 3. **Flexibility**: Support for both DeFi and fiat/DTL adapters with selection control 4. **User Control**: Optional simulation for advanced users, mandatory compliance checks 5. **Accessibility**: Intuitive for non-developers while providing advanced features --- ## 1. Main Builder Canvas ### Layout Structure ``` ┌─────────────────────────────────────────────────────────────────┐ │ Header: [Combo Builder] [User Identity] [Wallet] [Settings] │ ├─────────────┬─────────────────────────────────────────────────────────┤ │ │ │ │ Adapter │ Canvas (Drop Zone) │ │ Palette │ ┌─────────────────────┐ │ │ │ │ Step 1: Borrow │ │ │ [DeFi] │ │ 💰 CBDC_USD: 100k │ │ │ - Swap │ └─────────────────────┘ │ │ - Borrow │ ┌─────────────────────┐ │ │ - Deposit │ │ Step 2: Swap │ │ │ - Bridge │ │ 🔄 USD → EUR │ │ │ │ └─────────────────────┘ │ │ [Fiat] │ ┌─────────────────────┐ │ │ - Pay │ │ Step 3: Pay │ │ │ - Repay │ │ 📤 EUR to IBAN │ │ │ - Transfer │ └─────────────────────┘ │ │ │ │ │ [Compliance]│ │ │ ✓ LEI │ │ │ ✓ KYC │ │ │ ✓ AML │ │ └─────────────┴─────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Summary Panel: │ │ Initial Funds: 100,000 CBDC_USD │ │ You will receive: ~78,000 EUR │ │ Fees: 0.2% (200 USD) | Compliance: ✓ | Simulation: [Toggle] │ │ [Review & Sign] [Simulate] [Save Draft] │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components #### A. Adapter Palette (Left Sidebar) - **DeFi Section**: Swappable protocols (Uniswap, Aave, Compound, etc.) - **Fiat/DTL Section**: Banking rails (ISO-20022 pay, SWIFT, SEPA, etc.) - **Compliance Badge**: Shows current user compliance status (LEI/DID/KYC/AML) - **Filter Toggle**: "Show All" / "Show Whitelisted Only" / "Show DeFi Only" / "Show Fiat Only" #### B. Canvas (Center) - **Drop Zone**: Visual area where users place workflow steps - **Step Cards**: Each step shows: - Step number (1, 2, 3...) - Icon (💰, 🔄, 💳, 📤) - Step type and summary - Compliance badge (if applicable) - Drag handle (⋮⋮) for reordering - Edit/Remove buttons #### C. Summary Panel (Bottom) - **Initial Funds**: What user must supply (from wallet or borrow) - **You will receive**: Expected output at workflow end - **Fee Display**: "Included 0.2% fee" (if applicable) - **Compliance Status**: Visual indicators (✓ LEI, ✓ KYC, ✓ AML, ✓ DID) - **Simulation Toggle**: Optional checkbox for advanced users - **Action Buttons**: Review & Sign, Simulate (optional), Save Draft --- ## 2. Step Configuration Drawer ### Layout ``` ┌────────────────────────────────────────────────────────┐ │ Configure Step: Swap [X] │ ├────────────────────────────────────────────────────────┤ │ │ │ From Token: [CBDC_USD ▼] │ │ Amount: [100,000] │ │ │ │ To Token: [CBDC_EUR ▼] │ │ Min Receive: [90,000] (auto-calculated) │ │ │ │ Slippage: [0.5%] (default) │ │ │ │ ────────────────────────────────────────────────────── │ │ │ │ Compliance Requirements: │ │ ☑ LEI Required: [5493000IBP32UQZ0KL24] │ │ ☑ KYC Status: ✓ Verified │ │ ☑ AML Check: ✓ Passed │ │ │ │ [Save] [Cancel] │ └────────────────────────────────────────────────────────┘ ``` ### Features - **Token/Asset Selection**: Dropdown with supported tokens (DeFi) or currencies (Fiat) - **Amount Input**: Numeric input with validation - **Compliance Fields**: Auto-populated from user session (LEI, KYC, AML status) - **Dependency Visualization**: Shows which previous steps feed into this step - **Validation Feedback**: Real-time error messages (insufficient balance, invalid IBAN, etc.) --- ## 3. Simulation Results Panel (Optional) ### Layout ``` ┌────────────────────────────────────────────────────────┐ │ Simulation Results [Close] │ ├────────────────────────────────────────────────────────┤ │ Status: ✓ Simulation Successful │ │ │ │ Execution Summary: │ │ • Step 1 (Borrow): ✓ 100,000 CBDC_USD │ │ • Step 2 (Swap): ✓ 90,000 CBDC_EUR (estimated) │ │ • Step 3 (Pay): ✓ 78,000 EUR to beneficiary │ │ │ │ Gas Estimate: 450,000 gas │ │ Estimated Cost: $25.50 (at 50 gwei) │ │ │ │ Slippage Risk: Low (0.2% expected) │ │ Liquidity Check: ✓ Sufficient │ │ │ │ Compliance: ✓ All checks passed │ │ │ │ [Run Simulation Again] [Proceed to Sign] │ └────────────────────────────────────────────────────────┘ ``` ### Features - **Step-by-Step Results**: Shows success/failure for each step - **Gas Estimation**: Calculated gas cost for entire workflow - **Slippage Analysis**: Expected slippage for swaps - **Liquidity Checks**: Verifies sufficient liquidity for trades - **Compliance Status**: Confirms all compliance requirements met - **Error Warnings**: Highlights any potential failure points --- ## 4. Compliance Status Dashboard Overlay ### Layout ``` ┌────────────────────────────────────────────────────────┐ │ Compliance Status [Dismiss] │ ├────────────────────────────────────────────────────────┤ │ │ │ Identity Verification: │ │ ✓ LEI: 5493000IBP32UQZ0KL24 │ │ ✓ DID: did:web:example.com:user:123 │ │ ✓ KYC: Level 2 Verified (Expires: 2026-12-31) │ │ ✓ AML: Passed (Last check: 2025-01-15) │ │ │ │ Current Workflow Compliance: │ │ • All steps require LEI: ✓ Provided │ │ • KYC Level Required: 2 ✓ Met │ │ • AML Screening: ✓ Passed │ │ │ │ Missing Requirements: None │ │ │ │ [Update Identity] [View Compliance Details] │ └────────────────────────────────────────────────────────┘ ``` ### Features - **Always Visible Badge**: Small indicator in header showing compliance status - **Detailed View**: Expandable overlay with full compliance details - **Workflow-Specific Checks**: Validates compliance for current workflow - **Expiration Warnings**: Alerts if KYC/AML checks are expiring soon - **Update Actions**: Quick links to update identity or run new checks --- ## 5. Adapter Selection Modal ### Layout ``` ┌────────────────────────────────────────────────────────┐ │ Select Adapter Type [X] │ ├────────────────────────────────────────────────────────┤ │ │ │ Filter: [All] [DeFi] [Fiat/DTL] [Whitelisted Only] │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ DeFi Protocols │ │ Fiat/DTL Rails │ │ │ ├──────────────────┤ ├──────────────────┤ │ │ │ 🔄 Uniswap V3 │ │ 📤 ISO-20022 Pay │ │ │ │ 💰 Aave │ │ 💳 SWIFT MT │ │ │ │ 📊 Compound │ │ 🌐 SEPA │ │ │ │ 🌉 Bridge │ │ 🏦 FedNow │ │ │ │ │ │ │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ │ Selected: ISO-20022 Pay │ │ │ │ [Add to Palette] [Cancel] │ └────────────────────────────────────────────────────────┘ ``` ### Features - **Category Filtering**: Separate DeFi and Fiat/DTL adapters - **Whitelist Toggle**: Show only approved/whitelisted adapters - **Adapter Status**: Visual indicators (✓ Approved, ⚠ Deprecated, 🔒 Restricted) - **Search**: Quick search for specific adapters - **Version Info**: Shows adapter version and last updated date --- ## 6. User Flows ### Flow 1: Building a Simple Combo (DeFi Only) 1. User opens Builder page 2. User drags "Borrow" from DeFi palette → Canvas 3. Configures borrow step (asset, amount, collateral) 4. Drags "Swap" from palette → Canvas (after borrow step) 5. Configures swap step (from/to tokens, amount) 6. Summary panel updates automatically 7. User clicks "Review & Sign" (compliance auto-checked) 8. Redirected to preview/sign page ### Flow 2: Building Hybrid Combo (DeFi + Fiat) 1. User opens Builder page 2. Compliance badge shows: ✓ LEI, ✓ KYC, ✓ AML 3. User drags "Borrow" (DeFi) → Canvas 4. User drags "Swap" (DeFi) → Canvas 5. User drags "Pay" (Fiat/DTL) → Canvas 6. Configures pay step (IBAN, amount, beneficiary) 7. Compliance overlay appears: "Fiat step requires LEI" 8. LEI auto-populated from user session 9. User optionally enables simulation toggle 10. Clicks "Simulate" → sees results 11. Clicks "Review & Sign" → proceeds ### Flow 3: Advanced User with Simulation 1. User enables "Simulation" toggle in summary panel 2. Builds workflow as normal 3. Before signing, clicks "Simulate" button 4. Simulation results panel shows: - Gas estimate - Slippage analysis - Liquidity checks - Failure predictions 5. User reviews results, adjusts workflow if needed 6. Clicks "Proceed to Sign" after simulation passes ### Flow 4: Compliance Validation Failure 1. User builds workflow with fiat step requiring LEI 2. User has not provided LEI in settings 3. Compliance badge shows: ⚠ LEI Missing 4. User attempts to sign 5. Error modal: "LEI required for this workflow. Please update your identity in Settings." 6. User redirected to Settings page to add LEI 7. Returns to Builder, workflow auto-validated --- ## 7. Responsive Design ### Desktop (≥1024px) - Full layout with sidebar palette, canvas, and summary panel - All features visible simultaneously ### Tablet (768px - 1023px) - Collapsible sidebar palette - Canvas takes full width when palette collapsed - Summary panel remains at bottom ### Mobile (<768px) - Palette accessible via bottom sheet/modal - Canvas scrollable vertically - Step cards stack vertically - Summary panel sticky at bottom --- ## 8. Accessibility Requirements - **Keyboard Navigation**: Full keyboard support for drag-and-drop (arrow keys, space/enter) - **Screen Reader Support**: ARIA labels for all interactive elements - **Color Contrast**: WCAG AA compliance for all text and UI elements - **Focus Indicators**: Clear focus states for all interactive elements - **Error Messages**: Clear, actionable error messages for all validation failures --- ## 9. Performance Requirements - **Initial Load**: < 2 seconds for Builder page - **Step Addition**: < 500ms for drag-and-drop response - **Summary Calculation**: Real-time updates < 200ms - **Simulation**: < 5 seconds for full workflow simulation - **Compliance Check**: < 1 second for status validation --- ## 10. Integration Points ### Frontend → Backend API - `POST /api/plans` - Create execution plan - `GET /api/plans/:id/simulate` - Run simulation (optional) - `GET /api/compliance/status` - Fetch compliance status - `GET /api/adapters` - List available adapters (filtered by type/whitelist) ### Frontend → Smart Contracts - Wallet connection via Wagmi - Plan signing via wallet signature - Transaction submission via handler contract --- ## 11. Visual Design System ### Color Palette - **Primary**: Black (#000000) for actions - **Secondary**: Blue (#3B82F6) for compliance/info - **Success**: Green (#10B981) for valid states - **Warning**: Yellow (#F59E0B) for warnings - **Error**: Red (#EF4444) for errors - **Background**: White (#FFFFFF) for cards, Gray-50 (#F9FAFB) for canvas ### Typography - **Headings**: Inter, 24px/32px (h1), 18px/24px (h2) - **Body**: Inter, 14px/20px - **Code/Monospace**: Fira Code, 12px/16px for addresses/IDs ### Icons - Emoji icons for step types (💰, 🔄, 💳, 📤) - Lucide React icons for UI elements (Edit, Remove, Drag, etc.) --- ## 12. Error States & Edge Cases ### Insufficient Balance - Red warning badge on step card - Error message: "Insufficient balance. You need 100,000 CBDC_USD but have 50,000." ### Invalid Workflow - Step dependency error: "Step 2 requires output from Step 1. Please reorder steps." - Visual connection lines between dependent steps ### Compliance Failure - Modal overlay: "This workflow requires LEI verification. Please update your identity in Settings." - Link to Settings page ### Simulation Failure - Results panel shows: "⚠ Simulation Failed" - Detailed error: "Step 2 (Swap) would fail due to insufficient liquidity." ### Network/Chain Mismatch - Warning: "Selected adapter (Uniswap) is on Ethereum, but you're connected to Polygon." - Option to switch network or select different adapter --- ## 13. Future Enhancements (Out of Scope for v2) - **Workflow Templates**: Pre-built combo templates for common strategies - **Workflow Sharing**: Share workflows with other users (with compliance validation) - **Multi-user Workflows**: Collaborative workflow building - **Advanced Analytics**: Historical performance tracking for workflows - **Mobile App**: Native mobile app for workflow building --- ## Acceptance Criteria 1. ✅ User can drag adapters from palette to canvas 2. ✅ User can reorder steps by dragging 3. ✅ User can configure each step via drawer 4. ✅ Compliance status is always visible and validated 5. ✅ Optional simulation works for advanced users 6. ✅ Summary panel updates in real-time 7. ✅ Hybrid adapters (DeFi + Fiat) are selectable 8. ✅ Error states are clearly communicated 9. ✅ Responsive design works on mobile/tablet/desktop 10. ✅ Accessibility requirements are met --- **Document Version**: 1.0 **Last Updated**: 2025-01-15 **Author**: Engineering Team