scan-wave/styling.md

# ScanWave Styling Guide

This document outlines the design system and styling conventions used in the ScanWave application. Use this as a reference when creating new applications with similar visual design.

## Table of Contents
- [Color Palette](#color-palette)
- [Typography](#typography)
- [Layout Patterns](#layout-patterns)
- [Component Patterns](#component-patterns)
- [Form Elements](#form-elements)
- [Buttons](#buttons)
- [Cards and Containers](#cards-and-containers)
- [Navigation](#navigation)
- [Tables](#tables)
- [Loading States](#loading-states)
- [Toast Notifications](#toast-notifications)
- [Responsive Design](#responsive-design)

## Color Palette

### Primary Colors
- **Blue**: Primary action color
  - `bg-blue-600` / `text-blue-600` - Primary buttons, links
  - `bg-blue-700` / `text-blue-700` - Hover states
  - `bg-blue-50` / `text-blue-800` - Info notifications
  - `border-blue-600` / `focus:ring-blue-600` - Focus states

### Gray Scale
- **Text Colors**:
  - `text-gray-900` - Primary text (headings, important content)
  - `text-gray-700` - Secondary text (labels, descriptions)
  - `text-gray-500` - Tertiary text (metadata, placeholders)
  
- **Background Colors**:
  - `bg-white` - Main content backgrounds
  - `bg-gray-50` - Page backgrounds, subtle sections
  - `bg-gray-100` - Disabled form fields
  - `bg-gray-200` - Loading placeholders

- **Border Colors**:
  - `border-gray-300` - Standard borders (cards, inputs)
  - `border-gray-200` - Subtle borders (table rows)

### Status Colors
- **Success**: `bg-green-50 text-green-800 border-green-300`
- **Warning**: `bg-yellow-50 text-yellow-800 border-yellow-300`
- **Error**: `bg-red-50 text-red-800 border-red-300`
- **Info**: `bg-blue-50 text-blue-800 border-blue-300`

### Accent Colors
- **Red**: `text-red-600` / `hover:text-red-700` - Danger actions (sign out)
- **Green**: `text-green-600` - Success indicators

## Typography

### Headings
```html
<!-- Page titles -->
<h1 class="mb-6 text-2xl font-bold text-center text-gray-800">Page Title</h1>

<!-- Section headings -->
<h2 class="mb-4 text-xl font-semibold text-gray-900">Section Title</h2>
<h2 class="mb-2 text-lg font-semibold text-gray-900">Subsection Title</h2>
```

### Body Text
```html
<!-- Primary text -->
<p class="text-sm text-gray-900">Important content</p>

<!-- Secondary text -->
<p class="text-sm text-gray-700">Regular content</p>
<p class="text-sm leading-relaxed text-gray-700">Longer content blocks</p>

<!-- Metadata/labels -->
<span class="text-sm font-medium text-gray-500">Label</span>
<span class="text-sm font-medium text-gray-700">Form Label</span>

<!-- Small text -->
<p class="text-xs text-gray-500">Helper text</p>
```

### Text Utilities
- **Font Weight**: `font-bold`, `font-semibold`, `font-medium`
- **Text Alignment**: `text-center`, `text-left`
- **Line Height**: `leading-relaxed` for longer text blocks

## Layout Patterns

### Container Pattern
```html
<div class="container mx-auto max-w-2xl bg-white p-4">
  <!-- Content -->
</div>
```

### Grid Layouts
```html
<!-- Dashboard grid -->
<div class="grid grid-cols-1 gap-6 lg:grid-cols-3">
  <div class="lg:col-span-1"><!-- Sidebar --></div>
  <div class="lg:col-span-2"><!-- Main content --></div>
</div>

<!-- Two-column responsive -->
<dl class="grid grid-cols-1 gap-4 sm:grid-cols-2">
  <!-- Items -->
</dl>
```

### Spacing
- **Standard spacing**: `space-y-6`, `gap-6` - Between major sections
- **Component spacing**: `mb-4`, `mt-6`, `p-6` - Around components
- **Small spacing**: `gap-3`, `mb-2`, `mt-2` - Between related elements
- **Container padding**: `p-4`, `p-6` - Internal container spacing

## Component Patterns

### Card Structure
```html
<div class="rounded-lg border border-gray-300 bg-white p-6">
  <div class="mb-4 flex justify-between items-center">
    <h2 class="text-xl font-semibold text-gray-900">Title</h2>
    <!-- Actions -->
  </div>
  <!-- Content -->
</div>
```

### Avatar/Profile Picture
```html
<div class="flex h-24 w-24 items-center justify-center rounded-full bg-gray-200 text-4xl font-bold text-gray-600">
  {initials}
</div>
```

## Form Elements

### Input Fields
```html
<!-- Standard input -->
<input 
  class="w-full rounded-md border border-gray-300 px-3 py-2 focus:border-blue-600 focus:ring-blue-600 focus:outline-none"
  type="text"
/>

<!-- Disabled input -->
<input 
  class="w-full rounded-md border border-gray-300 px-3 py-2 disabled:cursor-default disabled:bg-gray-100"
  disabled
/>
```

### Textarea
```html
<textarea 
  class="w-full rounded-md border border-gray-300 px-3 py-2 focus:border-blue-600 focus:ring-blue-600 focus:outline-none"
  rows="6"
></textarea>
```

### Select Dropdown
```html
<select class="w-full rounded-md border border-gray-300 p-2 focus:ring-2 focus:ring-blue-600 focus:outline-none">
  <option>Option</option>
</select>
```

### Form Labels
```html
<label class="block mb-1 text-sm font-medium text-gray-700">Label Text</label>
```

## Buttons

### Primary Buttons
```html
<button class="rounded-md bg-blue-600 px-4 py-2 text-white font-medium transition hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-50">
  Primary Action
</button>
```

### Secondary/Outline Buttons
```html
<button class="rounded-md border border-gray-300 bg-white px-4 py-2 text-gray-700 font-medium transition hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50">
  Secondary Action
</button>
```

### Danger/Red Buttons
```html
<button class="rounded-md bg-red-600 px-4 py-2 text-white font-medium transition hover:bg-red-700">
  Danger Action
</button>
```

### Button States
- **Loading**: Replace text with "Loading..." or "Saving..."
- **Disabled**: `disabled:cursor-not-allowed disabled:opacity-50`

## Cards and Containers

### Standard Card
```html
<div class="mb-6 rounded-md border border-gray-300 bg-white p-6">
  <!-- Content -->
</div>
```

### Card with Header Actions
```html
<div class="rounded-md border border-gray-300 bg-white p-6">
  <div class="mb-4 flex justify-between items-center">
    <h2 class="text-xl font-semibold text-gray-900">Title</h2>
    <div class="flex gap-3">
      <!-- Action buttons -->
    </div>
  </div>
  <!-- Content -->
</div>
```

## Navigation

### Top Navigation
```html
<nav class="border-b border-gray-300 bg-gray-50 p-4 text-gray-900">
  <div class="container mx-auto max-w-2xl">
    <div class="flex items-center justify-between">
      <a href="/" class="text-lg font-bold">App Name</a>
      <ul class="flex space-x-4">
        <li><a href="/page" class="hover:text-blue-600 transition">Page</a></li>
      </ul>
    </div>
  </div>
</nav>
```

## Tables

### Standard Table
```html
<div class="overflow-x-auto">
  <table class="w-full">
    <thead class="bg-gray-50">
      <tr>
        <th class="px-4 py-3 text-left text-sm font-medium text-gray-700">Header</th>
      </tr>
    </thead>
    <tbody>
      <tr class="border-b border-gray-200 hover:bg-gray-50">
        <td class="px-4 py-3 text-sm text-gray-900">Data</td>
      </tr>
    </tbody>
  </table>
</div>
```

### Definition List (Key-Value Pairs)
```html
<dl class="grid grid-cols-1 gap-4 sm:grid-cols-2">
  <div class="sm:col-span-1">
    <dt class="text-sm font-medium text-gray-500">Key</dt>
    <dd class="mt-1 text-sm font-semibold text-gray-900">Value</dd>
  </div>
</dl>
```

## Loading States

### Skeleton Loading
```html
<div class="space-y-4">
  <div class="h-4 animate-pulse rounded-md bg-gray-200"></div>
  <div class="h-10 w-full animate-pulse rounded-md bg-gray-200"></div>
</div>
```

### Loading Spinner
```html
<div class="flex h-10 items-center justify-center">
  <div class="h-5 w-5 animate-spin rounded-full border-2 border-gray-300 border-t-blue-600"></div>
</div>
```

## Toast Notifications

### Toast Container Structure
```html
<div class="rounded-md border p-4 shadow-lg w-full {colorClasses}">
  <div class="flex items-start gap-3">
    <div class="flex-shrink-0">
      <!-- Icon -->
    </div>
    <div class="flex-1">
      <p class="text-sm font-medium">{message}</p>
    </div>
    <button class="flex-shrink-0">
      <!-- Close button -->
    </button>
  </div>
</div>
```

### Toast Color Variants
- **Success**: `border-green-300 bg-green-50 text-green-800`
- **Warning**: `border-yellow-300 bg-yellow-50 text-yellow-800`
- **Info**: `border-blue-300 bg-blue-50 text-blue-800`
- **Error**: `border-red-300 bg-red-50 text-red-800`

## Responsive Design

### Breakpoints
- **Mobile First**: Default styles for mobile
- **sm**: `sm:` prefix for small screens and up
- **lg**: `lg:` prefix for large screens and up

### Common Responsive Patterns
```html
<!-- Responsive grid -->
<div class="grid grid-cols-1 gap-6 lg:grid-cols-3">

<!-- Responsive padding -->
<div class="p-4 sm:p-6">

<!-- Responsive columns -->
<div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
```

## Common Utility Classes

### Flexbox
- `flex items-center justify-between` - Header with title and actions
- `flex items-start gap-3` - Toast notification layout
- `flex flex-col` - Vertical stacking
- `flex-grow` - Fill available space

### Positioning
- `relative` / `absolute` - Positioning contexts
- `fixed bottom-6 left-1/2 -translate-x-1/2` - Centered fixed positioning

### Visibility
- `hidden` / `block` - Show/hide elements
- `overflow-hidden` - Clip content
- `overflow-x-auto` - Horizontal scroll for tables

### Borders and Shadows
- `rounded-md` - Standard border radius for all components
- `rounded-full` - Circular elements (avatars)
- `shadow-lg` - Toast notifications and elevated elements
- `shadow-none` - Remove default shadows when needed

## Design Tokens Summary

### Standardized Values
- **Border Radius**: `rounded-md` (6px) for all rectangular components
- **Border Colors**: `border-gray-300` (standard), `border-gray-200` (subtle)
- **Focus States**: `focus:border-blue-600 focus:ring-blue-600`
- **Spacing**: `gap-4` (1rem), `gap-6` (1.5rem), `p-4` (1rem), `p-6` (1.5rem)
- **Font Weights**: `font-medium` for buttons and emphasis, `font-semibold` for headings, `font-bold` for titles
- **Status Border**: All status colors use `-300` shade for borders (e.g., `border-green-300`)

This styling guide captures the core design patterns used throughout the ScanWave application. Follow these conventions to maintain visual consistency across your new applications.