zhaodi-Wen/design-agent-skills

Scroll and Drag Product Showcase

Deliver a working web page along with editable source files. First confirm whether this iteration involves scrolling, dragging, or both. When adding one interaction to an existing page, preserve the other authorized interaction. Use reference videos to identify visual and motion relationships—do not assume which framework the original site used based solely on the video. Clearly state completion status separately for the page display and the real e-commerce ordering system.

Extracting from References

Read the duration and frame size of the local video, and extract frames from the beginning, transition midpoints, and end. If necessary, increase sampling to confirm continuous motion. Record: subject position and size, view changes, background and props, font size, occlusion order, scroll direction, and rewind behavior. Do not mistake screen recording borders, narration captions, or the mouse cursor for part of the web design.

Organize the references into an action table arranged by scroll progress. Mark which actions are directly visible, which are inferred, and which implementation method you choose. For the coffee case study and route decisions, see references/motion-design.md.

Choosing the Presentation Method

• Realistic view changes, interactive rotation, or material swapping: Three.js 3D model with GSAP. Reuse an existing GLB when suitable; for simple cups, bottles, or cans, use parametric geometry modeling and explicitly note it is an original illustrative model.
• Fixed camera, complex lighting, or pre-rendered assets: Canvas sprite-sheet animation. The frame number is determined by scroll progress; handle unloaded frames and memory usage—do not assume arbitrary video frames can be scrubbed smoothly.
• Only translation, opacity, and planar tilting: DOM/CSS layers. A single image cannot create a realistic front-to-back turn.

Decide the asset approach before building the scroll logic. If the user has not specified a brand, use clear demo brand and product data; do not fabricate certifications, sales figures, reviews, or real transaction results.

Starter Templates

Two self-contained Vite + Three.js + GSAP templates are available. Choose based on the product and task; new brands still require a new visual design.

• assets/starter/ (coffee, default): Coffee scroll narrative with drag rotation, flavor color change, and local shopping bag; mini.html is a mini-app style H5 sharing the product and shopping bag.
• assets/gallery/ (gallery): Three visual themes for perfume, headphones, and watch. Headphones support scroll expansion, three-section copy, and drag coexistence; perfume and watch use drag and structural buttons. Use this for non-coffee cases.

Create a project in a directory that does not yet exist (the script will not overwrite an existing project):

python3 /path/to/scroll-product-showcase/scripts/create_project.py /absolute/path/to/new-project
cd /absolute/path/to/new-project
npm ci
npm run dev -- --port 5197

Replace /path/to/scroll-product-showcase with the actual skill installation path. If the port is occupied, use an available port and deliver the actual address.

For non-coffee cases, add --template gallery. The headphone entry point is /?case=headphones; there are also /?case=perfume and /?case=watch. When modifying an existing project, edit that project directly instead of using the generator to overwrite it.

Modification locations:

• src/scene.js: camera, lighting, scroll posture, and independent drag angles; coffee model is here, gallery models are in src/models.js.
• src/scroll-story.js: scroll stages, synced copy, and progress bar.
• src/main.js: entry and interaction state; pointer gestures for coffee are in src/drag.js, shopping bag in src/bag.js.
• Coffee src/products.js, gallery src/content.js: product copy and color schemes.
• src/style.css and index.html: layout, responsive design, copy, and semantic structure.
• Coffee mini.html, src/mini.js, src/mini.css, src/cup-viewer.js: mini-app style interface; vite.config.js preserves both build entry points.

The templates use CSS sticky to fix the scene and ScrollTrigger to drive progress; do not add another pin at the same layer. Other projects can switch to ScrollTrigger pin, but must first remove the conflicting sticky layout.

Interaction Combinations and Implementation Constraints

When dealing with drag, scroll coexistence, structural buttons, or mini-app interfaces, read references/interaction-modes.md, which covers posture layering, input division, and acceptance criteria.

• Use a single 0–1 progress value to control the scroll-driven model, camera, and text; at the same manual angle, moving forward and backward to the same progress should yield the same posture. Store drag angles independently and overlay them on the scroll posture; do not let the two handlers overwrite each other's rotation.
• When scroll and drag coexist, reset should only clear manual angles, preserving scroll progress and color scheme. If structural buttons control the same action, they should jump to the timeline's corresponding position, avoid starting another animation that competes with the progress variable; obey the user's explicit instructions if they define a different meaning for reset.
• Determine the subject's safe area first, then place text; on mobile, resize the subject and trajectory—do not simply scale down the desktop version proportionally.
• Titles, descriptions, selection buttons, and prices must be placed in accessible HTML; Canvas handles visual presentation.
• Release old textures when swapping; clean up observers, animations, events, and GPU resources on teardown. Limit pixel ratio and avoid continuous repainting of invisible scenes.
• Provide static compositions and directly accessible product information for the reduce-motion preference. When WebGL fails, preserve product selection and the shopping bag.
• The local shopping bag can support selection, quantity adjustment, deletion, and persistence. Clearly label it as a demo when not connected to a backend; do not display "order submitted" or "payment successful."

Verification and Delivery

Build first, then check the real rendering in a browser. Cover the beginning, middle, end, rewind, narrow screen, reduce-motion mode, and product selection with actual interaction; in coexistence mode, also test mid-page drag, continued scrolling, and reset. After switching cases, verify copy, stage height, and color scheme. If there is a shopping bag, verify quantity, total, and state after refresh. Check for page anomalies, resource loading, and horizontal overflow.

The coffee template's scripts/verify-browser.mjs is an optional regression script that can be run by pointing PLAYWRIGHT_MODULE at an existing Playwright module and BASE_URL at the actual server. If the current environment mandates a browser tool, use that tool for the same interactive verification instead of launching another browser driver. Use the browser tool to verify the gallery with the scenarios above. Report only checks actually performed; screenshots are still needed to judge visual quality—a successful build or HTTP 200 does not replace visual inspection.

After completion, deliver the preview URL, source directory, and key screenshots. Explain the actual implementation path and any services not yet connected. Only record a screen capture or video if the user explicitly requests it; do not report static screenshots as interactive verification or a screen recording.

For technical reference, query as needed: GSAP ScrollTrigger, Three.js GLTFLoader.