# Add reablocks (Unify Theme) to my Next.js (App Router) project You are an expert React engineer. Add **reablocks** with the **Unify Theme** — the production design-token theme synced with the Unify Design System (UDS) in Figma, built on **Tailwind CSS v4** — to my existing **Next.js (App Router)** project. Start by installing Reaviz's official AI skills (Step 1) so you have the canonical, up-to-date reablocks knowledge loaded, then follow the remaining steps exactly. Do not substitute a different UI or styling library, and do not change my app architecture beyond what these steps require. ## ALWAYS do - Install the official reablocks AI skills first (`npx skills add reaviz/skills`) and follow them — they carry Reaviz's canonical, current reablocks + Tailwind v4 guidance. - Use **Tailwind CSS v4** — the `@import "tailwindcss"` + `@source` + `@theme` syntax. reablocks targets v4, not v3. - Install only the dependencies listed below. - Install the Unify assets as files (Step 4) — the CSS token layers and the `themeUnify.ts` module live in the repo, not in the npm package. - Wrap the app with `` where `theme` comes from the `themeUnify` module (`ThemeProvider` itself comes from `reablocks`). - Put a `theme-dark` (or `theme-light`) class on the root `` element. - Use my existing package manager — detect it from the lockfile (npm / pnpm / yarn / bun) and translate the install commands accordingly. ## NEVER do - Do NOT use Tailwind v3 syntax — no `@tailwind` directives, no `tailwind.config` content globs. reablocks needs v4. - Do NOT install or scaffold a different component library or design system. - Do NOT import the default `theme` from `reablocks` — for Unify the theme comes from the `themeUnify` module. - Do NOT try to import Unify CSS or a Unify theme from the reablocks npm package — they are not shipped; the assets are installed as files in Step 4. - Do NOT paste the default reablocks token block into the stylesheet — `tw.css` already registers every Unify token. - Do NOT reorder the imports inside `index.css` — `tw.css` must come last. - Do NOT place `` inside a Server Component (Next.js App Router); it must live in a Client Component. ## Steps ### 1. Install the reablocks AI skills Install Reaviz's official AI skills so you have the canonical, always-current reablocks API + Tailwind v4 setup knowledge loaded before you start: ```sh npx skills add reaviz/skills ``` (Team alternative: symlink the `reablocks` skill tree into `.claude/skills/`.) Once installed, follow the skills' guidance — the steps below match it. ### 2. Install dependencies ```sh npm install reablocks npm install -D tailwindcss@4 @tailwindcss/postcss ``` (Use the equivalent for your package manager — e.g. `pnpm add` / `pnpm add -D`, `yarn add` / `yarn add -D`, `bun add` / `bun add -d`.) ### 3. Enable the Tailwind v4 PostCSS plugin Next.js processes CSS through PostCSS, so add the Tailwind v4 plugin to your PostCSS config (`postcss.config.mjs` — create it if missing): ```js // postcss.config.mjs return { plugins: { '@tailwindcss/postcss': {} } }; ``` If a `postcss.config.{js,cjs,mjs,ts}` already exists, add the `@tailwindcss/postcss` plugin to that file instead of creating a second config. ### 4. Install the Unify Theme assets The Unify Theme is two parts — Figma-generated CSS token layers and a TypeScript component-theme module. Neither ships inside the `reablocks` npm package; install both as files: **a) Download the component-theme module** to `src/themeUnify.ts`: ```sh curl -o src/themeUnify.ts https://reablocks.dev/assets/themeUnify.ts ``` **b) Copy the CSS token layers** — `index.css`, `common.css`, `root.css`, `dark.css`, `light.css`, `tw.css` — into `src/assets/styles/`. They live at `src/assets/styles/` on the `main-react-query` branch of the official Unify starter: https://github.com/goodcodeus/app-starter/tree/main-react-query (If the team uses the Unify Design System in Figma, export fresh layers instead: Reablocks Figma Plugin → **Export Styles** → unzip into `src/assets/styles/`.) `tw.css` already contains `@import 'tailwindcss'`, the `@source` directive for reablocks, and the `@theme inline` token registration — do not add the default reablocks token block on top. Verify the `@source` path resolves to `node_modules/reablocks` relative to `src/assets/styles/tw.css`; if components render unstyled, adjust the `../` depth. ### 5. Set the default theme class on `` In `src/app/layout.tsx`, add the theme class to the root `` tag (set it once): ```tsx ``` Swap `theme-dark` for `theme-light` to default to light mode. Unify also recognizes `.dark` / `.light` classes and `data-theme` attributes. ### 6. Wrap your app with ThemeProvider + import the styles Import the Unify styles entry once at the app root and wrap the app with ``, using the `theme` from the `themeUnify` module — NOT the default theme from the package. Keep the import order inside `index.css` unchanged: `tw.css` must stay last: ```tsx // src/app/providers.tsx — new client component 'use client'; import { ThemeProvider } from 'reablocks'; import { theme } from '../themeUnify'; import type { ReactNode } from 'react'; export function Providers({ children }: { children: ReactNode }) { return {children}; } // src/app/layout.tsx — edit your existing layout: // 1. import the Providers component and the Unify styles entry // 2. add the theme class to // 3. wrap {children} with import { Providers } from './providers'; import '../assets/styles/index.css'; return function RootLayout({ children }: { children: ReactNode }) { return ( {children} ); } ``` ## Verify After the changes, confirm each item: - [ ] `reablocks`, `tailwindcss` (v4) and `@tailwindcss/postcss` are in `package.json`. - [ ] `src/assets/styles/` contains `index.css`, `common.css`, `root.css`, `dark.css`, `light.css` and `tw.css`; `src/themeUnify.ts` exists. - [ ] `src/assets/styles/index.css` is imported by the app entry, with `tw.css` last in its import chain. - [ ] `src/app/layout.tsx` has `className="theme-dark"` on the `` tag. - [ ] The app root is wrapped in `` with `theme` imported from the `themeUnify` module. - [ ] A `