JSN UI Performance

# JSN UI — Performance

JSN UI is built to be fast. This skill documents the budget and
patterns we follow.

## Budget

- **First Load JS** — keep shared chunks under 110 KB
- **Per-route JS** — under 5 KB above the shared for static routes
- **Lighthouse Performance** — 95+ on a mid-tier mobile profile
- **LCP** — under 2.0s on 4G
- **CLS** — 0
- **TBT** — under 200ms

## Built-in optimizations

- **Static rendering** by default. All pages without client-side data
  are static (the Next.js `○` indicator in the build output).
- **Dynamic OG image** on Edge runtime — fast cold start, no server cold start.
- **Fonts** — Inter via `next/font/google` with `display: swap` and
  `preload: true`. Self-hosted, no Google Fonts request.
- **JSON-LD** — server-rendered into the HTML, no client JS.
- **Theme provider** — uses localStorage to avoid FOUC on first load.
- **Sitemap** — generated at build time, served as a static file.
- **Images** — use `next/image` everywhere; the default config serves
  WebP/AVIF.

## What you need to do

### Use `next/image`

```tsx
import Image from "next/image";
<Image src="/hero.png" alt="Hero" width={1200} height={630} priority />
```

`priority` for above-the-fold images.

### Lazy-load below-the-fold sections

For pages with many sections, dynamic-import heavy blocks:

```tsx
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/charts/area"), {
  loading: () => <Skeleton />,
});
```

### Don't ship a full animation library

JSN UI's motion elements are pure CSS + rAF. Don't reach for
Framer Motion unless the user explicitly wants it.

### Don't use barrel files in client components

```tsx
// ❌ Bad — bundles all 16 UI primitives even if you use 1
import { Button } from "@/components/ui";

// ✅ Good — tree-shakable
import { Button } from "@/components/ui/button";
```

### Measure before optimizing

- `pnpm build` — look at the `+ First Load JS shared by all` line
- Chrome DevTools → Performance → Record a page load
- Lighthouse CI in GitHub Actions for every PR

## What to avoid

- Don't import the entire `@/components/icons` barrel in client components
- Don't add client-side data fetching to pages that don't need it
- Don't use unoptimized `<img>` tags
- Don't lazy-load above-the-fold content
- Don't add a `useEffect` that runs on every page (audit with the React DevTools Profiler)