service-finder/docs/UI_STANDARDS.md

# 🎨 Service Finder UI Design System v2.1

> **Audit Date:** 2026-07-28  
> **Scope:** `frontend_app/` Vue 3 + Tailwind CSS project  
> **Principle:** Every component must derive its visual properties from this document.  
> **Toolkit:** Tailwind CSS v3 custom theme + `main.css` utility components.

---

## 1. 🖌️ Color Palette

### 1.1 Brand Identity (from `tailwind.config.js` + SVG logo)

| Token | Hex | Tailwind Class | Usage |
|---|---|---|---|
| **sf-blue** | `#004B63` | `bg-sf-blue` / `text-sf-blue` | Primary headers, main CTAs, dashboard cards |
| **sf-accent** | `#008CA4` | `bg-sf-accent` / `text-sf-accent` | Hover states, secondary buttons, links |
| **sf-green** | `#70BC84` | `bg-sf-green` / `text-[#70BC84]` | Progress bars, success badges, positive states |
| **sf-wall** | `#B5DCE3` | `bg-sf-wall` | Light panels, background gradients |
| **logo-dark-blue** | `#306081` | `bg-[#306081]` | Plan card headers, logo primary |
| **logo-teal** | `#418890` | `bg-[#418890]` | Logo secondary elements |
| **logo-green** | `#79B085` | `bg-[#79B085]` | Logo leaf/green elements |

### 1.2 Semantic Colors

| Token | Hex | Tailwind Class | Meaning |
|---|---|---|---|
| **success / emerald** | `#10b981` | `bg-emerald-500` / `text-emerald-600` | Confirmation, active status, savings |
| **warning / amber** | `#f59e0b` | `bg-amber-400` / `text-amber-400` | Expiring soon (≤7 days), caution |
| **danger / red** | `#ef4444` | `bg-red-500` / `text-red-600` | Expired, full capacity, delete actions |
| **info / sky** | `#0284c7` | `bg-sky-600` | Subscription cards, neutral info |

### 1.3 Neutral & Background

| Token | Hex | Tailwind Class | Usage |
|---|---|---|---|
| **dark-bg** | `#04151F` | `bg-[#04151F]` | App body background |
| **dark-lighter** | `#0a2a40` | `bg-[#0a2a40]` | Gradient top |
| **white-solid** | `#ffffff` | `bg-white` | Content cards (light theme) |
| **white-95** | `rgba(255,255,255,0.95)` | `bg-white/95` | Semi-transparent card faces |
| **slate-50** | `#f8fafc` | `bg-slate-50` | Card inner sections (stats, inputs) |
| **slate-200** | `#e2e8f0` | `border-slate-200` | Card inner borders |
| **slate-500** | `#64748b` | `text-slate-500` | Secondary text on light cards |
| **slate-700** | `#334155` | `bg-slate-700` / `text-slate-700` | Header bars, primary text on light |
| **slate-800** | `#1e293b` | `text-slate-800` | Card body text color |

### 1.4 Gradient Presets

| Name | Tailwind | Usage |
|---|---|---|
| **sf-dark-bg** | `radial-gradient(...)` | `body` global background |
| **header-amber** | `bg-gradient-to-r from-amber-600 to-amber-700` | Wallet card header |
| **header-sky** | `bg-gradient-to-r from-sky-600 to-sky-700` | Subscription card header |
| **header-emerald** | `bg-gradient-to-r from-emerald-600 to-emerald-700` | Transactions card header |
| **header-violet** | `bg-gradient-to-r from-violet-600 to-violet-700` | Invoices card header |
| **header-green** (add-on) | `bg-gradient-to-r from-emerald-600 to-emerald-700` | Add-on card headers |
| **btn-premium** | `bg-gradient-to-r from-[#418890] to-[#70BC84]` | Premium buttons hover state |

---

## 2. 📐 Cards

### 2.1 Standard Card (Light Theme)

- **Radius:** Always `rounded-2xl` for cards
- **Shadow:** `shadow-[0_8px_30px_rgb(0,0,0,0.12)]` by default, `shadow-2xl` on hover
- **Hover:** `hover:-translate-y-3 hover:scale-[1.02]` — subtle lift + scale
- **Height:** `h-[350px]` fixed height standard; use `h-auto` for list cards
- **Background:** `bg-white/95` (semi-transparent white) for light theme cards
- **Body text color:** `text-slate-800` inside card bodies
- **Body padding:** `p-4` standard; `p-6` for "lg" variant
- **Header colors:** Use semantic gradients: amber=wallet, sky=subscription, emerald=transactions, violet=invoices

### 2.2 Dark / Glass Card

- Use `bg-white/5` or `bg-white/10` for glass effect
- Always add `backdrop-blur-md` for blur
- Border: `border-white/10` or `border-white/20`
- Text: `text-white/80` or `text-white/60` for secondary

### 2.3 BaseCard Component

Prefab component with `header`, default `body`, `footer` slots. See `BaseCard.vue`.

---

## 3. 🔘 Buttons

| Variant | Tailwind Classes |
|---|---|
| **btn-primary** | `px-4 py-2 bg-sf-blue text-white rounded-lg hover:bg-sf-accent transition-colors` |
| **btn-secondary** | `px-4 py-2 bg-sf-wall text-sf-blue rounded-lg hover:bg-sf-green hover:text-white` |
| **btn-premium** | `rounded-xl bg-white/10 px-6 py-3 font-bold text-white backdrop-blur-md border border-white/20` |
| **btn-card-cta** | `w-full text-center px-4 py-2.5 rounded-xl text-sm font-semibold shadow-md hover:shadow-lg active:scale-[0.98]` |
| **Disabled** | `bg-slate-400 cursor-not-allowed` |

---

## 4. 📝 Typography

- **Font:** `Inter, system-ui, sans-serif`
- **H1:** `text-3xl font-bold text-white`
- **H2:** `text-2xl font-bold text-white`
- **H3:** `text-lg font-bold text-slate-900`
- **H4:** `text-sm font-semibold text-slate-700 uppercase tracking-wider`
- **Body:** `text-sm text-slate-700` (light) / `text-sm text-white/60` (dark)
- **Small:** `text-xs text-slate-500`

---

## 5. 🪟 Modals

- Backdrop: `bg-black/60 backdrop-blur-sm`
- Close on backdrop click: `@click.self="$emit('close')"`
- Max height: `max-h-[90vh]`
- Transition: `modal-fade` 0.2s ease opacity
- Panel: `bg-white rounded-2xl shadow-2xl overflow-hidden flex flex-col`
- Header: colored bar with `text-white font-bold text-lg`
- Footer: `bg-slate-50 border-t border-slate-200`

---

## 6. 🧩 Add-on Card Specification (Phase 4)

The add-on cards follow the **same solid card pattern** as base plan cards with a **green-themed header** to visually distinguish them.

### 6.1 Classes

| Element | Classes |
|---|---|
| **Wrapper (selected)** | `bg-white/95 rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.12)] overflow-hidden border-emerald-500 ring-1 ring-emerald-500/50 transition-all duration-300 hover:-translate-y-2 hover:shadow-2xl` |
| **Wrapper (unselected)** | `bg-white/95 rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.12)] overflow-hidden border-slate-200 transition-all duration-300 hover:border-slate-400 hover:-translate-y-2 hover:shadow-2xl` |
| **Header** | `h-12 bg-gradient-to-r from-emerald-600 to-emerald-700 w-full shrink-0 flex items-center px-4` |
| **Header text** | `text-white font-bold text-sm tracking-wide` |
| **Body** | `p-4 flex flex-col h-full text-slate-800` |
| **Inner stat badges** | `bg-slate-50 text-slate-700` (match base plan stat boxes) |
| **Price (main)** | `text-xl font-bold text-slate-900` |
| **Price (small)** | `text-slate-500 text-xs` |
| **Toggle (selected)** | `w-full py-2 rounded-xl text-sm font-semibold bg-emerald-600 hover:bg-emerald-700 text-white` |
| **Toggle (unselected)** | `w-full py-2 rounded-xl text-sm font-semibold bg-slate-100 hover:bg-emerald-50 text-slate-700 hover:text-emerald-700 border border-slate-200 hover:border-emerald-300` |

### 6.2 What Changes from Current Glass Style

| Element | Current (broken) | Fix (target) |
|---|---|---|
| **Wrapper bg** | `bg-emerald-900/20` (glass, transparent on garage-bg) | `bg-white/95` (solid white, readable) |
| **Wrapper border** | `border-slate-700` (invisible) | `border-slate-200` (visible) |
| **Text color** | `text-white` (washes out on bg) | `text-slate-800` (solid dark on white) |
| **Secondary text** | `text-white/40` (illegible) | `text-slate-500` (readable) |
| **Toggle (unselected)** | `bg-white/10 text-white/80` (glass) | `bg-slate-100 text-slate-700 border border-slate-200` (solid) |
| **Header** | None (no header bar) | Green gradient header with add-on name |
| **Shadow** | None | `shadow-[0_8px_30px_rgb(0,0,0,0.12)]` |
| **Hover** | None | `hover:-translate-y-2 hover:shadow-2xl` |
| **Stat badges** | `bg-white/10 text-white/50` (invisible) | `bg-slate-50 text-slate-700` (same as base plans) |

---

## 7. ♿ Accessibility Checklist

- Minimum contrast ratio 4.5:1 for body text
- Focus rings on all interactive elements (`focus:ring-2 focus:ring-sf-accent`)
- `aria-label` on icon-only buttons
- Keyboard navigation for modals (Escape to close)

---

*End of UI Design System v2.1*