| name | frontend-web-core |
| description | Shared reference for the frontend-web cluster: the rendering-model decision (CSR / SSR / RSC / static) that sets the hydration boundary, plus the conventions every spoke shares — the SSR/'use client' contract, the motion-foundations layering rule, the accessibility baseline, and the framework/tooling matrix. USE WHEN choosing a framework, wiring SSR-sensitive or motion code, or planning accessibility — the interlocking rules every frontend-web spoke depends on. |
| cluster | frontend-web |
| version | 1.0.0 |
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.
