ui-ux-master 1.2.1 → 1.5.0

package/references/brand-method-utility-command-center.md

@@ -0,0 +1,278 @@
+# Brand Method: Utility Command Center
+
+Use this skill when building for ecommerce, logistics, booking platforms, dashboards, admin tools, marketplaces with strong search/filter, or any context where the user's primary goal is to find, track, order, or manage something fast.
+
+Reference brands: Amazon, FedEx, UPS, DHL, Booking.com, Expedia, Walmart, Target, Costco, IKEA, Dell, Domino's.
+
+---
+
+## When to Apply This Method
+
+Apply Utility Command Center when:
+- Speed and task completion are the primary UX goals.
+- Users arrive with a specific item, destination, order, or task in mind.
+- The product catalog or inventory is large (hundreds to millions of items).
+- Users compare, filter, track, or manage rather than just browse.
+
+Do not apply when:
+- Brand aspiration or emotion drives the visit (use Product Cinema or Editorial Brand World).
+- The product is premium/luxury (use Premium Restraint).
+- The primary user action is sign-up or subscription (use Conversion Simplicity).
+
+---
+
+## Layout Structure
+
+### Header / Primary Utility Bar
+- Full-width header with logo left.
+- **Search bar is dominant**: centered or filling most of the header width on desktop, full-width on mobile.
+- Search must have: placeholder with example query, clear button, submit, and autocomplete.
+- Secondary navigation: categories, account, cart/orders, location — compact, never competing with search.
+- Persistent across all pages.
+
+### Homepage Structure (in order)
+1. **Primary utility** — search, track, or book above the fold. No exception.
+2. **Deal / promotion strip** — thin banner, 1-2 active offers, dismissible.
+3. **Category navigation** — visual grid or horizontal scroll of top categories.
+4. **Recommended / featured** — personalized or curated product/listing grid.
+5. **Trust signals** — delivery times, return policy, security badges (compact).
+6. **Secondary categories / browse** — deeper catalog entry points.
+
+### Product / Listing Page
+- Sticky filter panel (left on desktop, bottom drawer on mobile).
+- Product grid: 3-4 columns desktop, 2 columns tablet, 1-2 columns mobile.
+- Each card: image, name (2 lines max), price, rating (star + count), delivery estimate, primary CTA.
+- Sort controls: above grid, always visible.
+- Pagination or infinite scroll: provide "back to top" and page indicator.
+
+### Product Detail Page
+- Breadcrumb at top.
+- Images: large primary + thumbnail strip. Zoom on hover (desktop), pinch on mobile.
+- Price: large, prominent. Savings amount if applicable.
+- Delivery / availability: above fold, always.
+- Primary CTA: "Add to Cart" or "Buy Now" — sticky on mobile scroll.
+- Specs, reviews, related products: below fold in tabs or sections.
+
+---
+
+## Color Scheme
+
+### Primary Palette by Sub-category
+
+**General Ecommerce / Retail**
+- Background: `#FFFFFF`
+- Surface: `#F0F2F2` (off-white cards, sidebar)
+- Primary text: `#0F1111`
+- Secondary text: `#565959`
+- Primary CTA: `#FF9900` (Amazon-style) or `#CC0000` (Target), `#0071CE` (Walmart)
+- CTA hover: Darken 8%
+- Link: `#007185`
+- Border: `#D5D9D9`
+- Badge/deal: `#CC0000` or `#E31837`
+
+**Logistics / Tracking**
+- Background: `#FFFFFF`
+- Primary: Brand color (FedEx `#4D148C`/`#FF6600`, UPS `#351C15`/`#FFB500`, DHL `#FFCC00`/`#D40511`)
+- Surface: `#F4F4F4`
+- Text: `#333333`
+- Status indicators: `#00A651` (success), `#E67E22` (in transit), `#C0392B` (exception)
+
+**Booking / Travel**
+- Background: `#FFFFFF`
+- Primary: `#003580` (Booking.com blue) or `#00355F`
+- Accent: `#FEBB02` (deal/highlight)
+- Surface: `#F2F2F2`
+- Text: `#333333`
+- Urgency: `#C0392B` (few left), `#E67E22` (limited time)
+
+### Rules
+- Never use dark backgrounds for utility layouts — they slow scanning.
+- CTA color must be visually distinct from every other element on the page.
+- Urgency / deal badges: use red or orange only; never use urgency color for non-urgent content.
+- White background with strong card borders or subtle shadows improves scannability.
+
+---
+
+## Typography
+
+### Scale
+| Role | Size | Weight | Notes |
+|---|---|---|---|
+| Site title / logo | — | — | Image/SVG, not text |
+| H1 (page title) | 22-28px | 600-700 | Category or search results title |
+| H2 (section title) | 18-22px | 600 | |
+| Product name | 14-16px | 400-500 | 2-line clamp |
+| Price | 18-24px | 600-700 | Tabular numerals |
+| Strikethrough price | 13-14px | 400 | `text-decoration: line-through`, muted color |
+| Rating / metadata | 12-13px | 400 | |
+| CTA | 13-16px | 600-700 | |
+| Body / description | 14-16px | 400 | 1.5 line-height |
+| Label / badge | 11-12px | 600-700 | All-caps or bold |
+
+### Font Pairings
+| Context | Font |
+|---|---|
+| General utility | System font stack: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` |
+| Logistics | Helvetica Neue, Arial, or Inter |
+| Travel booking | Circular, Inter, or Source Sans |
+
+### Rules
+- Prefer system fonts for performance — users arrive with a task, not a brand appreciation moment.
+- Product names must be readable at 2-line clamp. Avoid decorative fonts.
+- Price must be the most visually prominent number on a product card.
+
+---
+
+## Spacing System
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-xs` | 4px | Badge padding, tight inline gaps |
+| `--space-sm` | 8px | Card inner padding, icon gaps |
+| `--space-md` | 12-16px | Component padding, form inputs |
+| `--space-lg` | 24px | Card gutters, section dividers |
+| `--space-xl` | 32-40px | Major section separation |
+| `--space-2xl` | 48-64px | Page-level section separation |
+
+- Product grids: 12-16px gap between cards.
+- Page padding: 16px mobile, 24px tablet, 40-64px desktop (or centered max-width container).
+- Avoid excessive breathing room — utility UX is information-dense by design.
+
+---
+
+## Motion and Interaction
+
+### Principles
+- **Instant feedback over animation.** Users are in task mode; delays feel like failures.
+- Hover states: subtle background shift, no slow transitions.
+- Add-to-cart: brief success micro-animation (cart icon pulse, item count update).
+- Skeleton loading: always show skeletons instead of blank areas.
+
+### Key States
+| Component | States |
+|---|---|
+| Search input | Default, focused (border highlight), has-value (show clear button), loading (spinner) |
+| Product card | Default, hover (shadow lift + image zoom), loading (skeleton) |
+| Add to cart button | Default, hover, loading, success (brief), disabled (out of stock) |
+| Filter checkbox | Default, checked, hover, focus, disabled |
+| Sort dropdown | Default, open, selected option |
+| Tracking step | Completed (filled icon), Active (pulsing dot), Pending (hollow icon) |
+
+### Transitions
+- Card hover: `box-shadow 150ms ease`, `transform 150ms ease`
+- Button click: `background 100ms ease`, `transform 100ms`
+- Dropdown: `opacity 150ms ease`, `transform 150ms ease`
+- Never exceed 250ms for task-critical UI transitions.
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Key changes |
+|---|---|
+| Mobile 375px | Single column. Search full-width. Categories horizontal scroll. Sticky add-to-cart bar. Filter as bottom sheet. |
+| Tablet 768px | 2-column product grid. Collapsible filter sidebar. |
+| Desktop 1024px | 3-4 column grid. Persistent filter sidebar. Full header utility bar. |
+| Wide 1440px+ | Max content width 1440px, sidebar fixed, grid expands to 4-5 columns. |
+
+- Mobile: filter panel becomes a full-screen modal or bottom drawer.
+- Mobile: sticky "Add to Cart / Proceed" bar fixed to bottom viewport.
+- Mobile: search bar always accessible (sticky or easy scroll-to-top).
+
+---
+
+## Accessibility Requirements
+
+- Search input: `<label>` associated via `for`/`id`, or `aria-label`. Autocomplete results use `role="listbox"` with `aria-expanded`.
+- Product cards: each card is a landmark. Product name is the accessible label. Price announced. CTA has context: "Add [Product Name] to cart".
+- Filters: `<fieldset>` with `<legend>` per group. Checkboxes with visible labels.
+- Sort: `<select>` or custom control with `aria-label="Sort by"` and `aria-selected` on option.
+- Rating stars: `aria-label="4.5 out of 5 stars, 1,203 ratings"` — never visually-only stars.
+- Pagination: `<nav aria-label="Pagination">` with current page `aria-current="page"`.
+- Loading states: `aria-busy="true"` on the container while data loads.
+- Urgency badges ("Only 2 left"): announce with `aria-live="polite"` if dynamic.
+- Touch targets: minimum 44×44px for all interactive elements.
+- Focus: visible focus ring on all interactive elements, not removed.
+
+---
+
+## UX Principles for This Method
+
+1. **Search is sacred.** The search bar is the most important element. Never de-prioritize it.
+2. **Show don't hide.** Price, delivery estimate, and availability must be on the card — not behind a click.
+3. **Scan mode.** Users skim product grids. Design for F-pattern reading: image left, name top, price prominent.
+4. **Reduce checkout friction.** Guest checkout, saved addresses, payment tokens. Every field removed increases conversion.
+5. **Status visibility.** For logistics: always show where the order/shipment is in real-time.
+6. **Honest urgency.** Use scarcity only when true. Fake urgency destroys trust and constitutes a dark pattern.
+7. **Recovery is easy.** Undo add to cart, saved carts, continue shopping. Users make mistakes.
+
+---
+
+## Component Specs
+
+### Search Bar
+```
+Height: 40-48px
+Border: 1px solid var(--border), 2px focus
+Border-radius: 4px (utilitarian) | 24px (modern)
+Background: white
+Icon: magnifying glass left (16-20px)
+Clear button: right, appears when has-value
+Padding: 8px 40px (icon side) 8px 12px
+Font: 14-16px
+Autocomplete: absolute positioned, full width, max-height 300px, overflow-y scroll
+```
+
+### Product Card
+```
+Width: flexible (grid cell)
+Border: 1px solid var(--border)
+Border-radius: 4-8px
+Padding: 12-16px
+Image: aspect-ratio 1/1 or 4/3, object-fit: contain
+Product name: 14-16px, 2-line clamp, margin-bottom 4px
+Price: 18-22px bold, tabular-nums
+Rating: 12-13px, star icons + count
+CTA: full-width button, 40px height, brand accent
+```
+
+### Status Tracker (Logistics)
+```
+Steps: horizontal on desktop, vertical on mobile
+Active step: filled circle, brand color, pulse animation
+Completed: filled check icon, muted brand color
+Pending: hollow circle, gray
+Step label: 11-12px below/beside icon
+Connector line: 2px, colored for completed, gray for pending
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- Do not hide the price until the product page — users need it to scan.
+- Do not use dark backgrounds for product grids — reduces readability and scan speed.
+- Do not use fake urgency ("Only 3 left!" when 300 are in stock).
+- Do not auto-play promotional videos in the product grid.
+- Do not use hover-only filters or sort controls — mobile users cannot hover.
+- Do not paginate to page 1 after applying a filter — preserve scroll position or result context.
+- Do not use captcha on checkout — use it only before purchase if fraud risk is high.
+- Do not require account creation before cart or checkout.
+- Do not show "out of stock" only after the user has added to cart.
+
+---
+
+## QA Checklist
+
+- [ ] Search returns results within 300ms (or shows skeleton).
+- [ ] Product card: price, name, rating, delivery visible without hover.
+- [ ] Filter panel: applying a filter immediately updates results (no "Apply" button required unless many simultaneous changes).
+- [ ] Sticky add-to-cart bar visible on mobile product detail page scroll.
+- [ ] Guest checkout path exists and is accessible without account creation.
+- [ ] Tracking status page shows current step, timestamp, and next expected step.
+- [ ] All interactive elements have visible focus ring.
+- [ ] Rating stars have accessible text alternative.
+- [ ] Search input has `<label>` or `aria-label`.
+- [ ] Mobile filter is accessible as full-screen modal with close button.
+- [ ] No fake urgency copy — verify against live inventory logic.
+- [ ] Core Web Vitals: LCP ≤ 2.5s, CLS ≤ 0.1 (product grids must not shift on image load).

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.