diff --git a/SKILL.md b/SKILL.md index 0cecccb..ac521fc 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,226 +1,66 @@ --- 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. +description: Enforces high-end frontend design patterns, anti-AI-slop rules, and motion specifications for React/Next.js. Use when building or reviewing UI components, dashboards, or landing pages. --- -# 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. THE 100 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 `` 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? +# Design Taste Frontend + +Senior UI/UX Engineer skill that overrides default LLM biases toward generic AI designs. + +## Active Baseline + +``` +DESIGN_VARIANCE: 8 | MOTION_INTENSITY: 6 | VISUAL_DENSITY: 4 +``` + +Adapt these dynamically based on user requests. See `references/dials.md` for definitions. + +## Quick Reference + +| Topic | File | Search | +|-------|------|--------| +| Architecture | `references/architecture.md` | `grep "CRITICAL" references/architecture.md` | +| Design Rules | `references/design-rules.md` | `grep "NO " references/design-rules.md` | +| Motion/Animation | `references/motion.md` | `grep "spring" references/motion.md` | +| Performance | `references/performance.md` | `grep "NEVER" references/performance.md` | +| Creative Arsenal | `references/creative-arsenal.md` | `grep "Grid\|Menu\|Card" references/creative-arsenal.md` | +| Dial Definitions | `references/dials.md` | — | + +## Critical Rules (Always Apply) + +### Banned Defaults +- **NO Inter font** → Use Geist, Outfit, Cabinet Grotesk, Satoshi +- **NO AI Purple/Blue** → Use Zinc/Slate with singular accent (Emerald, Electric Blue, Deep Rose) +- **NO `h-screen`** → Use `min-h-[100dvh]` for mobile safety +- **NO Emojis** → Use Phosphor/Radix icons or SVG primitives +- **NO 3-Column Card Layouts** → Use asymmetric grids or zig-zag + +### Typography Defaults +```css +/* Headlines */ +text-4xl md:text-6xl tracking-tighter leading-none + +/* Body */ +text-base text-gray-600 leading-relaxed max-w-[65ch] +``` + +### Motion (When MOTION_INTENSITY > 5) +```javascript +// Always use spring physics, never linear +type: "spring", stiffness: 100, damping: 20 + +// For magnetic/continuous animations: useMotionValue, NOT useState +``` + +### Performance +- Animate only `transform` and `opacity` +- Isolate perpetual animations in their own Client Component with `React.memo` +- Use CSS Grid over flex-math: `grid grid-cols-1 md:grid-cols-3 gap-6` + +## Pre-Flight Checklist + +- [ ] Mobile collapse guaranteed (`w-full`, `px-4`, `max-w-7xl mx-auto`)? +- [ ] Full-height uses `min-h-[100dvh]` not `h-screen`? +- [ ] `useEffect` animations have cleanup functions? +- [ ] Empty, loading, and error states provided? +- [ ] CPU-heavy animations isolated in Client Components? diff --git a/references/architecture.md b/references/architecture.md new file mode 100644 index 0000000..0275ca2 --- /dev/null +++ b/references/architecture.md @@ -0,0 +1,36 @@ +# Architecture & Conventions + +## Dependency Verification [MANDATORY] +Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), check `package.json`. If missing, output the installation command before providing 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. Wrap providers in `"use client"`. +- **INTERACTIVITY ISOLATION:** If motion/glass effects are active, extract interactive UI as isolated leaf component with `'use client'`. Server Components render static layouts only. + +## State Management +- Use local `useState`/`useReducer` for isolated UI. +- Use global state strictly for deep prop-drilling avoidance. + +## Styling Policy +- 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 Vite plugin. + +## Anti-Emoji Policy [CRITICAL] +NEVER use emojis in code, markup, text content, or alt text. Replace with high-quality icons (Radix, Phosphor) or clean SVG primitives. + +## Responsiveness & Spacing +- Standardize breakpoints: `sm`, `md`, `lg`, `xl`. +- Contain layouts: `max-w-[1400px] mx-auto` or `max-w-7xl`. +- **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Heroes. ALWAYS use `min-h-[100dvh]` to prevent layout jumping on mobile (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`). + +## Icons +Use exactly `@phosphor-icons/react` or `@radix-ui/react-icons`. Standardize `strokeWidth` globally (e.g., `1.5` or `2.0`). + +## Forms +- Label MUST sit above input. +- Helper text optional but should exist in markup. +- Error text below input. +- Use standard `gap-2` for input blocks. diff --git a/references/creative-arsenal.md b/references/creative-arsenal.md new file mode 100644 index 0000000..53a09bc --- /dev/null +++ b/references/creative-arsenal.md @@ -0,0 +1,87 @@ +# The Creative Arsenal + +Pull from this library of advanced concepts to ensure output is visually striking and memorable. + +## The Standard Hero Paradigm +Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. Background should feature a high-quality, relevant image with subtle stylistic fade. + +--- + +## Navigation & Menus + +| Pattern | Description | +|---------|-------------| +| **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 main button like viscous liquid | +| **Dynamic Island** | Pill-shaped UI component that morphs to show status/alerts | +| **Contextual Radial Menu** | Circular menu expanding at click coordinates | +| **Floating Speed Dial** | FAB that springs out into curved line of secondary actions | +| **Mega Menu Reveal** | Full-screen dropdowns with stagger-fade content | + +## Layout & Grids + +| Pattern | Description | +|---------|-------------| +| **Bento Grid** | Asymmetric, tile-based grouping (Apple Control Center) | +| **Masonry Layout** | Staggered grid without fixed row heights (Pinterest) | +| **Chroma Grid** | Grid borders/tiles with subtle animating color gradients | +| **Split Screen Scroll** | Two screen halves sliding in opposite directions on scroll | +| **Curtain Reveal** | Hero section parting in the middle like a curtain on scroll | + +## Cards & Containers + +| Pattern | Description | +|---------|-------------| +| **Parallax Tilt Card** | 3D-tilting card tracking mouse coordinates | +| **Spotlight Border Card** | Card borders that illuminate dynamically under cursor | +| **Glassmorphism Panel** | True frosted glass with inner refraction borders | +| **Holographic Foil Card** | Iridescent, rainbow light reflections shifting on hover | +| **Tinder Swipe Stack** | Physical stack of cards user can swipe away | +| **Morphing Modal** | Button that seamlessly expands into full-screen dialog | + +## Scroll-Animations + +| Pattern | Description | +|---------|-------------| +| **Sticky Scroll Stack** | Cards that stick to top and physically stack over each other | +| **Horizontal Scroll Hijack** | Vertical scroll translates into smooth horizontal gallery pan | +| **Locomotive Scroll Sequence** | Video/3D sequences where framerate is tied to scrollbar | +| **Zoom Parallax** | Central background image zooming in/out as you scroll | +| **Scroll Progress Path** | SVG vector lines that draw themselves as you scroll | +| **Liquid Swipe Transition** | Page transitions that wipe screen like viscous liquid | + +## Galleries & Media + +| Pattern | Description | +|---------|-------------| +| **Dome Gallery** | 3D gallery feeling like a panoramic dome | +| **Coverflow Carousel** | 3D carousel with center focused and edges angled back | +| **Drag-to-Pan Grid** | Boundless grid you can freely drag in any direction | +| **Accordion Image Slider** | Narrow vertical/horizontal image strips that expand on hover | +| **Hover Image Trail** | Mouse leaves a trail of popping/fading images | +| **Glitch Effect Image** | Brief RGB-channel shifting digital distortion on hover | + +## Typography & Text + +| Pattern | Description | +|---------|-------------| +| **Kinetic Marquee** | Endless text bands that reverse direction or speed up on scroll | +| **Text Mask Reveal** | Massive typography acting as transparent window to 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 gradient continuously running along stroke | +| **Kinetic Typography Grid** | Grid of letters dodging or rotating away from cursor | + +## Micro-Interactions & Effects + +| Pattern | Description | +|---------|-------------| +| **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 exact side mouse entered | +| **Ripple Click Effect** | Visual waves rippling precisely from 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 foreground | diff --git a/references/design-rules.md b/references/design-rules.md new file mode 100644 index 0000000..6198ec0 --- /dev/null +++ b/references/design-rules.md @@ -0,0 +1,96 @@ +# Design Engineering Rules + +LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules. + +## Rule 1: Deterministic Typography + +### Display/Headlines +```css +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. Use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`). + +### Body/Paragraphs +```css +text-base text-gray-600 leading-relaxed max-w-[65ch] +``` + +## Rule 2: Color Calibration + +- Max 1 Accent Color. Saturation < 80%. +- **THE LILA BAN:** "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. + +## 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 +- 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. + +Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue. + +## Rule 5: Interactive UI States + +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 physical push. + +--- + +# The 100 AI Tells (Forbidden Patterns) + +To guarantee a premium, non-generic output, 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. +NO Serif on Dashboards: Use Serif fonts ONLY for creative/editorial designs. +``` + +## Layout & Spacing + +``` +NO Misaligned Elements: Ensure padding and margins are mathematically perfect. +NO Floating Elements: Avoid awkward gaps. +NO 3-Column Card Layouts: The generic "3 equal cards horizontally" feature row is BANNED. Use 2-column Zig-Zag, asymmetric grid, or horizontal scrolling. +``` + +## Content & Data (The "Jane Doe" Effect) + +``` +NO Generic Names: "John Doe", "Sarah Chan", "Jack Su" are banned. Use creative, realistic-sounding names. +NO Generic Avatars: DO NOT use standard SVG "egg" or Lucide user icons. Use creative, believable photo placeholders. +NO Fake Numbers: Avoid 99.99%, 50%, or 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 "Elevate", "Seamless", "Unleash", "Next-Gen". Use concrete verbs. +``` + +## External Resources & Components + +``` +NO Broken Unsplash Links: Do not use Unsplash. Use https://picsum.photos/seed/{random_string}/800/600 or SVG UI Avatars. +NO Default shadcn/ui: You may use shadcn/ui, but NEVER in generic default state. Customize radii, colors, shadows. +``` diff --git a/references/dials.md b/references/dials.md new file mode 100644 index 0000000..70dc756 --- /dev/null +++ b/references/dials.md @@ -0,0 +1,73 @@ +# Design Dials + +## Active Baseline + +``` +DESIGN_VARIANCE: 8 +MOTION_INTENSITY: 6 +VISUAL_DENSITY: 4 +``` + +The standard baseline for all generations is strictly set to these values. Do not ask the user to edit this file. + +**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 global variables to drive specific logic. + +--- + +## DESIGN_VARIANCE (Level 1-10) + +### 1-3 (Predictable) +- Flexbox `justify-center` +- Strict 12-column symmetrical grids +- Equal paddings + +### 4-7 (Offset) +- `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 (`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 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) +```css +transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1); +``` +- `animation-delay` cascades for load-ins +- Focus on `transform` and `opacity` +- `will-change: transform` sparingly + +### 8-10 (Advanced Choreography) +- Complex scroll-triggered reveals or parallax +- 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 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 diff --git a/references/motion.md b/references/motion.md new file mode 100644 index 0000000..83b351f --- /dev/null +++ b/references/motion.md @@ -0,0 +1,103 @@ +# Motion & Animation + +## Creative Proactivity (Anti-Slop Implementation) + +### Liquid Glass Refraction +When glassmorphism is needed, go beyond `backdrop-blur`: +```css +border-white/10 +shadow-[inset_0_1px_0_rgba(255,255,255,0.1)] +``` + +### Magnetic Micro-physics (If MOTION_INTENSITY > 5) +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. + +Apply premium Spring Physics: +```javascript +type: "spring", stiffness: 100, damping: 20 +``` + +No linear easing. + +### Layout Transitions +Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions. + +### Staggered Orchestration +Do not mount lists or grids instantly. Use: +- `staggerChildren` (Framer Motion) +- CSS cascade: `animation-delay: calc(var(--index) * 100ms)` + +**CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass data as props into a centralized Parent Motion wrapper. + +--- + +## Motion Intensity Levels (1-10) + +### 1-3 (Static) +- No automatic animations. +- CSS `:hover` and `:active` states only. + +### 4-7 (Fluid CSS) +```css +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')`. + +--- + +## The Motion-Engine Bento Paradigm + +For modern SaaS dashboards, enforce "Vercel-core meets Dribbble-clean" aesthetic. + +### Core Philosophy +- **Aesthetic:** High-end, minimal, functional. +- **Palette:** Background `#f9fafb`. Cards `#ffffff` with `border-slate-200/50`. +- **Surfaces:** `rounded-[2.5rem]`. Diffusion shadow: `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`. +- **Typography:** Geist, Satoshi, or Cabinet Grotesk. `tracking-tight` for headers. +- **Labels:** Place titles/descriptions **outside and below** cards. +- **Padding:** `p-8` or `p-10` inside cards. + +### Animation Engine Specs +All cards must contain **Perpetual Micro-Interactions:** +- **Spring Physics:** `type: "spring", stiffness: 100, damping: 20` +- **Layout Transitions:** Heavy use of `layout` and `layoutId` props +- **Infinite Loops:** Every card has an "Active State" that loops infinitely +- **Performance:** Wrap dynamic lists in `` + +**PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (`React.memo`) and isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout. + +### The 5-Card Archetypes + +1. **The Intelligent List:** Vertical stack with infinite auto-sorting loop. Items swap positions using `layoutId`. + +2. **The Command Input:** Search/AI bar with multi-step Typewriter Effect. Cycles through prompts with blinking cursor and "processing" shimmer gradient. + +3. **The Live Status:** Scheduling interface with "breathing" status indicators. Pop-up notification badge emerges with "Overshoot" spring, stays 3 seconds, vanishes. + +4. **The Wide Data Stream:** Horizontal "Infinite Carousel" of data cards. Seamless loop using `x: ["0%", "-100%"]`. + +5. **The Contextual UI (Focus Mode):** Document view with staggered text highlight, followed by "Float-in" of floating action toolbar. + +--- + +## GSAP / ThreeJS Usage + +Default to Framer Motion for UI/Bento interactions. + +Use GSAP (ScrollTrigger/Parallax) or ThreeJS/WebGL EXCLUSIVELY for: +- Isolated full-page scrolltelling +- Canvas backgrounds + +**CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Wrap in strict `useEffect` cleanup blocks. diff --git a/references/performance.md b/references/performance.md new file mode 100644 index 0000000..5451d40 --- /dev/null +++ b/references/performance.md @@ -0,0 +1,37 @@ +# Performance Guardrails + +## DOM Cost +Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements: +```css +fixed inset-0 z-50 pointer-events-none +``` +NEVER apply 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` +- `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 + +--- + +## Pre-Flight Checklist + +Before outputting code, evaluate against this matrix: + +- [ ] 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?