feat: Add custom accent color picker and random theme generator

CUSTOMIZATION_FEATURES.md

@@ -0,0 +1,134 @@
+# Custom Accent Color Picker & Random Theme Generator
+
+## Overview
+This document describes the new personalization features added to the GitHub Avatar Frame API project.
+
+## Features Added
+
+### 1. Custom Accent Color Picker 🎨
+- **Location**: Added below the theme selection area in the "Customization & Discovery" section
+- **Functionality**: 
+  - Color picker input for selecting custom accent colors
+  - Quick color presets with 6 popular colors
+  - Reset button to restore default theme colors
+  - Real-time preview with CSS variables
+- **API Integration**: Custom colors are passed via `accentColor` parameter to the backend
+- **Backend Processing**: Uses Sharp.js to apply color tinting and modulation to frames
+
+### 2. Random Theme Generator 🎲
+- **Location**: Next to the color picker in the "Customization & Discovery" section
+- **Functionality**:
+  - Randomly selects one of the available themes
+  - 30% chance to also randomize accent color for extra variety
+  - Toast notifications for user feedback
+  - Disabled state when no themes are available
+- **User Experience**: 
+  - "✨ Surprise Style Loaded!" for theme-only randomization
+  - "🎲 Random Theme + Color Applied!" when both theme and color are randomized
+
+### 3. Toast Notification System
+- **Design**: Slide-in animation from the right
+- **Duration**: 3 seconds auto-dismiss
+- **Styling**: Matches the app's design system with proper dark/light mode support
+- **Usage**: Provides feedback for random theme selection and color reset actions
+
+## Technical Implementation
+
+### Frontend (React)
+- Added state management for `customAccentColor`, `originalThemeColor`, and toast notifications
+- Updated API URL generation to include accent color parameter
+- Enhanced UI with responsive design for mobile and desktop
+- Added CSS animations for toast notifications
+
+### Backend (Node.js/Sharp.js)
+- Added `accentColor` query parameter handling
+- Implemented color processing using Sharp.js:
+  - Hex to RGB conversion
+  - Color tinting with custom colors
+  - Brightness and saturation modulation for better visual results
+
+### API Endpoints
+- Updated `/api/framed-avatar/{username}` to accept `accentColor` parameter
+- Example: `?theme=minimal&accentColor=%23ff6b6b&size=256`
+
+## System Architecture Flow
+
+```
+User Interface
+├── Theme Selection (existing)
+├── Custom Color Picker (new)
+│   ├── Color Input Field
+│   ├── Quick Color Presets
+│   └── Reset Button
+├── Random Theme Generator (new)
+│   ├── Random Theme Selection
+│   └── Optional Random Color (30% chance)
+└── Toast Notifications (new)
+
+API Request
+├── theme: selected theme
+├── accentColor: custom color (optional)
+├── size, canvas, shape, radius (existing)
+└── style (existing)
+
+Backend Processing
+├── Fetch GitHub Avatar
+├── Load Theme Frame
+├── Apply Custom Color Tint (if provided)
+│   ├── Convert hex to RGB
+│   ├── Apply color modulation
+│   └── Enhance brightness/saturation
+└── Composite Final Image
+
+Response
+└── Framed Avatar with Custom Colors
+```
+
+## User Experience Enhancements
+
+### Quick Color Presets
+Six predefined colors for easy selection:
+- Purple: `#7c3aed`
+- Pink: `#ec4899` 
+- Orange: `#f97316`
+- Green: `#10b981`
+- Blue: `#3b82f6`
+- Violet: `#8b5cf6`
+
+### Responsive Design
+- Color picker and controls adapt to mobile screens
+- Proper spacing and alignment across different screen sizes
+- Touch-friendly button sizes
+
+### Accessibility
+- Proper ARIA labels and tooltips
+- Keyboard navigation support
+- Color contrast compliance
+
+## Future Enhancements
+- Save custom color combinations
+- Export/import color themes
+- Color history for recently used colors
+- Advanced color picker with HSL/HSV support
+- Theme preview with custom colors before generation
+
+## Usage Examples
+
+### Basic Custom Color
+1. Select a theme (e.g., "minimal")
+2. Click the color picker and choose a custom color
+3. Generate the avatar with the custom accent color
+
+### Quick Color Selection
+1. Use the quick color presets for instant color changes
+2. Colors are applied immediately without opening the color picker
+
+### Random Theme Discovery
+1. Click "🎲 Random Theme" to discover new themes
+2. Sometimes includes random accent colors for extra variety
+3. Toast notification confirms the selection
+
+### Reset to Default
+1. When a custom color is selected, a "↻ Reset" button appears
+2. Click to restore the original theme colors
+3. Toast notification confirms the reset

QUICK_PUSH_COMMANDS.md

@@ -0,0 +1,68 @@
+# 🚀 Quick Push Commands
+
+## ⚡ Fast Track to Push
+
+### 1. Check Status
+```bash
+git status
+```
+
+### 2. Add All Changes
+```bash
+git add .
+```
+
+### 3. Commit with Feature Description
+```bash
+git commit -m "feat: Add custom accent color picker and random theme generator
+
+- Add custom accent color picker with hex color support
+- Add 6 quick color presets for instant selection
+- Add random theme generator with optional color randomization
+- Add reset to default color functionality
+- Add toast notification system with animations
+- Update API to support accentColor parameter with Sharp.js processing
+- Enhance UI with responsive design and accessibility features"
+```
+
+### 4. Push to Repository
+```bash
+git push origin main
+```
+
+## 🔄 Alternative: Feature Branch
+
+### Create Feature Branch
+```bash
+git checkout -b feature/custom-color-picker
+git add .
+git commit -m "feat: Add custom accent color picker and random theme generator"
+git push origin feature/custom-color-picker
+```
+
+## 🧪 Quick Test Before Push
+
+### Start Servers
+```bash
+# Terminal 1
+npm run dev
+
+# Terminal 2  
+cd client
+npm run dev
+```
+
+### Test Features
+- Open `http://localhost:5173`
+- Test color picker
+- Test random theme generator
+- Generate avatar with custom color
+
+## ✅ Ready to Push!
+
+Your new features are ready:
+- 🎨 Custom accent color picker
+- 🎲 Random theme generator
+- ✨ Toast notifications
+- 📱 Responsive design
+- 🔧 API enhancement

api/frames.js

@@ -13,7 +13,8 @@ export default async function handler(req, res) {
     const username = req.query.username;
     const theme = req.query.theme || "base";
     const size = Math.max(64, Math.min(Number(req.query.size || 256), 1024));
-    const canvas= req.query.canvas || "light";
+    const canvas = req.query.canvas || "light";
+    const accentColor = req.query.accentColor || null;
     // Validate username
     if (!username || typeof username !== "string" || username.trim() === "") {
       return res.status(400).json({ error: "Username is required" });
@@ -82,10 +83,24 @@ export default async function handler(req, res) {
       .toBuffer();
     // only resize frame if it was successfully loaded
     if(frameBuffer){
-     frameResized = await sharp(frameBuffer)
-      .resize(size, size)
-      .png()
-      .toBuffer();
+      let frameProcessor = sharp(frameBuffer).resize(size, size);
+
+      // Apply custom accent color if provided
+      if (accentColor) {
+        // Convert hex color to RGB for processing
+        const hex = accentColor.replace('#', '');
+        const r = parseInt(hex.substr(0, 2), 16);
+        const g = parseInt(hex.substr(2, 2), 16);
+        const b = parseInt(hex.substr(4, 2), 16);
+
+        // Apply color tint to the frame
+        frameProcessor = frameProcessor.modulate({
+          brightness: 1.1, // Slightly brighten
+          saturation: 1.3, // Increase saturation
+        }).tint({ r, g, b });
+      }
+
+      frameResized = await frameProcessor.png().toBuffer();
     }
     // composition logic for transparency and avatar clipping
     let imageProcessor;