docs(getting-started): update

docs/content/1.getting-started/2.installation.md

@@ -91,7 +91,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::note{to="/getting-started/colors#color-variant"}
+::note{to="/getting-started/colors#build-colors"}
 This can help reduce the number of CSS classes generated in your bundle.
 ::
 

docs/content/1.getting-started/3.theme.md

@@ -33,12 +33,12 @@ Tailwind CSS v4 takes a CSS-first configuration approach, you now customize your
 
 The `@theme` directive tells Tailwind to make new utilities and variants available based on those variables. It's the equivalent of the `theme.extend` key in Tailwind CSS v3 `tailwind.config.ts` file.
 
-This is exactly what the [`@nuxt/ui`](https://github.com/nuxt/ui/blob/v3/src/runtime/index.css) import is all about, it declares the `primary`, `error` and `gray` colors to be configurable through the [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) but we'll talk more about that in the [Colors](/getting-started/colors) section.
-
 ::note
-You can learn more about this on https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration.
+You can learn more about this on [https://tailwindcss.com/blog/tailwindcss-v4-alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration).
 ::
 
+This is exactly what the [`@import "@nuxt/ui";`](https://github.com/nuxt/ui/blob/v3/src/runtime/index.css) is all about, it extends the default Tailwind CSS theme and declares the `primary`, `error` and `gray` colors to be configurable through the [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) but we'll talk more about that in the [Colors](/getting-started/colors) section.
+
 ## Tailwind Variants API
 
 Nuxt UI components are styled using the [Tailwind Variants](https://www.tailwind-variants.org/) API, which provides a powerful way to create variants and manage component styles. Let's explore the key features of this API:
@@ -213,7 +213,7 @@ In this example, the `leadingIcon` slot is overwritten even though the `md` size
 
 ### `class` prop
 
-The `class` prop allows you to override the classes of the `root` slot or the `base` slot when the component has no slots.
+The `class` prop allows you to override the classes of the `root` or `base` slot. This has priority over the `app.config.ts` configuration and `variants` resolution.
 
 ::component-code{slug="button"}
 ---

docs/content/1.getting-started/4.colors.md

@@ -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,38 +30,132 @@ 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>
   <UButton color="cerise">Button</UButton>
 </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
+
+Nuxt UI introduces three key color aliases used to style components:
 
-You can configure those aliases in your `app.config.ts` file under the `ui.colors` key:
+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.
+::
 
-- 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`.
+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>
+```

docs/content/1.getting-started/5.icons.md

@@ -1,38 +1,54 @@
 ---
-description: ''
+description: 'Nuxt UI integrates seamlessly with `@nuxt/icon`, providing access to over 200,000+ icons from [Iconify](https://iconify.design/).'
 links:
   - label: 'nuxt/icon'
     to: https://github.com/nuxt/icon
     target: _blank
     icon: i-simple-icons-github
-navigation:
-  badge:
-    label: Todo
 ---
 
-Thanks to [`@nuxt/icon`](https://github.com/nuxt/icon), add 200,000+ ready to use icons to your Nuxt application based on [Iconify](https://iconify.design).
+## Usage
 
-You can use any name from the https://icones.js.org collection such as the `i-` prefix (for example, `i-heroicons-cog`) with:
+Nuxt UI automatically registers the `@nuxt/icon` module for you, so there's no additional setup required.
 
-- any `icon` prop available across the components:
+::note
+You can use any name from the https://icones.js.org collection.
+::
 
-```vue
-<template>
-  <UButton icon="i-heroicons-magnifying-glass" />
-</template>
-```
+### Icon Component
 
-- the `UIcon` component to use icons anywhere:
+You can use the [Icon](/components/icon) component with a `name` prop to display an icon:
 
-```vue
-<template>
-  <UIcon name="i-heroicons-moon" class="w-5 h-5 text-primary-500" />
-</template>
-```
+::component-code{slug="icon"}
+---
+props:
+  name: 'i-heroicons-light-bulb'
+  class: 'size-5'
+---
+::
+
+### Component Props
+
+Some components also have an `icon` prop to display an icon, like the [Button](/components/button) for example:
+
+::component-code{slug="button"}
+---
+ignore:
+  - color
+  - variant
+props:
+  icon: i-heroicons-sun
+  variant: subtle
+slots:
+  default: Button
+---
+::
 
-### Collections
+## Collections
 
-It's highly recommended to install the icons collections locally with:
+### Iconify Dataset
+
+It's highly recommended to install the icon data locally with:
 
 ::code-group
 
@@ -52,10 +68,52 @@ npm install @iconify-json/{collection_name}
 
 For example, to use the `i-uil-github` icon, install it's collection with `@iconify-json/uil`. This way the icons can be served locally or from your serverless functions, which is faster and more reliable on both SSR and client-side.
 
-::callout{icon="i-heroicons-light-bulb" to="https://github.com/nuxt/icon?tab=readme-ov-file#custom-local-collections" target="_blank"}
-Read more about custom collections in the `@nuxt/icon` documentation.
+::tip{to="https://github.com/nuxt/icon?tab=readme-ov-file#iconify-dataset" target="_blank"}
+Read more about this in the `@nuxt/icon` documentation.
+::
+
+### Custom Local Collections
+
+You can use local SVG files to create a custom Iconify collection.
+
+For example, place your icons' SVG files under a folder of your choice, for example, `./assets/icons`:
+
+```bash
+assets/icons
+├── add.svg
+└── remove.svg
+```
+
+In your `nuxt.config.ts`, add an item in `icon.customCollections`:
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/ui'
+  ],
+  icon: {
+    customCollections: [{
+      prefix: 'custom',
+      dir: './assets/icons'
+    }]
+  }
+})
+```
+
+Then you can use the icons like this:
+
+```vue
+<template>
+  <UIcon name="i-custom-add" />
+</template>
+```
+
+::tip{to="https://github.com/nuxt/icon?tab=readme-ov-file#custom-local-collections" target="_blank"}
+Read more about this in the `@nuxt/icon` documentation.
 ::
 
 ## Theme
 
+You can change the default icons used by Nuxt UI components in your `app.config.ts`:
+
 :icons-theme