302 lines
9.3 KiB
Markdown
302 lines
9.3 KiB
Markdown
# Modular Design System: Alwrity Onboarding
|
|
|
|
## 🎯 **Overview**
|
|
|
|
This document outlines the modular design system for Alwrity's onboarding flow, ensuring **consistency**, **reusability**, and **maintainability** across all onboarding steps while preserving all current functionality and styling.
|
|
|
|
---
|
|
|
|
## **🏗️ Architecture**
|
|
|
|
### **Core Components**
|
|
```
|
|
frontend/src/components/OnboardingWizard/
|
|
├── common/
|
|
│ ├── useOnboardingStyles.ts # Centralized styling hook
|
|
│ ├── onboardingUtils.ts # Shared utility functions
|
|
│ ├── OnboardingStepLayout.tsx # Reusable layout component
|
|
│ ├── OnboardingCard.tsx # Reusable card component
|
|
│ └── OnboardingButton.tsx # Reusable button component
|
|
├── ApiKeyStep.tsx # Refactored to use design system
|
|
├── WebsiteStep.tsx # Will be refactored
|
|
├── ResearchStep.tsx # Will be refactored
|
|
├── PersonalizationStep.tsx # Will be refactored
|
|
├── IntegrationsStep.tsx # Will be refactored
|
|
└── FinalStep.tsx # Will be refactored
|
|
```
|
|
|
|
---
|
|
|
|
## **🎨 Design System Components**
|
|
|
|
### **1. useOnboardingStyles Hook**
|
|
**Purpose**: Centralized styling for all onboarding components
|
|
**Benefits**:
|
|
- ✅ Consistent styling across all steps
|
|
- ✅ Easy to maintain and update
|
|
- ✅ Theme-aware styling
|
|
- ✅ Reusable style objects
|
|
|
|
```typescript
|
|
// Usage in any step component
|
|
const styles = useOnboardingStyles();
|
|
|
|
// Apply consistent styling
|
|
<Box sx={styles.container}>
|
|
<Typography sx={styles.headerTitle}>Title</Typography>
|
|
<Button sx={styles.primaryButton}>Action</Button>
|
|
</Box>
|
|
```
|
|
|
|
### **2. onboardingUtils Functions**
|
|
**Purpose**: Shared utility functions for common operations
|
|
**Benefits**:
|
|
- ✅ DRY (Don't Repeat Yourself) principle
|
|
- ✅ Consistent validation logic
|
|
- ✅ Reusable animation utilities
|
|
- ✅ Standardized error handling
|
|
|
|
```typescript
|
|
// Validation utilities
|
|
const isValid = validateApiKey(key, 'openai');
|
|
const status = getKeyStatus(key, 'openai');
|
|
|
|
// Animation utilities
|
|
const delay = getAnimationDelay(index);
|
|
const direction = getSlideDirection(current, target);
|
|
|
|
// Form utilities
|
|
const isValid = isFormValid(formValues);
|
|
const progress = calculateProgress(current, total);
|
|
```
|
|
|
|
### **3. OnboardingStepLayout Component**
|
|
**Purpose**: Consistent layout structure for all steps
|
|
**Benefits**:
|
|
- ✅ Standardized header structure
|
|
- ✅ Consistent spacing and typography
|
|
- ✅ Reusable animations
|
|
- ✅ Flexible content area
|
|
|
|
```typescript
|
|
<OnboardingStepLayout
|
|
icon={<Key />}
|
|
title="Connect Your AI Services"
|
|
subtitle="Add your API keys to enable AI-powered content creation"
|
|
>
|
|
{/* Step-specific content */}
|
|
</OnboardingStepLayout>
|
|
```
|
|
|
|
### **4. OnboardingCard Component**
|
|
**Purpose**: Consistent card styling with status indicators
|
|
**Benefits**:
|
|
- ✅ Standardized card appearance
|
|
- ✅ Built-in status validation
|
|
- ✅ Consistent hover effects
|
|
- ✅ Reusable across all steps
|
|
|
|
```typescript
|
|
<OnboardingCard
|
|
title="OpenAI API Key"
|
|
icon={<Security />}
|
|
status={getKeyStatus(key, 'openai')}
|
|
saved={!!savedKeys.openai}
|
|
>
|
|
<TextField value={key} onChange={handleChange} />
|
|
</OnboardingCard>
|
|
```
|
|
|
|
---
|
|
|
|
## **🔧 Implementation Guidelines**
|
|
|
|
### **1. Step Component Structure**
|
|
Every onboarding step should follow this structure:
|
|
|
|
```typescript
|
|
import { useOnboardingStyles } from './common/useOnboardingStyles';
|
|
import { relevantUtils } from './common/onboardingUtils';
|
|
|
|
const StepComponent: React.FC<StepProps> = ({ onContinue }) => {
|
|
const styles = useOnboardingStyles();
|
|
|
|
// State management
|
|
const [formData, setFormData] = useState({});
|
|
const [loading, setLoading] = useState(false);
|
|
const [error, setError] = useState<string | null>(null);
|
|
|
|
// Validation
|
|
const isValid = isFormValid(formData);
|
|
|
|
// Event handlers
|
|
const handleSave = async () => {
|
|
// Implementation
|
|
};
|
|
|
|
return (
|
|
<Fade in={true} timeout={500}>
|
|
<Box sx={styles.container}>
|
|
{/* Header */}
|
|
<Box sx={styles.header}>
|
|
<Zoom in={true} timeout={600}>
|
|
{/* Header content */}
|
|
</Zoom>
|
|
</Box>
|
|
|
|
{/* Form content */}
|
|
<Box sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
|
|
{/* Cards and form elements */}
|
|
</Box>
|
|
|
|
{/* Alerts */}
|
|
{/* Action buttons */}
|
|
{/* Skip section */}
|
|
</Box>
|
|
</Fade>
|
|
);
|
|
};
|
|
```
|
|
|
|
### **2. Styling Guidelines**
|
|
- **Use the styles hook**: Always use `useOnboardingStyles()` for styling
|
|
- **Consistent spacing**: Use the predefined spacing values
|
|
- **Theme integration**: Leverage Material-UI theme for colors
|
|
- **Responsive design**: Use the responsive breakpoints
|
|
|
|
### **3. Animation Guidelines**
|
|
- **Fade in**: Use `Fade` component for step transitions
|
|
- **Zoom effects**: Use `Zoom` for important elements
|
|
- **Slide transitions**: Use `Slide` for step navigation
|
|
- **Consistent timing**: Use predefined timeouts (300ms, 500ms, 700ms)
|
|
|
|
### **4. Validation Guidelines**
|
|
- **Real-time validation**: Use debounced validation for better UX
|
|
- **Visual feedback**: Show status chips and border colors
|
|
- **Error handling**: Use `formatErrorMessage` for consistent error messages
|
|
- **Form validation**: Use `isFormValid` for form completeness
|
|
|
|
---
|
|
|
|
## **📋 Component Checklist**
|
|
|
|
### **For Each Step Component**
|
|
- [ ] **Import design system**: Use `useOnboardingStyles` and relevant utilities
|
|
- [ ] **Consistent structure**: Follow the standard component structure
|
|
- [ ] **Proper animations**: Use `Fade`, `Zoom`, and `Slide` components
|
|
- [ ] **Form validation**: Implement real-time validation with visual feedback
|
|
- [ ] **Error handling**: Use `formatErrorMessage` for error display
|
|
- [ ] **Loading states**: Show loading indicators during async operations
|
|
- [ ] **Auto-save**: Implement auto-save functionality where appropriate
|
|
- [ ] **Skip options**: Provide skip functionality for optional steps
|
|
- [ ] **Help sections**: Include collapsible help content
|
|
- [ ] **Responsive design**: Ensure mobile-friendly layout
|
|
|
|
### **For New Components**
|
|
- [ ] **Reusable design**: Make components generic and reusable
|
|
- [ ] **Props interface**: Define clear TypeScript interfaces
|
|
- [ ] **Default values**: Provide sensible defaults
|
|
- [ ] **Documentation**: Add JSDoc comments
|
|
- [ ] **Testing**: Include unit tests for utilities
|
|
|
|
---
|
|
|
|
## **🎯 Benefits of This System**
|
|
|
|
### **1. Consistency**
|
|
- ✅ **Visual consistency**: All steps look and feel the same
|
|
- ✅ **Behavior consistency**: Same interactions across all steps
|
|
- ✅ **Animation consistency**: Standardized transitions and effects
|
|
- ✅ **Error handling**: Consistent error messages and recovery
|
|
|
|
### **2. Reusability**
|
|
- ✅ **Shared components**: Common components used across steps
|
|
- ✅ **Shared utilities**: Validation, animation, and form utilities
|
|
- ✅ **Shared styles**: Centralized styling system
|
|
- ✅ **Shared logic**: Common business logic extracted to utilities
|
|
|
|
### **3. Maintainability**
|
|
- ✅ **Single source of truth**: Styles and utilities in one place
|
|
- ✅ **Easy updates**: Change once, affects all components
|
|
- ✅ **Clear structure**: Consistent file and component organization
|
|
- ✅ **Type safety**: Full TypeScript support with proper interfaces
|
|
|
|
### **4. Performance**
|
|
- ✅ **Optimized animations**: Efficient animation utilities
|
|
- ✅ **Debounced operations**: Prevent excessive API calls
|
|
- ✅ **Lazy loading**: Components load only when needed
|
|
- ✅ **Memory management**: Proper cleanup in useEffect hooks
|
|
|
|
---
|
|
|
|
## **🚀 Migration Strategy**
|
|
|
|
### **Phase 1: Foundation (Complete)**
|
|
- ✅ Create design system components
|
|
- ✅ Implement utility functions
|
|
- ✅ Create styling hook
|
|
- ✅ Refactor ApiKeyStep as example
|
|
|
|
### **Phase 2: Component Migration**
|
|
- [ ] Refactor WebsiteStep
|
|
- [ ] Refactor ResearchStep
|
|
- [ ] Refactor PersonalizationStep
|
|
- [ ] Refactor IntegrationsStep
|
|
- [ ] Refactor FinalStep
|
|
|
|
### **Phase 3: Enhancement**
|
|
- [ ] Add more utility functions as needed
|
|
- [ ] Create additional reusable components
|
|
- [ ] Implement advanced animations
|
|
- [ ] Add accessibility features
|
|
|
|
### **Phase 4: Testing & Optimization**
|
|
- [ ] Add unit tests for utilities
|
|
- [ ] Add integration tests for components
|
|
- [ ] Performance optimization
|
|
- [ ] Accessibility audit
|
|
|
|
---
|
|
|
|
## **📚 Usage Examples**
|
|
|
|
### **Creating a New Step**
|
|
```typescript
|
|
// 1. Import design system
|
|
import { useOnboardingStyles } from './common/useOnboardingStyles';
|
|
import { validateRequired, formatErrorMessage } from './common/onboardingUtils';
|
|
|
|
// 2. Use the styles hook
|
|
const styles = useOnboardingStyles();
|
|
|
|
// 3. Implement consistent structure
|
|
const NewStep: React.FC<StepProps> = ({ onContinue }) => {
|
|
// State and logic
|
|
return (
|
|
<Fade in={true} timeout={500}>
|
|
<Box sx={styles.container}>
|
|
{/* Header */}
|
|
{/* Content */}
|
|
{/* Actions */}
|
|
</Box>
|
|
</Fade>
|
|
);
|
|
};
|
|
```
|
|
|
|
### **Adding New Utilities**
|
|
```typescript
|
|
// Add to onboardingUtils.ts
|
|
export const validateEmail = (email: string): boolean => {
|
|
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
|
|
return emailRegex.test(email);
|
|
};
|
|
|
|
export const formatPhoneNumber = (phone: string): string => {
|
|
// Implementation
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
**This modular design system ensures that all onboarding steps are consistent, maintainable, and provide an excellent user experience while reducing development time and improving code quality.** |