# How do you keep a coding agent on your shadcn/ui theme?

Updated 2026-11-21 · https://briefatto.com/guides/shadcn-ui-design-md/

Keep the theme where shadcn/ui puts it, in CSS variables under `:root` and `.dark`, and give the agent a DESIGN.md that says how your brand uses them. Briefatto Board records that guide from your rendered pages, points AGENTS.md and CLAUDE.md at it, and `board check` notes any colour or font that strays from it.

## Where the theme lives

shadcn/ui's [theming documentation](https://ui.shadcn.com/docs/theming) uses and recommends CSS variables, set through `tailwind.cssVariables` in `components.json`, with the tokens in your CSS file under `:root` and `.dark`. Those variables say which values exist. DESIGN.md says how your brand puts them together: which colour signals, which face carries headings, how a card or a hero is built.

## Set it up

1. Run `npx briefatto-board install`.
2. With the app running, run `npx briefatto-board adopt . --page <url>` for each representative route.
3. The agent reads the captures and computed styles, inspects your CSS variables and theme files, and writes DESIGN.md by role.
4. Run `npx briefatto-board freeze .`. Freeze records the exact rendered styles, and the block tells every session to read the guide first.

## Catch the strays

On a frozen board, `board check` notes every colour and font a piece paints that is not in the current guide. Add `--consistency` for a kit format to list each off-palette colour with its nearest frozen colour.

## Questions and answers

### Does DESIGN.md replace components.json or my CSS variables?

No. shadcn/ui keeps the theme; DESIGN.md is the brief the agent reads before it uses it.

### Can DESIGN.md refer to my variables by name?

Yes. Describe them by role in the prose. Freeze compares the colour values written in the guide with the render, and reads a braced reference as a token name.

### 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

- [How is DESIGN.md different from a Tailwind config?](https://briefatto.com/guides/design-md-vs-tailwind-config/)
- [Design tokens for AI coding agents: what goes in DESIGN.md?](https://briefatto.com/guides/design-tokens-for-ai-coding-agents/)
- [How do you keep design tokens consistent in Cursor's output?](https://briefatto.com/guides/keep-design-tokens-consistent-in-cursor/)
- [Your AI coding agent ignores your design system: what to do](https://briefatto.com/guides/ai-coding-tools-ignore-your-design-system/)

## Sources

- https://ui.shadcn.com/docs/theming (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- 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/design-validation.ts
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
