ytc/FocusBuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96658339e184eba658d114f4453a33060db4279c
FocusBuddy/ui-design-spec.md
ytc1012 d427916c6a first commit
2025-11-22 18:17:35 +08:00

22 KiB
Raw Blame History

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 (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:

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:

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 (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

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

// 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:

[
  "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

Reference in New Issue View Git Blame Copy Permalink