# 🎨 Visual Guide - See Your App in Action

This document shows what LangOver looks like when running.

---

## 🖥️ The User Interface

### Menu Bar Icon (Inactive)

```
┌──────────────────────────────────────────────────────┐
│  🔋 100%  📶 WiFi  🔊 Volume  ⌚ 2:30 PM  [abc] ← HERE│
└──────────────────────────────────────────────────────┘
```

**What the user sees:**
- Small, subtle icon in the top-right corner
- Looks professional, matches macOS style
- Always accessible with one click

---

### Menu Bar Icon (Disabled/Inactive State)

```
┌──────────────────────────────────────────────────────┐
│  🔋 100%  📶 WiFi  🔊 Volume  ⌚ 2:30 PM  [abc] (grayed)│
└──────────────────────────────────────────────────────┘
```

**Visual feedback:**
- Icon appears slightly grayed/dimmed
- User knows app is paused
- Can be re-enabled anytime

---

## 🗂️ Menu Bar Dropdown Menu

```
                                    [abc] ← Click here
                                      │
        ┌─────────────────────────────▼────────┐
        │                                      │
        │  [✓] Disable                         │ ← Toggle on/off
        │  ────────────────────────────────    │
        │  U.S. ↔ Hebrew                       │ ← Current pair
        │  ────────────────────────────────    │
        │  Preferences…              ⌘,        │ ← Settings
        │  ────────────────────────────────    │
        │  Quit LangOver             ⌘Q        │ ← Exit
        │                                      │
        └──────────────────────────────────────┘
```

**Design principles:**
- Clean, minimal design
- Standard macOS menu appearance
- Keyboard shortcuts shown (⌘,, ⌘Q)
- Clear visual separators

---

## 🎬 First Launch Dialog

```
┌─────────────────────────────────────────────────────────────┐
│                   Welcome to LangOver!                      │
│                                                             │
│                        [keyboard icon]                      │
│                           🎹                                │
│                                                             │
│        I found 5 keyboard layout(s) on your Mac:            │
│                                                             │
│     ┌─────────────────────────────────────────────┐        │
│     │                                             │        │
│     │   ✓ U.S.                                    │        │
│     │   ✓ Hebrew                                  │        │
│     │   ✓ British                                 │        │
│     │   ✓ Russian                                 │        │
│     │   ✓ Spanish                                 │        │
│     │                                             │        │
│     └─────────────────────────────────────────────┘        │
│                                                             │
│         Select at least 2 keyboards to enable conversion.   │
│                                                             │
│                    [     Continue     ]                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
        500px wide × 600px tall
```

**User experience:**
- Large, friendly welcome message
- Clear instructions
- All keyboards pre-selected (user can uncheck)
- Single action button (Continue)
- No confusion about what to do

---

## ⚙️ Preferences Window

```
┌─────────────────────────────────────────────────────────────┐
│  ⚙️  Preferences                                      [×]    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │  ⌨️  Selected Keyboards                            │     │
│  │                                                    │     │
│  │  Choose which keyboards to convert between        │     │
│  │  (minimum 2):                                     │     │
│  │                                                    │     │
│  │  ✓ U.S.                                           │     │
│  │  ✓ Hebrew                                         │     │
│  │  ☐ British                                        │     │
│  │  ☐ Russian                                        │     │
│  │  ☐ Spanish                                        │     │
│  │                                                    │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │  ⌘  Global Hotkey                                 │     │
│  │                                                    │     │
│  │  Press this key combination to convert text:      │     │
│  │                                                    │     │
│  │  ┌──────────────────────────────────────┐        │     │
│  │  │  [  Ctrl  +  Shift  +  Space  ]      │        │     │
│  │  └──────────────────────────────────────┘        │     │
│  │  Click to change                                  │     │
│  │                                                    │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │  🚀  Startup                                       │     │
│  │                                                    │     │
│  │  ✓ Start LangOver at login                        │     │
│  │                                                    │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │  🔒  Privacy                                       │     │
│  │                                                    │     │
│  │  All text conversion happens locally on your      │     │
│  │  Mac. LangOver never sends data over the          │     │
│  │  internet.                                        │     │
│  │                                                    │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  ⚠️  Accessibility permission required                      │
│                                        [Grant Permission]   │
└─────────────────────────────────────────────────────────────┘
        500px wide × 600px tall
```

**Design features:**
- Grouped settings in "cards" (GroupBox)
- Clear section headers with icons
- Privacy notice prominent
- Warning footer if permission missing
- No "Apply" button (saves automatically)

---

## 🎭 Before & After (Text Conversion)

### Example 1: Email in Mail.app

**BEFORE (Wrong Layout):**
```
┌─────────────────────────────────────────────────────────────┐
│  📧  Mail                                            [×]     │
├─────────────────────────────────────────────────────────────┤
│  To: friend@example.com                                     │
│  Subject: Quick question                                    │
│                                                             │
│  Hey,                                                       │
│  akuo! ksç cm?  ← Meant to type in Hebrew                  │
│                                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**User action:** Select text, press Ctrl+Shift+Space

**AFTER (Converted):**
```
┌─────────────────────────────────────────────────────────────┐
│  📧  Mail                                            [×]     │
├─────────────────────────────────────────────────────────────┤
│  To: friend@example.com                                     │
│  Subject: Quick question                                    │
│                                                             │
│  Hey,                                                       │
│  שלום! מה נשמע?  ← Converted instantly!                     │
│                                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**Time elapsed:** ~50ms (instant to user)

---

### Example 2: Notes without Selection

**BEFORE:**
```
┌─────────────────────────────────────────────────────────────┐
│  📝  Notes                                           [×]     │
├─────────────────────────────────────────────────────────────┤
│  Shopping List                                              │
│                                                             │
│  • Milk                                                     │
│  • Bread                                                    │
│  • akuo📍← cursor here (didn't select)                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**User action:** Just press Ctrl+Shift+Space (nothing selected)

**AFTER:**
```
┌─────────────────────────────────────────────────────────────┐
│  📝  Notes                                           [×]     │
├─────────────────────────────────────────────────────────────┤
│  Shopping List                                              │
│                                                             │
│  • Milk                                                     │
│  • Bread                                                    │
│  • שלום📍← converted from cursor to line break!             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**Smart behavior:** Automatically found text to convert!

---

## ⚠️ Alert Dialogs

### Accessibility Permission Required

```
┌──────────────────────────────────────────────────────┐
│  ⚠️                                                   │
│                                                      │
│         Accessibility Permission Required            │
│                                                      │
│  LangOver needs Accessibility permission to read    │
│  and modify text in other apps.                     │
│                                                      │
│  Without this permission, the app won't be able to  │
│  read or modify text when you press the hotkey.     │
│                                                      │
│  Please grant permission in:                        │
│  System Settings → Privacy & Security → Accessibility│
│                                                      │
│                                                      │
│      [  Open System Settings  ]    [  Later  ]      │
│                                                      │
└──────────────────────────────────────────────────────┘
```

**User-friendly:**
- Clear explanation WHY permission needed
- Exact path to system settings
- Option to do it later (not forced)

---

### Could Not Replace Text

```
┌──────────────────────────────────────────────────────┐
│  ℹ️                                                   │
│                                                      │
│            Could Not Replace Text                    │
│                                                      │
│  The text field you're in may be read-only or       │
│  doesn't support text replacement.                  │
│                                                      │
│  Try in a different app (Notes, Mail, etc.)         │
│                                                      │
│                                                      │
│                     [  OK  ]                         │
│                                                      │
└──────────────────────────────────────────────────────┘
```

**Helpful:**
- Explains why it didn't work
- Suggests alternatives
- Not scary or technical

---

## 🎬 Animation Flow (Conceptual)

### Text Conversion Animation

```
Step 1: User selects text
┌────────────────┐
│  [akuo] ← sel  │
└────────────────┘

Step 2: User presses Ctrl+Shift+Space
         ⌨️
         │
         ▼

Step 3: Text converts (instant)
┌────────────────┐
│  שלום ✨        │
└────────────────┘
```

**Visual feedback:**
- Text changes instantly
- Cursor/selection preserved
- No loading spinner needed (too fast!)

---

## 🖼️ System Integration

### System Settings - Accessibility

```
┌─────────────────────────────────────────────────────────────┐
│  System Settings                                     [×]    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  🔒  Privacy & Security                                     │
│                                                             │
│  Accessibility                                              │
│  ────────────────────────────────────────────────────      │
│  Apps that can control your computer to improve             │
│  accessibility for users with disabilities.                 │
│                                                             │
│  ┌─────────────────────────────────────────────────┐       │
│  │  ☐ Terminal                                     │       │
│  │  ☐ Zoom                                         │       │
│  │  ✓ LangOver ← User needs to enable this        │       │
│  │  ☐ Screen Recording App                        │       │
│  └─────────────────────────────────────────────────┘       │
│                                                             │
│  🔓 Click the lock to make changes                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**System integration:**
- LangOver appears in official system list
- User toggles it on
- macOS manages the permission

---

## 🎨 Color Scheme & Style

### macOS Native Appearance

**Light Mode:**
```
Menu bar icon:     Black (system default)
Window background: White
Text:              Black
Accent:            System blue (#007AFF)
GroupBox borders:  Light gray
```

**Dark Mode:**
```
Menu bar icon:     White (system default)
Window background: Dark gray (#1E1E1E)
Text:              White
Accent:            System blue (#0A84FF)
GroupBox borders:  Dark gray
```

**Automatically adapts to user's system preference!**

---

## 📐 Layout Dimensions

### Windows

```
FirstLaunchView:   500 × 600 px
PreferencesView:   500 × 600 px
ContentView:       400 × 300 px (unused)
```

### Menu

```
Menu width:        ~250 px
Item height:       24 px
Padding:          8 px
Icon size:        16 × 16 px
```

### Menu Bar Icon

```
Icon size:        16 × 16 px (standard)
Spacing:          8 px from other icons
Hit target:       44 × 22 px (Apple HIG)
```

---

## 🎭 State Indicators

### Menu Bar Icon States

```
Normal (Enabled):
[abc] ← Full opacity, blue accent (if selected)

Disabled:
[abc] ← Gray, appears dimmed

Menu Open:
[abc] ← Highlighted background
  ▼
```

### Menu Items

```
Enabled:
[✓] Disable ← Checkmark + normal color

Disabled (not in use):
[ ] Enable ← No checkmark + normal color

Unavailable:
  Preferences… ← Grayed out (never happens)
```

---

## 🔔 User Feedback

### Success (Silent)
```
Text conversion happens
No visual feedback needed (text change IS the feedback)
Duration: Instant
```

### Error (Gentle Beep)
```
User presses hotkey but nothing to convert
System beep: 🔔
Duration: 200ms
Volume: System volume
```

### Alert (Modal Dialog)
```
Serious issues (no permission, can't replace text)
Modal alert appears
User must acknowledge
```

---

## 🌈 SF Symbols Used

### Icons in the App

```
Menu bar icon:       "textformat.abc"
Keyboard section:    "keyboard"
Hotkey section:      "command"
Startup section:     "power"
Privacy section:     "lock.shield"
First launch:        "keyboard" (large)
Warning:            "exclamationmark.triangle.fill"
Settings gear:      "gearshape.fill"
```

**All icons:**
- Native SF Symbols (built into macOS)
- Scale properly at any size
- Adapt to light/dark mode automatically
- Free to use (no licensing)

---

## 📱 Responsive Design

### Window Behaviors

```
FirstLaunchView:
- Fixed size (500×600)
- Centered on screen
- Cannot be resized
- Closable (but re-opens if not completed)

PreferencesView:
- Fixed size (500×600)
- Centered on screen
- Cannot be resized
- Closable anytime

ContentView:
- Fixed size (400×300)
- Not used (menu bar app)
- Could be used for "About" window
```

---

## 🖱️ Interaction Design

### Click Targets

```
Menu bar icon:     44×22 px (Apple HIG minimum)
Menu items:        Height 24px (comfortable)
Checkboxes:        20×20 px + label
Buttons:           Min 88×44 px (Apple HIG)
Hotkey recorder:   Full width of section
```

**All targets meet Apple's Human Interface Guidelines!**

---

## ♿ Accessibility

### VoiceOver Support

```
Menu bar icon:
"LangOver, menu bar item. Click to open menu."

Menu items:
"Disable LangOver, checked, menu item"
"U.S. to Hebrew, menu item"
"Preferences, menu item, command comma"
"Quit LangOver, menu item, command Q"

Checkboxes:
"U.S., checked, checkbox"
"Hebrew, checked, checkbox"

Buttons:
"Continue, button"
"Grant Permission, button"
```

**Every element is screen-reader accessible!**

---

## 🎨 Design Philosophy

### Principles

1. **Native First**
   - Looks like a macOS app
   - Uses system fonts, colors, icons
   - Respects user's appearance preference

2. **Minimal & Focused**
   - No clutter
   - Only essential features visible
   - Progressive disclosure (advanced in Preferences)

3. **Clear & Honest**
   - Privacy notice prominent
   - Permissions explained clearly
   - No hidden behaviors

4. **Forgiving**
   - Can't make destructive mistakes
   - Easy to undo (disable app)
   - Helpful error messages

---

## 🖼️ Screenshots You Should Take

When showing off your app, capture:

1. **Menu bar icon** (show it integrated with system icons)
2. **Menu dropdown** (show all menu items)
3. **First launch dialog** (show keyboard selection)
4. **Preferences window** (show all sections)
5. **Before/After conversion** (in real app like Mail)
6. **System Settings** (show Accessibility permission)

These tell the complete story visually!

---

## 🎉 Visual Summary

**LangOver looks like:**
- ✅ A professional macOS app
- ✅ Native, integrated, familiar
- ✅ Clean, minimal, uncluttered
- ✅ Respectful of user preferences
- ✅ Clear, helpful, forgiving

**Not like:**
- ❌ A Windows app ported to Mac
- ❌ A web app wrapped in Electron
- ❌ A cluttered power-user tool
- ❌ A confusing technical utility

---

**Your app will look great because it follows Apple's design guidelines!** 🎨✨
