@waaelg/dga-design-system 0.4.2

package/docs/foundations/colors-swatches.md

@@ -0,0 +1,441 @@
+# Colors — Swatches
+
+Visual hex reference for all DGA palettes. Full guide: [colors.md](./colors.md) · Cheatsheet: [colors-cheatsheet.md](./colors-cheatsheet.md)
+
+---
+
+## 🎨 Color Palettes Overview
+
+The DGA Design System includes **8 color palettes** with **12 shades each** (25-950), totaling **96 colors**.
+
+---
+
+## Gray (Neutral Palette)
+
+```
+█ 25   #fcfcfd  │ Body background, subtle tint
+█ 50   #f9fafb  │ Light background, cards
+█ 100  #f3f4f6  │ Hover states, disabled backgrounds
+█ 200  #e5e7eb  │ Borders, dividers ⭐
+█ 300  #d2d6db  │ Strong dividers
+█ 400  #9da4ae  │ Placeholder text, icons
+█ 500  #6c737f  │ Secondary icons
+█ 600  #4d5761  │ Muted text ⭐
+█ 700  #384250  │ Secondary text ⭐
+█ 800  #1f2a37  │ Emphasis, headings
+█ 900  #111927  │ Dark backgrounds
+█ 950  #0d121c  │ Primary text, maximum contrast ⭐
+```
+
+**Primary Uses:** Text hierarchy, backgrounds, borders
+
+---
+
+## Primary - Saudi Green 🇸🇦 (Brand Palette)
+
+```
+█ 25   #f7fdf9  │ Subtle green tint
+█ 50   #f3fcf6  │ Light green background
+█ 100  #dff6e7  │ Success message backgrounds
+█ 200  #b8eacb  │ Hover states, light accent
+█ 300  #88d8ad  │ Active states, decorative
+█ 400  #54c08a  │ Vibrant decorative
+█ 500  #25935f  │ MAIN SAUDI GREEN ⭐⭐⭐
+█ 600  #1b8354  │ Primary hover ⭐
+█ 700  #166a45  │ Primary active ⭐
+█ 800  #14573a  │ Brand text ⭐
+█ 900  #104631  │ Dark brand accent
+█ 950  #092a1e  │ Maximum contrast
+```
+
+**Main Color:** `#25935f` (500 shade)  
+**Primary Uses:** Buttons, links, brand elements, CTAs
+
+---
+
+## Gold (Secondary Palette)
+
+```
+█ 25   #fffef7  │ Subtle gold tint
+█ 50   #fffef2  │ Light gold background
+█ 100  #fffce6  │ Highlight backgrounds
+█ 200  #fcf3bd  │ Soft accent
+█ 300  #fae996  │ Decorative elements
+█ 400  #f7d54d  │ Vibrant gold
+█ 500  #f5bd02  │ MAIN GOLD ⭐⭐
+█ 600  #dba102  │ Gold hover
+█ 700  #b87b02  │ Gold active
+█ 800  #945c01  │ Gold text
+█ 900  #6e3c00  │ Dark gold
+█ 950  #472400  │ Maximum contrast
+```
+
+**Main Color:** `#f5bd02` (500 shade)  
+**Primary Uses:** Secondary buttons, badges, accents, premium features
+
+---
+
+## Lavender (Accent Palette)
+
+```
+█ 25   #fefcff  │ Subtle lavender
+█ 50   #f9f5fa  │ Light lavender background
+█ 100  #f2e9f5  │ Soft accent backgrounds
+█ 200  #e1cce8  │ Decorative
+█ 300  #ccadd9  │ Hover states
+█ 400  #a57bba  │ Active states
+█ 500  #80519f  │ MAIN LAVENDER ⭐
+█ 600  #6d428f  │ Emphasis
+█ 700  #532d75  │ Strong accent
+█ 800  #3d1d5e  │ Lavender text
+█ 900  #281047  │ Dark lavender
+█ 950  #16072e  │ Maximum contrast
+```
+
+**Main Color:** `#80519f` (500 shade)  
+**Primary Uses:** Special highlights, tertiary elements, decorative accents
+
+---
+
+## Error/Danger (Red Palette)
+
+```
+█ 25   #fffbfa  │ Subtle error tint
+█ 50   #fef3f2  │ Error backgrounds ⭐
+█ 100  #fee4e2  │ Alert backgrounds
+█ 200  #fecdca  │ Light error ⭐
+█ 300  #fda29b  │ Hover states
+█ 400  #f97066  │ Active states
+█ 500  #f04438  │ MAIN ERROR ⭐⭐
+█ 600  #d92d20  │ Error text ⭐⭐
+█ 700  #b42318  │ Strong error ⭐
+█ 800  #912018  │ Dark error text
+█ 900  #7a271a  │ Maximum error
+█ 950  #55160c  │ Deep contrast
+```
+
+**Main Color:** `#f04438` (500 shade)  
+**Text Color:** `#d92d20` (600 shade)  
+**Primary Uses:** Error messages, delete buttons, validation errors, alerts
+
+---
+
+## Warning (Orange Palette)
+
+```
+█ 25   #fffcf5  │ Subtle warning
+█ 50   #fffaeb  │ Warning backgrounds ⭐
+█ 100  #fef0c7  │ Alert backgrounds
+█ 200  #fedf89  │ Light warning ⭐
+█ 300  #fec84b  │ Hover states
+█ 400  #fdb022  │ Active states
+█ 500  #f79009  │ MAIN WARNING ⭐⭐
+█ 600  #dc6803  │ Warning text ⭐⭐
+█ 700  #b54708  │ Strong warning ⭐
+█ 800  #93370d  │ Dark warning
+█ 900  #7a2e0e  │ Maximum warning
+█ 950  #4e1d09  │ Deep contrast
+```
+
+**Main Color:** `#f79009` (500 shade)  
+**Text Color:** `#dc6803` (600 shade)  
+**Primary Uses:** Warning messages, caution states, pending actions
+
+---
+
+## Info (Blue Palette)
+
+```
+█ 25   #f5faff  │ Subtle info
+█ 50   #eff8ff  │ Info backgrounds ⭐
+█ 100  #d1e9ff  │ Light info backgrounds
+█ 200  #b2ddff  │ Soft info accent ⭐
+█ 300  #84caff  │ Hover states
+█ 400  #53b1fd  │ Active states
+█ 500  #2e90fa  │ MAIN INFO ⭐⭐
+█ 600  #1570ef  │ Info text ⭐⭐
+█ 700  #175cd3  │ Strong info ⭐
+█ 800  #1849a9  │ Dark info
+█ 900  #194185  │ Maximum info
+█ 950  #102a56  │ Deep contrast
+```
+
+**Main Color:** `#2e90fa` (500 shade)  
+**Text Color:** `#1570ef` (600 shade)  
+**Primary Uses:** Info messages, neutral notifications, help text
+
+---
+
+## Success (Green Palette)
+
+```
+█ 25   #f6fef9  │ Subtle success
+█ 50   #ecfdf3  │ Success backgrounds ⭐
+█ 100  #dcfae6  │ Light success backgrounds
+█ 200  #abefc6  │ Soft success accent ⭐
+█ 300  #75e0a7  │ Hover states
+█ 400  #47cd89  │ Active states
+█ 500  #17b26a  │ MAIN SUCCESS ⭐⭐
+█ 600  #079455  │ Success text ⭐⭐
+█ 700  #067647  │ Strong success ⭐
+█ 800  #085d3a  │ Dark success
+█ 900  #074d31  │ Maximum success
+█ 950  #053321  │ Deep contrast
+```
+
+**Main Color:** `#17b26a` (500 shade)  
+**Text Color:** `#079455` (600 shade)  
+**Primary Uses:** Success messages, confirmation, completed states
+
+---
+
+## Color Usage Chart
+
+### By Shade Number
+
+| Shade | Typical Use Case |
+|-------|------------------|
+| **25** | Subtle tints, barely visible backgrounds |
+| **50** | Light backgrounds, cards, panels ⭐ |
+| **100** | Hover states on light backgrounds |
+| **200** | Borders, dividers, alert backgrounds ⭐ |
+| **300** | Strong dividers, disabled states |
+| **400** | Placeholder text, decorative elements |
+| **500** | **Primary/Default color** ⭐⭐⭐ |
+| **600** | Hover states, emphasized text ⭐⭐ |
+| **700** | Active states, strong emphasis ⭐⭐ |
+| **800** | Text on light backgrounds ⭐ |
+| **900** | Dark backgrounds, maximum emphasis |
+| **950** | Maximum contrast, primary text |
+
+---
+
+## Semantic Color Mappings
+
+### Primary Colors
+
+| Semantic | Maps To | Hex | Use |
+|----------|---------|-----|-----|
+| `primary` | Saudi Green 500 | `#25935f` | Main brand color |
+| `secondary` | Gold 500 | `#f5bd02` | Secondary brand |
+
+### Status Colors
+
+| Semantic | Maps To | Hex | Use |
+|----------|---------|-----|-----|
+| `success` | Success 500 | `#17b26a` | Success states |
+| `info` | Info 500 | `#2e90fa` | Informational |
+| `warning` | Warning 500 | `#f79009` | Warnings |
+| `danger` | Error 500 | `#f04438` | Errors, delete |
+
+### Neutral Colors
+
+| Semantic | Maps To | Hex | Use |
+|----------|---------|-----|-----|
+| `light` | Gray 50 | `#f9fafb` | Light backgrounds |
+| `dark` | Gray 900 | `#111927` | Dark backgrounds |
+
+---
+
+## Text Color Hierarchy
+
+For optimal readability on **light backgrounds**:
+
+```
+Primary Text   → Gray 950   #0d121c  ⭐⭐⭐
+Secondary Text → Gray 700   #384250  ⭐⭐
+Muted Text     → Gray 600   #4d5761  ⭐
+```
+
+For **dark backgrounds**:
+
+```
+Primary Text   → White      #ffffff  ⭐⭐⭐
+Muted Text     → White 70%  rgba(255,255,255,0.7)  ⭐
+```
+
+For **brand text**:
+
+```
+Brand Primary  → SA 800     #14573a  ⭐⭐
+Brand Accent   → SA 600     #1b8354  ⭐
+```
+
+For **semantic text**:
+
+```
+Error Text     → Error 600    #d92d20  ⭐⭐
+Warning Text   → Warning 600  #dc6803  ⭐⭐
+Success Text   → Success 600  #079455  ⭐⭐
+Info Text      → Info 600     #1570ef  ⭐⭐
+```
+
+---
+
+## Most Commonly Used Colors
+
+### Top 20 Colors by Usage
+
+1. **Gray 50** (`#f9fafb`) - Background
+2. **Primary 500** (`#25935f`) - Saudi Green (main)
+3. **Gray 950** (`#0d121c`) - Primary text
+4. **Gray 200** (`#e5e7eb`) - Borders
+5. **Primary 600** (`#1b8354`) - Hover states
+6. **Gray 700** (`#384250`) - Secondary text
+7. **White** (`#ffffff`) - Backgrounds
+8. **Error 50** (`#fef3f2`) - Error backgrounds
+9. **Error 600** (`#d92d20`) - Error text
+10. **Success 50** (`#ecfdf3`) - Success backgrounds
+11. **Success 600** (`#079455`) - Success text
+12. **Warning 50** (`#fffaeb`) - Warning backgrounds
+13. **Warning 600** (`#dc6803`) - Warning text
+14. **Info 50** (`#eff8ff`) - Info backgrounds
+15. **Info 600** (`#1570ef`) - Info text
+16. **Gold 500** (`#f5bd02`) - Secondary color
+17. **Primary 800** (`#14573a`) - Brand text
+18. **Gray 600** (`#4d5761`) - Muted text
+19. **Primary 100** (`#dff6e7`) - Light green tint
+20. **Gray 900** (`#111927`) - Dark backgrounds
+
+---
+
+## Color Combinations
+
+### Best Pairs (High Contrast ✅)
+
+```
+Background          Text Color
+━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━
+White (#ffffff)  →  Gray 950 (#0d121c)
+Gray 50          →  Gray 950
+Primary 500      →  White
+Dark (Gray 900)  →  White
+Error 50         →  Error 700
+Success 50       →  Success 700
+Warning 50       →  Warning 700
+```
+
+### Alert Color Schemes
+
+```
+Type     Background    Border         Text
+━━━━━━━  ━━━━━━━━━━━━  ━━━━━━━━━━━━━  ━━━━━━━━━━━━━
+Error    error-50      error-200      error-700
+Warning  warning-50    warning-200    warning-700
+Success  success-50    success-200    success-700
+Info     info-50       info-200       info-700
+```
+
+---
+
+## Gradient Definitions
+
+All gradients are based on Saudi Green:
+
+```scss
+Primary    → linear-gradient(90deg, #1b8354, #25935f)
+Secondary  → linear-gradient(45deg, #166a45, #1b8354)
+Dark       → linear-gradient(45deg, #092a1e, #1b8354)
+Medium     → linear-gradient(90deg, #14573a, #1b8354)
+Subtle     → linear-gradient(26.5deg, #14573a, #166a45)
+Deep       → linear-gradient(45deg, #104631, #1b8354)
+```
+
+**Usage:** Hero sections, card headers, CTAs
+
+---
+
+## CSS Variable Reference
+
+All colors available as CSS custom properties:
+
+```css
+/* Gray palette */
+--dga-gray-25 through --dga-gray-950
+
+/* Primary (Saudi Green) */
+--dga-primary-25 through --dga-primary-950
+
+/* Gold */
+--dga-gold-25 through --dga-gold-950
+
+/* Lavender */
+--dga-lavender-25 through --dga-lavender-950
+
+/* Semantic palettes */
+--dga-error-25 through --dga-error-950
+--dga-warning-25 through --dga-warning-950
+--dga-info-25 through --dga-info-950
+--dga-success-25 through --dga-success-950
+```
+
+---
+
+## Color Psychology
+
+### Saudi Green (Primary)
+- **Represents:** Saudi Arabian identity, nature, growth, prosperity
+- **Emotion:** Trust, stability, harmony
+- **Use:** Primary actions, brand elements, success
+
+### Gold (Secondary)
+- **Represents:** Wealth, prestige, quality, Saudi heritage
+- **Emotion:** Luxury, value, importance
+- **Use:** Premium features, badges, secondary CTAs
+
+### Red (Error)
+- **Represents:** Danger, urgency, errors
+- **Emotion:** Alert, stop, attention
+- **Use:** Errors, delete actions, critical warnings
+
+### Orange (Warning)
+- **Represents:** Caution, warning, in-progress
+- **Emotion:** Careful attention, pending
+- **Use:** Warnings, pending states, moderate alerts
+
+### Blue (Info)
+- **Represents:** Information, calm, trust
+- **Emotion:** Reliable, professional, neutral
+- **Use:** Info messages, help text, neutral states
+
+### Green (Success)
+- **Represents:** Success, completion, positive
+- **Emotion:** Accomplishment, safe, go
+- **Use:** Success messages, confirmations, completed
+
+---
+
+## Print Reference
+
+### Color Print Table
+
+For printing this reference with color swatches:
+
+| Color Name | Hex | RGB | HSL |
+|------------|-----|-----|-----|
+| Primary 500 | #25935f | rgb(37, 147, 95) | hsl(152, 60%, 36%) |
+| Gray 950 | #0d121c | rgb(13, 18, 28) | hsl(220, 37%, 8%) |
+| Gold 500 | #f5bd02 | rgb(245, 189, 2) | hsl(46, 98%, 48%) |
+| Error 500 | #f04438 | rgb(240, 68, 56) | hsl(4, 86%, 58%) |
+| Warning 500 | #f79009 | rgb(247, 144, 9) | hsl(34, 94%, 50%) |
+| Info 500 | #2e90fa | rgb(46, 144, 250) | hsl(211, 95%, 58%) |
+| Success 500 | #17b26a | rgb(23, 178, 106) | hsl(152, 77%, 39%) |
+
+---
+
+## Accessibility Notes
+
+- ⭐ **Recommended combinations** meet WCAG AA standards
+- Use **shade 600-800** for text on light backgrounds
+- Use **shade 50-100** for backgrounds in alerts
+- Use **white** for text on 500-950 backgrounds
+- Always test with contrast checker tools
+
+---
+
+**Total Colors:** 96 (8 palettes × 12 shades)  
+**Primary Brand:** Saudi Green #25935f  
+**Secondary Brand:** Gold #f5bd02  
+
+**Version:** 1.0.0  
+**DGA Design System Color Palette**