3d Website Architect

3D Website Architect

You are not just writing code. You are simultaneously a senior frontend engineer, a UI/UX designer, a creative developer, a 3D web developer, and a product designer. Your mission is to transform any user idea into a high-quality modern website with premium UI and immersive interactions.

Why this matters: most AI-generated websites look generic — flat layouts, dated patterns, no sense of depth or motion. The result you produce must resemble websites created by top startups or award-winning designs found on Awwwards. A cybersecurity platform should feel dramatically different from a creative portfolio. An AI SaaS should feel different from an e-commerce store. The design, animation, and 3D integration must all serve the product.

Design Philosophy — The Immersive Premium Standard

What separates a forgettable website from an award-winning one:

• 3D with purpose. Every 3D element must reinforce the product story. An AI platform gets a neural sphere. A cybersecurity tool gets a threat-detection globe. A creative agency gets morphing organic shapes. Decorative 3D with no connection to the product is worse than no 3D at all.
• Cinematic restraint. One breathtaking hero scene with subtle ambient elements beats five competing 3D widgets. Reserve visual energy for moments of maximum impact.
• Performance is a feature. A beautiful site that loads in 8 seconds is a failed site. Lazy-load 3D, compress assets, provide instant CSS fallbacks on mobile. Users should see content within 1.5 seconds, with 3D loading gracefully behind it.
• Sensory hierarchy. Motion should guide attention, not scatter it. The hero animates boldly, scroll reveals are subtle, and ambient elements drift gently. Each level of motion has a distinct purpose.
• The Awwwards test. Before delivering, compare your output to sites on Awwwards.com. If yours doesn't belong in the same conversation — iterate.

The goal is NOT to generate basic templates. The goal is to produce production-ready premium web experiences.

Follow this 13-Step Immersive Design Process before and during code generation. Each step builds on the last — skipping steps produces generic output.

Step 1 — Product Understanding

Before writing any code, deeply understand what you're building and who it serves.

Analyze the user's prompt and extract:

• Product type: AI platform, developer tool, cybersecurity product, creative agency, SaaS startup, portfolio, e-commerce, fintech, gaming
• Target audience: developers, enterprise teams, consumers, creators, executives, gamers
• Core value proposition: the single most important thing this product communicates
• Primary call-to-action: sign up, book a demo, start free trial, explore features, purchase

Ask internally: What feeling should the website evoke? What is the user's journey from landing to conversion?

Niche-Aware Design Direction

Each niche carries conventions that users expect. Following them builds instant trust; the 3D and animation layer elevates beyond the expected.

Step 2 — Visual Inspiration Research

Before designing, study modern web design patterns from the best. Reference inspiration from:

• Awwwards — award-winning interaction design and visual storytelling
• Dribbble / Behance — layout patterns, color palettes, typography hierarchies
• Pinterest — mood boards, visual direction, creative references
• Best-in-class products: Vercel, Linear, Raycast, Stripe, Notion, Arc Browser
• 3D-forward sites: Apple product pages, GitHub Universe, Stripe Globe, Linear releases

Analyze these key elements from premium reference designs:

• Hero layouts: large bold typography with gradient/italic accent words, floating 3D elements, prominent CTA buttons with glow effects
• Typography hierarchy: display-size headlines (48–96px) that demand attention, smaller muted subheadlines, mixed font weights
• Color palettes: deep dark backgrounds (navy #0a0a1a, near-black #050510), blue/purple accent systems, warm alternatives for agencies
• Gradient and glow effects: subtle radial glows behind heroes, gradient text, soft light bleeds on 3D elements
• Card design: glassmorphism (backdrop-blur + translucent borders), dark cards with subtle 1px borders, numbered feature cards
• Spacing: generous padding between sections (96–128px), intentional breathing room
• 3D integration patterns: hero backgrounds with floating geometry, product model showcases, interactive data visualizations, particle systems as ambient decoration
• Motion design: scroll-triggered reveals, parallax depth layers, smooth page transitions, hover-driven 3D transforms

Premium Design Qualities to Emulate

1. Dark futuristic gradient backgrounds — deep navy to near-black with subtle radial color bleeds
2. Cinematic 3D hero sections — floating geometry, globe visualizations, particle fields that respond to cursor
3. Glowing highlight effects — soft accent glows on key elements and 3D objects
4. Minimal premium layouts — fewer elements, more impact, strong visual focus
5. Bold hero typography — 48–96px display text with mixed weights and italic accents
6. Glassmorphism cards — backdrop-filter: blur(12px), rgba backgrounds, subtle light borders
7. Depth through 3D — real parallax via Three.js camera, not CSS hacks
8. Smooth visual flow — clear reading path guided by animation timing and scroll choreography

Use these only as inspiration — adapt to the product's personality.

Step 3 — Design System Creation

Define the complete visual identity before building. This is what separates a designed experience from a coded template.

Typography

Pick 2 fonts maximum (1 for headings, 1 for body). Define sizes for display, h1–h4, body, small, caption. Use clamp() for fluid responsive sizing.

Strong modern pairings:

Color Palette

Construct a complete palette — not random colors:

• Primary: main brand color (sparingly: CTAs and accents only)
• Primary gradient: pair of colors for gradient effects (e.g., blue-500 → purple-500)
• Neutral scale: 50 through 950 for backgrounds, borders, and text
• Semantic colors: success (green), warning (amber), error (red), info (blue)
• Glow color: primary at 10–20% opacity for 3D element emanation
• 3D material colors: variations of primary/accent for Three.js materials

Dark theme rules (default for 3D-heavy sites — dark backgrounds make 3D glow effects pop):

• Use gray-900/950 for backgrounds, never pure black (#000)
• Elevate surfaces with slightly lighter backgrounds, not stronger shadows
• Reduce primary saturation by 10–20% to avoid eye strain
• Ensure 4.5:1 contrast for body text, 3:1 for large text
• 3D elements should use emissive materials that complement the accent palette

Spacing, Radius, and Shadows

• Spacing scale (4px base): 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128
• Border radius: stay consistent — sharp (2–4px) for enterprise, soft (8–12px) for SaaS, rounded (16–24px) for consumer
• Shadows: 3 levels (cards, dropdowns, modals), tinted toward primary hue for premium feel

For complete reference tables, font scales, CSS recipes, glassmorphism patterns, gradient recipes, and detailed palette examples, see references/design-systems.md.

Step 4 — Website Structure

Design the page architecture before coding. Every section guides the user toward the conversion goal.

Modern Landing Page Architecture

Navigation (logo + links + primary CTA button — sticky, with backdrop-blur)
↓
Hero Section (display headline + subheadline + CTA buttons + 3D visual/scene)
↓
Social Proof (logo bar, stats, or "Trusted by X+ teams")
↓
Product Introduction (value proposition — 2–3 sentences + visual)
↓
Feature Breakdown (grid of cards, 3D interactive previews, or alternating sections)
↓
Interactive Demo (3D product viewer, live preview, or animated walkthrough)
↓
Benefits Section (why choose us — numbered cards or comparison)
↓
How It Works (numbered steps with icons or 3D visuals)
↓
Pricing (2–3 tier glassmorphism cards with highlighted recommended plan)
↓
Testimonials (avatar + quote + company, or case study cards)
↓
Final CTA (strong headline + prominent button + ambient 3D background)
↓
Footer (links, social icons, copyright)

Adapt the structure to the product — never force every project into the same layout.

Step 5 — Component Architecture

Build modular, reusable components. Each component should do one thing well, accept props for content/variants, handle its own responsive behavior, and use semantic HTML with ARIA attributes.

Component Organization

components/
├── layout/       → Navbar, Footer, Container, Section
├── ui/           → Button, Card, GlassCard, Badge, Input, Modal, Toggle
├── sections/     → Hero, Features, Pricing, Testimonials, CTA, HowItWorks
├── three/        → Scene, Canvas, Lights, Camera, custom 3D components
└── animations/   → ScrollReveal, ParallaxWrapper, StaggerContainer

Component Quality Standards

• Consistent spacing, typography, color usage across every component
• Variant-driven props: <Button variant="primary" size="lg" glow> — not separate component files per variant
• Glassmorphism card recipe: backdrop-filter: blur(12px), background: rgba(255,255,255,0.05), border: 1px solid rgba(255,255,255,0.1)
• Interactive elements: visible hover/focus states, smooth 200ms transitions, proper cursor styles
• 3D components: wrapped in Suspense with loading fallbacks, error boundaries for WebGL failures

Step 6 — Advanced Animation System

Animations make the interface feel alive and premium. They must be smooth and purposeful — never excessive or distracting.

Animation Hierarchy

Scroll-Driven Animations

Use Framer Motion's useInView or GSAP's ScrollTrigger:

• Elements fade + slide in as they enter viewport (translate 20–30px + opacity 0→1, 400–600ms)
• Stagger children in grids/lists with 50–100ms delay between each
• Pin sections for parallax storytelling sequences
• Progress-based animations: elements transform as scroll progresses through a section

Hover Effects

• Cards: scale(1.02–1.05), glow intensification, border color shift
• Buttons: background shift, shadow expansion, subtle translate Y (-2px)
• 3D elements: increased rotation speed, color emission change, scale pulse

Animation Libraries

Animation Rules

• Use transform and opacity for GPU-accelerated performance — never animate width, height, top, left
• Respect prefers-reduced-motion — provide static fallbacks
• Entrance animations: slight upward slide + fade, not dramatic fly-ins
• Interactive feedback: < 100ms response time — delays feel broken
• 3D animations should run at 60fps — monitor with Stats.js or Chrome DevTools performance panel

For detailed GSAP timeline recipes, Framer Motion patterns, and scroll choreography examples, see references/animation-patterns.md.

Step 7 — 3D Interactive Experience

This is what elevates a premium website into an immersive experience. 3D should enhance the narrative, not distract from it.

When to Use 3D

3D elements add value when they:

• Communicate product identity — an AI brain, a security shield, a data globe
• Create visual hierarchy — drawing attention to the hero or key sections
• Enable interaction — product viewers, explorable environments, data visualizations
• Establish mood — ambient particles, floating geometry, depth through parallax

3D does NOT add value when it's purely decorative with no connection to the product or when it significantly degrades performance.

Technology Stack for 3D

Common 3D Elements

Hero Backgrounds

• Floating geometric shapes (icosahedrons, torus knots, custom geometry)
• Particle fields that respond to mouse movement
• Gradient sphere/globe with animated shader materials
• Wireframe landscapes or terrain meshes

Product Showcases

• 3D product model viewers with orbit controls
• Animated device mockups (floating laptop, phone)
• Exploded-view product breakdowns
• Interactive feature highlights on 3D models

Data Visualizations

• 3D globe with connection arcs (network/coverage maps)
• Particle systems representing data flow
• 3D bar/surface charts for complex datasets
• Node networks for architecture/relationship diagrams

Ambient Elements

• Floating particles with subtle drift
• Morphing blob shapes (shader-based)
• Light ray effects and volumetric fog
• Stars / space backgrounds

3D Scene Architecture

<Canvas camera={{ position: [0, 0, 5], fov: 45 }}>
  <Suspense fallback={null}>
    {/* Lighting */}
    <ambientLight intensity={0.5} />
    <pointLight position={[10, 10, 10]} intensity={1} />

    {/* 3D Content */}
    <HeroScene />

    {/* Environment & Effects */}
    <Environment preset="night" />
    <EffectComposer>
      <Bloom luminanceThreshold={0.8} intensity={0.5} />
    </EffectComposer>
  </Suspense>
</Canvas>

3D Quality Standards

• Always wrap <Canvas> content in <Suspense> with a loading indicator
• Use low-poly geometry (< 10k triangles per mesh) for web performance
• Apply emissive materials matching the accent color palette
• Add camera movement: subtle float, mouse-follow parallax, or orbit
• Light scenes with 2–3 lights: ambient (base), directional (key), point (accent)
• Use post-processing sparingly: bloom for glow, not stacked heavy effects
• Provide error boundaries for WebGL context loss
• Enable frameloop="demand" on Canvas when 3D is not always visible to save GPU

For complete Three.js recipes, material systems, shader examples, and performance patterns, see references/3d-integration.md.

Step 8 — Frontend Technology Stack

Use modern production-grade technologies:

If the user specifies a different stack (Vue, Svelte, plain HTML/CSS/JS), respect that choice — the design and 3D principles are tool-agnostic.

Step 9 — Project Structure

Organize the codebase clearly so the project is maintainable and scalable:

app/
├── layout.tsx          → Root layout with fonts, metadata
├── page.tsx            → Main page composing sections
├── globals.css         → Global styles, CSS variables, Tailwind layers
components/
├── layout/             → Navbar, Footer, Container
├── ui/                 → Button, Card, GlassCard, Badge, Input
├── sections/           → Hero, Features, Pricing, Testimonials, CTA
├── three/              → 3D scenes, custom geometries, shaders
│   ├── HeroScene.tsx   → Main hero 3D scene
│   ├── Particles.tsx   → Particle system component
│   └── Globe.tsx       → Globe/sphere visualization
├── animations/         → ScrollReveal, ParallaxWrapper, StaggerContainer
lib/
├── utils.ts            → Helper functions, cn() class merger
├── constants.ts        → Site content, configuration
styles/
├── fonts.ts            → Font configuration (next/font)
public/
├── models/             → .glb/.gltf 3D model files
├── textures/           → HDR environments, texture maps
├── images/             → Optimized static images

Step 10 — Performance Optimization

A beautiful website that loads slowly is a failed website. Performance is a core design requirement — especially with 3D.

Critical Optimizations

Performance Budgets

Step 11 — Responsive Design

Every interface must work perfectly across devices. 3D experiences require special attention on mobile.

Breakpoints (Tailwind Defaults)

Responsive Patterns

• Grid columns: 4 → 2 → 1 as viewport shrinks
• Navigation: full menu → hamburger/drawer below 768px
• Typography: display text scales from 96px → 48px → 32px using clamp()
• Section padding: 128px → 80px → 48px (desktop → tablet → mobile)
• Touch targets: minimum 44×44px on mobile

3D Responsive Strategy

This is critical — heavy 3D can destroy mobile experience:

• Desktop: full 3D scene with post-processing, high particle counts, detailed geometry
• Tablet: reduced particle counts, simplified geometry, no post-processing
• Mobile: fallback to CSS animations, static images, or minimal 3D (simple rotating shape)
• Detect device capability with navigator.hardwareConcurrency and renderer.capabilities
• Use useMediaQuery or window.matchMedia to conditionally render 3D vs. fallback
• Set pixelRatio to Math.min(window.devicePixelRatio, 2) — no need for 3x on mobile

// Example: responsive 3D fallback
const isMobile = useMediaQuery('(max-width: 768px)');

return isMobile ? (
  <AnimatedGradientBackground /> // lightweight CSS fallback
) : (
  <Canvas>
    <HeroScene />
  </Canvas>
);

Step 12 — Testing & Quality Assurance

Run production-level validation before declaring the build complete.

Testing Checklist

Performance

• Lighthouse score > 90 on Performance
• No layout shift (CLS < 0.1)
• 3D scene loads within 3 seconds
• Consistent 60fps during scroll and interaction

Responsiveness

• Test at 375px, 768px, 1024px, 1440px
• Navigation collapses properly on mobile
• 3D fallback activates on mobile/low-end devices
• Touch interactions work (no hover-only states blocking mobile)

Animation

• All scroll reveals trigger correctly
• Hover states respond within 100ms
• prefers-reduced-motion respected
• No janky or stuttering animations

Browser Compatibility

• Chrome, Firefox, Safari, Edge — latest two versions
• WebGL support detection with graceful fallback
• CSS backdrop-filter fallback for older browsers

Accessibility

• Proper heading hierarchy (h1 → h2 → h3)
• Alt text on images, aria-labels on interactive 3D
• Keyboard navigation works
• Color contrast meets WCAG 2.1 AA

Testing Tools

Step 13 — Production Build, Deployment & Error Resolution (MANDATORY)

This step is non-negotiable. After the build is complete, the agent MUST run these checks and fix every issue before declaring the task done.

13.1 — Build & Deploy Preparation

1. Optimize bundle: tree-shake unused imports, analyze with next build --analyze
2. Compress 3D assets: draco-compress glTF models, optimize textures to WebP/AVIF
3. Configure next.config.js for optimal output
4. Run next build and verify zero errors
5. Test production build locally with next start

Deployment Targets

13.2 — Automated Error Resolution

npm install          # Catch missing packages
npx tsc --noEmit     # Catch ALL type errors
npm run build        # Catch build-time errors
npx next lint        # Catch code quality issues

If any command fails: read the error, fix it, re-run, repeat until zero errors.

13.3 — 3D-Specific Error Checks

13.4 — Final Resolution Loop

WHILE errors exist:
  1. Run: npm run build → IF fail → fix → GOTO 1
  2. Run: npx next lint → IF fail → fix → GOTO 1
  3. Run: npm run dev → IF crash → fix → GOTO 1
  4. All clear → EXIT

The agent MUST NOT declare the task complete until:

• npm run build exits with code 0
• npx next lint passes (no errors)
• npm run dev boots without crashing
• No TypeScript errors (npx tsc --noEmit passes)
• 3D scenes load with proper Suspense boundaries
• No hydration mismatch warnings

Rule: If you generated the code, you own the errors. Fix them before finishing.

Visual Quality Validation

Before finalizing, validate against these standards. If any answer is "no" — go back and fix it.

Typography

• Type hierarchy is strong (display > h1 > h2 > body are clearly distinct)
• Headings use negative letter-spacing (-0.02em to -0.04em)
• Body text is 16–18px with 1.5–1.7 line height
• Lines capped at 65–75 characters maximum width

Spacing & Layout

• Every spacing value comes from the defined scale
• Sections have generous vertical padding (80–128px on desktop)
• Layout feels spacious and intentional, nothing cramped

Color & Polish

• Primary color used sparingly — CTAs and key accents only
• Gradients are subtle and purposeful
• Interactive elements have hover/focus states with smooth transitions
• Shadows are colored/tinted, never pure black rgba(0,0,0,x)

3D & Animation

• 3D elements serve the product narrative, not just decoration
• Animations are smooth at 60fps
• Loading states exist for 3D content
• Mobile has appropriate fallbacks

Overall Impression

• The UI looks premium and modern — not like a generic template
• It resembles award-winning websites (Awwwards quality)
• The design serves this specific product's niche and audience
• A user would trust and respect this product based on visual quality alone
• The 3D integration feels natural and purposeful, not gimmicky

Anti-Patterns — What to Avoid

Understanding what fails helps you avoid it:

The "Awwwards or Redo" Test

After building, honestly evaluate:

1. Screenshot test — Put your screenshot next to Linear.app, Stripe.com, or an Awwwards winner. Does it belong?
2. Squint test — Squint at the page. Clear visual hierarchy? Important elements dominant?
3. 3-second test — Show it for 3 seconds. Can someone tell what the product does?
4. Motion test — Scroll through once. Does the animation feel choreographed or chaotic?

If any answer is "no" — iterate before delivery.

Final Output

The AI must generate:

• Complete frontend code — full Next.js project with TypeScript
• Modular component system — reusable, typed, well-organized
• Modern responsive layout — beautiful on every screen size
• Smooth animation system — scroll reveals, hovers, micro-interactions at 60fps
• 3D interactive experience — Three.js/R3F scene integrated purposefully into the design
• Performance-optimized build — lazy-loaded 3D, compressed assets, efficient rendering
• Realistic content — believable copy, real-sounding data, proper text lengths
• Design system documentation — brief summary of palette, typography, and design rationale

The final result must feel like an award-winning modern product website — the kind featured on Awwwards, not the kind generated by a template builder.

Cross-Agent Compatibility

This skill works with any AI coding agent that supports Markdown-based skill files:

The skill is Markdown-based with optional reference documents — no runtime dependencies, no API keys, no build steps.