# GGM Commerce Plugin - Design Principles

## The Fundamental Rule

**professional-defaults.css styling + widget controls = user customizable**

If styling exists in professional-defaults.css, corresponding widget controls MUST exist so users can override those defaults.

## CSS Architecture

### widgets.css (Always Loaded)
Contains ONLY structural/functional CSS needed for widgets to work properly.

**DO include:**
- Structural CSS (display, flex, grid, position, width, height)
- Functional CSS (transitions, transforms, cursor states, animations)
- Layout properties (align-items, justify-content, gap)
- Responsive breakpoints for layout changes
- Essential accessibility (text-decoration for links, cursor for buttons)

**DO NOT include:**
- Colors (backgrounds, text, borders)
- Typography (font-family, font-size, font-weight, line-height)
- Spacing values (margin, padding - controlled by Elementor controls)
- Decorative styles (shadows, borders, border-radius)

### professional-defaults.css (Conditionally Loaded)
Contains all design styling when "Professional Defaults" are enabled in Settings > Widget Styles.

**Requirements:**
- Colors: ONLY via CSS variables (var(--ggmc-*))
- Typography: ONLY via CSS variables
- Shadows/Border-radius: ONLY via CSS variables
- Spacing (padding/margin): Acceptable IF widget controls exist to override
- Every styled property MUST have a corresponding widget control

## How Professional Defaults Work

1. **When Professional Defaults are ENABLED:**
   - professional-defaults.css provides beautiful default styling
   - Widget controls can override any CSS property
   - User gets professional look but full customization control

2. **When Professional Defaults are DISABLED:**
   - Only widgets.css loads (structural only)
   - Widget controls use Site Settings or user-defined values
   - User has complete control from scratch

## Workflow Before Making CSS Changes

### Step 1: Read the Renderer PHP File
```bash
# Find the renderer for the widget you're styling
Read wp-content/plugins/ggm-commerce/widgets/renderers/class-{widget}-renderer.php
```

**Why:** Verify actual HTML class structure before writing CSS selectors

### Step 2: Verify CSS Selectors
```css
/* WRONG: Assuming class names */
.ggmc-filter-container { }

/* CORRECT: Verified from renderer */
.ggmc-product-filter { }
```

### Step 3: Check Widget Controls
```php
// Read the widget file
Read wp-content/plugins/ggm-commerce/widgets/class-{widget}.php
```

**Verify:** Does the widget have Elementor controls for the properties you want to style?

### Step 4: Add Missing Controls (If Needed)
If CSS styling exists but no widget control:
1. Add the Elementor control to the widget PHP file
2. Ensure control can override the CSS (inline styles or higher specificity)

### Step 5: Add/Modify CSS
Only after confirming controls exist:
1. Add styling to professional-defaults.css
2. Use CSS variables for all design values
3. Target with `.elementor-widget-{widget-name}` prefix for specificity

## Common Mistakes to Avoid

### ❌ Wrong: Assuming Class Names
```css
/* Don't write CSS based on assumptions */
.ggmc-filter-container .filter-group { }
```

### ✅ Correct: Verify First
```bash
# Read the renderer to see actual HTML
Read class-product-filter-renderer.php
# Then write accurate selectors
```

### ❌ Wrong: Hardcoded Values
```css
.product-card {
    background: #ffffff;  /* Never hardcode colors */
    padding: 20px;        /* No control exists to override this */
}
```

### ✅ Correct: Variables + Controls
```css
.product-card {
    background: var(--ggmc-surface);
    padding: var(--ggmc-spacing-md);
    /* AND ensure widget has a Padding control */
}
```

### ❌ Wrong: Removing All Spacing
"I found 71 instances of padding/margin to remove"

**This is a ridiculous conclusion.** Spacing is fine if widget controls exist.

### ✅ Correct: Verify Control Exists
1. Check if widget has padding/margin controls
2. If YES: CSS padding/margin is fine
3. If NO: Add the controls first, then CSS is fine

## CSS Variable System

All design values use CSS custom properties defined in professional-defaults.css:

```css
/* Color Variables */
--ggmc-primary: #007bff;
--ggmc-surface: #ffffff;
--ggmc-text-primary: #333333;

/* Typography Variables */
--ggmc-font-family: 'Inter', sans-serif;
--ggmc-font-size-base: 16px;

/* Spacing Variables */
--ggmc-spacing-sm: 8px;
--ggmc-spacing-md: 16px;
--ggmc-spacing-lg: 24px;

/* Shadow Variables */
--ggmc-shadow: 0 2px 8px rgba(0,0,0,0.1);
```

## Widget Control Override Hierarchy

1. **User's inline widget control** (highest priority)
2. professional-defaults.css styling
3. Site Settings
4. Browser defaults (lowest priority)

This ensures users always have the final say in styling, regardless of Professional Defaults setting.
