# DESIGN.md with Next.js and Tailwind in Claude Code

Updated 2026-11-21 · https://briefatto.com/guides/claude-code-nextjs-tailwind-briefatto-board/

Start `next dev`, run `npx briefatto-board adopt . --page http://localhost:3000/` for each key route, and Claude Code writes DESIGN.md from the rendered pages, your Tailwind configuration and CSS variables. After `board freeze`, the block in CLAUDE.md tells Claude Code to read that guide before any visual work.

## How it fits a Next.js and Tailwind project

- Claude Code's [documentation](https://code.claude.com/docs/en/memory) describes persistent instructions through CLAUDE.md or AGENTS.md, and it [loads skills](https://code.claude.com/docs/en/skills) from `.claude/skills/`. Briefatto Board writes its block to both files and its skill to that folder.
- Next.js [serves the app](https://nextjs.org/docs/app/api-reference/cli/next) on http://localhost:3000 by default during development. `board adopt` captures a running site from the URLs you pass.
- Tailwind [theme variables](https://tailwindcss.com/docs/theme) defined with `@theme` become regular CSS variables. The skill tells Claude Code to inspect those CSS variables and your Tailwind configuration, and freeze records the computed styles your pages render.

## Set it up

Start the dev server with `next dev` and leave it running. Then, in the project folder:

```sh
npx briefatto-board install
npx briefatto-board adopt . --page http://localhost:3000/ --page http://localhost:3000/pricing
npx briefatto-board freeze .
```

Between adopt and freeze, ask Claude Code to write DESIGN.md from the captures in `.briefatto/adoption/`. Pass a `--page` for each representative route and state; the default captures are desktop and mobile.

## Static export instead

With `output: "export"` in next.config.js, `next build` creates an `out` folder with one HTML file per route. Adopt it directly: `npx briefatto-board adopt . --root out`.

## What Claude Code gets

- **One versioned guide.** DESIGN.md is frozen as v1, v2 and on.
- **A check on every piece.** `board check` fails clipped text, small text, unloaded fonts and low contrast.
- **A stale list after a rebrand.** `board status` lists which pieces are current, stale or unrecorded.

## Questions and answers

### Which routes should I pass to adopt?

The representative routes and states that carry the brand, such as the home page, a content page and a form. Repeat `--page` for each.

### Does it read my Tailwind theme?

Yes. The skill tells Claude Code to inspect your Tailwind configuration and CSS variables, and freeze records the styles they produce on the rendered pages.

### Do I need the dev server running for freeze?

Yes. Leave the site running from adopt through freeze, because freeze records styles from a fresh render.

### Is Briefatto Board free?

Yes. It is open source under the Apache-2.0 licence and installs with `npx briefatto-board install`.

## Try it

```
npx briefatto-board install
```

Briefatto Board is free and open source under Apache-2.0: https://github.com/Briefatto/briefatto-board

## Related guides

- [DESIGN.md with Next.js and Tailwind in Cursor](https://briefatto.com/guides/cursor-nextjs-tailwind-briefatto-board/)
- [DESIGN.md with Vite and React in OpenAI Codex](https://briefatto.com/guides/codex-vite-react-briefatto-board/)
- [Cursor + Briefatto Board: on-brand UI from one DESIGN.md](https://briefatto.com/guides/cursor-briefatto-board/)
- [How to make Claude Code follow your brand with DESIGN.md](https://briefatto.com/guides/how-to-use-design-md-in-claude-code/)

## Sources

- https://code.claude.com/docs/en/memory (checked 2026-11-21)
- https://code.claude.com/docs/en/skills (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md (checked 2026-11-21)
- https://nextjs.org/docs/app/api-reference/cli/next (checked 2026-11-21)
- https://nextjs.org/docs/app/guides/static-exports (checked 2026-11-21)
- https://tailwindcss.com/docs/theme (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/cli.ts
- https://github.com/Briefatto/briefatto-board/blob/main/README.md
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE

Briefatto Board is independent and is not affiliated with Claude Code.
