docs: update

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

@@ -0,0 +1,184 @@
+---
+description: 'Learn how to customize the look and feel of the components.'
+---
+
+This module relies on Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) file to customize the look and feel of the components at runtime with HMR (hot-module-replacement).
+
+## Colors
+
+### Configuration
+
+Components are based on a `primary` and a `gray` color. You can change them in your `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    primary: 'green',
+    gray: 'cool'
+  }
+})
+```
+
+::callout{icon="i-heroicons-light-bulb"}
+Try to change the `primary` and `gray` colors by clicking on the :u-icon{name="i-heroicons-swatch-20-solid" class="w-4 h-4 align-middle text-primary-500 dark:text-primary-400"} button in the header.
+::
+
+As this module uses Tailwind CSS under the hood, you can use any of the [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. By default, the `primary` color is `green` and the `gray` color is `cool`.
+
+When [using custom colors](https://tailwindcss.com/docs/customizing-colors#using-custom-colors) or [adding additional colors](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) through the `extend` key in your `tailwind.config.ts`, you'll need to make sure to define all the shades from `50` to `950` as most of them are used in the components config defined in [`ui.config/`](https://github.com/nuxt/ui/tree/dev/src/runtime/ui.config) directory. You can [generate your colors](https://tailwindcss.com/docs/customizing-colors#generating-colors) using tools such as https://uicolors.app/ for example.
+
+```ts [tailwind.config.ts]
+import type { Config } from 'tailwindcss'
+import defaultTheme from 'tailwindcss/defaultTheme'
+
+export default <Partial<Config>>{
+  theme: {
+    extend: {
+      colors: {
+        green: {
+          50: '#EFFDF5',
+          100: '#D9FBE8',
+          200: '#B3F5D1',
+          300: '#75EDAE',
+          400: '#00DC82',
+          500: '#00C16A',
+          600: '#00A155',
+          700: '#007F45',
+          800: '#016538',
+          900: '#0A5331',
+          950: '#052e16'
+        }
+      }
+    }
+  }
+}
+```
+
+### CSS Variables
+
+To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As Tailwind CSS already has a `gray` color, the module automatically renames it to `cool` to avoid conflicts (`coolGray` was renamed to `gray` when Tailwind CSS v3.0 was released).
+
+Likewise, you can't define a `primary` color in your `tailwind.config.ts` as it would conflict with the `primary` color defined by the module.
+
+::callout{icon="i-heroicons-light-bulb"}
+We'd advise you to use those colors in your components and pages, e.g. `text-primary-500 dark:text-primary-400`, `bg-gray-100 dark:bg-gray-900`, etc. so your app automatically adapts when changing your `app.config.ts`.
+::
+
+The `primary` color also has a `DEFAULT` shade that changes based on the theme. It is `500` in light mode and `400` in dark mode. You can use as a shortcut in your components and pages, e.g. `text-primary`, `bg-primary`, `focus-visible:ring-primary`, etc.
+
+## Components
+
+### `app.config.ts`
+
+You can find the config of each component in the [`ui.config/`](https://github.com/nuxt/ui/tree/dev/src/runtime/ui.config) directory. You can override those classes in your own `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    container: {
+      constrained: 'max-w-5xl'
+    }
+  }
+})
+```
+
+Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `app.config.ts` is smartly merged with the default config. This means you don't have to rewrite everything.
+
+You can change this behavior by setting `strategy` to `override` in your `app.config.ts`:
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    strategy: 'override',
+    button: {
+      color: {
+        white: {
+          solid: 'bg-white dark:bg-gray-900'
+        }
+      }
+    }
+  }
+})
+```
+
+### `ui` prop
+
+Each component has a `ui` prop that allows you to customize everything specifically.
+
+```vue
+<template>
+  <UContainer :ui="{ constrained: 'max-w-2xl' }">
+    <slot />
+  </UContainer>
+</template>
+```
+
+::callout{icon="i-heroicons-light-bulb"}
+You can find the default classes for each component under the `Config` section.
+::
+
+Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `ui` prop is smartly merged with the config. This means you don't have to rewrite everything.
+
+For example, the default preset of the `FormGroup` component looks like this:
+
+```json
+{
+  "label": {
+    "base": "block font-medium text-gray-700 dark:text-gray-200"
+  }
+}
+```
+
+To change the font of the `label`, you only need to write:
+
+```vue
+<UFormGroup name="email" label="Email" :ui="{ label: { base: 'font-semibold' } }" />
+```
+
+This will smartly replace the `font-medium` by `font-semibold` and prevent any class duplication and any class priority issue.
+
+You can change this behavior by setting `strategy` to `override` inside the `ui` prop:
+
+```vue
+<UButton
+  to="https://github.com/nuxt/ui"
+  :ui="{
+    strategy: 'override',
+    color: {
+      white: {
+        solid: 'bg-white dark:bg-gray-900'
+      }
+    }
+  }"
+/>
+```
+
+### `class` attribute
+
+You can also use the `class` attribute to add classes to the component.
+
+```vue
+<template>
+  <UButton label="Button" class="rounded-full" />
+</template>
+```
+
+Again, with [tailwind-merge](https://github.com/dcastil/tailwind-merge), this will smartly merge the classes with the `ui` prop and the config.
+
+### Default values
+
+Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    button: {
+      default: {
+        size: 'md',
+        color: 'gray',
+        variant: 'ghost'
+      }
+    }
+  }
+})
+```