docs: lots of improvements

docs/content/1.getting-started/1.index.md

@@ -0,0 +1,36 @@
+---
+title: Introduction
+description: 'Components library as a Nuxt module using TailwindCSS and HeadlessUI.'
+---
+
+This module has been developed by the [NuxtLabs](https://nuxtlabs.com/) team for [Volta](https://volta.net) and [Nuxt Studio](https://nuxt.studio/), its goal is to provide everything related to UI when building a Nuxt app. This includes components, icons, colors, dark mode but also keyboard shortcuts.
+
+Components are built on top of [TailwindCSS](https://tailwindcss.com/) and [HeadlessUI](https://headlessui.com/) to provide a set of fully customizable components with dark mode support.
+
+::alert{icon="i-heroicons-light-bulb"}
+[Volta](https://volta.net/) entire UI is built with this module alongside the 50+ keyboard shortcuts defined.
+::
+
+## Features
+
+- Fully customizable components
+- HMR support through Nuxt App Config
+- Dark mode support
+- Keyboard shortcuts
+- Bundled icons
+- Fully typed
+
+## Credits
+
+- [nuxt/nuxt](https://github.com/nuxt/nuxt)
+- [nuxt-modules/color-mode](https://github.com/nuxt-modules/color-mode)
+- [nuxt-modules/tailwindcss](https://github.com/nuxt-modules/tailwindcss)
+- [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss)
+- [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)
+- [vueuse/vueuse](https://github.com/vueuse/vueuse)
+- [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons)
+- [krisk/fuse](https://github.com/krisk/Fuse)
+
+::alert{icon="i-heroicons-exclamation-triangle"}
+This documentation is still a work in progress and will be updated regularly.
+::

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

@@ -1,11 +1,8 @@
 ---
-title: 'nuxthq/ui'
-description: 'Components library as a Nuxt module using TailwindCSS and HeadlessUI.'
-navigation:
-  title: Installation
+description: 'Learn how to install and configure the module in your Nuxt app.'
 ---
 
-## Installation
+## Overview
 
 1. Install `@nuxthq/ui` dependency to your project:
 

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

@@ -1,5 +0,0 @@
----
-navigation: false
----
-
-## Overview

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

@@ -1,11 +0,0 @@
----
-navigation: false
----
-
-## Overview
-
-## Composables
-
-## `defineShortcuts`
-
-## `useShortcuts`

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

@@ -0,0 +1,167 @@
+---
+description: 'Learn how to customize the look and feel of the components.'
+---
+
+## Overview
+
+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
+
+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: 'sky',
+    gray: 'cool'
+  }
+})
+```
+
+As this module uses TailwindCSS under the hood, you can use any of the [TailwindCSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. By default, the `primary` color is `sky` and the `gray` color is `cool`.
+
+To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As TailwindCSS 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).
+
+::alert{icon="i-heroicons-light-bulb"}
+Try to change the `primary` and `gray` colors in the navbar and see the colors change live.
+::
+
+Components that have a `color` prop like [Avatar](/elements/avatar), [Badge](/elements/badge) and [Button](/elements/button) will use the `primary` color by default but will handle all the colors defined in your `tailwind.config.ts` or the default TailwindCSS colors.
+
+## Components
+
+Components are styled with TailwindCSS but classes are all defined in the default [app.config.ts](https://github.com/nuxtlabs/ui/blob/dev/src/runtime/app.config.ts) file. You can override them in your `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    container: {
+      constrained: 'max-w-5xl'
+    }
+  }
+})
+```
+
+Each component has a `ui` prop that allows you to customize everything specifically.
+
+```vue
+<template>
+  <UContainer :ui="{ constrained: 'max-w-2xl' }">
+    <slot />
+  </UContainer>
+</template>
+```
+
+::alert{icon="i-heroicons-light-bulb"}
+You can find the default classes for each component under the `Preset` section.
+::
+
+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'
+      }
+    }
+  }
+})
+```
+
+## Icons
+
+You can use any icon (100,000+) from [Iconify](https://iconify.design/).
+
+Most of the components have an `icon` prop that allows you to add an icon to the component.
+
+```vue
+<template>
+  <UButton icon="i-heroicons-magnifying-glass" />
+</template>
+```
+
+You can also use the [Icon](/elements/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.
+
+```vue
+<template>
+  <UIcon name="i-heroicons-moon" />
+</template>
+```
+
+By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ui: {
+    icons: ['mdi', 'simple-icons']
+  }
+})
+```
+
+::alert{icon="i-heroicons-light-bulb"}
+Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
+::
+
+Unlike the official [nuxt-icon](https://github.com/nuxt-modules/icon/) module, this module will not fetch any icon from the web and will only bundle the icons you use in your app thanks to [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons).
+
+However, you will need to install the icon packages you want to use.
+
+```sh
+yarn add --dev @iconify/json-{collection_name}
+```
+
+You can easily replace all the default icons of the components in your `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    button: {
+      default: {
+        loadingIcon: 'i-octicon-sync-24'
+      }
+    },
+    input: {
+      default: {
+        loadingIcon: 'i-octicon-sync-24'
+      }
+    },
+    select: {
+      default: {
+        trailingIcon: 'i-octicon-chevron-down-24'
+      }
+    },
+    selectMenu: {
+      default: {
+        selectedIcon: 'i-octicon-check-24'
+      }
+    },
+    notification: {
+      default: {
+        close: {
+          icon: 'i-octicon-x-24'
+        }
+      }
+    },
+    commandPalette: {
+      default: {
+        icon: 'i-octicon-search-24',
+        selectedIcon: 'i-octicon-check-24',
+        empty: {
+          icon: 'i-octicon-search-24'
+        }
+      }
+    }
+  }
+})
+```
+
+## Dark mode
+
+All the components are styled with dark mode in mind.
+
+Thanks to [TailwindCSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) `class` strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.

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

@@ -0,0 +1,65 @@
+---
+description: 'Learn how to display and define keyboard shortcuts in your app.'
+---
+
+## Overview
+
+Some components like [Dropdown](/elements/dropdown), [Command Palette](/navigation/command-palette) and [Tooltip](/overlays/tooltip) support the display of keyboard shortcuts.
+
+```vue
+<UDropdown :items="[{ label: 'Edit', shortcuts: ['E'] }]" />
+```
+
+Shortcuts are displayed and styled through the [Kbd](/elements/kbd) component.
+
+```vue
+<template>
+  <div class="flex items-center gap-0.5">
+    <UKbd>⌘</UKbd>
+    <UKbd>K</UKbd>
+  </div>
+</template>
+```
+
+::alert{icon="i-heroicons-light-bulb"}
+You will have a preview of how shortcuts are rendered in each component page.
+::
+
+## Composables
+
+### `defineShortcuts`
+
+This module provides a `defineShortcuts` composable that allows you to define keyboard shortcuts in your app really easily.
+
+```vue
+<template>
+  <UModal v-model="isOpen" />
+</template>
+
+<script setup lang="ts">
+const isOpen = ref(false)
+
+defineShortcuts({
+  meta_k: {
+    usingInput: true,
+    handler: () => {
+      isOpen.value = !isOpen.value
+    }
+  }
+})
+</script>
+```
+
+### `useShortcuts`
+
+To display shortcuts in your app according to the user's OS, you can use the `useShortcuts` composable.
+
+```vue
+<script setup>
+const { metaSymbol } = useShortcuts()
+</script>
+
+<template>
+  <UKbd>{{ metaSymbol }}</UKbd>
+</template>
+```