ui-ux-master 1.2.0 → 1.5.0

package/references/color-psychology-branding.md

@@ -0,0 +1,286 @@
+# Color Psychology in Branding
+
+Use this skill when a user describes a product, business, or UI concept and you must recommend a color scheme. Analyze the business type, target audience, emotional goals, and brand positioning — then apply color psychology principles to prescribe a complete palette.
+
+---
+
+## How to Apply This Skill
+
+When a user says: "I'm building a [product/business type] for [audience]. The feel should be [adjective]."
+
+Follow this process:
+1. **Identify the business category** → look up the category in the table below.
+2. **Identify the emotional goal** → trust, energy, calm, luxury, health, play, authority, innovation.
+3. **Check for conflicts** → does the requested adjective match the business category's expectations?
+4. **Prescribe a palette** → primary, secondary, accent, background, surface, text, semantic colors.
+5. **State the psychological rationale** → explain why these colors work for this business.
+6. **Warn of anti-patterns** → what colors to avoid and why.
+
+---
+
+## Color Emotion Reference
+
+| Color | Core emotions | Common industries |
+|---|---|---|
+| **Blue** | Trust, calm, competence, security, depth | Finance, tech, healthcare, logistics, government |
+| **Deep navy** | Authority, stability, prestige, institutional trust | Finance, law, consulting, insurance |
+| **Cyan / teal** | Innovation, freshness, clarity, health-tech | SaaS, health, wellness, clean energy |
+| **Green** | Growth, health, nature, money, safety | Finance, organic food, wellness, sustainability, pharmacy |
+| **Emerald / forest** | Wealth, premium, sustainability, natural luxury | Luxury eco, premium wellness, high-end food |
+| **Red** | Energy, urgency, passion, appetite, danger | Food, automotive, sale/promo, entertainment |
+| **Warm red / crimson** | Tradition, boldness, confidence, strength | Heritage brands, sportswear, food |
+| **Orange** | Friendliness, enthusiasm, affordability, warmth | Retail, food, casual tech, children |
+| **Amber / gold** | Premium, achievement, warmth, celebration | Luxury, rewards, premium food/beverage |
+| **Yellow** | Optimism, clarity, attention, speed, caution | Construction, food, warnings, casual consumer |
+| **Purple** | Creativity, spirituality, luxury, wisdom, mystery | Beauty, wellness, spiritual, creative SaaS |
+| **Deep violet** | Premium, mystery, innovation | AI/tech (use carefully), beauty, luxury |
+| **Pink** | Warmth, romance, care, femininity | Beauty, wellness, romance, children, healthcare |
+| **Dusty rose / mauve** | Sophistication, calm care | Premium wellness, beauty, hospitality |
+| **White** | Purity, simplicity, clarity, space | Healthcare, luxury, tech, minimal |
+| **Black** | Authority, sophistication, mystery, premium | Luxury, tech, automotive, fashion |
+| **Warm gray / greige** | Neutral sophistication, calm | Luxury interiors, editorial, premium services |
+| **Brown / earth tones** | Heritage, craft, organic, reliability | Food, craft beverages, natural products, luxury leather |
+
+---
+
+## Industry Palette Prescriptions
+
+### Finance and Banking
+- **Trust goal**: use blue family.
+- Palette: Navy primary `#002D72`, white `#FFFFFF`, light blue surface `#EBF5FB`, gold accent `#B8860B` (premium signal).
+- Text: `#1A1A2E` on light.
+- Semantic: success `#1A7F5A`, error `#C0392B`, warning `#D4AC0D`.
+- Avoid: red as primary (signals loss/danger), orange (cheap), bright yellow.
+
+### Healthcare / Medical
+- **Trust + calm goal**: blue-teal family.
+- Palette: calm blue `#0072CE` or teal `#00A7B5`, white `#FFFFFF`, pale blue surface `#EBF8FF`, soft green accent `#27AE60`.
+- Text: `#1A2B3C`.
+- Avoid: aggressive red (associates with blood/emergency), dark purple, black-dominant UI.
+- Exception: red is acceptable for emergency/urgent care contexts.
+
+### Wellness / Mental Health
+- **Calm + care goal**: green, teal, warm earth tones.
+- Palette A (calm): sage green `#87A878`, warm cream `#FAF6F0`, soft teal `#5F9EA0`, text `#2C3E50`.
+- Palette B (energy/vitality): coral `#E8705A`, warm yellow `#F4C842`, white background.
+- Avoid: clinical blue (too medical), aggressive red, dark/heavy backgrounds.
+
+### Physical Fitness / Gym / Sportswear
+- **Energy + performance goal**: bold primaries, high contrast.
+- Palette A (performance): black `#0D0D0D`, red `#D32F2F`, white. (Nike/Adidas approach.)
+- Palette B (energy): orange `#E65C00`, black, white. (High-octane sports.)
+- Palette C (premium athletic): deep navy, gold, white. (Premium fitness brand.)
+- Avoid: pastels, muted tones — they signal relaxation, not performance.
+
+### Food and Restaurant
+- **Appetite + urgency goal**: warm reds, oranges, yellows.
+- Fast food: red + yellow + white (appetite, speed, familiarity).
+- Premium dining: deep plum or dark forest green, cream, gold (sophistication).
+- Healthy/organic: green, earth brown, cream (natural, wholesome).
+- Café/coffee: warm brown `#6F4E37`, cream `#F5F0E8`, gold accent (comfort, ritual).
+- Avoid: blue as a dominant color for food (appetite suppressor except for specialty/brand contexts).
+- Avoid: cold grays in food photography backgrounds.
+
+### E-commerce / Retail
+- **Conversion + trust goal**: primary action color must be high-energy and high-contrast.
+- Mass market: blue/white + orange or yellow CTA.
+- Fashion: depends on positioning (see Fashion below).
+- Premium: neutral backgrounds, single accent.
+- Discount/deal: red or orange urgency, white or light gray base.
+- Avoid: making the CTA the same color as any other non-interactive element.
+
+### Fashion (General)
+- **Identity expression**: palette varies entirely by brand positioning.
+- Luxury: black/white/cream + 1 heritage accent (see Premium Restraint).
+- Contemporary: black/white or muted palette.
+- Fast fashion: white + current season campaign accent.
+- Streetwear: black + one bright accent per drop.
+- Avoid: generic "fashion" pastels without a point of view.
+
+### Technology (Consumer)
+- **Innovation + approachability**: blue or brand accent on white, or high-contrast dark.
+- Modern tech: white + one bright accent (electric blue, electric green, or vibrant red).
+- AI/ML products: dark surface + green or electric blue accent.
+- Developer tools: dark background + accent (see Technical Authority).
+- Avoid: purple/violet as the only tech differentiator — saturated by AI-industry overuse in 2024-2025.
+
+### Education
+- **Trust + optimism goal**: blue for authority, yellow for optimism.
+- K-12 / children: primary colors (red/blue/yellow), friendly, high contrast.
+- Higher ed: institutional navy + gold (authority + achievement).
+- EdTech: blue or teal + white + one friendly accent.
+- Avoid: overly corporate (dark gray/navy only) or overly playful for adult learners.
+
+### Legal / Consulting
+- **Authority + trust**: navy, deep charcoal, white, gold accent.
+- Palette: `#1A2744` (navy), `#FFFFFF`, `#B8860B` (gold), surface `#F7F8FA`.
+- Conservative: maximum 2 colors, no bright accents.
+- Avoid: red (danger/aggression), orange (casual), bright primaries.
+
+### Real Estate
+- **Trust + aspiration**: navy or forest green + gold.
+- Luxury real estate: black/white + gold.
+- Residential: blue + white + green.
+- Commercial: navy + silver/gray.
+- Avoid: too many colors — real estate brands are conservative.
+
+### Automotive
+- **Power/trust OR luxury**: depends on segment.
+- Mass market reliability: red + white or blue + white.
+- Premium/performance: black + silver/white + one accent.
+- Luxury: see Premium Restraint.
+- Electric/EV: blue, cyan, or green (sustainability + innovation).
+- Avoid: yellow/orange as primary for luxury automotive.
+
+### Beauty and Cosmetics
+- **Luxury + aspiration**: black/white/gold for premium; pastels for approachable.
+- Luxury beauty: black `#0A0A0A`, cream `#FAF5EF`, gold `#D4A017`, white.
+- Natural/clean beauty: sage green, cream, dusty rose, earth tones.
+- Bold/color-forward: vivid brand accent on white or black, changes per campaign.
+- Avoid: clinical blue (too medical for beauty), heavy industrial tones.
+
+### Travel and Hospitality
+- **Aspiration + calm**: blue (sky/ocean), teal, white, warm accent.
+- Airlines: blue + white + national accent color.
+- Hotels (luxury): deep navy or forest green + cream + gold.
+- Hotels (budget): blue + white + orange CTA.
+- Travel marketplace: brand accent on white (Airbnb coral, Booking.com blue).
+- Avoid: overuse of stock-photo tropical palettes — they feel generic.
+
+### Non-Profit / Social Impact
+- **Hope + action**: green (growth), blue (trust), warm yellow/orange (optimism, humanity).
+- Human rights / emergency: red + white (urgency + care).
+- Environmental: green + earth tones.
+- Community: warm orange + blue or teal.
+- Avoid: corporate navy-only (feels institutional, not human).
+
+### Gaming
+- **Immersion + energy**: dark surfaces + vivid accent.
+- AAA / console: black + brand color (PlayStation blue, Xbox green, Nintendo red).
+- Mobile/casual: bright primaries, white, high contrast.
+- Esports: black + electric cyan or electric green + red accent.
+- Avoid: muted or pastel palettes — they signal casualness in a world that values intensity.
+
+### SaaS / Productivity
+- **Clarity + trust + approachability**: blue or purple family.
+- B2B SaaS: blue or indigo on white, clean, professional.
+- Creative SaaS: purple, indigo, or gradient accent on white/dark.
+- Developer SaaS: see Technical Authority.
+- Note: avoid full-saturation purple if the brand is not clearly creative — it has AI-product associations.
+- Preferred: `#4361EE` (indigo), `#7209B7` (violet, creative SaaS), `#3A86FF` (bright blue).
+
+---
+
+## Sentiment-to-Palette Mapping
+
+When users describe emotions or goals, translate them:
+
+| User describes | Translate to |
+|---|---|
+| "trustworthy", "reliable", "secure" | Blue family: `#1A56DB`, `#0072CE`, `#003580` |
+| "energetic", "exciting", "bold" | Red/orange: `#D32F2F`, `#E65C00`, `#FF385C` |
+| "calm", "peaceful", "relaxing" | Green/teal: `#27AE60`, `#5F9EA0`, `#87A878` |
+| "luxurious", "premium", "exclusive" | Black/cream/gold: `#0A0A0A`, `#FAF5EF`, `#D4A017` |
+| "playful", "fun", "friendly" | Bright primaries or pastels: `#FF6B6B`, `#4ECDC4`, `#FFE66D` |
+| "innovative", "modern", "forward" | Electric blue/green on dark: `#3A86FF`, `#06D6A0`, `#76B900` |
+| "natural", "organic", "healthy" | Earth greens, browns, cream: `#4A7C59`, `#8B5E3C`, `#FAF6F0` |
+| "authoritative", "expert", "serious" | Navy, charcoal, white: `#1A2744`, `#2D3748`, `#FFFFFF` |
+| "warm", "welcoming", "comforting" | Warm orange, gold, cream: `#E8A000`, `#F5CBA7`, `#FAF0E6` |
+| "creative", "artistic", "expressive" | Vivid unexpected combos: purple + yellow, teal + coral |
+| "clean", "minimal", "simple" | White, light gray, single accent: `#FFFFFF`, `#F7F7F7`, one brand color |
+| "feminine", "delicate", "romantic" | Soft pink, rose, mauve: `#FFB6C1`, `#C08497`, `#E8B4B8` |
+
+---
+
+## Complete Palette Output Format
+
+When you prescribe a palette, always output:
+
+```
+Business type: [name]
+Emotional goal: [trust / energy / calm / luxury / health / play / authority / innovation]
+Positioning: [mass market / mid-range / premium / luxury]
+Primary: [hex] — [color name] — [psychological role]
+Secondary: [hex] — [color name] — [role]
+Accent / CTA: [hex] — [color name] — [role]
+Background: [hex]
+Surface: [hex]
+Text primary: [hex] — contrast on background: [ratio]:1
+Text secondary: [hex] — contrast on background: [ratio]:1
+Border: [hex]
+Semantic — Success: [hex]
+Semantic — Warning: [hex]
+Semantic — Error: [hex]
+Semantic — Info: [hex]
+Dark mode variant: [yes/no — if yes, provide swapped values]
+Avoid: [color] — [reason]
+```
+
+---
+
+## Contrast and Accessibility Requirements
+
+All prescribed palettes must:
+- Pass WCAG 2.2 AA minimum: 4.5:1 for body text, 3:1 for large text (18px+) and UI components.
+- Pass WCAG AAA (7:1) for primary text on primary background when possible.
+- Never place text on an image without a scrim — calculate contrast with the scrim included.
+
+Pre-verified contrast pairs (safe to use):
+| Text | Background | Ratio |
+|---|---|---|
+| `#FFFFFF` white | `#0A0A0A` near-black | 19.8:1 ✓ |
+| `#1A1A1A` near-black | `#FFFFFF` white | 16.1:1 ✓ |
+| `#FFFFFF` white | `#0072CE` blue | 4.6:1 ✓ (AA) |
+| `#FFFFFF` white | `#D32F2F` red | 4.5:1 ✓ (AA min) |
+| `#FFFFFF` white | `#27AE60` green | 2.5:1 ✗ (FAIL — use dark text) |
+| `#1A1A1A` dark | `#FFC72C` yellow | 10.3:1 ✓ |
+| `#FFFFFF` white | `#0A3D62` deep navy | 12.5:1 ✓ |
+| `#767676` gray | `#FFFFFF` white | 4.6:1 ✓ (AA minimum) |
+
+Common failures to warn users about:
+- White text on green backgrounds — fails almost always except very dark green.
+- Light gray text (`#AAAAAA`) on white — 2.3:1, fails.
+- Yellow text on white — always fails.
+- Red CTA buttons with white text — only passes on dark reds (`#C0392B` or darker).
+
+---
+
+## Multi-Audience Palette Variation
+
+When a product serves multiple audiences with different emotional needs:
+
+1. **Primary audience palette**: defines the brand identity.
+2. **Secondary surfaces**: slightly adjusted tone (e.g., consumer = lighter/warmer, enterprise = cooler/darker).
+3. **Shared semantic colors**: consistent success/error/warning across all surfaces.
+4. **Never split brand identity**: the primary color must be consistent — only surface tones vary.
+
+Example: Fintech serving both consumers and businesses.
+- Consumer sections: lighter blue surface `#EBF5FB`, friendly round shapes, warm accent.
+- Business sections: darker navy `#002D72`, formal layout, gold accent.
+- Shared: brand blue `#0072CE`, white background, semantic colors.
+
+---
+
+## Anti-Patterns in Color
+
+- **Purple for every AI/tech product**: overused to the point of signal loss. Use only if brand has genuine creative/creative-tech identity.
+- **Gradients as primary backgrounds**: they tire quickly, age poorly, and compete with content.
+- **Red for a finance brand**: associates with loss, deficit, danger. Use only for error states.
+- **Blue for appetite**: statistically suppresses appetite (avoid as dominant hue for food brands).
+- **All-neutral palette without an accent**: never have a brand with zero brand color — users cannot remember or identify you.
+- **Low-contrast text in pursuit of trend**: thin gray text on white is inaccessible regardless of how "clean" it looks.
+- **Color without meaning**: every color in the palette should have a reason. Remove decorative colors with no semantic or brand function.
+
+---
+
+## Dark Mode Color Adaptation
+
+When dark mode is required, follow these rules:
+- **Never simply invert**: inversion creates jarring contrasts and unintended color meanings.
+- Backgrounds: `#FFFFFF` → `#121212` or `#0A0A0A`.
+- Surfaces: `#F7F7F7` → `#1E1E1E`.
+- Text: `#1A1A1A` → `#E8E8E8` (not pure white — reduces eye strain).
+- Primary color: may need to lighten in dark mode (e.g., `#0072CE` → `#4FA3E0`) for contrast.
+- Semantic colors: keep hue, adjust lightness for contrast. `#27AE60` (dark mode) → `#2ECC71`.
+- Shadows: on dark surfaces, shadows are invisible — use surface elevation (lighter background) instead.
+- Test both modes in WCAG contrast checker before finalizing.

package/references/color-scale-system.md

@@ -0,0 +1,347 @@
+# Color Scale System
+
+Load this file when building a design system that requires full architectural color scales. Every production-grade design system needs 11-step shade ramps (50–950), not just 5–7 semantic tokens.
+
+Use these scales as the foundation for your token system. Then map semantic roles (primary, surface, text, border, accent, semantic states) onto the appropriate shade steps.
+
+---
+
+## How to Use
+
+1. Choose a hue for your brand primary color.
+2. Use the scale template below to generate the 11 steps (50–950) in OKLch.
+3. Map semantic roles to specific steps using the role-to-step mapping table.
+4. For secondary, neutral, and semantic colors (success/warning/error/info), use the provided base scales.
+5. Export as CSS custom properties using the naming convention `--[color-name]-[step]`.
+
+---
+
+## Scale Generation Formula (OKLch)
+
+For any hue `H`, the 11-step scale uses lightness and chroma progressions:
+
+| Step | Lightness | Chroma multiplier | Usage |
+|------|-----------|-------------------|-------|
+| 50 | 97% | 0.15× base chroma | Tinted backgrounds, hover states |
+| 100 | 93% | 0.25× | Soft backgrounds, tags |
+| 200 | 85% | 0.40× | Borders, dividers |
+| 300 | 74% | 0.60× | Disabled states, placeholder |
+| 400 | 62% | 0.80× | Muted text, icons |
+| 500 | 52% | 1.00× **base** | Primary brand color |
+| 600 | 44% | 0.95× | Hover on primary |
+| 700 | 36% | 0.90× | Active/pressed states |
+| 800 | 27% | 0.80× | Dark headings on light |
+| 900 | 18% | 0.65× | Near-black brand tint |
+| 950 | 12% | 0.50× | Deepest shade, dark mode bg |
+
+**Example for Indigo (H=264, base chroma=0.20):**
+
+```css
+:root {
+  --indigo-50:  oklch(97% 0.030 264);
+  --indigo-100: oklch(93% 0.050 264);
+  --indigo-200: oklch(85% 0.080 264);
+  --indigo-300: oklch(74% 0.120 264);
+  --indigo-400: oklch(62% 0.160 264);
+  --indigo-500: oklch(52% 0.200 264);  /* brand primary */
+  --indigo-600: oklch(44% 0.190 264);
+  --indigo-700: oklch(36% 0.180 264);
+  --indigo-800: oklch(27% 0.160 264);
+  --indigo-900: oklch(18% 0.130 264);
+  --indigo-950: oklch(12% 0.100 264);
+}
+```
+
+---
+
+## Semantic Role → Step Mapping
+
+Once you have your scales, map semantic tokens to steps:
+
+| Semantic Token | Light Mode Step | Dark Mode Step | Notes |
+|---|---|---|---|
+| `--color-bg` | Neutral 50 | Neutral 950 | Page background |
+| `--color-surface` | Neutral 100 | Neutral 900 | Card/panel background |
+| `--color-surface-2` | Neutral 200 | Neutral 800 | Nested surface |
+| `--color-border` | Neutral 300 | Neutral 700 | Dividers, input border |
+| `--color-border-strong` | Neutral 400 | Neutral 600 | Emphasis borders |
+| `--color-text-muted` | Neutral 400 | Neutral 500 | Placeholder, disabled |
+| `--color-text-secondary` | Neutral 600 | Neutral 400 | Meta, captions |
+| `--color-text-primary` | Neutral 900 | Neutral 50 | Body copy |
+| `--color-accent` | Primary 500 | Primary 400 | CTAs, links, active |
+| `--color-accent-hover` | Primary 600 | Primary 300 | Hover on accent |
+| `--color-accent-active` | Primary 700 | Primary 200 | Pressed state |
+| `--color-accent-soft` | Primary 100 | Primary 900 | Tinted backgrounds |
+| `--color-accent-text` | Primary 700 | Primary 200 | Text on tinted bg |
+
+---
+
+## Base Neutral Scale (Gray)
+
+Use as the backbone for backgrounds, text, and borders.
+
+```css
+:root {
+  /* Neutral — cool gray, H=264, chroma=0.005 */
+  --neutral-50:  oklch(99% 0.002 264);   /* #FAFAFA */
+  --neutral-100: oklch(96% 0.003 264);   /* #F4F4F6 */
+  --neutral-200: oklch(92% 0.004 264);   /* #EBEBEE */
+  --neutral-300: oklch(85% 0.006 264);   /* #D8D8DE */
+  --neutral-400: oklch(72% 0.008 264);   /* #ABABB8 */
+  --neutral-500: oklch(58% 0.009 264);   /* #818190 */
+  --neutral-600: oklch(46% 0.009 264);   /* #5E5E6E */
+  --neutral-700: oklch(34% 0.008 264);   /* #434352 */
+  --neutral-800: oklch(24% 0.007 264);   /* #2C2C38 */
+  --neutral-900: oklch(15% 0.006 264);   /* #1A1A24 */
+  --neutral-950: oklch(9%  0.005 264);   /* #0E0E14 */
+}
+```
+
+**Warm neutral variant** (use for editorial/warm brand):
+```css
+:root {
+  /* Warm Neutral — H=72, chroma=0.010 */
+  --warm-50:  oklch(98% 0.008 72);
+  --warm-100: oklch(95% 0.012 72);
+  --warm-200: oklch(90% 0.016 72);
+  --warm-300: oklch(82% 0.018 72);
+  --warm-400: oklch(70% 0.016 72);
+  --warm-500: oklch(56% 0.014 72);
+  --warm-600: oklch(44% 0.012 72);
+  --warm-700: oklch(33% 0.010 72);
+  --warm-800: oklch(24% 0.008 72);
+  --warm-900: oklch(16% 0.007 72);
+  --warm-950: oklch(10% 0.005 72);
+}
+```
+
+---
+
+## Brand Color Scales by Hue Family
+
+### Blue / Indigo (Trust, Technology, Finance)
+```css
+:root {
+  --blue-50:  oklch(97% 0.020 230);
+  --blue-100: oklch(93% 0.040 230);
+  --blue-200: oklch(85% 0.070 230);
+  --blue-300: oklch(74% 0.110 230);
+  --blue-400: oklch(62% 0.150 230);
+  --blue-500: oklch(52% 0.180 230);   /* #0072CE calm blue */
+  --blue-600: oklch(44% 0.170 230);
+  --blue-700: oklch(36% 0.160 230);
+  --blue-800: oklch(27% 0.140 230);
+  --blue-900: oklch(18% 0.110 230);
+  --blue-950: oklch(11% 0.080 230);
+
+  --indigo-50:  oklch(97% 0.025 264);
+  --indigo-100: oklch(93% 0.050 264);
+  --indigo-200: oklch(85% 0.080 264);
+  --indigo-300: oklch(74% 0.120 264);
+  --indigo-400: oklch(62% 0.160 264);
+  --indigo-500: oklch(52% 0.200 264);   /* #4361EE */
+  --indigo-600: oklch(44% 0.190 264);
+  --indigo-700: oklch(36% 0.180 264);
+  --indigo-800: oklch(27% 0.160 264);
+  --indigo-900: oklch(18% 0.130 264);
+  --indigo-950: oklch(11% 0.095 264);
+}
+```
+
+### Green (Health, Finance-positive, Nature, Success)
+```css
+:root {
+  --green-50:  oklch(97% 0.025 142);
+  --green-100: oklch(93% 0.050 142);
+  --green-200: oklch(85% 0.085 142);
+  --green-300: oklch(74% 0.120 142);
+  --green-400: oklch(62% 0.150 142);
+  --green-500: oklch(52% 0.160 142);   /* #1A7F5A */
+  --green-600: oklch(44% 0.150 142);
+  --green-700: oklch(36% 0.140 142);
+  --green-800: oklch(27% 0.120 142);
+  --green-900: oklch(18% 0.095 142);
+  --green-950: oklch(11% 0.070 142);
+}
+```
+
+### Red (Energy, Alert, Food, Bold brands)
+```css
+:root {
+  --red-50:  oklch(97% 0.025 25);
+  --red-100: oklch(93% 0.050 25);
+  --red-200: oklch(85% 0.090 25);
+  --red-300: oklch(74% 0.130 25);
+  --red-400: oklch(62% 0.180 25);
+  --red-500: oklch(52% 0.220 25);   /* #C0392B */
+  --red-600: oklch(44% 0.210 25);
+  --red-700: oklch(36% 0.195 25);
+  --red-800: oklch(27% 0.170 25);
+  --red-900: oklch(18% 0.135 25);
+  --red-950: oklch(11% 0.100 25);
+}
+```
+
+### Amber / Gold (Warning, Luxury, Premium, Energy)
+```css
+:root {
+  --amber-50:  oklch(98% 0.030 72);
+  --amber-100: oklch(94% 0.060 72);
+  --amber-200: oklch(88% 0.100 72);
+  --amber-300: oklch(80% 0.140 72);
+  --amber-400: oklch(74% 0.170 72);
+  --amber-500: oklch(72% 0.180 72);   /* #D4A017 */
+  --amber-600: oklch(62% 0.170 72);
+  --amber-700: oklch(50% 0.160 72);
+  --amber-800: oklch(38% 0.140 72);
+  --amber-900: oklch(26% 0.110 72);
+  --amber-950: oklch(16% 0.080 72);
+}
+```
+
+### Purple / Violet (Creative, Premium SaaS, Innovation)
+```css
+:root {
+  --purple-50:  oklch(97% 0.025 300);
+  --purple-100: oklch(93% 0.050 300);
+  --purple-200: oklch(85% 0.085 300);
+  --purple-300: oklch(74% 0.120 300);
+  --purple-400: oklch(62% 0.170 300);
+  --purple-500: oklch(52% 0.220 300);
+  --purple-600: oklch(44% 0.210 300);
+  --purple-700: oklch(36% 0.195 300);
+  --purple-800: oklch(27% 0.170 300);
+  --purple-900: oklch(18% 0.130 300);
+  --purple-950: oklch(11% 0.095 300);
+}
+```
+
+### Teal / Cyan (Healthcare, Tech, Trust-plus-energy)
+```css
+:root {
+  --teal-50:  oklch(97% 0.025 180);
+  --teal-100: oklch(93% 0.050 180);
+  --teal-200: oklch(85% 0.085 180);
+  --teal-300: oklch(74% 0.125 180);
+  --teal-400: oklch(64% 0.165 180);
+  --teal-500: oklch(55% 0.185 180);
+  --teal-600: oklch(46% 0.175 180);
+  --teal-700: oklch(37% 0.160 180);
+  --teal-800: oklch(28% 0.140 180);
+  --teal-900: oklch(19% 0.110 180);
+  --teal-950: oklch(12% 0.080 180);
+}
+```
+
+---
+
+## Semantic State Scales (Fixed — used for success/warning/error/info)
+
+These are standardized across all projects:
+
+```css
+:root {
+  /* Success — green family */
+  --success-50:  oklch(97% 0.025 142);
+  --success-100: oklch(92% 0.050 142);
+  --success-500: oklch(52% 0.160 142);
+  --success-700: oklch(36% 0.140 142);
+  --success-900: oklch(18% 0.095 142);
+
+  /* Warning — amber family */
+  --warning-50:  oklch(98% 0.030 72);
+  --warning-100: oklch(94% 0.060 72);
+  --warning-500: oklch(72% 0.180 72);
+  --warning-700: oklch(50% 0.160 72);
+  --warning-900: oklch(26% 0.110 72);
+
+  /* Error — red family */
+  --error-50:  oklch(97% 0.025 25);
+  --error-100: oklch(93% 0.050 25);
+  --error-500: oklch(52% 0.220 25);
+  --error-700: oklch(36% 0.195 25);
+  --error-900: oklch(18% 0.135 25);
+
+  /* Info — blue family */
+  --info-50:  oklch(97% 0.020 230);
+  --info-100: oklch(93% 0.040 230);
+  --info-500: oklch(52% 0.180 230);
+  --info-700: oklch(36% 0.160 230);
+  --info-900: oklch(18% 0.110 230);
+}
+```
+
+---
+
+## Dark Mode Scale Mapping
+
+In dark mode, the scale direction inverts for surfaces and text but stays consistent for interactive elements:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Surfaces — use high-step (dark) values */
+    --color-bg:       var(--neutral-950);
+    --color-surface:  var(--neutral-900);
+    --color-surface-2: var(--neutral-800);
+    --color-border:   var(--neutral-700);
+    --color-border-strong: var(--neutral-600);
+
+    /* Text — use low-step (light) values */
+    --color-text-primary:   var(--neutral-50);
+    --color-text-secondary: var(--neutral-400);
+    --color-text-muted:     var(--neutral-500);
+
+    /* Accent — shift one step lighter for dark bg legibility */
+    --color-accent:       var(--[brand]-400);
+    --color-accent-hover: var(--[brand]-300);
+    --color-accent-soft:  var(--[brand]-900);
+
+    /* Semantic states — lighter variants for dark bg */
+    --color-success: var(--success-400);
+    --color-warning: var(--warning-400);
+    --color-error:   var(--error-400);
+    --color-info:    var(--info-400);
+  }
+}
+```
+
+---
+
+## Typography Scale (px + rem)
+
+Always output both px and rem values. Base: 16px = 1rem.
+
+| Token | px | rem | Line-height | Weight | Use |
+|---|---|---|---|---|---|
+| `--text-xs` | 11px | 0.6875rem | 1.4 | 400 | Labels, captions |
+| `--text-sm` | 13px | 0.8125rem | 1.5 | 400 | Secondary body |
+| `--text-base` | 15px | 0.9375rem | 1.6 | 400 | Primary body |
+| `--text-md` | 16px | 1rem | 1.6 | 400 | Alternate body |
+| `--text-lg` | 18px | 1.125rem | 1.5 | 500 | Lead / intro |
+| `--text-xl` | 20px | 1.25rem | 1.4 | 500–600 | Section label |
+| `--text-2xl` | 24px | 1.5rem | 1.3 | 600 | Card headline |
+| `--text-3xl` | 30px | 1.875rem | 1.25 | 600–700 | H3 |
+| `--text-4xl` | 36px | 2.25rem | 1.2 | 700 | H2 |
+| `--text-5xl` | 48px | 3rem | 1.15 | 700 | H1 |
+| `--text-6xl` | 60px | 3.75rem | 1.1 | 700–800 | Display |
+| `--text-7xl` | 72px | 4.5rem | 1.05 | 800 | Hero headline |
+
+---
+
+## Pre-Delivery Color Checklist
+
+Before any design system output, verify:
+
+```
+COLOR SCALE CHECKLIST
+[ ] All 11 steps (50–950) defined for primary brand color
+[ ] Neutral scale complete (50–950)
+[ ] Semantic roles mapped to specific scale steps
+[ ] Dark mode overrides specified
+[ ] Text on --color-bg: contrast ≥ 4.5:1 (body), ≥ 3:1 (large/UI)
+[ ] Text on --color-accent: contrast ≥ 4.5:1
+[ ] Text on --color-success/warning/error backgrounds: contrast verified
+[ ] Both px and rem values in typography scale
+[ ] Google Fonts import URL included if using web fonts
+```