feat: implement management folder architecture, hover-only tool sliders, grain transform animation, and prominent upload studio
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# Management Folder Architecture & Refined Visual UX Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
This plan resolves four core user requirements:
|
||||
1. **Centralized Management Folder (`management/`)**: Modular, page-by-page folder architecture housing all JSON configs and media (before/after images, banners, videos), allowing direct file-drop replacement for live website updates.
|
||||
2. **Tool Page Re-engineering (`/tools/[slug]`)**: Spacious prominent upload studio, borderless result-focused display stage, typography placed outside cards, and a generative latent grain transformation animation.
|
||||
3. **Homepage Tool Stack Cards Hover-Only Slide**: Eliminate simultaneous chaotic auto-sliding across all 8 cards; only animate the card that is actively hovered, and allow click/drag to manually inspect.
|
||||
4. **Fluid, Seamless Horizontal Scroll**: Fix sticky overflow constraints (`overflow-x: clip`), smooth scroll conflicts, and ensure frictionless progression from vertical -> horizontal -> vertical.
|
||||
|
||||
---
|
||||
|
||||
## File Structure & Responsibilities
|
||||
|
||||
```
|
||||
management/
|
||||
├── pages/
|
||||
│ ├── home/
|
||||
│ │ ├── page.config.json # Home page section configuration & copy
|
||||
│ │ └── media/ # Media assets used on home page
|
||||
│ └── tools/
|
||||
│ ├── cartoon-avatar/
|
||||
│ │ ├── tool.config.json # Tool metadata, copy, displayType ("beforeAfter" | "banner")
|
||||
│ │ └── media/ # before.jpg, after.jpg, sample-*.jpg
|
||||
│ ├── blemish-remover/
|
||||
│ ├── background-remover/
|
||||
│ ├── colorization/
|
||||
│ ├── old-photo-restorer/
|
||||
│ ├── photo-enhancer/
|
||||
│ ├── polaroid-maker/
|
||||
│ └── teeth-whitener/
|
||||
public/
|
||||
└── management -> symlink or synced to ../management
|
||||
src/
|
||||
├── components/
|
||||
│ ├── ui/
|
||||
│ │ ├── NeuralGrainOverlay.tsx # Generative AI latent grain transform animation
|
||||
│ │ ├── CardBeforeAfterSlider.tsx # Tool stack card slider (hover-only slide, click-drag)
|
||||
│ ├── sections/
|
||||
│ │ ├── HeroSection.tsx # Redesigned tool hero (prominent upload, result-focused display)
|
||||
│ │ ├── TryItWidget.tsx # Spacious, beautiful upload studio
|
||||
│ │ ├── CinematicHorizontalScrollSection.tsx # Frictionless horizontal showcase
|
||||
├── lib/
|
||||
│ ├── config/
|
||||
│ │ ├── loader.ts # Loads configurations and media paths from management/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Task 1: Create Centralized `management/` Folder Architecture
|
||||
- [ ] Create `management/pages/tools/[slug]/` directories for all 8 tools with `tool.config.json` and `media/` subdirectories.
|
||||
- [ ] Copy or generate high-res before/after assets into `management/pages/tools/[slug]/media/before.jpg` and `after.jpg`.
|
||||
- [ ] Create `management/pages/home/` with `page.config.json` and `media/`.
|
||||
- [ ] Ensure Next.js can serve assets from `management/` via symlink in `public/management` or Next route so replacing any file immediately updates the live site.
|
||||
- [ ] Update `src/lib/config/loader.ts` to source tool data and media paths from `management/`.
|
||||
- [ ] Verify `npm test` and build compile cleanly.
|
||||
|
||||
### Task 2: Home Page Tool Stack Cards — Hover-Only Sliding
|
||||
- [ ] Update `src/components/ui/CardBeforeAfterSlider.tsx`:
|
||||
- Static 50% rest state when not hovered.
|
||||
- Start smooth, gentle slide animation **only when cursor is hovering over the card**.
|
||||
- Clicking/dragging allows manual scrub.
|
||||
- Reset to rest on mouse leave.
|
||||
- [ ] Verify all cards remain calm and static until hovered.
|
||||
|
||||
### Task 3: Tool Landing Page (`/tools/[slug]`) Visual Redesign & Grain Transform Animation
|
||||
- [ ] Create `src/components/ui/NeuralGrainOverlay.tsx`:
|
||||
- Authentic generative AI latent grain / noise sweep animation representing neural model synthesis.
|
||||
- Canvas/SVG-based high-frequency grain texture with customizable intensity and scan sweep.
|
||||
- [ ] Redesign `src/components/sections/HeroSection.tsx` (`variant === 'toolHero'`):
|
||||
- Typography placed outside cards: Large editorial headline, category badge, and descriptive copy directly on page background.
|
||||
- **Left / Display Stage**: Focus 100% on actual transformation results with minimal border chrome, integrated Before/After slider, and the Neural Grain transformation effect.
|
||||
- **Right / Upload Studio**: Spacious, prominent, high-end upload dropzone with glowing borders, clear specs, and sample presets.
|
||||
- [ ] Update `src/components/sections/TryItWidget.tsx` to match the spacious, beautiful studio layout.
|
||||
|
||||
### Task 4: Fix Horizontal Showcase Scroll Fluidity
|
||||
- [ ] Fix `body` overflow in `src/app/globals.css`: replace `overflow-x: hidden` with `overflow-x: clip` so `position: sticky` is never disabled.
|
||||
- [ ] In `CinematicHorizontalScrollSection.tsx`, ensure synchronous DOM transform updates on scroll with liquid GPU hardware acceleration.
|
||||
- [ ] Ensure arrow navigation, wheel scrolling, and trackpad swipe glide seamlessly through all cards and transition cleanly to the next section.
|
||||
|
||||
### Task 5: Verification & End-to-End Testing
|
||||
- [ ] Run `npm test` to verify all unit tests pass.
|
||||
- [ ] Run headless browser script verifying:
|
||||
- Tool cards in "Find the right tool fast" slide ONLY on hover.
|
||||
- Tool specific page renders prominent upload studio + grain transformation display + typography outside cards.
|
||||
- Horizontal scroll glides seamlessly.
|
||||
- Replacing an image in `management/` updates the live page.
|
||||
- [ ] Commit all changes to git.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Interactive Model Showcase Vertical Wheel Translation & Side Arrows Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Enable visitors to navigate the flagship transformation models in the Interactive Model Showcase via vertical wheel/trackpad scrolling and dedicated Left/Right side arrow buttons.
|
||||
|
||||
**Architecture:** Client-side React hooks (`useRef`, `useState`, `useEffect`) in `CinematicHorizontalScrollSection.tsx` with non-passive wheel event interception, edge boundary pass-through, smooth card stepping via `scrollBy`, and floating accessible arrow buttons.
|
||||
|
||||
**Tech Stack:** Next.js 14 App Router, React 18, TypeScript, Tailwind CSS, Lucide React (`ChevronLeft`, `ChevronRight`).
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-11-04-showcase-vertical-wheel-and-arrows-design.md`
|
||||
|
||||
## Global Constraints
|
||||
- Preserve existing data interfaces and Mustache binding resolution.
|
||||
- Never trap user scroll: when rail is at the left boundary and scrolling up, or right boundary and scrolling down, let vertical scroll bubble to page.
|
||||
- Accessible: `aria-label` attributes on both buttons, keyboard operable.
|
||||
- Responsive: Floating arrows styled to fit both mobile and wide screens without obscuring critical interactive elements.
|
||||
|
||||
## Review Focus
|
||||
1. Wheel listener must use `{ passive: false }` so `preventDefault()` functions cleanly without console warnings.
|
||||
2. Left and Right arrows calculate proper scroll distance (card width + gap) and smoothly animate.
|
||||
3. Clean boundary detection prevents stutter when reaching start/end of the rail.
|
||||
4. Touch swipe functionality on mobile devices is preserved intact.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Enhance `CinematicHorizontalScrollSection.tsx` with Wheel & Arrow Controls
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/components/sections/CinematicHorizontalScrollSection.tsx`
|
||||
|
||||
- [ ] **Step 1: Add state and refs for rail, scroll boundaries, and wheel interaction**
|
||||
- Define `railRef = useRef<HTMLDivElement>(null)`
|
||||
- Define `canScrollLeft` and `canScrollRight` states
|
||||
- Define `isHovered` or rail event listener for `wheel` with `{ passive: false }`
|
||||
|
||||
- [ ] **Step 2: Implement boundary-aware vertical wheel translation**
|
||||
- Intercept vertical `deltaY` when dominant over `deltaX`
|
||||
- Translate `e.deltaY` into `rail.scrollLeft`
|
||||
- Allow natural page scroll if already at leftmost or rightmost boundary
|
||||
|
||||
- [ ] **Step 3: Implement floating Left and Right navigation buttons**
|
||||
- Place Left and Right arrow buttons vertically centered on the carousel flanks
|
||||
- Implement `scrollDirection('left')` and `scrollDirection('right')` using `rail.scrollBy({ left: +/- step, behavior: 'smooth' })`
|
||||
- Add `aria-label` and visual disabled/faded states
|
||||
|
||||
- [ ] **Step 4: Update scroll snap style to `snap-proximity`**
|
||||
- Prevent harsh snapping conflict during continuous wheel scrolling
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Build Verification & Regression Check
|
||||
|
||||
**Files:**
|
||||
- Run test and build commands
|
||||
|
||||
- [ ] **Step 1: Run unit test suite**
|
||||
- `npm test`
|
||||
- [ ] **Step 2: Run production Next.js build**
|
||||
- `npm run build`
|
||||
@@ -0,0 +1,64 @@
|
||||
# Design: Interactive Model Showcase Vertical Scroll Translation & Side Navigation Arrows
|
||||
|
||||
**Date:** 2026-11-04
|
||||
**Status:** Approved (Option 1 selected by user)
|
||||
**Target File:** `src/components/sections/CinematicHorizontalScrollSection.tsx`
|
||||
|
||||
---
|
||||
|
||||
## 1. Intent & Purpose
|
||||
Enable visitors to navigate the flagship transformation models in the **Interactive Model Showcase** using natural vertical wheel/trackpad scrolling and dedicated tactile Left/Right side arrow buttons, making horizontal exploration effortless on both desktop and mobile.
|
||||
|
||||
---
|
||||
|
||||
## 2. Goals, Non-Goals, and Anti-Goals
|
||||
|
||||
### Goals
|
||||
- **Vertical-to-Horizontal Translation**: Vertical mouse wheel and trackpad scroll gestures (`deltaY`) over the showcase rail directly translate into horizontal scrolling.
|
||||
- **Natural Boundary Pass-Through**: When the rail reaches its horizontal start (scrolling up) or end (scrolling down), vertical page scrolling naturally resumes so users never get trapped.
|
||||
- **Side Navigation Arrows**: Sleek, accessible, liquid-glass Left and Right arrow buttons floating on either side of the rail that slide card-by-card on click.
|
||||
- **Dynamic State**: Arrow buttons automatically update their disabled/opacity state based on current scroll position.
|
||||
- **Zero Regressions**: Maintain high-contrast light creamy theme, mobile touch-swipe, and WCAG AA accessibility standards.
|
||||
|
||||
### Non-Goals
|
||||
- Full viewport height pinning (Option 2 was declined in favor of in-place wheel translation).
|
||||
- Modifying the underlying data schemas in `content/pages/home.json` or `SectionRenderer.tsx`.
|
||||
|
||||
### Anti-Goals
|
||||
- Trapping vertical scroll permanently or blocking scroll when at the edges.
|
||||
- Obscuring before/after comparison interactive sliders with arrow buttons.
|
||||
|
||||
---
|
||||
|
||||
## 3. Approaches Considered
|
||||
|
||||
1. **Option 1: In-Place Wheel & Trackpad Translation + Floating Side Arrows (Selected)**
|
||||
- Translates `deltaY` to `scrollLeft` on non-passive wheel events when hovering the showcase section.
|
||||
- Bails out when at the boundary edges to allow standard vertical document scroll.
|
||||
- Adds floating, accessible `ChevronLeft` and `ChevronRight` buttons on the left and right flanks.
|
||||
- **Trade-off:** Retains clean layout flow without modifying page scroll height.
|
||||
|
||||
2. **Option 2: Sticky Pinned Viewport Track (Rejected)**
|
||||
- Pins the section to the viewport for 300vh of vertical scroll distance.
|
||||
- **Trade-off:** High layout footprint, can feel disruptive on shorter viewports.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Details
|
||||
|
||||
- **File:** `src/components/sections/CinematicHorizontalScrollSection.tsx`
|
||||
- **State & Refs:**
|
||||
- `railRef = useRef<HTMLDivElement>(null)`: Reference to the horizontal scrolling rail.
|
||||
- `canScrollLeft`: boolean state, default false.
|
||||
- `canScrollRight`: boolean state, default true.
|
||||
- **Wheel Listener (`passive: false`):**
|
||||
- Attached via `useEffect` with clean cleanup.
|
||||
- Only intercepts when vertical delta is dominant (`Math.abs(e.deltaY) > Math.abs(e.deltaX)`).
|
||||
- Calls `e.preventDefault()` only if the rail has remaining scroll distance in the scroll direction.
|
||||
- **Arrow Navigation:**
|
||||
- Left button with `ChevronLeft` icon, right button with `ChevronRight` icon.
|
||||
- `scrollBy({ left: +/- scrollDistance, behavior: 'smooth' })`, calculating step based on card width + gap.
|
||||
- High z-index, styled with `bg-white/90`, `backdrop-blur-md`, `shadow-cream-md`, and smooth hover scale.
|
||||
- Hidden or opacity-0 when disabled to maintain a clean aesthetic at boundaries.
|
||||
- **Snap Polish:**
|
||||
- Uses `snap-x snap-proximity` for smooth wheel translation without abrasive snap fighting, locking neatly onto cards when resting.
|
||||
Reference in New Issue
Block a user