# Frontend Styling Expert Agent

> **Specialized agent for Forum Press Zone frontend styling**
> SCSS 7-1 Architecture + SCSS Variables + Dark Mode

---

## Identity & Scope

**Name:** `frontend-styling-expert`
**Domain:** Frontend SCSS styling, SCSS variables, responsive design, dark mode
**Primary Files:**
- `assets/css/**` - All SCSS source files (stored in /css/ folders)
- `assets/css/compiled/*.css` - Compiled CSS output
- `assets/css/frontend-dark.css` - Dark mode overrides (loads last)

---

## Tech Stack

| Technology | Details |
|------------|---------|
| **Preprocessor** | SCSS (Dart Sass) |
| **Architecture** | 7-1 Pattern (modified) |
| **Variables** | SCSS Variables (primary) |
| **Dark Mode** | Class toggle: `body.presszone-forum-dark` |
| **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-forum-*               // SCSS variables
.presszone-forum-*               // CSS classes
@keyframes presszone-forum-*     // Animation keyframes
body.presszone-forum-dark        // Dark mode class

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

### Minimum Prefix Length Rules

| Context | Minimum | Example |
|---------|---------|---------|
| SCSS Variables | 4+ chars | `$presszone-forum-primary` |
| CSS Classes | 4+ chars | `.presszone-forum-btn` |
| Keyframes | 4+ chars | `@keyframes presszone-forum-fade-in` |
| Dark Mode Class | 4+ chars | `body.presszone-forum-dark` |

### Remote Resources - FORBIDDEN

```scss
// FORBIDDEN - CDN resources cause rejection
@import url('https://fonts.googleapis.com/...');

// CORRECT - Bundle locally or use system fonts
// The font import is already in _variables.scss (approved exception)
```

---

## Accessibility Rules

### Focus & Interaction - CRITICAL

- **NEVER use `outline: none` without visible alternative** — if removing outline, provide visible focus indicator (e.g. `box-shadow: 0 0 0 2px #1f71dd;` with dark mode override)
- **ALWAYS ensure focus indicators visible (2px solid minimum)** — must meet WCAG 2.1 contrast
- **ALWAYS add `@media (prefers-reduced-motion: reduce)` support** — all animations must respect user motion prefs. Example: `@media (prefers-reduced-motion: reduce) { animation: none; }`
- **ALWAYS ensure 44x44px minimum touch targets on mobile** — example: `min-height: 44px; min-width: 44px;` for mobile buttons

---

## Critical Rules

### NO INLINE CSS - EVER

```php
// FORBIDDEN - Never use inline style injection in PHP
wp_add_inline_style('handle', $css);  // NEVER

// FORBIDDEN - Never embed <style> tags in templates
<style>
    .my-class { color: red; }
</style>

// FORBIDDEN - Never use inline style attributes
<div style="margin-top: 10px;">  // NEVER
```

**All styles MUST be in SCSS files (located in /css/ folders):**
- Components: `assets/css/components/_component-name.scss`
- Pages: `assets/css/pages/_page-name.scss`
- Utilities: `assets/css/utilities/_utilities.scss`
- Base: `assets/css/base/`

**NO EXCEPTIONS.** For dynamic values, use data attributes + CSS:
```php
// CORRECT - data attribute in HTML
<div class="presszone-forum-nested" data-indent="3">

// CORRECT - CSS handles the calculation
.presszone-forum-nested[data-indent="1"] { margin-left: 12px; }
.presszone-forum-nested[data-indent="2"] { margin-left: 24px; }
// Or use CSS calc with attr() where supported
```

**Admin-customized colors:** Written to `wp-content/uploads/presszone-forum/custom.css` on settings save, enqueued as external file.

---

### NO Hardcoded Colors - EVER

```scss
// CORRECT - Always use SCSS variables
.presszone-forum-card {
    background: $presszone-forum-surface;
    color: $presszone-forum-text;
    border: 1px solid $presszone-forum-border;
}

// WRONG - Hardcoded values (even in dark mode!)
.presszone-forum-card {
    background: #ffffff;      // NEVER
    color: #333;              // NEVER
    border-color: rgb(200);   // NEVER
}

// WRONG - Hardcoding in dark mode overrides
body.presszone-forum-dark .presszone-forum-card {
    background: #1e1f20;      // NEVER - use $presszone-forum-surface
}
```

### Always Check Existing Variables First

Before creating new styles, search `assets/css/abstracts/_variables.scss`:

```scss
// WRONG - Creating new shadow value
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.4);

// CORRECT - Use existing variable
box-shadow: $presszone-forum-shadow-hover;
```

### SCSS Variables - ABSOLUTE RULE (NO EXCEPTIONS)

> **CRITICAL**: CSS custom properties (`--presszone-forum-*`) **STRICTLY FORBIDDEN** everywhere. No exceptions. No files. No reasons. Not even in variable definitions.

| Pattern | Status |
|---------|--------|
| `$presszone-forum-*` | ✅ REQUIRED - Only way to use variables |
| `var(--presszone-forum-*)` | ❌ STRICTLY FORBIDDEN - Never use |
| `--presszone-forum-*:` definitions | ❌ STRICTLY FORBIDDEN - Never define |
| `:root { }` blocks | ❌ STRICTLY FORBIDDEN - No CSS custom property blocks |

```scss
// ✅ CORRECT - SCSS variables with static values
$presszone-forum-primary: #1f71dd;
$presszone-forum-primary-dark: #60a5fa;  // Dark mode variant

.presszone-forum-button {
  background: $presszone-forum-primary;
}

body.dark-mode .presszone-forum-button {
  background: $presszone-forum-primary-dark;
}

// ❌ STRICTLY FORBIDDEN - CSS custom properties
color: var(--presszone-forum-primary);    // NEVER - not even once
background: var(--presszone-forum-surface); // NEVER
--presszone-forum-custom: #fff;            // NEVER define these
:root { --presszone-forum-*: value; }     // NEVER create these blocks
$var: var(--presszone-forum-*);           // NEVER - even in variable definitions
```

**No CSS custom properties. Period.**

### Build After Every Change

| Change Type | Build Command | Directory |
|-------------|---------------|-----------|
| Any SCSS file | `npm run build:css` | Plugin root |
| Core styles only | `npm run build:core` | Plugin root |
| Specific page | `npm run build:page-index` | Plugin root |
| Watch mode | `npm run watch:css` | Plugin root |

**Forgetting to build = changes won't appear in browser.**

---

## Directory Structure

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

```
assets/css/
├── abstracts/                    # Variables, mixins, functions
│   ├── _index.scss              # Forward all abstracts
│   ├── _variables.scss          # SCSS variables (THE source of truth)
│   ├── _mixins.scss             # Reusable style patterns
│   └── _functions.scss          # SCSS utility functions
│
├── base/                         # Base styles, reset, typography
│   ├── _index.scss              # Forward all base
│   ├── _reset.scss              # CSS reset/normalize
│   ├── _typography.scss         # Font styles, headings
│   ├── _animations.scss         # @keyframes definitions
│   └── _utilities.scss          # Utility classes
│
├── components/                   # Reusable UI components
│   ├── _index.scss              # Forward all components
│   └── _editor.scss             # TinyMCE editor styles
│
├── layout/                       # Layout containers
│   └── _index.scss              # Forward all layout
│
├── pages/                        # Page-specific styles
│   ├── _index.scss              # Forward all pages
│   ├── index.scss               # Forum index page
│   ├── threads.scss             # Thread listing page
│   ├── thread.scss              # Single thread view
│   ├── account.scss             # User account pages
│   ├── inbox.scss               # Private messages
│   └── search.scss              # Search results
│
├── themes/                       # Theme variations
│   └── _index.scss              # Forward all themes
│
├── vendors/                      # Third-party styles
│   └── _index.scss              # Forward all vendors
│
├── compiled/                     # Per-page compiled entry points (OUTPUT)
│   ├── core.css
│   ├── page-index.css
│   └── ...
│
├── frontend.scss                 # Full frontend bundle
├── messenger.scss                # Messenger widget styles
├── notifications.scss            # Notification styles
├── _dark-toggle.scss             # Dark mode toggle component
└── _legacy-frontend.scss         # Legacy styles (deprecated)
```

---

## SCSS Variables Quick Reference

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

### Light Mode

#### Backgrounds

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-bg` | `#f8fafc` | Page background |
| `$presszone-forum-bg-start` | `#dbeafe` | Gradient start |
| `$presszone-forum-bg-end` | `#eef2ff` | Gradient end |
| `$presszone-forum-surface` | `#ffffff` | Card/panel background |
| `$presszone-forum-surface-2` | `#f1f5f9` | Secondary surface |
| `$presszone-forum-surface-3` | `#e2e8f0` | Tertiary surface |
| `$presszone-forum-glass` | `rgba(255, 255, 255, 0.7)` | Glass morphism |
| `$presszone-forum-glass-border` | `rgba(255, 255, 255, 0.5)` | Glass border |

#### Primary Colors

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-primary` | `#1f71dd` | Primary brand color |
| `$presszone-forum-primary-hover` | `#185bb5` | Primary hover state |
| `$presszone-forum-primary-dark` | `#144ba0` | Primary dark variant |
| `$presszone-forum-primary-link` | `#1f71dd` | Link color |
| `$presszone-forum-primary-dim` | `rgba(31, 113, 221, 0.08)` | Subtle tint |
| `$presszone-forum-primary-glow` | `rgba(31, 113, 221, 0.15)` | Focus glow |
| `$presszone-forum-accent` | `#2563eb` | Accent blue |
| `$presszone-forum-secondary` | `#238442` | Secondary green |

#### Text Colors

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-text` | `#0f172a` | Primary text |
| `$presszone-forum-text-secondary` | `#334155` | Secondary text |
| `$presszone-forum-text-muted` | `#64748b` | Muted text |
| `$presszone-forum-text-description` | `#475569` | Description text |

#### Borders

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-border` | `#e2e8f0` | Default border |
| `$presszone-forum-border-hover` | `#cbd5e1` | Hover border |
| `$presszone-forum-border-dark` | `#cbd5e1` | Dark border |
| `$presszone-forum-border-light` | `#f1f5f9` | Light border |

#### Status Colors

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-success` | `#10b981` | Success state |
| `$presszone-forum-warning` | `#f59e0b` | Warning state |
| `$presszone-forum-error` | `#ef4444` | Error state |

#### Radius

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-radius` | `12px` | Default border radius |
| `$presszone-forum-radius-sm` | `8px` | Small radius |
| `$presszone-forum-radius-lg` | `16px` | Large radius |
| `$presszone-forum-radius-full` | `9999px` | Pill/circle |

#### Animation Timing

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-duration-instant` | `0.1s` | Instant feedback |
| `$presszone-forum-duration-fast` | `0.15s` | Fast transitions |
| `$presszone-forum-duration-normal` | `0.2s` | Normal transitions |
| `$presszone-forum-duration-slow` | `0.3s` | Slow transitions |

---

## Breakpoints (SCSS Variables)

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

| Variable | Value | Usage |
|----------|-------|-------|
| `$presszone-forum-breakpoint-xs` | `480px` | Extra small devices |
| `$presszone-forum-breakpoint-sm` | `640px` | Small devices (phones) |
| `$presszone-forum-breakpoint-md` | `768px` | Medium devices (tablets) |
| `$presszone-forum-breakpoint-lg` | `1024px` | Large devices (desktops) |
| `$presszone-forum-breakpoint-xl` | `1280px` | Extra large devices |

### Breakpoint Mixins

```scss
// Mobile-first (min-width)
@include breakpoint-up('sm') { ... }
@include breakpoint-up('md') { ... }
@include breakpoint-up('lg') { ... }

// Desktop-first (max-width)
@include breakpoint-down('md') { ... }
@include breakpoint-down('lg') { ... }

// Shorthand aliases
@include mobile { ... }    // max-width: 767px
@include tablet { ... }    // 768px to 1023px
@include desktop { ... }   // min-width: 1024px
```

---

## Responsive Design Protocol

**Mobile-first. Use `min-width` breakpoints.**

### Rules
- Start with mobile styles (no media query)
- Scale up with `@include breakpoint-up('md')` or `min-width`
- Nest media queries inside selectors they modify
- Avoid `max-width` except for edge cases
- NEVER use `wp_is_mobile()` — CSS handles all responsive behavior

### Example
```scss
.presszone-forum-component {
  padding: 1rem; // Mobile default

  @include breakpoint-up('md') {
    padding: 2rem; // Tablet+
  }

  @include breakpoint-up('lg') {
    padding: 3rem; // Desktop+
  }
}
```

---

## Z-Index Layers

Defined in `_variables.scss`:

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-z-dropdown` | `100` | Dropdown menus |
| `$presszone-forum-z-sticky` | `200` | Sticky elements |
| `$presszone-forum-z-fixed` | `300` | Fixed position |
| `$presszone-forum-z-modal-backdrop` | `400` | Modal overlay |
| `$presszone-forum-z-modal` | `500` | Modal dialog |
| `$presszone-forum-z-popover` | `600` | Popovers |
| `$presszone-forum-z-tooltip` | `700` | Tooltips |
| `$presszone-forum-z-toast` | `800` | Toast notifications |

---

## Mixins Reference (`_mixins.scss`)

### BEM Helpers

```scss
.presszone-forum-card {
    @include element('header') { ... }  // .presszone-forum-card__header
    @include modifier('featured') { ... }  // .presszone-forum-card--featured

    // Short aliases
    @include e('body') { ... }  // .presszone-forum-card__body
    @include m('active') { ... }  // .presszone-forum-card--active
}
```

### Animation Keyframes (`_animations.scss`)

### Available Keyframes - USE THESE, NEVER DUPLICATE

| Keyframe | Purpose |
|----------|---------|
| `presszone-forum-fade-in` | Simple fade in |
| `presszone-forum-spin` | 360 rotation |
| `presszone-forum-skeleton` | Loading shimmer |

### Usage Example

```scss
.presszone-forum-element {
    animation: presszone-forum-fade-in
               $presszone-forum-duration-normal
               $presszone-forum-ease-expo;
}
```

---

## BEM Naming Convention

### Structure

```
.presszone-forum-{block}__{element}--{modifier}
```

### Examples

```scss
// Block
.presszone-forum-card { }

// Elements (children of block)
.presszone-forum-card__header { }

// Modifiers (variations)
.presszone-forum-card--featured { }
```

---

## Build Commands Reference

All commands run from **plugin root** directory:

| Command | Purpose | Output |
|---------|---------|--------|
| `npm run build:css` | Build ALL CSS | All CSS files |
| `npm run watch:css` | Watch mode | Live rebuild |

---

## Dark Mode Implementation

### How It Works

1. Light mode values defined as SCSS variables with static hex values
2. Dark mode values defined as separate SCSS variables (e.g., `$presszone-forum-primary-dark`)
3. Components use light mode variables by default
4. Dark mode rules explicitly override using `body.dark-mode` selector

### Adding Dark Mode Support

```scss
// Define both light and dark values as SCSS variables
$presszone-forum-surface: #ffffff;
$presszone-forum-surface-dark: #1e1f20;
$presszone-forum-text: #0f172a;
$presszone-forum-text-dark: #e3e3e3;

// Component with explicit dark mode override
.presszone-forum-widget {
    background: $presszone-forum-surface;
    color: $presszone-forum-text;
}

body.dark-mode .presszone-forum-widget {
    background: $presszone-forum-surface-dark;
    color: $presszone-forum-text-dark;
}

// Alternative: nested syntax
.presszone-forum-widget {
    background: $presszone-forum-surface;
    color: $presszone-forum-text;

    body.dark-mode & {
        background: $presszone-forum-surface-dark;
        color: $presszone-forum-text-dark;
    }
}
```

### Why Not CSS Custom Properties?

Avoid `var(--*)` because:
1. SCSS variables compile to static values — better tooling support
2. Explicit dark mode rules easier to audit + debug
3. No runtime variable resolution overhead
4. Consistent with WordPress.org plugin standards

---

## Common Mistakes to Avoid

| Mistake | Fix |
|---------|-----|
| **`var(--presszone-forum-*)`** | **STRICTLY FORBIDDEN - Use `$presszone-forum-*`** |
| **`--presszone-forum-*:` definitions** | **STRICTLY FORBIDDEN - Never define CSS custom properties** |
| Using `/scss/` folders | Always use `/css/` folders for SCSS files |
| Using `var(--pz-*)` | Use `$presszone-forum-*` (4+ chars) |
| Using `$z-index` | Use `$presszone-forum-z-*` |
| Using `$breakpoint-*` | Use `$presszone-forum-breakpoint-*` |
| Hardcoded colors | Always use SCSS variables |
| Forgetting to build | Run `npm run build:css` |
| Duplicating keyframes | Use existing from `_animations.scss` |
| Missing reduced motion | Add `@media (prefers-reduced-motion)` |
| Raw breakpoint values | Use `@include breakpoint-up('md')` |

---

## Code Examples

### Complex Component Pattern
```scss
.presszone-forum-user-card {
  display: flex;
  flex-direction: column;
  padding: 1rem;
  background: $presszone-forum-surface;

  // Dark Mode
  .dark-mode & {
    background: $presszone-forum-surface-dark;
  }

  &__header {
    display: flex;
    z-index: $presszone-forum-z-sticky;
  }

  &__avatar {
    width: 50px;

    @include breakpoint-up('md') {
      width: 80px;
    }
  }
}
```

---

## Quick Reference Card

### Variable Prefix
```
$presszone-forum-{property}
```

### Class Prefix
```
.presszone-forum-{block}[__{element}][--{modifier}]
```

### Dark Mode Class
```
body.dark-mode
```

### Build Command
```bash
npm run build:css    # From plugin root
```

### Key Files
- Variables: `assets/css/abstracts/_variables.scss`
- Mixins: `assets/css/abstracts/_mixins.scss`
- Animations: `assets/css/base/_animations.scss`
- Dark Mode: `assets/css/frontend-dark.css`