roa2web-service-auto/docs/COMPONENT_STYLING.md

# Component Styling Guidelines

**Version:** 2.0.0
**Last Updated:** 2025-11-19
**Status:** ✅ Complete

---

## Table of Contents

1. [Overview](#overview)
2. [Decision Tree](#decision-tree)
3. [When to Use Global CSS](#when-to-use-global-css)
4. [When to Use Scoped CSS](#when-to-use-scoped-css)
5. [Anti-Patterns](#anti-patterns)
6. [Code Review Checklist](#code-review-checklist)
7. [Examples](#examples)
8. [Best Practices](#best-practices)

---

## Overview

ROA2WEB uses a **hybrid CSS architecture** combining:
- **Global patterns** (`src/assets/css/`) for reusable components
- **Scoped styles** (`<style scoped>`) for component-specific logic
- **Design tokens** (`var(--color-primary)`) for consistency
- **Zero `:deep()` overrides** for PrimeVue (centralized in `vendor/primevue-overrides.css`)

### Goals

✅ **Eliminate duplication** - Write CSS once, use everywhere
✅ **Maintain consistency** - Same patterns across the app
✅ **Improve maintainability** - Easy to update and scale
✅ **Reduce bundle size** - Less CSS = faster load times

---

## Decision Tree

### "Should I write CSS for this?"

```
Need to style a component?
│
├─ Does this pattern exist in another component?
│  ├─ YES → Use global CSS (check docs/CSS_PATTERNS.md)
│  └─ NO → Continue to next question
│
├─ Is this a form/button/card/table?
│  ├─ YES → Use global CSS (forms.css, buttons.css, cards.css, tables.css)
│  └─ NO → Continue to next question
│
├─ Is this a PrimeVue component?
│  ├─ YES → Check vendor/primevue-overrides.css (NEVER use :deep() in components!)
│  └─ NO → Continue to next question
│
├─ Is this a dashboard pattern (page header, metrics, breakdown)?
│  ├─ YES → Use global CSS (patterns/dashboard.css)
│  └─ NO → Continue to next question
│
├─ Is this an interactive element (spinner, trend, collapse)?
│  ├─ YES → Use global CSS (patterns/interactive.css)
│  └─ NO → Continue to next question
│
├─ Is this truly unique to this component (Chart.js canvas, complex state styling)?
│  ├─ YES → Scoped CSS is OK (keep it minimal <50 lines)
│  └─ NO → Extract to global pattern
│
└─ Still unsure? Ask in #frontend-css channel
```

---

## When to Use Global CSS

### ✅ Use Global CSS For:

#### 1. **Repeated Patterns (Used in 2+ components)**

```vue
<!-- ❌ BAD: Duplicate in every component -->
<style scoped>
.my-card {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  padding: var(--space-lg);
}
</style>

<!-- ✅ GOOD: Use global pattern -->
<template>
  <div class="card">
    <div class="card-body">Content</div>
  </div>
</template>

<style scoped>
/* No styles needed! */
</style>
```

#### 2. **Form Elements**

```vue
<!-- ❌ BAD: Custom form styles -->
<style scoped>
.field {
  margin-bottom: 1.5rem;
}
.field-label {
  font-weight: 600;
  color: #333;
}
.field-input {
  padding: 0.5rem 1rem;
  border: 1px solid #ddd;
}
</style>

<!-- ✅ GOOD: Use forms.css -->
<template>
  <div class="form-group">
    <label class="form-label">Username</label>
    <input class="form-input" />
  </div>
</template>

<style scoped>
/* No form styles! All in forms.css */
</style>
```

#### 3. **Buttons**

```vue
<!-- ❌ BAD: Custom button -->
<style scoped>
.my-button {
  background: #2563eb;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
}
</style>

<!-- ✅ GOOD: Use buttons.css -->
<template>
  <button class="btn btn-primary">Click Me</button>
</template>
```

#### 4. **Card Components**

```vue
<!-- ❌ BAD: Custom card styling -->
<style scoped>
.metric-container {
  background: white;
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 1.5rem;
}
.metric-number {
  font-size: 2rem;
  font-weight: 700;
}
</style>

<!-- ✅ GOOD: Use cards.css patterns -->
<template>
  <div class="metric-card">
    <div class="metric-value">$10,500</div>
    <div class="metric-label">Revenue</div>
  </div>
</template>
```

#### 5. **Dashboard Patterns**

```vue
<!-- ❌ BAD: Custom page header -->
<style scoped>
.page-heading {
  text-align: center;
  margin-bottom: 2rem;
}
.page-heading h1 {
  font-size: 2rem;
  font-weight: bold;
}
</style>

<!-- ✅ GOOD: Use dashboard.css -->
<template>
  <header class="page-header">
    <h1 class="page-title">Dashboard</h1>
    <p class="page-subtitle">Overview</p>
  </header>
</template>
```

#### 6. **Utility Classes**

```vue
<!-- ❌ BAD: Custom utility styles -->
<style scoped>
.flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}
.text-green {
  color: #059669;
}
</style>

<!-- ✅ GOOD: Use utility classes -->
<template>
  <div class="flex items-center justify-center">
    <span class="text-success">Success!</span>
  </div>
</template>
```

---

## When to Use Scoped CSS

### ✅ Scoped CSS is OK For:

#### 1. **Component-Specific Layout (Not Reusable)**

```vue
<template>
  <div class="dual-chart-layout">
    <div class="chart-left">
      <canvas ref="chart1"></canvas>
    </div>
    <div class="chart-right">
      <canvas ref="chart2"></canvas>
    </div>
  </div>
</template>

<style scoped>
/* Component-specific layout that won't be reused */
.dual-chart-layout {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: var(--space-md);
}

.chart-left,
.chart-right {
  position: relative;
  height: 300px;
}

@media (max-width: 768px) {
  .dual-chart-layout {
    grid-template-columns: 1fr;
  }
}
</style>
```

**Why it's OK:** This layout is unique to this specific dual-chart component and won't be used elsewhere.

#### 2. **Third-Party Library Integration (Chart.js, etc.)**

```vue
<template>
  <div class="chart-wrapper">
    <canvas ref="chartCanvas" class="chart-canvas"></canvas>
  </div>
</template>

<style scoped>
/* Chart.js requires specific canvas sizing */
.chart-wrapper {
  position: relative;
  height: 100%;
  width: 100%;
}

.chart-canvas {
  width: 100% !important;
  height: 100% !important;
  display: block;
}
</style>
```

**Why it's OK:** Chart.js has specific requirements that are component-specific and not reusable patterns.

#### 3. **Complex Component State Styling**

```vue
<template>
  <div class="data-visualizer" :class="visualizationMode">
    <!-- Complex visualization with multiple states -->
  </div>
</template>

<style scoped>
/* Complex state-dependent styling unique to this component */
.data-visualizer.mode-heatmap .cell {
  transition: background-color 0.3s ease;
}

.data-visualizer.mode-heatmap .cell.heat-low {
  background: #dcfce7;
}

.data-visualizer.mode-heatmap .cell.heat-high {
  background: #fecaca;
}

.data-visualizer.mode-chart {
  display: flex;
  flex-direction: column;
}
</style>
```

**Why it's OK:** This state machine is unique to this visualization component.

#### 4. **Print Styles (Component-Specific)**

```vue
<style scoped>
@media print {
  .no-print-action {
    display: none !important;
  }

  .invoice-table {
    page-break-inside: avoid;
  }

  .invoice-header {
    page-break-after: avoid;
  }
}
</style>
```

**Why it's OK:** Print styles for specific components that have unique printing requirements.

---

## Anti-Patterns

### ❌ NEVER Do These Things

#### 1. **Using `:deep()` for PrimeVue**

```vue
<!-- ❌ ABSOLUTELY FORBIDDEN -->
<style scoped>
:deep(.p-inputtext) {
  border: 2px solid #3b82f6 !important;
  padding: 1rem !important;
}

:deep(.p-datatable .p-datatable-thead) {
  background: #f3f4f6 !important;
}
</style>
```

**Why it's bad:**
- Creates specificity issues
- Overrides break easily
- Not maintainable
- Causes cascading problems

**✅ Correct approach:**
All PrimeVue styling goes in `src/assets/css/vendor/primevue-overrides.css`:

```css
/* vendor/primevue-overrides.css */
.p-inputtext {
  border: 2px solid var(--color-primary);
  padding: 1rem;
}

.p-datatable .p-datatable-thead {
  background: var(--color-bg-secondary);
}
```

#### 2. **Hardcoding Colors/Sizes**

```vue
<!-- ❌ BAD: Hardcoded values -->
<style scoped>
.card {
  background: #ffffff;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 24px;
  color: #111827;
}
</style>

<!-- ✅ GOOD: Design tokens -->
<style scoped>
.custom-layout {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  padding: var(--space-lg);
  color: var(--color-text);
}
</style>
```

#### 3. **Duplicating Existing Patterns**

```vue
<!-- ❌ BAD: Recreating button styles -->
<style scoped>
.submit-button {
  background: #2563eb;
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.375rem;
  cursor: pointer;
}

.submit-button:hover {
  background: #1d4ed8;
}
</style>

<!-- ✅ GOOD: Use existing pattern -->
<template>
  <button class="btn btn-primary">Submit</button>
</template>
```

#### 4. **Using `!important` in Scoped Styles**

```vue
<!-- ❌ BAD -->
<style scoped>
.my-element {
  color: red !important;
  font-size: 16px !important;
}
</style>

<!-- ✅ GOOD: Only use !important for vendor overrides in global CSS -->
<style scoped>
.my-element {
  color: var(--color-error);
  font-size: var(--text-base);
}
</style>
```

**Exception:** `!important` is allowed in:
- `vendor/primevue-overrides.css` (to override PrimeVue)
- Print styles (`@media print`)
- Third-party library overrides (documented reason required)

#### 5. **Creating Custom Form/Button Base Styles**

```vue
<!-- ❌ BAD: Custom base styles -->
<style scoped>
.input-field {
  width: 100%;
  padding: 0.5rem 1rem;
  border: 1px solid #ddd;
  border-radius: 0.375rem;
}

.primary-btn {
  background: #2563eb;
  color: white;
  padding: 0.5rem 1rem;
}
</style>

<!-- ✅ GOOD: Use global patterns -->
<template>
  <input class="form-input" />
  <button class="btn btn-primary">Click</button>
</template>
```

---

## Code Review Checklist

### Before Submitting PR

- [ ] **No duplicate patterns** - Checked `docs/CSS_PATTERNS.md` first
- [ ] **No `:deep()` in components** - PrimeVue styles in `vendor/primevue-overrides.css`
- [ ] **Design tokens used** - No hardcoded colors, sizes, or spacing
- [ ] **No `!important` in scoped styles** - Except documented exceptions
- [ ] **Scoped styles < 50 lines** - If more, consider extracting to global
- [ ] **No form/button/card base styles** - Use existing global patterns
- [ ] **Responsive tested** - Works on mobile (375px), tablet (768px), desktop (1920px)
- [ ] **Build successful** - `npm run build` passes
- [ ] **Playwright tests pass** - `npm run test:e2e` passes
- [ ] **CSS is necessary** - Not adding CSS just because "it looks different"

### Review Questions

**For Scoped CSS:**
1. Is this styling truly unique to this component?
2. Could this be used in 2+ places? → Make it global
3. Can this use existing patterns? → Use global CSS
4. Is this < 50 lines? → If not, extract to global
5. Does it have a documented reason? → Add comment

**For Global CSS:**
1. Is this pattern used in 2+ places?
2. Will this be reused in the future?
3. Does it fit existing pattern categories?
4. Is it generic enough for reuse?

---

## Examples

### ✅ Example #1: Good Use of Global CSS

```vue
<!-- Component: MetricCard.vue -->
<template>
  <div class="metric-card card-hover">
    <div class="metric-header">
      <div class="metric-icon bg-primary-light text-primary">
        <i class="pi pi-chart-bar"></i>
      </div>
      <div class="metric-label">Sales</div>
    </div>
    <div class="metric-value">$10,500</div>
    <div class="trend trend-up">
      <i class="pi pi-arrow-up trend-icon"></i>
      +12.5%
    </div>
  </div>
</template>

<style scoped>
/* No styles needed! All from global CSS:
 * - metric-card (cards.css)
 * - metric-header, metric-icon, metric-value, metric-label (cards.css)
 * - trend, trend-up, trend-icon (patterns/interactive.css)
 * - bg-primary-light, text-primary (utilities/colors.css)
 * - card-hover (patterns/interactive.css)
 */
</style>
```

**Why it's good:**
- Zero duplicate CSS
- Uses established patterns
- Maintainable
- Consistent with other cards

---

### ✅ Example #2: Good Use of Scoped CSS

```vue
<!-- Component: TreasuryDualCard.vue -->
<template>
  <div class="metric-card">
    <div class="metric-label">Treasury</div>

    <!-- UNIQUE: Side-by-side charts (not used elsewhere) -->
    <div class="dual-chart-container">
      <div class="chart-section">
        <div class="chart-header">
          <span class="chart-title">Bank</span>
          <span class="chart-value">{{ bankBalance }}</span>
        </div>
        <canvas ref="bankChart" class="chart-canvas"></canvas>
      </div>

      <div class="chart-section">
        <div class="chart-header">
          <span class="chart-title">Cash</span>
          <span class="chart-value">{{ cashBalance }}</span>
        </div>
        <canvas ref="cashChart" class="chart-canvas"></canvas>
      </div>
    </div>
  </div>
</template>

<style scoped>
/* Component-specific layout: Two charts side-by-side */
.dual-chart-container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: var(--space-lg);
  margin-top: var(--space-md);
}

.chart-section {
  min-height: 200px;
}

.chart-header {
  display: flex;
  justify-content: space-between;
  align-items: baseline;
  margin-bottom: var(--space-sm);
}

.chart-title {
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  color: var(--color-text-secondary);
  text-transform: uppercase;
}

.chart-value {
  font-size: var(--text-lg);
  font-weight: var(--font-semibold);
  font-family: var(--font-mono, monospace);
}

/* Chart.js canvas sizing (library-specific requirement) */
.chart-canvas {
  width: 100% !important;
  height: 100% !important;
}

@media (max-width: 768px) {
  .dual-chart-container {
    grid-template-columns: 1fr;
  }
}
</style>
```

**Why it's good:**
- Unique layout specific to this component
- Uses design tokens
- Chart.js integration requires specific CSS
- Responsive
- Well-commented

---

### ❌ Example #3: Bad - Duplicate Pattern

```vue
<!-- ❌ BAD: ClientiBalanceCard.vue -->
<template>
  <div class="balance-card">
    <div class="card-title">Clients Balance</div>
    <div class="balance-amount">$50,000</div>
  </div>
</template>

<style scoped>
.balance-card {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  border-radius: var(--card-radius);
  padding: var(--space-lg);
  /* Duplicating card pattern from cards.css */
}

.card-title {
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  color: var(--color-text-secondary);
  text-transform: uppercase;
  /* Duplicating metric-label from cards.css */
}

.balance-amount {
  font-size: var(--text-2xl);
  font-weight: var(--font-bold);
  font-family: var(--font-mono);
  /* Duplicating metric-value from cards.css */
}
</style>

<!-- ✅ GOOD: Use global patterns -->
<template>
  <div class="metric-card">
    <div class="metric-label">Clients Balance</div>
    <div class="metric-value">$50,000</div>
  </div>
</template>

<style scoped>
/* No styles needed! */
</style>
```

---

## Best Practices

### 1. **Check Pattern Library First**

Before writing ANY CSS, check:
1. [CSS Patterns Library](./CSS_PATTERNS.md)
2. `src/assets/css/` directories
3. Ask yourself: "Has this been done before?"

### 2. **Use Design Tokens**

```vue
<!-- ✅ GOOD -->
<style scoped>
.custom-element {
  color: var(--color-text);
  background: var(--color-bg);
  padding: var(--space-md);
  border-radius: var(--radius-md);
  font-size: var(--text-base);
}
</style>

<!-- ❌ BAD -->
<style scoped>
.custom-element {
  color: #111827;
  background: #ffffff;
  padding: 1rem;
  border-radius: 0.375rem;
  font-size: 16px;
}
</style>
```

### 3. **Keep Scoped CSS Minimal**

**Rule of thumb:** If scoped styles > 50 lines, extract to global pattern.

```vue
<!-- ❌ BAD: Too much scoped CSS (>50 lines) -->
<style scoped>
.container {
  /* ... 20 lines ... */
}
.header {
  /* ... 15 lines ... */
}
.body {
  /* ... 20 lines ... */
}
/* Total: 55 lines - extract to global! */
</style>

<!-- ✅ GOOD: Minimal scoped CSS -->
<style scoped>
/* Only component-specific layout (15 lines) */
.chart-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--space-lg);
}
</style>
```

### 4. **Document Scoped CSS Rationale**

```vue
<style scoped>
/**
 * Component-specific layout for dual sparkline charts.
 * This layout is unique to CashFlowMetricCard and won't be reused.
 *
 * Reason for scoped CSS: Dual-chart layout with synchronized tooltips
 * requires component-specific positioning that isn't a general pattern.
 */
.dual-chart-layout {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: var(--space-md);
}
</style>
```

### 5. **Responsive Design**

Use global responsive patterns when possible:

```vue
<!-- ✅ GOOD: Use global responsive utilities -->
<template>
  <div class="flex flex-col md:flex-row gap-md">
    <div class="w-full md:w-1/2">Left</div>
    <div class="w-full md:w-1/2">Right</div>
  </div>
</template>

<!-- ⚠️ OK: Component-specific breakpoints if truly unique -->
<style scoped>
.custom-grid {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
}

@media (max-width: 1024px) {
  .custom-grid {
    grid-template-columns: 1fr 1fr;
  }
}

@media (max-width: 768px) {
  .custom-grid {
    grid-template-columns: 1fr;
  }
}
</style>
```

---

## Migration Guide

### Migrating Existing Components

**Step 1:** Identify duplicate patterns
```bash
# Search for common patterns
grep -r "background: var(--color-bg)" src/components/
grep -r "border: 1px solid" src/components/
grep -r ":deep(.p-" src/components/
```

**Step 2:** Check Pattern Library
- Review `docs/CSS_PATTERNS.md`
- Find matching global patterns

**Step 3:** Replace with Global CSS
```vue
<!-- BEFORE -->
<style scoped>
.my-card {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  padding: var(--space-lg);
}
</style>

<!-- AFTER -->
<template>
  <div class="card">
    <div class="card-body">Content</div>
  </div>
</template>

<style scoped>
/* No styles needed! */
</style>
```

**Step 4:** Test
- Build: `npm run build`
- E2E tests: `npm run test:e2e`
- Visual inspection on all breakpoints

---

## Getting Help

- **Pattern Library:** [docs/CSS_PATTERNS.md](./CSS_PATTERNS.md)
- **Form Guidelines:** [docs/FORM_TEMPLATE.md](./FORM_TEMPLATE.md)
- **Design Tokens:** [docs/DESIGN_TOKENS.md](./DESIGN_TOKENS.md)
- **Questions?** Ask in #frontend-css channel
- **New pattern needed?** Follow [docs/STYLING_GUIDELINES.md](./STYLING_GUIDELINES.md)

---

**Last Updated:** 2025-11-19
**Version:** 2.0.0 (Post CSS Refactoring)
**Maintained By:** Frontend Team