Next.js UI Foundation

When to apply

Use at project start or when adding branding/SEO. Pair with shadcn-ui-setup for component library wiring.

Bootstrap checklist

- [ ] Root layout: html lang, font variables, body classes, global providers
- [ ] SkipToMain link as first focusable element in body
- [ ] Metadata export in layout.tsx (title, description, metadataBase in prod)
- [ ] Favicon: app/icon.svg (+ apple-icon.svg for iOS)
- [ ] Tailwind theme tokens in globals.css (@theme)
- [ ] next.config.ts: devIndicators false for clean dev UI
- [ ] .env.example documents NEXT_PUBLIC_* vars (incl. NEXT_PUBLIC_SITE_URL)

Fonts (next/font/google)

Pick one sans + optional display/serif. Load in layout, expose CSS variables:

import { Inter, Playfair_Display } from "next/font/google";

const sans = Inter({ variable: "--font-sans", subsets: ["latin"] });
const display = Playfair_Display({ variable: "--font-display", subsets: ["latin"], weight: ["700"] });

// <html className={`${sans.variable} ${display.variable}`}>
// body: font-sans; headings: font-display (via Tailwind)

Wire in globals.css:

@theme {
  --font-sans: var(--font-sans), system-ui, sans-serif;
  --font-display: var(--font-display), Georgia, serif;
}

Favicons (App Router file convention)

Remove legacy favicon.ico if adding SVG icons to avoid conflicts.

Design tips: simple mark, 2–3 colors, readable at 16×16.

Root layout pattern

export const metadata: Metadata = {
  title: { default: "App Name", template: "%s | App Name" },
  description: "One-line value prop.",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${sans.variable} h-full`}>
      <body className="min-h-full flex flex-col font-sans antialiased">
        {/* TooltipProvider, ThemeProvider, AnalyticsProvider, etc. */}
        {children}
      </body>
    </html>
  );
}

Theme tokens (Tailwind v4)

Define brand palette once in @theme:

@theme {
  --color-brand-50: #f0f4ff;
  --color-brand-900: #0f172a;
  --color-accent-400: #fbbf24;
}

Use semantic names (brand, accent, muted) not raw hex in components.

Route structure defaults

Keep marketing and app layouts separate ((marketing)/layout.tsx, (app)/layout.tsx) when styles diverge.

Production polish

// next.config.ts
const nextConfig = { devIndicators: false };

• Use loading.tsx / error.tsx per route group when UX matters
• Prefer next/image for photos; SVG icons via lucide-react
• Set metadataBase + NEXT_PUBLIC_SITE_URL when deploying (OG/sitemap) — see nextjs-seo-metadata
• Add skip link + <main id="main"> — see web-accessibility-wcag

Related skills

• nextjs-app-router — layouts, route handlers, env helpers
• nextjs-seo-metadata — robots, sitemap, JSON-LD, Open Graph
• tailwind-css-v4 — @theme tokens and dark mode variants
• next-themes-dark-mode — ThemeProvider wiring

Anti-patterns

• Loading fonts via <link> CDN when next/font is available
• Hardcoding page titles in client components instead of metadata
• Mixing multiple icon systems (pick lucide + app SVG mark)