teqo-backup/.agents/skills/top-design/references/technical-stack.md
Francisco Ignácio Fontoura Solla b75daab498 Refactor campaign dashboard UX and add product discovery artifacts.
Extract dashboard cards into focused components (queues, upcoming plans, leadership status, recently visited, choropleth legend), compile the roadmap for outcome-oriented tracking, document the customer job and improve-app journey, and tighten roadmap skills with decision-quality gates.
2026-07-19 21:56:01 -03:00

11 KiB

Technical Stack Reference

Table of Contents

  1. Core Technologies
  2. Animation Libraries
  3. Smooth Scrolling Solutions
  4. 3D & WebGL
  5. Build Tools & Frameworks
  6. Performance Optimization
  7. Deployment & Hosting

1. Core Technologies

CSS Approach

METHODOLOGY
├── CSS Custom Properties (required)
├── Modern CSS (container queries, :has(), etc.)
├── Utility-first OR Component-based (not mixed)
└── PostCSS for processing (autoprefixer, nesting)

RECOMMENDED STACK
├── Plain CSS with custom properties
├── Tailwind CSS (for rapid prototyping)
├── CSS Modules (for React/Vue scoping)
└── Vanilla Extract (for type-safe CSS-in-JS)

JavaScript Standards

// Modern JS features to use freely
const features = {
  modules: true,                    // ES Modules
  asyncAwait: true,                 // Async/await
  optionalChaining: true,           // obj?.prop
  nullishCoalescing: true,          // value ?? default
  destructuring: true,              // const { a, b } = obj
  spreadOperator: true,             // [...arr, newItem]
  templateLiterals: true,           // `${var}`
  arrowFunctions: true,             // () => {}
};

// Avoid
const avoid = {
  var: true,                        // Use const/let
  callbacks: 'Use promises/async',
  jquery: 'Use native APIs',
};

2. Animation Libraries

GSAP (GreenSock)

THE INDUSTRY STANDARD
├── Power: Most capable animation library
├── Performance: Optimized for 60fps
├── Ecosystem: ScrollTrigger, SplitText, MorphSVG
└── License: Free for most uses, paid for some plugins

INSTALLATION
npm install gsap

CORE PLUGINS (free)
├── ScrollTrigger - scroll-based animations
├── Observer - scroll/touch/pointer tracking
├── Draggable - drag interactions
└── MotionPath - animate along SVG paths

CLUB PLUGINS (paid)
├── SplitText - text splitting for animation
├── MorphSVG - shape morphing
├── DrawSVG - line drawing effects
├── ScrollSmoother - smooth scroll + ScrollTrigger
└── Flip - layout animations
// GSAP initialization pattern
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

// Set defaults
gsap.defaults({
  ease: "expo.out",
  duration: 1
});

// Basic animation
gsap.to(".element", {
  x: 100,
  opacity: 1,
  duration: 0.8
});

// Timeline
const tl = gsap.timeline();
tl.to(".first", { x: 100 })
  .to(".second", { x: 100 }, "-=0.5") // overlap
  .to(".third", { x: 100 }, "+=0.2"); // gap

Motion (Framer Motion)

REACT-SPECIFIC
├── Declarative API
├── Layout animations
├── Gesture support
├── Exit animations
└── Server-side rendering support

INSTALLATION
npm install motion
// Motion usage
import { motion, AnimatePresence } from "motion/react";

// Basic animation
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  exit={{ opacity: 0 }}
  transition={{ duration: 0.6, ease: [0.16, 1, 0.3, 1] }}
>
  Content
</motion.div>

// Scroll-triggered
<motion.div
  initial={{ opacity: 0 }}
  whileInView={{ opacity: 1 }}
  viewport={{ once: true, margin: "-100px" }}
>
  Reveals on scroll
</motion.div>

// Layout animation
<motion.div layout>
  {/* Animates when layout changes */}
</motion.div>

Anime.js

LIGHTWEIGHT ALTERNATIVE
├── Size: ~17KB minified
├── SVG morphing included
├── Timeline support
└── Good for simpler projects

INSTALLATION
npm install animejs
import anime from 'animejs';

anime({
  targets: '.element',
  translateX: 250,
  rotate: '1turn',
  duration: 800,
  easing: 'easeOutExpo'
});

// Stagger
anime({
  targets: '.grid-item',
  translateY: [50, 0],
  opacity: [0, 1],
  delay: anime.stagger(100)
});

3. Smooth Scrolling Solutions

MODERN & LIGHTWEIGHT
├── Size: ~4KB gzipped
├── Native scroll (accessibility preserved)
├── GSAP integration
├── Performant
└── Actively maintained by Studio Freight

INSTALLATION
npm install lenis
import Lenis from 'lenis';

const lenis = new Lenis({
  duration: 1.2,
  easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
  orientation: 'vertical',
  gestureOrientation: 'vertical',
  smoothWheel: true,
  wheelMultiplier: 1,
  touchMultiplier: 2,
  infinite: false,
});

function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}

requestAnimationFrame(raf);

// GSAP integration
import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

lenis.on('scroll', ScrollTrigger.update);

gsap.ticker.add((time) => {
  lenis.raf(time * 1000);
});

gsap.ticker.lagSmoothing(0);

Locomotive Scroll

FEATURE-RICH
├── Smooth scrolling
├── Parallax effects built-in
├── Data attributes for quick setup
├── Horizontal scroll support
└── Heavier than Lenis

INSTALLATION
npm install locomotive-scroll
import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  multiplier: 1,
  lerp: 0.1
});

// Data attribute usage
// <div data-scroll data-scroll-speed="2">Parallax element</div>

4. 3D & WebGL

Three.js

FULL 3D CAPABILITY
├── Complete 3D engine
├── Large ecosystem
├── Extensive documentation
└── Performance-intensive

INSTALLATION
npm install three
import * as THREE from 'three';

// Basic scene setup
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

// Animation loop
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();

React Three Fiber

THREE.JS FOR REACT
├── Declarative Three.js
├── React ecosystem integration
├── Easier state management
└── Drei helpers library

INSTALLATION
npm install @react-three/fiber @react-three/drei
import { Canvas } from '@react-three/fiber';
import { OrbitControls, Environment } from '@react-three/drei';

function Scene() {
  return (
    <Canvas>
      <ambientLight intensity={0.5} />
      <mesh>
        <boxGeometry />
        <meshStandardMaterial color="orange" />
      </mesh>
      <OrbitControls />
      <Environment preset="city" />
    </Canvas>
  );
}

OGL

LIGHTWEIGHT WEBGL
├── Size: ~30KB
├── Lower-level than Three.js
├── Better for simple effects
└── Less overhead

INSTALLATION
npm install ogl

5. Build Tools & Frameworks

FAST BUILD TOOL
├── Instant dev server
├── Native ES modules
├── Optimized production builds
└── Framework agnostic

SETUP
npm create vite@latest

Next.js (React Apps)

REACT FRAMEWORK
├── Server-side rendering
├── Static site generation
├── API routes
├── Image optimization
└── File-based routing

SETUP
npx create-next-app@latest

Astro (Content Sites)

CONTENT-FOCUSED
├── Zero JS by default
├── Partial hydration
├── Any framework components
├── Excellent performance
└── Great for portfolios/marketing

SETUP
npm create astro@latest

Nuxt (Vue Apps)

VUE FRAMEWORK
├── SSR/SSG
├── Auto-imports
├── File-based routing
└── Excellent DX

SETUP
npx nuxi@latest init

6. Performance Optimization

Image Optimization

FORMATS
├── WebP: Primary format, 25-35% smaller than JPEG
├── AVIF: Best compression, growing support
├── SVG: Icons, logos, illustrations
└── JPEG/PNG: Fallbacks only

TOOLS
├── Sharp (Node.js): npm install sharp
├── Squoosh: squoosh.app (browser-based)
├── ImageOptim: Desktop app (Mac)
└── SVGO: SVG optimization

RESPONSIVE IMAGES
<picture>
  <source srcset="image.avif" type="image/avif">
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="Description" loading="lazy">
</picture>

SRCSET FOR RESOLUTION
<img 
  srcset="image-400.webp 400w, image-800.webp 800w, image-1200.webp 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  src="image-800.webp"
  alt="Description"
  loading="lazy"
>

Font Optimization

<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/display.woff2" as="font" type="font/woff2" crossorigin>

<!-- Font-display strategy -->
<style>
@font-face {
  font-family: 'Display';
  src: url('/fonts/display.woff2') format('woff2');
  font-display: swap; /* or optional for non-critical */
  unicode-range: U+0000-00FF; /* Subset to Latin */
}
</style>

Code Splitting

// Dynamic imports
const HeavyComponent = lazy(() => import('./HeavyComponent'));

// Route-based splitting (Next.js automatic)
// Each page is a separate chunk

// Manual chunk with Vite
// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['gsap', 'three'],
        },
      },
    },
  },
};

Critical CSS

// Extract critical CSS with Critters (Vite plugin)
// npm install critters
import critters from 'critters';

// Or inline critical styles manually
<style>
  /* Above-the-fold styles inlined */
</style>
<link rel="preload" href="/styles.css" as="style" onload="this.rel='stylesheet'">

7. Deployment & Hosting

STATIC SITES
├── Vercel: Best for Next.js, excellent DX
├── Netlify: Great for Jamstack, easy deploys
├── Cloudflare Pages: Fast edge network
└── GitHub Pages: Free, simple static hosting

FULL-STACK
├── Vercel: Serverless functions, edge middleware
├── Railway: Containers, databases
├── Render: Full infrastructure
└── AWS Amplify: AWS ecosystem

CDN FOR ASSETS
├── Cloudflare: Free tier, global
├── AWS CloudFront: Enterprise scale
├── Bunny CDN: Cost-effective, fast
└── Imgix/Cloudinary: Image-specific CDN

Performance Checklist

PRE-LAUNCH
□ Images optimized (WebP/AVIF, lazy loaded)
□ Fonts subset and preloaded
□ CSS/JS minified and compressed
□ Gzip/Brotli compression enabled
□ HTTP/2 or HTTP/3 enabled
□ Cache headers configured
□ Critical CSS inlined
□ Unused CSS/JS removed

MONITORING
□ Lighthouse CI in deployment
□ Core Web Vitals tracking
□ Real User Monitoring (RUM)
□ Error tracking (Sentry, etc.)