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:

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

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

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

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