GuideBest Practicesdesign-systemtokensconsistencynuxt-uiarchitecture

Building a Design System with Nuxt UI

How to build a consistent, scalable design system for your Nuxt application using Nuxt UI v4 design tokens, theme configuration, and component conventions.

A design system is more than a component library - it's a shared language of design decisions. Nuxt UI v4 provides the building blocks. The Theme Builder helps you define and preview those decisions visually.

This guide covers how to establish a coherent design system using Nuxt UI's token architecture.

What Makes a Design System

A design system consists of:

  1. Design tokens - Color palettes, spacing, radius, typography
  2. Component library - Pre-built, themed UI components
  3. Conventions - Rules for how tokens and components are combined
  4. Documentation - Living references for developers and designers

Nuxt UI handles #1 and #2. Your job is #3 and #4.

Step 1: Define Your Token Foundation

Start with the core decisions that affect every page:

Colors

Choose your semantic palette mapping:

export default defineAppConfig({
  ui: {
    colors: {
      primary: "blue",
      secondary: "sky",
      success: "emerald",
      warning: "amber",
      error: "rose",
      neutral: "slate",
    },
  },
});

Decision to document: Why these palettes? What brand values do they represent?

Border Radius

Pick a radius strategy:

StrategyValueCharacter
Sharpnone or xsTechnical, precise, editorial
Softmd or lgFriendly, modern, approachable
Roundxl or 2xlPlayful, casual, consumer
FullfullPill buttons, tags, avatars

Consistency matters more than the specific value. Choose one strategy and apply it everywhere.

Typography

Select font pairings that support your content:

Content TypeRecommended Pairing
SaaS DashboardInter / JetBrains Mono
Marketing SitePlus Jakarta Sans / DM Mono
DocumentationDM Sans / Fira Code
Creative / AgencySpace Grotesk / Space Mono

Step 2: Establish Component Conventions

With tokens defined, establish rules for how components use them:

Button Hierarchy

Define which button variant serves each purpose:

PurposeVariantColor
Primary CTAsolidprimary
Secondary actionoutlineprimary
Tertiary / cancelghostneutral
Destructivesoliderror
Link-stylelinkprimary

Alert / Feedback Colors

Map feedback colors consistently:

StateColor RoleIcon
Informationprimaryi-lucide-info
Successsuccessi-lucide-check-circle
Warningwarningi-lucide-alert-triangle
Errorerrori-lucide-x-circle

Spacing Scale

Use Tailwind's spacing scale consistently. Pick a base unit and stick to multiples:

ContextSpacing
Between related itemsgap-2 (8px)
Between sectionsgap-6 (24px)
Page paddingpx-4 md:px-8
Card paddingp-4 md:p-6

Step 3: Document and Share

A design system only works if it's documented and accessible:

  1. Use the Theme Builder to visualize and iterate on token choices
  2. Export your theme configuration as the source of truth
  3. Create a living style guide by linking to your Theme Builder preview
  4. Write conventions as markdown - button rules, spacing guidelines, color usage

Step 4: Maintain Consistency

As your app grows:

  • Audit regularly - check new pages against your token foundation
  • Use theme presets - save named presets in the Theme Builder for different brands or modes
  • Enforce in code review - catch deviations from established patterns
  • Update the system - add new tokens/conventions as needs evolve

Common Pitfalls

PitfallSolution
One-off colorsAlways use semantic roles, never hard-coded hex
Inconsistent radiusSet once in config, don't override per-component
Mixed font stacksChoose one sans + one mono, apply via tokens
Skipping dark modeDesign both modes from the start

Try It

Use the Nuxt UI Theme Builder to define your token foundation visually, preview it across 125+ components, and export the configuration. It's the fastest way to bootstrap a design system for any Nuxt UI project.

Not sure where to start? Pick one of the built-in themes as your baseline, then stress-test it on full-page templates before you commit to it.

Next Steps

Back to All Articles