oh-my-opencode 4.9.2 → 4.11.0

package/packages/shared-skills/skills/frontend/references/design/taste-skill.md

@@ -0,0 +1,226 @@
+---
+name: design-taste-frontend
+description: Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering.
+---
+
+# High-Agency Frontend Skill
+
+## 1. ACTIVE BASELINE CONFIGURATION
+* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
+* MOTION_INTENSITY: 6 (1=Static/No movement, 10=Cinematic/Magic Physics)
+* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)
+
+**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 6, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts. Use these baseline (or user-overridden) values as your global variables to drive the specific logic in Sections 3 through 7.
+
+## 2. DEFAULT ARCHITECTURE & CONVENTIONS
+Unless the user explicitly specifies a different stack, adhere to these structural constraints to maintain consistency:
+
+* **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), you MUST check `package.json`. If the package is missing, you MUST output the installation command (e.g. `npm install package-name`) before providing the code. **Never** assume a library exists.
+* **Framework & Interactivity:** React or Next.js. Default to Server Components (`RSC`). 
+    * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
+    * **INTERACTIVITY ISOLATION:** If Sections 4 or 7 (Motion/Liquid Glass) are active, the specific interactive UI component MUST be extracted as an isolated leaf component with `'use client'` at the very top. Server Components must exclusively render static layouts.
+* **State Management:** Use local `useState`/`useReducer` for isolated UI. Use global state strictly for deep prop-drilling avoidance.
+* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling. 
+    * **TAILWIND VERSION LOCK:** Check `package.json` first. Do not use v4 syntax in v3 projects. 
+    * **T4 CONFIG GUARD:** For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
+* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (Radix, Phosphor) or clean SVG primitives. Emojis are BANNED.
+* **Responsiveness & Spacing:**
+  * Standardize breakpoints (`sm`, `md`, `lg`, `xl`).
+  * Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
+  * **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent catastrophic layout jumping on mobile browsers (iOS Safari).
+  * **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
+* **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
+
+
+## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
+LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
+
+**Rule 1: Deterministic Typography**
+* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
+    * **ANTI-SLOP:** Discourage `Inter` for "Premium" or "Creative" vibes. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
+    * **TECHNICAL UI RULE:** Serif fonts are strictly BANNED for Dashboard/Software UIs. For these contexts, use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
+* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
+
+**Rule 2: Color Calibration**
+* **Constraint:** Max 1 Accent Color. Saturation < 80%.
+* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
+* **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
+
+**Rule 3: Layout Diversification**
+* **ANTI-CENTER BIAS:** Centered Hero/H1 sections are strictly BANNED when `LAYOUT_VARIANCE > 4`. Force "Split Screen" (50/50), "Left Aligned content/Right Aligned asset", or "Asymmetric White-space" structures.
+
+**Rule 4: Materiality, Shadows, and "Anti-Card Overuse"**
+* **DASHBOARD HARDENING:** For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logic-grouping via `border-t`, `divide-y`, or purely negative space. Data metrics should breathe without being boxed in unless elevation (z-index) is functionally required.
+* **Execution:** Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.
+
+**Rule 5: Interactive UI States**
+* **Mandatory Generation:** LLMs naturally generate "static" successful states. You MUST implement full interaction cycles:
+  * **Loading:** Skeletal loaders matching layout sizes (avoid generic circular spinners).
+  * **Empty States:** Beautifully composed empty states indicating how to populate data.
+  * **Error States:** Clear, inline error reporting (e.g., forms).
+  * **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push indicating success/action.
+
+**Rule 6: Data & Form Patterns**
+* **Forms:** Label MUST sit above input. Helper text is optional but should exist in markup. Error text below input. Use a standard `gap-2` for input blocks.
+
+## 4. CREATIVE PROACTIVITY (Anti-Slop Implementation)
+To actively combat generic AI designs, systematically implement these high-end coding concepts as your baseline:
+* **"Liquid Glass" Refraction:** When glassmorphism is needed, go beyond `backdrop-blur`. Add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate physical edge refraction.
+* **Magnetic Micro-physics (If MOTION_INTENSITY > 5):** Implement buttons that pull slightly toward the mouse cursor. **CRITICAL:** NEVER use React `useState` for magnetic hover or continuous animations. Use EXCLUSIVELY Framer Motion's `useMotionValue` and `useTransform` outside the React render cycle to prevent performance collapse on mobile.
+* **Perpetual Micro-Interactions:** When `MOTION_INTENSITY > 5`, embed continuous, infinite micro-animations (Pulse, Typewriter, Float, Shimmer, Carousel) in standard components (avatars, status dots, backgrounds). Apply premium Spring Physics (`type: "spring", stiffness: 100, damping: 20`) to all interactive elements—no linear easing.
+* **Layout Transitions:** Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions across state changes.
+* **Staggered Orchestration:** Do not mount lists or grids instantly. Use `staggerChildren` (Framer) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) to create sequential waterfall reveals. **CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass the data as props into a centralized Parent Motion wrapper.
+
+## 5. PERFORMANCE GUARDRAILS
+* **DOM Cost:** Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements (e.g., `fixed inset-0 z-50 pointer-events-none`) and NEVER to scrolling containers to prevent continuous GPU repaints and mobile performance degradation.
+* **Hardware Acceleration:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`.
+* **Z-Index Restraint:** NEVER spam arbitrary `z-50` or `z-10` unprompted. Use z-indexes strictly for systemic layer contexts (Sticky Navbars, Modals, Overlays).
+
+## 6. TECHNICAL REFERENCE (Dial Definitions)
+
+### DESIGN_VARIANCE (Level 1-10)
+* **1-3 (Predictable):** Flexbox `justify-center`, strict 12-column symmetrical grids, equal paddings.
+* **4-7 (Offset):** Use `margin-top: -2rem` overlapping, varied image aspect ratios (e.g., 4:3 next to 16:9), left-aligned headers over center-aligned data.
+* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (e.g., `grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`). 
+* **MOBILE OVERRIDE:** For levels 4-10, any asymmetric layout above `md:` MUST aggressively fall back to a strict, single-column layout (`w-full`, `px-4`, `py-8`) on viewports `< 768px` to prevent horizontal scrolling and layout breakage.
+
+### MOTION_INTENSITY (Level 1-10)
+* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only.
+* **4-7 (Fluid CSS):** Use `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. Use `animation-delay` cascades for load-ins. Focus strictly on `transform` and `opacity`. Use `will-change: transform` sparingly.
+* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals or parallax. Use Framer Motion hooks. NEVER use `window.addEventListener('scroll')`.
+
+### VISUAL_DENSITY (Level 1-10)
+* **1-3 (Art Gallery Mode):** Lots of white space. Huge section gaps. Everything feels very expensive and clean.
+* **4-7 (Daily App Mode):** Normal spacing for standard web apps.
+* **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
+
+## 7. AI TELLS (Forbidden Patterns)
+To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
+
+### Visual & CSS
+* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
+* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
+* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
+* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
+* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
+
+### Typography
+* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
+* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
+* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
+
+### Layout & Spacing
+* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
+* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
+
+### Content & Data (The "Jane Doe" Effect)
+* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
+* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
+* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
+* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
+* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
+
+### External Resources & Components
+* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
+* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
+* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
+
+## 8. THE CREATIVE ARSENAL (High-End Inspiration)
+Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
+
+### The Standard Hero Paradigm
+* Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
+
+### Navigation & Menüs
+* **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
+* **Magnetic Button:** Buttons that physically pull toward the cursor.
+* **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
+* **Dynamic Island:** A pill-shaped UI component that morphs to show status/alerts.
+* **Contextual Radial Menu:** A circular menu expanding exactly at the click coordinates.
+* **Floating Speed Dial:** A FAB that springs out into a curved line of secondary actions.
+* **Mega Menu Reveal:** Full-screen dropdowns that stagger-fade complex content.
+
+### Layout & Grids
+* **Bento Grid:** Asymmetric, tile-based grouping (e.g., Apple Control Center).
+* **Masonry Layout:** Staggered grid without fixed row heights (e.g., Pinterest).
+* **Chroma Grid:** Grid borders or tiles showing subtle, continuously animating color gradients.
+* **Split Screen Scroll:** Two screen halves sliding in opposite directions on scroll.
+* **Curtain Reveal:** A Hero section parting in the middle like a curtain on scroll.
+
+### Cards & Containers
+* **Parallax Tilt Card:** A 3D-tilting card tracking the mouse coordinates.
+* **Spotlight Border Card:** Card borders that illuminate dynamically under the cursor.
+* **Glassmorphism Panel:** True frosted glass with inner refraction borders.
+* **Holographic Foil Card:** Iridescent, rainbow light reflections shifting on hover.
+* **Tinder Swipe Stack:** A physical stack of cards the user can swipe away.
+* **Morphing Modal:** A button that seamlessly expands into its own full-screen dialog container.
+
+### Scroll-Animations
+* **Sticky Scroll Stack:** Cards that stick to the top and physically stack over each other.
+* **Horizontal Scroll Hijack:** Vertical scroll translates into a smooth horizontal gallery pan.
+* **Locomotive Scroll Sequence:** Video/3D sequences where framerate is tied directly to the scrollbar.
+* **Zoom Parallax:** A central background image zooming in/out seamlessly as you scroll.
+* **Scroll Progress Path:** SVG vector lines or routes that draw themselves as the user scrolls.
+* **Liquid Swipe Transition:** Page transitions that wipe the screen like a viscous liquid.
+
+### Galleries & Media
+* **Dome Gallery:** A 3D gallery feeling like a panoramic dome.
+* **Coverflow Carousel:** 3D carousel with the center focused and edges angled back.
+* **Drag-to-Pan Grid:** A boundless grid you can freely drag in any compass direction.
+* **Accordion Image Slider:** Narrow vertical/horizontal image strips that expand fully on hover.
+* **Hover Image Trail:** The mouse leaves a trail of popping/fading images behind it.
+* **Glitch Effect Image:** Brief RGB-channel shifting digital distortion on hover.
+
+### Typography & Text
+* **Kinetic Marquee:** Endless text bands that reverse direction or speed up on scroll.
+* **Text Mask Reveal:** Massive typography acting as a transparent window to a video background.
+* **Text Scramble Effect:** Matrix-style character decoding on load or hover.
+* **Circular Text Path:** Text curved along a spinning circular path.
+* **Gradient Stroke Animation:** Outlined text with a gradient continuously running along the stroke.
+* **Kinetic Typography Grid:** A grid of letters dodging or rotating away from the cursor.
+
+### Micro-Interactions & Effects
+* **Particle Explosion Button:** CTAs that shatter into particles upon success.
+* **Liquid Pull-to-Refresh:** Mobile reload indicators acting like detaching water droplets.
+* **Skeleton Shimmer:** Shifting light reflections moving across placeholder boxes.
+* **Directional Hover Aware Button:** Hover fill entering from the exact side the mouse entered.
+* **Ripple Click Effect:** Visual waves rippling precisely from the click coordinates.
+* **Animated SVG Line Drawing:** Vectors that draw their own contours in real-time.
+* **Mesh Gradient Background:** Organic, lava-lamp-like animated color blobs.
+* **Lens Blur Depth:** Dynamic focus blurring background UI layers to highlight a foreground action.
+
+## 9. THE "MOTION-ENGINE" BENTO PARADIGM
+When generating modern SaaS dashboards or feature sections, you MUST utilize the following "Bento 2.0" architecture and motion philosophy. This goes beyond static cards and enforces a "Vercel-core meets Dribbble-clean" aesthetic heavily reliant on perpetual physics.
+
+### A. Core Design Philosophy
+* **Aesthetic:** High-end, minimal, and functional.
+* **Palette:** Background in `#f9fafb`. Cards are pure white (`#ffffff`) with a 1px border of `border-slate-200/50`.
+* **Surfaces:** Use `rounded-[2.5rem]` for all major containers. Apply a "diffusion shadow" (a very light, wide-spreading shadow, e.g., `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`) to create depth without clutter.
+* **Typography:** Strict `Geist`, `Satoshi`, or `Cabinet Grotesk` font stack. Use subtle tracking (`tracking-tight`) for headers.
+* **Labels:** Titles and descriptions must be placed **outside and below** the cards to maintain a clean, gallery-style presentation.
+* **Pixel-Perfection:** Use generous `p-8` or `p-10` padding inside cards.
+
+### B. The Animation Engine Specs (Perpetual Motion)
+All cards must contain **"Perpetual Micro-Interactions."** Use the following Framer Motion principles:
+* **Spring Physics:** No linear easing. Use `type: "spring", stiffness: 100, damping: 20` for a premium, weighty feel.
+* **Layout Transitions:** Heavily utilize the `layout` and `layoutId` props to ensure smooth re-ordering, resizing, and shared element state transitions.
+* **Infinite Loops:** Every card must have an "Active State" that loops infinitely (Pulse, Typewriter, Float, or Carousel) to ensure the dashboard feels "alive".
+* **Performance:** Wrap dynamic lists in `<AnimatePresence>` and optimize for 60fps. **PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (React.memo) and completely isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout.
+
+### C. The 5-Card Archetypes (Micro-Animation Specs)
+Implement these specific micro-animations when constructing Bento grids (e.g., Row 1: 3 cols | Row 2: 2 cols split 70/30):
+1. **The Intelligent List:** A vertical stack of items with an infinite auto-sorting loop. Items swap positions using `layoutId`, simulating an AI prioritizing tasks in real-time.
+2. **The Command Input:** A search/AI bar with a multi-step Typewriter Effect. It cycles through complex prompts, including a blinking cursor and a "processing" state with a shimmering loading gradient.
+3. **The Live Status:** A scheduling interface with "breathing" status indicators. Include a pop-up notification badge that emerges with an "Overshoot" spring effect, stays for 3 seconds, and vanishes.
+4. **The Wide Data Stream:** A horizontal "Infinite Carousel" of data cards or metrics. Ensure the loop is seamless (using `x: ["0%", "-100%"]`) with a speed that feels effortless.
+5. **The Contextual UI (Focus Mode):** A document view that animates a staggered highlight of a text block, followed by a "Float-in" of a floating action toolbar with micro-icons.
+
+## 10. FINAL PRE-FLIGHT CHECK
+Evaluate your code against this matrix before outputting. This is the **last** filter you apply to your logic.
+- [ ] Is global state used appropriately to avoid deep prop-drilling rather than arbitrarily?
+- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed for high-variance designs?
+- [ ] Do full-height sections safely use `min-h-[100dvh]` instead of the bugged `h-screen`?
+- [ ] Do `useEffect` animations contain strict cleanup functions?
+- [ ] Are empty, loading, and error states provided?
+- [ ] Are cards omitted in favor of spacing where possible?
+- [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?

package/packages/shared-skills/skills/frontend/references/design/tesla.md

@@ -0,0 +1,286 @@
+# Design System Inspired by Tesla
+
+## 1. Visual Theme & Atmosphere
+
+Tesla's website is an exercise in radical subtraction — a digital showroom where the product is everything and the interface is almost nothing. The page opens with a full-viewport hero that fills the entire screen with cinematic car photography: three vehicles arranged on polished concrete against a hazy cityscape sky, with a single model name floating above in translucent white type. There are no decorative borders, no gradients, no patterns, no shadows. The UI exists only to provide just enough navigational structure to get out of the way. Every pixel that isn't product imagery is white space, and that restraint is the design system's most powerful statement.
+
+The color philosophy is almost ascetic: a single blue (`#3E6AE1`) for primary calls to action, three shades of dark gray for text hierarchy, and white for everything else. The entire emotional weight is carried by photography — sprawling landscape shots, studio-lit vehicle profiles, and atmospheric environmental compositions that stretch edge-to-edge across each viewport-height section. The UI chrome dissolves into the imagery. The navigation bar floats above the hero with no visible background, border, or shadow — the TESLA wordmark and five navigation labels simply exist in the space, trusting the content beneath them to provide sufficient contrast.
+
+Typography recently transitioned from Gotham to Universal Sans — a custom family split into "Display" for headlines and "Text" for body/UI elements — unifying the website, mobile app, and in-car software into a single typographic voice. The Display variant renders hero titles at 40px weight 500, while the Text variant handles everything from navigation (14px/500) to body copy (14px/400). The font carries a geometric precision with slightly humanist terminals that feels engineered rather than designed — exactly matching Tesla's brand identity of technology that doesn't need to announce itself. There are no text shadows, no text gradients, no decorative type treatments. Every letterform earns its place through clarity alone.
+
+**Key Characteristics:**
+- Full-viewport hero sections (100vh) dominated by cinematic car photography with minimal overlay UI
+- Near-zero UI decoration: no shadows, no gradients, no borders, no patterns anywhere on the page
+- Single accent color — Electric Blue (`#3E6AE1`) — used exclusively for primary CTA buttons
+- Universal Sans font family (Display + Text) unifying web, app, and in-car interfaces
+- Photography-first presentation where product imagery carries all emotional weight
+- Frosted-glass navigation concept with transparent/white nav that floats over hero content
+- 0.33s cubic-bezier transitions as the universal timing for all interactive state changes
+- Carousel-driven hero with dot indicators and edge arrow navigation for multiple vehicle showcases
+- "Ask a Question" persistent chatbot bar anchored to the viewport bottom
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Electric Blue** (`#3E6AE1`): Primary CTA button background — a confident, mid-saturation blue (rgb 62, 106, 225) that stands alone as the only chromatic color in the entire interface. Used exclusively for "Order Now" and other primary action buttons
+- **Pure White** (`#FFFFFF`): Dominant background color for all surfaces, panels, navigation, and secondary button fills — the canvas that lets photography breathe
+
+### Secondary & Accent
+- **Promo Blue** (`#3E6AE1`): Blue also serves for promotional text ("0% APR Available") displayed over hero imagery in the same hue as the CTA — creating a visual link between incentive messaging and action
+- No secondary accent colors exist. Tesla deliberately avoids color variety to maintain extreme visual discipline
+
+### Surface & Background
+- **White Canvas** (`#FFFFFF`): Page background, navigation panel, dropdown menus, and all surface containers
+- **Light Ash** (`#F4F4F4`): Subtle alternate surface for section differentiation — barely perceptible shift from pure white (rgb 244, 244, 244)
+- **Carbon Dark** (`#171A20`): Dark surface color for hero text overlays and potential dark-mode contexts (rgb 23, 26, 32) — a warm near-black with a blue undertone
+- **Frosted Glass** (`rgba(255, 255, 255, 0.75)`): Semi-transparent white for navigation backdrop-filter effects on scroll
+
+### Neutrals & Text
+- **Carbon Dark** (`#171A20`): Primary heading and navigation text — the darkest text value (rgb 23, 26, 32), used for model names, nav labels, and hero titles on light backgrounds
+- **Graphite** (`#393C41`): Body text and secondary content (rgb 57, 60, 65) — the default paragraph color, slightly warmer than pure gray
+- **Pewter** (`#5C5E62`): Tertiary text for sub-links, secondary navigation links like "Learn" and "Order" (rgb 92, 94, 98)
+- **Silver Fog** (`#8E8E8E`): Placeholder text in input fields and disabled states (rgb 142, 142, 142)
+- **Cloud Gray** (`#EEEEEE`): Light borders and divider lines (rgb 238, 238, 238)
+- **Pale Silver** (`#D0D1D2`): Subtle UI borders and delineation (rgb 208, 209, 210)
+
+### Semantic & Accent
+- Tesla's marketing site avoids semantic color coding (no green/red/yellow status indicators). Error, success, and warning states follow standard browser defaults in form contexts
+- The blue CTA (`#3E6AE1`) serves as the sole interactive color signal
+
+### Gradient System
+- No gradients are used anywhere in the interface
+- Depth is achieved entirely through photography, whitespace, and the binary contrast between full-bleed imagery and clean white surfaces
+- The navigation achieves layering through opacity (frosted glass effect) rather than gradient or shadow
+
+## 3. Typography Rules
+
+### Font Family
+- **Display**: `Universal Sans Display`, -apple-system, Arial, sans-serif — used for hero titles and large model names. A geometric sans-serif with precisely engineered proportions, recently replacing Gotham to unify Tesla's digital ecosystem (website, mobile app, vehicle interface)
+- **Text/UI**: `Universal Sans Text`, -apple-system, Arial, sans-serif — used for navigation, body copy, buttons, and all UI text. Optimized for legibility at smaller sizes with slightly wider proportions than the Display variant
+- **No OpenType features** detected — typography is completely unembellished
+- **No italic variants** observed on the marketing site
+
+### Hierarchy
+
+| Role | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|--------|-------------|----------------|-------|
+| Hero Title | 40px (2.50rem) | 500 | 48px (1.20) | normal | Universal Sans Display, white on dark hero imagery |
+| Product Name | 17px (1.06rem) | 500 | 20px (1.18) | normal | Universal Sans Text, model names in nav panel and cards |
+| Nav Item | 14px (0.88rem) | 500 | 16.8px (1.20) | normal | Universal Sans Text, primary navigation labels |
+| Body Text | 14px (0.88rem) | 400 | 20px (1.43) | normal | Universal Sans Text, paragraph and descriptive content |
+| Button Label | 14px (0.88rem) | 500 | 16.8px (1.20) | normal | Universal Sans Text, CTA button text |
+| Sub-link | 14px (0.88rem) | 400 | 20px (1.43) | normal | Tertiary links (Learn, Order, Experience) |
+| Promo Text | 22px (1.38rem) | 400 | 20px (0.91) | normal | White promotional text on hero ("0% APR Available") |
+| Category Label | 16px (est.) | 500 | — | normal | White text labels on category cards ("Sport Sedan") |
+
+### Principles
+- **"Normal" letter-spacing everywhere**: Unlike most modern tech brands that use negative tracking for headlines, Tesla uses default letter-spacing at every level. This reflects a philosophy that the typeface should speak for itself without manipulation
+- **Weight restraint**: Only two weights appear — 500 (medium) for headings/UI and 400 (regular) for body. No bold (700), no light (300). The system avoids typographic drama
+- **Unified font sizing**: Most UI text clusters at 14px with only hero titles (40px) and promo text (22px) breaking away. This extreme uniformity creates a sense of engineered consistency
+- **Display vs Text split**: The two-variant system (Display for hero, Text for UI) creates subtle optical correction without visible stylistic difference — they appear as the same typeface at different sizes
+- **No text transforms**: No uppercase text appears in the main navigation or CTAs — the lowercase approach reinforces Tesla's understated confidence
+
+## 4. Component Stylings
+
+### Buttons
+All buttons use barely-rounded rectangles (4px border-radius) — creating a sharp, technical aesthetic that mirrors the precision of the vehicles.
+
+**Primary CTA** — The main action button:
+- Default: bg `#3E6AE1` (Electric Blue), text `#FFFFFF`, fontSize 14px, fontWeight 500, padding 4px with inner content centering, borderRadius 4px, minHeight 40px, width 200px
+- Border: 3px solid transparent (reserves space for focus/active border animation)
+- Box Shadow: `rgba(0,0,0,0) 0px 0px 0px 2px inset` (invisible at rest, animates to visible on focus)
+- Transition: `border-color 0.33s, background-color 0.33s, color 0.33s, box-shadow 0.25s`
+- Hover: subtle darkening of blue background
+- Used for: "Order Now" calls to action
+
+**Secondary CTA** — The alternative action button:
+- Default: bg `#FFFFFF`, text `#393C41` (Graphite), same dimensions and border pattern as primary
+- Transition: identical timing to primary (0.33s)
+- Used for: "View Inventory" alongside primary CTA
+
+**Nav Button** — Top navigation items:
+- Default: bg transparent, text `#171A20` (Carbon Dark), fontSize 14px, fontWeight 500, borderRadius 4px, padding 4px 16px, minHeight 32px
+- Transition: `color 0.33s, background-color 0.33s`
+- Active/expanded: subtle background highlight
+- Used for: "Vehicles", "Energy", "Charging", "Discover", "Shop"
+
+**Text Link** — In-content actions:
+- Default: text `#5C5E62` (Pewter), fontSize 14px, fontWeight 400, no background, no border
+- Hover: underline decoration with box-shadow transition
+- Transition: `box-shadow 0.33s cubic-bezier(0.5, 0, 0, 0.75), color 0.33s`
+- Used for: "Learn", "Order", "Experience", "New", "Pre-Owned" links in dropdown panel
+
+### Cards & Containers
+
+**Vehicle Card** (Navigation panel):
+- Background: transparent (inherits panel white)
+- Border: none
+- Shadow: none
+- Content: vehicle image (transparent PNG) + model name centered below + two text links
+- Layout: 3-column grid within the dropdown panel
+- No hover animation on the card itself — interaction is via the text links beneath
+
+**Category Card** (Homepage lower section):
+- Background: full-bleed landscape photography
+- Border radius: approximately 12px (subtly rounded)
+- Overflow: hidden (clips image to rounded corners)
+- Text: white label in top-left corner ("Sport Sedan", "Midsize SUV")
+- Size: large format, approximately 2:1 aspect ratio
+- No shadow, no border, no overlay gradient — text relies on image darkness for contrast
+
+### Inputs & Forms
+- Background: transparent
+- Text color: `#171A20` (Carbon Dark)
+- Placeholder color: `#8E8E8E` (Silver Fog)
+- Border: minimal, inherits from browser defaults
+- Font: Universal Sans Text, 14px
+- The "Ask a Question" chatbot input bar sits at the viewport bottom with a clean white background and subtle border
+
+### Navigation
+- **Desktop**: Centered horizontal nav with TESLA wordmark (spaced uppercase letters) on the left, five category buttons center-aligned, and three icon buttons (help, globe/language, account) on the right
+- **Background**: White (transitions from transparent over dark hero to opaque white on scroll via class toggle `tds-site-header--white-background`)
+- **Dropdown panel**: Full-width white panel with 3-column vehicle grid + right sidebar text links, no shadow, no border — appears seamlessly below the nav
+- **Sticky behavior**: `sticky-without-slide` class — stays at top without slide-in animation
+- **Mobile**: Hamburger collapse pattern
+- **No visible separator** between nav and content — the nav blends with the hero
+
+### Image Treatment
+- **Hero**: Full-viewport (100vh) sections with cinematic photography — edge-to-edge, no padding, no margin
+- **Vehicle images**: Transparent PNG renders on white background in dropdown panel, studio-quality 3/4 angle shots
+- **Category cards**: Landscape photography with approximately 2:1 ratio, rounded corners (12px)
+- **Carousel**: Auto-advancing with dot indicators (3 dots) and left/right arrow navigation on edges
+- **Lazy loading**: Below-fold sections use lazy loading, rendering as blank white until scrolled into view
+
+### Persistent Chat Bar
+- Anchored to viewport bottom, visible across all sections
+- White background with subtle border
+- Contains: chat icon + "Ask a Question" label + placeholder text ("What's Dog Mode?") + send icon + "Schedule a Drive Today" secondary CTA
+- Schedule CTA has a teal/blue icon accent
+
+## 5. Layout Principles
+
+### Spacing System
+- **Base unit**: 8px
+- **Common values**: 8px (0.5rem), 16px (1rem), 21.44px (1.34rem)
+- **Button padding**: 4px (minimal outer) with content centering via flexbox, 4px 16px for nav items
+- **Section padding**: Full-viewport sections with content centered vertically
+- **Card gap**: approximately 16px between category cards
+
+### Grid & Container
+- **Max width**: approximately 1383px (full viewport width used for most content)
+- **Hero**: Full-bleed, edge-to-edge, 100vh sections
+- **Navigation panel**: 3-column grid for vehicle cards with right-aligned text sidebar (~70/30 split)
+- **Category cards**: 2-up horizontal layout (large left card + smaller right card)
+
+### Whitespace Philosophy
+Tesla uses whitespace as a luxury signal. The generous vertical spacing between sections (each section is a full viewport height) means you can only see one "message" at a time — one car, one model name, one CTA pair. This creates a gallery-like browsing experience where each scroll is a deliberate transition, not a continuous feed. White space is not empty — it's the frame that elevates each vehicle to the status of art piece.
+
+### Border Radius Scale
+| Value | Context |
+|-------|---------|
+| 0px | Most elements — sharp edges are the default |
+| 4px | Buttons (primary, secondary, nav items) — barely perceptible rounding |
+| ~12px | Category cards — noticeable but restrained rounding on larger surfaces |
+| 50% | Carousel dot indicators — perfect circles |
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Level 0 (Flat) | No shadow, no border | Default state for all elements — cards, panels, buttons at rest |
+| Level 1 (Frost) | `rgba(255,255,255,0.75)` backdrop | Navigation bar on scroll — frosted glass transparency |
+| Level 2 (Overlay) | `rgba(128,128,128,0.65)` | Modal overlays and region/cookie popups |
+| Level 3 (Subtle) | `rgba(0,0,0,0.05)` | Minimal shadow hints on rare hover states |
+
+### Shadow Philosophy
+Tesla's approach to elevation is essentially "none." The site avoids box-shadows entirely in its primary interface. Depth is communicated through three alternative strategies:
+1. **Z-index layering**: The sticky navigation sits above hero content through positioning, not shadow
+2. **Opacity-based transparency**: The frosted glass nav and overlay modals use background-color opacity rather than shadow to indicate layering
+3. **Photography-as-depth**: The full-bleed images create their own visual depth through perspective, lighting, and composition — making UI shadows redundant
+
+### Decorative Depth
+- No gradients, glows, or atmospheric effects on UI elements
+- The hero imagery itself provides all visual richness — sunset skies, reflected light on car surfaces, ground shadows from studio lighting
+- The carousel arrow buttons use a semi-transparent white background to float above the hero imagery without disrupting it
+
+## 7. Do's and Don'ts
+
+### Do
+- Let photography dominate every screen — the product IS the design
+- Use Electric Blue (`#3E6AE1`) exclusively for primary CTAs — never for decorative purposes
+- Maintain viewport-height sections for major content blocks — one message per screen
+- Keep typography at weight 400-500 only — no bold, no light, no extremes
+- Use 4px border-radius for all interactive elements — precision over playfulness
+- Trust whitespace as a luxury signal — never fill available space just because it's empty
+- Keep all transitions at 0.33s — consistency in motion is as important as consistency in color
+- Use transparent PNG vehicle imagery on white backgrounds for product showcases
+- Center CTAs horizontally below model names — the vertical rhythm is model → subtitle → buttons
+- Maintain the Display/Text font split — Display for hero-scale text only, Text for everything else
+
+### Don't
+- Add shadows to any element — elevation through shadow contradicts the flat, gallery aesthetic
+- Use more than one chromatic color besides the blue CTA — the palette is intentionally monochrome-plus-one
+- Apply gradients, patterns, or decorative backgrounds to surfaces — white and photography are the only backgrounds
+- Use text larger than 40px on the web — the typography is deliberately restrained even at hero scale
+- Add borders to cards or containers — separation is achieved through spacing, not lines
+- Use uppercase text transforms — Tesla's confidence is expressed through lowercase calm
+- Introduce rounded-pill buttons or large border-radii — the 4px radius is deliberate and precise
+- Override the Universal Sans family with other typefaces — cross-platform consistency is a core brand value
+- Add hover animations with scale/translate transforms — Tesla's interactions are color-only (background and border transitions)
+- Clutter the viewport with multiple CTAs — every screen should have at most two action buttons
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile | <768px | Single-column layout, hamburger nav replaces horizontal labels, hero text scales to ~28px, CTA buttons stack vertically, category cards become full-width |
+| Tablet | 768-1024px | 2-column nav panel, hero maintains full-viewport height, CTAs remain side-by-side, reduced horizontal padding |
+| Desktop | 1024-1440px | Full horizontal nav, 3-column vehicle grid in dropdown, hero at 40px, side-by-side CTAs at 200px/160px width |
+| Large Desktop | >1440px | Content remains centered, hero photography scales to fill wider viewports, max-width container for nav panel content |
+
+### Touch Targets
+- Primary CTA buttons: 200px × 40px minimum (well above 44×44px WCAG requirement)
+- Nav buttons: minimum 32px height with 4px 16px padding — adequate touch targets
+- Carousel arrows: ~44px square white semi-transparent buttons at viewport edges
+- Text links ("Learn", "Order"): 14px text with adequate line-height spacing for touch
+
+### Collapsing Strategy
+- **Navigation**: Horizontal category buttons (Vehicles, Energy, Charging, Discover, Shop) collapse to a hamburger/drawer menu on mobile
+- **Hero CTA pair**: Side-by-side buttons on desktop stack vertically on mobile
+- **Category cards**: 2-up horizontal layout collapses to single-column full-width on mobile
+- **Vehicle grid**: 3-column grid in desktop nav panel becomes 2-column on tablet, single-column on mobile
+- **Spacing**: Section vertical padding remains generous (viewport-height sections) but horizontal padding reduces
+
+### Image Behavior
+- Hero images are fully responsive and fill the entire viewport at every breakpoint
+- Vehicle carousel images use `object-fit: cover` to maintain cinematic composition across widths
+- Transparent PNG vehicle images in the nav panel scale proportionally within their grid cells
+- Category card images maintain their landscape ratio and clip via `overflow: hidden` with border-radius
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Primary CTA: "Electric Blue (#3E6AE1)"
+- Background: "Pure White (#FFFFFF)"
+- Heading text: "Carbon Dark (#171A20)"
+- Body text: "Graphite (#393C41)"
+- Tertiary text: "Pewter (#5C5E62)"
+- Placeholder: "Silver Fog (#8E8E8E)"
+- Alternate surface: "Light Ash (#F4F4F4)"
+- Dark surface: "Carbon Dark (#171A20)"
+
+### Example Component Prompts
+- "Create a hero section with a full-viewport background image, centered 'Model Y' title in Universal Sans Display at 40px weight 500 in white, a subtitle line below, and two buttons side by side: a primary Electric Blue (#3E6AE1) 'Order Now' button and a secondary white 'View Inventory' button, both with 4px border-radius and 40px height"
+- "Design a navigation bar with a spaced-letter wordmark on the left, five text buttons (14px, weight 500, Carbon Dark #171A20) centered, and three icon buttons on the right, all on a white background with no shadow or border"
+- "Build a vehicle card grid with 3 columns, each card showing a transparent-background car image above a model name (17px, weight 500, Carbon Dark) and two text links (14px, weight 400, Pewter #5C5E62) labeled 'Learn' and 'Order', on a pure white surface with no borders or shadows"
+- "Create a category card with full-bleed landscape photography, 12px border-radius, overflow hidden, and a white text label ('Sport Sedan') positioned in the top-left corner with no overlay gradient"
+- "Design a persistent bottom bar with a chat input ('Ask a Question' placeholder), a send icon, and a secondary CTA ('Schedule a Drive Today') with a teal icon, anchored to the viewport bottom on a white background"
+
+### Iteration Guide
+When refining existing screens generated with this design system:
+1. Focus on ONE component at a time — Tesla's system is so minimal that each element must be pixel-perfect
+2. Reference specific color names and hex codes from this document — there are only 6-7 colors in the entire system
+3. Use natural language descriptions, not CSS values — "barely rounded corners" not "border-radius: 4px"
+4. Describe the desired "feel" alongside specific measurements — "gallery-like silence between sections" communicates the whitespace philosophy better than "margin-bottom: 100vh"
+5. Always verify that photography is doing the emotional heavy-lifting — if the UI itself feels "designed," it's too much