arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-28 10:50:40 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(getting-started): update

Browse Source
This commit is contained in:
Benjamin Canac
2024-09-17 16:36:14 +02:00
parent 1f5372baba
commit df72003516
7 changed files with 237 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/content/1.getting-started/4.colors.md
View File

@@ -1,13 +1,10 @@
---
description: 'Learn how to customize the look and feel of the components.'
navigation:
badge:
label: Todo
description: 'Learn how to customize colors and optimize your color palette for Nuxt UI components.'
---
## Color variant
## Build colors
In the previous section, we explored how components have themes that can include `variants`, which are reflected in their props. One common variant is `color`. Let's examine this using the [Button](/components/button) component as an example:
Nuxt UI components provide dynamic `color` variants. By default, these variants classes are generated based on the default Tailwind CSS colors. Let's take the [Button](/components/button) component as an example:
::component-code{slug="button"}
---
@@ -18,28 +15,11 @@ slots:
---
::
These `color` variants are generated based on the default Tailwind CSS colors, you can change this by using the [`colors`](/getting-started/installation#colors) option in your `nuxt.config.ts` to select only the colors you're actually using.
You can change these colors with the [`colors`](/getting-started/installation#colors) option in your `nuxt.config.ts` to select only the colors you're actually using.
For example, you've added a custom `cerise` color and only use the default `blue` and `green` colors in your application.
For example, if you added a custom `cerise` color and only use the default `blue` and `green` colors in your application, you can configure the `colors` option like this:
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-cerise-50: #fef2f4;
--color-cerise-100: #fde6e9;
--color-cerise-200: #fbd0d9;
--color-cerise-300: #f7aab9;
--color-cerise-400: #f27a93;
--color-cerise-500: #e63f66;
--color-cerise-600: #d42a5b;
--color-cerise-700: #b21e4b;
--color-cerise-800: #951c45;
--color-cerise-900: #801b40;
--color-cerise-950: #470a1f;
}
```
::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
@@ -50,7 +30,31 @@ export default defineNuxtConfig({
})
```
This configuration will ensure that only classes for those three colors are generated in your final CSS bundle and that the `color` prop will be typed and provide autocompletion in your editor with those three colors.
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-cerise-50: #FEF2F4;
--color-cerise-100: #FDE6E9;
--color-cerise-200: #FBD0D9;
--color-cerise-300: #F7AAB9;
--color-cerise-400: #F27A93;
--color-cerise-500: #E63F66;
--color-cerise-600: #D42A5B;
--color-cerise-700: #B21E4B;
--color-cerise-800: #951C45;
--color-cerise-900: #801B40;
--color-cerise-950: #470A1F;
}
```
::
::caution
Make sure to use color ranges from `50` to `950`. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
::
This configuration will ensure that only classes for those three colors are generated in your final CSS bundle. When you use the `color` prop, it will be typed and provide autocompletion in your editor with those three colors.
```vue
<template>
@@ -58,30 +62,100 @@ This configuration will ensure that only classes for those three colors are gene
</template>
```
::caution
Make sure to use color ranges from `50` to `950` when you define your colors. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
::
## Runtime colors
Nuxt UI generates CSS variables for color management. Among these, you'll find `primary` and `gray` color aliases, which are specifically introduced by Nuxt UI to simplify component styling and provide a consistent color scheme across your application.
### Default aliases
You can configure those aliases in your `app.config.ts` file under the `ui.colors` key:
Nuxt UI introduces three key color aliases used to style components:
- The `gray` alias can be any of the default Tailwind CSS colors: `slate`, `cool` (renamed from `gray`), `zinc`, `neutral` or `stone`. Defaults to `cool`.
- The `primary` alias can be any of the other colors including your custom ones. Defaults to `green`.
1. `primary`{color="primary"}: Main brand color. Default: `green`{color="green"}.
2. `error`{color="error"}: For error states. Default: `red`{color="red"}.
3. `gray`: Neutral color for backgrounds, text, etc. Default: `cool`.
::warning{to="https://tailwindcss.com/docs/customizing-colors#default-color-palette" target="_blank"}
The Tailwind CSS `gray` color is renamed to `cool` in Nuxt UI to avoid conflicts with the `gray` alias.
::
You can configure these aliases in your `app.config.ts` file under the `ui.colors` key:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
colors: {
primary: 'cerise',
primary: 'blue',
error: 'red',
gray: 'zinc'
}
}
})
```
This powerful feature leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file), enabling dynamic styling of all components at runtime. It allows for real-time theme customization without requiring an application rebuild.
::tip
The aliases colors can be removed from the `colors` option in your `nuxt.config.ts` if you don't use them specifically. For example if `primary`'s target is `cerise` you don't have to select `cerise`, this will reduce the bundle even more.
We recommend using these colors in your application whenever possible with classes like `text-primary-500 dark:text-primary-400`, `border-gray-200 dark:border-gray-800` or `bg-white dark:bg-gray-900` for example.
::
::important
These alias colors don't need to be explicitly listed in the `colors` option of your `nuxt.config.ts`. Also, if you've set `primary` to a custom color (e.g., `cerise`), you don't need to list `cerise` in the `colors` array.
::
::note
You can try this out by clicking on the :prose-icon{name="i-heroicons-swatch-20-solid" class="text-primary-500 dark:text-primary-400"} button in the header of this documentation.
::
### Custom aliases
You can also add your own color aliases to be configurable at runtime in your `app.config.ts` file:
1. Define the alias color by using CSS variables to let Tailwind know about it:
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-secondary-50: var(--color-secondary-50);
--color-secondary-100: var(--color-secondary-100);
--color-secondary-200: var(--color-secondary-200);
--color-secondary-300: var(--color-secondary-300);
--color-secondary-400: var(--color-secondary-400);
--color-secondary-500: var(--color-secondary-500);
--color-secondary-600: var(--color-secondary-600);
--color-secondary-700: var(--color-secondary-700);
--color-secondary-800: var(--color-secondary-800);
--color-secondary-900: var(--color-secondary-900);
--color-secondary-950: var(--color-secondary-950);
}
```
2. Set a default value for the color alias in your `app.config.ts` file:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
colors: {
secondary: 'indigo'
}
}
})
```
3. Add this color to the `colors` option of your `nuxt.config.ts` file to generate classes:
```ts [nuxt.config.ts]
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
ui: {
colors: ['secondary']
}
})
```
4. You can use the `secondary` color alias in your application and use classes like `text-secondary-500 dark:text-secondary-400`:
```vue
<template>
<UButton color="secondary">Button</UButton>
</template>
```