Frontend web core

Frontend Web Core

Shared model for the frontend-web cluster. The framework, motion, a11y, and tooling spokes all depend on these interlocking conventions — keep them consistent here so no spoke contradicts another.

1. The rendering model (this cluster's defining decision)

Every web UI is one of four rendering models, and the choice fixes the hydration boundary — where server-rendered HTML hands off to client JavaScript. Get this wrong and you get hydration mismatches, layout shift, and dead interactivity.

Static (SSG) ──► SSR ──► RSC (server components) ──► CSR (client only)
   most cacheable  ◄──────────  most interactive  ──────────►

• Static / SSG — HTML built at build time. Cheapest, most cacheable. No per-request data.
• SSR — HTML rendered per request, then hydrated on the client. → nuxt4-patterns (useFetch/useAsyncData), Next.js pages.
• RSC — React Server Components render on the server and ship zero JS; interactivity is opted into with "use client". → react-patterns (server/client boundary), nextjs-turbopack.
• CSR — everything runs in the browser. Simplest mental model; worst first paint. → SPA-style React/Vue/Angular.

Rule: decide the model first. It dictates how you fetch data (server vs client), where state can live, whether a component may use browser APIs, and how motion mounts. Default to the most static model that still meets the interactivity requirement — push work to build time or the server before reaching for client JS.

2. The SSR / "use client" contract

The server and the first client render must produce identical markup. Violations are the #1 source of frontend bugs in this cluster.

• Mark any component using state, effects, browser APIs, or motion as a client component ("use client" in Next.js App Router; <ClientOnly>/import.meta.client in Nuxt). → react-patterns, nuxt4-patterns
• Always set an explicit initial state on animated elements — never an implicit origin. → motion-foundations
• Never read window/navigator/localStorage during render; gate them behind an effect or a client check.
• Match data between server and client renders; hydrate from the same payload. → react-performance (avoid client-side refetch waterfalls)

3. Motion layering rule

Motion is layered, not flat. Tokens and springs are defined once in motion-foundations; every pattern imports them — no inline durations or eases.

motion-foundations (tokens · springs · perf rules · reduced-motion · SSR safety)
        │
        ├─► motion-patterns   (button · modal · toast · stagger · page transitions · scroll)
        └─► motion-advanced   (drag · gestures · SVG · text · useAnimate sequences)

• Animate only transform and opacity; never width/height/top/left (layout thrash).
• Honor prefers-reduced-motion everywhere (useReducedMotion + the CSS media query).
• Never mix motion/react and framer-motion in one project — conflicting schedulers break AnimatePresence.
• Set AnimatePresence mode explicitly ("wait" for modals/toasts/page transitions, "popLayout" for lists).

4. Accessibility baseline (non-negotiable)

Two altitudes, both required:

• Standard → accessibility: WCAG 2.2 AA — POUR principles, ≥24×24px target size (SC 2.5.8), visible focus (SC 2.4.11), 4.5:1 text contrast, 400% reflow. The spec states cross-platform principles; in this cluster apply them to browser UI (DOM/ARIA) only — for native mobile a11y use the react-native / expo / mobile-flutter clusters.
• Implementation → frontend-a11y: semantic HTML before ARIA, htmlFor/id label pairing, aria-* only when native semantics fall short, keyboard navigation, focus management/restore.

Rule: semantic element first; every interactive control keyboard-reachable; every state change announced.

5. Framework / tooling matrix

Concern	React / Next	Vue / Nuxt	Angular
Components & state	react-patterns	ui-to-vue (from designs)	angular-developer
SSR / data fetching	react-patterns (RSC), nextjs-turbopack	nuxt4-patterns (useFetch)	angular-developer (SSR)
Performance	react-performance	nuxt4-patterns (route rules, lazy)	angular-developer (signals)
Testing	react-testing	—	angular-developer (refs)
Bundler	nextjs-turbopack, vite-patterns	vite-patterns	Angular CLI
Runtime / PM	bun-runtime	bun-runtime	bun-runtime

Cross-cutting (framework-agnostic): motion-foundations/patterns/advanced, accessibility, frontend-a11y, design-system, make-interfaces-feel-better, frontend-design-direction, frontend-slides.

6. Version / conventions

• React 18/19 (hooks + Server Components); Next.js 16+ on Turbopack; Nuxt 4; Angular with signals/resource.
• Vite for non-Next bundling and library mode; Turbopack for Next dev; Bun as the fast runtime/PM/test alternative to Node.
• Motion via the motion package (motion/react); framer-motion is the legacy import path only.
• TypeScript throughout; additionalProperties in skill frontmatter is fine, but version must be valid semver.

7. Shared guardrails

• Decide the rendering model first; default to the most static option that meets the need.
• Respect the SSR boundary: "use client" for stateful/motion code, identical server/client initial markup, no browser APIs during render.
• Layer motion on motion-foundations; animate transform/opacity only; honor reduced motion; one motion package per project.
• Accessibility is baseline: semantic HTML, keyboard reachability, WCAG 2.2 AA target sizes and focus.
• Pick one framework per surface; don't blend React and Vue idioms.
• State every regression-prone change (a new client boundary, a layout-animating property, a dropped label) explicitly.