diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md
new file mode 100644
index 0000000..1c151a5
--- /dev/null
+++ b/USAGE_GUIDE.md
@@ -0,0 +1,219 @@
+# Calendar Component Usage Guide
+
+## 🎨 Custom Color Schemes
+
+### Basic Active Colors (Simple)
+For highlighting specific dates with custom colors:
+
+```tsx
+import { Year, ActiveColors } from 'react-calendario';
+
+const activeColors: ActiveColors = {
+  headerBg: '#D4EDDA',
+  headerColor: '#155724',
+  contentBg: '#28A745',
+  contentColor: '#FFFFFF'
+};
+
+<Year 
+  year={2025}
+  activeDates={[new Date(2025, 0, 1), new Date(2025, 11, 25)]}
+  activeColors={activeColors}
+/>
+```
+
+### Comprehensive Color Scheme (Advanced)
+Full control over colors for every state and day type:
+
+```tsx
+import { Year, ColorScheme } from 'react-calendario';
+
+const colorScheme: ColorScheme = [
+  // Weekday colors
+  { 
+    type: 'weekday', 
+    state: 'default',  // Normal weekday
+    colors: { 
+      header: { backgroundColor: '#2c3e50', color: '#ffffff' },
+      content: { backgroundColor: '#ffffff', color: '#2c3e50' }
+    }
+  },
+  { 
+    type: 'weekday', 
+    state: 'rangeStart',  // First day of selected range
+    colors: {
+      header: { backgroundColor: '#2980b9', color: '#ffffff' },
+      content: { backgroundColor: '#3498db', color: '#ffffff' }
+    }
+  },
+  { 
+    type: 'weekday', 
+    state: 'rangeMid',  // Middle days of selected range
+    colors: {
+      header: { backgroundColor: '#5dade2', color: '#ffffff' },
+      content: { backgroundColor: '#aed6f1', color: '#1a5490' }
+    }
+  },
+  
+  // Weekend colors
+  { 
+    type: 'weekend', 
+    state: 'default',  // Normal weekend
+    colors: {
+      header: { backgroundColor: '#7f8c8d', color: '#ffffff' },
+      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
+    }
+  },
+  { 
+    type: 'weekend', 
+    state: 'rangeStart',  // Weekend that starts a range
+    colors: {
+      header: { backgroundColor: '#2980b9', color: '#ffffff' },
+      content: { backgroundColor: '#3498db', color: '#ffffff' }
+    }
+  },
+  // ... more states
+];
+
+<Year 
+  year={2025}
+  colorScheme={colorScheme}
+/>
+```
+
+#### Available States:
+- `default` - Normal day appearance
+- `selected` - Day is part of a completed selection (deprecated, use `rangeMid`)
+- `selecting` - Day is being hovered during selection (important for weekends!)
+- `rangeStart` - First day of a range
+- `rangeEnd` - Last day of a range  
+- `rangeMid` - Middle days of a selected range
+- `active` - Special highlighted days (holidays, events)
+
+#### Day Types:
+- `weekday` - Monday through Friday
+- `weekend` - Saturday and Sunday (or custom weekend days)
+
+## 🌍 Locale Support
+
+### Basic Usage
+```tsx
+import { Year } from 'react-calendario';
+import { fr, de, ja, es } from 'date-fns/locale';
+
+// French
+<Year year={2025} locale={fr} />
+
+// German
+<Year year={2025} locale={de} />
+
+// Japanese
+<Year year={2025} locale={ja} />
+
+// Spanish
+<Year year={2025} locale={es} />
+```
+
+### What Gets Localized:
+- Month names (January → Janvier → Januar → 一月)
+- Day headers based on style:
+  - `expanded`: Full names (MONDAY → LUNDI → MONTAG)
+  - `compacted`: 3-letter (MON → LUN → MO)
+  - `tiny`: Single letter (M → L → M)
+- Date formats in tooltips and labels
+
+### Available Locales:
+All date-fns locales are supported. Common ones include:
+- `enUS` - English (US) - Default
+- `es` - Spanish
+- `fr` - French
+- `de` - German
+- `it` - Italian
+- `pt` - Portuguese
+- `ja` - Japanese
+- `ko` - Korean
+- `zhCN` - Chinese (Simplified)
+- `ru` - Russian
+- `ar` - Arabic
+- `nl` - Dutch
+- `pl` - Polish
+- `tr` - Turkish
+- `sv` - Swedish
+- `nb` - Norwegian
+
+## 🎯 Combined Example
+
+Using both features together:
+
+```tsx
+import { Year, ColorScheme } from 'react-calendario';
+import { fr } from 'date-fns/locale';
+
+const frenchHolidayScheme: ColorScheme = [
+  // Regular days with French aesthetic
+  { 
+    type: 'weekday', 
+    state: 'default',
+    colors: { 
+      header: { backgroundColor: '#002395', color: '#ffffff' },  // French blue
+      content: { backgroundColor: '#ffffff', color: '#002395' }
+    }
+  },
+  // Weekends in subtle gray
+  { 
+    type: 'weekend', 
+    state: 'default',
+    colors: {
+      header: { backgroundColor: '#95a5a6', color: '#ffffff' },
+      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
+    }
+  },
+  // French holidays in red
+  { 
+    type: 'weekday', 
+    state: 'active',
+    colors: {
+      header: { backgroundColor: '#ed2939', color: '#ffffff' },  // French red
+      content: { backgroundColor: '#c0392b', color: '#ffffff' }
+    }
+  },
+  { 
+    type: 'weekend', 
+    state: 'active',
+    colors: {
+      header: { backgroundColor: '#c0392b', color: '#ffffff' },
+      content: { backgroundColor: '#ed2939', color: '#ffffff' }
+    }
+  }
+];
+
+const frenchHolidays = [
+  new Date(2025, 0, 1),   // Jour de l'An
+  new Date(2025, 4, 1),   // Fête du Travail
+  new Date(2025, 6, 14),  // Fête Nationale
+  new Date(2025, 11, 25)  // Noël
+];
+
+<Year 
+  year={2025}
+  locale={fr}
+  colorScheme={frenchHolidayScheme}
+  activeDates={frenchHolidays}
+  dayHeaderStyle="compacted"
+/>
+```
+
+## 📝 Tips
+
+1. **Color Scheme Fallbacks**: You don't need to define every state. The system intelligently falls back:
+   - Weekend states → Weekday states of same type
+   - Missing states → Default state
+   - Weekend default → Weekday default
+
+2. **Performance**: ColorScheme is more efficient than inline styles for large calendars
+
+3. **Accessibility**: Ensure sufficient color contrast between background and text colors
+
+4. **Locale + Colors**: Combine locale with themed colors for culturally appropriate calendars
+
+5. **Weekend Customization**: Weekend days are automatically detected and styled differently, including when they're part of a selected range
\ No newline at end of file
diff --git a/src/examples/ComprehensiveColorScheme.tsx b/src/examples/ComprehensiveColorScheme.tsx
index 6ff182e..0e60e84 100644
--- a/src/examples/ComprehensiveColorScheme.tsx
+++ b/src/examples/ComprehensiveColorScheme.tsx
@@ -64,6 +64,14 @@ export const ComprehensiveColorScheme: React.FC = () => {
         header: { backgroundColor: '#5dade2', color: '#ffffff' },
         content: { backgroundColor: '#d4e6f1', color: '#2874a6' }
       }},
+      { type: 'weekend', state: 'selecting', colors: {
+        header: { backgroundColor: '#aab7b8', color: '#ffffff' },
+        content: { backgroundColor: '#d5dbdb', color: '#5d6d7e' }
+      }},
+      { type: 'weekend', state: 'rangeMid', colors: {
+        header: { backgroundColor: '#85c1e9', color: '#ffffff' },
+        content: { backgroundColor: '#d6eaf8', color: '#21618c' }
+      }},
       { type: 'weekend', state: 'rangeStart', colors: {
         header: { backgroundColor: '#2980b9', color: '#ffffff' },
         content: { backgroundColor: '#3498db', color: '#ffffff' }
@@ -114,6 +122,22 @@ export const ComprehensiveColorScheme: React.FC = () => {
         header: { backgroundColor: '#ffc107', color: '#000000' },
         content: { backgroundColor: '#fff8e1', color: '#f57f17' }
       }},
+      { type: 'weekend', state: 'selecting', colors: {
+        header: { backgroundColor: '#ce93d8', color: '#ffffff' },
+        content: { backgroundColor: '#f3e5f5', color: '#6a1b9a' }
+      }},
+      { type: 'weekend', state: 'rangeMid', colors: {
+        header: { backgroundColor: '#ffca28', color: '#000000' },
+        content: { backgroundColor: '#fff9c4', color: '#f57c00' }
+      }},
+      { type: 'weekend', state: 'rangeStart', colors: {
+        header: { backgroundColor: '#ff6f00', color: '#ffffff' },
+        content: { backgroundColor: '#ff9800', color: '#ffffff' }
+      }},
+      { type: 'weekend', state: 'rangeEnd', colors: {
+        header: { backgroundColor: '#ff6f00', color: '#ffffff' },
+        content: { backgroundColor: '#ff9800', color: '#ffffff' }
+      }},
       { type: 'weekend', state: 'active', colors: {
         header: { backgroundColor: '#006064', color: '#ffffff' },
         content: { backgroundColor: '#00acc1', color: '#ffffff' }
@@ -152,6 +176,26 @@ export const ComprehensiveColorScheme: React.FC = () => {
         header: { backgroundColor: '#fafafa', color: '#666666' },
         content: { backgroundColor: '#f0f0f0', color: '#666666' }
       }},
+      { type: 'weekend', state: 'selected', colors: {
+        header: { backgroundColor: '#e0e0e0', color: '#212121' },
+        content: { backgroundColor: '#f5f5f5', color: '#212121' }
+      }},
+      { type: 'weekend', state: 'selecting', colors: {
+        header: { backgroundColor: '#eeeeee', color: '#424242' },
+        content: { backgroundColor: '#fafafa', color: '#757575' }
+      }},
+      { type: 'weekend', state: 'rangeMid', colors: {
+        header: { backgroundColor: '#b0b0b0', color: '#ffffff' },
+        content: { backgroundColor: '#d0d0d0', color: '#424242' }
+      }},
+      { type: 'weekend', state: 'rangeStart', colors: {
+        header: { backgroundColor: '#424242', color: '#ffffff' },
+        content: { backgroundColor: '#757575', color: '#ffffff' }
+      }},
+      { type: 'weekend', state: 'rangeEnd', colors: {
+        header: { backgroundColor: '#424242', color: '#ffffff' },
+        content: { backgroundColor: '#757575', color: '#ffffff' }
+      }},
       { type: 'weekend', state: 'active', colors: {
         header: { backgroundColor: '#212121', color: '#ffffff' },
         content: { backgroundColor: '#424242', color: '#ffffff' }