Promptory Web Build
Three tools, one stack, each with one job:
| Tool | Role | Rule of thumb |
|---|---|---|
| Lenis | Scroll engine — smooth, inertial scrolling on top of native scroll | Installed once, globally. Never per-section. |
| GSAP (+ ScrollTrigger) | Animation engine — custom timelines, scroll-driven animation, pinning | Anything bespoke to this site's design. |
| React Bits | Ready-made animated components (text, backgrounds, cursors, cards, buttons) | Reach for it first when a catalog component already does the effect. |
They share one animation loop: GSAP's ticker drives Lenis, and ScrollTrigger reads Lenis's scroll. Getting that wiring right is the single most important thing in this skill (§3).
Scope: real-time web/DOM only. For video rendering (Remotion, reels), this skill does not apply.
0. Golden rule — don't redesign
Implement the design and the effects the user asked for. Do not change layout, colors, fonts, spacing or copy on your own, and do not add extra sections or "bonus" effects nobody requested. If an effect or fix would clearly improve something, suggest it in one line and wait for a yes. Motion and quality checks should serve the existing design, not replace it.
0.5 Intake questionnaire — FIRST step on every new website request
Before writing any code for a new site, run the intake questionnaire in references/intake-questionnaire.md:
- Read the request and skip anything already answered.
- Ask the remaining questions in up to 3 short rounds (project → motion → delivery). Use Claude Code's
AskUserQuestiontool when available (clickable options + automatic "Other" free-text box); otherwise print each round as one code block with lettered options and an empty "✎ أخرى" line on every question. - Show the Project Brief in one code block and wait for the go-ahead.
- Then build, following the answers exactly.
If the user says "ابدأ على طول" / "skip", use the ⭐ defaults and state them in the Brief. For small edits to an existing site, skip the questionnaire unless the request is ambiguous.
The brief must record: language and direction (Arabic/RTL, English/LTR, or both), the accessibility target (default WCAG 2.2 AA), the forms and their backend, and the analytics tool if any.
0.6 Visual references — Prompt Motion
https://prompt-motion.com/ is the visual library for motion direction (kinetic type, product UI, particles, shapes, charts…, each with the prompt behind it). Use it only when the user asks for inspiration, picks "needs a proposal" / "bold motion" in the questionnaire, or shares a link from it. Borrow the motion idea, rebuild it with GSAP / Lenis / React Bits, keep the client's design. Workflow, category→component map and the motion-spec template: references/visual-references.md.
0.7 Quality bar — check before showing anything
Scan the build for the generic-output tells (default indigo accent, emoji icons, invented metrics, lorem ipsum, stock template sections). Fix what is in your own code; suggest a one-line fix for anything in the client's design. Full list: references/quality-bar.md.
0.8 Design direction — every site looks different
When the client has no design of their own, choose a direction before writing code. Read references/design-styles.md and:
- Shortlist three directions from the Fit guide for the brief's industry and audience.
- Skip any direction used in the last three sites in this chat or project (Style Log).
- Write one line in the Project Brief:
Direction: <name> — <why>, with one alternative. - Build with that direction's signature choices, then run the Variety check: at least four of six axes must differ from the previous site.
The directions are references for structure and feel. Never copy a reference's brand, photos, copy or exact layout. If the client supplies a design, follow it and skip this step (§0 golden rule).
0.9 Distinctive visual design (when the brief leaves it open)
Source: anthropics/skills, skill frontend-design (Apache-2.0, see its LICENSE.txt). Applies only where the brief leaves the visual direction open. §0 wins: follow the client's design and the brief's own words, including when the brief asks for one of the looks listed below.
- Identify the subject first: product, audience, primary job. If the brief does not say, propose one and confirm. Industry and materials are where distinctive choices come from.
- Hero opens with the most characteristic thing in the subject's world (headline, image, live demo, or interaction). Avoid the default of a big number, a small label, and a gradient accent unless it is clearly the best option.
- Type: one family, or two that are clearly distinct. Set a clear type scale. In headlines, the type treatment is part of the design.
- Line length under 80 characters. Serif body text needs slightly more line-height than sans.
- Avoid typographic tells: one italic or colored word in a headline, all-caps labels, and labels above headings that add nothing.
- Numbered markers (01 / 02 / 03) only when the content is really a sequence.
- Motion: one orchestrated moment (page load or one reveal). No fade-and-slide on every section, no hover transition on every card. Motion that answers a user action (opening, expanding, confirming) is fine.
- Plan before code: 4–6 named hex colors, type roles, a layout concept (ASCII wireframe allowed), and principles. Review the plan against the brief. If a part reads like the generic default for any similar page, revise it and say what changed.
- Default looks to avoid unless the brief asks for them: cream background with terracotta accent; near-black with acid-green or vermilion accent; broadsheet with hairline rules and zero radius; identical rounded SaaS cards with one radius and one grey shadow; ALL-CAPS eyebrow above every heading; middle-dot meta strings ('A · B · C'); 'WORD — fragment' labels; #0B0B0B or #111 standing in for black; monospace for small labels; '→' on every link.
- Spend boldness in one place. Keep everything around it quiet. Cut decoration that does not serve the brief.
- Quality floor: responsive to mobile, visible focus, reduced motion respected, accessible contrast.
- Watch CSS selector specificity, especially padding and margin between sections, where rules cancel each other.
- Copy: plain words for the end user, active voice, sentence case. Keep one verb through a flow ("Publish" leads to "Published"). Errors say what happened and how to fix it, without apology. Empty states invite the next action.
1. Decision flow — which tool for which request
- Arabic, bilingual or RTL site → read
references/rtl-arabic.mdbefore writing any layout. Direction is structural; retrofitting it is expensive. - Smooth scroll anywhere on the site → Lenis (global provider, §3). Do it once at project setup when any scroll animation exists.
- Is there a React Bits component that already does the effect? → check
references/react-bits-catalog.md→ install it (§4). Typical hits: split/blur/scramble text, scroll-reveal text, animated backgrounds (aurora, particles, grids, shaders), custom cursors, magnet/tilt cards, marquees, galleries, dock/menus, animated buttons/counters. - Effect is specific to this design (hero intro sequence, pinned storytelling section, horizontal scroll section, synced multi-element reveals) → GSAP timeline / ScrollTrigger (§5, full detail in
references/gsap.md). - Project is NOT React (plain HTML/vanilla) → React Bits is not available; use Lenis + GSAP only (
assets/vanilla-setup.js). - Any form, list, booking or data-driven section →
references/forms-and-states.md(labels, errors, five states). - Choosing a third-party service (fonts, form backend, analytics, hosting, images) →
references/free-services.md, then verify current limits. - New site with no client design → pick a direction first (§0.8,
references/design-styles.md).
2. Installation
npm install gsap @gsap/react lenis
@gsap/react→ only for React projects (providesuseGSAP).lenis/reactandlenis/snapship insidelenis— no extra packages.- All GSAP plugins (ScrollTrigger, SplitText, Flip, ScrollSmoother, Draggable…) ship inside
gsap. - React Bits components are added individually via CLI (§4); some pull in their own deps (
motion,three,ogl,matter-js…) — the CLI installs them, but check the Deps column in the catalog before choosing, to avoid bloating the bundle.
Never use GSAP's ScrollSmoother together with Lenis — they are two competing smooth-scroll engines. Lenis is the scroll engine in this stack.
3. Wiring Lenis + GSAP + ScrollTrigger (do this exactly)
React / Next.js
Copy assets/SmoothScroll.jsx into the project (e.g. components/SmoothScroll.jsx) and wrap the app once:
// app/layout.jsx (Next.js App Router)
import SmoothScroll from '@/components/SmoothScroll';
import ScrollToTopOnRoute from '@/components/ScrollToTopOnRoute';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<SmoothScroll>
<ScrollToTopOnRoute />
{children}
</SmoothScroll>
</body>
</html>
);
}
For Arabic, set lang and dir from the locale on <html> (see references/rtl-arabic.md §1).
For Vite/React, wrap <App /> in main.jsx the same way and skip ScrollToTopOnRoute (it uses next/navigation).
What the provider does — and why each line matters:
<ReactLenis root options={{ autoRaf: false }}>→ one global instance on<html>;autoRaf: falsebecause GSAP will drive it.lenis.on('scroll', ScrollTrigger.update)→ ScrollTrigger recalculates on every smooth-scroll frame. Missing this = animations fire late/at wrong positions.gsap.ticker.add(t => lenis.raf(t * 1000))→ one shared loop (GSAP time is seconds, Lenis wants ms).gsap.ticker.lagSmoothing(0)→ no stutter catching up after a tab switch.ScrollTrigger.refresh()after fonts and load → trigger positions match final layout.
Vanilla HTML/JS
Use assets/vanilla-setup.js as the entry module, import lenis from it where needed.
4. React Bits — picking and installing components
- Find the component in
references/react-bits-catalog.md(grouped: Text Animations, Animations, Components, Micro, Backgrounds — name, what it does, deps). - Pick the flavor matching the project:
JSorTS, thenCSSorTW(Tailwind). - Install:
For thenpx shadcn@latest add @react-bits/SplitText-TS-TW@react-bits/shorthand, the project'scomponents.jsonmust contain:No{ "registries": { "@react-bits": "https://reactbits.dev/r/{name}.json" } }components.json/ not a shadcn project? Use the direct URL instead:npx shadcn@latest add https://reactbits.dev/r/SplitText-TS-TW.json # or npx jsrepo@latest add https://reactbits.dev/r/SplitText-TS-TW - Open the installed file and read its props before using it — every component is configurable (colors, speed, delay, easing, triggers). Set props to match the site's existing design tokens (colors, fonts) rather than leaving demo defaults.
- If the user wants the agent workflow:
npx shadcn@latest mcp init --client claudeconnects Claude Code to the registry via MCP.
Integration notes:
- React Bits components that animate on scroll (ScrollReveal, ScrollFloat, AnimatedContent, SplitText…) use GSAP ScrollTrigger or IntersectionObserver internally → they work with Lenis automatically as long as §3 is in place.
- Components are client components (
'use client'). In Next.js, render them inside client components or pages that allow it. - WebGL/shader backgrounds (deps
three,ogl,vgpu) are heavy: max one or two per page, lazy-load below-the-fold ones (next/dynamicwithssr: falseorReact.lazy), and give them a fixed-size container. Pause them when off-screen or when the tab is hidden. - Don't stack two cursor effects or two backgrounds in the same viewport.
- Check each component for a pause control if it loops for more than 5 seconds (see
references/accessibility-motion.md§5). - License: React Bits is MIT + Commons Clause — free to use inside any client website (including paid client work), but the components themselves must not be resold or redistributed as a pack/template. Never paste React Bits source into this skill or a shared library; always install from the registry.
5. GSAP essentials (custom animation)
Always in React via useGSAP with a scope — never raw useEffect:
'use client';
import { useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';
gsap.registerPlugin(ScrollTrigger, useGSAP);
export default function Story() {
const root = useRef(null);
useGSAP(() => {
const tl = gsap.timeline({
scrollTrigger: { trigger: root.current, start: 'top top', end: '+=150%', scrub: 1, pin: true },
});
tl.from('.line', { yPercent: 100, autoAlpha: 0, stagger: 0.15 })
.to('.image', { scale: 1.15 }, '<');
}, { scope: root });
return <section ref={root}>…</section>;
}
Core patterns (details + responsive matchMedia, batching, FOUC, checklist in references/gsap.md):
- Timelines for anything with >1 element;
ScrollTrigger.batch()for repeated cards. scrubfor scroll-linked motion (with Lenis,scrub: trueis already smooth;scrub: 1adds extra lag).pin: trueworks with Lenis on native scroll — nopinTypehacks needed when Lenis usesroot.- Horizontal scroll section: pin the wrapper, tween the track's
xto-(track.scrollWidth - innerWidth),scrub: true,invalidateOnRefresh: true. In RTL, reverse the direction (seereferences/rtl-arabic.md§6). - Wrap decorative blocks in
gsap.matchMedia()so reduced-motion users get the substitute (references/accessibility-motion.md§4).
6. Lenis essentials (detail in references/lenis.md)
- Modal / mobile menu open →
lenis.stop(); close →lenis.start()(get instance withuseLenis()). - Any inner scrollable element (dropdown list, modal body, chat, code block) → add
data-lenis-prevent. - Nav links →
anchors: true(already in the provider) orlenis.scrollTo('#id', { offset: -headerHeight }). The offset keeps the target out from under a sticky header. - Feel:
lerp0.08 = luxurious/heavy, 0.1 = default, 0.12–0.15 = snappy. Pick one per site and keep it. - Section snapping →
lenis/snap(CSSscroll-snapdoes NOT work with Lenis). - Leave
syncTouchoff — native touch scrolling already feels right on phones. - Keep
respectReducedMotion: true(the default) and do not override it.
7. Performance & accessibility (non-negotiable)
Full rules, durations, contrast and touch-target tables: references/accessibility-motion.md. The short version:
- Target WCAG 2.2 AA. Contrast 4.5:1 for body text, 3:1 for UI and focus rings. Touch targets at least 24×24 px.
- Animate only
transform/opacity(x,y,scale,rotation,autoAlpha). - One Lenis instance, one loop. No
autoRaf+ ticker double-driving. - Lazy-load heavy WebGL React Bits backgrounds; cap at one or two per page; pause when off-screen.
- Motion durations: 50–150 ms for feedback, 200–300 ms for entering UI, under 500 ms for any non-navigation microinteraction. Shorter on mobile.
- No flashing above 3 times per second. Any loop longer than 5 seconds that moves, blinks or scrolls needs a pause control.
- Reduced motion: keep Lenis's default; wrap decorative GSAP in
gsap.matchMedia().add('(prefers-reduced-motion: no-preference)', …)and give reduced-motion users a substitute. Content stays visible in both modes. - Focus: never remove the outline without a visible replacement; use
:focus-visible. Modals trap focus and return it on close. - Call
ScrollTrigger.refresh()after layout changes (images, accordions, tabs, injected content). - Test on a real phone and in Safari (Lenis is capped at 60fps there).
7.5 Forms and states
Every form, booking flow, and data-driven list needs labels wired to errors and all five states (default, loading, empty, error, success). Details, the ARIA pattern, and backend notes: references/forms-and-states.md.
7.6 React and Next.js performance (Vercel rules)
Source: vercel-labs/agent-skills, skill react-best-practices (author vercel, v1.0.0, MIT). 72 rules in 8 categories, ordered by impact. Apply when writing, reviewing, or refactoring React/Next.js code. Work from the top category down.
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL | async- |
| 2 | Bundle Size Optimization | CRITICAL | bundle- |
| 3 | Server-Side Performance | HIGH | server- |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | client- |
| 5 | Re-render Optimization | MEDIUM | rerender- |
| 6 | Rendering Performance | MEDIUM | rendering- |
| 7 | JavaScript Performance | LOW-MEDIUM | js- |
| 8 | Advanced Patterns | LOW | advanced- |
Default rules to apply:
- Waterfalls:
async-parallel(Promise.all for independent work),async-defer-await(await only in the branch that uses the value),async-suspense-boundaries(stream with Suspense). - Bundle:
bundle-barrel-imports(import directly, no barrel files),bundle-dynamic-imports(next/dynamic for heavy components),bundle-defer-third-party(load analytics after hydration). - Server:
server-cache-react(React.cache for per-request dedup),server-serialization(pass only needed fields to client components),server-parallel-fetching,server-after-nonblocking(after() for non-blocking work). - Client:
client-swr-dedup,client-passive-event-listenersfor scroll. - Re-render:
rerender-derived-state-no-effect(derive during render, not in effects),rerender-functional-setstate,rerender-no-inline-components,rerender-transitions,rerender-lazy-state-init. - Rendering:
rendering-content-visibility(long lists),rendering-conditional-render(ternary, not && for conditionals),rendering-hoist-jsx(static JSX outside components). - JavaScript:
js-index-mapsandjs-set-map-lookupsfor repeated lookups,js-tosorted-immutable.
Full before/after code lives in the upstream rules/<name>.md files; fetch the one you need before applying it. These rules never override §0 (golden rule) or the accessibility and motion rules: if a performance rule would change the design or break reduced motion, suggest it in one line and wait.
7.7 Postgres and Supabase (database work)
Source: supabase/agent-skills, skill supabase-postgres-best-practices (author supabase, v1.1.1, MIT). Load before any change to a Postgres database: tables, column types, migrations, RLS policies, indexes, functions, triggers, queues, or slow queries. The rules apply to any Postgres, not only Supabase.
Categories, in priority order: Query Performance (query-, CRITICAL), Connection Management (conn-, CRITICAL), Security & RLS (security-, CRITICAL), Schema Design (schema-, HIGH), Concurrency & Locking (lock-, MEDIUM-HIGH), Data Access Patterns (data-, MEDIUM), Monitoring (monitor-, LOW-MEDIUM), Advanced Features (advanced-, LOW).
Default rules to apply:
- Schema:
schema-data-types(choose proper types),schema-primary-keys(pick a PK strategy),schema-foreign-key-indexes(index every FK column),schema-lowercase-identifiers,schema-constraints. - Security:
security-rls-basics(enable RLS on every multi-tenant table),security-rls-performance(write policies that use indexes),security-privileges. - Queries:
query-missing-indexes,query-composite-indexes,query-partial-indexes,query-covering-indexes. - Connections:
conn-pooling(pool for all apps),conn-limits,conn-prepared-statements. - Data access:
data-pagination(cursor pagination, not OFFSET),data-n-plus-one,data-batch-inserts,data-upsert. - Locking:
lock-short-transactions,lock-skip-locked,lock-deadlock-prevention. - Diagnosis:
monitor-explain-analyze,monitor-pg-stat-statements.
Full SQL before/after examples live in the upstream references/<rule>.md files; fetch the one you need before applying it.
Safety: destructive or irreversible SQL (DROP, TRUNCATE, type change on live data, mass UPDATE or DELETE) waits for an explicit yes. Show the statement and its effect first.
7.8 Testing local web apps (Playwright)
Source: anthropics/skills, skill webapp-testing (license in its LICENSE.txt). Use to verify frontend behavior, debug UI, capture screenshots, or read browser console logs of a local web app.
- Write native Python Playwright scripts with
sync_playwright()and headless chromium. - Static HTML: read the file for selectors, then script. Dynamic app: check whether the server is running. If not, run
python scripts/with_server.py --helpand let it manage server lifecycle (one or several servers). - Always
page.wait_for_load_state('networkidle')before inspecting the DOM. Inspecting earlier gives wrong selectors on dynamic apps. - Reconnaissance first: screenshot or
page.content(), pick selectors (text=,role=, IDs), then act. - Run helper scripts as black boxes. Read their source only if
--helpand a plain run fail. - Close the browser when done. Patterns:
examples/element_discovery.py,examples/static_html_automation.py,examples/console_logging.py.
The upstream scripts/ and examples/ files are not bundled here; fetch them from the source repo when needed. Test runs use the user's local app only; never run them against a production URL.
8. Pre-ship checklist
- Intake questionnaire done and Project Brief approved before coding (language, direction, accessibility target, forms backend, analytics)
- Arabic/RTL handled if selected:
lang+diron<html>, logical CSS properties,dirSignfor horizontal GSAP moves, word-level text splitting, real Arabic copy (references/rtl-arabic.md) -
SmoothScrollprovider mounted once at root; CSSlenis/dist/lenis.cssimported -
autoRaf: false+ GSAP ticker driving Lenis +lenis.on('scroll', ScrollTrigger.update) - No ScrollSmoother, no second smooth-scroll lib, no CSS
scroll-behavior: smoothonhtml - Every GSAP block in React uses
useGSAPwithscope;'use client'where needed - Inner scrollable areas have
data-lenis-prevent; modals calllenis.stop()/start()and trap focus - React Bits props tuned to the site's colors/fonts; heavy backgrounds lazy-loaded and paused off-screen
- WCAG 2.2 AA: contrast, focus ring, touch targets, alt text, heading order, keyboard-only pass
- Reduced motion handled for all transform-based motion; no flashing above 3/s; loops over 5s have pause
- Forms labeled, errors linked with
aria-describedby, five states built (references/forms-and-states.md) - Quality bar passed: no default indigo, no emoji icons, no invented numbers, no lorem ipsum (
references/quality-bar.md) - Third-party services chosen from
references/free-services.mdwith current limits verified and noted in the brief - Design direction chosen from
references/design-styles.md(if no client design) and differs from the last three sites on at least four axes; direction named in the Brief - Nothing redesigned or added beyond what was requested (§0)
- Visual choices follow the brief, not the defaults listed in §0.9; design plan reviewed before code
- React/Next.js code checked against §7.6: no request waterfalls, no barrel imports, no state derived in effects
- Database changes checked against §7.7: RLS on multi-tenant tables, FK indexes, cursor pagination, no unconfirmed destructive SQL
- Local web app tested with §7.8 (Playwright, networkidle wait, screenshot of result)
- Route changes reset scroll (Next.js
ScrollToTopOnRoute) - Tested on mobile + Safari; reduced-motion and keyboard-only paths checked
Files in this skill
references/intake-questionnaire.md— the pre-build questionnaire: rules, interactive + code-block formats, question bank, Project Brief templatereferences/visual-references.md— Prompt Motion as a motion reference library: when to use it, browsing, video→web implementation map, motion-spec templatereferences/rtl-arabic.md— Arabic and RTL build guide: document setup, logical properties, Tailwind utilities, bidi, mirroring rules, GSAP in RTL, Arabic typography, formsreferences/accessibility-motion.md— WCAG 2.2 AA target, motion durations and easing, reduced motion, flashing and looping rules, contrast, touch targets, focusreferences/forms-and-states.md— form wiring (labels, errors, focus), validation rules, backends, and the five required statesreferences/quality-bar.md— checks against generic output (default accent, emoji icons, invented metrics, filler copy) and where character should come fromreferences/free-services.md— free and low-cost fonts, form backends, analytics, hosting/CDN, image services, with a verify-before-recommending rulereferences/gsap.md— full GSAP guide (React integration, timelines, ScrollTrigger, matchMedia, FOUC, performance, defaults)references/lenis.md— full Lenis guide (settings table, methods, nested scroll, snap, troubleshooting)references/react-bits-catalog.md— all 218 React Bits components by category with description and depsassets/SmoothScroll.jsx— React/Next.js global Lenis + GSAP providerassets/ScrollToTopOnRoute.jsx— Next.js route-change scroll resetreferences/design-styles.md— 13 distinct design directions with fit guide, variety axes, style log and variety checkassets/vanilla-setup.js— non-React setup