Design tokens for Next.js: what to ship first
A practical order for exporting colors, type, and spacing into a Next.js app without boiling the ocean.
Teams new to design tokens often try to port an entire Figma variable collection on day one. Then the PR sits open for three weeks. Ship a thin vertical slice instead.
Week one: color and type
Your app already has CSS variables or Tailwind theme keys. Map brand primary, background, text, and muted text first. Add heading and body font stacks. That alone fixes eighty percent of "this looks off-brand" feedback.
Week two: spacing and radius
Pick a spacing scale you will actually use: 4, 8, 12, 16, 24, 32. Pick two border radii: default and pill. Document them in the same file as colors. Resist adding seventeen shadow tokens until you have components that need them.
Wire tokens at the layout boundary
In Next.js App Router, inject tokens in layout.tsx or a global CSS file loaded once. Child routes inherit. Do not pass hex codes as props unless you are building a theme switcher.
Connect brand flow to code
Run brand flow to generate palette and typography from your brief, then follow export and use in code. If you use Cursor, add the Cursor integration so agents read the same design.md you do.
Test with one high-traffic screen
Pick login or dashboard. Refactor only that route to tokens. Measure: fewer one-off styles, faster iteration on accent color. Then roll out route by route.
Common failure mode
Tokens live in a package nobody imports. Put imports where junior devs cannot miss them: global styles or the root layout. Visibility beats elegance early on.