@hegemonart/get-design-done 1.14.7 → 1.15.0

package/reference/iconography.md

@@ -0,0 +1,231 @@
+# Iconography — Reference Guide
+
+Icons are a precise visual language. Every sizing, weight, metaphor, and accessibility decision either reinforces or undermines the system's communicative intent. This reference establishes canonical rules for icon usage across the get-design-done framework.
+
+---
+
+## 1. Optical Sizing & Stroke Weight
+
+Icons are not scalable art objects that merely get bigger — they are optical instruments tuned to specific viewing contexts. A 16px icon rendered with the same stroke weight as a 32px icon will look fragile and thin at small sizes, because the eye perceives stroke weight relative to the overall icon bounding box.
+
+**Canonical stroke weights by icon size:**
+
+| Icon size | Recommended stroke | Why |
+|-----------|-------------------|-----|
+| 16px | 1.5px | At 16px, a 1px stroke disappears on most non-retina displays; 1.5px gives enough mass without filling the internal counter spaces |
+| 20px | 1.5–2px | Transition size — match the body text weight; if using medium-weight body copy, lean toward 2px |
+| 24px | 2px | The most common "default" icon grid. 2px is the industry convention (Lucide, Heroicons, Feather all default here) |
+| 32px | 2–2.5px | Larger icons need more weight to avoid looking drawn with a fine pen against the heavier surrounding UI |
+| 48px+ | 2.5–3px | Display-size icons (app icons, hero illustrations) should be optically balanced to read boldly at distance |
+
+**Pixel alignment rules:** Icons on an even grid (16px, 24px, 32px) align their strokes to whole pixels. Icons on an odd grid (20px, 28px) should have strokes centered on 0.5px boundaries to avoid sub-pixel blur on non-retina displays. For SVG exports, always set `shape-rendering: crispEdges` on icon wrappers, and center the viewBox exactly on the pixel grid (e.g., `viewBox="0 0 24 24"`, not `"0.5 0.5 23 23"`). A stroke centered on the path boundary will anti-alias; a stroke offset by 0.5px will render sharply.
+
+---
+
+## 2. Weight & Stroke Consistency
+
+Never mix stroke weights within the same UI surface. Mixing a 1.5px outline icon next to a 2px icon in the same toolbar creates a visual discord that users register as "something feels off" even if they cannot articulate why. The eye calibrates to a baseline weight, and deviations feel like errors.
+
+**The typography matching principle:** Icon weight should correspond to the surrounding text weight. A regular-weight body paragraph (400) pairs with a regular or medium icon (1.5–2px stroke). A bold heading (700) pairs with a bold or filled icon variant. This alignment creates a perception of visual kinship — the icon "belongs" to the text alongside it rather than floating in from a different design register.
+
+**Practical rule:** Choose one icon library per product surface and use it exclusively. If a specific icon is unavailable in your chosen library, draw it using the same stroke grammar rather than importing a single icon from a different library. The visual inconsistency of mixing libraries is nearly always worse than an imperfect icon from the right library.
+
+---
+
+## 3. Metaphor Taxonomy
+
+Icons communicate meaning through shared cultural metaphors. Understanding the four functional categories prevents category errors — using a navigation metaphor for an action, or a status metaphor for wayfinding.
+
+### Functional (Action) Icons
+
+Functional icons represent user-initiated operations: save, delete, copy, filter, sort, upload, download. They answer the question "what can I do here?" Their metaphors must be action-verifiable — a user looking at the icon should be able to predict the outcome of clicking it. The floppy disk for "save" is a dead metaphor that persists by convention, not visual logic; prefer more literal representations (cloud-upload for cloud save, checkmark-circle for "mark complete") where the action is unambiguous without cultural baggage.
+
+**Recognition test:** Cover the label. Can a first-time user accurately predict what clicking this icon will do? If fewer than 80% of testers answer correctly in usability studies, pair the icon with a text label.
+
+### Status Icons
+
+Status icons communicate system state: success, warning, error, loading, offline, syncing. They answer "what is the system telling me?" Their metaphors are highly convention-bound: green circle-check for success, yellow triangle-exclamation for warning, red circle-X for error. Deviating from these conventions introduces cognitive load — users must re-learn your system's visual language rather than drawing on years of software experience.
+
+**When to use:** Status icons appear adjacent to data fields, system messages, toast notifications, and form validation. They must never be used as the sole indicator of status for users with color vision deficiency — always pair with a distinct shape and a text description.
+
+### Navigation (Wayfinding) Icons
+
+Navigation icons orient users within an information space: home, back, forward, menu, close, external-link, settings. They answer "where am I and how do I move?" Their metaphors are cartographic and gestural — arrows indicate direction of travel, the house represents the origin point, the hamburger menu represents a collapsed list.
+
+**When to use:** Navigation icons appear in navbars, breadcrumbs, sidebars, and dialog controls. Because wayfinding is critical to task completion, navigation icons should almost always be paired with visible labels until the product has established enough user familiarity to support icon-only navigation (typically after repeated-use screens with power users).
+
+### Brand Icons
+
+Brand icons represent identity: logos, product wordmarks, social platform logos, and payment method marks. They follow the brand owner's guidelines, not the product's icon system. Never apply your system's stroke weight or color palette to third-party brand marks — use the official SVG assets. Brand icons communicate "who or what" rather than action, status, or direction.
+
+**Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/icons.csv**
+
+---
+
+## 4. Dark-Mode Icon Variants
+
+A common mistake is inverting an icon library's default black strokes to `#FFFFFF` in dark mode. Pure white icons on dark backgrounds produce harsh contrast that reads as aggressive, particularly for secondary and tertiary actions. More importantly, pure white does not participate in the opacity token system that controls visual hierarchy.
+
+**Use opacity tokens, not white fills.** The correct approach is to define icon colors using a semantic token (`--icon-default`, `--icon-secondary`, `--icon-disabled`) and resolve those tokens differently per color scheme:
+
+```css
+:root {
+  --icon-default: oklch(0.15 0 0);       /* near-black */
+  --icon-secondary: oklch(0.45 0 0);     /* mid-gray */
+  --icon-disabled: oklch(0.70 0 0 / 0.4);
+}
+
+[data-theme="dark"] {
+  --icon-default: oklch(0.92 0 0);       /* near-white, not pure */
+  --icon-secondary: oklch(0.65 0 0);
+  --icon-disabled: oklch(0.40 0 0 / 0.4);
+}
+```
+
+**Icon-on-color contrast rules:** When placing a white icon on a brand primary background (e.g., a white checkmark inside a colored button), the contrast ratio between the icon color and the background must meet WCAG 2.1 AA minimum of 4.5:1 for icons associated with text-size equivalents, and 3:1 for large-scale graphical elements (per WCAG 1.4.11 Non-text Contrast). Use the APCA method for more perceptually accurate contrast estimation in complex color environments.
+
+---
+
+## 5. Icon Animation Guidelines
+
+Animated icons communicate state transitions — they are not decorative flourishes. Every animation should signal a specific semantic event: a state change the user caused, a process completing, or feedback confirming an action.
+
+**Morphing between states (cross-fade pattern):**
+
+When transitioning between two icons (e.g., play → pause, bookmark-outline → bookmark-filled), use the following three-property animation. The outgoing icon exits while the incoming icon enters simultaneously:
+
+```css
+/* Outgoing icon */
+.icon-exit {
+  animation: icon-exit 150ms ease-in forwards;
+}
+@keyframes icon-exit {
+  from { opacity: 1; transform: scale(1); filter: blur(0px); }
+  to   { opacity: 0; transform: scale(0.75); filter: blur(4px); }
+}
+
+/* Incoming icon */
+.icon-enter {
+  animation: icon-enter 200ms ease-out forwards;
+  animation-delay: 100ms;
+}
+@keyframes icon-enter {
+  from { opacity: 0; transform: scale(0.25); filter: blur(4px); }
+  to   { opacity: 1; transform: scale(1); filter: blur(0px); }
+}
+```
+
+This pattern (scale 0.25→1, opacity 0→1, blur 4→0) creates a "materialization" feel that communicates emergence — the new state is coming into existence rather than simply swapping. Duration should be 150–200ms; shorter feels mechanical, longer feels sluggish.
+
+**Rotation for loading states:** A continuous 360° rotation at 700–900ms per revolution communicates "waiting for external process." Use `animation-timing-function: linear` — easing causes visual pulsing that reads as multiple distinct events rather than a continuous state. The rotation axis must be the center of the icon's bounding box.
+
+**Entrance for success states:** A success icon (checkmark, circle-check) should entrance with a brief overshoot — scale from 0 to 1.1 then settle to 1.0 — over 250–300ms using a spring-like timing function (`cubic-bezier(0.175, 0.885, 0.32, 1.275)`). This micro-bounce communicates "confirmed" rather than merely "appeared."
+
+**Respect prefers-reduced-motion:** All icon animations must be disabled or reduced to an instant opacity transition when `@media (prefers-reduced-motion: reduce)` is active.
+
+---
+
+## 6. Semantic vs. Decorative Labeling
+
+The single most common accessibility error in icon implementation is failing to distinguish between semantic icons (conveying meaning) and decorative icons (providing visual accompaniment to text that already conveys the meaning).
+
+**Semantic (interactive standalone) icons require `aria-label`:**
+
+```html
+<!-- Icon-only button — meaning conveyed solely by icon -->
+<button aria-label="Delete item">
+  <svg aria-hidden="true" focusable="false"><!-- trash icon --></svg>
+</button>
+```
+
+The `aria-label` on the button describes the action. The SVG itself receives `aria-hidden="true"` to prevent screen readers from announcing "svg" or the icon's internal text elements. Never rely on `title` elements within SVG for accessible names in interactive contexts — browser support is inconsistent.
+
+**Decorative icons require `aria-hidden="true"`:**
+
+```html
+<!-- Icon accompanies visible label — purely decorative -->
+<button>
+  <svg aria-hidden="true" focusable="false"><!-- search icon --></svg>
+  Search
+</button>
+```
+
+When visible text already conveys the full meaning, the icon is decorative. Hiding it from the accessibility tree prevents redundant announcements ("search graphic, search button").
+
+**Never use a standalone icon as the sole affordance for critical or destructive actions.** Even if the icon is well-recognized (trash = delete), critical actions like permanent deletion, payment confirmation, or account changes must always pair the icon with a visible text label. The cost of an unclear icon on a destructive action is irreversible user harm.
+
+---
+
+## 7. Touch Target Pairing
+
+Visual icon size and interactive touch target size are different concerns. A 16px icon is visually appropriate for compact UI contexts, but an interactive area of 16×16px fails accessibility and usability standards — fingers are much larger than icons.
+
+**Minimum interactive touch targets:**
+
+| Context | Minimum target | Rationale |
+|---------|---------------|-----------|
+| Standard interactive icon | 40×40px | WCAG 2.5.5 Target Size AAA; Apple HIG minimum |
+| Primary action icon | 48×48px | Material Design 3 recommendation for primary actions |
+| Dense data tables | 32×32px | Acceptable for expert-user interfaces with high density requirements |
+
+**Implementation with `::after` pseudo-element:**
+
+This technique extends the clickable area without changing the visual icon size:
+
+```css
+.icon-button {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.icon-button::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 40px;
+  height: 40px;
+  /* Optionally: background: transparent; border-radius: 50%; */
+}
+```
+
+The visual icon remains 20px; the interactive zone expands to 40px. On touch devices, this satisfies pointer accuracy requirements without creating visual padding that disrupts layout density.
+
+---
+
+## 8. Public Icon Library Catalog
+
+Choosing an icon library is an architectural decision — all icons in a product surface should come from a single library to ensure stroke weight and visual grammar consistency. These are the major open-source libraries with their key characteristics.
+
+### Lucide Icons
+Over 1,000 icons under the MIT license. Stroke-based with a consistent 2px stroke weight on a 24px grid. This is the default icon library for shadcn/ui components and has become the de facto standard for React-based design systems. Strong community maintenance with frequent additions. Import individual icons by name to enable tree-shaking: `import { ChevronRight } from 'lucide-react'`. Never import the entire library — the barrel export will bloat bundles.
+
+### Phosphor Icons
+Available in six weights — thin, light, regular, bold, fill, and duotone — making it one of the most expressive icon systems available. MIT licensed. Ideal for products where visual hierarchy needs to be communicated through icon weight variation (e.g., active nav item uses bold, inactive uses regular). The duotone variant provides a two-tone fill that works well in marketing and onboarding contexts.
+
+### Heroicons
+Produced by the Tailwind CSS team. Available in outline and solid variants on a 24px grid. MIT licensed. The outline variant is a 1.5px stroke, which is slightly lighter than Lucide's 2px — choose based on whether your typography leans toward light or regular weight. First-class Tailwind integration and React/Vue packages available.
+
+### Radix Icons
+Designed specifically for the 15px grid rather than the standard 24px grid, making Radix Icons uniquely suited for dense, compact UI contexts — form fields, inline badges, data table actions. They pair directly with Radix UI primitives and share the same design philosophy: functional, unobtrusive, and predictable. MIT licensed.
+
+### Tabler Icons
+Over 3,000 icons with a consistent 2px stroke on a 24px grid. The largest coherent stroke-based icon set available. MIT licensed. Excellent for applications requiring coverage of unusual domains (medical, scientific, geographic) that other libraries do not address. Actively maintained with SVG optimization.
+
+### Iconoir
+Clean, minimal line icons on a 24px grid. MIT licensed. Characterized by a slightly rounded stroke termination that gives it a friendlier character than more angular systems. Well-suited for consumer-facing applications where the brand tonality is approachable and modern rather than corporate or technical.
+
+### Remix Icon
+Open-source with filled and line variants in each icon, organized into semantic categories (system, business, media, communication, etc.). The parallel line/filled pairing makes it straightforward to communicate active vs. inactive states without switching libraries.
+
+### SF Symbols
+Apple's system-native icon library, available exclusively on Apple platforms (iOS, macOS, watchOS, visionOS). Variable weights that match the San Francisco typeface — when the user adjusts text size or boldness in system settings, SF Symbols adjust proportionally. Not available for web or Android; use only in native Swift/SwiftUI or UIKit contexts. Access via `Image(systemName:)` in SwiftUI.
+
+### Feather
+A minimal, classic icon set with 287 icons on a 24px grid at a 2px stroke. MIT licensed. Feather is older than many alternatives on this list and receives fewer updates, but its visual grammar is exceptionally clean and it remains a reliable choice for products that prioritize restraint. The limited catalog means it works best for simple, focused applications rather than complex dashboards.
+
+---
+
+*This reference governs all icon decisions within the get-design-done framework. Deviations require explicit justification in `.design/DESIGN-CONTEXT.md` as a C-XX constraint.*

package/reference/motion.md

@@ -283,3 +283,105 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 3. For many elements, share a single observer instance and call `observe()` once per element.
 4. Prefer CSS transitions triggered by a class toggle over requestAnimationFrame loops.
 5. Use `will-change: transform, opacity` sparingly (only on elements that animate repeatedly).
+
+---
+
+## MIFB Micro-Motion Extensions
+Source: jakubkrehel/make-interfaces-feel-better (MIT) — motion.md
+
+### Interruptible Animations
+
+Use CSS transitions for interactive elements because transitions retarget mid-animation — when a user moves their cursor away before a hover animation completes, the transition reverses smoothly from wherever it currently is. Keyframe animations restart from the beginning, creating a jarring jump.
+
+**Decision rule:**
+- Interactive states (hover, focus, active, pressed): always CSS transitions
+- Orchestrated sequences, entrance effects, data-driven animations: keyframe or JS animation
+
+```css
+/* Good — transition retargets smoothly */
+.button { transition: background-color 150ms ease-out; }
+
+/* Avoid for interactive — restarts on interruption */
+.button:hover { animation: hover-bg 150ms ease-out forwards; }
+```
+
+### Split-and-Stagger Enter/Exit
+
+For multi-element entrances (card grids, lists, feature sections):
+
+- Default stagger: 100ms between elements
+- Heading words: 80ms per word
+- Entrance transform: `opacity: 0 → 1` + `translateY(12px → 0)` + `blur(4px → 0)`
+- Entrance duration: 300ms, `ease-out`
+- Exit transform: `opacity: 1 → 0` + `translateY(0 → -12px)` (opposite direction, smaller offset)
+- Exit duration: 150ms (half the entrance duration — exits should be faster)
+
+The blur component adds a depth cue that makes entrances feel less flat. Keep blur modest (4px) — the goal is a subtle focus effect, not a visible blur.
+
+### Contextual Icon Animations — Cross-Fade Pattern
+
+When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, bookmark ↔ bookmarked), use this exact cross-fade spec:
+
+**Framer Motion spring (preferred):**
+- `scale: 0.25 → 1` (entering), `scale: 1 → 0.25` (exiting)
+- `opacity: 0 → 1` (entering), `opacity: 1 → 0` (exiting)
+- `filter: blur(4px) → blur(0)` (entering), `blur(0) → blur(4px)` (exiting)
+- `transition: { type: "spring", duration: 0.3, bounce: 0 }` — **bounce MUST be 0**
+
+**CSS fallback (no Framer):**
+- Keep both icons in the DOM, one `position: absolute`
+- Use `cubic-bezier(0.2, 0, 0, 1)` easing
+- Duration: 200ms
+
+The scale + blur combination creates a focus-snap effect that feels intentional rather than mechanical. The `bounce: 0` hard constraint exists because any bounce on a 0.25-scale origin point makes icons appear to "pop" invasively.
+
+### Scale on Press — Canonical Value
+
+The canonical scale value for press feedback is **`0.96`**.
+
+Rules:
+- Never use `scale(0.95)` — too large, feels unresponsive
+- Never use `scale(0.97)` — too subtle at high DPI, not perceived as feedback
+- Never use `scale(0.98)` or higher — imperceptible
+- `0.96` is the ONLY correct value for standard interactive elements
+
+Tailwind: `active:scale-[0.96]`
+Framer: `whileTap={{ scale: 0.96 }}`
+
+For primary CTAs where maximum tactility is needed (purchase, send, confirm):
+use `0.96` with a shadow reduction: `box-shadow: none` during press.
+
+Deprecation note: earlier versions of `reference/checklists.md` referenced `scale(0.97)`. That entry has been reconciled. **0.96 is the canonical value.**
+
+### AnimatePresence initial={false}
+
+When `AnimatePresence` wraps UI that exists in the DOM before it enters the animation scope (e.g., a tab panel that renders its first tab immediately, a dropdown that's already open on first load), use `initial={false}`:
+
+```tsx
+<AnimatePresence initial={false}>
+  {isOpen && <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
+</AnimatePresence>
+```
+
+Without `initial={false}`, Framer will animate the FIRST render of children — meaning UI that's immediately visible on page load will "fade in" unnecessarily. This creates a flash/flicker that signals poor craftsmanship.
+
+**Rule:** Any `AnimatePresence` wrapping persistent UI should have `initial={false}`.
+
+### will-change — GPU Property Table
+
+Only add `will-change` when you observe first-frame stutter on lower-end hardware. Do NOT add it preemptively — it consumes GPU memory continuously for every element that has it.
+
+GPU-compositable properties (safe with will-change):
+| Property | will-change value |
+|----------|------------------|
+| transform (translate, scale, rotate) | `transform` |
+| opacity | `opacity` |
+| filter (blur, brightness, contrast) | `filter` |
+| clip-path | `clip-path` |
+
+Never use `will-change: all` or `will-change: contents` — this forces the entire element and its subtree onto a new compositor layer, thrashing memory.
+
+Remove `will-change` after the animation completes if applied dynamically:
+```js
+element.addEventListener('transitionend', () => element.style.willChange = 'auto')
+```

package/reference/palette-catalog.md

@@ -0,0 +1,82 @@
+---
+name: palette-catalog
+type: palette
+version: 1.0.0
+source: "nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/colors.csv"
+tags: [color, palette, wcag, industry]
+---
+
+# Palette Catalog — Industry-Vertical Color Systems
+
+This catalog gives design agents and the brief-stage palette picker a pre-verified starting point for every major industry vertical. Rather than selecting colors ad-hoc, an agent reads the vertical row that matches the product type, adopts the baseline tokens, then adjusts tints and shades to establish brand uniqueness without sacrificing legibility.
+
+## How to Use This Catalog
+
+**Step 1 — Identify the vertical.** Match the product type to the closest row. When a product spans verticals (e.g., a wellness fintech), prefer the primary revenue model as the anchor vertical and borrow the accent color from the secondary vertical.
+
+**Step 2 — Adopt the baseline palette.** The hex values below represent the semantic center of each role: Primary, Secondary, Accent, Background, Foreground, Card, Muted, Border, Destructive. Downstream agents (design-executor, token-mapper) map these directly to CSS custom property names (`--color-primary`, `--color-secondary`, etc.).
+
+**Step 3 — Cross-check brand voice.** Palette choice must align with the voice axis established in the brief. A palette that reads "authoritative navy" conflicts with a voice direction of "playful and irreverent." Resolve conflicts in favor of the voice axis — palettes are easier to shift than voice. For industry voice conventions, see `reference/brand-voice.md`.
+
+**Step 4 — Adjust for brand uniqueness.** All values here are mid-point baselines. Shift the primary hue ±15°, adjust lightness ±10%, or introduce a proprietary tint to differentiate the brand. Do not use these hex values verbatim in production without at least one brand-distinguishing adjustment.
+
+**Step 5 — Verify pairing.** After choosing the palette, consult `reference/typography.md` for matching typeface pairings that reinforce the vertical's tone.
+
+## WCAG Compliance Notes
+
+All palettes in this catalog are designed to meet WCAG 2.1 AA as a baseline:
+
+- **Body text:** Foreground-on-Background must achieve a contrast ratio of at least **4.5:1**. All rows in this table satisfy this requirement at the listed values.
+- **UI elements (icons, borders, input outlines):** Must achieve at least **3:1** against their adjacent background. Verify muted and border values when used as sole affordance indicators.
+- **Destructive actions:** The Destructive color is always shown against white (On-Primary) — verify contrast when placed on colored backgrounds.
+- **Dark mode:** This catalog covers light-mode baselines. For dark mode, invert the lightness scale — Background moves to #0A0A0A–#1C1C1E range, Foreground to #F5F5F5, and Primary desaturates by 20% to reduce eye strain. See `reference/accessibility.md` for dark-mode token guidance.
+
+> Note: Neumorphism palettes are not represented here because they structurally fail WCAG contrast requirements in most implementations. If a brief requests a neumorphic style, escalate to design-advisor before proceeding with palette selection.
+
+## Palette Table
+
+| Vertical | Primary | On-Primary | Secondary | On-Secondary | Accent | Background | Foreground | Card | Muted | Border | Destructive | Notes |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| FinTech/Banking | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #E02424 | Authoritative navy-blue signals trust and regulatory solidity; green secondary for positive account states and confirmations; red destructive for irreversible transfers and deletions. WCAG verified. |
+| Healthcare/Medical | #0E9F6E | #FFFFFF | #1A56DB | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #E02424 | Clinical green primary communicates health and safety; blue secondary for informational states; amber accent for caution alerts. Avoids emergency red as primary to prevent alarm. WCAG verified. |
+| SaaS/B2B Tools | #6875F5 | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #FFFFFF | #111928 | #F9FAFB | #F3F4F6 | #E5E7EB | #E02424 | Periwinkle-purple primary is the contemporary B2B SaaS signal (productively calm, not boring blue); green secondary for success states; red destructive. Cards slightly off-white to create depth without shadows. WCAG verified. |
+| E-commerce/Retail | #D97706 | #FFFFFF | #1A56DB | #FFFFFF | #E02424 | #FFFFFF | #111928 | #F9FAFB | #FEF3C7 | #E5E7EB | #DC2626 | Amber primary drives purchase urgency and warmth; blue secondary for trust (payments, account); muted in warm-yellow family for promotional surfaces. Avoid pure red as primary — reserve for destructive/sale badges. WCAG verified. |
+| Gaming/Entertainment | #7E3AF2 | #FFFFFF | #FF8A4C | #111928 | #F05252 | #111928 | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Deep violet primary on dark background — high visual energy without neon; amber accent for XP/reward moments; dark card on near-black background creates depth. Light foreground on dark background meets 4.5:1. WCAG verified. |
+| Social/Community | #3F83F8 | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #FFFFFF | #111928 | #F9FAFB | #EFF6FF | #E5E7EB | #DC2626 | Friendly blue primary — approachable, not corporate; green for connection/online states; light muted sky for feed background separation. WCAG verified. |
+| Developer Tools | #0F172A | #F8FAFC | #6875F5 | #FFFFFF | #22D3EE | #F8FAFC | #0F172A | #FFFFFF | #F1F5F9 | #CBD5E1 | #EF4444 | Near-black primary on white for precision and professionalism; purple secondary for interactive elements; cyan accent for syntax-highlight-inspired pops. Matches developer expectations set by GitHub, Linear, Vercel. WCAG verified. |
+| EdTech/Learning | #FF8A4C | #FFFFFF | #6875F5 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm amber primary is energizing and optimistic — signals motivation and focus; violet secondary for interactive quiz/exercise elements; warm background avoids clinical white. WCAG verified. |
+| Legal/Compliance | #1E3A5F | #FFFFFF | #374151 | #FFFFFF | #B45309 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Deep navy primary signals authority, gravity, and precision; slate secondary for neutral UI chrome; amber accent for deadlines and flagged items. No bright colors — the palette communicates seriousness. WCAG verified. |
+| HR/People Ops | #7E3AF2 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3F4F6 | #E9D5FF | #DC2626 | Violet primary balances authority and empathy — appropriate for people-management contexts; amber secondary for recognition/reward surfaces; lavender muted for soft separation. WCAG verified. |
+| Real Estate/Property | #065F46 | #FFFFFF | #1A56DB | #FFFFFF | #B45309 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep forest green primary signals land, stability, and value; blue secondary for financing/trust contexts; amber accent for featured/premium listings. Avoids the overused real-estate red. WCAG verified. |
+| Travel/Hospitality | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #EFF6FF | #111928 | #FFFFFF | #DBEAFE | #BFDBFE | #DC2626 | Sky blue primary evokes open skies and freedom; green secondary for bookings confirmed and eco-travel; warm amber accent for warmth of destination discovery. Sky-tinted muted background is distinctive. WCAG verified. |
+| Food/Delivery | #D97706 | #FFFFFF | #E02424 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary stimulates appetite and speed; red secondary for urgency (limited offers, spicy badge) — distinct from destructive red which is darker; warm background mirrors food photography warmth. WCAG verified. |
+| Fitness/Wellness | #047857 | #FFFFFF | #1A56DB | #FFFFFF | #F05252 | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #BBF7D0 | #DC2626 | Saturated green primary signals vitality, growth, and health achievement; blue secondary for calm recovery/sleep contexts; red accent for intensity/max-effort moments. Green-tinted background reinforces wellness. WCAG verified. |
+| Non-profit/NGO | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep green primary signals mission and environmental conscience; amber secondary for warmth and community; blue accent for data/impact reporting. Avoid corporate-looking palettes — earthy and grounded. WCAG verified. |
+| Government/Civic | #1E3A5F | #FFFFFF | #374151 | #FFFFFF | #D97706 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Deep navy is the global convention for government digital services (GOV.UK, USWDS, Australian DTA); slate secondary for dense information displays; amber accent for notices and alerts. Trust through convention. WCAG verified. |
+| Luxury/Fashion | #111928 | #F9FAFB | #374151 | #F9FAFB | #B45309 | #FFFFFF | #111928 | #F9FAFB | #F9FAFB | #E5E7EB | #DC2626 | Near-black primary on white background is the international language of luxury — Chanel, Saint Laurent, Bottega; slate secondary for layered surfaces; gold-amber accent for price points and premium badges. Minimum color = maximum status. WCAG verified. |
+| Media/Publishing | #111928 | #F9FAFB | #E02424 | #FFFFFF | #D97706 | #FFFFFF | #111928 | #F9FAFB | #F3F4F6 | #E5E7EB | #B91C1C | Near-black primary on white mirrors newspaper printing conventions — ink on paper; red secondary for breaking news, featured sections, and editorial accents (NYT, BBC, The Guardian pattern); amber for secondary sections. WCAG verified. |
+| Analytics/BI | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Blue primary is the universal data-visualization anchor color — maps cleanly to sequential chart palettes; green secondary for positive delta/growth; amber accent for cautionary thresholds. Minimal decoration — the data is the hero. WCAG verified. |
+| AI/ML Platform | #4F46E5 | #FFFFFF | #7E3AF2 | #FFFFFF | #22D3EE | #0F172A | #F8FAFC | #1E293B | #334155 | #475569 | #EF4444 | Indigo primary on dark background — the established AI product visual language (Anthropic, Cohere, Mistral); violet secondary for model/capability exploration; cyan accent for real-time/streaming states. Dark-first layout. WCAG verified. |
+| Cybersecurity | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #22D3EE | #0A0A0A | #F8FAFC | #111827 | #1F2937 | #374151 | #EF4444 | Deep navy on near-black background signals a monitoring environment; green secondary for "all clear" / healthy system states; cyan accent for network traffic visualization and active scanning states. Terminal-inspired palette. WCAG verified. |
+| Logistics/Supply Chain | #D97706 | #111928 | #1A56DB | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Amber primary mirrors physical logistics — high-vis safety colors, warehouse signage, shipping labels; blue secondary for tracking/digital interfaces; warm background differentiates from generic enterprise SaaS. WCAG verified. |
+| Insurance | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #D97706 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Navy primary signals protection, stability, and reliability — the universal insurance palette anchor (Allianz, AXA pattern); green secondary for claims approved and policy active states; amber for upcoming renewals and caution. WCAG verified. |
+| Automotive | #111928 | #F9FAFB | #374151 | #F9FAFB | #E02424 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #B91C1C   | Near-black primary matches the premium automotive convention — matte dark, precision engineering; red accent for performance/sport trims and urgency (limited availability); silver-gray secondary for neutral chrome surfaces. WCAG verified. |
+| Agriculture/AgriTech | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #A7F3D0 | #DC2626 | Deep green primary is literal and honest — crops, fields, sustainability; amber secondary for harvest, yield, soil richness; blue accent for water management and satellite data. Green-tinted background grounds the product in nature. WCAG verified. |
+| CleanTech/Sustainability | #047857 | #FFFFFF | #1A56DB | #FFFFFF | #D97706 | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #BBF7D0 | #DC2626 | Rich emerald primary signals genuine environmental commitment — distinct from generic "eco green"; blue secondary for water/energy resource tracking; amber accent for carbon credit and offset metrics. Avoid greenwashing: use the earthy tones. WCAG verified. |
+| Pharmaceutical | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Regulated navy primary signals clinical authority and FDA compliance; green secondary for dosage confirmed and health-positive states; amber accent for contraindications and warnings. Never use red as primary — reserved for severe adverse events only. WCAG verified. |
+| Architecture/AEC | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Slate primary evokes material neutrality — concrete, steel, rendered surfaces; amber secondary for warmth of wood, brick, and material samples; blue accent for technical drawings and BIM layers. Restrained palette mirrors blueprint conventions. WCAG verified. |
+| Interior Design | #92400E | #FFFFFF | #065F46 | #FFFFFF | #1E3A5F | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm terracotta-brown primary evokes material warmth — timber, linen, clay; deep green secondary for biophilic design moments and plant integration; warm cream background mimics actual interior photography styling. WCAG verified. |
+| Music/Audio | #111928 | #F9FAFB | #7E3AF2 | #FFFFFF | #F05252 | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark primary — music is a dark-mode-first medium (Spotify, SoundCloud, Apple Music pattern); violet secondary for playlist/discovery surfaces; red accent for recording states and live moments. WCAG verified on dark background. |
+| Photography/Video | #111928 | #F9FAFB | #374151 | #F9FAFB | #FF8A4C | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark canvas lets photography and video content take center stage — the UI must disappear; slate secondary for control surfaces; amber accent for selected states and active tools. WCAG verified on dark background. |
+| Crypto/Web3 | #4F46E5 | #FFFFFF | #0E9F6E | #FFFFFF | #F59E0B | #0F172A | #F8FAFC | #1E293B | #334155 | #475569 | #EF4444 | Indigo on dark background signals the crypto-native aesthetic (Coinbase, Uniswap pattern); green secondary for price-up and confirmed transaction states; gold accent for high-value wallet events. Dark-first mandatory. WCAG verified. |
+| Marketing/AdTech | #D97706 | #111928 | #E02424 | #FFFFFF | #7E3AF2 | #FFFFFF | #111928 | #F9FAFB | #FEF3C7 | #FDE68A | #B91C1C | Amber primary signals campaign energy and conversion urgency; red secondary for CTAs and limited-offer badges; violet accent for creative/brand moments. Warm background differentiates from SaaS tools. WCAG verified. |
+| Recruitment/HR Tech | #7E3AF2 | #FFFFFF | #1A56DB | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3E8FF | #E9D5FF | #DC2626 | Violet primary signals human potential and opportunity — differentiated from corporate blue; navy secondary for employer-side trust; green accent for application submitted and offer extended. Lavender muted backgrounds are distinctive in the space. WCAG verified. |
+| Customer Support/CX | #0E9F6E | #FFFFFF | #3F83F8 | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Green primary signals resolution and "all good" — the opposite of customer frustration red; blue secondary for informational knowledge base surfaces; amber accent for escalation and SLA-risk alerts. WCAG verified. |
+| E-learning/MOOC | #6875F5 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #F9FAFB | #111928 | #FFFFFF | #EFF6FF | #E0E7FF | #DC2626 | Periwinkle primary is academically focused yet modern — bridges EdTech energy with SaaS discipline; amber secondary for assignment deadlines and achievement badges; green accent for progress and course completion. WCAG verified. |
+| Telemedicine | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #EFF6FF | #111928 | #FFFFFF | #DBEAFE | #BFDBFE | #DC2626 | Blue primary signals clinical authority and digital trust — video-consult contexts require colors that photograph well on video call backgrounds; green secondary for patient-status OK and prescription-ready states; sky-blue background creates a calm, clinical context. WCAG verified. |
+| Smart Home/IoT | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #F59E0B | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep navy primary signals reliable infrastructure and always-on connectivity; green secondary for device-online and automation-active states; amber accent for device warnings and energy usage peaks. Functional palette — never decorative. WCAG verified. |
+| Manufacturing/Industrial | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Slate primary mirrors industrial material honesty — steel, aluminum, precision tooling; amber secondary mirrors high-visibility safety equipment conventions; blue accent for digital HMI overlays and OEE dashboards. Avoid soft consumer palettes. WCAG verified. |
+| Construction | #D97706 | #111928 | #374151 | #FFFFFF | #1A56DB | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary is literal high-vis construction site signaling — hard hats, caution tape, equipment; slate secondary for technical drawing and plan review surfaces; blue accent for BIM integration and weather/site tracking. Warm background. WCAG verified. |
+
+For matching typography pairings by vertical, see `reference/typography.md`.
+For industry voice conventions that must align with palette choice, see `reference/brand-voice.md`.