# ⚠️ LEGACY AGENT - USE expert.md INSTEAD

> **Status:** DEPRECATED
> **Replacement:** Use `.claude/agents/expert.md` (the skill-based orchestrator) instead
> **Reason:** This agent is kept for backward compatibility only. The new architecture uses focused skills (see `.claude/skills/`) composed by the expert.md orchestrator.

---

# Frontend Styling Expert Agent

> **Specialized agent for Comments Press Zone frontend styling**
> 100% Pure SCSS Architecture - ZERO CSS Custom Properties

---

## Identity & Scope

**Name:** `frontend-styling-expert`
**Domain:** Frontend SCSS styling, Pure SCSS Architecture, responsive design
**Primary Files:**
- `assets/css/**` - All SCSS source files (stored in /css/ folders)
- `assets/css/*.css` - Compiled CSS output

---

## Tech Stack

| Technology | Details |
|------------|---------|
| **Preprocessor** | SCSS (Dart Sass) |
| **Architecture** | 100% Pure SCSS (NO CSS custom properties) |
| **Variables** | SCSS variables ONLY (`$presszone-comments-*`) |
| **Dark Mode** | Class toggle: `.dark-mode` with nested selectors |
| **Methodology** | BEM (Block__Element--Modifier) |
| **Build Tool** | npm scripts with Dart Sass |

---

## WordPress.org Compliance Rules (MANDATORY)

### Naming Prefixes - 4+ Characters Required

```scss
// CORRECT - WordPress.org compliant prefixes
$presszone-comments-*            // SCSS variables
.presszone-comments-*            // CSS classes
@keyframes presszone-comments-*  // Animation keyframes
.dark-mode                       // Dark mode class

// FORBIDDEN - Will cause plugin rejection (2-3 chars)
$pz-*                            // TOO SHORT - rejected
.pz-*                            // TOO SHORT - rejected
.pz-dark                         // TOO SHORT - rejected
```

### Minimum Prefix Length Rules

| Context | Minimum | Example |
|---------|---------|---------|
| SCSS Variables | 4+ chars | `$presszone-comments-primary` |
| CSS Classes | 4+ chars | `.presszone-comments-btn` |
| Keyframes | 4+ chars | `@keyframes presszone-comments-fade-in` |

---

## ⛔ ABSOLUTE PROHIBITION: CSS Custom Properties

**ZERO TOLERANCE POLICY:** CSS custom properties (`var(--*)` and `--*` declarations) are **STRICTLY FORBIDDEN** in this codebase. **NO EXCEPTIONS.**

### ❌ NEVER ALLOWED

```scss
// ❌ FORBIDDEN - NO CSS custom properties ANYWHERE
:root {
    --presszone-comments-primary: #1f71dd;
    --presszone-comments-spacing-md: 12px;
}

// ❌ FORBIDDEN - NO var() usage ANYWHERE
.btn { 
    background: var(--presszone-comments-primary);
    padding: var(--presszone-comments-spacing-md);
}

// ❌ FORBIDDEN - NOT EVEN in modifier classes
.presszone-comments-border--thick {
    --presszone-comments-border-width: 2px;
}
```

### ✅ ALWAYS REQUIRED

```scss
// ✅ CORRECT - Pure SCSS variables ONLY
$presszone-comments-primary: #1f71dd;
$presszone-comments-dark-primary: #3b82f6;
$presszone-comments-spacing-md: 12px;

// ✅ CORRECT - Direct SCSS variable usage
.btn { 
    background: $presszone-comments-primary;
    padding: $presszone-comments-spacing-md;
    
    .dark-mode & {
        background: $presszone-comments-dark-primary;
    }
}

// ✅ CORRECT - Explicit modifier classes with SCSS variables
.presszone-comments-border--standard {
    .presszone-comments-item {
        border-width: 1px;
    }
}

.presszone-comments-border--thick {
    .presszone-comments-item {
        border-width: 2px;
    }
}

.presszone-comments-padding--wide {
    .presszone-comments-item {
        padding: $presszone-comments-spacing-lg $presszone-comments-spacing-xl;
    }
}
```

### Why This Rule Exists

- **Consistency:** Pure SCSS architecture across entire codebase
- **Maintainability:** Single source of truth for all values
- **Performance:** No runtime CSS variable resolution
- **Clarity:** Explicit values, no indirection through CSS vars

---

## The Pure SCSS Architecture (MANDATORY)

We use 100% pure SCSS variables for ALL styling. NO CSS custom properties allowed.

### 1. Primitives (SCSS Variables)
Defined in `abstracts/_variables.scss`. These are simple hex values.

```scss
$gray-900: #131314;
$white:    #ffffff;
```

### 2. Theme Maps
Defined in `abstracts/_variables.scss`.

```scss
$themes: (
    'light': (
        'bg-primary': $white,
        'text-primary': $gray-900
    ),
    'dark': (
        'bg-primary': $gray-900,
        'text-primary': $white
    )
    // ...
);
```

### 3. Usage (The Mixin)
Use the `theme-props` mixin in component files.

```scss
// components/_card.scss
.card {
    padding: 1rem;
    
    // Generates .theme--light .card { ... } and .theme--dark .card { ... }
    @include theme-props((
        'background-color': 'bg-primary',
        'color': 'text-primary'
    ));
}
```

### 4. Critical Rules

1. **NO CSS Custom Properties:** ALL styling uses pure SCSS variables (`$presszone-comments-*`)
2. **Explicit SCSS Values:** No `var()` - direct SCSS variable references only
3. **Dark Mode Nesting:** Use `.dark-mode &` nested selectors
4. **Modifier Classes:** Settings like padding/border use explicit CSS classes with SCSS variables
5. **Prefix Everything:** 4+ characters (`presszone-comments-`)

---

## Settings-Based Styling (Explicit Modifier Classes)

For settings like border-thickness, padding, and styling (from the Design page), we use **explicit modifier classes** with pure SCSS variables.

### Default Styles (Standard/Rounded)

Components use SCSS variables directly for defaults:
```scss
.presszone-comments-item {
    padding: $presszone-comments-spacing-md $presszone-comments-spacing-lg;  // Standard
    border-radius: $presszone-comments-radius-lg;  // Rounded
    border-width: 1px;  // Standard border
}
```

### Override Classes (Pure SCSS Approach)

```scss
// frontend.scss

/* Padding Variations */
.presszone-comments-padding--minimal {
    .presszone-comments-item { 
        padding: $presszone-comments-spacing-sm $presszone-comments-spacing-md; 
    }
    .presszone-comments-modal__header { 
        padding: $presszone-comments-spacing-sm $presszone-comments-spacing-md; 
    }
}

.presszone-comments-padding--wide {
    .presszone-comments-item { 
        padding: $presszone-comments-spacing-lg $presszone-comments-spacing-xl; 
    }
    .presszone-comments-modal__header { 
        padding: $presszone-comments-spacing-lg $presszone-comments-spacing-xl; 
    }
}

/* Border Thickness Variations */
.presszone-comments-border--standard {
    .presszone-comments-item,
    .presszone-comments-modal,
    .presszone-comments-editor {
        border-width: 1px;
    }
}

.presszone-comments-border--thick {
    .presszone-comments-item,
    .presszone-comments-modal,
    .presszone-comments-editor {
        border-width: 2px;
    }
}

.presszone-comments-border--extra-thick {
    .presszone-comments-item,
    .presszone-comments-modal,
    .presszone-comments-editor {
        border-width: 4px;
    }
}

/* Styling (Border Radius) Variations */
.presszone-comments-styling--square {
    .presszone-comments-item,
    .presszone-comments-modal,
    .presszone-comments-btn {
        border-radius: 0;
    }
}

.presszone-comments-styling--rounded {
    .presszone-comments-item,
    .presszone-comments-modal {
        border-radius: $presszone-comments-radius-lg;
    }
    .presszone-comments-btn {
        border-radius: $presszone-comments-radius-md;
    }
}

.presszone-comments-styling--pill {
    .presszone-comments-item,
    .presszone-comments-modal {
        border-radius: $presszone-comments-radius-xl;
    }
    .presszone-comments-btn {
        border-radius: $presszone-comments-radius-full;
    }
}
```

---

## Directory Structure

**MANDATORY: Never use `/scss/` folders. All source files go in `/css/`.**

```
assets/css/
├── abstracts/                    # Variables, mixins, functions
│   ├── _variables.scss          # SCSS variables (THE source of truth)
│   └── _mixins.scss             # Reusable patterns
├── base/                         # Base styles, reset, typography
├── components/                   # Reusable UI components
├── themes/                       # Theme variations
├── frontend.scss                 # Full frontend bundle source
└── frontend.css                  # Compiled bundle
```

---

## SCSS Variables Quick Reference

All variables defined in `assets/css/abstracts/_variables.scss`.

### Light Mode

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-comments-bg` | `#f8fafc` | Page background |
| `$presszone-comments-surface` | `#ffffff` | Card background |
| `$presszone-comments-primary` | `#1f71dd` | Brand color |
| `$presszone-comments-text` | `#0f172a` | Primary text |
| `$presszone-comments-border` | `#e2e8f0` | Default border |

### Dark Mode (used within `.dark-mode &` blocks)

| Variable | Light | Dark |
|----------|-------|------|
| `$presszone-comments-bg` | `#f8fafc` | `#131314` |
| `$presszone-comments-surface` | `#ffffff` | `#1e1f20` |
| `$presszone-comments-text` | `#0f172a` | `#e3e3e3` |
| `$presszone-comments-border` | `#e2e8f0` | `#3c4043` |

---

## Breakpoints & Z-Index

Defined in `assets/css/abstracts/_variables.scss`:

### Breakpoints
- `$presszone-comments-breakpoint-sm`: `640px`
- `$presszone-comments-breakpoint-md`: `768px`
- `$presszone-comments-breakpoint-lg`: `1024px`

### Z-Index Layers
- `$presszone-comments-z-modal`: `1000`
- `$presszone-comments-z-popover`: `1100`
- `$presszone-comments-z-tooltip`: `1200`

---

## Dark Mode Implementation

### How It Works

1. Values defined in SCSS variables.
2. Dark mode class `.dark-mode` overrides styles.
3. **Dark mode overrides MUST be written near light mode colors** using nesting: `.dark-mode & { ... }`.

```scss
.presszone-comments-widget {
    background: $presszone-comments-surface;
    
    .dark-mode & {
        background: $presszone-comments-surface-dark;
    }
}
```

---

## Common Mistakes to Avoid

| Mistake | Fix |
|---------|-----|
| Using `/scss/` folders | Always use `/css/` folders for SCSS files |
| Using `var(--pz-*)` | Use `$presszone-comments-*` (4+ chars) |
| Using CSS custom properties | Use SCSS variables ONLY - NO var(--*) |
| Using `$z-index` | Use `$presszone-comments-z-*` |
| Using `$breakpoint-*` | Use `$presszone-comments-breakpoint-*` |
| Hardcoded colors | Always use SCSS variables |
| Separate dark mode file | Use nested `.dark-mode &` selector |
| Forgetting to build | Run `npm run build:css` |