Structure and performance

A design system is only as good as the place people look for it. Put tokens, components and content in predictable folders, and write the performance budgets down next to them. Then speed becomes a rule you check in review, not a crisis you fix before launch.

Folder structureCopy Anchor Link

my-app/
├─ app/                     # routes only: layout, page, loading, error
│  ├─ global.css            # tokens (@theme + :root + dark) and base styles
│  ├─ layout.tsx            # fonts, <html lang>, metadata defaults
│  ├─ icon.svg              # favicon, picked up by file convention
│  ├─ opengraph-image.png   # 1200 × 630
│  └─ (marketing)/page.tsx  # route groups keep URLs clean
├─ components/
│  ├─ ui/                   # primitives: button.tsx, input.tsx, dialog.tsx
│  └─ hero.tsx              # patterns built from primitives
├─ content/                 # MDX and copy, no logic
├─ lib/                     # pure helpers: cn.ts, motion.ts, format.ts
├─ public/                  # static files served as-is: fonts, video, images
└─ next.config.mjs

• MUST name files in kebab-case (pricing-table.tsx) and components in PascalCase (PricingTable).
• MUST keep one component per file in components/ui/.
• MUST NOT import from app/ into components/. It creates cycles and couples patterns to routes.
• MUST NOT put margins on primitives. The parent sets spacing, so the same button works anywhere.
• SHOULD mark client components with 'use client' at the smallest leaf that needs it, not at the page.

This site follows the same shape: tokens in app/global.css, diagrams in components/diagrams.tsx, content in content/docs/.

Core Web VitalsCopy Anchor Link

Google's "good" thresholds, measured at the 75th percentile of real page loads, on mobile and desktop separately.

• MUST meet all three "good" thresholds on a mid-range phone over a throttled 4G connection.
• MUST mark the LCP image with preload on next/image (or fetchpriority="high" on a plain img).
• MUST NOT lazy-load anything above the fold.
• MUST reserve space for anything that arrives late: images, embeds, cookie banners, ads.
• SHOULD check field data (Vercel Speed Insights, CrUX, PageSpeed Insights) before and after each release, not only Lighthouse.

BudgetsCopy Anchor Link

These are this guide's budgets for a content or marketing page. They are not a standard. A dashboard may need a larger JS budget; write down whatever you choose and check against it.

• MUST check first-load JS in the next build output for every route that changes.
• SHOULD load heavy client-only pieces (3D, shaders, editors) with next/dynamic and ssr: false (called from a client component), after the page is interactive.
• SHOULD load third-party scripts with next/script and strategy="lazyOnload" unless they are needed for the first paint.
• SHOULD pause canvases and animation loops when they are off-screen or the tab is hidden.

FontsCopy Anchor Link

// app/layout.tsx
import localFont from 'next/font/local';
import { Schibsted_Grotesk } from 'next/font/google';

const sans = Schibsted_Grotesk({ // the body face this site uses
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-sans',
});

const display = localFont({
  src: './fonts/display-var.woff2',
  display: 'swap',
  variable: '--font-display',
  preload: false, // only preload the font the LCP text uses
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en-GB" className={`${sans.variable} ${display.variable}`}>
      <body>{children}</body>
    </html>
  );
}

• MUST serve fonts as WOFF2 only. Every current browser supports it.
• MUST self-host through next/font. It inlines the @font-face, removes the request to Google and adds a size-matched fallback, which prevents layout shift on swap.
• MUST subset to the scripts you use (subsets: ['latin']).
• MUST use font-display: swap (or optional for non-essential display faces). Text must never be invisible while a font loads.
• SHOULD use one variable font instead of several static weights when you need three weights or more.
• SHOULD preload at most one or two font files: the ones used by the LCP text.
• SHOULD expose fonts as CSS variables (--font-sans) and map them in @theme, as this site does in app/global.css.

Why it worksCopy Anchor Link

Predictable folders make the system discoverable: anyone can guess where a button or a colour lives. One-way dependencies mean a change to a token flows down and a change to a page never breaks a primitive. Written budgets turn performance into a yes-or-no check at build time, and the Core Web Vitals thresholds tie that check to what people actually feel: content appearing, taps responding and nothing jumping.

SourcesCopy Anchor Link