rpa_vision_v3/.kiro/steering/design-system.md

---
inclusion: always
---

# RPA Vision V3 Design System Rules

This document provides comprehensive design system guidelines for integrating Figma designs with the RPA Vision V3 codebase using the Figma MCP integration.

## Project Architecture Overview

RPA Vision V3 is a multi-component system with distinct UI frameworks:

- **Visual Workflow Builder**: React + TypeScript + Material-UI frontend
- **Web Dashboard**: Flask + HTML/CSS/JavaScript with custom styling
- **Desktop GUI**: PyQt5 Python application
- **Agent V0**: Cross-platform capture tool with PyQt5 UI
- **Server API**: Flask-based REST API with minimal UI

## Design Token Definitions

### Color System

**Primary Colors:**
- Primary Blue: `#1976d2` (Material-UI primary)
- Secondary Pink: `#dc004e` (Material-UI secondary)
- Success Green: `#22c55e`
- Warning Orange: `#f59e0b`
- Error Red: `#ef4444`

**Background Colors:**
- Dark Background: `#0f172a` (Dashboard primary)
- Card Background: `#1e293b` (Dashboard cards)
- Border Color: `#334155`
- Text Primary: `#e2e8f0`
- Text Secondary: `#94a3b8`
- Text Muted: `#64748b`

**PyQt5 Colors:**
- Background: `#1e1e1e` (Dark theme)
- Text: `#d4d4d4`
- Success: `#4CAF50`
- Accent: `#2196f3`

### Typography Scale

**Web (Material-UI + Custom):**
- Headers: `'Segoe UI', Tahoma, Geneva, Verdana, sans-serif`
- Body: Material-UI default typography
- Monospace: `monospace` (for logs and code)

**PyQt5:**
- Default system fonts with size variations
- Monospace for technical displays

### Spacing System

**Web Spacing (px):**
- xs: 4px
- sm: 8px
- md: 12px
- lg: 16px
- xl: 20px
- xxl: 24px
- xxxl: 30px

**Component Spacing:**
- Card padding: 20px
- Button padding: 10px 20px
- Input padding: 12px
- Grid gaps: 15px-20px

## Component Library Structure

### React Components Location
```
visual_workflow_builder/frontend/src/components/
├── Canvas/                 # Main workflow canvas
├── Palette/               # Tool palette
├── PropertiesPanel/       # Node properties editor
├── TemplateSelector/      # Workflow templates
├── AnalyticsDashboard/    # Analytics display
├── DocumentationTab/      # Interactive documentation
├── ExecutionPanel/        # Workflow execution controls
├── KeyboardShortcuts/     # Keyboard shortcuts help
└── [Other components]/
```

### Component Architecture
- **Material-UI based**: Primary component library
- **Custom CSS modules**: Component-specific styling in `.css` files
- **Hooks pattern**: Custom hooks for state management (`useWorkflow`, `useSelection`, etc.)
- **TypeScript interfaces**: Defined in `src/types/`

### PyQt5 Components Location
```
gui/
├── main_window.py         # Main application window
├── components/            # Reusable UI components
└── orchestrator.py        # Business logic integration
```

## Styling Approach

### React/TypeScript (Visual Workflow Builder)

**Primary Method**: Material-UI with custom CSS modules
```typescript
// Component structure
import { Box, Button, Typography } from '@mui/material';
import './ComponentName.css';

// Theme usage
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    secondary: { main: '#dc004e' }
  }
});
```

**CSS Modules Pattern**:
```css
/* Component.css */
.component-container {
  background: #1e293b;
  border-radius: 12px;
  padding: 20px;
  border: 1px solid #334155;
}

.component-title {
  color: #e2e8f0;
  margin-bottom: 15px;
}
```

### Flask Dashboard (Web Dashboard)

**Method**: Inline CSS with utility classes
```html
<!-- Embedded styles in templates -->
<style>
  .card { 
    background: #1e293b; 
    border-radius: 12px; 
    padding: 20px; 
    border: 1px solid #334155; 
  }
  .btn-primary { 
    background: #3b82f6; 
    color: white; 
    padding: 10px 20px; 
    border-radius: 8px; 
  }
</style>
```

### PyQt5 (Desktop GUI)

**Method**: Inline StyleSheet strings
```python
# PyQt5 styling
widget.setStyleSheet("""
    QWidget {
        background: #1e1e1e;
        color: #d4d4d4;
        font-family: monospace;
    }
    QPushButton {
        background: #4CAF50;
        color: white;
        padding: 10px;
        font-size: 14px;
        border-radius: 4px;
    }
""")
```

## Asset Management

### Icons
- **Material-UI Icons**: `@mui/icons-material` for React components
- **Emoji Icons**: Used extensively in dashboard (🚀, 📊, ⚡, etc.)
- **Unicode Symbols**: For PyQt5 components (▶, ⏸, ⏹)

### Images and Screenshots
```
data/
├── screenshots/           # Runtime captured screenshots
├── training/             # Training data assets
└── [other data]/
```

### Asset Optimization
- **No CDN**: Local asset serving
- **Webpack bundling**: For React frontend
- **Flask static serving**: For dashboard assets

## Responsive Design Implementation

### React Components
```typescript
// Material-UI responsive breakpoints
const useStyles = makeStyles((theme) => ({
  container: {
    [theme.breakpoints.down('md')]: {
      padding: theme.spacing(1),
    },
    [theme.breakpoints.up('lg')]: {
      padding: theme.spacing(3),
    },
  },
}));
```

### Dashboard CSS
```css
/* Responsive grid */
.grid { 
  display: grid; 
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); 
  gap: 20px; 
}

@media (max-width: 768px) {
  .grid { grid-template-columns: 1fr; }
  .react-flow__minimap { display: none; }
}
```

## Figma Integration Guidelines

### Design-to-Code Mapping

**When using Figma MCP tools:**

1. **Replace Tailwind with Material-UI**:
   ```typescript
   // Figma output (Tailwind)
   <div className="bg-blue-500 text-white p-4 rounded-lg">
   
   // Convert to Material-UI
   <Box sx={{ 
     bgcolor: 'primary.main', 
     color: 'white', 
     p: 2, 
     borderRadius: 2 
   }}>
   ```

2. **Use Project Color Tokens**:
   ```typescript
   // Instead of Figma colors
   color: '#1976d2'  // Use theme.palette.primary.main
   
   // Dashboard colors
   background: '#1e293b'  // Use established card background
   ```

3. **Maintain Component Consistency**:
   ```typescript
   // Reuse existing components
   import { Button } from '@mui/material';
   // Instead of creating new button styles
   ```

4. **Respect Layout Patterns**:
   ```typescript
   // Follow established grid patterns
   <div className="grid grid-2">  // Dashboard pattern
   <Grid container spacing={2}>   // Material-UI pattern
   ```

### Code Connect Mapping

**Component Mapping Strategy**:
- Map Figma components to existing Material-UI components
- Create custom components only when necessary
- Maintain consistency with existing component APIs

**File Structure for Code Connect**:
```
visual_workflow_builder/frontend/src/components/
├── Button/index.tsx           # Map to Material-UI Button
├── Card/index.tsx            # Map to Material-UI Card
├── Input/index.tsx           # Map to Material-UI TextField
└── [Custom components]/      # Project-specific components
```

## Build System Integration

### React Frontend
```json
// package.json build commands
{
  "scripts": {
    "start": "webpack serve --mode development",
    "build": "webpack --mode production",
    "type-check": "tsc --noEmit"
  }
}
```

### Python Backend
```python
# Flask app structure
app/
├── static/              # Static assets
├── templates/           # Jinja2 templates
└── api/                # API endpoints
```

### Development Workflow
1. **Design in Figma**: Create/update designs
2. **Extract with MCP**: Use Figma tools to generate code
3. **Adapt to Project**: Convert to project patterns
4. **Integrate Components**: Add to existing component library
5. **Test Integration**: Ensure consistency with existing UI

## Framework-Specific Patterns

### React + Material-UI
- Use theme provider for consistent styling
- Leverage Material-UI's responsive system
- Custom CSS modules for component-specific styles
- TypeScript interfaces for props and state

### Flask Dashboard
- Inline styles for rapid development
- Utility CSS classes for common patterns
- WebSocket integration for real-time updates
- Chart.js for data visualization

### PyQt5 Desktop
- StyleSheet strings for theming
- Signal/slot pattern for interactions
- QThread for background operations
- System tray integration

## Quality Assurance

### Visual Consistency Checklist
- [ ] Colors match established palette
- [ ] Typography follows project scale
- [ ] Spacing uses project tokens
- [ ] Components reuse existing patterns
- [ ] Responsive behavior works across breakpoints
- [ ] Dark theme compatibility maintained

### Code Quality Standards
- [ ] TypeScript types defined
- [ ] Component props documented
- [ ] Accessibility attributes included
- [ ] Performance optimizations applied
- [ ] Error boundaries implemented
- [ ] Testing coverage maintained

## Migration Strategy

When integrating new Figma designs:

1. **Analyze Design**: Identify reusable vs. custom components
2. **Map to Existing**: Use existing components where possible
3. **Extend Carefully**: Create new components only when necessary
4. **Maintain Consistency**: Follow established patterns
5. **Update Documentation**: Keep design system current
6. **Test Thoroughly**: Ensure integration doesn't break existing functionality

This design system ensures consistent, maintainable integration between Figma designs and the RPA Vision V3 codebase while respecting the multi-framework architecture and existing component patterns.