@hegemonart/get-design-done 1.14.8 → 1.16.0

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`.

package/reference/performance.md

@@ -0,0 +1,304 @@
+# Performance — Reference Guide
+
+Performance is a design constraint, not an engineering afterthought. Every millisecond of delay in LCP is a measurable reduction in conversion rate; every layout shift during page load erodes user trust. This reference establishes authoritative performance budgets, measurement targets, and implementation rules for all project types handled by the get-design-done framework.
+
+---
+
+## 1. Core Web Vitals Targets by Project Type
+
+Google's Core Web Vitals are the industry-standard performance metrics for user experience. They measure loading (LCP), interactivity (INP), and visual stability (CLS). Understanding the thresholds and how they vary by project type is essential for setting appropriate design constraints during the planning phase.
+
+### Universal Thresholds
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| LCP (Largest Contentful Paint) | ≤2.5s | 2.5–4.0s | >4.0s |
+| INP (Interaction to Next Paint) | ≤200ms | 200–500ms | >500ms |
+| CLS (Cumulative Layout Shift) | ≤0.1 | 0.1–0.25 | >0.25 |
+| TTFB (Time to First Byte) | ≤800ms | 800ms–1.8s | >1.8s |
+
+### SaaS / Dashboard Applications
+
+Authenticated dashboard applications carry more JavaScript, more real-time data subscriptions, and more complex component trees than public pages. LCP tolerance is relaxed to ≤3.0s because users have a high motivation to wait (they are trying to accomplish a work task) and the LCP element is often a data-heavy chart or table that legitimately takes time to render. However, INP must be held to ≤200ms strictly — dashboards involve dense interaction patterns (filter, sort, paginate, drill down) and a sluggish response loop destroys the power-user experience.
+
+### Marketing / Landing Pages
+
+Conversion-critical pages have zero tolerance for perceived slowness. LCP must reach ≤2.0s because first impressions determine bounce rate, and bounce rate directly impacts conversion. CLS must be ≤0.05 (half the general threshold) because layout pop during hero section rendering — caused by web font loading, lazy image dimensions, or server-side-rendered content shifting — destroys the premium impression marketing pages are designed to create. Every 100ms of LCP improvement correlates with measurable conversion lift in e-commerce and SaaS trials.
+
+### E-Commerce
+
+| Metric | Target | Rationale |
+|--------|--------|-----------|
+| LCP | ≤2.5s | Product images are the LCP element — optimize aggressively |
+| CLS | ≤0.1 | Price and "Add to Cart" button must not jump as images load |
+| INP | ≤200ms | Cart interactions, quantity updates, and variant selection must feel instant |
+
+Cart and checkout flows are revenue-critical paths where a 500ms interaction delay demonstrably increases abandonment. Prioritize INP on product pages and checkout funnels above other optimization work.
+
+### Documentation Sites
+
+| Metric | Target | Rationale |
+|--------|--------|-----------|
+| LCP | ≤3.0s | Docs users are high-intent; tolerate slightly longer loads |
+| CLS | ≤0.1 | Code blocks and long-form content must not reflow after load |
+| TTFB | ≤600ms | Docs are often statically generated — TTFB should approach CDN speed |
+
+Documentation sites benefit from aggressive static generation and CDN distribution. TTFB at ≤600ms is achievable with proper static export (Next.js, Astro, Docusaurus) and CDN edge caching.
+
+---
+
+## 2. Critical CSS Strategy
+
+The browser must parse and execute CSS before it can paint pixels. CSS that blocks rendering is the most impactful optimization target after eliminating render-blocking JavaScript. The goal is to get the above-the-fold experience to paint within the first TCP round trip (≤14KB compressed).
+
+**Inline above-the-fold styles:** Identify the CSS rules that affect visible content within the initial viewport — typically layout grid, hero component, navigation bar, and typography declarations. Inline these rules in a `<style>` block in the `<head>`. Keep this block under 14KB compressed, which corresponds to approximately 40–60KB uncompressed depending on your gzip ratio.
+
+**Defer non-critical CSS with preload:** Load the full stylesheet asynchronously to prevent it from blocking rendering:
+
+```html
+<link rel="preload" href="/styles/main.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+<noscript><link rel="stylesheet" href="/styles/main.css"></noscript>
+```
+
+This pattern preloads the stylesheet at high priority (ensuring it is fetched before it is needed) while not blocking rendering. The `onload` handler promotes the `rel` from `preload` to `stylesheet` once the file is ready, applying styles without a flash of unstyled content.
+
+**CSS containment for performance isolation:** Use `contain: layout style` on components that are visually self-contained (cards, sidebars, modals). Containment tells the browser that layout and style changes inside the component cannot affect elements outside it, enabling the browser to skip recalculation of the rest of the page tree when internal changes occur. This is particularly valuable for frequently-updated dashboard widgets and animated components.
+
+---
+
+## 3. Image Budgets
+
+Images are typically the single largest contributor to LCP and total page weight. Every image decision — format, dimensions, lazy-loading strategy, and priority — directly affects Core Web Vitals.
+
+**Format requirements:**
+- **Photos and complex rasters:** WebP as primary format, AVIF as progressive enhancement where browser support allows. Never ship JPEG or PNG for photos in new projects. AVIF achieves 20–50% smaller file sizes than WebP at equivalent visual quality; use it where CMS and CDN pipelines support it.
+- **Icons and logos:** SVG only. Never rasterize icons for web delivery — SVGs are resolution-independent, style-inheriting, and typically smaller than equivalent PNG at display sizes.
+- **Illustrations:** SVG if illustration complexity allows; WebP for complex multi-color illustrations that would produce large SVG files.
+
+**Responsive images with `srcset`:**
+
+```html
+<img
+  src="/images/hero.webp"
+  srcset="/images/hero-480.webp 480w, /images/hero-960.webp 960w, /images/hero-1920.webp 1920w"
+  sizes="(max-width: 640px) 100vw, (max-width: 1280px) 80vw, 1200px"
+  alt="[descriptive alt text]"
+  width="1920"
+  height="1080"
+/>
+```
+
+Always specify `width` and `height` attributes. These allow the browser to reserve the correct space before the image loads, eliminating CLS from image loading. The `sizes` attribute tells the browser what display size to expect at each breakpoint so it can select the optimal `srcset` candidate.
+
+**Lazy loading below-the-fold images:** Apply `loading="lazy"` to all images that are not visible in the initial viewport. This defers their network requests until the user scrolls toward them, reducing initial page weight significantly on image-heavy pages.
+
+**The LCP image must never be lazy-loaded.** The LCP image — typically the hero image or first product image — must load as fast as possible. Apply `fetchpriority="high"` to signal the browser to deprioritize other resources in favor of this image:
+
+```html
+<img
+  src="/images/hero.webp"
+  fetchpriority="high"
+  loading="eager"
+  alt="[descriptive alt text]"
+  width="1200"
+  height="600"
+/>
+```
+
+---
+
+## 4. Animation Frame Budget
+
+Smooth animation requires a consistent 60 frames per second, which means each frame must complete in ≤16.67 milliseconds. Exceeding this budget causes visible frame drops ("jank") that make interfaces feel cheap and unresponsive.
+
+**Frame budget allocation:**
+
+| Phase | Budget | What fits |
+|-------|--------|-----------|
+| JavaScript execution | ≤10ms | Style recalculation triggers, event handlers, React renders |
+| Rendering pipeline | ≤6ms | Layout, paint, composite |
+| **Total** | **≤16.67ms** | One 60fps frame |
+
+**Never animate layout-triggering properties.** Properties like `width`, `height`, `margin`, `padding`, `top`, `left`, `right`, `bottom`, `border-width`, and `font-size` force the browser to recalculate layout for the entire affected subtree on every animation frame. This is guaranteed to exceed the 10ms JS budget on all but the simplest pages.
+
+**Only animate `transform` and `opacity`.** These two properties are composited by the GPU independently of the browser's main thread layout system. An animation that only changes `transform` and `opacity` does not trigger layout or paint — it executes entirely on the compositor thread, achieving smooth 60fps even when the main thread is busy:
+
+```css
+/* DO: GPU-composited, no layout cost */
+.card-enter {
+  animation: card-enter 200ms ease-out;
+}
+@keyframes card-enter {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+/* DO NOT: forces layout recalculation every frame */
+@keyframes card-enter-bad {
+  from { margin-top: 8px; }
+  to   { margin-top: 0; }
+}
+```
+
+Use `will-change: transform, opacity` on elements that will be animated to promote them to their own compositor layer before the animation begins. Use this property sparingly — each compositor layer consumes GPU memory, and overuse causes memory pressure on mobile devices.
+
+---
+
+## 5. JavaScript Bundle Budgets
+
+Bundle size is a proxy for parse time and execution time, both of which block interactivity. Every kilobyte of JavaScript must be justified against its user-visible value.
+
+**Initial load budget:** The JavaScript required to render the first meaningful page interaction must be ≤170KB gzipped. This budget includes the framework runtime, routing, and any above-the-fold component logic. At average mobile connection speeds (≈1.5 Mbps download), 170KB gzipped represents approximately 900ms of transfer time — already a significant portion of a 2.5s LCP budget before parse and execution time is counted.
+
+**Code splitting strategy:**
+- **Route-level splitting:** Each page/route is a separate async chunk. Users only download code for the pages they visit.
+- **Vendor chunk isolation:** Isolate `node_modules` dependencies into a separate chunk that can be cached independently of application code. Application code changes on every deploy; library code changes rarely.
+- **Lazy component loading:** Use `React.lazy()` with `Suspense` for components that are not required for the initial render (modals, drawers, complex charts):
+
+```tsx
+const DataChart = React.lazy(() => import('./DataChart'));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<ChartSkeleton />}>
+      <DataChart />
+    </Suspense>
+  );
+}
+```
+
+**Never use synchronous `import()` in a render path.** Dynamic `import()` inside a React render function will fire on every render, creating network requests during rendering. Load dynamic imports in effects, event handlers, or route loaders.
+
+**Icon library tree-shaking:** Icon libraries are the most common source of unintentional bundle bloat. A single barrel import (`import * as Icons from 'lucide-react'`) will include all 1,000+ icons in the bundle. Always use named imports: `import { ChevronRight, Search } from 'lucide-react'`. Configure your bundler to use `sideEffects: false` in `package.json` for icon packages to enable full tree-shaking.
+
+---
+
+## 6. Font Budgets
+
+Web fonts are blocking resources in the critical rendering path. Every additional font family, weight, and style file adds to the payload that must load before text can be rendered.
+
+**Maximum two font families per product.** One for headings/display, one for body and UI. This constraint is both a performance budget and a typographic discipline — every additional font family increases visual complexity and requires justification against a clear aesthetic goal.
+
+**`font-display: swap` is required.** This CSS property instructs the browser to use a system fallback font immediately and swap in the web font when it loads. Without `swap`, text is invisible during font loading (FOIT — Flash of Invisible Text), which directly hurts LCP and user experience:
+
+```css
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/inter-variable.woff2') format('woff2-variations');
+  font-display: swap;
+  font-weight: 100 900;
+}
+```
+
+**Preload critical font weights:** The most visually prominent weight of the body font (typically 400) and the primary heading weight (600 or 700) should be preloaded:
+
+```html
+<link rel="preload" href="/fonts/inter-400.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/fonts/inter-700.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+**Variable fonts for 3+ weights:** If a project uses three or more weights of a single typeface, use a variable font rather than separate weight files. One variable font file covers the entire weight axis and is typically smaller than three separate weight files combined. Variable fonts also enable smooth weight animations (`font-weight` transitions).
+
+**Unicode subsetting:** Use the `unicode-range` descriptor to split fonts into subsets that load only when the characters in that range appear on the page:
+
+```css
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/inter-latin.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
+}
+```
+
+**Total font payload target:** ≤100KB across all font files for the initial page load. Variable fonts for Latin character sets typically fall in the 50–80KB range for a single family.
+
+---
+
+## 7. Lighthouse CI Integration
+
+Automated performance regression testing prevents gradual budget creep — small performance regressions accumulate unnoticed through routine development until the product is significantly slower than its target.
+
+**GitHub Actions workflow:** Create `.github/workflows/lighthouse.yml` to run Lighthouse CI on every pull request against a staging deployment:
+
+```yaml
+name: Lighthouse CI
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  lighthouse:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Lighthouse CI
+        uses: treosh/lighthouse-ci-action@v11
+        with:
+          urls: |
+            ${{ env.STAGING_URL }}
+            ${{ env.STAGING_URL }}/products
+          budgetPath: ./lighthouse-budget.json
+          uploadArtifacts: true
+```
+
+**Budget configuration in `lighthouse-budget.json`:**
+
+```json
+[{
+  "path": "/*",
+  "timings": [
+    { "metric": "largest-contentful-paint", "budget": 2500 },
+    { "metric": "interactive", "budget": 3500 },
+    { "metric": "cumulative-layout-shift", "budget": 0.1 }
+  ],
+  "resourceSizes": [
+    { "resourceType": "script", "budget": 170 },
+    { "resourceType": "font", "budget": 100 }
+  ],
+  "resourceCounts": [
+    { "resourceType": "third-party", "budget": 10 }
+  ]
+}]
+```
+
+**Block PRs on regression:** Configure the CI step to fail (blocking merge) when LCP regresses by more than 500ms compared to the base branch, or when the overall Lighthouse Performance score drops below 90. Regressions in accessibility and best practices scores below 90 should also be treated as blocking failures.
+
+---
+
+## 8. React Runtime Performance
+
+React's rendering model is optimized by default, but naive usage patterns — particularly around object identity, memoization, and context — can introduce significant re-render cascades that degrade INP and animation smoothness.
+
+**Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT)**
+
+### `React.memo()`
+
+Use `React.memo()` only when the React DevTools Profiler demonstrates that a component re-renders with identical props and the render takes ≥50ms. `React.memo()` adds overhead — a shallow prop comparison on every parent render — that only pays for itself when the avoided render cost exceeds the comparison cost. Never memoize components that receive primitive values (strings, numbers, booleans) as props; React's reconciler handles these efficiently without memoization.
+
+### `useMemo()`
+
+Use `useMemo()` for computationally expensive derivations — sorting or filtering large arrays, running statistical calculations, or building complex objects from raw data — where the computation takes more than 1ms and the dependencies are stable across most renders. Do not use `useMemo()` to memoize simple object creation for the purpose of maintaining reference identity; instead, move the object outside the component or into a `useRef` if it is genuinely static.
+
+### `useCallback()`
+
+Use `useCallback()` when a function is passed as a prop to a memoized child component and the function's creation would invalidate the child's memo on every parent render. `useCallback()` is not needed for event handlers attached directly to DOM elements (`onClick`, `onChange`) — the DOM does not compare function references. The cost of useCallback (closure creation + dependency comparison) is only justified when it prevents a measurable re-render cascade.
+
+### Re-render Root Causes
+
+The two most common causes of unnecessary re-renders are (1) new object and array references created inline in JSX, and (2) Context value changes propagating to all consumers. Avoid `value={{ key: value }}` inline in Context providers — this creates a new object reference on every parent render, re-rendering all consumers. Memoize the context value with `useMemo()` or split contexts so consumers only subscribe to the slice of state they need.
+
+Avoid anonymous arrow functions as props to performance-critical components: `<List onItemClick={() => handleClick(id)} />` creates a new function reference on every render of the parent.
+
+### Suspense Boundaries
+
+Place Suspense boundaries at two levels: route-level (wrapping each page's lazy-loaded component tree) and per-expensive-async-boundary (wrapping individual data-fetching components that have independent loading states). The fallback UI must match the approximate layout dimensions of the loaded content — a fallback that occupies significantly different space than the loaded component will cause CLS when the content arrives.
+
+### React Server Components vs. Client Components
+
+Use RSC (React Server Components) for data fetching, static markup generation, and components that do not require browser APIs or user interaction. RSC output is streamed as HTML — it adds zero JavaScript to the client bundle. Use client components (`'use client'`) only when browser APIs (localStorage, geolocation, IntersectionObserver) or event handlers (onClick, onChange) are required. Co-locate client components as deep in the component tree as possible so that only the interactive leaf nodes are included in the client bundle, not their entire parent subtrees.
+
+### Virtualization
+
+Never render more than 100 list items into the DOM simultaneously. Beyond this threshold, DOM node count degrades scroll performance, memory consumption, and garbage collection pauses. Use `react-window` for fixed-size list virtualization or `@tanstack/virtual` for variable-height items, table virtualization, and grid layouts. Virtualization renders only the items currently visible in the viewport plus a configurable overscan buffer, keeping DOM node count constant regardless of list length.
+
+---
+
+*Performance budgets defined here are enforced as acceptance criteria in `.design/STATE.md` must-haves for all phases involving UI implementation.*