Every great app has its own visual identity. The default Nuxt UI look is polished and clean. Out of the box, every Nuxt UI app shares the same default look. Whether you're building a SaaS product, a personal blog, or a client project, you'll eventually need to make it yours. The good news? Theming in Nuxt UI v4 is one of its best features. With just a CSS file and a config file, you can transform the look of your entire application to match any brand. Nuxt UI's theming system is built around CSS variables and design tokens, with Tailwind CSS and the @theme directive at the center. No forking. No hacks. No overrides. Just clean, token-based theming that scales. That gives you a few nice benefits: your theme lives in one obvious place colors and fonts are easier to reuse light and dark mode become much easier to manage you can brand the whole app without rewriting each component one by one In this guide, we'll build a custom theme from scratch. We will utilize fonts we like, implement our brand's colors, and override component-level defaults. By the end, you'll have a fully branded design system and a clear mental model for extending it further. What You'll Need Before diving in, make sure you have: A Nuxt project with @nuxt/ui v4 installed Basic familiarity with Tailwind CSS utility classes Node.js 18 or higher If you're starting from scratch, scaffold a new project to include Nuxt UI. When you run the following command, you will be prompted to choose a template. Select the "ui - App using Nuxt UI" template. npx nuxi init nuxt-theme-demo How Theming Works in Nuxt UI v4 It helps to understand the architecture before touching any files. Nuxt UI v4 theming is built on three layers, each with a distinct responsibility: Layer 1 — main.css (Design Tokens) This is where you define your raw design values — fonts, colors, spacing — using Tailwind CSS v4's @theme directive. Think of this as your brand's DNA. Layer 2 — app.config.ts (Semantic Mapping) This is where you map your raw tokens to semantic meaning — telling Nuxt UI which color is primary, which is neutral, and so on. This layer is also reactive at runtime, meaning you can swap themes without a redeploy. Layer 3 — app.config.ts Component Overrides (Component Styling) Also in app.config.ts, you can override the styles of individual components globally — changing the default button size, making all cards have rounded corners, or making the navigation link text bold. Let's build each layer. Step 1: Set Up Your CSS File NOTE: If you created your project using the "ui" template, this file will already exist. If you are adding Nuxt UI to an existing project, you will need to create this file. Open (or create) your assets/css/main.css file. This is Nuxt UI's main entry point for global styles and the place where Tailwind v4 configuration lives. Start with the required imports: /* assets/css/main.css */ @import "tailwindcss"; @import "@nuxt/ui"; Make sure this file is referenced in your nuxt.config.ts: // nuxt.config.ts export default defineNuxtConfig( css: ['~/assets/css/main.css'], modules: ['@nuxt/ui'], ) Step 2: Customize Your Fonts The first thing visitors notice about a brand is often its typography. Nuxt UI v4 integrates with @nuxt/fonts, which means any font you declare in your CSS is automatically loaded and optimized — no manual tags, no Google Fonts boilerplate. Add your fonts inside a @theme block: /* assets/css/main.css */ @import "tailwindcss"; @import "@nuxt/ui"; @theme --font-sans: 'Inter', system-ui, sans-serif; --font-mono: 'JetBrains Mono', monospace; The --font-sans variable controls body text across your entire app. The --font-mono variable handles code blocks and any element using the font-mono utility. Tailwind will instantly expose utilities like font-sans and font-mono for you to use in your templates. Tip: Choose a sans-serif that matches your brand's personality. Geometric fonts like Inter or DM Sans feel modern and technical. Humanist fonts like Nunito or Lato feel approachable and friendly. Step 3: Define Your Brand Colors This is where the fun begins. Nuxt UI uses a semantic color system — you define raw color palettes in CSS, then map them to semantic roles (primary, secondary, etc.) in your config. 3a. Register Your Custom Color Palette Inside a @theme static block, define your brand color as a full scale from 50 to 950. You need all shades because Nuxt UI components use them for hover states, focus rings, backgrounds, and text. If you created your project using the "ui" template, this block will already exist as it customizes the color green to match Nuxt's brand color. If you are adding Nuxt UI to an existing project, you will need to create this block. Here is what the block looks like in the template: /* assets/css/main.css */ @import "tailwindcss"; @i