Skip to content

QUICK_START.md

Latest commit

 

History

History
346 lines (248 loc) · 8.42 KB

QUICK_START.md

File metadata and controls

346 lines (248 loc) · 8.42 KB

🚀 EyeBreak Quick Start Guide

Get up and running with EyeBreak in 5 minutes!

📥 Installation

Step 1: Download

Download the latest version from GitHub Releases

Step 2: Remove Quarantine

Since the app is unsigned, you need to remove macOS quarantine:

cd ~/Downloads
xattr -cr EyeBreak-v2.3.0.dmg

Step 3: Install

  1. Open the DMG file
  2. Drag EyeBreak.app to your Applications folder
  3. Launch EyeBreak

Step 4: Grant Permissions

When prompted, grant:

  • Accessibility access (for idle detection)
  • Notifications permission (for break reminders)

🎯 First Use

1. Welcome Screen

Complete the onboarding to learn about the 20-20-20 rule:

  • Every 20 minutes of screen time
  • Look 20 feet away
  • For 20 seconds

2. Start Your First Session

  1. Find the eye icon 👁️ in your menu bar
  2. Click it and select "Start Timer"
  3. Work normally - EyeBreak will remind you when it's time to rest

3. Take Your First Break

When the timer ends:

  • Your screen will gently blur
  • Follow the on-screen instructions
  • Rest your eyes for 20 seconds
  • Press ESC if you need to skip (not recommended!)

⚙️ Basic Settings

Click the eye icon → Settings to customize:

Timer Settings

  • Work Interval: 10-60 minutes (default: 20 min)
  • Break Duration: 10-60 seconds (default: 20 sec)
  • Warning Time: When to notify before break (default: 30 sec)

Break Styles

Choose how breaks appear:

  • Blur Screen (recommended) - Gentle full-screen overlay
  • Notification Only - Just a notification
  • Eye Exercise - Guided eye movement exercises

Session Presets

Quick presets for common workflows:

  • Standard - 20 min work / 20 sec break (20-20-20 rule)
  • Pomodoro - 25 min work / 5 min break
  • Custom - Set your own intervals

🎨 Theme Customization (v2.0+)

New in v2.3.0 🎨

Menu Bar Timer Display

  • Live countdown visible directly in the menu bar
  • Dynamic state icons that change based on timer state
  • Monospaced digits for clean, stable display

Professional UI Polish

  • Enhanced floating break window with gradient styling
  • Polished onboarding with spring animations
  • Refined settings views with hidden scrollbars
  • New reusable components for consistent design

🎨 Theme Customization

Choose Your Theme

In Settings, scroll to "Color Themes" section:

Default Theme 🎨

Classic EyeBreak colors - no configuration needed

Random Color 🎲

Fresh, beautiful colors every time:

  1. Click "Random Color" button
  2. Enjoy 20 curated palettes
  3. New colors with each break!

Custom Theme 🛠️

Complete control:

  1. Click "Custom" button
  2. Use color pickers for:
    • Background color
    • Accent color
    • Text colors
    • Opacity levels
  3. Try Quick Presets for inspiration

Customize Icons

Make reminders personal:

  1. Scroll to "Ambient Reminder Settings"
  2. Enable "Use Custom Reminder"
  3. Click the icon grid (16 SF Symbols available)
  4. Enter custom message text

Independent Themes

Set different themes for:

  • Ambient Reminders - Small floating notifications
  • Break Overlay - Full-screen break mode

🔔 Ambient Reminders (Optional)

Small, non-intrusive reminders while working:

  1. In Settings, enable "Ambient Reminders"
  2. Set interval (how often they appear)
  3. Set duration (how long they stay)
  4. Choose icon and message
  5. Pick a theme!

These appear as floating notifications to gently remind you about eye health.

📊 Track Your Progress

Click the eye icon → "View Stats" to see:

  • Breaks taken today
  • Current streak
  • Weekly history
  • Daily progress toward goal

💡 Pro Tips

For Best Results

  • ✅ Keep timer running during work hours
  • ✅ Actually rest your eyes during breaks
  • ✅ Look at distant objects (20 feet away)
  • ✅ Blink frequently during breaks

Customize Your Experience

  • 🎨 Try Random Color theme for variety
  • 🎯 Enable Ambient Reminders between breaks
  • ⏱️ Use Pomodoro mode for focused work
  • 🔕 Disable sound if needed

Working from Home

  • 📍 Idle detection pauses when you're away
  • 🖥️ Multi-monitor support included
  • 🌙 Works great with Dark Mode

❓ Common Questions

Timer not starting? → Check if you have permission to run the app (System Settings → Privacy & Security)

Breaks not appearing? → Ensure timer is started and notifications are enabled

Colors not changing? → Random colors change between breaks, not during

App not in menu bar? → Restart the app or check System Settings → General → Login Items

🆘 Need More Help?

🎉 You're All Set!

EyeBreak is now protecting your eyes. Remember:

  • Consistency is key - keep the timer running
  • Rest during breaks - don't skip them
  • Customize to match your workflow
  • Share with colleagues who need it too!

Enjoy healthy eyes! 👁️✨

🚀 Quick Setup

1. Open Settings

Click the eye icon 👁️ in your menu bar → Select "Settings..."

2. Find Color Themes

Scroll down to the "Color Themes" section

3. Choose Your Style

🎨 Default Theme

  • Classic EyeBreak colors
  • Perfect if you like the original look
  • No configuration needed

🎲 Random Color (Recommended to try!)

  • Click "Random Color" button
  • Fresh, beautiful colors every time
  • 20 curated palettes
  • Just enable and enjoy!

🛠️ Custom Theme

  • Click "Custom" button
  • Use color pickers to customize:
    • Background color
    • Accent color
    • Text colors
    • Opacity levels
    • Glass effects
  • Try Quick Presets for inspiration

4. Customize Icons (Optional)

In the same settings:

  • Scroll to "Ambient Reminder Settings"
  • Enable "Use Custom Reminder"
  • Click the icon grid to choose from 16 SF Symbols
  • Enter custom message text

5. Independent Themes

You can set different themes for:

  • Ambient Reminders - Small floating notifications
  • Break Overlay - Full-screen break mode

Mix and match as you like!

💡 Tips & Tricks

For Random Color Fans:

  • Colors change between sessions, not during
  • Each break gets a new beautiful palette
  • No two sessions look the same!

For Custom Theme Creators:

  • Start with a Quick Preset, then adjust
  • Use the preview to see changes live
  • Adjust opacity for subtle or bold looks
  • Blur radius changes the glass effect

For Icon Lovers:

  • Eye icons: Classic reminder look
  • Stars/Sparkles: Magical feel
  • Nature icons: Calm and peaceful
  • Time icons: Professional style
  • Wellness icons: Health-focused

🎯 Popular Combinations

The Professional

  • Theme: Default
  • Icon: Clock or Eye
  • Clean, business-appropriate

The Colorful

  • Theme: Random Color
  • Icon: Sparkles or Star
  • Vibrant, surprising, fun

The Minimalist

  • Theme: Custom (low opacity, subtle colors)
  • Icon: Eye or Drop
  • Barely-there notifications

The Bold

  • Theme: Custom (high contrast, vibrant)
  • Icon: Heart or Sun
  • Eye-catching, impossible to ignore

⚙️ Advanced Settings

Theme Controls Available:

Background Color

  • Pick any color
  • Adjust opacity (0-100%)

Accent Color

  • Highlights and borders
  • Adjust opacity (0-100%)

Text Colors

  • Primary text color
  • Secondary text color
  • Individual opacity controls

Glass Effects

  • Blur radius (0-20)
  • Highlight opacity (0-100%)

🔄 Switching Themes

Want to try something different?

  1. Open Settings
  2. Click a different theme type
  3. Changes apply instantly!

Your preferences are saved automatically.

🆘 Troubleshooting

Colors look washed out? → Increase opacity in custom theme

Random colors not changing? → They change between sessions, not during display

Can't see icon picker? → Enable "Use Custom Reminder" first

Settings not saving? → Try quitting and relaunching the app

📚 Learn More

  • Full documentation: docs/ folder
  • Release notes: docs/releases/RELEASE_NOTES_v2.3.0.md
  • Changelog: CHANGELOG.md

💬 Need Help?

  • GitHub Issues: Report bugs or ask questions
  • GitHub Discussions: Share your custom themes!

Enjoy your personalized eye break experience! 🎨✨