You are an AI assistant tasked with building a single-page progressive web application (SPA) using React and Tailwind CSS. The application's goal is to help users manage their social media consumption and reduce digital addiction, inspired by the concerns raised in the Hacker News post about Meta and YouTube being found negligent.
**1. PROJECT OVERVIEW:**
The application, titled 'Digital Detox & Awareness Guide', aims to empower users to regain control over their digital lives. It addresses the growing problem of social media addiction by providing tools for monitoring usage, setting healthy limits, and fostering mindful engagement with technology. The core value proposition is to help users reduce screen time, improve focus, enhance mental well-being, and cultivate a more balanced relationship with their devices and online platforms.
**2. TECH STACK:**
- **Frontend Framework:** React (using Create React App for simplicity or Vite for faster builds).
- **Styling:** Tailwind CSS for rapid, utility-first styling.
- **State Management:** React Context API for simpler state management, potentially Zustand or Jotai for more complex global state if needed. For this MVP, Context API will suffice.
- **Routing:** React Router DOM for navigation within the SPA.
- **Local Storage:** Browser's `localStorage` API for persisting user settings and tracking data.
- **Date/Time Handling:** `date-fns` or `moment.js` (prefer `date-fns` for smaller bundle size) for managing time spent and setting limits.
- **Icons:** `react-icons` for a variety of icons.
- **Charting (Optional for MVP, consider for future):** `chart.js` with `react-chartjs-2` for visualizing usage data.
**3. CORE FEATURES:**
- **Usage Tracking & Analysis:**
- **User Flow:** On first launch, the app requests permission to track app usage (this would typically involve native capabilities or requires more complex setup; for this SPA MVP, we'll simulate this by allowing users to manually log time spent on specific apps or use browser history/active tab detection if feasible within a web context, acknowledging limitations of a pure web SPA for deep native app tracking).
- **Functionality:** Users can add 'tracked apps' (e.g., Instagram, TikTok, YouTube, Facebook). The app will display daily, weekly, and monthly usage statistics for each logged app and total screen time. Users can view charts and graphs of their usage patterns.
- **Smart Timer & Blocker:**
- **User Flow:** Users select an application from their tracked list, set a daily time limit (e.g., 'Instagram: 30 minutes/day'). Once the limit is reached, the app prompts the user about exceeding the limit and offers to block access to that app for the remainder of the day.
- **Functionality:** Enforces user-defined limits. When a limit is reached, the app interface for that specific tracked app (or a generic 'time's up' screen) becomes inaccessible until the next day. This requires careful state management to track daily resets.
- **Focus Mode:**
- **User Flow:** Users can initiate a 'Focus Session' of a predefined duration (e.g., 45 minutes). During this session, all notifications from selected distracting apps are silenced, and access to these apps might be temporarily restricted.
- **Functionality:** A timer counts down. A 'Focus Session' state is active, overriding normal app access rules. Users can choose which apps to 'block' during focus sessions. A 'pause' or 'end early' option should be available.
- **Mindful Usage Tips:**
- **User Flow:** A dedicated section or rotating tips displayed on the dashboard provide actionable advice on digital well-being, managing notifications, and understanding the impact of screen time.
- **Functionality:** Displays curated content. Tips can be fetched from a simple JSON array or a basic API if implemented.
**4. UI/UX DESIGN:**
- **Layout:** Single-page application with a main dashboard, a usage statistics section, a settings/limits section, and a focus mode control area. A clean, minimalist, and calming design aesthetic.
- **Color Palette:** Soft, muted colors. Primary: A calming blue or green (e.g., `#4A90E2` or `#50E3C2`). Secondary: Light grays and whites for backgrounds (e.g., `#F5F5F5`, `#FFFFFF`). Accent: A subtle orange or yellow for calls to action or highlighting warnings (e.g., `#F5A623`).
- **Typography:** Use a readable sans-serif font like 'Inter' or 'Manrope'. Define clear hierarchy for headings, subheadings, and body text.
- **Responsive Design:** Mobile-first approach. Ensure usability across various screen sizes, from small mobile phones to tablets and desktops. Use Flexbox and Grid for layout, and Tailwind's responsive modifiers (`sm:`, `md:`, `lg:`).
- **Navigation:** Simple top or side navigation bar. Clear visual cues for active states.
**5. DATA MODEL:**
- **`userData` (localStorage object):**
- `userId`: string (optional, for future sync)
- `trackedApps`: Array of objects
- `id`: string (e.g., 'com.instagram.android')
- `name`: string (e.g., 'Instagram')
- `iconUrl`: string (optional path to icon)
- `usageStats`: Object mapping app IDs to daily/weekly/monthly usage arrays
- e.g., `{'com.instagram.android': [{ date: '2023-10-27', timeSpent: 120000 }, ...]}` (time in milliseconds)
- `appLimits`: Object mapping app IDs to daily time limits in milliseconds
- e.g., `{'com.instagram.android': 1800000}` (30 minutes)
- `focusModeSettings`: Object
- `isActive`: boolean
- `startTime`: string (ISO format timestamp)
- `duration`: number (minutes)
- `blockedAppsDuringFocus`: Array of app IDs
- `mindfulTips`: Array of strings or objects { id, text, category }
- `settings`: Object
- `notificationsEnabled`: boolean
- `theme`: 'light' | 'dark'
**6. COMPONENT BREAKDOWN:**
- **`App.js`:** Main application component, sets up routing and global layout.
- **`DashboardPage.js`:** Landing page. Displays overview: total usage, progress towards limits, quick access to Focus Mode, and a featured mindful tip.
- **`UsageSummaryCard.js`:** Displays total daily/weekly usage.
- **`LimitProgressCard.js`:** Shows progress bars for apps with set limits.
- **`FocusModeToggle.js`:** Button/component to activate Focus Mode.
- **`MindfulTipCard.js`:** Displays a single mindful tip.
- **`UsageAnalyticsPage.js`:** Detailed breakdown of app usage.
- **`AppUsageList.js`:** Lists all tracked apps with their current usage stats.
- **`DetailedUsageChart.js`:** (If using charting library) Displays historical usage data.
- **`DateRangeSelector.js`:** Allows users to select date ranges for analysis.
- **`LimitsSettingsPage.js`:** Manage app limits and blocking.
- **`AppLimitSetter.js`:** Component to set/edit time limits for individual apps.
- **`AppBlockerList.js`:** Lists apps and allows toggling blocking status.
- **`FocusModePage.js`:** Dedicated page/modal for configuring and starting Focus Mode.
- **`FocusDurationSelector.js`:** Sets the duration for the focus session.
- **`FocusAppSelector.js`:** Selects which apps to block during focus.
- **`FocusTimerDisplay.js`:** Shows the countdown timer.
- **`SettingsPage.js`:** General application settings (e.g., theme, notification preferences).
- **`NavBar.js`:** Navigation links for different sections.
- **`Modal.js`:** Reusable modal component for confirmations, alerts, etc.
**7. ANIMATIONS & INTERACTIONS:**
- **Hover Effects:** Subtle background color changes or slight scaling on buttons and interactive elements.
- **Transitions:** Smooth transitions for opening/closing modals, expanding/collapsing sections, and route changes (if using a library that supports it, otherwise fades).
- **Loading States:** Use skeletons or spinners (`Tailwind CSS` animations) when fetching or processing data (e.g., loading usage stats).
- **Micro-interactions:** Visual feedback when setting a limit, activating focus mode (e.g., a subtle pulse or color change), or reaching a time limit (e.g., a gentle shake or color change on the progress bar).
- **Focus Mode:** A clear visual indicator when Focus Mode is active (e.g., a persistent banner or screen overlay). Countdown timer animation.
**8. EDGE CASES:**
- **Empty States:** When no apps are tracked, or no usage data is available, display informative messages and clear calls to action (e.g., 'Start tracking apps by adding them in Settings').
- **Error Handling:** Gracefully handle potential errors with `localStorage` (e.g., storage full, access denied) and display user-friendly messages.
- **Validation:** Ensure time limits and focus durations are valid positive numbers. Prevent negative inputs or excessively large values.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure sufficient color contrast. Make sure all interactive elements are keyboard-navigable and have appropriate ARIA attributes. Test with screen readers.
- **Permissions (Web Context):** Clearly explain why certain permissions (like usage tracking) are needed. Since a pure SPA has limitations, clearly communicate what can and cannot be tracked automatically and provide manual logging as an alternative.
- **Time Synchronization:** Ensure daily resets for limits occur correctly based on the user's local time, not server time.
**9. SAMPLE DATA:**
```json
{
"userData": {
"trackedApps": [
{"id": "com.instagram.android", "name": "Instagram", "iconUrl": "/icons/instagram.png"},
{"id": "com.zhiliaoapp.musically", "name": "TikTok", "iconUrl": "/icons/tiktok.png"},
{"id": "com.google.android.youtube", "name": "YouTube", "iconUrl": "/icons/youtube.png"}
],
"usageStats": {
"com.instagram.android": [
{"date": "2023-10-26", "timeSpent": 7200000},
{"date": "2023-10-27", "timeSpent": 5400000}
],
"com.zhiliaoapp.musically": [
{"date": "2023-10-26", "timeSpent": 9000000},
{"date": "2023-10-27", "timeSpent": 6300000}
],
"com.google.android.youtube": [
{"date": "2023-10-26", "timeSpent": 3600000},
{"date": "2023-10-27", "timeSpent": 4500000}
]
},
"appLimits": {
"com.instagram.android": 1800000,
"com.zhiliaoapp.musically": 3600000
},
"focusModeSettings": {
"isActive": false,
"startTime": null,
"duration": 45,
"blockedAppsDuringFocus": ["com.instagram.android", "com.zhiliaoapp.musically"]
},
"mindfulTips": [
{"id": 1, "text": "Schedule short breaks during long work sessions to stretch and rest your eyes.", "category": "Breaks"},
{"id": 2, "text": "Turn off non-essential notifications to minimize interruptions and stay focused.", "category": "Notifications"},
{"id": 3, "text": "Designate specific times of day for checking social media, rather than doing it reactively.", "category": "Social Media"}
],
"settings": {
"notificationsEnabled": true,
"theme": "light"
}
}
}
```
**10. DEPLOYMENT NOTES:**
- Use `npm run build` or `yarn build` to create a production-ready build.
- Configure environment variables (e.g., API keys if used) via `.env` files.
- For deployment, choose a static hosting service like Netlify, Vercel, or GitHub Pages.
- Optimize images and code for performance. Consider code-splitting if the application grows significantly.
- Ensure SSL is enabled for secure data transmission (HTTPS).
- Implement PWA features (service workers, manifest.json) for offline capabilities and installability.