--- name: impl-nextjs description: >- Implement or refactor Next.js frontend features with Tailwind and Skeleton UI. Covers App Router, Server Components, Server Actions, Skeleton themes and components, layout patterns, and theme token compliance. USE FOR: Next.js + Skeleton UI setup, feature implementation, theming, component development with App Router patterns. DO NOT USE FOR: SvelteKit (use impl-sveltekit), Angular (use impl-angular), generic React/Vue (use impl-typescript-frontend), backend (use impl-typescript-backend). argument-hint: 'Describe a Next.js + Skeleton setup or feature and I will implement it.' phase: '4' phase-family: implementation --- # Next.js + Skeleton UI Implementation ## When to Use - A requirement is implementation-ready and the target stack is Next.js with Skeleton UI and Tailwind. - The task is project setup, feature implementation, theming, or component development using Skeleton's design system with Next.js App Router. - The project uses (or will use) `@skeletonlabs/skeleton` and `@skeletonlabs/skeleton-react`. ## When Not to Use - SvelteKit + Skeleton -- use `impl-sveltekit`. - Angular -- use `impl-angular`. - Generic React/Vue/Nuxt frontend without Skeleton -- use `impl-typescript-frontend`. - Backend work -- use `impl-typescript-backend`. - Architecture or planning -- use `architecture-planning`. - Requirements are vague -- use `requirements-clarification` first. - Routing a mixed-scope task -- use `implementation-routing`. ## Procedure 1. **Detect context** -- Check for existing Next.js + Skeleton setup (`package.json`, `app/globals.css`, `data-theme` in layout) or assume greenfield. Read `package.json` and `tsconfig.json` to identify versions and structure. 2. **Read the spec or task** -- Extract acceptance criteria and implementation steps. If a Stage 3.5 task breakdown exists, follow it checkbox-by-checkbox. 3. **Fetch latest Skeleton docs** -- Before implementing or changing Skeleton layout or components, fetch `https://www.skeleton.dev/llms-react.txt` and use it as the source of truth for component names, props, layout patterns, and code samples. 4. **Setup or inspect existing patterns** -- For greenfield projects, follow the Project Setup section below. For existing projects, read neighboring modules for naming, error handling, styling, and test conventions before writing code. 5. **Implement or refactor** -- Write or modify code following project conventions, Skeleton's design system, and Next.js App Router patterns. Enforce all standards in the Standards section below. 6. **Build and verify** -- Run `npm run build` and `npm run dev`; fix failures. Ensure theme and components render correctly. 7. **Produce the output contract** -- Write the Implementation Complete Report (see Output Contract below). ## Standards Every Next.js + Skeleton implementation must comply with the following. These are enforced by `code-review` as Critical Issues. ### 1. Project Setup (Next.js + Tailwind + Skeleton) Use this sequence for new projects or when adding Skeleton to an existing Next.js app: 1. **Create Next.js project** (if greenfield): ```bash npm create next-app@latest cd ``` Use TypeScript, ESLint, Tailwind, `app/` router, and src directory if the project prefers it. 2. **Install Skeleton**: ```bash npm i -D @skeletonlabs/skeleton @skeletonlabs/skeleton-react ``` 3. **Configure Tailwind and Skeleton in CSS** -- In `app/globals.css` (or `src/app/globals.css`): - Import Tailwind: `@import 'tailwindcss';` - Import Skeleton: `@import '@skeletonlabs/skeleton';` - Import optional presets: `@import '@skeletonlabs/skeleton/optional/presets';` - Import a theme (e.g. cerberus, hamlindigo): `@import '@skeletonlabs/skeleton/themes/cerberus';` - Source Skeleton React components: `@source '../../node_modules/@skeletonlabs/skeleton-react/dist';` (adjust path if not using `src/`). 4. **Set active theme** -- In `app/layout.tsx`, set `data-theme` on the `` element, e.g. ``. 5. **Verify** -- Run `npm run dev` and confirm the app loads with Skeleton styles. **Compatibility:** Do not integrate Flowbite React, Flowbite Svelte, or Daisy UI; they conflict with Skeleton's Tailwind usage. Skeleton works with headless libraries (Bits UI, Melt UI, Radix, Zag.js) and Tailwind utility-based components. ### 2. Skeleton Integration - **Requirements:** Next.js 15+, React 18+, Tailwind 4+. - **Themes and presets:** Choose a theme from Skeleton's theme list (e.g. cerberus, hamlindigo, rocket). Use `data-theme` on `` or a wrapper to switch themes. Optional presets adjust spacing and typography. - **Components:** Use Skeleton's React components from `@skeletonlabs/skeleton-react` -- Accordion, App Bar, Avatar, Buttons, Cards, Chips, Forms/Inputs, Dialog, Menu, Navigation, Tabs, Toast, and others. See [Framework Components](https://www.skeleton.dev/docs/components). - **Styling:** Components accept `className` for Tailwind utilities. Skeleton uses CSS custom properties and Tailwind; follow the design system (Themes, Colors, Typography) from the docs. - **Theme switching:** If the app needs multiple themes, add a theme provider or script that sets `data-theme` on the root element; document the chosen approach. ### 3. Layout Components (Skeleton UI) Before implementing layouts or changing layout structure, fetch `https://www.skeleton.dev/llms-react.txt` and use the latest Layouts guide, App Bar, and Navigation sections as the source of truth. - **Custom page layouts** -- Skeleton does not provide an AppShell; use the Layouts guide: semantic HTML (`

`, `