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](./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**

```vue
<!-- ❌ 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](./FORM_TEMPLATE.md)

```vue
<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](./CSS_PATTERNS.md#metric-card)

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

---

### Task: Style a PrimeVue Component

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

**Always do this:**
```css
/* ✅ 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:**

```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: 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](./CSS_PATTERNS.md)** - All available patterns
2. **[COMPONENT_STYLING.md](./COMPONENT_STYLING.md)** - When to use global vs scoped
3. **[FORM_TEMPLATE.md](./FORM_TEMPLATE.md)** - Form standard template
4. **[DESIGN_TOKENS.md](./DESIGN_TOKENS.md)** - Available CSS variables
5. **[STYLING_GUIDELINES.md](./STYLING_GUIDELINES.md)** - Best practices

**Quick References:**

- Need a button? → [CSS_PATTERNS.md#button-patterns](./CSS_PATTERNS.md#button-patterns)
- Need a card? → [CSS_PATTERNS.md#card-patterns](./CSS_PATTERNS.md#card-patterns)
- Need a form? → [FORM_TEMPLATE.md](./FORM_TEMPLATE.md)
- Need spacing? → [DESIGN_TOKENS.md#spacing-scale](./DESIGN_TOKENS.md#spacing-scale)
- Need colors? → [DESIGN_TOKENS.md#color-palette](./DESIGN_TOKENS.md#color-palette)

---

## Common Mistakes & Fixes

### ❌ Mistake #1: Not checking patterns first

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

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

```vue
<!-- 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](./CSS_PATTERNS.md)
- **How to style?** Check [COMPONENT_STYLING.md](./COMPONENT_STYLING.md)
- **What tokens?** Check [DESIGN_TOKENS.md](./DESIGN_TOKENS.md)
- **Still stuck?** Ask in #frontend-css channel

---

## Next Steps

1. ✅ Read this onboarding (you're here!)
2. ✅ Browse [CSS_PATTERNS.md](./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 🚀