roa2web-service-auto/docs/STYLING_GUIDELINES.md

Styling Best Practices & Guidelines

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

---

Quick Reference

Golden Rules

1. ✅ Use global patterns first - Check CSS_PATTERNS.md
2. ✅ Use design tokens - var(--color-primary) not #2563eb
3. ❌ No :deep() in components - PrimeVue styles in vendor/primevue-overrides.css
4. ❌ No duplication - Write CSS once, use everywhere
5. ❌ No hardcoded values - Use tokens for all values

---

Design Token Usage

Colors

/* ✅ GOOD */
color: var(--color-primary);
background: var(--color-bg);
border-color: var(--color-border);

/* ❌ BAD */
color: #2563eb;
background: #ffffff;
border-color: #e5e7eb;

Spacing

/* ✅ GOOD */
padding: var(--space-md);
margin: var(--space-lg);
gap: var(--space-sm);

/* ❌ BAD */
padding: 16px;
margin: 24px;
gap: 8px;

Typography

/* ✅ GOOD */
font-size: var(--text-base);
font-weight: var(--font-semibold);
line-height: var(--leading-normal);

/* ❌ BAD */
font-size: 16px;
font-weight: 600;
line-height: 1.5;

---

File Organization

src/assets/css/
├── core/              # Foundation (DO NOT MODIFY without team approval)
│   ├── variables.css  # Base CSS variables
│   ├── tokens.css     # Extended design tokens
│   ├── reset.css      # CSS reset
│   └── typography.css # Font definitions
│
├── patterns/          # Reusable interactive patterns
│   ├── interactive.css # Spinners, trends, collapse
│   ├── dashboard.css   # Page headers, metrics, breakdowns
│   └── animations.css  # Transitions & animations
│
├── components/        # Component library
│   ├── cards.css      # All card variants
│   ├── buttons.css    # All button styles
│   ├── forms.css      # Form patterns
│   ├── tables.css     # Table styles
│   └── stats.css      # Statistics displays
│
├── layout/            # Page structure
│   ├── containers.css # Content containers
│   ├── grid.css       # Grid system
│   └── navigation.css # Navigation components
│
├── utilities/         # Utility classes
│   ├── colors.css     # Color utilities
│   ├── text.css       # Typography utilities
│   ├── spacing.css    # Margin/padding utilities
│   ├── flex.css       # Flexbox utilities
│   └── display.css    # Display utilities
│
└── vendor/            # Third-party overrides
    └── primevue-overrides.css # PrimeVue customization

---

Naming Conventions

Classes

/* Component classes: .component-name */
.card { }
.btn { }
.form-input { }

/* Variant classes: .component-variant */
.btn-primary { }
.btn-secondary { }
.card-elevated { }

/* State classes: .state */
.active { }
.disabled { }
.invalid { }

/* Utility classes: .utility-value */
.text-center { }
.flex { }
.mt-lg { }

BEM (When Needed)

/* Block__Element--Modifier */
.metric-card { }              /* Block */
.metric-card__header { }      /* Element */
.metric-card--compact { }     /* Modifier */

---

Performance

CSS Bundle Optimization

/* ✅ GOOD: Group related selectors */
.btn,
.btn-primary,
.btn-secondary {
  display: inline-flex;
  align-items: center;
}

/* ❌ BAD: Repeat properties */
.btn { display: inline-flex; align-items: center; }
.btn-primary { display: inline-flex; align-items: center; }
.btn-secondary { display: inline-flex; align-items: center; }

Animations

/* ✅ GOOD: Use transform & opacity (GPU-accelerated) */
.card-hover:hover {
  transform: translateY(-2px);
  opacity: 0.9;
}

/* ❌ BAD: Animate layout properties */
.card-hover:hover {
  top: -2px;  /* Forces reflow */
  height: 110%;  /* Forces reflow */
}

---

Accessibility

Color Contrast (WCAG 2.1 AA)

/* ✅ GOOD: 4.5:1 contrast ratio */
color: var(--color-text);        /* #111827 on #ffffff = 16.9:1 */
background: var(--color-bg);

/* ✅ GOOD: Large text (18px+) needs 3:1 */
.heading {
  font-size: var(--text-xl);
  color: var(--color-text-secondary);  /* #6b7280 = 4.6:1 */
}

Focus States

/* ✅ GOOD: Visible focus indicator */
.btn:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* ❌ BAD: Removing focus */
.btn:focus {
  outline: none;  /* Never do this! */
}

Touch Targets (Mobile)

/* ✅ GOOD: Minimum 44x44px */
.btn {
  min-height: 44px;
  min-width: 44px;
  padding: var(--space-sm) var(--space-md);
}

---

Browser Compatibility

Supported Browsers

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Use Modern CSS

/* ✅ GOOD: Modern CSS features */
.grid {
  display: grid;
  gap: var(--space-md);
}

.card {
  aspect-ratio: 16 / 9;
}

/* ⚠️ If using very new features, check caniuse.com */

---

Testing

Before Committing

# 1. Build check
npm run build

# 2. Visual regression tests
npm run test:e2e

# 3. Check bundle size
ls -lh dist/assets/*.css

Manual Testing Checklist

• Desktop (1920x1080, 1366x768)
• Tablet (768x1024)
• Mobile (375x667, 414x896)
• Dark mode (if applicable)
• Print view (@media print)
• Keyboard navigation (Tab through elements)
• Screen reader (test with NVDA/JAWS)

---

Code Review Standards

CSS in PRs

Reviewers check for:

1. No duplication - Pattern exists in global CSS?
2. Design tokens - All values use var(--*)?
3. No :deep() - PrimeVue overrides in correct file?
4. Scoped CSS justified - < 50 lines & documented?
5. Responsive - Works on all breakpoints?
6. Accessible - Focus states, contrast ratios?
7. Performance - No layout thrashing animations?
8. Tested - Build passes, E2E tests pass?

---

Common Mistakes

❌ Mistake #1: Not Checking Pattern Library

<!-- Wrong: Recreating existing pattern -->
<style scoped>
.my-button {
  background: var(--color-primary);
  /* ... 20 lines duplicating btn class */
}
</style>

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

❌ Mistake #2: Hardcoded Values

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

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

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

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

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

---

Resources

• Pattern Library: CSS_PATTERNS.md
• Component Guidelines: COMPONENT_STYLING.md
• Form Template: FORM_TEMPLATE.md
• Design Tokens: DESIGN_TOKENS.md
• Onboarding: ONBOARDING_CSS.md

---

Last Updated: 2025-11-19 Version: 2.0.0 Maintained By: Frontend Team