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
2. Decision Tree
3. When to Use Global CSS
4. When to Use Scoped CSS
5. Anti-Patterns
6. Code Review Checklist
7. Examples
8. 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)

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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)

<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.)

<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

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

<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

<!-- ❌ 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:

/* 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

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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

<!-- ❌ 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

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

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

<!-- ❌ 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
2. src/assets/css/ directories
3. Ask yourself: "Has this been done before?"

2. Use Design Tokens

<!-- ✅ 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.

<!-- ❌ 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

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

<!-- ✅ 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

# 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

<!-- 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
• Form Guidelines: docs/FORM_TEMPLATE.md
• Design Tokens: docs/DESIGN_TOKENS.md
• Questions? Ask in #frontend-css channel
• New pattern needed? Follow docs/STYLING_GUIDELINES.md

---

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