codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/frontend-slides/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: frontend-slides
+description: Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files.
+risk: safe
+source: https://github.com/zarazhangrui/frontend-slides
+date_added: "2026-03-07"
+---
+
+# Frontend Slides
+
+Create zero-dependency, animation-rich HTML presentations that run entirely in the browser.
+
+## When to Use This Skill
+
+- Use when the user asks to create a presentation, slide deck, or pitch from scratch.
+- Use when the user wants to convert an existing PPT or PPTX file into a web-based presentation.
+- Use when designing visually rich, animated HTML content that needs to fit exactly within the viewport.
+
+## Core Principles
+
+1. **Zero Dependencies** — Single HTML files with inline CSS/JS. No npm, no build tools.
+2. **Show, Don't Tell** — Generate visual previews, not abstract choices. People discover what they want by seeing it.
+3. **Distinctive Design** — No generic "AI slop." Every presentation must feel custom-crafted.
+4. **Viewport Fitting (NON-NEGOTIABLE)** — Every slide MUST fit exactly within 100vh. No scrolling within slides, ever. Content overflows? Split into multiple slides.
+
+## Design Aesthetics
+
+You tend to converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.
+
+Focus on:
+
+- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.
+- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.
+- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.
+- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.
+
+Avoid generic AI-generated aesthetics:
+
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Cliched color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!
+
+## Viewport Fitting Rules
+
+These invariants apply to EVERY slide in EVERY presentation:
+
+- Every `.slide` must have `height: 100vh; height: 100dvh; overflow: hidden;`
+- ALL font sizes and spacing must use `clamp(min, preferred, max)` — never fixed px/rem
+- Content containers need `max-height` constraints
+- Images: `max-height: min(50vh, 400px)`
+- Breakpoints required for heights: 700px, 600px, 500px
+- Include `prefers-reduced-motion` support
+- Never negate CSS functions directly (`-clamp()`, `-min()`, `-max()` are silently ignored) — use `calc(-1 * clamp(...))` instead
+
+**When generating, read `viewport-base.css` and include its full contents in every presentation.**
+
+### Content Density Limits Per Slide
+
+| Slide Type    | Maximum Content                                           |
+| ------------- | --------------------------------------------------------- |
+| Title slide   | 1 heading + 1 subtitle + optional tagline                 |
+| Content slide | 1 heading + 4-6 bullet points OR 1 heading + 2 paragraphs |
+| Feature grid  | 1 heading + 6 cards maximum (2x3 or 3x2)                  |
+| Code slide    | 1 heading + 8-10 lines of code                            |
+| Quote slide   | 1 quote (max 3 lines) + attribution                       |
+| Image slide   | 1 heading + 1 image (max 60vh height)                     |
+
+**Content exceeds limits? Split into multiple slides. Never cram, never scroll.**
+
+---
+
+## Phase 0: Detect Mode
+
+Determine what the user wants:
+
+- **Mode A: New Presentation** — Create from scratch. Go to Phase 1.
+- **Mode B: PPT Conversion** — Convert a .pptx file. Go to Phase 4.
+- **Mode C: Enhancement** — Improve an existing HTML presentation. Read it, understand it, enhance. **Follow Mode C modification rules below.**
+
+### Mode C: Modification Rules
+
+When enhancing existing presentations, viewport fitting is the biggest risk:
+
+1. **Before adding content:** Count existing elements, check against density limits
+2. **Adding images:** Must have `max-height: min(50vh, 400px)`. If slide already has max content, split into two slides
+3. **Adding text:** Max 4-6 bullets per slide. Exceeds limits? Split into continuation slides
+4. **After ANY modification, verify:** `.slide` has `overflow: hidden`, new elements use `clamp()`, images have viewport-relative max-height, content fits at 1280x720
+5. **Proactively reorganize:** If modifications will cause overflow, automatically split content and inform the user. Don't wait to be asked
+
+**When adding images to existing slides:** Move image to new slide or reduce other content first. Never add images without checking if existing content already fills the viewport.
+
+---
+
+## Phase 1: Content Discovery (New Presentations)
+
+**Ask ALL questions in a single AskUserQuestion call** so the user fills everything out at once:
+
+**Question 1 — Purpose** (header: "Purpose"):
+What is this presentation for? Options: Pitch deck / Teaching-Tutorial / Conference talk / Internal presentation
+
+**Question 2 — Length** (header: "Length"):
+Approximately how many slides? Options: Short 5-10 / Medium 10-20 / Long 20+
+
+**Question 3 — Content** (header: "Content"):
+Do you have content ready? Options: All content ready / Rough notes / Topic only
+
+**Question 4 — Inline Editing** (header: "Editing"):
+Do you need to edit text directly in the browser after generation? Options:
+
+- "Yes (Recommended)" — Can edit text in-browser, auto-save to localStorage, export file
+- "No" — Presentation only, keeps file smaller
+
+**Remember the user's editing choice — it determines whether edit-related code is included in Phase 3.**
+
+If user has content, ask them to share it.
+
+### Step 1.2: Image Evaluation (if images provided)
+
+If user selected "No images" → skip to Phase 2.
+
+If user provides an image folder:
+
+1. **Scan** — List all image files (.png, .jpg, .svg, .webp, etc.)
+2. **View each image** — Use the Read tool (Claude is multimodal)
+3. **Evaluate** — For each: what it shows, USABLE or NOT USABLE (with reason), what concept it represents, dominant colors
+4. **Co-design the outline** — Curated images inform slide structure alongside text. This is NOT "plan slides then add images" — design around both from the start (e.g., 3 screenshots → 3 feature slides, 1 logo → title/closing slide)
+5. **Confirm via AskUserQuestion** (header: "Outline"): "Does this slide outline and image selection look right?" Options: Looks good / Adjust images / Adjust outline
+
+**Logo in previews:** If a usable logo was identified, embed it (base64) into each style preview in Phase 2 — the user sees their brand styled three different ways.
+
+---
+
+## Phase 2: Style Discovery
+
+**This is the "show, don't tell" phase.** Most people can't articulate design preferences in words.
+
+### Step 2.0: Style Path
+
+Ask how they want to choose (header: "Style"):
+
+- "Show me options" (recommended) — Generate 3 previews based on mood
+- "I know what I want" — Pick from preset list directly
+
+**If direct selection:** Show preset picker and skip to Phase 3. Available presets are defined in [STYLE_PRESETS.md](STYLE_PRESETS.md).
+
+### Step 2.1: Mood Selection (Guided Discovery)
+
+Ask (header: "Vibe", multiSelect: true, max 2):
+What feeling should the audience have? Options:
+
+- Impressed/Confident — Professional, trustworthy
+- Excited/Energized — Innovative, bold
+- Calm/Focused — Clear, thoughtful
+- Inspired/Moved — Emotional, memorable
+
+### Step 2.2: Generate 3 Style Previews
+
+Based on mood, generate 3 distinct single-slide HTML previews showing typography, colors, animation, and overall aesthetic. Read [STYLE_PRESETS.md](STYLE_PRESETS.md) for available presets and their specifications.
+
+| Mood                | Suggested Presets                                  |
+| ------------------- | -------------------------------------------------- |
+| Impressed/Confident | Bold Signal, Electric Studio, Dark Botanical       |
+| Excited/Energized   | Creative Voltage, Neon Cyber, Split Pastel         |
+| Calm/Focused        | Notebook Tabs, Paper & Ink, Swiss Modern           |
+| Inspired/Moved      | Dark Botanical, Vintage Editorial, Pastel Geometry |
+
+Save previews to `.claude-design/slide-previews/` (style-a.html, style-b.html, style-c.html). Each should be self-contained, ~50-100 lines, showing one animated title slide.
+
+Open each preview automatically for the user.
+
+### Step 2.3: User Picks
+
+Ask (header: "Style"):
+Which style preview do you prefer? Options: Style A: [Name] / Style B: [Name] / Style C: [Name] / Mix elements
+
+If "Mix elements", ask for specifics.
+
+---
+
+## Phase 3: Generate Presentation
+
+Generate the full presentation using content from Phase 1 (text, or text + curated images) and style from Phase 2.
+
+If images were provided, the slide outline already incorporates them from Step 1.2. If not, CSS-generated visuals (gradients, shapes, patterns) provide visual interest — this is a fully supported first-class path.
+
+**Before generating, read these supporting files:**
+
+- [html-template.md](html-template.md) — HTML architecture and JS features
+- [viewport-base.css](viewport-base.css) — Mandatory CSS (include in full)
+- [animation-patterns.md](animation-patterns.md) — Animation reference for the chosen feeling
+
+**Key requirements:**
+
+- Single self-contained HTML file, all CSS/JS inline
+- Include the FULL contents of viewport-base.css in the `<style>` block
+- Use fonts from Fontshare or Google Fonts — never system fonts
+- Add detailed comments explaining each section
+- Every section needs a clear `/* === SECTION NAME === */` comment block
+
+---
+
+## Phase 4: PPT Conversion
+
+When converting PowerPoint files:
+
+1. **Extract content** — Run `python scripts/extract-pptx.py <input.pptx> <output_dir>` (install python-pptx if needed: `pip install python-pptx`)
+2. **Confirm with user** — Present extracted slide titles, content summaries, and image counts
+3. **Style selection** — Proceed to Phase 2 for style discovery
+4. **Generate HTML** — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments)
+
+---
+
+## Phase 5: Delivery
+
+1. **Clean up** — Delete `.claude-design/slide-previews/` if it exists
+2. **Open** — Use `open [filename].html` to launch in browser
+3. **Summarize** — Tell the user:
+   - File location, style name, slide count
+   - Navigation: Arrow keys, Space, scroll/swipe, click nav dots
+   - How to customize: `:root` CSS variables for colors, font link for typography, `.reveal` class for animations
+   - If inline editing was enabled: Hover top-left corner or press E to enter edit mode, click any text to edit, Ctrl+S to save
+
+---
+
+## Supporting Files
+
+| File                                               | Purpose                                                              | When to Read              |
+| -------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
+| [STYLE_PRESETS.md](STYLE_PRESETS.md)               | 12 curated visual presets with colors, fonts, and signature elements | Phase 2 (style selection) |
+| [viewport-base.css](viewport-base.css)             | Mandatory responsive CSS — copy into every presentation              | Phase 3 (generation)      |
+| [html-template.md](html-template.md)               | HTML structure, JS features, code quality standards                  | Phase 3 (generation)      |
+| [animation-patterns.md](animation-patterns.md)     | CSS/JS animation snippets and effect-to-feeling guide                | Phase 3 (generation)      |
+| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content extraction                             | Phase 4 (conversion)      |

package/templates/.agent/skills/frontend-slides/STYLE_PRESETS.md

@@ -0,0 +1,347 @@
+# Style Presets Reference
+
+Curated visual styles for Frontend Slides. Each preset is inspired by real design references — no generic "AI slop" aesthetics. **Abstract shapes only — no illustrations.**
+
+**Viewport CSS:** For mandatory base styles, see [viewport-base.css](viewport-base.css). Include in every presentation.
+
+---
+
+## Dark Themes
+
+### 1. Bold Signal
+
+**Vibe:** Confident, bold, modern, high-impact
+
+**Layout:** Colored card on dark gradient. Number top-left, navigation top-right, title bottom-left.
+
+**Typography:**
+- Display: `Archivo Black` (900)
+- Body: `Space Grotesk` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-primary: #1a1a1a;
+    --bg-gradient: linear-gradient(135deg, #1a1a1a 0%, #2d2d2d 50%, #1a1a1a 100%);
+    --card-bg: #FF5722;
+    --text-primary: #ffffff;
+    --text-on-card: #1a1a1a;
+}
+```
+
+**Signature Elements:**
+- Bold colored card as focal point (orange, coral, or vibrant accent)
+- Large section numbers (01, 02, etc.)
+- Navigation breadcrumbs with active/inactive opacity states
+- Grid-based layout for precise alignment
+
+---
+
+### 2. Electric Studio
+
+**Vibe:** Bold, clean, professional, high contrast
+
+**Layout:** Split panel—white top, blue bottom. Brand marks in corners.
+
+**Typography:**
+- Display: `Manrope` (800)
+- Body: `Manrope` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-dark: #0a0a0a;
+    --bg-white: #ffffff;
+    --accent-blue: #4361ee;
+    --text-dark: #0a0a0a;
+    --text-light: #ffffff;
+}
+```
+
+**Signature Elements:**
+- Two-panel vertical split
+- Accent bar on panel edge
+- Quote typography as hero element
+- Minimal, confident spacing
+
+---
+
+### 3. Creative Voltage
+
+**Vibe:** Bold, creative, energetic, retro-modern
+
+**Layout:** Split panels—electric blue left, dark right. Script accents.
+
+**Typography:**
+- Display: `Syne` (700/800)
+- Mono: `Space Mono` (400/700)
+
+**Colors:**
+```css
+:root {
+    --bg-primary: #0066ff;
+    --bg-dark: #1a1a2e;
+    --accent-neon: #d4ff00;
+    --text-light: #ffffff;
+}
+```
+
+**Signature Elements:**
+- Electric blue + neon yellow contrast
+- Halftone texture patterns
+- Neon badges/callouts
+- Script typography for creative flair
+
+---
+
+### 4. Dark Botanical
+
+**Vibe:** Elegant, sophisticated, artistic, premium
+
+**Layout:** Centered content on dark. Abstract soft shapes in corner.
+
+**Typography:**
+- Display: `Cormorant` (400/600) — elegant serif
+- Body: `IBM Plex Sans` (300/400)
+
+**Colors:**
+```css
+:root {
+    --bg-primary: #0f0f0f;
+    --text-primary: #e8e4df;
+    --text-secondary: #9a9590;
+    --accent-warm: #d4a574;
+    --accent-pink: #e8b4b8;
+    --accent-gold: #c9b896;
+}
+```
+
+**Signature Elements:**
+- Abstract soft gradient circles (blurred, overlapping)
+- Warm color accents (pink, gold, terracotta)
+- Thin vertical accent lines
+- Italic signature typography
+- **No illustrations—only abstract CSS shapes**
+
+---
+
+## Light Themes
+
+### 5. Notebook Tabs
+
+**Vibe:** Editorial, organized, elegant, tactile
+
+**Layout:** Cream paper card on dark background. Colorful tabs on right edge.
+
+**Typography:**
+- Display: `Bodoni Moda` (400/700) — classic editorial
+- Body: `DM Sans` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-outer: #2d2d2d;
+    --bg-page: #f8f6f1;
+    --text-primary: #1a1a1a;
+    --tab-1: #98d4bb; /* Mint */
+    --tab-2: #c7b8ea; /* Lavender */
+    --tab-3: #f4b8c5; /* Pink */
+    --tab-4: #a8d8ea; /* Sky */
+    --tab-5: #ffe6a7; /* Cream */
+}
+```
+
+**Signature Elements:**
+- Paper container with subtle shadow
+- Colorful section tabs on right edge (vertical text)
+- Binder hole decorations on left
+- Tab text must scale with viewport: `font-size: clamp(0.5rem, 1vh, 0.7rem)`
+
+---
+
+### 6. Pastel Geometry
+
+**Vibe:** Friendly, organized, modern, approachable
+
+**Layout:** White card on pastel background. Vertical pills on right edge.
+
+**Typography:**
+- Display: `Plus Jakarta Sans` (700/800)
+- Body: `Plus Jakarta Sans` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-primary: #c8d9e6;
+    --card-bg: #faf9f7;
+    --pill-pink: #f0b4d4;
+    --pill-mint: #a8d4c4;
+    --pill-sage: #5a7c6a;
+    --pill-lavender: #9b8dc4;
+    --pill-violet: #7c6aad;
+}
+```
+
+**Signature Elements:**
+- Rounded card with soft shadow
+- **Vertical pills on right edge** with varying heights (like tabs)
+- Consistent pill width, heights: short → medium → tall → medium → short
+- Download/action icon in corner
+
+---
+
+### 7. Split Pastel
+
+**Vibe:** Playful, modern, friendly, creative
+
+**Layout:** Two-color vertical split (peach left, lavender right).
+
+**Typography:**
+- Display: `Outfit` (700/800)
+- Body: `Outfit` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-peach: #f5e6dc;
+    --bg-lavender: #e4dff0;
+    --text-dark: #1a1a1a;
+    --badge-mint: #c8f0d8;
+    --badge-yellow: #f0f0c8;
+    --badge-pink: #f0d4e0;
+}
+```
+
+**Signature Elements:**
+- Split background colors
+- Playful badge pills with icons
+- Grid pattern overlay on right panel
+- Rounded CTA buttons
+
+---
+
+### 8. Vintage Editorial
+
+**Vibe:** Witty, confident, editorial, personality-driven
+
+**Layout:** Centered content on cream. Abstract geometric shapes as accent.
+
+**Typography:**
+- Display: `Fraunces` (700/900) — distinctive serif
+- Body: `Work Sans` (400/500)
+
+**Colors:**
+```css
+:root {
+    --bg-cream: #f5f3ee;
+    --text-primary: #1a1a1a;
+    --text-secondary: #555;
+    --accent-warm: #e8d4c0;
+}
+```
+
+**Signature Elements:**
+- Abstract geometric shapes (circle outline + line + dot)
+- Bold bordered CTA boxes
+- Witty, conversational copy style
+- **No illustrations—only geometric CSS shapes**
+
+---
+
+## Specialty Themes
+
+### 9. Neon Cyber
+
+**Vibe:** Futuristic, techy, confident
+
+**Typography:** `Clash Display` + `Satoshi` (Fontshare)
+
+**Colors:** Deep navy (#0a0f1c), cyan accent (#00ffcc), magenta (#ff00aa)
+
+**Signature:** Particle backgrounds, neon glow, grid patterns
+
+---
+
+### 10. Terminal Green
+
+**Vibe:** Developer-focused, hacker aesthetic
+
+**Typography:** `JetBrains Mono` (monospace only)
+
+**Colors:** GitHub dark (#0d1117), terminal green (#39d353)
+
+**Signature:** Scan lines, blinking cursor, code syntax styling
+
+---
+
+### 11. Swiss Modern
+
+**Vibe:** Clean, precise, Bauhaus-inspired
+
+**Typography:** `Archivo` (800) + `Nunito` (400)
+
+**Colors:** Pure white, pure black, red accent (#ff3300)
+
+**Signature:** Visible grid, asymmetric layouts, geometric shapes
+
+---
+
+### 12. Paper & Ink
+
+**Vibe:** Editorial, literary, thoughtful
+
+**Typography:** `Cormorant Garamond` + `Source Serif 4`
+
+**Colors:** Warm cream (#faf9f7), charcoal (#1a1a1a), crimson accent (#c41e3a)
+
+**Signature:** Drop caps, pull quotes, elegant horizontal rules
+
+---
+
+## Font Pairing Quick Reference
+
+| Preset | Display Font | Body Font | Source |
+|--------|--------------|-----------|--------|
+| Bold Signal | Archivo Black | Space Grotesk | Google |
+| Electric Studio | Manrope | Manrope | Google |
+| Creative Voltage | Syne | Space Mono | Google |
+| Dark Botanical | Cormorant | IBM Plex Sans | Google |
+| Notebook Tabs | Bodoni Moda | DM Sans | Google |
+| Pastel Geometry | Plus Jakarta Sans | Plus Jakarta Sans | Google |
+| Split Pastel | Outfit | Outfit | Google |
+| Vintage Editorial | Fraunces | Work Sans | Google |
+| Neon Cyber | Clash Display | Satoshi | Fontshare |
+| Terminal Green | JetBrains Mono | JetBrains Mono | JetBrains |
+
+---
+
+## DO NOT USE (Generic AI Patterns)
+
+**Fonts:** Inter, Roboto, Arial, system fonts as display
+
+**Colors:** `#6366f1` (generic indigo), purple gradients on white
+
+**Layouts:** Everything centered, generic hero sections, identical card grids
+
+**Decorations:** Realistic illustrations, gratuitous glassmorphism, drop shadows without purpose
+
+---
+
+## CSS Gotchas
+
+### Negating CSS Functions
+
+**WRONG — silently ignored by browsers (no console error):**
+```css
+right: -clamp(28px, 3.5vw, 44px);   /* Browser ignores this */
+margin-left: -min(10vw, 100px);      /* Browser ignores this */
+```
+
+**CORRECT — wrap in `calc()`:**
+```css
+right: calc(-1 * clamp(28px, 3.5vw, 44px));  /* Works */
+margin-left: calc(-1 * min(10vw, 100px));     /* Works */
+```
+
+CSS does not allow a leading `-` before function names. The browser silently discards the entire declaration — no error, the element just appears in the wrong position. **Always use `calc(-1 * ...)` to negate CSS function values.**
+

package/templates/.agent/skills/frontend-slides/animation-patterns.md

@@ -0,0 +1,110 @@
+# Animation Patterns Reference
+
+Use this reference when generating presentations. Match animations to the intended feeling.
+
+## Effect-to-Feeling Guide
+
+| Feeling | Animations | Visual Cues |
+|---------|-----------|-------------|
+| **Dramatic / Cinematic** | Slow fade-ins (1-1.5s), large scale transitions (0.9 to 1), parallax scrolling | Dark backgrounds, spotlight effects, full-bleed images |
+| **Techy / Futuristic** | Neon glow (box-shadow), glitch/scramble text, grid reveals | Particle systems (canvas), grid patterns, monospace accents, cyan/magenta/electric blue |
+| **Playful / Friendly** | Bouncy easing (spring physics), floating/bobbing | Rounded corners, pastel/bright colors, hand-drawn elements |
+| **Professional / Corporate** | Subtle fast animations (200-300ms), clean slides | Navy/slate/charcoal, precise spacing, data visualization focus |
+| **Calm / Minimal** | Very slow subtle motion, gentle fades | High whitespace, muted palette, serif typography, generous padding |
+| **Editorial / Magazine** | Staggered text reveals, image-text interplay | Strong type hierarchy, pull quotes, grid-breaking layouts, serif headlines + sans body |
+
+## Entrance Animations
+
+```css
+/* Fade + Slide Up (most versatile) */
+.reveal {
+    opacity: 0;
+    transform: translateY(30px);
+    transition: opacity 0.6s var(--ease-out-expo),
+                transform 0.6s var(--ease-out-expo);
+}
+.visible .reveal {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+/* Scale In */
+.reveal-scale {
+    opacity: 0;
+    transform: scale(0.9);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+
+/* Slide from Left */
+.reveal-left {
+    opacity: 0;
+    transform: translateX(-50px);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+
+/* Blur In */
+.reveal-blur {
+    opacity: 0;
+    filter: blur(10px);
+    transition: opacity 0.8s, filter 0.8s var(--ease-out-expo);
+}
+```
+
+## Background Effects
+
+```css
+/* Gradient Mesh — layered radial gradients for depth */
+.gradient-bg {
+    background:
+        radial-gradient(ellipse at 20% 80%, rgba(120, 0, 255, 0.3) 0%, transparent 50%),
+        radial-gradient(ellipse at 80% 20%, rgba(0, 255, 200, 0.2) 0%, transparent 50%),
+        var(--bg-primary);
+}
+
+/* Noise Texture — inline SVG for grain */
+.noise-bg {
+    background-image: url("data:image/svg+xml,..."); /* Inline SVG noise */
+}
+
+/* Grid Pattern — subtle structural lines */
+.grid-bg {
+    background-image:
+        linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
+    background-size: 50px 50px;
+}
+```
+
+## Interactive Effects
+
+```javascript
+/* 3D Tilt on Hover — adds depth to cards/panels */
+class TiltEffect {
+    constructor(element) {
+        this.element = element;
+        this.element.style.transformStyle = 'preserve-3d';
+        this.element.style.perspective = '1000px';
+
+        this.element.addEventListener('mousemove', (e) => {
+            const rect = this.element.getBoundingClientRect();
+            const x = (e.clientX - rect.left) / rect.width - 0.5;
+            const y = (e.clientY - rect.top) / rect.height - 0.5;
+            this.element.style.transform = `rotateY(${x * 10}deg) rotateX(${-y * 10}deg)`;
+        });
+
+        this.element.addEventListener('mouseleave', () => {
+            this.element.style.transform = 'rotateY(0) rotateX(0)';
+        });
+    }
+}
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Fonts not loading | Check Fontshare/Google Fonts URL; ensure font names match in CSS |
+| Animations not triggering | Verify Intersection Observer is running; check `.visible` class is being added |
+| Scroll snap not working | Ensure `scroll-snap-type: y mandatory` on html; each slide needs `scroll-snap-align: start` |
+| Mobile issues | Disable heavy effects at 768px breakpoint; test touch events; reduce particle count |
+| Performance issues | Use `will-change` sparingly; prefer `transform`/`opacity` animations; throttle scroll handlers |