ComponentsGitHubWebsite

Design system

Vueless enhances Tailwind CSS theming with a flexible design system, featuring pre-configured color aliases and CSS variables. This enables seamless customization and effortless UI adaptation to match your brand’s aesthetic.

Colors

Vueless utilizes the Vueless config to define customizable color aliases based on Tailwind CSS colors.

Color
Default
Description

primary

grayscale

The primary brand color, used as the default for components.

secondary

gray

A secondary color that complements the primary color.

success

green

A color used for success states.

error

red

A color used for danger states or form error validation.

warning

orange

A color used for warning states.

notice

violet

A color used for highlighted informational states.

info

blue

A color used for informational states.

grayscale

gray

Contrasted neutral color.

neutral

gray

Neutral gray color for backgrounds, text, etc.

Tokens

Vueless uses 40+ CSS variables as design tokens to ensure consistent and flexible component styling. These tokens form the foundation of the theming system, providing seamless support for light and dark modes. Applied across all components, they can be customized through the Vueless config.

Color Shades

Vueless automatically generates three CSS variables and defines custom Tailwind CSS color utilities for each color alias.

Here’s an example of an error color:

CSS variable
Tailwind CSS class example
Description

--vl-error

bg-error

Default shade.

--vl-error-lifted

bg-error-lifted

Darker shade (e.g., for hover states).

--vl-error-accented

bg-error-accented

Darkest shade (e.g., for active states).

You can use this colors just like any regular Tailwind CSS colors or use CSS variable in a utility class directly bg-(--vl-error).

To override specific color shades, define them in your application’s Vueless config or main CSS file, as shown in the example below (which includes all available shades with their default values).

vueless.config.{js,ts}
export default {
  lightTheme: {
    /* Primary colors */
    "--vl-primary": "--vl-primary-600",
    "--vl-primary-lifted": "--vl-primary-700",
    "--vl-primary-accented": "--vl-primary-800",

    /* Secondary colors */
    "--vl-secondary": "--vl-neutral-500",
    "--vl-secondary-lifted": "--vl-neutral-600",
    "--vl-secondary-accented": "--vl-neutral-700",

    /* Success colors */
    "--vl-success": "--color-green-600",
    "--vl-success-lifted": "--color-green-700",
    "--vl-success-accented": "--color-green-800",

    /* Info colors */
    "--vl-info": "--color-blue-600",
    "--vl-info-lifted": "--color-blue-700",
    "--vl-info-accented": "--color-blue-800",

    /* Notice colors */
    "--vl-notice": "--color-violet-600",
    "--vl-notice-lifted": "--color-violet-700",
    "--vl-notice-accented": "--color-violet-800",

    /* Warning colors */
    "--vl-warning": "--color-orange-600",
    "--vl-warning-lifted": "--color-orange-700",
    "--vl-warning-accented": "--color-orange-800",

    /* Error colors */
    "--vl-error": "--color-red-600",
    "--vl-error-lifted": "--color-red-700",
    "--vl-error-accented": "--color-red-800",

    /* Grayscale colors */
    "--vl-grayscale": "--vl-neutral-900",
    "--vl-grayscale-lifted": "--vl-neutral-800",
    "--vl-grayscale-accented": "--vl-neutral-700",

    /* Neutral colors */
    "--vl-neutral": "--vl-neutral-500",
    "--vl-neutral-lifted": "--vl-neutral-600",
    "--vl-neutral-accented": "--vl-neutral-700",
  },
};

Neutral Shades

Vueless automatically generates five CSS variables and defines custom Tailwind utility classes for text, border and background neutral colors.

To override specific color shades, define them in your application’s Vueless config or main CSS file, as shown in the example below (which includes all available shades).

vueless.config.{js,ts}
export default {
  lightTheme: {
    /* Text neutral colors */
    "--vl-text-inverted": "--color-white",
    "--vl-text-muted": "--vl-neutral-400",
    "--vl-text-lifted": "--vl-neutral-500",
    "--vl-text-accented": "--vl-neutral-600",
    "--vl-text": "--vl-neutral-900",

    /* Border neutral colors */
    "--vl-border-muted": "--vl-neutral-200",
    "--vl-border": "--vl-neutral-300",
    "--vl-border-lifted": "--vl-neutral-400",
    "--vl-border-accented": "--vl-neutral-600",    

    /* Background neutral colors */
    "--vl-bg": "--color-white",
    "--vl-bg-muted": "--vl-neutral-50",
    "--vl-bg-lifted": "--vl-neutral-100",
    "--vl-bg-accented": "--vl-neutral-200",
    "--vl-bg-inverted": "--vl-neutral-900",
  },
};

Text neutral colors

CSS variable
Tailwind CSS utility class
Description

--vl-text-inverted

text-inverted

Text to show on inverted backgrounds.

--vl-text-muted

text-muted

Disabled / placeholder state text.

--vl-text-lifted

text-lifted

Description / supportive text.

--vl-text-accented

text-accented

Active state text.

--vl-text

text-default

Contrast text.

You can use this colors as an CSS variable in a utility class directly text-(--vl-text-muted).

Border neutral colors

CSS variable
Tailwind CSS utility class
Description

--vl-border-muted

border-muted

Lighter border (e.g., for disabled states).

--vl-border

border-default

Default border.

--vl-border-lifted

border-lifted

Darker border (e.g., for hover states).

--vl-border-accented

border-accented

Darkest border (e.g., for active states).

You can use this colors as an CSS variable in a utility class directly border-(--vl-border-accented).

Background neutral colors

CSS variable
Tailwind CSS utility class
Description

--vl-bg

bg-default

Unfilled background.

--vl-bg-muted

bg-muted

Slightly filled background.

--vl-bg-lifted

bg-lifted

Filled background.

--vl-bg-accented

bg-accented

Pretty filled background.

--vl-bg-inverted

bg-inverted

Contrast background.

You can use this colors as an CSS variable in a utility class directly bg-(--vl-bg-muted).

Redefining colors

You can use the following color types as color value: CSS variable (or just their name), HEX, RGB, RGBA, HSL, HSLA and OKLCH.

vueless.config.{js,ts}
export default {
  lightTheme: {
    "--vl-primary": "--vl-primary-600",                   // css variable name
    "--vl-primary-lifted": "var(--vl-primary-700)",       // css variable
    "--vl-primary-accented": "#0d597f",                   // hex
  },
  darkTheme: {
    "--vl-primary": "rgba(65, 190, 239, 1)",              // rgba
    "--vl-primary-lifted": "hsl(197, 81%, 48%)",          // hsl
    "--vl-primary-accented": "oklch(0.59 0.1273 237.97)", // oklch
  },
};

Component colors restriction

Some components — such as UAvatar, UButton, ULink ... — include a color prop with a predefined list of available colors. To globally customize this list (either by restricting or extending it), use the colors configuration key.

vueless.config.{js,ts}
export default {
  colors: ["success", "error", "primary"],
}

Runtime color switching

If you want to allow users to switch primary or neutral colors at runtime, define them using the runtimeColors configuration key. It can be set to either an array of color names or true to enable all supported colors. Vueless automatically safelists CSS variables for all Tailwind color shades to support this functionality.

vueless.config.{js,ts}
export default {
  runtimeColors: ["amber", "rose", "fuchsia", "teal"],
  /* OR */
  runtimeColors: true,
}

Last updated