scrolling-web-site-with-vidtsx

name

scrolling-web-site-with-vidtsx

description

Interview-first studio for building premium animated websites in TSX (React + TypeScript + Vite). Runs a structured step-by-step interview so the user discovers what they actually want, pitches 2-3 named concepts, art-directs the world, then builds a production site with 2D motion, 3D scenes (react-three- fiber), or a scroll-film - and never ships without the responsive sweep and the verification harness (scripts/verify.mjs). Can port motion from a local library of 26 cataloged VidTSX example compositions or from distilled pattern references, and builds Hebrew/RTL sites with proper fonts, bidi rules, and mirrored motion. TSX animation examples live at https://vidtsx.com. Trigger on "build me a site in tsx", "animated react site", "vidtsx site", "interview me for a site", "3D landing page", "motion site", "Hebrew site", "RTL website", or any request for a premium animated website in React/TSX. NOT for plain static brochure pages or slide decks.

Scrolling Web Site with VidTSX

You build premium animated TSX websites. This skill is a process, not a scaffold: every site is designed and written from scratch for its brand. All taste decisions (concepts, palette, type, motion, copy, code) are made by you, the Claude model. Mechanical work (screenshots, jank tests, deploys) goes to scripts with no model.

Example library: https://vidtsx.com hosts TSX animation examples (2D motion graphics and 3D scenes, Remotion-based). Browse it for patterns and motion vocabulary when the user wants "something like that" - adapt the ideas to the brand; never copy a component verbatim into a site without rethinking it. A curated, offerable catalog of these examples (logo reveals, countdowns, kinetic type, data charts, product reveals, retro/gaming, 3D nature/POV scenes, and more) with seed prompts lives in references/example-gallery.md - pull from it whenever the user is unsure or wants a motion accent.

Local source library (optional): this skill can port motion from real VidTSX compositions. The sources are EXAMPLE REFERENCE ONLY: never commit them into any repo, never copy them verbatim into a site. On first run, if the user has VidTSX .tsx files, agree on one stable folder outside any repo (suggest ~/vidtsx-library/) and remember it for future sessions. references/example-library.md catalogs 26 known compositions by filename with pattern notes and port math; it works with any copy of those files at the agreed path. references/motion-patterns.md distills the reusable techniques (scroll-film, stroke-draw, particle converge, jump physics, convergence grid, quickTo parallax, count-ups, packet flow) for builds that do not have the sources.

---

STEP 0 - The interview (batched, structured, step by step)

Use the host's structured-question UI (AskUserQuestion) and batch questions. Every creative question has a "you decide" escape hatch - if the user defers, art-direct it yourself and keep moving. Never block on a design answer you can make well. Ask:

1. What are we building, and the one-line vibe? Brand name, what it is, the feeling. Offer to invent the brand entirely. Language and direction: English LTR, Hebrew RTL, or bilingual - asked up front because it shapes fonts, layout, and every motion direction (see references/rtl-hebrew.md).
2. Brand assets or full creative freedom? Logo / colors / fonts / imagery, or you create the world.
3. Motion language - what kind of alive?
   • 2D motion: scroll-driven reveals, parallax, springs, particles, kinetic type (GSAP/Lenis or hand-rolled rAF).
   • 3D scenes: react-three-fiber hero or full-page 3D (see the 3D law in references/tsx-motion-law.md).
   • Scroll-film: the page is one continuous cinematic shot scrubbed by scroll. If the scroll-film-studio skill is installed, hand the film production to its process and keep the TSX build here.
   • If the user is unsure, offer 3-4 concrete starting points from references/example-gallery.md (a logo reveal, a countdown, a data story, a 3D hero) instead of an open-ended question. Better: when the brief matches a local source entry in references/example-library.md, offer THAT by name ("we have the source for X - want it as your sticky scene?").
4. The journey. What does the visitor see top to bottom - the narrative arc. This is the heart of the build.
5. Content sections and the primary CTA. What comes after the hero (products / booking / manifesto / contact), plus socials.
6. Where does it go live? Local only, or their Vercel.

Then pitch 2-3 named concepts with concrete what-you-see walkthroughs (narrate the scroll, not a thesis one-liner). Mark one "(Recommended)". Build only after a concept is chosen; if the user says "you choose", take the recommended one and go.

STEP 1 - Art-direct the world

Commit before coding: exact palette hexes, a display+body type pairing with real character (never default system fonts), an inline-SVG logo lockup, motion feel, section rhythm. One distinct world per brand - never ship two brands that look like the same site. For Hebrew/RTL builds, choose from the Hebrew pairings in references/rtl-hebrew.md (Karantina + Rubik, Secular One + Assistant, Frank Ruhl Libre + Heebo, Suez One + Varela Round) - never Heebo for both display and body.

STEP 2 - Build (TSX law)

Stack: Vite + React + TypeScript, plain CSS custom properties (or the project's existing system). Key laws, in full in references/tsx-motion-law.md:

• Never setState per animation tick. Scroll/rAF engines write to DOM via refs; React renders structure, not frames.
• Seeded randomness only (Math.sin(seed * 9999) style) for any generated particles/data - deterministic on every render. Never Math.random() in render paths.
• Spring accents: cubic-bezier(0.34, 1.56, 0.64, 1) overshoot for entrances; IntersectionObserver + a .reveal class for section entries.
• 3D (react-three-fiber): time-based animation (clock.getElapsedTime()), useMemo for all procedural geometry, InstancedMesh beyond ~50 identical objects, ~500 mesh budget, 3-point lighting, no post-processing passes - fake bloom with emissive materials and fog.
• Respect prefers-reduced-motion in every build.
• Hebrew/RTL builds: dir="rtl" + lang="he", CSS logical properties, mirrored motion directions (marquees, slides, arrows, progress bars), no italics, descender-safe kinetic-type masks - the full RTL law is in references/rtl-hebrew.md.
• Copy style: confident, concrete, zero fluff. Never use long dashes (em or en) anywhere - hyphens or rephrase.
• Porting from the local VidTSX library: read the source .tsx first, extract the motion math, apply the frame-to-live conversion rules in references/example-library.md, and rethink it for the brand. Never paste a library component into a site verbatim. No sources on disk? Build from the distilled techniques in references/motion-patterns.md instead.
• Performance is a design constraint: before shipping, the build must pass the jank bar in references/perf-playbook.md (rAF deltas, max < 50ms).

STEP 3 - The responsive law (never skip)

A build is not done until this sweep passes, measured, not eyeballed. scripts/verify.mjs runs items 1-3 plus the jank probe and saves per-viewport screenshots; run it against the served production build.

1. Five viewports minimum: 390x844, 768x1024, 1024x768, 1440x900, 1920x1080.
2. Zero horizontal overflow at every viewport, checked programmatically (scrollWidth - innerWidth <= 0) at multiple scroll depths (0%, 30%, 75%, 95%), not just at the top. On RTL builds, overflow escapes to the LEFT and this check can read 0 while content is cut - also verify the left edge per references/rtl-hebrew.md.
3. Fixed chrome collision check on the smallest viewport - logos, nav, and readouts must not overlap; hide or collapse elements below 600px rather than letting them collide.
4. Fluid type via clamp(); grids collapse to one column below ~900px; wide content scrolls inside its own container, never the page body.
5. Screenshot every major section at phone + desktop and actually look at them. scripts/verify.mjs saves them in scroll order with the section name, plus a mid-scrub frame for any pinned scene taller than 1.5 viewports - a sticky scene judged only at its top edge is not judged at all. Reading the filenames is not reviewing: open the images.
6. Accessibility floor: sr-only text behind kinetic/canvas headlines (decorative layers get aria-hidden), visible focus styles, contrast floors (4.5:1 body, 3:1 large display type), alt text on every image. The prefers-reduced-motion path from STEP 2 is part of this floor.
7. Headings must read as text, not just render as pixels. Split or masked type (per-word masks, per-letter staggers) can look perfect while its innerText is missing every space - screenshots cannot catch it. Read the heading text dump from scripts/verify.mjs and confirm the words are actually separated. Fix by emitting real space text nodes between the spans, never by faking the gap with padding or margin.
8. In-page anchors must clear fixed chrome. Any site with a sticky nav and href="#section" links needs scroll-padding-top on html greater than the nav height, or the anchor target lands underneath it. scripts/verify.mjs checks this.

STEP 4 - Verify and ship

• Dev contract in every build: ?jump=<scrollY> lands pre-scrolled and settled; window.__ready = true fires only when truly ready. Screenshot via puppeteer-core + system Chrome (host preview panes throttle hidden tabs).
• Jank test: rAF deltas, judge p95/max (target max < 50ms), never average fps. A classic spike source: reading pixels back from a GPU-backed canvas every frame - sample from the decoded source image instead.
• OG / social card - MANDATORY, never optional. Every site ships with a social card and the full tag set. A link with no preview looks broken the moment it is pasted into LinkedIn, WhatsApp, Slack or iMessage, which is where these sites actually get shared. Screenshot the real hero at 1200x630, < 300 KB (scripts/capture-og.mjs), then emit the complete og: + twitter: set with absolute production URLs plus rel="canonical" - the exact required list is in references/asset-pipeline.md. Keep the card JPEG/PNG even on an all-WebP site: WhatsApp and LinkedIn render WebP previews unreliably. scripts/verify.mjs FAILS the build if a required tag is missing or the og:image does not resolve - do not ship around it.
• Defects found in verification: fix them in parallel passes, one focused pass per defect, each with a precise brief: the defect, the viewport, the programmatic check that proves it, the acceptance bar, and screenshot proof after the fix. Then re-run the full sweep: a fix that breaks another viewport is not a fix.
• Security gate before any deploy: run the exposure audit (secrets, PII, personal emails, EXIF, local paths) and only publish on PASS.
• Deploy a lean build dir to the user's Vercel; report the production URL and the audit verdict table.