# CSS/SCSS Development Skill

> **Technology:** 100% Pure SCSS Architecture - ZERO CSS Custom Properties

---

## Purpose

This skill covers frontend styling with pure SCSS variables, dark mode implementation, and responsive design for the Comments Press Zone plugin.

---

## 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 |

---

## ⛔ ABSOLUTE PROHIBITION: CSS Custom Properties

**ZERO TOLERANCE:** CSS custom properties (`var(--*)` and `--*` declarations) are **STRICTLY FORBIDDEN**. Use pure SCSS variables ONLY.

```scss
// ❌ FORBIDDEN - NO CSS custom properties
:root {
    --presszone-comments-primary: #1f71dd;
}
.btn { color: var(--presszone-comments-primary); }

// ✅ CORRECT - Pure SCSS variables ONLY
$presszone-comments-primary: #1f71dd;
$presszone-comments-primary-dark: #3b82f6;

.presszone-comments-btn {
    color: $presszone-comments-primary;
    
    .dark-mode & {
        color: $presszone-comments-primary-dark;
    }
}
```

---

## WordPress.org Compliance

### Naming Prefixes (4+ Characters REQUIRED)

```scss
// ✅ CORRECT
$presszone-comments-primary: #1f71dd;
.presszone-comments-btn {}
@keyframes presszone-comments-fade-in {}

// ❌ FORBIDDEN - TOO SHORT
$pz-primary: #1f71dd;
.pz-btn {}
@keyframes pz-fade {}
```

---

## Directory Structure

**MANDATORY: All SCSS source files go in `/css/` folders (NOT `/scss/`).**

```
assets/css/
├── abstracts/
│   ├── _variables.scss      # SCSS variables (source of truth)
│   └── _mixins.scss         # Reusable patterns
├── base/
│   ├── _reset.scss
│   └── _typography.scss
├── components/
│   ├── _buttons.scss
│   ├── _cards.scss
│   ├── _modals.scss
│   └── ...
├── themes/
│   └── _dark-mode.scss
├── frontend.scss             # Main entry point
└── frontend.css              # Compiled output
```

---

## SCSS Variables (Source of Truth)

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

### Color System

```scss
// Light mode colors
$presszone-comments-bg: #f8fafc;
$presszone-comments-surface: #ffffff;
$presszone-comments-surface-2: #f1f5f9;
$presszone-comments-surface-3: #e2e8f0;
$presszone-comments-primary: #1f71dd;
$presszone-comments-text: #0f172a;
$presszone-comments-text-secondary: #334155;
$presszone-comments-text-muted: #64748b;
$presszone-comments-border: #e2e8f0;
$presszone-comments-success: #10b981;
$presszone-comments-warning: #f59e0b;
$presszone-comments-error: #ef4444;

// Dark mode colors (used within .dark-mode & blocks)
$presszone-comments-bg-dark: #131314;
$presszone-comments-surface-dark: #1e1f20;
$presszone-comments-surface-2-dark: #282a2c;
$presszone-comments-surface-3-dark: #353739;
$presszone-comments-primary-dark: #3b82f6;
$presszone-comments-text-dark: #e3e3e3;
$presszone-comments-text-secondary-dark: #c4c7c5;
$presszone-comments-text-muted-dark: #bdc1c6;
$presszone-comments-border-dark: #3c4043;
$presszone-comments-success-dark: #34d399;
$presszone-comments-warning-dark: #fbbf24;
$presszone-comments-error-dark: #f87171;
```

### Spacing System

```scss
$presszone-comments-spacing-xs: 4px;
$presszone-comments-spacing-sm: 8px;
$presszone-comments-spacing-md: 12px;
$presszone-comments-spacing-lg: 16px;
$presszone-comments-spacing-xl: 24px;
$presszone-comments-spacing-2xl: 32px;
$presszone-comments-spacing-3xl: 48px;
```

### Border Radius

```scss
$presszone-comments-radius-sm: 4px;
$presszone-comments-radius-md: 8px;
$presszone-comments-radius-lg: 12px;
$presszone-comments-radius-xl: 16px;
$presszone-comments-radius-full: 9999px;
```

### Typography

```scss
$presszone-comments-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
$presszone-comments-font-size-sm: 0.875rem;
$presszone-comments-font-size-base: 1rem;
$presszone-comments-font-size-lg: 1.125rem;
$presszone-comments-font-size-xl: 1.25rem;
$presszone-comments-font-size-2xl: 1.5rem;
```

### Z-Index Layers

```scss
$presszone-comments-z-base: 1;
$presszone-comments-z-dropdown: 100;
$presszone-comments-z-modal: 1000;
$presszone-comments-z-popover: 1100;
$presszone-comments-z-tooltip: 1200;
```

### Breakpoints

```scss
$presszone-comments-breakpoint-sm: 640px;
$presszone-comments-breakpoint-md: 768px;
$presszone-comments-breakpoint-lg: 1024px;
$presszone-comments-breakpoint-xl: 1280px;
```

---

## BEM Naming Convention

```scss
// Block
.presszone-comments-btn {
    padding: $presszone-comments-spacing-md;
    background: $presszone-comments-primary;
}

// Element
.presszone-comments-btn__icon {
    margin-right: $presszone-comments-spacing-sm;
}

// Modifier
.presszone-comments-btn--primary {
    background: $presszone-comments-primary;
}

.presszone-comments-btn--secondary {
    background: $presszone-comments-surface-2;
}

.presszone-comments-btn--large {
    padding: $presszone-comments-spacing-lg;
    font-size: $presszone-comments-font-size-lg;
}
```

---

## Dark Mode Implementation

### How It Works

1. Light mode values defined as default SCSS variables
2. Dark mode values defined with `-dark` suffix
3. Dark mode overrides use `.dark-mode &` nesting

```scss
.presszone-comments-card {
    background: $presszone-comments-surface;
    color: $presszone-comments-text;
    border: 1px solid $presszone-comments-border;
    
    .dark-mode & {
        background: $presszone-comments-surface-dark;
        color: $presszone-comments-text-dark;
        border-color: $presszone-comments-border-dark;
    }
}
```

### NEVER Separate Dark Mode Files

```scss
// ❌ WRONG - Separate dark mode file
// dark-mode.scss
.dark-mode .presszone-comments-card {
    background: #1e1f20;
}

// ✅ CORRECT - Nested within component
.presszone-comments-card {
    background: $presszone-comments-surface;
    
    .dark-mode & {
        background: $presszone-comments-surface-dark;
    }
}
```

---

## Settings-Based Styling (Explicit Modifier Classes)

For dynamic settings (padding, border, styling), use explicit modifier classes with SCSS variables.

```scss
/* Default styles (Standard/Rounded) */
.presszone-comments-item {
    padding: $presszone-comments-spacing-md $presszone-comments-spacing-lg;
    border-radius: $presszone-comments-radius-lg;
    border-width: 1px;
}

/* Padding variations */
.presszone-comments-padding--minimal {
    .presszone-comments-item {
        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;
    }
}

/* Border thickness variations */
.presszone-comments-border--standard {
    .presszone-comments-item,
    .presszone-comments-modal {
        border-width: 1px;
    }
}

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

/* Border radius variations */
.presszone-comments-styling--square {
    .presszone-comments-item,
    .presszone-comments-btn {
        border-radius: 0;
    }
}

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

---

## Responsive Design

```scss
.presszone-comments-container {
    display: grid;
    grid-template-columns: 1fr;
    gap: $presszone-comments-spacing-md;

    @media (min-width: $presszone-comments-breakpoint-md) {
        grid-template-columns: repeat(2, 1fr);
    }

    @media (min-width: $presszone-comments-breakpoint-lg) {
        grid-template-columns: repeat(3, 1fr);
        gap: $presszone-comments-spacing-lg;
    }
}
```

---

## Animations

### Keyframes

```scss
@keyframes presszone-comments-fade-in {
    from {
        opacity: 0;
        transform: translateY(10px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

@keyframes presszone-comments-slide-down {
    from {
        max-height: 0;
        opacity: 0;
    }
    to {
        max-height: 1000px;
        opacity: 1;
    }
}
```

### Usage with Stagger

```scss
.presszone-comments-item {
    animation: presszone-comments-fade-in 0.3s ease-out;
}

// Explicit stagger classes
.presszone-comments-stagger-0 { animation-delay: 0ms; }
.presszone-comments-stagger-1 { animation-delay: 60ms; }
.presszone-comments-stagger-2 { animation-delay: 120ms; }
.presszone-comments-stagger-3 { animation-delay: 180ms; }
.presszone-comments-stagger-4 { animation-delay: 240ms; }
```

### Reduced Motion

```scss
@media (prefers-reduced-motion: reduce) {
    * {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}
```

---

## Common Component Patterns

### Button

```scss
.presszone-comments-btn {
    display: inline-flex;
    align-items: center;
    gap: $presszone-comments-spacing-sm;
    padding: $presszone-comments-spacing-sm $presszone-comments-spacing-md;
    border: none;
    border-radius: $presszone-comments-radius-md;
    font-size: $presszone-comments-font-size-base;
    font-weight: 500;
    cursor: pointer;
    transition: all 0.2s;

    &:hover {
        opacity: 0.9;
    }

    &:disabled {
        opacity: 0.5;
        cursor: not-allowed;
    }
}
```

### Card

```scss
.presszone-comments-card {
    background: $presszone-comments-surface;
    border: 1px solid $presszone-comments-border;
    border-radius: $presszone-comments-radius-lg;
    padding: $presszone-comments-spacing-lg;
    
    .dark-mode & {
        background: $presszone-comments-surface-dark;
        border-color: $presszone-comments-border-dark;
    }
}
```

### Modal

```scss
.presszone-comments-modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.5);
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: $presszone-comments-z-modal;

    &__content {
        background: $presszone-comments-surface;
        border-radius: $presszone-comments-radius-lg;
        max-width: 600px;
        width: 90%;
        max-height: 90vh;
        overflow-y: auto;
        
        .dark-mode & {
            background: $presszone-comments-surface-dark;
        }
    }
}
```

---

## Build Command

| Change Type | Command | Directory |
|-------------|---------|-----------|
| Frontend CSS | `npm run build:css` | Plugin root |
| Admin CSS | `npm run build` | `admin/` |

**CRITICAL:** Always rebuild after SCSS changes.

### WordPress.org Build Documentation Requirement

**MANDATORY:** If plugin contains SCSS files, you MUST provide build documentation in `CONTRIBUTING.md` or `BUILD.md`.

**Required Documentation:**
- Prerequisites (Node.js version, npm version)
- Build commands (installation + compilation)
- Source-to-output mapping (`assets/css/frontend.scss` → `assets/css/frontend.css`)
- Development workflow (watch mode for auto-rebuild)

**Example:**
```markdown
## Build CSS

### Prerequisites
- Node.js 14.x or higher
- npm 6.x or higher

### Production Build
```bash
npm install
npm run build:css
```

### Development Mode
```bash
npm run watch:css  # Auto-rebuild on file changes
```

### Source Files
- `assets/css/abstracts/_variables.scss` - SCSS variables
- `assets/css/frontend.scss` → `assets/css/frontend.css` (compiled)
```

**Failure to provide this documentation will result in WordPress.org rejection.**

---

## Common Mistakes to Avoid

| Mistake | Fix |
|---------|-----|
| Using CSS custom properties | Use SCSS variables ONLY |
| Using `/scss/` folders | Always use `/css/` folders |
| Short prefixes (<4 chars) | Use `$presszone-comments-*` |
| Hardcoded colors | Use SCSS variables |
| Separate dark mode file | Use nested `.dark-mode &` |
| Forgetting to build | Run `npm run build:css` |
| Using `!important` excessively | Increase specificity properly |
| Deep nesting (4+ levels) | Flatten with BEM naming |

---

## Testing Checklist

- [ ] All colors use SCSS variables
- [ ] Dark mode tested with `.dark-mode` class
- [ ] No CSS custom properties (`--*` or `var()`)
- [ ] All prefixes are 4+ characters
- [ ] Responsive at all breakpoints
- [ ] Reduced motion respected
- [ ] CSS rebuilt after changes
- [ ] No hardcoded values
- [ ] **Build documentation exists (CONTRIBUTING.md or BUILD.md)**