roa2web-service-auto/docs/CSS_PATTERNS.md

ROA2WEB CSS Patterns Library

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

---

Table of Contents

1. Card Patterns
2. Form Patterns
3. Button Patterns
4. Table Patterns
5. Dashboard Patterns
6. Interactive Patterns
7. Layout Patterns
8. Utility Classes
9. Quick Reference

---

Overview

This document provides a comprehensive reference to all CSS patterns available in the ROA2WEB frontend application. All patterns are production-ready, tested, and follow our design system.

Key Principles

• ✅ Use global patterns first - Check this library before writing custom CSS
• ✅ Design tokens - Use CSS variables (var(--color-primary)) not hardcoded values
• ✅ Responsive by default - All patterns work on mobile
• ✅ Accessibility - WCAG 2.1 AA compliant
• ❌ No duplication - Never recreate existing patterns

---

Card Patterns

Basic Card

Standard card with optional header, body, and footer sections.

<div class="card">
  <div class="card-header">
    <h3>Card Title</h3>
  </div>
  <div class="card-body">
    <p>Card content goes here</p>
  </div>
  <div class="card-footer">
    <button class="btn btn-primary">Action</button>
  </div>
</div>

Variants:

• .card-compact - Reduced padding
• .card-minimal - No border/shadow
• .card-elevated - Higher shadow with hover lift
• .card-hover - Hover effect with border color change

Use Cases:

• Content containers
• Form wrappers
• Information blocks

---

Metric Card

Dashboard metric display with icon, value, and label.

<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">Total Sales</div>
  </div>
  <div class="metric-value">$125,430</div>
  <div class="trend trend-up">
    <i class="pi pi-arrow-up trend-icon"></i>
    +12.5% vs last month
  </div>
</div>

Structure:

• .metric-card - Base container
• .metric-header - Icon + label section
• .metric-icon - 40x40px icon container
• .metric-value - Large numeric display
• .metric-label - Uppercase description

Modifiers:

• .metric-value-lg - Larger font size (2.5rem)

Use Cases:

• KPI displays
• Financial metrics
• Statistics cards

---

Stats Card

Centered statistics display for key metrics.

<div class="stats-card">
  <span class="stats-value">1,234</span>
  <span class="stats-label">Active Users</span>
  <span class="stats-change positive">
    <i class="pi pi-arrow-up"></i> +5.2%
  </span>
</div>

Variants:

• .stats-card-mini - Compact size, left-aligned
• .stats-card-large - Extra padding
• .stats-value-large - Larger number display

Use Cases:

• Dashboard summaries
• Quick stats
• Report headers

---

KPI Card

Horizontal card with icon and key performance indicator.

<div class="kpi-card">
  <div class="kpi-icon bg-primary">
    <i class="pi pi-dollar"></i>
  </div>
  <div class="kpi-content">
    <div class="kpi-value">$45,231</div>
    <div class="kpi-label">Monthly Revenue</div>
  </div>
</div>

Use Cases:

• Performance indicators
• Business metrics
• Dashboard sidebar stats

---

Action Card

Interactive card that functions as a clickable button.

<div class="action-card">
  <div class="action-icon">
    <i class="pi pi-file-excel"></i>
  </div>
  <div class="action-title">Export Data</div>
  <div class="action-description">Download as Excel file</div>
</div>

Use Cases:

• Quick actions
• Navigation tiles
• Feature shortcuts

---

Status Card

Card with colored left border indicating status.

<div class="status-card success">
  <strong>Success!</strong> Your payment was processed.
</div>

<div class="status-card error">
  <strong>Error:</strong> Payment failed, please try again.
</div>

Variants:

• .success - Green border, success background
• .warning - Yellow border, warning background
• .error - Red border, error background
• .info - Blue border, info background

Use Cases:

• Alerts
• Notifications
• Status messages

---

Form Patterns

Standard Form

Complete form structure with validation.

<form @submit.prevent="handleSubmit" class="form">

  <!-- Single Field -->
  <div class="form-group">
    <label for="username" class="form-label required">Username</label>
    <input
      id="username"
      v-model="formData.username"
      type="text"
      class="form-input"
      :class="{ 'invalid': errors.username }"
      placeholder="Enter username"
    />
    <span v-if="errors.username" class="form-error">
      <i class="pi pi-exclamation-circle"></i>
      {{ errors.username }}
    </span>
    <span v-else class="form-help">
      Minimum 3 characters
    </span>
  </div>

  <!-- Horizontal Fields -->
  <div class="form-row">
    <div class="form-col">
      <div class="form-group">
        <label class="form-label">First Name</label>
        <input type="text" class="form-input" />
      </div>
    </div>
    <div class="form-col">
      <div class="form-group">
        <label class="form-label">Last Name</label>
        <input type="text" class="form-input" />
      </div>
    </div>
  </div>

  <!-- Actions -->
  <div class="form-actions">
    <button type="button" class="btn btn-secondary">Cancel</button>
    <button type="submit" class="btn btn-primary" :disabled="isSubmitting">
      <i v-if="isSubmitting" class="pi pi-spin pi-spinner"></i>
      Submit
    </button>
  </div>
</form>

Key Classes:

• .form - Base form container
• .form-group - Field wrapper
• .form-row - Horizontal field container
• .form-col - Column within row
• .form-label - Label text
• .form-label.required - Adds red asterisk
• .form-input - Text input
• .form-select - Select dropdown
• .form-textarea - Multi-line text
• .form-error - Error message (red)
• .form-help - Help text (gray)
• .form-actions - Button container

Validation States:

• .valid - Green border with checkmark icon
• .invalid - Red border with X icon

---

Input Sizes

<!-- Small -->
<input type="text" class="form-input form-input-sm" />

<!-- Default -->
<input type="text" class="form-input" />

<!-- Large -->
<input type="text" class="form-input form-input-lg" />

---

Input Group

Input with prefix/suffix addons.

<div class="input-group">
  <span class="input-group-addon">https://</span>
  <input type="text" class="form-input" placeholder="example.com" />
  <span class="input-group-addon">.com</span>
</div>

---

Search Form

Dedicated search input with icon.

<div class="search-form">
  <div class="search-input">
    <input type="search" class="form-input" placeholder="Search..." />
    <i class="pi pi-search search-icon"></i>
  </div>
  <button class="btn btn-primary">Search</button>
</div>

---

File Upload

Drag-and-drop file upload area.

<div class="file-upload">
  <input type="file" class="file-upload-input" />
  <label class="file-upload-label">
    <i class="pi pi-cloud-upload"></i>
    <span>Click to upload or drag and drop</span>
  </label>
</div>

---

Button Patterns

Button Variants

<!-- Primary (filled blue) -->
<button class="btn btn-primary">Primary</button>

<!-- Secondary (outlined gray) -->
<button class="btn btn-secondary">Secondary</button>

<!-- Outline (outlined blue) -->
<button class="btn btn-outline">Outline</button>

<!-- Ghost (transparent) -->
<button class="btn btn-ghost">Ghost</button>

<!-- Status variants -->
<button class="btn btn-success">Success</button>
<button class="btn btn-warning">Warning</button>
<button class="btn btn-error">Danger</button>

---

Button Sizes

<button class="btn btn-xs btn-primary">Extra Small</button>
<button class="btn btn-sm btn-primary">Small</button>
<button class="btn btn-md btn-primary">Medium (Default)</button>
<button class="btn btn-lg btn-primary">Large</button>
<button class="btn btn-xl btn-primary">Extra Large</button>

---

Icon Buttons

<!-- Button with icon + text -->
<button class="btn btn-primary">
  <i class="pi pi-plus"></i>
  Add Item
</button>

<!-- Icon-only button -->
<button class="btn btn-icon btn-primary">
  <i class="pi pi-pencil"></i>
</button>

<!-- Circle icon button -->
<button class="btn btn-circle btn-primary">
  <i class="pi pi-search"></i>
</button>

Sizes:

• .btn-icon-sm - 32x32px
• .btn-icon - 40x40px
• .btn-icon-lg - 48x48px

---

Button Groups

<div class="btn-group">
  <button class="btn btn-secondary">Left</button>
  <button class="btn btn-secondary">Middle</button>
  <button class="btn btn-secondary">Right</button>
</div>

---

Loading State

<button class="btn btn-primary btn-loading">
  Loading...
</button>

<!-- Or manually with spinner -->
<button class="btn btn-primary" disabled>
  <i class="pi pi-spin pi-spinner"></i>
  Processing...
</button>

---

Table Patterns

Note: Table styles are centralized in tables.css. Always use PrimeVue DataTable component with global styling.

Basic Table

<DataTable
  :value="data"
  class="p-datatable-sm"
  stripedRows
  :paginator="true"
>
  <Column field="name" header="Name" sortable></Column>
  <Column field="email" header="Email"></Column>
  <Column field="status" header="Status">
    <template #body="slotProps">
      <span :class="getStatusClass(slotProps.data.status)">
        {{ slotProps.data.status }}
      </span>
    </template>
  </Column>
</DataTable>

Global Row Classes (App.vue):

• .bank-row - Blue background for bank rows
• .cash-row - Green background for cash rows
• .invoice-paid - Light green for paid invoices
• .invoice-overdue - Light red for overdue invoices

---

Dashboard Patterns

Page Header

Standard page title with subtitle.

<header class="page-header">
  <h1 class="page-title">
    <i class="pi pi-chart-line"></i>
    Dashboard
  </h1>
  <p class="page-subtitle">
    Financial overview for {{ companyName }}
  </p>
</header>

---

Section Header

Section title with actions.

<div class="section-header">
  <h2 class="section-title">Recent Transactions</h2>
  <div class="section-controls">
    <button class="btn btn-secondary btn-sm">Filter</button>
    <button class="btn btn-primary btn-sm">Export</button>
  </div>
</div>

---

Metrics Row

Responsive grid for metric cards.

<div class="metrics-row">
  <div class="metric-card">...</div>
  <div class="metric-card">...</div>
</div>

Responsive:

• Desktop: 2 columns
• Tablet/Mobile: 1 column

---

Breakdown Pattern

Collapsible data breakdown.

<div class="breakdown-section">
  <div class="breakdown-header" @click="toggleBreakdown">
    <div class="breakdown-header-left">
      <i class="pi pi-angle-right breakdown-toggle" :class="{ expanded: isExpanded }"></i>
      <span class="breakdown-label">Details</span>
    </div>
    <span class="breakdown-value">$10,500</span>
  </div>

  <div v-if="isExpanded" class="breakdown-subitems">
    <div class="breakdown-subitem">
      <span class="breakdown-sublabel">Item 1</span>
      <span class="breakdown-subvalue">$5,000</span>
    </div>
    <div class="breakdown-subitem">
      <span class="breakdown-sublabel">Item 2</span>
      <span class="breakdown-subvalue">$5,500</span>
    </div>
  </div>
</div>

---

Interactive Patterns

Loading Spinner

Animated loading indicator.

<!-- Default (40px) -->
<div class="loading-spinner"></div>

<!-- Small (24px) -->
<div class="loading-spinner loading-spinner-sm"></div>

<!-- Large (56px) -->
<div class="loading-spinner loading-spinner-lg"></div>

---

Trend Indicator

Shows increase/decrease with icon.

<!-- Positive trend -->
<div class="trend trend-up">
  <i class="pi pi-arrow-up trend-icon"></i>
  +12.5%
</div>

<!-- Negative trend -->
<div class="trend trend-down">
  <i class="pi pi-arrow-down trend-icon"></i>
  -3.2%
</div>

<!-- Neutral trend -->
<div class="trend trend-neutral">
  <i class="pi pi-minus trend-icon"></i>
  0.0%
</div>

---

Collapsible Section

Expandable/collapsible content.

<div class="collapsible-header" @click="toggle">
  <span>Section Title</span>
  <i class="pi pi-angle-right collapse-icon" :class="{ expanded: isOpen }"></i>
</div>
<div v-if="isOpen">
  Content goes here
</div>

---

Sparkline Chart

Mini line chart for trends.

<div class="metric-sparkline">
  <div class="sparkline-header">
    <span class="sparkline-title">Last 7 Days</span>
    <span class="sparkline-value">$12,345</span>
  </div>
  <div class="sparkline-container">
    <canvas ref="sparklineCanvas" class="sparkline-canvas"></canvas>
  </div>
</div>

Sizes:

• Default: 60px height
• .sparkline-chart-lg: 150px height

---

Layout Patterns

Container

Page-level content container.

<div class="container">
  <!-- Content -->
</div>

Variants:

• .container-sm - Max-width 640px
• .container-md - Max-width 768px
• .container-lg - Max-width 1024px
• .container-xl - Max-width 1280px
• .container-full - Full width

---

Grid System

Responsive column layout.

<div class="grid grid-cols-3 gap-lg">
  <div class="col">Column 1</div>
  <div class="col">Column 2</div>
  <div class="col">Column 3</div>
</div>

Grid Columns:

• .grid-cols-1 to .grid-cols-12
• Responsive: .sm:grid-cols-2, .md:grid-cols-3, .lg:grid-cols-4

---

Utility Classes

Spacing

<!-- Margin -->
<div class="m-0">No margin</div>
<div class="m-sm">Small margin (0.5rem)</div>
<div class="m-md">Medium margin (1rem)</div>
<div class="m-lg">Large margin (1.5rem)</div>
<div class="m-xl">Extra large margin (2rem)</div>

<!-- Padding -->
<div class="p-0">No padding</div>
<div class="p-sm">Small padding</div>
<div class="p-md">Medium padding</div>
<div class="p-lg">Large padding</div>

<!-- Directional -->
<div class="mt-lg">Margin top</div>
<div class="mb-md">Margin bottom</div>
<div class="ml-sm">Margin left</div>
<div class="mr-xl">Margin right</div>
<div class="mx-auto">Horizontal center</div>
<div class="my-lg">Vertical margin</div>

---

Text Utilities

<!-- Sizes -->
<p class="text-xs">Extra small (0.75rem)</p>
<p class="text-sm">Small (0.875rem)</p>
<p class="text-base">Base (1rem)</p>
<p class="text-lg">Large (1.125rem)</p>
<p class="text-xl">Extra large (1.25rem)</p>
<p class="text-2xl">2X large (1.5rem)</p>
<p class="text-3xl">3X large (1.875rem)</p>
<p class="text-4xl">4X large (2.25rem)</p>

<!-- Alignment -->
<p class="text-left">Left aligned</p>
<p class="text-center">Center aligned</p>
<p class="text-right">Right aligned</p>

<!-- Weight -->
<p class="font-normal">Normal (400)</p>
<p class="font-medium">Medium (500)</p>
<p class="font-semibold">Semibold (600)</p>
<p class="font-bold">Bold (700)</p>

<!-- Transform -->
<p class="uppercase">UPPERCASE TEXT</p>
<p class="lowercase">lowercase text</p>
<p class="capitalize">Capitalized Text</p>

---

Color Utilities

<!-- Text Colors -->
<p class="text-primary">Primary color</p>
<p class="text-success">Success (green)</p>
<p class="text-warning">Warning (yellow)</p>
<p class="text-error">Error (red)</p>
<p class="text-info">Info (blue)</p>
<p class="text-muted">Muted (gray)</p>
<p class="text-secondary">Secondary (light gray)</p>

<!-- Background Colors -->
<div class="bg-primary">Primary background</div>
<div class="bg-success">Success background</div>
<div class="bg-warning">Warning background</div>
<div class="bg-error">Error background</div>

<!-- Light Backgrounds (10% opacity) -->
<div class="bg-primary-light">Light primary</div>
<div class="bg-success-light">Light success</div>
<div class="bg-warning-light">Light warning</div>
<div class="bg-error-light">Light error</div>

---

Flexbox Utilities

<!-- Flex Container -->
<div class="flex">Flex container</div>
<div class="inline-flex">Inline flex</div>

<!-- Direction -->
<div class="flex flex-row">Row (default)</div>
<div class="flex flex-col">Column</div>
<div class="flex flex-row-reverse">Row reverse</div>
<div class="flex flex-col-reverse">Column reverse</div>

<!-- Justify Content -->
<div class="flex justify-start">Start</div>
<div class="flex justify-center">Center</div>
<div class="flex justify-end">End</div>
<div class="flex justify-between">Space between</div>
<div class="flex justify-around">Space around</div>

<!-- Align Items -->
<div class="flex items-start">Start</div>
<div class="flex items-center">Center</div>
<div class="flex items-end">End</div>
<div class="flex items-stretch">Stretch</div>

<!-- Gap -->
<div class="flex gap-sm">Small gap</div>
<div class="flex gap-md">Medium gap</div>
<div class="flex gap-lg">Large gap</div>

---

Display Utilities

<div class="block">Block</div>
<div class="inline-block">Inline block</div>
<div class="inline">Inline</div>
<div class="hidden">Hidden</div>

<!-- Responsive -->
<div class="hidden md:block">Hidden mobile, visible tablet+</div>
<div class="block md:hidden">Visible mobile, hidden tablet+</div>

---

Quick Reference

Most Common Patterns

<!-- Card with content -->
<div class="card">
  <div class="card-body">Content</div>
</div>

<!-- Primary button -->
<button class="btn btn-primary">Action</button>

<!-- Form field -->
<div class="form-group">
  <label class="form-label">Label</label>
  <input type="text" class="form-input" />
</div>

<!-- Loading spinner -->
<div class="loading-spinner"></div>

<!-- Success text -->
<p class="text-success font-semibold">Success message</p>

<!-- Flex row with spacing -->
<div class="flex items-center gap-md">
  <span>Item 1</span>
  <span>Item 2</span>
</div>

---

Color Shortcuts

Purpose	Class	Color
Primary action	.text-primary .bg-primary	Blue (#2563eb)
Success/Positive	.text-success .bg-success	Green (#059669)
Warning/Caution	.text-warning .bg-warning	Yellow (#d97706)
Error/Danger	.text-error .bg-error	Red (#dc2626)
Info/Neutral	.text-info .bg-info	Cyan (#0891b2)

---

Spacing Scale

Token	Size	Use Case
var(--space-xs)	0.25rem (4px)	Tight spacing
var(--space-sm)	0.5rem (8px)	Default gaps
var(--space-md)	1rem (16px)	Component padding
var(--space-lg)	1.5rem (24px)	Section padding
var(--space-xl)	2rem (32px)	Page margins
var(--space-2xl)	3rem (48px)	Large separations
var(--space-3xl)	4rem (64px)	Hero sections

---

Font Sizes

Class	Size	Use Case
.text-xs	0.75rem (12px)	Tiny labels
.text-sm	0.875rem (14px)	Small text
.text-base	1rem (16px)	Body text
.text-lg	1.125rem (18px)	Emphasized text
.text-xl	1.25rem (20px)	Small headings
.text-2xl	1.5rem (24px)	Headings
.text-3xl	1.875rem (30px)	Large headings
.text-4xl	2.25rem (36px)	Page titles

---

Browser Support

All patterns support:

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

---

Performance Notes

• CSS bundle size: 366.42 kB (51.31 kB gzipped)
• All patterns use design tokens for consistency
• Animations use transform and opacity for GPU acceleration
• No unused patterns in production build

---

Need Help?

• Pattern not listed? Check src/assets/css/ directories
• Custom requirement? Consult Component Styling Guidelines
• New pattern needed? Follow Styling Guidelines
• Questions? Ask in #frontend-css channel

---

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