# UI Design Specification for FocusBuddy

**Version**: 1.0  
**Target Platforms**: iOS & Android (responsive)  
**Framework**: Flutter-friendly  
**Design Philosophy**: Calm • Gentle • Accessible • Neurodivergent-Friendly

---

## 1. Core Principles

- **Low Stimulation**: Avoid bright colors, sharp edges, fast animations
- **Emotional Safety**: No red error messages, no countdown pressure
- **Clarity Over Cleverness**: One primary action per screen
- **Offline-First UX**: Assume no internet; no loading spinners

---

## 2. Color Palette

| Role | Hex | Usage |
|------|-----|-------|
| Primary (Calm Green) | `#A7C4BC` | Main buttons, active states |
| Background | `#F8F6F2` | App background (warm off-white) |
| Text Primary | `#5B6D6D` | Headings, large numbers |
| Text Secondary | `#8A9B9B` | Descriptions, helper text |
| Distraction Button | `#E0E0E0` | “I got distracted” button |
| Success | `#88C9A1` | Achievement unlocked |

> 🎨 All colors pass WCAG AA contrast ratio for accessibility.

---

## 3. Typography

| Element | Font | Size | Weight |
|--------|------|------|--------|
| App Title | Nunito | 24px | Bold |
| Timer Display | Nunito | 64px | ExtraBold |
| Buttons | Nunito | 18px | SemiBold |
| Body Text | Nunito | 16px | Regular |
| Helper Text | Nunito | 14px | Light |

> 💡 **Font Source**: [Google Fonts – Nunito](https://fonts.google.com/specimen/Nunito) (free, supports Latin + basic Unicode)

---

## 4. Core Screens

### 4.1 Home Screen (Start Focus)

**Layout:**
```
┌─────────────────────────────────┐
│                                 │
│         FocusBuddy              │  ← App title (24px, centered)
│                                 │
│                                 │
│      [  25 minutes  ]           │  ← Duration selector (slider below)
│       ◀─────────▶               │  ← Slider: 5min - 60min (step: 5)
│                                 │
│                                 │
│   ┌───────────────────────┐    │
│   │   Start Focusing      │    │  ← Primary button (#A7C4BC)
│   │       ▶               │    │  ← 56px height, rounded 16px
│   └───────────────────────┘    │
│                                 │
│  "Tap 'I got distracted'        │  ← Helper text (#8A9B9B)
│   anytime — no guilt."          │  ← 14px, centered
│                                 │
│                                 │
│  📊 History    ⚙️ Settings      │  ← Bottom navigation (icons only)
└─────────────────────────────────┘
```

**Interactions:**
- Slider adjusts duration in real-time (haptic feedback on iOS)
- "Start Focusing" button: Scale animation (0.95 → 1.0) on press
- Transitions to "During Focus" screen with fade-in (300ms)

**Animation:**
- Subtle particle floating in background (Lottie: `calm-particles.json`)
- Particles: 5-8 dots, opacity 0.1-0.3, slow drift upward

---

### 4.2 During Focus Screen

**Layout:**
```
┌─────────────────────────────────┐
│                                 │
│         24:37                   │  ← Timer (64px, #5B6D6D)
│                                 │  ← Breathing animation (scale 1.0-1.02)
│                                 │
│                                 │
│   ┌───────────────────────┐    │
│   │  I got distracted     │    │  ← Secondary button (#E0E0E0)
│   │         🤚            │    │  ← 48px height, rounded 12px
│   └───────────────────────┘    │
│                                 │
│   ┌───────────────────────┐    │
│   │      ⏸ Pause          │    │  ← Tertiary button (outlined)
│   └───────────────────────┘    │  ← Border: 1px #A7C4BC
│                                 │
│                                 │
│  🎵 White Noise: Rain ▼         │  ← Dropdown (bottom sheet)
│                                 │
└─────────────────────────────────┘
```

**Interactions:**
- **Timer**: Count-down display, updates every second
- **"I got distracted"** → Opens bottom sheet with 4 options
- **Pause** → Shows "Resume" button + elapsed time badge
- **White Noise** → Bottom sheet: Off / Rain / Keyboard / Forest

**Bottom Sheet: Distraction Types**
```
┌─────────────────────────────────┐
│  What pulled you away?          │  ← Title (16px, #5B6D6D)
│                                 │
│  📱 Scrolling social media      │  ← Option 1 (tap to select)
│  👥 Got interrupted             │  ← Option 2
│  😰 Felt overwhelmed            │  ← Option 3
│  💭 Just zoned out              │  ← Option 4
│                                 │
│  [Skip this time]               │  ← Text button (optional)
└─────────────────────────────────┘
```

**Feedback after selection:**
- Toast message: "It happens. Let's gently come back." (3s)
- Soft haptic pulse
- Auto-dismiss bottom sheet
- Timer continues running

---

### 4.3 Focus Complete Screen

**Layout:**
```
┌─────────────────────────────────┐
│                                 │
│           ✨                    │  ← Success icon (animated)
│                                 │
│    You focused for              │  ← Headline (20px, #5B6D6D)
│       24 minutes                │  ← Large number (32px, bold)
│                                 │
│  ┌─────────────────────────┐   │
│  │ Total Today: 47 mins    │   │  ← Stats card (#F8F6F2 bg)
│  │ Distractions: 2 times   │   │  ← Body text (16px)
│  │                         │   │
│  │ "Showing up is half     │   │  ← Random encouragement
│  │  the battle."           │   │  ← Italic, #8A9B9B
│  └─────────────────────────┘   │
│                                 │
│  🎁 Achievement Unlocked!       │  ← Conditional (if milestone hit)
│  "Calm Cloud" theme             │  ← Badge animation
│                                 │
│  ┌───────────────────────┐     │
│  │   Start Another       │     │  ← Primary button
│  └───────────────────────┘     │
│                                 │
│  [View Full Report]             │  ← Text link
└─────────────────────────────────┘
```

**Interactions:**
- Success icon: Lottie animation (plays once, 2s)
- "Start Another" → Resets to Home screen
- "View Full Report" → Navigates to History tab

**Achievement Badge:**
- Slides up from bottom with bounce effect
- Shimmer animation (gradient sweep)
- If ad required: Shows "Watch ad to unlock" button

---

### 4.4 History/Report Screen

**Layout:**
```
┌─────────────────────────────────┐
│  📊 Your Focus Journey          │  ← Header (24px)
│                                 │
│  ┌─ Today ──────────────────┐  │
│  │                          │  │
│  │  Total: 47 mins          │  │  ← Daily summary card
│  │  Sessions: 2             │  │
│  │  Distractions: 3         │  │
│  │                          │  │
│  │  ▓▓▓▓▓░░░░░ 60%          │  │  ← Progress bar
│  │  (Goal: 75 mins/day)     │  │
│  └──────────────────────────┘  │
│                                 │
│  ┌─ This Week ─────────────┐   │
│  │  Mon  ■■■  24 mins       │  │  ← Bar chart (simplified)
│  │  Tue  ■■■■  32 mins      │  │
│  │  Wed  ■■  15 mins        │  │
│  │  Thu  ■■■■■  47 mins ←   │  │  ← Today highlighted
│  └──────────────────────────┘  │
│                                 │
│  📈 Top Distraction:            │
│  📱 Social media (60%)          │  ← Insight card
│                                 │
│  [Export PDF Report]            │  ← Secondary button (outlined)
│                                 │
└─────────────────────────────────┘
```

**Interactions:**
- Pull-to-refresh: Animates header particles
- Bar chart: Tap day → Shows session details
- Export PDF: Generates report with past 7 days data
  - Requires storage permission (Android)
  - iOS: Share sheet

**PDF Report Content:**
- Logo + Date range
- Total focus time
- Session breakdown by day
- Distraction type distribution (pie chart)
- Encouragement message
- Footer: "Generated by FocusBuddy"

---

### 4.5 Settings Screen

**Layout:**
```
┌─────────────────────────────────┐
│  ⚙️ Settings                    │
│                                 │
│  ┌─ Appearance ──────────────┐ │
│  │  Theme: Calm Cloud      ▼ │ │  ← Dropdown
│  │  [Preview]                │ │
│  │                           │ │
│  │  🔓 Unlock More Themes    │ │  ← Ad button
│  └───────────────────────────┘ │
│                                 │
│  ┌─ Focus Settings ──────────┐ │
│  │  Default Duration: 25 min │ │
│  │  White Noise: Rain        │ │
│  │  Daily Goal: 75 mins      │ │
│  └───────────────────────────┘ │
│                                 │
│  ┌─ Notifications ───────────┐ │
│  │  Focus Reminders     [ON] │ │  ← Toggle
│  │  Encourage Messages  [ON] │ │
│  └───────────────────────────┘ │
│                                 │
│  💎 Remove Ads ($2.99)          │  ← IAP button (highlighted)
│                                 │
│  Privacy Policy                 │  ← Links (text buttons)
│  About FocusBuddy               │
│                                 │
└─────────────────────────────────┘
```

**Interactions:**
- Theme preview: Shows timer screen with selected theme
- "Unlock Themes": Shows rewarded ad → Unlocks next theme
- IAP button: Opens native purchase dialog
- Toggles: Animated switch with haptic feedback

---

## 5. Component Specifications

### 5.1 Primary Button

**Visual:**
- Background: `#A7C4BC`
- Text: `#FFFFFF`, 18px, SemiBold
- Height: 56px
- Border radius: 16px
- Shadow: 0px 4px 12px rgba(167, 196, 188, 0.3)

**States:**
```
Normal:   opacity 1.0, scale 1.0
Pressed:  opacity 0.9, scale 0.95 (150ms ease-out)
Disabled: opacity 0.5, grayscale 100%
```

**Flutter Example:**
```dart
ElevatedButton(
  style: ElevatedButton.styleFrom(
    backgroundColor: Color(0xFFA7C4BC),
    minimumSize: Size(double.infinity, 56),
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(16),
    ),
    elevation: 4,
  ),
  child: Text('Start Focusing'),
)
```

---

### 5.2 Secondary Button (Distraction Button)

**Visual:**
- Background: `#E0E0E0`
- Text: `#5B6D6D`, 18px, SemiBold
- Height: 48px
- Border radius: 12px
- No shadow (flat design)

**States:**
```
Normal:   background #E0E0E0
Pressed:  background #D5D5D5
```

---

### 5.3 Timer Display

**Visual:**
- Font: Nunito ExtraBold
- Size: 64px
- Color: `#5B6D6D`
- Letter spacing: 2px (monospace feel)

**Animation:**
- Breathing effect: Scale 1.0 → 1.02 → 1.0 (4s loop, ease-in-out)
- On last 10 seconds: Pulse glow (0.3 opacity) around text

**Flutter Example:**
```dart
AnimatedScale(
  scale: _breathingAnimation.value,
  duration: Duration(seconds: 4),
  curve: Curves.easeInOut,
  child: Text(
    '24:37',
    style: TextStyle(
      fontSize: 64,
      fontWeight: FontWeight.w800,
      letterSpacing: 2,
    ),
  ),
)
```

---

### 5.4 Bottom Sheet (Distraction Selector)

**Visual:**
- Background: `#FFFFFF`
- Border radius: 24px 24px 0 0
- Height: 60% of screen (max 400px)
- Drag handle: 4px × 32px rounded bar, `#E0E0E0`

**Options:**
- Each row: 56px height
- Icon: 24px, `#8A9B9B`
- Text: 16px Regular, `#5B6D6D`
- Divider: 1px, `#F0F0F0`

**Animation:**
- Slide up: 300ms ease-out
- Backdrop: Fade to 0.5 opacity black

---

### 5.5 Achievement Badge

**Visual:**
```
┌─────────────────┐
│   🎁  Unlocked! │  ← Emoji + text (14px)
│                 │
│   Calm Cloud    │  ← Theme name (18px Bold)
│   ▓▓▓▓▓▓▓▓▓▓   │  ← Preview gradient bar
└─────────────────┘
```

**Animation:**
- Slide up from bottom: 400ms spring
- Shimmer sweep: 2s loop (gradient -100% → +100% X)
- Auto-dismiss after 5s (slide down)

**Colors:**
- Background: `#FFFFFF`
- Border: 2px `#88C9A1` (success color)
- Shadow: 0px 8px 24px rgba(136, 201, 161, 0.4)

---

## 6. Animations & Micro-interactions

### 6.1 Loading States

**When app launches:**
- Logo fade-in: 500ms
- Particles appear one by one (staggered 100ms)
- Total: 1s to interactive

**When switching screens:**
- Cross-fade: 300ms ease-in-out
- No slide transitions (avoid motion sickness)

---

### 6.2 Haptic Feedback

**iOS UIFeedbackGenerator:**
- Slider adjustment: `.selection`
- Button press: `.light`
- Timer complete: `.success`
- Distraction logged: `.soft` (custom if available)

**Android:**
- Use `HapticFeedback.lightImpact()`
- Intensity: 30% (gentle)

---

### 6.3 Sound Effects

**Audio Files (CC Licensed):**
- `button_tap.mp3`: Soft click (50ms)
- `distraction_logged.mp3`: Gentle chime (200ms)
- `focus_complete.mp3`: Warm bell (1s)
- `white_noise_rain.mp3`: 10min loop
- `white_noise_keyboard.mp3`: 10min loop

**Volume:**
- Default: 60%
- User adjustable in settings
- Respect system silent mode

---

## 7. Responsive Design

### 7.1 Screen Sizes

**Small (< 5.5"):**
- Timer: 56px (reduce from 64px)
- Button height: 48px (reduce from 56px)
- Padding: 16px (reduce from 24px)

**Large (> 6.5"):**
- Keep default sizes
- Max content width: 400px (centered)

**Tablet (7"+):**
- Use 2-column layout for History screen
- Timer centered with max 500px container

---

### 7.2 Safe Areas

**iOS:**
- Respect notch: Use `SafeArea` widget
- Bottom nav: 20px padding above home indicator

**Android:**
- Edge-to-edge: Use `WindowInsets`
- Navigation bar: Semi-transparent overlay

---

## 8. Accessibility

### 8.1 Screen Reader Support

**Labels:**
- Timer: "24 minutes and 37 seconds remaining"
- Distraction button: "Record a distraction, no penalty"
- Slider: "Focus duration, 25 minutes, adjustable from 5 to 60"

**Announcements:**
- Focus start: "Focus session started"
- Distraction logged: "Distraction recorded. It happens."
- Focus complete: "Session complete. You focused for 24 minutes."

---

### 8.2 High Contrast Mode

**When system high contrast enabled:**
- Increase all borders to 2px
- Button text: Pure black `#000000`
- Background: Pure white `#FFFFFF`
- Disable shadows and gradients

---

### 8.3 Font Scaling

**Support dynamic type:**
- Small: 0.85× base sizes
- Large: 1.2× base sizes
- Max: 1.5× (prevent overflow)

**Test at:**
- iOS: Settings → Accessibility → Display → Text Size
- Android: Settings → Accessibility → Font size

---

## 9. Dark Mode (Future Enhancement)

**Not in MVP**, but color mappings ready:

| Light Mode | Dark Mode |
|-----------|-----------|
| `#F8F6F2` (bg) | `#1A1A1A` |
| `#A7C4BC` (primary) | `#88A89F` (dimmer) |
| `#5B6D6D` (text) | `#E0E0E0` |
| `#FFFFFF` (cards) | `#2A2A2A` |

---

## 10. Design Assets Checklist

### 10.1 Required Lottie Files
- [ ] `calm-particles.json` (background animation)
- [ ] `success-sparkle.json` (focus complete)
- [ ] `achievement-shimmer.json` (badge unlock)

**Source:** [LottieFiles](https://lottiefiles.com) (search "calm", "gentle", "success")

---

### 10.2 App Icons

**Sizes needed:**
- **iOS:** 1024×1024 (App Store), 180×180, 120×120, 87×87, 80×80, 60×60
- **Android:** 512×512 (Play Store), 192×192, 144×144, 96×96, 72×72, 48×48

**Design:**
- Main symbol: Gentle wave or breathing circle
- Background: `#A7C4BC` gradient to `#88C9A1`
- Style: Minimal, rounded, approachable

---

### 10.3 Screenshots (for stores)

**Required shots (6.5" iPhone):**
1. Home screen with "Start Focusing" button
2. During focus with timer + distraction button
3. Focus complete with achievement badge
4. History screen with weekly chart
5. Settings with theme preview
6. (Optional) User testimonial overlay

**Text overlays:**
- "Focus without guilt"
- "Track gently, improve naturally"
- "Made for neurodivergent minds"

---

## 11. Implementation Notes

### 11.1 Flutter Packages

```yaml
dependencies:
  flutter:
    sdk: flutter
  hive: ^2.2.3          # Local storage
  hive_flutter: ^1.1.0
  flutter_local_notifications: ^17.0.0
  workmanager: ^0.5.2   # Background tasks
  lottie: ^3.0.0        # Animations
  just_audio: ^0.9.36   # White noise
  google_mobile_ads: ^4.0.0  # AdMob
  path_provider: ^2.1.0
  pdf: ^3.10.0          # Report export
```

---

### 11.2 Folder Structure

```
lib/
├── main.dart
├── screens/
│   ├── home_screen.dart
│   ├── focus_screen.dart
│   ├── complete_screen.dart
│   ├── history_screen.dart
│   └── settings_screen.dart
├── widgets/
│   ├── primary_button.dart
│   ├── timer_display.dart
│   ├── distraction_sheet.dart
│   └── achievement_badge.dart
├── models/
│   ├── focus_session.dart
│   └── distraction.dart
├── services/
│   ├── storage_service.dart
│   ├── notification_service.dart
│   └── audio_service.dart
├── theme/
│   ├── app_colors.dart
│   └── app_text_styles.dart
└── assets/
    ├── animations/
    ├── sounds/
    └── fonts/
```

---

### 11.3 Theme Definition

```dart
// lib/theme/app_colors.dart
class AppColors {
  static const primary = Color(0xFFA7C4BC);
  static const background = Color(0xFFF8F6F2);
  static const textPrimary = Color(0xFF5B6D6D);
  static const textSecondary = Color(0xFF8A9B9B);
  static const distractionButton = Color(0xFFE0E0E0);
  static const success = Color(0xFF88C9A1);
}

// lib/theme/app_text_styles.dart
class AppTextStyles {
  static const appTitle = TextStyle(
    fontFamily: 'Nunito',
    fontSize: 24,
    fontWeight: FontWeight.bold,
    color: AppColors.textPrimary,
  );

  static const timerDisplay = TextStyle(
    fontFamily: 'Nunito',
    fontSize: 64,
    fontWeight: FontWeight.w800,
    letterSpacing: 2,
    color: AppColors.textPrimary,
  );

  static const buttonText = TextStyle(
    fontFamily: 'Nunito',
    fontSize: 18,
    fontWeight: FontWeight.w600,
    color: Colors.white,
  );

  static const bodyText = TextStyle(
    fontFamily: 'Nunito',
    fontSize: 16,
    fontWeight: FontWeight.normal,
    color: AppColors.textPrimary,
  );

  static const helperText = TextStyle(
    fontFamily: 'Nunito',
    fontSize: 14,
    fontWeight: FontWeight.w300,
    color: AppColors.textSecondary,
  );
}
```

---

## 12. Quality Assurance Checklist

### 12.1 Visual QA

- [ ] All colors match design system
- [ ] Fonts render correctly on iOS/Android
- [ ] Animations run at 60fps
- [ ] No pixel shifts when rotating
- [ ] Safe areas respected on all devices

### 12.2 Interaction QA

- [ ] Buttons have press states
- [ ] Haptics fire at correct moments
- [ ] Sound effects play (and respect mute)
- [ ] Timer counts down accurately
- [ ] Bottom sheet dismisses on backdrop tap

### 12.3 Accessibility QA

- [ ] Screen reader announces all elements
- [ ] High contrast mode works
- [ ] Font scaling doesn't break layout
- [ ] Minimum touch target: 44×44 (iOS) / 48×48 (Android)

---

## Appendix: Encouragement Messages Library

Store in `assets/encouragements.json`:

```json
[
  "Showing up is half the battle.",
  "Every minute counts.",
  "You're learning, not failing.",
  "Gentleness is strength.",
  "Progress over perfection.",
  "Your effort matters.",
  "Small steps, big journey.",
  "Be kind to your brain.",
  "You're doing your best.",
  "One moment at a time.",
  "Focus is a practice, not a trait.",
  "It's okay to take breaks.",
  "You came back — that's what matters.",
  "Celebrate trying, not just succeeding.",
  "Your attention is valid."
]
```

**Usage:** Randomly select one message per focus completion.

---

**Document Status:** ✅ Complete
**Last Updated:** November 22, 2025
**Next Steps:** Create Figma prototype → Share with ADHD community for feedback