# Mobile Responsive Design Specifications

> **Mobile-First Design Guide**
>
> Breakpoint: `< 640px` (sm in Tailwind)

## 📱 Overview

**Target Devices**:
- iPhone 12/13/14: 390px width
- iPhone SE: 375px width
- Android phones: 360px - 414px width

**Orientation**: Portrait (primary), Landscape (secondary)

**Last Updated**: 2026-01-04

---

## 🎯 Mobile Design Principles

### 1. Touch-First Interaction
- Minimum touch target: `44x44px` (Apple HIG)
- Recommended: `48x48px` (Material Design)
- Spacing between touchable elements: `8px` minimum

### 2. Thumb Zone Optimization
- Primary actions: Bottom center (easy reach)
- Secondary actions: Top corners
- Avoid: Middle edges (hard to reach)

### 3. Content Priority
- Show essential content only
- Progressive disclosure for details
- Reduce visual clutter

### 4. Performance
- Optimize images for mobile
- Minimize animations
- Fast load times (< 2s)

---

## 📋 Auth Pages - Mobile Specifications

### Login Page (`/login`)

#### Layout

**Container**:
```css
width: 100vw;
min-height: 100vh;
padding: 16px; /* Reduced from 32px */
background: #15202b;
```

**Form Container**:
```css
width: 100%;
max-width: 100%; /* Remove 448px limit */
padding: 24px; /* Reduced from 32px */
margin: auto;
```

**Vertical Spacing**:
- Logo to heading: `16px` (reduced from 24px)
- Heading to form: `20px` (reduced from 24px)
- Between inputs: `12px` (reduced from 16px)
- Form to button: `20px` (reduced from 24px)

#### Typography

**Heading**:
```css
font-size: 28px; /* Reduced from 36px */
line-height: 1.2;
margin-bottom: 8px;
```

**Subheading**:
```css
font-size: 14px; /* Same */
line-height: 1.4;
```

**Input Labels**:
```css
font-size: 14px;
margin-bottom: 6px;
```

**Input Text**:
```css
font-size: 16px; /* Must be 16px to prevent zoom on iOS */
```

#### Form Elements

**Input Fields**:
```css
height: 48px; /* Increased from 44px for better touch */
padding: 12px 16px;
border-radius: 8px;
font-size: 16px; /* Prevent iOS zoom */
```

**Submit Button**:
```css
height: 52px; /* Increased from 48px */
width: 100%;
font-size: 16px;
border-radius: 8px;
```

**Links**:
```css
min-height: 44px; /* Touch target */
padding: 8px 0;
display: inline-block;
```

**Checkbox**:
```css
width: 24px; /* Increased from 20px */
height: 24px;
margin-right: 8px;
```

#### Theme/Language Controls

**Position**:
```css
position: fixed;
top: 16px; /* Reduced from 24px */
right: 16px;
z-index: 50;
```

**Size**:
```css
width: 40px;
height: 40px;
gap: 8px;
```

#### Screenshot Layout
![Mobile Login](../../../public/design/mockups/mobile-login-layout.png)
*TODO: Add annotated screenshot*

---

### Register Page (`/register`)

**Same as Login with additions**:

#### Password Strength Indicator

**Bars**:
```css
height: 4px; /* Reduced from 6px */
width: 100%;
gap: 4px;
border-radius: 2px;
```

**Text**:
```css
font-size: 12px;
margin-top: 4px;
```

#### Terms Checkbox

**Hit Area**:
```css
min-height: 44px;
padding: 8px 0;
```

**Text**:
```css
font-size: 13px; /* Slightly smaller */
line-height: 1.5;
```

#### Screenshot
![Mobile Register](../../../public/design/mockups/mobile-register-layout.png)
*TODO: Add screenshot*

---

### Forgot Password Page (`/forgot-password`)

**Same mobile specs as Login**

#### Success State

**Message Box**:
```css
padding: 16px;
border-radius: 8px;
margin-bottom: 16px;
```

#### Screenshot
![Mobile Forgot Password](../../../public/design/mockups/mobile-forgot-password.png)
*TODO: Add screenshot*

---

## 📐 Grid & Spacing

### 8-Point Grid (Mobile Adjusted)

**Base unit**: 4px

**Common spacing**:
- Extra small: `4px` (spacing-1)
- Small: `8px` (spacing-2)
- Medium: `12px` (spacing-3)
- Default: `16px` (spacing-4)
- Large: `20px` (spacing-5)
- Extra large: `24px` (spacing-6)

**Container Padding**:
- Side padding: `16px` (px-4)
- Top/bottom: `16px` (py-4)

---

## 🎨 Typography Scale (Mobile)

| Element | Size | Weight | Line Height | Letter Spacing |
|---------|------|--------|-------------|----------------|
| H1 | 28px | 800 | 1.2 | -0.02em |
| H2 | 24px | 700 | 1.25 | -0.01em |
| H3 | 20px | 600 | 1.3 | 0 |
| Body | 16px | 400 | 1.5 | 0 |
| Small | 14px | 400 | 1.5 | 0 |
| Tiny | 12px | 400 | 1.4 | 0 |

**Important**: All input fields MUST use `font-size: 16px` to prevent iOS auto-zoom.

---

## 🔘 Interactive Elements

### Touch Targets

**Minimum Sizes**:
- Buttons: `48x48px` or `100% width x 52px`
- Links: `44px` min-height
- Checkboxes: `24x24px`
- Radio buttons: `24x24px`
- Toggle switches: `52x32px`

**Spacing**:
- Between buttons: `12px`
- Button to text: `8px`
- Icon to text: `8px`

### Button Variations

**Primary Button (Sign In)**:
```css
width: 100%;
height: 52px;
font-size: 16px;
font-weight: 600;
border-radius: 8px;
```

**Secondary Button** (if needed):
```css
width: 100%;
height: 48px;
font-size: 15px;
font-weight: 500;
```

**Link Button**:
```css
min-height: 44px;
padding: 10px 0;
display: inline-block;
```

---

## ⌨️ Virtual Keyboard Handling

### iOS Safari

**Issue**: Keyboard covers bottom of viewport

**Solutions**:

1. **Input Focus**:
```javascript
// Scroll input into view
input.scrollIntoView({ behavior: 'smooth', block: 'center' });
```

2. **Form Position**:
```css
/* Keep submit button visible */
.form-container {
  margin-bottom: 300px; /* Space for keyboard */
}
```

3. **Viewport Units**:
```css
/* Avoid 100vh on mobile */
min-height: 100dvh; /* Dynamic viewport height */
```

### Android

**Input Types**:
```html
<!-- Show correct keyboard -->
<input type="email" inputmode="email" />
<input type="tel" inputmode="tel" />
<input type="number" inputmode="numeric" />
```

---

## 🖼️ Images & Assets

### Icon Sizes (Mobile)

| Element | Size | Format |
|---------|------|--------|
| Logo | 40x40px | SVG |
| Form icons | 20x20px | SVG |
| Success/Error icons | 20x20px | SVG |
| Menu icons | 24x24px | SVG |

### Image Export

**Density**:
- Standard: @1x
- Retina: @2x
- Super Retina: @3x

**Format**:
- Icons: SVG (preferred)
- Photos: WebP or JPEG
- Transparency: PNG

---

## 🎭 Animations (Mobile)

### Reduced Motion

**Respect User Preference**:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

### Performance

**Avoid**:
- Heavy blur effects (< 8px ok)
- Too many simultaneous animations
- Animating `width`, `height`, `top`, `left`

**Use**:
- `transform` (translateY, scale)
- `opacity`
- Hardware acceleration: `will-change: transform`

### Transitions

**Fast**:
```css
transition: all 150ms cubic-bezier(0.4, 0.0, 0.2, 1);
```

**Normal**:
```css
transition: all 300ms cubic-bezier(0.4, 0.0, 0.2, 1);
```

---

## 📊 Performance Targets (Mobile)

### Load Times
- First Contentful Paint: < 1.5s
- Time to Interactive: < 2.5s
- Total page weight: < 500KB

### Lighthouse Scores
- Performance: ≥ 85
- Accessibility: ≥ 95
- Best Practices: ≥ 90

---

## ♿ Mobile Accessibility

### Touch Targets
- Minimum: `44x44px`
- Ideal: `48x48px`
- Spacing: `8px` between targets

### Text Sizing
- All text scalable (no `font-size: 16px !important`)
- Test with iOS text size settings
- Test with Android display size settings

### Screen Readers
- iOS VoiceOver compatible
- Android TalkBack compatible
- Proper heading hierarchy
- Form labels associated

### Focus Management
- Visible focus indicators
- Focus not trapped unintentionally
- Logical tab order

---

## 🧪 Testing Checklist

### Devices to Test

**iOS**:
- [ ] iPhone 14 Pro (393x852)
- [ ] iPhone 14 (390x844)
- [ ] iPhone SE (375x667)

**Android**:
- [ ] Samsung Galaxy S21 (360x800)
- [ ] Google Pixel 7 (412x915)

### Orientations
- [ ] Portrait (primary)
- [ ] Landscape (secondary)

### Actions
- [ ] Form filling with virtual keyboard
- [ ] Submit form
- [ ] Navigate between fields (Tab)
- [ ] Tap all interactive elements
- [ ] Zoom in/out (pinch)
- [ ] Scroll form
- [ ] Theme toggle
- [ ] Language switcher

### Edge Cases
- [ ] Long email addresses
- [ ] Small screen (320px width)
- [ ] Large text size (iOS settings)
- [ ] Slow network (3G simulation)
- [ ] Offline mode

---

## 🐛 Common Mobile Issues & Solutions

### Issue 1: Input Zoom on iOS
**Problem**: Safari zooms in when focusing input < 16px
**Solution**: Always use `font-size: 16px` for inputs

### Issue 2: Keyboard Covers Submit Button
**Problem**: Virtual keyboard hides button
**Solution**: Add bottom margin or use `scrollIntoView()`

### Issue 3: Touch Targets Too Small
**Problem**: Users miss buttons
**Solution**: Minimum `44x44px`, ideally `48x48px`

### Issue 4: Viewport Height Issues
**Problem**: `100vh` includes browser chrome
**Solution**: Use `100dvh` (dynamic viewport height)

### Issue 5: Click Delay
**Problem**: 300ms delay on iOS
**Solution**: Add `<meta name="viewport" content="width=device-width">`

---

## 🎨 Mobile-Specific Patterns

### Form Layout

**Stack Vertically**:
```
[Logo]
[Heading]
[Subheading]

[Email Label]
[Email Input]

[Password Label]
[Password Input]

[Remember Me] [Forgot Password]

[Submit Button]

[Sign Up Link]
```

### Error Messages

**Position**: Below field (not inline)
**Icon**: Left of text
**Color**: Red with light background
**Dismissible**: Tap X to close

### Loading States

**Full Screen Overlay** (for page transitions):
```css
position: fixed;
inset: 0;
background: rgba(21, 32, 43, 0.8);
backdrop-filter: blur(4px);
z-index: 9999;
```

**Inline** (for button):
- Show spinner in button
- Disable form
- Keep button in place (no layout shift)

---

## 🔗 Related Documentation

- [Tablet Specs](./tablet-specs.md)
- [Desktop Specs](./desktop-specs.md)
- [Design System](../../DESIGN_SYSTEM.md)
- [Auth Mockups](../mockups/auth-login-states.md)

---

**Designer**: [Name]
**Last Updated**: 2026-01-04
**Version**: 2.0 (X.ai Minimal Redesign)
