Files

ajaysi 32f97fa6b3 ALwrity Version 0.5.0 (Fastapi + React )

2025-08-06 12:48:02 +05:30

9.3 KiB

Raw Blame History

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

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

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

<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

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

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

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

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

9.3 KiB Raw Blame History