roa2web-service-auto/reports-app/frontend/docs/COMPONENT_STYLING.md

Component Styling Guidelines - ROA2WEB

Last Updated: 2025-11-18 Phase: 3 - PrimeVue Centralization

---

🎯 Core Principles

1. NEVER Use :deep() in Components

❌ NEVER Do This:

<style scoped>
:deep(.p-inputtext) {
  border: 2px solid #3b82f6 !important;
}
</style>

✅ Always Do This: PrimeVue components are styled globally in assets/css/vendor/primevue-overrides.css.

Use classes, not deep overrides:

<template>
  <InputText class="form-input" />
</template>

<style scoped>
.form-input {
  /* Component-specific spacing/layout only */
  margin-bottom: var(--space-md);
}
</style>

---

2. Use Design Tokens, Not Hardcoded Values

❌ NEVER Do This:

<style scoped>
.my-button {
  background: #3b82f6;
  color: #ffffff;
  border: 1px solid #e5e7eb;
}
</style>

✅ Always Do This:

<style scoped>
.my-button {
  background: var(--color-primary);
  color: var(--color-text-inverse);
  border: 1px solid var(--color-border);
}
</style>

Available Design Tokens: See assets/css/core/variables.css

---

3. Minimize !important Usage

✅ Acceptable Use Cases:

1. Global PrimeVue Overrides (primevue-overrides.css):

.p-inputtext {
  border: 2px solid var(--color-border) !important;
}

2. Print Styles (@media print):

@media print {
  .dashboard-table th {
    background: var(--color-bg-muted) !important;
    color: #000 !important;
  }
}

3. Critical PrimeVue Component Overrides (rare):

<style scoped>
.login-button {
  /* Overriding PrimeVue Button defaults intentionally */
  background: var(--color-primary-light) !important;
}
</style>

❌ NEVER Do This:

<style scoped>
.my-text {
  color: red !important;  /* No justification for !important */
  font-size: 16px !important;
}
</style>

---

📁 File Organization

Where to Put Styles

1. Component-Specific Styles → <style scoped> in component

   • Layout (flexbox, grid)
   • Component-specific spacing
   • Custom animations

2. Global Patterns → assets/css/patterns/

   • Reusable UI patterns
   • Interactive states
   • Dashboard metrics

3. PrimeVue Overrides → assets/css/vendor/primevue-overrides.css

   • ALL PrimeVue component styling
   • Global theme customization

4. App-Wide Row Styling → App.vue (unscoped)

   • DataTable row classes (.invoice-paid, .bank-row, etc.)
   • Status badges
   • Global utilities

---

🎨 PrimeVue Styling Strategy

Global Override File

Location: src/assets/css/vendor/primevue-overrides.css

Purpose: Single source of truth for all PrimeVue component styling

Example:

/* Input Components */
.p-inputtext,
.p-password input {
  border: 2px solid var(--color-border) !important;
  border-radius: var(--radius-md) !important;
}

/* Focus States */
.p-inputtext:focus {
  border-color: var(--color-primary) !important;
  box-shadow: var(--focus-ring) !important;
}

Component Usage

<template>
  <!-- PrimeVue components automatically styled by global overrides -->
  <InputText v-model="username" placeholder="Username" />

  <!-- Add component-specific classes for layout/spacing only -->
  <InputText v-model="email" class="email-input" />
</template>

<style scoped>
/* Component-specific layout ONLY - no PrimeVue overrides */
.email-input {
  margin-top: var(--space-md);
  width: 100%;
}
</style>

---

🔄 DataTable Row Styling

Global Row Classes (App.vue)

Custom row classes for DataTables are defined globally in App.vue:

/* src/App.vue - unscoped styles */
.p-datatable .p-datatable-tbody > tr.invoice-paid {
  background-color: var(--green-50);
  color: var(--green-900);
}

.p-datatable .p-datatable-tbody > tr.invoice-overdue {
  background-color: var(--red-50);
  color: var(--red-900);
}

.p-datatable .p-datatable-tbody > tr.bank-row {
  background-color: var(--blue-50);
}

.p-datatable .p-datatable-tbody > tr.cash-row {
  background-color: var(--yellow-50);
}

Component Usage

<script setup>
const getRowClass = (data) => {
  if (data.status === 'paid') return 'invoice-paid';
  if (data.status === 'overdue') return 'invoice-overdue';
  return '';
};
</script>

<template>
  <DataTable :value="invoices" :rowClass="getRowClass">
    <!-- columns -->
  </DataTable>
</template>

<style scoped>
/* NO :deep() overrides needed! Row classes defined in App.vue */
</style>

---

📐 Design Tokens Reference

Colors

/* Primary */
--color-primary: #2563eb
--color-primary-light: #3b82f6
--color-primary-dark: #1d4ed8

/* Semantic */
--color-success: #059669
--color-warning: #d97706
--color-error: #dc2626
--color-info: #0891b2

/* Text */
--color-text: #111827
--color-text-secondary: #6b7280
--color-text-muted: #9ca3af
--color-text-inverse: #ffffff

/* Backgrounds */
--color-bg: #ffffff
--color-bg-secondary: #f9fafb
--color-bg-muted: #f3f4f6

/* Borders */
--color-border: #e5e7eb
--color-border-light: #f3f4f6
--color-border-dark: #d1d5db

Spacing

--space-xs: 0.25rem   /* 4px */
--space-sm: 0.5rem    /* 8px */
--space-md: 1rem      /* 16px */
--space-lg: 1.5rem    /* 24px */
--space-xl: 2rem      /* 32px */
--space-2xl: 3rem     /* 48px */

Border Radius

--radius-sm: 0.25rem  /* 4px */
--radius-md: 0.5rem   /* 8px */
--radius-lg: 0.75rem  /* 12px */
--radius-xl: 1rem     /* 16px */
--radius-full: 9999px

Transitions

--transition-fast: 150ms ease
--transition-normal: 250ms ease
--transition-slow: 350ms ease

Full Reference: src/assets/css/core/variables.css

---

✅ Phase 3 Achievements

• ✅ Zero :deep() in Components - All migrated to global CSS
• ✅ Zero Hardcoded CSS Colors - All use design tokens
• ✅ Centralized PrimeVue Styling - Single source in primevue-overrides.css
• ✅ Documented !important Usage - Clear acceptable use cases
• ✅ Build Successful - Zero breaking changes

---

🚫 Common Mistakes to Avoid

1. Duplicating Global Styles

❌ Wrong:

<!-- InvoicesView.vue -->
<style scoped>
:deep(.p-datatable .p-datatable-tbody > tr.invoice-paid) {
  background-color: var(--green-50); /* Already in App.vue! */
}
</style>

✅ Correct:

<!-- InvoicesView.vue -->
<style scoped>
/* Row styling defined globally in App.vue */
</style>

2. Overriding PrimeVue in Components

❌ Wrong:

<style scoped>
:deep(.p-button) {
  padding: 12px 24px;
}
</style>

✅ Correct: Add to assets/css/vendor/primevue-overrides.css instead.

3. Using Hardcoded Colors

❌ Wrong:

<style scoped>
.card {
  background: #ffffff;
  border: 1px solid #e5e7eb;
}
</style>

✅ Correct:

<style scoped>
.card {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
}
</style>

---

📚 Related Documentation

• Form Patterns: docs/FORM_TEMPLATE.md
• Design Tokens: src/assets/css/core/variables.css
• PrimeVue Overrides: src/assets/css/vendor/primevue-overrides.css
• Phase 3 Plan: features/phases/phase-3-primevue.md

---

Questions? Check the CSS Refactoring documentation in features/