@nerdev/skillset 0.2.1

package/skills/ui/refero-design/references/color.md

@@ -0,0 +1,563 @@
+# Color Guide
+
+Color is the emotional backbone of UI. Get it wrong and your product looks either amateur or AI-generated. Get it right and everything feels intentional.
+
+---
+
+## 0. Context First
+
+Before touching palettes, answer these questions:
+
+| Question | Why It Matters |
+|----------|----------------|
+| **Product UI or marketing?** | Product: fewer colors, more neutrals, strict semantics. Marketing: more emotion, gradients, contrast allowed. |
+| **Data density?** | Dashboards need muted accents, high text contrast, no "glowing" colors. Content-focused UI can be softer. |
+| **Is brand defined?** | No brand: use safe preset, refine later. Existing brand: translate brand color into system tokens, don't paint everything with it. |
+
+**Hard rule:**
+
+> When in doubt — fewer colors, more neutrals, stricter purpose. Restraint beats "colorful."
+
+This single rule eliminates 50% of AI-slop before you start.
+
+---
+
+## 1. Color Space
+
+Why most palettes "break" when you try to extend them.
+
+### The Problem with HSL
+
+HSL is intuitive but poorly represents perceptual brightness. A "50% lightness" yellow looks much brighter than "50% lightness" blue. This makes consistent scales nearly impossible.
+
+### The Solution: OKLCH
+
+OKLCH (or LCH) provides perceptually uniform lightness. Steps from 50→950 actually look even.
+
+**Practical workflow:**
+- Generate and adjust palettes in OKLCH
+- Store production values as hex
+- Keep OKLCH logic as source of truth
+
+```css
+/* OKLCH example */
+--primary-500: oklch(0.55 0.2 250);  /* Base */
+--primary-600: oklch(0.48 0.2 250);  /* Hover */
+--primary-700: oklch(0.41 0.2 250);  /* Active */
+```
+
+**For MVP:** You can skip OKLCH. Use curated palettes (Tailwind, Radix, Open Color). But know why they work.
+
+---
+
+## 2. Palette Structure
+
+You need 4 layers, not "30 beautiful colors."
+
+### 2.1 Neutrals (Most Important)
+
+Neutrals are 70–90% of your UI. This is where you win or lose.
+
+**Requirements:**
+- 10-12 steps: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
+- Slight character (warm or cool), not colorful circus
+- Consistent across light and dark themes
+
+**Scale reference:**
+
+| Step | Use | Example |
+|------|-----|---------|
+| 50 | Near-white backgrounds | `#fafafa` |
+| 100-200 | Surfaces, cards | `#f5f5f5`, `#e5e5e5` |
+| 300-400 | Borders, dividers | `#d4d4d4`, `#a3a3a3` |
+| 500 | Placeholder text | `#737373` |
+| 600-700 | Secondary text | `#525252`, `#404040` |
+| 800-900 | Primary text | `#262626`, `#171717` |
+| 950 | Near-black | `#0a0a0a` |
+
+**Hard rules:**
+- Never use pure `#000` on white as body text
+- Don't make text gray "for breathing room" — spacing creates breathing room, not faded text
+
+### 2.2 Primary Accent
+
+One brand color. It should:
+- Have good contrast on both white and dark backgrounds
+- Have a full scale (50–950), not just one hex
+- Be used sparingly and purposefully
+
+**Typical usage:**
+
+| Step | Use |
+|------|-----|
+| 50-100 | Tinted backgrounds |
+| 500-600 | Default state |
+| 600-700 | Hover state |
+| 700-800 | Active/pressed state |
+
+### 2.3 Semantic Colors
+
+Usually 3-4:
+- **Success** — Green (confirmations, completion)
+- **Warning** — Amber/Yellow (attention needed)
+- **Danger** — Red (errors, destructive actions)
+- **Info** — Blue (neutral information) — optional
+
+**Important:** Semantics work through pairs, not single colors.
+
+```css
+/* Each semantic needs: */
+--success: #16a34a;           /* Icon, text accent */
+--success-bg: #f0fdf4;        /* Background */
+--success-border: #86efac;    /* Border */
+--on-success: #ffffff;        /* Text on solid success */
+```
+
+### 2.4 Effects (Only If Needed)
+
+- Gradients
+- Glows
+- Illustration tints
+
+**Rule:** In product UI, effects should be rare and localized. Save drama for marketing.
+
+---
+
+## 3. The 60/30/10 Rule
+
+Distribution that works for any interface:
+
+| Percentage | Elements |
+|------------|----------|
+| 60-80% | Neutrals (backgrounds, surfaces, borders) |
+| 10-20% | Text hierarchy (different gray levels) |
+| 5-10% | Accents and semantics |
+
+### Component Color Limit
+
+**Maximum 2 colors per component.**
+
+If a button has brand gradient + colored border + colored shadow + colored text, it's almost always garbage.
+
+### State Changes: Structure, Not Circus
+
+Hover and Active should be:
+- Slightly darker/lighter
+- Slightly more contrast
+- Subtle shadow enhancement
+
+**Don't** repaint every state with a new random color.
+
+```css
+/* Good */
+.button {
+  background: var(--primary);
+}
+.button:hover {
+  background: var(--primary-hover);  /* Just darker */
+}
+
+/* Bad */
+.button:hover {
+  background: linear-gradient(135deg, #ff6b6b, #feca57);
+  box-shadow: 0 0 20px #ff6b6b;
+}
+```
+
+---
+
+## 4. Contrast and Readability
+
+Not about checking boxes — about actual readability.
+
+### Minimum Requirements
+
+| Text Type | WCAG AA Ratio |
+|-----------|---------------|
+| Body text (≤16px) | 4.5:1 |
+| Large text (18px+ bold, 24px+ regular) | 3:1 |
+| UI components, icons | 3:1 |
+
+### Common Failures
+
+1. **Secondary text too pale** — The #1 issue. If it looks fine on your Retina display at noon, it fails on cheap monitors at 9pm.
+
+2. **Text on tinted backgrounds** — "Almost readable" text on colored backgrounds fails in real conditions (tired eyes, ambient light, older monitors).
+
+### Practical Check
+
+- Test secondary text on multiple devices
+- If you squint and text disappears, it's too light
+- Ask: "Would my parents read this easily?"
+
+---
+
+## 5. Light and Dark Themes
+
+### The Wrong Way
+
+Inverting colors mechanically: white → black, black → white.
+
+Result: eye-burning contrast, amateur look.
+
+### The Right Way
+
+**Dark theme gets its own neutral scale.**
+
+```css
+/* Light */
+:root {
+  --bg: #ffffff;
+  --surface: #f7f7f7;
+  --text: #0b0b0b;
+  --text-muted: #5f6368;
+}
+
+/* Dark — NOT just inverted */
+[data-theme="dark"] {
+  --bg: #0f0f0f;          /* Not #000 */
+  --surface: #1a1a1a;
+  --text: #f0f0f0;        /* Not #fff */
+  --text-muted: #a1a1a1;
+}
+```
+
+### Dark Theme Elevation
+
+In dark UI, surfaces and layers communicate through:
+- Slightly lighter backgrounds for elevated elements
+- Subtle borders (1px, low contrast)
+- Very soft shadows or no shadows at all
+
+```css
+[data-theme="dark"] {
+  --surface-elevated: #242424;  /* Lighter than base */
+  --border: rgba(255, 255, 255, 0.1);
+}
+```
+
+### Dark Mode: Technical Implementation
+
+Browser-level settings that most developers miss:
+
+```html
+<!-- In <head> — tells browser UI elements to use dark mode -->
+<meta name="color-scheme" content="light dark">
+
+<!-- Theme color for browser chrome, PWA, mobile address bar -->
+<meta name="theme-color" content="#0f0f0f" media="(prefers-color-scheme: dark)">
+<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
+```
+
+```css
+/* On <html> — fixes scrollbars, form controls, system dialogs */
+:root {
+  color-scheme: light;
+}
+[data-theme="dark"] {
+  color-scheme: dark;
+}
+```
+
+**Why this matters:**
+- Without `color-scheme: dark`, scrollbars stay light gray on dark backgrounds
+- Form inputs (`<input>`, `<select>`, `<textarea>`) get wrong default colors
+- System dialogs and autofill appear broken
+
+**Native `<select>` fix for dark mode (Windows issue):**
+
+```css
+[data-theme="dark"] select {
+  background-color: var(--surface-2);
+  color: var(--text);
+}
+```
+
+---
+
+## 6. Naming Tokens
+
+**Never name tokens by color. Name by purpose.**
+
+### Bad
+
+```css
+--blue: #2563eb;
+--light-blue: #eff6ff;
+--dark-blue: #1e40af;
+```
+
+### Good
+
+```css
+--primary: #2563eb;
+--primary-tint: #eff6ff;
+--primary-active: #1e40af;
+```
+
+### Minimum Token Set
+
+```css
+:root {
+  /* Surfaces */
+  --bg: #ffffff;
+  --surface-1: #ffffff;
+  --surface-2: #f7f7f7;
+
+  /* Text */
+  --text: #0b0b0b;
+  --text-muted: #5f6368;
+  --text-subtle: #7a7f85;
+
+  /* Borders */
+  --border: #e6e6e6;
+  --border-strong: #d1d1d1;
+
+  /* Primary */
+  --primary: #2563eb;
+  --on-primary: #ffffff;
+  --primary-hover: #1d4ed8;
+  --primary-active: #1e40af;
+  --primary-tint: #eff6ff;
+
+  /* Semantic */
+  --success: #16a34a;
+  --warning: #f59e0b;
+  --danger: #ef4444;
+}
+```
+
+**Key:** Components should work from tokens, not hardcoded hex values.
+
+---
+
+## 7. Building a Palette from Scratch
+
+When there's no brand yet:
+
+### Step 1: Choose Neutral Character
+
+Decide warm or cool. This affects the entire feel.
+
+```css
+/* Cool (tech, precision) */
+--neutral-100: #f4f4f5;
+
+/* Warm (friendly, premium) */
+--neutral-100: #f5f4f2;
+```
+
+### Step 2: Choose One Primary
+
+Requirements:
+- Works on white background
+- Works on dark background
+- Works in buttons, links, badges
+- "Strong" but not fluorescent
+
+**Test:** Put your primary in a button, a text link, a badge. All three should feel right.
+
+### Step 3: Generate Scale
+
+Use OKLCH or curated palette generators:
+- [Tailwind CSS Colors](https://tailwindcss.com/docs/customizing-colors)
+- [Radix Colors](https://www.radix-ui.com/colors)
+- [Open Color](https://yeun.github.io/open-color/)
+
+### Step 4: Add Semantics
+
+Choose semantic colors that don't clash with primary.
+
+| Primary | Avoid for Success |
+|---------|-------------------|
+| Blue | Blue (use green) |
+| Green | Yellow-green (use teal) |
+| Red | Red-orange (use green) |
+
+---
+
+## 8. Gradients
+
+Gradients are allowed when:
+- They support brand identity
+- They don't break readability
+- They're localized (hero, illustration, small highlight)
+
+### Rules
+
+1. **Gradient is never the only way to make something visible** — If removing the gradient makes the element invisible, redesign.
+
+2. **Subtle > dramatic** — Direction and angle matter more than color variety.
+
+3. **Text on gradients** — Ensure contrast works across the entire gradient, not just the start.
+
+```css
+/* Acceptable */
+.hero-badge {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+/* Problematic */
+.card {
+  background: linear-gradient(90deg, 
+    #ff6b6b, #feca57, #48dbfb, #ff9ff3);
+}
+```
+
+---
+
+## 9. Anti-Patterns
+
+Structural problems that reveal unintentional design:
+
+### 🚨 THE #1 AI SLOP INDICATOR: INDIGO/VIOLET
+
+**This deserves its own section because it's THAT important.**
+
+Every LLM, every AI code generator, every design tool defaults to indigo/violet (`#6366f1`, `#8b5cf6`, or similar). This has become the universal fingerprint of AI-generated design.
+
+**Before using any purple-family color, ask:**
+1. Does the brand explicitly require purple?
+2. Did research references use purple (and why)?
+3. Is there a semantic reason (not just "looks modern")?
+4. Would a senior designer question this choice?
+
+**If you can't answer YES to at least one of these—choose a different color.**
+
+Safe alternatives when you need an accent:
+- Blue (`#2563eb`) — trust, stability, professional
+- Teal (`#0d9488`) — fresh, modern, distinctive
+- Green (`#16a34a`) — growth, success, natural
+- Orange (`#ea580c`) — energy, action, warmth
+- Brand-specific color from research
+
+**The rule:** Indigo is BANNED unless explicitly justified by brand requirements.
+
+### Other Red Flags
+
+- **Multiple competing accents** — One primary. Others should be clearly secondary or semantic
+- **Random hex in components** — Should use tokens
+- **Pure black on white** — Use near-black (#0b0b0b)
+- **Every state is a new color** — Hover/active should be predictable shifts
+- **Dark theme = inverted** — Needs separate neutrals
+
+### Quick Test
+
+1. Is your primary color indigo/violet? (If yes, justify it or change it)
+2. Can you justify your primary color choice with research?
+3. How many accent colors? (Should be 1-2)
+4. Are all colors from tokens, not random hex?
+
+→ Full anti-AI-slop guide: [anti-ai-slop.md](anti-ai-slop.md)
+
+---
+
+## 10. Pre-Ship Checklist
+
+- [ ] **One primary accent**, not 3 "hero colors"
+- [ ] **Neutrals are 70-90%** of the interface
+- [ ] **Text readable everywhere**, secondary text not pale
+- [ ] **Hover/Active states predictable** and calm
+- [ ] **Tokens named by purpose** (bg, text, border, primary)
+- [ ] **Dark theme is separate**, not inverted
+- [ ] **Semantics don't clash** with primary
+- [ ] **No random hex** in components — all from tokens
+- [ ] **Contrast passes** WCAG AA (4.5:1 body, 3:1 large)
+- [ ] **Gradients are rare** and localized
+- [ ] **`color-scheme`** set on `<html>` for dark mode (fixes scrollbars, inputs)
+- [ ] **`<meta name="theme-color">`** matches page background
+
+---
+
+## Appendix: Complete Token System
+
+Reference implementation with all tokens:
+
+```css
+:root {
+  /* Neutrals (cool variant) */
+  --neutral-50: #fafafa;
+  --neutral-100: #f5f5f5;
+  --neutral-200: #e5e5e5;
+  --neutral-300: #d4d4d4;
+  --neutral-400: #a3a3a3;
+  --neutral-500: #737373;
+  --neutral-600: #525252;
+  --neutral-700: #404040;
+  --neutral-800: #262626;
+  --neutral-900: #171717;
+  --neutral-950: #0a0a0a;
+
+  /* Surfaces */
+  --bg: var(--neutral-50);
+  --surface-1: #ffffff;
+  --surface-2: var(--neutral-100);
+  --surface-3: var(--neutral-200);
+
+  /* Text */
+  --text: var(--neutral-900);
+  --text-muted: var(--neutral-600);
+  --text-subtle: var(--neutral-500);
+  --text-disabled: var(--neutral-400);
+
+  /* Borders */
+  --border: var(--neutral-200);
+  --border-strong: var(--neutral-300);
+
+  /* Primary (blue) */
+  --primary-50: #eff6ff;
+  --primary-100: #dbeafe;
+  --primary-200: #bfdbfe;
+  --primary-500: #3b82f6;
+  --primary-600: #2563eb;
+  --primary-700: #1d4ed8;
+  --primary-800: #1e40af;
+  --primary-900: #1e3a8a;
+
+  --primary: var(--primary-600);
+  --primary-hover: var(--primary-700);
+  --primary-active: var(--primary-800);
+  --primary-tint: var(--primary-50);
+  --on-primary: #ffffff;
+
+  /* Semantic */
+  --success: #16a34a;
+  --success-bg: #f0fdf4;
+  --warning: #f59e0b;
+  --warning-bg: #fffbeb;
+  --danger: #ef4444;
+  --danger-bg: #fef2f2;
+  --info: #0ea5e9;
+  --info-bg: #f0f9ff;
+}
+
+/* Dark theme */
+[data-theme="dark"] {
+  --bg: #0f0f0f;
+  --surface-1: #171717;
+  --surface-2: #1f1f1f;
+  --surface-3: #262626;
+
+  --text: #f5f5f5;
+  --text-muted: #a3a3a3;
+  --text-subtle: #737373;
+
+  --border: rgba(255, 255, 255, 0.1);
+  --border-strong: rgba(255, 255, 255, 0.15);
+
+  --primary: #60a5fa;
+  --primary-hover: #3b82f6;
+  --primary-active: #2563eb;
+  --primary-tint: rgba(59, 130, 246, 0.15);
+  --on-primary: #0f0f0f;
+
+  --success-bg: rgba(22, 163, 74, 0.15);
+  --warning-bg: rgba(245, 158, 11, 0.15);
+  --danger-bg: rgba(239, 68, 68, 0.15);
+  --info-bg: rgba(14, 165, 233, 0.15);
+}
+```
+
+---
+
+*Color is restraint. Neutrals are 90% of the work. One accent, used purposefully, beats five competing for attention.*