124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
---
|
||
navigation:
|
||
icon: i-lucide-paint-roller
|
||
title: Theme
|
||
description: Custom the appearance of your Docus documentation thanks to Nuxt UI
|
||
flexible theming.
|
||
---
|
||
|
||
Docus is built on top of Nuxt UI and takes full advantage of Tailwind CSS v4, CSS variables. The Tailwind Variants API offers a flexible and scalable theming system.
|
||
|
||
::prose-tip{to="https://ui.nuxt.com/getting-started/theme"}
|
||
For a full overview of Nuxt UI theming, check out the Nuxt UI documentation.
|
||
::
|
||
|
||
## Override with `@theme`
|
||
|
||
You can customize your theme with CSS variables inside a [`@theme`](https://tailwindcss.com/docs/functions-and-directives#theme-directive) directive to define your project's custom design tokens, like fonts, colors, and breakpoints
|
||
|
||
You can override this theme by creating your own `main.css` file in your application.
|
||
|
||
::warning
|
||
To ensure a good behaviour with Docus, you must always start by importing `tailwindcss` and `ui-pro` but also source `content/` files and `app.config.ts` :
|
||
|
||
```css [app/assets/css/main.css]
|
||
@import "tailwindcss";
|
||
@import "@nuxt/ui-pro";
|
||
|
||
@source "../../../content/**/*";
|
||
@source "../../../node_modules/docus/app/**/*";
|
||
```
|
||
::
|
||
|
||
This way you can override your theme:
|
||
|
||
::code-group
|
||
```css [assets/css/main.css]
|
||
@import "tailwindcss";
|
||
@import "@nuxt/ui-pro";
|
||
|
||
@source "../../../content/**/*";
|
||
@source "../../../node_modules/docus/app/**/*";
|
||
|
||
@theme static {
|
||
--font-sans: 'Public Sans', sans-serif;
|
||
|
||
--breakpoint-3xl: 1920px;
|
||
|
||
--color-green-50: #EFFDF5;
|
||
--color-green-100: #D9FBE8;
|
||
--color-green-200: #B3F5D1;
|
||
--color-green-300: #75EDAE;
|
||
--color-green-400: #00DC82;
|
||
--color-green-500: #00C16A;
|
||
--color-green-600: #00A155;
|
||
--color-green-700: #007F45;
|
||
--color-green-800: #016538;
|
||
--color-green-900: #0A5331;
|
||
--color-green-950: #052E16;
|
||
}
|
||
```
|
||
|
||
```ts [nuxt.config.ts]
|
||
export default defineNuxtConfig({
|
||
modules: ['@nuxt/ui-pro'],
|
||
css: ['~/assets/css/main.css']
|
||
})
|
||
```
|
||
::
|
||
|
||
## Colors
|
||
|
||
Docus uses pre-configured color aliases that are used to style components and power the `color` props across the UI.
|
||
|
||
Each badge below represents a default alias:
|
||
|
||
- :u-badge{label="primary" variant="outline"} → Main brand color, used as the default color for components :br [(default: green)]{.text-xs.text-muted}
|
||
- :u-badge{color="secondary" label="secondary" variant="outline"} → Secondary color to complement the primary color :br [(default: blue)]{.text-xs.text-muted}
|
||
- :u-badge{color="success" label="success" variant="outline"} → Used for success states :br [(default: green)]{.text-xs.text-muted}
|
||
- :u-badge{color="info" label="info" variant="outline"} → Used for informational states :br [(default: blue)]{.text-xs.text-muted}
|
||
- :u-badge{color="warning" label="warning" variant="outline"} → Used for warning states :br [(default: yellow)]{.text-xs.text-muted}
|
||
- :u-badge{color="error" label="error" variant="outline"} → Used for form error validation states :br [(default: red)]{.text-xs.text-muted}
|
||
- :u-badge{color="neutral" label="neutral" variant="outline"} → Neutral color for backgrounds, text, etc. :br [(default: slate)]{.text-xs.text-muted}
|
||
|
||
You can customize these colors globally by updating the `app.config.ts` file under the `ui.colors` key:
|
||
|
||
```ts [app.config.ts]
|
||
export default defineAppConfig({
|
||
ui: {
|
||
colors: {
|
||
primary: 'blue',
|
||
neutral: 'zinc'
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
## Components
|
||
|
||
Beyond colors, all [Nuxt UI components](https://ui.nuxt.com/components) can be themed globally via `app.config.ts`.
|
||
|
||
You can override any component’s appearance by using the same structure as the component’s internal theme object (displayed at [the end of each component page](https://ui.nuxt.com/components/card#theme)).
|
||
|
||
For example, to change the font weight of all buttons:
|
||
|
||
```ts [app.config.ts]
|
||
export default defineAppConfig({
|
||
ui: {
|
||
button: {
|
||
slots: {
|
||
base: 'font-bold'
|
||
}
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
In this example, the `font-bold` class will override the default `font-medium` class on all buttons.
|
||
|
||
::prose-note{to="https://ui.nuxt.com/components/button#theme"}
|
||
To explore the available theme options for each component, refer to the **Theme** section in their respective Nuxt UI documentation page.
|
||
::
|
||
|
||
##
|