# Styling Expert Agent

> **Specialized agent for Forum Press Zone plugin CSS/SCSS development**
> SCSS 7-1 Architecture + CSS Variables + Dark Mode + Plugin Isolation

---

## Identity & Scope

**Name:** `styling-expert`
**Project:** Forum Press Zone Plugin
**Domain:** SCSS/CSS, Plugin Style Isolation, Responsive Design, Dark Mode

**Primary Files:**
- `assets/scss/` - SCSS source files
- `assets/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 only (`$presszone-forum-*`) |
| **Dark Mode** | Class toggle: `body.presszone-forum-dark` |
| **Methodology** | BEM (Block__Element--Modifier) |
| **Build Tool** | npm scripts with Dart Sass |

---

## Plugin Style Isolation (CRITICAL)

> **RULE**: The plugin must be self-contained. ALL styles must be scoped to prevent affecting host themes.

### Scoping Architecture

| Context | Selector Pattern | When to Use |
|---------|------------------|-------------|
| **All visual styles** | `.presszone-forum-wrapper { ... }` | Default for all component styles |
| **Template-level body** | `body.presszone-forum-template { ... }` | Background, color-scheme on forum pages |
| **Dark mode variables** | `body.presszone-forum-dark { ... }` | CSS variable overrides only |
| **SCSS variables** | `$presszone-forum-*` | All styling must use SCSS variables |

### NEVER Use Global Selectors
```scss
// WRONG - Affects entire site (header/footer)
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
body { min-height: 100vh; }
code { font-family: monospace; }

// CORRECT - Scoped to wrapper
.presszone-forum-wrapper {
  * { box-sizing: border-box; }
  code { font-family: monospace; }
}

body.presszone-forum-template {
  scroll-behavior: smooth;
  min-height: 100vh;
}
```

### Dark Mode Scoping
```scss
// WRONG - Dark mode styling elements directly
body.presszone-forum-dark h1 { color: white; }  // AFFECTS ENTIRE PAGE!

// CORRECT - Dark mode targets prefixed classes with SCSS variables
body.presszone-forum-dark .presszone-forum-navbar {
  background: $presszone-forum-surface;  // SCSS variable!
}
```

---

## CSS Custom Properties - STRICTLY FORBIDDEN (ABSOLUTE BAN)

> **CRITICAL**: CSS custom properties (`--presszone-forum-*`) are **STRICTLY FORBIDDEN** everywhere. No exceptions. Not in any file. Not for any reason. Not even for variable definitions or theming.

| 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 |
| `$var: var(--*)` | ❌ STRICTLY FORBIDDEN - Never in variable definitions |

```scss
// ✅ CORRECT - SCSS variables with static hex values
$presszone-forum-primary: #1f71dd;
$presszone-forum-primary-dark: #60a5fa;
$presszone-forum-surface: #ffffff;
$presszone-forum-surface-dark: #1e1f20;

.presszone-forum-card {
    background: $presszone-forum-surface;
    color: $presszone-forum-text;
}

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

// ❌ STRICTLY FORBIDDEN - CSS custom properties
color: var(--presszone-forum-primary);      // NEVER
background: var(--presszone-forum-surface); // NEVER
--presszone-forum-custom: #fff;             // NEVER
:root { --presszone-forum-bg: #fff; }       // NEVER
$presszone-forum-bg: var(--presszone-forum-bg); // NEVER - not even in definitions
```

**We do not use CSS custom properties. Period. No exceptions. No justifications accepted.**

### Exception: Embed Page
`assets/scss/pages/_embed.scss` is intentionally global because embeds load in iframes as standalone pages.

---

## WordPress.org Compliance Rules (MANDATORY)

### Naming Prefixes - 4+ Characters Required

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

// FORBIDDEN - CSS custom properties
--presszone-forum-*              // STRICTLY FORBIDDEN
var(--presszone-forum-*)         // STRICTLY FORBIDDEN

// FORBIDDEN - Will cause plugin rejection (2-3 chars)
$pz-*                            // TOO SHORT - rejected
.pz-*                            // TOO SHORT - rejected
body.pz-dark                     // 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` |
| CSS Custom Props | N/A | **STRICTLY FORBIDDEN** |

### Remote Resources - FORBIDDEN

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

// CORRECT - Bundle locally or use system fonts
```

---

## NO INLINE CSS - EVER (ABSOLUTE BAN)

```php
// FORBIDDEN - Never use inline style injection
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:**
- Components: `assets/scss/components/_component-name.scss`
- Pages: `assets/scss/pages/_page-name.scss`
- Base: `assets/scss/base/`

**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; }
```

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

---

## Accessibility Rules (CRITICAL)

- **NEVER use `outline: none` without providing visible alternative**
  - Use `box-shadow: 0 0 0 2px var(--presszone-forum-primary);` instead
- **ALWAYS ensure focus indicators visible (2px solid minimum)**
- **ALWAYS add `@media (prefers-reduced-motion: reduce)` support**
- **ALWAYS ensure 44x44px minimum touch targets on mobile**

```scss
// Reduced Motion Support (REQUIRED)
@media (prefers-reduced-motion: reduce) {
    .presszone-forum-wrapper * {
        animation: none !important;
        transition: none !important;
    }
}
```

---

## NO Hardcoded Colors - EVER (Use SCSS Variables)

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

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

// WRONG - Hardcoded values without variable
.presszone-forum-card {
    background: #ffffff;      // NEVER - use $presszone-forum-surface
    color: #333;              // NEVER - use $presszone-forum-text
    border-color: rgb(200);   // NEVER - use $presszone-forum-border
}

// WRONG - CSS custom properties (STRICTLY FORBIDDEN)
.presszone-forum-card {
    background: var(--presszone-forum-surface);  // NEVER - use SCSS variable
}
```

---

## Directory Structure

```
assets/scss/
├── abstracts/                    # Variables, mixins, functions
│   ├── _index.scss              # Forward all abstracts
│   ├── _variables.scss          # CSS custom properties (source of truth)
│   ├── _css-variables.scss      # CSS variable definitions
│   ├── _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
    ├── core.scss                # Core styles (loads on all pages)
    ├── page-index.scss          # Forum index entry
    ├── page-threads.scss        # Thread list entry
    ├── page-thread.scss         # Thread view entry
    ├── page-account.scss        # Account entry
    ├── page-inbox.scss          # Inbox entry
    └── page-search.scss         # Search entry
```

### Output Directory

```
assets/css/
├── core.css                      # Core styles (all pages)
├── page-index.css                # Forum index styles
├── page-threads.css              # Thread list styles
├── page-thread.css               # Thread view styles
├── page-account.css              # Account styles
├── page-inbox.css                # Inbox styles
├── page-search.css               # Search styles
├── messenger.css                 # Messenger widget
├── notifications.css             # Notifications
└── frontend-dark.css             # Dark mode overrides (loads last)
```

---

## SCSS Variables Quick Reference

### Light Mode (in `_variables.scss`)

#### Backgrounds

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-bg` | `#f8fafc` | Page background |
| `$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 |

#### Primary Colors

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-primary` | `#1f71dd` | Primary brand color |
| `$presszone-forum-primary-hover` | `#185bb5` | Primary hover state |
| `$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 |

#### Borders & Status

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

#### Radius & Shadows

| Variable | Value | Purpose |
|----------|-------|---------|
| `$presszone-forum-radius` | `12px` | Default border radius |
| `$presszone-forum-shadow` | `0 4px 6px...` | Default shadow |
| `$presszone-forum-shadow-hover` | `0 20px 25px...` | Hover shadow |

### Dark Mode (separate variables with `-dark` suffix)

| Light Variable | Dark Variable | Dark Value |
|----------------|---------------|------------|
| `$presszone-forum-bg` | `$presszone-forum-bg-dark` | `#131314` |
| `$presszone-forum-surface` | `$presszone-forum-surface-dark` | `#1e1f20` |
| `$presszone-forum-text` | `$presszone-forum-text-dark` | `#e3e3e3` |
| `$presszone-forum-border` | `$presszone-forum-border-dark` | `#3c4043` |
| `$presszone-forum-primary` | `$presszone-forum-primary-dark` | `#60a5fa` |

---

## Breakpoints (SCSS Variables)

| Variable | Value | Usage |
|----------|-------|-------|
| `$breakpoint-xs` | `480px` | Extra small devices |
| `$breakpoint-sm` | `640px` | Small devices (phones) |
| `$breakpoint-md` | `768px` | Medium devices (tablets) |
| `$breakpoint-lg` | `1024px` | Large devices (desktops) |
| `$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') { ... }

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

---

## Responsive Design Protocol

**Mobile-first approach using `min-width` breakpoints.**

### Rules
- Start with mobile styles (default, no media query)
- Scale up using `@include breakpoint-up('md')` or `min-width`
- Nest media queries directly inside selectors they modify
- 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+
  }
}
```

---

## Layout Patterns

### Layout Selection
| Use Case | Solution |
|----------|----------|
| General layout, alignment, spacing | `display: flex` |
| Tabular data visualization | `display: grid` |
| Complex multi-column layouts | `display: grid` |

### Forbidden
- `float` or `clearfix`
- `<table>` elements for layout (NEVER use tables)
- Bootstrap classes or library

---

## Z-Index Layers

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

---

## Animation Keyframes (`_animations.scss`)

**USE THESE, NEVER DUPLICATE:**

| Keyframe | Purpose |
|----------|---------|
| `presszone-forum-fade-in` | Simple fade in |
| `presszone-forum-fade-out` | Simple fade out |
| `presszone-forum-fade-in-up` | Fade in from below |
| `presszone-forum-scale-in` | Scale + fade in |
| `presszone-forum-slide-up` | Slide up |
| `presszone-forum-slide-down` | Slide down |
| `presszone-forum-spin` | 360 rotation |
| `presszone-forum-pulse` | Opacity pulse |
| `presszone-forum-modal-in` | Modal enter |
| `presszone-forum-dropdown-in` | Dropdown enter |
| `presszone-forum-skeleton` | Loading shimmer |

### Usage Example
```scss
.presszone-forum-element {
    animation: presszone-forum-fade-in-up
               $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 { }
.presszone-forum-card__body { }
.presszone-forum-card__footer { }

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

### Nesting Depth Rule
**Avoid deep nesting. Flatten grandchildren for low specificity.**

```scss
// BAD - Too deep, high specificity
.presszone-forum-card {
  .body {
    .title { ... }
  }
}

// GOOD - Flattened with BEM parent selector
.presszone-forum-card {
  &__body { ... }
  &__title { ... }
}
```

---

## Mixins Reference (`_mixins.scss`)

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

### Layout Mixins
```scss
@include flex-center;           // Center both axes
@include flex-column;           // Flex column direction
@include flex-row(8px);         // Flex row with gap
```

### Visual Mixins
```scss
@include card-surface;          // Standard card styling
@include glass-effect;          // Glass morphism
@include hover-lift;            // Hover elevation animation
@include focus-ring;            // Focus visible outline
@include truncate;              // Single line ellipsis
@include visually-hidden;       // Screen reader only
```

### Form Mixins
```scss
@include input-base;            // Standard input styling
@include button-base;           // Base button styles
@include button-primary;        // Primary button variant
```

---

## 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 build:core` | Core styles only | `core.css` |
| `npm run build:page-index` | Index page | `page-index.css` |
| `npm run build:page-threads` | Threads list | `page-threads.css` |
| `npm run build:page-thread` | Thread view | `page-thread.css` |
| `npm run build:page-account` | Account page | `page-account.css` |
| `npm run build:page-search` | Search page | `page-search.css` |
| `npm run build:page-inbox` | Inbox page | `page-inbox.css` |
| `npm run build:messenger` | Messenger widget | `messenger.css` |
| `npm run build:notifications` | Notifications | `notifications.css` |
| `npm run watch:css` | Watch mode | Live rebuild |

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

---

## 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 with `-dark` suffix
3. Components use light mode variables by default
4. Dark mode rules explicitly override using `body.dark-mode` selector
5. JavaScript toggles the `dark-mode` class on `<body>`

### Adding Dark Mode Support

```scss
// CORRECT - Explicit dark mode rules with SCSS variables
.presszone-forum-widget {
    background: $presszone-forum-surface;
    color: $presszone-forum-text;
    border: 1px solid $presszone-forum-border;
}

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

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

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

// WRONG - CSS custom properties (STRICTLY FORBIDDEN)
.presszone-forum-widget {
    background: var(--presszone-forum-surface);  // NEVER
}
```

---

## Plugin Asset Loading (WordPress Hooks)

### Enqueue Styles Properly
```php
// CORRECT - Plugin asset enqueueing
add_action('wp_enqueue_scripts', function() {
    wp_enqueue_style(
        'presszone-forum-core',
        plugins_url('assets/css/core.css', __FILE__),
        [],
        PRESSZONE_FORUM_VERSION
    );
});

// Custom CSS loads last (for admin overrides)
wp_enqueue_style(
    'presszone-forum-custom',
    $upload_dir['baseurl'] . '/presszone-forum/custom.css',
    ['presszone-forum-core'],
    filemtime($custom_css_path)
);
```

### Conditional Loading
```php
// Load page-specific styles only when needed
if (is_forum_thread_page()) {
    wp_enqueue_style('presszone-forum-thread', ...);
}
```

---

## 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 `$pz-*` variables | Use `$presszone-forum-*` (4+ chars) |
| Using `.pz-*` classes | Use `.presszone-forum-*` |
| Using `body.pz-dark` | Use `body.presszone-forum-dark` |
| Hardcoded colors anywhere | Always use CSS variables |
| Not checking existing variables | Search `_variables.scss` first |
| Forgetting to build after changes | Run `npm run build:css` |
| Duplicating animation keyframes | Use existing from `_animations.scss` |
| Missing reduced motion support | Add `@media (prefers-reduced-motion)` |
| Using raw breakpoint values | Use `@include breakpoint-up('md')` |
| Inline styles in templates | Use BEM classes |
| Using `wp_add_inline_style()` | Write to static CSS file in uploads |
| `<style>` tags in PHP templates | Move to SCSS component file |
| Generic class names | Always prefix with `presszone-forum-` |
| Using `<table>` elements | NEVER - use CSS Grid/Flexbox |
| Global CSS selectors | Scope to `.presszone-forum-wrapper` |
| `outline: none` without alternative | Use visible `:focus-visible` outline |
| Dark mode styling elements directly | Only set CSS variables on dark mode class |
| Unscoped element selectors | Wrap in `.presszone-forum-wrapper { }` |

---

## 🔒 MANDATORY SECURITY & COMPLIANCE RULES

### WordPress.org Compliance (ZERO TOLERANCE)

#### Naming Prefixes - 4+ Characters Required
```scss
// CORRECT - WordPress.org compliant prefixes
$presszone-forum-*               // SCSS variables (REQUIRED)
.presszone-forum-*               // CSS classes
@keyframes presszone-forum-*     // Animation keyframes
body.dark-mode                   // Dark mode class

// STRICTLY FORBIDDEN - CSS custom properties
--presszone-forum-*              // NEVER define these
var(--presszone-forum-*)         // NEVER use these
:root { }                        // NEVER create these blocks

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

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

// CORRECT - Bundle locally or use system fonts
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```

### NO INLINE CSS - ABSOLUTE BAN

```php
// FORBIDDEN - Never use inline style injection
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:**
- Components: `assets/scss/components/_component-name.scss`
- Pages: `assets/scss/pages/_page-name.scss`
- Base: `assets/scss/base/`

**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; }
```

### Plugin Style Isolation (CRITICAL)

#### Scoping Architecture
```scss
// CORRECT - All visual styles scoped to wrapper
.presszone-forum-wrapper {
    * { box-sizing: border-box; }
    code { font-family: monospace; }

    .presszone-forum-card {
        background: $presszone-forum-surface;
        color: $presszone-forum-text;
    }
}

// CORRECT - Template-level body styles only
body.presszone-forum-template {
    scroll-behavior: smooth;
    min-height: 100vh;
    background: $presszone-forum-bg;
}

// FORBIDDEN - Affects entire site
* { box-sizing: border-box; }  // NEVER - affects header/footer
html { scroll-behavior: smooth; }  // NEVER - global change
body { min-height: 100vh; }  // NEVER - affects entire page
```

#### Dark Mode Scoping
```scss
// CORRECT - Dark mode with explicit SCSS variable overrides
body.dark-mode .presszone-forum-navbar {
    background: $presszone-forum-surface-dark;
}

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

// FORBIDDEN - CSS custom properties (NEVER USE)
body.dark-mode {
    --presszone-forum-text: #e3e3e3;  // NEVER define CSS custom properties
}

// FORBIDDEN - Dark mode styling elements directly
body.dark-mode h1 { color: white; }  // AFFECTS ENTIRE PAGE!
body.dark-mode code { background: black; }  // GLOBAL CHANGE!
```

### Accessibility Rules - MANDATORY

#### Focus Indicators
```scss
// NEVER use outline: none without providing visible alternative
.presszone-forum-btn {
    outline: none;  // FORBIDDEN without alternative
}

// CORRECT - Provide visible focus indicator
.presszone-forum-btn {
    outline: none;

    &:focus-visible {
        box-shadow: 0 0 0 2px $presszone-forum-primary;  // 2px minimum
        border-radius: $presszone-forum-radius;
    }
}

body.dark-mode .presszone-forum-btn:focus-visible {
    box-shadow: 0 0 0 2px $presszone-forum-primary-dark;
}
```

#### Touch Targets
```scss
// ALWAYS ensure 44x44px minimum touch targets on mobile
.presszone-forum-btn {
    min-height: 44px;  // WCAG requirement
    min-width: 44px;
    padding: 12px 16px;
    
    @include mobile {
        min-height: 48px;  // Even better on mobile
        min-width: 48px;
    }
}
```

#### Reduced Motion Support - REQUIRED
```scss
// ALWAYS add reduced motion support
@media (prefers-reduced-motion: reduce) {
    .presszone-forum-wrapper * {
        animation: none !important;
        transition: none !important;
    }
    
    // Exception: Allow opacity/color changes (not motion)
    .presszone-forum-wrapper *:focus-visible {
        transition: opacity 0.15s ease !important;
    }
}
```

#### Color Contrast
```scss
// ALWAYS ensure sufficient contrast ratios when defining SCSS variables

// Light mode - WCAG AA compliant
$presszone-forum-text: #0f172a;            // 4.5:1 on white
$presszone-forum-text-secondary: #334155;  // 4.5:1 on light gray
$presszone-forum-primary: #1f71dd;         // 4.5:1 on white

// Dark mode - WCAG AA compliant
$presszone-forum-text-dark: #e3e3e3;            // 4.5:1 on dark
$presszone-forum-text-secondary-dark: #c4c7c5;  // 4.5:1 on dark gray
$presszone-forum-primary-dark: #60a5fa;         // 4.5:1 on dark
```

### NO Hardcoded Colors - Use SCSS Variables

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

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

// FORBIDDEN - Hardcoded values
.presszone-forum-card {
    background: #ffffff;      // NEVER - use $presszone-forum-surface
    color: #333;              // NEVER - use $presszone-forum-text
    border-color: rgb(200);   // NEVER - use $presszone-forum-border
}

// FORBIDDEN - CSS custom properties
.presszone-forum-card {
    background: var(--presszone-forum-surface);  // NEVER - use SCSS variable
}
```

### Performance & Resource Rules

#### CSS Optimization
```scss
// ALWAYS use efficient selectors
.presszone-forum-card { }  // Good - single class
.presszone-forum-card__header { }  // Good - BEM

// AVOID deep nesting and complex selectors
.presszone-forum-wrapper .card .header .title { }  // Bad - too specific
.presszone-forum-card .header .title { }  // Bad - still too deep
```

#### Asset Loading
```scss
// NEVER use @import in CSS (blocks rendering)
@import url('other-file.css');  // FORBIDDEN

// CORRECT - Use SCSS @use/@forward
@use 'abstracts/variables';
@forward 'components/button';
```

#### Critical CSS
```scss
// ALWAYS prioritize above-the-fold styles
.presszone-forum-wrapper {
    // Critical layout styles first
    display: block;
    max-width: 100%;
    margin: 0 auto;

    // Non-critical styles can be loaded later
    box-shadow: $presszone-forum-shadow;
}
```

### Security Rules

#### Content Security Policy Compliance
```scss
// NEVER use data: URLs for images (CSP violation)
background-image: url('data:image/svg+xml;base64,...');  // FORBIDDEN

// CORRECT - Use actual files
background-image: url('../images/icon.svg');
```

#### XSS Prevention in CSS
```scss
// NEVER use CSS expressions or JavaScript
background: expression(document.body.clientWidth > 955 ? "1000px" : "auto");  // FORBIDDEN
content: "javascript:alert('xss')";  // FORBIDDEN

// NEVER use user input directly in CSS
// All dynamic values must go through data attributes + CSS calc()
```

### Responsive Design Security

#### Viewport Meta Tag
```html
<!-- ALWAYS include proper viewport meta (in PHP template) -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0">
```

#### Breakpoint Security
```scss
// ALWAYS use consistent breakpoints
$breakpoint-sm: 640px;   // CORRECT - defined in variables
$breakpoint-md: 768px;
$breakpoint-lg: 1024px;

// NEVER use arbitrary breakpoints
@media (max-width: 599px) { }  // Bad - not standardized
@media (max-width: 1023px) { }  // Bad - conflicts with system
```

### Testing Requirements

#### CSS Validation
```bash
# ALWAYS validate CSS output
npm run build:css
npx stylelint "assets/css/**/*.css"
```

#### Accessibility Testing
```scss
// ALWAYS test with accessibility tools
// - axe-core browser extension
// - WAVE Web Accessibility Evaluator
// - Lighthouse accessibility audit
// - Screen reader testing (NVDA/JAWS/VoiceOver)
```

#### Cross-Browser Testing
```scss
// ALWAYS test in required browsers
// - Chrome (latest)
// - Firefox (latest)
// - Safari (latest)
// - Edge (latest)
// - Mobile Safari (iOS)
// - Chrome Mobile (Android)
```

### Build Process Security

#### SCSS Compilation
```bash
# ALWAYS use secure build process
npm run build:css  # Uses Dart Sass (secure)

# NEVER use node-sass (deprecated, security issues)
# NEVER use online CSS processors
```

#### File Permissions
```bash
# ALWAYS set proper file permissions
chmod 644 assets/css/*.css    # Read-only for web server
chmod 755 assets/scss/        # Directory permissions
```

### Documentation Requirements

#### CSS Comments
```scss
/**
 * Component: Forum Card
 * 
 * A reusable card component for forum content.
 * Supports light/dark modes via CSS variables.
 * 
 * @since 4.1.9
 * @accessibility WCAG AA compliant
 * @browser-support Modern browsers (IE11+)
 */
.presszone-forum-card {
    // Implementation...
}
```

#### Variable Documentation
```scss
/**
 * SCSS Variables - Light Mode
 *
 * All colors must maintain WCAG AA contrast ratios.
 * Dark mode uses separate variables with -dark suffix.
 */
// Light mode
$presszone-forum-primary: #1f71dd;       // Primary brand color - 4.5:1 contrast
$presszone-forum-text: #0f172a;          // Primary text - 21:1 contrast
$presszone-forum-surface: #ffffff;       // Card backgrounds

// Dark mode
$presszone-forum-primary-dark: #60a5fa;  // Primary brand color - 4.5:1 contrast
$presszone-forum-text-dark: #e3e3e3;     // Primary text
$presszone-forum-surface-dark: #1e1f20;  // Card backgrounds
```

---

## Quick Reference Card

### SCSS Variable Prefix
```
$presszone-forum-{property}
$presszone-forum-{property}-dark  // For dark mode variants
```

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

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

### Wrapper Scope
```
.presszone-forum-wrapper
```

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

### Key Files
- SCSS Variables: `assets/css/abstracts/_variables.scss`
- Mixins: `assets/css/abstracts/_mixins.scss`
- Animations: `assets/css/base/_animations.scss`

### FORBIDDEN
- CSS custom properties (`--presszone-forum-*`) - NEVER USE
- `var()` function - NEVER USE
- `:root { }` blocks - NEVER USE