roa2web-service-auto/docs/ONBOARDING_CSS.md

CSS System Onboarding Guide

Welcome to ROA2WEB CSS Architecture! Version: 2.0.0 | Updated: 2025-11-19

---

Quick Start (5 Minutes)

1. Understand the Structure

src/assets/css/
├── core/          # Design tokens (colors, spacing, typography)
├── components/    # Reusable UI (buttons, forms, cards)
├── patterns/      # Interactive patterns (spinners, trends)
├── layout/        # Page structure (containers, grid)
├── utilities/     # Utility classes (colors, spacing, flex)
└── vendor/        # PrimeVue overrides

2. Golden Rules

✅ Use global patterns first (check docs/CSS_PATTERNS.md)
✅ Use design tokens (var(--color-primary) not #2563eb)
❌ Never use :deep() in components (PrimeVue → vendor/)
❌ Never duplicate CSS (write once, use everywhere)
❌ Never hardcode values (tokens for everything)

3. Your First Component (10 Minutes)

Before writing ANY CSS:

1. Check CSS_PATTERNS.md
2. Search existing code: grep -r "pattern-name" src/assets/css/
3. If it exists → use it. If not → continue reading.

Example: Creating a Card

<!-- ❌ DON'T DO THIS -->
<template>
  <div class="my-card">Content</div>
</template>

<style scoped>
.my-card {
  background: white;
  border: 1px solid #e5e7eb;
  padding: 24px;
  border-radius: 8px;
}
</style>

<!-- ✅ DO THIS -->
<template>
  <div class="card">
    <div class="card-body">Content</div>
  </div>
</template>

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

---

Decision Tree (30 Seconds)

Need to style something?
↓
Does this pattern exist? → YES → Use global CSS
↓ NO
Is this a form/button/card? → YES → Use global CSS (forms.css, buttons.css, cards.css)
↓ NO
Is this PrimeVue? → YES → Edit vendor/primevue-overrides.css
↓ NO
Truly component-specific? → YES → Scoped CSS OK (keep < 50 lines)
↓ NO
Extract to global pattern

---

Common Tasks

Task: Add a New Form

Template: docs/FORM_TEMPLATE.md

<template>
  <form @submit.prevent="handleSubmit" class="form">
    <div class="form-group">
      <label for="field" class="form-label required">Label</label>
      <input id="field" v-model="data.field" class="form-input" />
      <span v-if="errors.field" class="form-error">{{ errors.field }}</span>
    </div>

    <div class="form-actions">
      <button type="button" class="btn btn-secondary">Cancel</button>
      <button type="submit" class="btn btn-primary">Submit</button>
    </div>
  </form>
</template>

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

---

Task: Create a Dashboard Card

Pattern: CSS_PATTERNS.md#metric-card

<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! Global patterns handle everything */
</style>

---

Task: Style a PrimeVue Component

Never do this:

<!-- ❌ NEVER -->
<style scoped>
:deep(.p-inputtext) {
  border: 2px solid blue !important;
}
</style>

Always do this:

/* ✅ Edit src/assets/css/vendor/primevue-overrides.css */
.p-inputtext {
  border: 2px solid var(--color-primary);
  padding: var(--space-md);
}

---

Task: Add Custom Component Layout

Only if truly unique:

<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: Side-by-side charts
 * Reason: This layout is unique to this component and won't be reused
 */
.dual-chart-layout {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: var(--space-md);
}

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

---

Code Review Checklist

Before submitting your PR:

[ ] Checked CSS_PATTERNS.md first
[ ] No duplicate patterns
[ ] Design tokens used (no hardcoded values)
[ ] No :deep() in components
[ ] No form/button/card base styles
[ ] Scoped CSS < 50 lines (if any)
[ ] Build passes: npm run build
[ ] Tests pass: npm run test:e2e
[ ] Responsive tested (375px, 768px, 1920px)

---

Resources

Read these (in order):

1. CSS_PATTERNS.md - All available patterns
2. COMPONENT_STYLING.md - When to use global vs scoped
3. FORM_TEMPLATE.md - Form standard template
4. DESIGN_TOKENS.md - Available CSS variables
5. STYLING_GUIDELINES.md - Best practices

Quick References:

• Need a button? → CSS_PATTERNS.md#button-patterns
• Need a card? → CSS_PATTERNS.md#card-patterns
• Need a form? → FORM_TEMPLATE.md
• Need spacing? → DESIGN_TOKENS.md#spacing-scale
• Need colors? → DESIGN_TOKENS.md#color-palette

---

Common Mistakes & Fixes

❌ Mistake #1: Not checking patterns first

<!-- Wrong: Recreating button -->
<style scoped>
.submit-btn {
  background: #2563eb;
  color: white;
  padding: 0.5rem 1rem;
}
</style>

<!-- Correct: Use existing -->
<button class="btn btn-primary">Submit</button>

❌ Mistake #2: Hardcoded values

/* Wrong */
color: #111827;
padding: 16px;
border-radius: 8px;

/* Correct */
color: var(--color-text);
padding: var(--space-md);
border-radius: var(--radius-md);

❌ Mistake #3: Using :deep() for PrimeVue

<!-- Wrong: In component -->
<style scoped>
:deep(.p-dropdown) {
  border: 2px solid blue;
}
</style>

<!-- Correct: In vendor/primevue-overrides.css -->

---

Getting Help

• Pattern exists? Check CSS_PATTERNS.md
• How to style? Check COMPONENT_STYLING.md
• What tokens? Check DESIGN_TOKENS.md
• Still stuck? Ask in #frontend-css channel

---

Next Steps

1. ✅ Read this onboarding (you're here!)
2. ✅ Browse CSS_PATTERNS.md for 10 minutes
3. ✅ Try creating a simple component
4. ✅ Get your first PR reviewed
5. ✅ Start building!

---

Last Updated: 2025-11-19 Version: 2.0.0 Maintained By: Frontend Team Time to productivity: < 30 minutes 🚀