PROJECT OVERVIEW:
Create a single-page React application called 'Mac Space Accelerator' that enhances the macOS user experience by enabling instant, animation-free switching between virtual desktops (Spaces). The core problem it solves is the jarring and inefficient default animation that disrupts user workflow and causes visual discomfort. The primary value proposition is to provide a seamless, fluid, and highly productive desktop environment by eliminating these animations and offering quick access to frequently used Spaces.
TECH STACK:
- Frontend Framework: React (using Vite for fast development server and build)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Animation Library (optional, for subtle UI feedback): Framer Motion for smooth transitions on UI elements like buttons or loading states, but NOT for the core space switching.
- macOS Integration: A native macOS application wrapper (e.g., using Electron or Tauri) to interact with system-level shortcuts and potentially macOS APIs for space management. For MVP, we will simulate this interaction via customizable hotkeys within the app's settings, assuming the native bridge will be handled externally or in a later phase.
- Routing: Not required for a single-page application.
CORE FEATURES:
1. **Instant Space Switching Configuration:**
* User Flow: On the settings page, the user can define custom keyboard shortcuts for switching to specific Spaces (e.g., Cmd+1 for Space 1, Cmd+2 for Space 2, etc., or even arbitrary shortcuts like Ctrl+Alt+Shift+1).
* Functionality: When a defined shortcut is pressed, the application (or the underlying native mechanism it controls) should trigger an immediate switch to the corresponding Space without any visual animation.
2. **Disable All macOS Space Animations:**
* User Flow: A prominent toggle switch in the settings labeled 'Disable Space Transition Animations'.
* Functionality: When enabled, this setting should instruct the macOS system (via the native wrapper or a background process) to eliminate all default animations associated with switching between Spaces. This includes the slide, fade, or zoom effects.
3. **Favorite Spaces Quick Access:**
* User Flow: Users can mark specific Spaces as 'favorites' within the app. On the main interface or a dedicated quick access menu (triggered by a specific hotkey), these favorite Spaces can be listed. Clicking or using a shortcut associated with a favorite Space instantly switches to it.
* Functionality: Allows users to group their most-used Spaces for even faster access, bypassing the need to remember exact Space numbers.
4. **Settings Management:**
* User Flow: A dedicated settings area where users can configure shortcuts, toggle animation disabling, manage favorite Spaces, and potentially adjust other minor preferences.
* Functionality: Persists user settings locally (e.g., using `localStorage` or native user defaults via the wrapper).
UI/UX DESIGN:
- **Layout:** Single-page application. A clean, minimalist interface. A main dashboard/status view (optional for MVP) and a dedicated Settings page. Navigation between these views should be simple, possibly using tabs or a sidebar.
- **Color Palette:** Primarily dark mode focused, aligning with macOS aesthetics. Dark grays, blacks, with a single accent color (e.g., a vibrant blue or green) for interactive elements, toggles, and highlights. Use subtle gradients sparingly. Example: `#1a1a1d` (dark background), `#2c2c2e` (secondary background/cards), `#ffffff` (primary text), `#8a8a8e` (secondary text), `#007aff` (accent color).
- **Typography:** Clean, modern sans-serif font. System fonts like San Francisco (if possible via web) or a close alternative like Inter or Roboto. Ensure readability and hierarchy using font weights and sizes.
- **Responsive Design:** While primarily targeting macOS, the UI should be clean and functional on various screen sizes if accessed via a browser or if the app window is resized. Focus on a comfortable vertical layout for settings.
- **Visual Elements:** Use clear icons for actions (e.g., gear for settings, star for favorite, keyboard keys for shortcuts). Minimalistic illustrations or no illustrations at all.
COMPONENT BREAKDOWN:
1. **`App.jsx`:** Main application component. Manages overall layout, potentially routing (if needed later), and integrates global state.
* Props: None
* Responsibility: Root component, layout structure.
2. **`SettingsPage.jsx`:** Contains all configuration options.
* Props: `appState` (from Zustand), `setAppState` (from Zustand)
* Responsibility: Renders shortcut configuration, animation toggle, favorite Space management.
3. **`ShortcutConfigurator.jsx`:** UI component for setting up keyboard shortcuts.
* Props: `spaceNumber` (number), `currentShortcut` (string), `onShortcutChange` (function)
* Responsibility: Displays current shortcut, provides input or button to define a new shortcut for a specific Space.
4. **`AnimationToggle.jsx`:** A switch component to enable/disable animations.
* Props: `isEnabled` (boolean), `onToggle` (function)
* Responsibility: Renders the toggle switch and calls the handler function on change.
5. **`FavoriteSpacesManager.jsx`:** UI for selecting and managing favorite Spaces.
* Props: `allSpaces` (array), `favoriteSpaces` (array), `onFavoriteToggle` (function)
* Responsibility: Displays all available Spaces, allows users to toggle them as favorites.
6. **`SystemStatusIndicator.jsx` (Optional):** Shows if animations are currently disabled by the app.
* Props: `isAnimationsDisabled` (boolean)
* Responsibility: Visual feedback to the user.
7. **`HotkeyManager.jsx` (Background Logic):** Handles listening for global hotkeys (this would require the native wrapper).
* Props: None (operates on global state/system hooks)
* Responsibility: Captures defined hotkeys and triggers corresponding actions (simulated via function calls in this SPA context).
DATA MODEL:
- **`appState` (Zustand Store):**
```javascript
{
// Shortcut mapping: { '1': 'Cmd+1', '2': 'Cmd+2', ... } or { '1': { modifier: 'Cmd', key: '1' }, ... }
shortcuts: { [spaceNumber: string]: string },
// Boolean flag to disable macOS space animations
disableAnimations: boolean,
// Array of favorite space numbers
favoriteSpaces: number[],
// Total number of spaces detected or configured (e.g., 1-10)
totalSpaces: number
}
```
- **Initial State (Mock):**
```javascript
{
shortcuts: {
'1': 'Cmd+1',
'2': 'Cmd+2',
'3': 'Cmd+3'
},
disableAnimations: true,
favoriteSpaces: [1, 3],
totalSpaces: 4
}
```
- **Persistence:** Use `localStorage.setItem('macSpaceAcceleratorState', JSON.stringify(appState))` on state changes and `localStorage.getItem('macSpaceAcceleratorState')` on app load to retrieve saved settings.
ANIMATIONS & INTERACTIONS:
- **Core Switching:** STRICTLY NO ANIMATIONS. Instantaneous.
- **UI Elements:** Subtle transitions for toggles, buttons, and list item appearance/disappearance using Framer Motion or CSS transitions. Example: A smooth fade-in/out for the 'Save' confirmation, a slight scale-up on button hover.
- **Loading States:** If fetching any data (not applicable for MVP local storage but good practice), use subtle spinners or skeleton loaders.
- **Micro-interactions:** Provide visual feedback on shortcut definition (e.g., button briefly flashes when a new shortcut is registered).
EDGE CASES:
- **No Shortcuts Defined:** The UI should gracefully handle cases where no shortcuts are set, perhaps displaying a prompt to configure them.
- **Conflicting Shortcuts:** The application should ideally detect or warn the user about potential conflicts with existing macOS shortcuts or other applications. (Advanced, may be out of MVP scope).
- **Invalid Input:** Input fields for shortcuts should ideally validate input or provide clear instructions.
- **Animation Toggle State:** Ensure the toggle's state accurately reflects the system's setting (though direct system feedback might be limited without native integration).
- **Accessibility (a11y):** Use semantic HTML, ensure keyboard navigability for all interactive elements, provide ARIA labels where necessary, ensure sufficient color contrast.
- **First Launch:** Guide the user through the initial setup, possibly with a brief onboarding tour.
- **macOS Version Compatibility:** While targeting modern macOS, acknowledge potential differences in how animations are handled across versions. The native wrapper would be key here.
SAMPLE DATA:
1. **Mock Shortcut Mapping:**
```json
{
"1": "Cmd+Alt+1",
"2": "Cmd+Alt+2",
"3": "Ctrl+1",
"4": ""
}
```
2. **Mock Favorite Spaces:**
```json
[1, 4]
```
3. **Mock Total Spaces:**
`5`
4. **Mock Animation State (Enabled):**
`true`
5. **Mock App State (Complete):**
```json
{
"shortcuts": {
"1": "Cmd+1",
"2": "Cmd+2",
"3": "Option+3",
"4": ""
},
"disableAnimations": true,
"favoriteSpaces": [1, 2],
"totalSpaces": 4
}
```
6. **Mock UI Text - Settings Title:**
`"Space Accelerator Settings"`
7. **Mock UI Text - Animation Toggle Label:**
`"Disable macOS Space Animations"`
8. **Mock UI Text - Add Favorite Button:**
`"Add to Favorites"`
9. **Mock UI Text - Remove Favorite Button:**
`"Remove from Favorites"`
10. **Mock UI Text - Shortcut Input Placeholder:**
`"Press keys..."`
DEPLOYMENT NOTES:
- **Build Tool:** Vite (`vite build`) will generate optimized static assets.
- **Environment Variables:** While not strictly necessary for this local-first MVP, plan for variables like `VITE_APP_VERSION` if needed.
- **Native Wrapper:** For actual deployment as a macOS app, integrate with Electron or Tauri. This involves packaging the React build output and adding native code to handle background processes and system interactions (like global hotkeys).
- **Performance:** Keep the React component tree lean. Optimize Zustand selectors. Ensure `localStorage` operations are efficient. The primary goal is responsiveness, so avoid heavy computations on the main thread.
- **Installation:** Provide clear instructions for installing the native wrapper and the application itself, including any necessary macOS permissions (e.g., Accessibility access if required by the native layer for hotkeys).
- **Updates:** Consider a mechanism for checking and applying updates, especially for the native wrapper component.