Design tokens for Next.js

Server Components, App Router, and beyond

Next.js projects span server and client boundaries. Design tokens need to work in both — CSS variables for Server Components, theme objects for Client Components, Tailwind config for utility classes. A designtoken.md gives your coding agent the complete token system so it generates consistent UI across your entire Next.js app.

Server-side

Server Components

CSS custom properties defined in your global stylesheet, sourced from designtoken.md's color scales and typography. No JavaScript runtime cost. Your agent generates className with CSS variable references, keeping server components lean and predictable.

Client-side

Client Components

When you need dynamic theming, the agent reads designtoken.md and generates theme providers, context values, or CSS-in-JS tokens. Full scale awareness means no magic numbers. Your Client Components can switch themes at runtime while maintaining design fidelity.

Styling

Tailwind CSS

The default styling in Next.js projects. designtoken.md's generator outputs Tailwind-compatible config. Your agent reads the markdown for semantic intent and generates utility classes: bg-primary-500, text-heading-lg, space-y-md.

Getting started

Next.js project structure with designtoken.md

Drop designtoken.md in your project root. Any coding agent reads it automatically as project context. No imports, no build steps, no config.

my-app/
├── designtoken.md ← Agent reads this
├── app/
│ ├── layout.tsx
│ ├── page.tsx
│ └── globals.css ← Token CSS variables
├── tailwind.config.ts ← Generated from tokens
└── package.json

Comparison

What your agent gets

With tokens, your agent generates semantic references instead of magic numbers.

Aspect	Without tokens	With designtoken.md
Colors	Hardcoded hex: #3B82F6, #1E40AF, #EFF6FF	Semantic references: primary-500, primary-800, primary-50
Typography	Arbitrary sizes: 16px, 20px, 14px	Semantic scales: heading-lg, body, caption
Spacing	Magic pixels: 8, 16, 24, 32px	Named tokens: space-sm, space-md, space-lg
Component states	Guessed hover/focus colors	Defined state tokens: primary-600, primary-700
Consistency	Variable across pages	Locked across entire app

FAQ

Common questions

Does designtoken.md work with the Next.js App Router?

Yes. The token file is project context, not a runtime dependency. It works identically with App Router, Pages Router, or any Next.js version. Your agent reads it as it generates components and styles.

Can I use designtoken.md with next/font?

Yes. Your designtoken.md defines the typography hierarchy — sizes, weights, leading, tracking. The agent maps these to your next/font declarations and generates consistent type styles across all your pages and components.

Do I need to configure anything in next.config.js?

No. designtoken.md is a context file your agent reads, not a build dependency. Zero Next.js config changes needed. The file lives in your project root and works with any Next.js setup.