vikaso-nuxt-ui

vikaso-nuxt-ui

The VIKASO theme for Nuxt UI v4: Nuxt UI colours and --ui-* variables mapped to vikaso-design-tokens, shared component styling, glass surfaces and base element styles. Visual only: no components and no app logic.

Install

npm install vikaso-nuxt-ui vikaso-design-tokens @nuxt/ui

Peer dependencies: @nuxt/ui ^4.12.0 and vikaso-design-tokens ^0.2.0.

Usage (Vue + Vite)

/* src/assets/main.css */
@import "tailwindcss";
@import "@nuxt/ui";
@import "vikaso-design-tokens/tailwind.css";
@import "vikaso-nuxt-ui";

// vite.config.js
import ui from '@nuxt/ui/vite';
import { vikasoNuxtUi } from 'vikaso-nuxt-ui';

export default defineConfig({
  plugins: [vue(), ui(vikasoNuxtUi())],
});

Both parts are required. The CSS import holds the colour mapping and tells Tailwind to scan the theme's classes, which it would otherwise skip because they live in node_modules.

Usage (Nuxt)

Use the same CSS imports in app/assets/css/main.css, then:

// app/app.config.ts
import { vikasoNuxtUi } from 'vikaso-nuxt-ui';

export default defineAppConfig({ ui: vikasoNuxtUi().ui });

App layers

vikasoNuxtUi(...layers) is the whole API. Each layer has the shape of the Nuxt UI plugin options and is merged on top of the previous one:

// src/assets/nuxtui.options.ts
import { vikasoNuxtUi } from 'vikaso-nuxt-ui';

export default vikasoNuxtUi({
  ui: {
    popover: { slots: { content: 'z-50' } },
  },
});

Keep app layers to layout and feature tweaks (z-index, offsets, compact sizes). Remove any compoundVariants that hard-code colours, or they keep overriding the theme.

Component libraries

A library built on Nuxt UI declares @nuxt/ui and vikaso-nuxt-ui as peer dependencies and keeps @nuxt/ui external. Nuxt UI components read their theme from build-time modules that only the app's ui() plugin provides, so the app passes vikasoNuxtUi() once and the library's components follow it. Put component-specific classes in the component (:ui prop or class), never in app config, because consuming apps would not have them. Use ui(vikasoNuxtUi()) in the library's Storybook so stories match the apps.

What the theme styles

Base elements

Elements Nuxt UI has no component for: body text, h1 to h3, number fields without spinners, scrollbars, and plain tables (table:not([data-slot])). No other stylesheet is needed.

UTable gets the same look from the table.* tokens: bordered and rounded, header background, striped rows, centred cells. Header text wraps; cell text truncates.

Surfaces

Tailwind utilities for the surface tokens, which follow the tokens' opaque fallbacks:

tailwind-merge resolves them against Nuxt UI's own classes, so bg-glass replaces bg-default.

Every floating surface is glass: popovers, tooltips, dropdown and context menus, select, select menu and input menu lists, the navigation menu viewport, editor menus, toasts, modals (not fullscreen), slideovers and drawers. The command palette takes the glass of the modal or popover it sits in. The overlays behind modals, slideovers and drawers use the backdrop, and form fields the field surface.

Accessibility

• Focus: Nuxt UI draws keyboard focus as a 3px outline at 25% of the colour, 1.39 to 2.18:1 against VIKASO backgrounds. WCAG 2.2 AA (1.4.11) needs 3:1, so the theme restores the full colour (4.54:1 or more).
• Never add focus:outline-none to a layer: it also hides Nuxt UI's focus-visible outline.
• Solid variants put one text-inverted colour on every fill. The tokens' on colours are chosen to pass on each fill.
• Secondary is a tonal grey that Nuxt UI's colour recipe does not suit. For button, badge, kbd and alert, solid secondary uses text-on-secondary, and the outline, soft, subtle and ghost variants use neutral's surfaces (bg-elevated, ring-accented). Other components with color="secondary" keep Nuxt UI's recipe on the grey.