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

inclusion

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

// 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:

/* 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

<!-- 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

# 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

// 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

/* 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:

   // 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:

   // Instead of Figma colors
   color: '#1976d2'  // Use theme.palette.primary.main
   
   // Dashboard colors
   background: '#1e293b'  // Use established card background
   

3. Maintain Component Consistency:

   // Reuse existing components
   import { Button } from '@mui/material';
   // Instead of creating new button styles
   

4. Respect Layout Patterns:

   // 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

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

Python Backend

# 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.