WizdomWeb/StylingStructure.md

Recommended Approach for Managing Styling Structure & Expansions

To streamline and efficiently manage CSS styling across the Wizdom Networks website without administrative overhead, we need a structured, scalable, and maintainable approach. Below is the recommended framework and workflow.

---

1️⃣ Styling Structure Overview

We will use a layered CSS structure, ensuring separation between global styles, components, and page-specific styles.

🔹 Core Structure

/assets/css/
├── main.css               # Global styles (typography, colors, layouts)
├── utilities.css          # Reusable utility classes (spacing, flex, visibility)
├── components/
│   ├── hero.css           # Hero section styles
│   ├── slider.css         # Slider-specific styles
│   ├── sidebar.css        # Sidebar-specific styles
│   ├── navbar.css         # Navigation styles
│   ├── footer.css         # Footer styles
│   ├── forms.css          # Forms & inputs
│   ├── buttons.css        # Buttons & CTA styles
│   ├── modal.css          # Modal windows
│   ├── tables.css         # Table styles
│   ├── cards.css          # Card-based UI styles
│   ├── animations.css     # Custom animations & transitions
│   ├── overlays.css       # Image & text overlays
│   ├── accessibility.css  # WCAG accessibility fixes & enhancements
│   ├── dark-mode.css      # Dark mode support (if applicable)
│   ├── page-specific/
│   │   ├── about.css      # About page styles
│   │   ├── services.css   # Services page styles
│   │   ├── contact.css    # Contact page styles
│   │   ├── terms.css      # Terms of service page styles
│   │   ├── privacy.css    # Privacy policy styles

✅ Benefit: Keeps global styles separate from component and page-specific styles, ensuring scalability.

---

2️⃣ Automatic & Dynamic CSS Loading

To ensure minimal manual configuration, we dynamically load required stylesheets.

🔹 Update head.php to Dynamically Load CSS

Modify head.php so that global, component, and page-specific styles load automatically.

<?php 
    // Load Global Styles
    echo '<link rel="stylesheet" href="/assets/css/main.css">';
    echo '<link rel="stylesheet" href="/assets/css/utilities.css">';

    // Load Component Styles Automatically
    $components = ['hero', 'slider', 'sidebar', 'navbar', 'footer', 'forms', 'buttons', 'modal', 'tables', 'cards', 'animations', 'overlays', 'accessibility'];
    foreach ($components as $component) {
        echo '<link rel="stylesheet" href="/assets/css/components/' . $component . '.css">';
    }

    // Load Page-Specific Styles (if applicable)
    if (isset($pageId)) {
        echo '<link rel="stylesheet" href="/assets/css/components/page-specific/' . htmlspecialchars($pageId, ENT_QUOTES, 'UTF-8') . '.css">';
    }
?>

✅ Benefit:

• No need to manually add stylesheets per page—it dynamically loads required styles.
• Automatically extends when new pages or components are added.

---

3️⃣ Defining Utility Classes (utilities.css)

To avoid redundant styles and enhance reusability, we should define core utility classes.

🔹 Example utilities.css

/* Spacing Utilities */
.m-0 { margin: 0 !important; }
.m-5 { margin: 5px !important; }
.p-0 { padding: 0 !important; }
.p-5 { padding: 5px !important; }

/* Display Utilities */
.d-none { display: none !important; }
.d-block { display: block !important; }
.d-flex { display: flex !important; }

/* Flexbox */
.flex-column { flex-direction: column !important; }
.flex-row { flex-direction: row !important; }
.justify-center { justify-content: center !important; }
.align-center { align-items: center !important; }

/* Visibility */
.hidden { visibility: hidden !important; }
.visible { visibility: visible !important; }

/* Responsive Utilities */
@media (max-width: 768px) {
    .hide-sm { display: none !important; }
    .text-center-sm { text-align: center !important; }
}
@media (min-width: 768px) {
    .hide-lg { display: none !important; }
}

✅ Benefit:

• Eliminates repetition in individual stylesheets.
• Ensures consistency across pages.

---

4️⃣ Guidelines for Expanding Styling

To ensure new features or styles are seamlessly integrated, follow these best practices:

🔹 When Adding a New Feature

1️⃣ Check if existing global styles cover it (main.css, utilities.css).
2️⃣ If it's a UI component, place it in components/.
3️⃣ If it's page-specific, place it in page-specific/.
4️⃣ Ensure head.php dynamically loads the new file.

✅ Example:

• If we add a new pricing table component, it goes into components/tables.css instead of main.css.
• If we add unique animations for one page, it goes into page-specific/custom-page.css.

---

5️⃣ Versioning & Documentation

To track changes effectively:

• All stylesheets include a version comment at the top.
• Major updates should be logged in a CHANGELOG.md file.

✅ Example: main.css Header Comment

/* Main Styles (v2) - Last Updated: 2025-02-03 */

✅ Example: CHANGELOG.md

## v2.0 (2025-02-03)
- Moved page-specific styles to `components/page-specific/`
- Improved layout spacing in `main.css`
- Optimized `head.php` to dynamically load required stylesheets

---

📌 Summary of the Approach

Action	Implementation	Benefit
Global styles	main.css, utilities.css	Standardizes typography, buttons, layout
Component styles	components/ directory	Keeps reusable UI elements modular
Page-specific styles	page-specific/ directory	Avoids cluttering global styles
Automatic CSS loading	head.php dynamically includes required files	Reduces manual work, ensures scalability
Utility classes	utilities.css	Prevents redundant styling
Change tracking	Versioned styles + CHANGELOG.md	Ensures traceability of updates

---

6️⃣ Next Steps

Would you like me to: 1️⃣ Apply this refactored structure now, or
2️⃣ Implement it incrementally over time to avoid disruptions? 🚀