mirror of
https://github.com/soconnor0919/beenvoice.git
synced 2025-12-14 01:54:43 -05:00
Add Turso/Vercel deployment configuration
- Updated database connection to support Turso auth token - Added vercel.json with bun build configuration - Updated environment schema for production deployment - Added new features and components for production readiness
This commit is contained in:
303
DARK_MODE_GUIDE.md
Normal file
303
DARK_MODE_GUIDE.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Dark Mode Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
BeenVoice implements a **media query-based dark mode** system that automatically adapts to the user's system preferences. This approach provides a seamless experience without requiring manual theme switching controls.
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### Media Query-Based vs Class-Based
|
||||
|
||||
We chose **media query-based** dark mode (`@media (prefers-color-scheme: dark)`) over class-based dark mode for the following reasons:
|
||||
|
||||
- **Automatic System Integration**: Respects user's OS/browser theme preference
|
||||
- **No JavaScript Required**: Pure CSS solution with better performance
|
||||
- **Better Accessibility**: Follows system accessibility settings
|
||||
- **Seamless Experience**: No flash of incorrect theme on page load
|
||||
- **Reduced Complexity**: No need for theme toggle components or state management
|
||||
|
||||
## Configuration Changes
|
||||
|
||||
### 1. Tailwind CSS Configuration
|
||||
|
||||
**File:** `tailwind.config.ts`
|
||||
|
||||
```typescript
|
||||
export default {
|
||||
darkMode: "media", // Changed from "class" to "media"
|
||||
// ... rest of config
|
||||
} satisfies Config;
|
||||
```
|
||||
|
||||
### 2. Global CSS Updates
|
||||
|
||||
**File:** `src/styles/globals.css`
|
||||
|
||||
Key changes made:
|
||||
|
||||
- Replaced `.dark { }` class selector with `@media (prefers-color-scheme: dark) { :root { } }`
|
||||
- Maintained all existing CSS custom properties
|
||||
- Updated dark mode color definitions to use media queries
|
||||
|
||||
```css
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--background: oklch(0.145 0 0);
|
||||
--foreground: oklch(0.985 0 0);
|
||||
--card: oklch(0.205 0 0);
|
||||
/* ... all other dark mode variables */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Component Updates
|
||||
|
||||
### Core Layout Components
|
||||
|
||||
#### 1. Root Layout (`src/app/layout.tsx`)
|
||||
- Updated background gradients with dark mode variants
|
||||
- Improved layering structure for background effects
|
||||
- Added proper z-index management
|
||||
|
||||
#### 2. Landing Page (`src/app/page.tsx`)
|
||||
- Comprehensive dark mode classes for all sections
|
||||
- Updated text colors, backgrounds, and hover states
|
||||
- Maintained brand consistency with green color scheme
|
||||
|
||||
#### 3. Authentication Pages
|
||||
- **Sign In Page** (`src/app/auth/signin/page.tsx`)
|
||||
- **Register Page** (`src/app/auth/register/page.tsx`)
|
||||
|
||||
Both pages updated with:
|
||||
- Dark background gradients
|
||||
- Card component dark backgrounds
|
||||
- Input field icon colors
|
||||
- Text color variations
|
||||
- Link hover states
|
||||
|
||||
### Navigation Components
|
||||
|
||||
#### 1. Navbar (`src/components/Navbar.tsx`)
|
||||
- Glass morphism effect with dark background support
|
||||
- Button variant adaptations
|
||||
- Text color adjustments for user information
|
||||
|
||||
#### 2. Sidebar (`src/components/Sidebar.tsx`)
|
||||
- Dark background with transparency
|
||||
- Navigation link states (active/hover)
|
||||
- Border color adaptations
|
||||
- Icon and text color updates
|
||||
|
||||
#### 3. Mobile Sidebar (`src/components/SidebarTrigger.tsx`)
|
||||
- Sheet component dark styling
|
||||
- Navigation link consistency with desktop sidebar
|
||||
- Border and background adaptations
|
||||
|
||||
### Dashboard Components
|
||||
|
||||
#### 1. Dashboard Page (`src/app/dashboard/page.tsx`)
|
||||
- Welcome text color adjustments
|
||||
- Maintained gradient text effects
|
||||
|
||||
#### 2. Universal Table (`src/components/ui/universal-table.tsx`)
|
||||
- Comprehensive table styling updates
|
||||
- Header background and text colors
|
||||
- Cell content color adaptations
|
||||
- Status badge color schemes
|
||||
- Pagination control styling
|
||||
- Grid view card backgrounds
|
||||
|
||||
## Color System
|
||||
|
||||
### Text Colors
|
||||
- **Primary Text**: `text-gray-900 dark:text-white`
|
||||
- **Secondary Text**: `text-gray-700 dark:text-gray-300`
|
||||
- **Muted Text**: `text-gray-500 dark:text-gray-400`
|
||||
- **Icon Colors**: `text-gray-400 dark:text-gray-500`
|
||||
|
||||
### Background Colors
|
||||
- **Card Backgrounds**: `dark:bg-gray-800`
|
||||
- **Hover States**: `hover:bg-gray-100 dark:hover:bg-gray-800`
|
||||
- **Border Colors**: `border-gray-200 dark:border-gray-700`
|
||||
- **Glass Effects**: `bg-white/60 dark:bg-gray-900/60`
|
||||
|
||||
### Brand Colors
|
||||
Maintained consistent green brand colors with dark mode adaptations:
|
||||
- **Primary Green**: `text-green-600 dark:text-green-400`
|
||||
- **Emerald Accents**: `bg-emerald-100 dark:bg-emerald-900/30`
|
||||
|
||||
## Testing the Implementation
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. **System Theme Toggle**:
|
||||
- Change your OS dark/light mode setting
|
||||
- Verify automatic theme switching
|
||||
- Check for smooth transitions
|
||||
|
||||
2. **Page Coverage**:
|
||||
- Landing page
|
||||
- Authentication pages (sign in/register)
|
||||
- Dashboard and navigation
|
||||
- All table views and components
|
||||
|
||||
3. **Component Testing**:
|
||||
- Form elements (inputs, buttons, selects)
|
||||
- Cards and containers
|
||||
- Navigation states (hover, active)
|
||||
- Text readability in both modes
|
||||
|
||||
### Browser Developer Tools
|
||||
|
||||
1. **Media Query Testing**:
|
||||
```css
|
||||
/* In DevTools Console */
|
||||
document.documentElement.style.colorScheme = 'dark';
|
||||
document.documentElement.style.colorScheme = 'light';
|
||||
```
|
||||
|
||||
2. **Emulation**:
|
||||
- Chrome DevTools > Rendering > Emulate CSS prefers-color-scheme
|
||||
- Firefox DevTools > Settings > Dark theme simulation
|
||||
|
||||
### Test Component
|
||||
|
||||
A comprehensive test component is available at `src/components/dark-mode-test.tsx` that displays:
|
||||
- Color variations
|
||||
- Button states
|
||||
- Form elements
|
||||
- Status indicators
|
||||
- Background patterns
|
||||
- Icon colors
|
||||
|
||||
## Best Practices for Future Development
|
||||
|
||||
### 1. Color Class Patterns
|
||||
|
||||
Always pair light mode colors with dark mode variants:
|
||||
|
||||
```tsx
|
||||
// ✅ Good
|
||||
<div className="text-gray-900 dark:text-white bg-white dark:bg-gray-800">
|
||||
|
||||
// ❌ Avoid
|
||||
<div className="text-gray-900 bg-white">
|
||||
```
|
||||
|
||||
### 2. Common Patterns
|
||||
|
||||
**Text Colors:**
|
||||
```tsx
|
||||
// Primary text
|
||||
className="text-gray-900 dark:text-white"
|
||||
|
||||
// Secondary text
|
||||
className="text-gray-700 dark:text-gray-300"
|
||||
|
||||
// Muted text
|
||||
className="text-gray-500 dark:text-gray-400"
|
||||
```
|
||||
|
||||
**Backgrounds:**
|
||||
```tsx
|
||||
// Card backgrounds
|
||||
className="bg-white dark:bg-gray-800"
|
||||
|
||||
// Hover states
|
||||
className="hover:bg-gray-100 dark:hover:bg-gray-800"
|
||||
|
||||
// Borders
|
||||
className="border-gray-200 dark:border-gray-700"
|
||||
```
|
||||
|
||||
**Interactive Elements:**
|
||||
```tsx
|
||||
// Links
|
||||
className="text-green-600 hover:text-green-700 dark:text-green-400 dark:hover:text-green-300"
|
||||
|
||||
// Active states
|
||||
className="bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400"
|
||||
```
|
||||
|
||||
### 3. Component Development Guidelines
|
||||
|
||||
1. **Always test both modes** during development
|
||||
2. **Use semantic color tokens** from the design system when possible
|
||||
3. **Maintain sufficient contrast** for accessibility
|
||||
4. **Consider glass morphism effects** with appropriate alpha values
|
||||
5. **Test with real content** to ensure readability
|
||||
|
||||
### 4. shadcn/ui Components
|
||||
|
||||
Most shadcn/ui components already include dark mode support:
|
||||
- Button variants adapt automatically
|
||||
- Input fields use CSS custom properties
|
||||
- Card components respond to theme changes
|
||||
|
||||
For custom components, follow the established patterns.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Colors Not Switching**:
|
||||
- Verify `darkMode: "media"` in `tailwind.config.ts`
|
||||
- Check CSS custom properties are properly defined
|
||||
- Ensure no conflicting class-based dark mode styles
|
||||
|
||||
2. **Flash of Incorrect Theme**:
|
||||
- Should not occur with media query approach
|
||||
- If present, check for JavaScript theme switching code
|
||||
|
||||
3. **Incomplete Styling**:
|
||||
- Search for hardcoded colors: `text-gray-XXX` without `dark:` variants
|
||||
- Use component test page to verify all elements
|
||||
|
||||
4. **Performance Issues**:
|
||||
- Media query approach should have no performance impact
|
||||
- CSS variables resolve efficiently
|
||||
|
||||
### Debugging Tools
|
||||
|
||||
1. **CSS Custom Properties Inspector**:
|
||||
```javascript
|
||||
// In DevTools Console
|
||||
getComputedStyle(document.documentElement).getPropertyValue('--background')
|
||||
```
|
||||
|
||||
2. **Media Query Detection**:
|
||||
```javascript
|
||||
// Check current preference
|
||||
window.matchMedia('(prefers-color-scheme: dark)').matches
|
||||
```
|
||||
|
||||
## Browser Support
|
||||
|
||||
The media query-based approach is supported in:
|
||||
- Chrome 76+
|
||||
- Firefox 67+
|
||||
- Safari 12.1+
|
||||
- Edge 79+
|
||||
|
||||
For older browsers, the light theme serves as a fallback.
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Checks
|
||||
|
||||
1. **New Component Integration**: Ensure new components follow dark mode patterns
|
||||
2. **Third-party Components**: Verify external components adapt to theme
|
||||
3. **Asset Updates**: Check images/icons work in both modes
|
||||
4. **Performance Monitoring**: Ensure no CSS bloat from unused dark mode classes
|
||||
|
||||
### Updates and Migration
|
||||
|
||||
If future requirements need class-based dark mode:
|
||||
1. Update `tailwind.config.ts` to `darkMode: "class"`
|
||||
2. Add theme toggle component
|
||||
3. Implement theme persistence
|
||||
4. Update CSS to use `.dark` selector instead of media queries
|
||||
|
||||
## Conclusion
|
||||
|
||||
The media query-based dark mode implementation provides a robust, performant, and user-friendly theming solution that automatically adapts to user preferences while maintaining design consistency and accessibility standards.
|
||||
Reference in New Issue
Block a user