upskill-event-manager/docs/design_guidance.md

# Design Guidance for HVAC Community Events

This document provides design guidance for implementing the HVAC Community Events Management System based on the design references and WordPress theme integration requirements.

## Design Reference Analysis

The design references in the `design_references/` directory provide valuable insights into the desired user interface and experience. These references should be used as guides for implementing the various pages of the plugin.

## Core UI Elements and Patterns

### 1. Navigation and Header Elements

- **Global Header**: The site uses the standard Upskill HVAC header with main navigation
- **Sub-navigation**: Pages have contextual navigation with clear action buttons
- **Breadcrumbs**: Event Summary page includes breadcrumb navigation (Trainer Home > Event Summary)
- **Action Buttons**: Consistently styled blue buttons with icons for primary actions

### 2. Layout Patterns

- **Card-based Layout**: Information is organized in clean card sections with white backgrounds
- **Section Headers**: Clear typographic hierarchy with section titles
- **Grid Structure**: Responsive grid layout for statistics cards and information sections
- **Table Layout**: Clean tables with clear headers and alternating row colors
- **Form Layout**: Well-structured forms with logical grouping and clear labels

### 3. Visual Elements

- **Color Scheme**: Light blue page backgrounds with white cards and blue accents
- **Typography**: Consistent heading hierarchy and paragraph styling
- **Icons**: Used to enhance recognition of statistics and action buttons
- **Spacing**: Consistent padding and margin patterns throughout

## WordPress Theme Integration

### 1. Leveraging Astra Theme

The Upskill HVAC site uses a child theme of Astra (4.9.0). To ensure consistency:

- Use Astra's hook system:
  - `astra_header_before`/`astra_header_after` for header content
  - `astra_primary_content_top`/`astra_primary_content_bottom` for main content area
  - `astra_entry_content_before`/`astra_entry_content_after` for content containers
  
- Use Astra's styling classes:
  - `.ast-container` for main content containers
  - `.ast-row` for grid layouts
  - `.ast-col-*` for column structures
  - `.ast-button` and variants for button styling

### 2. Essential Blocks and Spectra Pro Integration

- **Content Blocks**: Use Essential Blocks for advanced content structures when appropriate
- **Layout Elements**: Leverage Spectra Pro's advanced layout options for complex page sections
- **Component Styling**: Apply Spectra's pre-styled components rather than custom CSS when possible

### 3. Custom Templates

When creating custom templates, follow these guidelines:

1. Start by extending default theme templates:
   ```php
   // Example template hierarchy
   get_header();
   ?>
   <div id="primary" class="ast-container">
       <main id="main" class="site-main">
           <!-- Your custom content here -->
       </main>
   </div>
   <?php
   get_footer();
   ```

2. Use Astra's content wrappers:
   ```php
   <div class="ast-container">
       <div class="ast-row">
           <div class="ast-col-lg-8">
               <!-- Main content -->
           </div>
           <div class="ast-col-lg-4">
               <!-- Sidebar content -->
           </div>
       </div>
   </div>
   ```

## Page-Specific Implementation Guidelines

### 1. Trainer Dashboard

Based on `upskillhvac.com_hce-dashboard_ (4).png`:

- **Page Structure**:
  - Top navigation bar with action buttons
  - "Your Stats" section with 5 stat cards in a responsive grid
  - "Your Events" section with tabbed filtering and table display

- **Theme Integration**:
  ```php
  // Stat cards implementation example
  echo '<div class="ast-row">';
  foreach ($stats as $stat) {
      echo '<div class="ast-col-md-6 ast-col-lg-3">';
      echo '<div class="hvac-stat-card">';
      // Card content
      echo '</div>';
      echo '</div>';
  }
  echo '</div>';
  ```

- **Responsive Behavior**:
  - Statistics cards stack on mobile (1 column)
  - Table becomes scrollable on smaller screens
  - Action buttons adapt to mobile layout

### 2. Event Summary Page

Based on `upskillhvac.com_hce-event-summary__event_id=1662 (1).png`:

- **Page Structure**:
  - Breadcrumb navigation
  - Event title with action buttons
  - Event details section with 4 info cards
  - Event description with formatted sections
  - Transactions table

- **Theme Integration**:
  ```php
  // Event details cards implementation example
  echo '<div class="ast-row">';
  echo '<div class="ast-col-md-6 ast-col-lg-3">';
  echo '<div class="hvac-event-detail-card">';
  echo '<h4>Date & Time</h4>';
  // Card content
  echo '</div>';
  echo '</div>';
  // Repeat for other cards
  echo '</div>';
  ```

- **Typography**:
  - Use theme's heading hierarchy: `<h1>` for event title, `<h2>` for main sections, `<h3>` for subsections
  - Follow theme's paragraph styling for descriptions

### 3. Login Page

Based on `upskillhvac.com_hce-login_.png`:

- **Form Styling**:
  - Center-aligned form on a card background
  - Standard form field spacing
  - Consistent button styling

- **Theme Integration**:
  - Use Astra's form styling classes
  - Maintain consistent padding and margin with theme

### 4. Modify Event Page

Based on `upskillhvac.com_hce-modify-event__event_id=1662.png`:

- **Form Structure**:
  - Clearly labeled sections
  - Logical grouping of related fields
  - Consistent form element styling

- **Theme Integration**:
  - Use theme's form element styling
  - Follow theme's spacing patterns

## Responsive Design Guidelines

1. **Breakpoints**: Use Astra theme's breakpoints:
   - Mobile: < 544px
   - Tablet: 544px - 921px
   - Desktop: > 921px

2. **Mobile Adaptations**:
   - Cards stack vertically
   - Tables become scrollable
   - Form fields expand to full width
   - Navigation adapts to mobile patterns

3. **Testing across Devices**:
   - Test on multiple screen sizes
   - Verify theme's responsive behavior is maintained
   - Ensure tap targets are appropriately sized on mobile

## Theme Compatibility Testing

1. **Visual Regression Testing**:
   - Test across different screen sizes
   - Compare against design references
   - Verify consistent spacing and alignment

2. **Plugin Compatibility**:
   - Test with all active plugins:
     - The Events Calendar suite
     - Spectra Pro
     - Essential Blocks
     - Premium Starter Templates

3. **Performance Testing**:
   - Check load times with theme integration
   - Monitor CSS specificity conflicts
   - Test JavaScript interactions

## Best Practices

1. **CSS Approach**:
   - Use theme's CSS variables when available
   - Avoid overriding theme styles with `!important`
   - Use the WordPress CSS specificity cascade appropriately
   - Keep custom CSS minimal and targeted

2. **JavaScript Integration**:
   - Follow theme's JavaScript patterns and dependencies
   - Initialize components after DOM is ready
   - Use event delegation for dynamically loaded content
   - Namespace custom JavaScript functions

3. **Template Organization**:
   - Keep templates modular and reusable
   - Use get_template_part() for component reuse
   - Follow Astra's naming conventions for consistency

By following these guidelines, the implementation will maintain consistency with the existing WordPress theme while achieving the design goals shown in the reference screenshots.