@umbra.ui/core 0.1.0

package/src/components/pickers/ColorPicker/README.md

@@ -0,0 +1,1439 @@
+# ColorPicker
+
+A comprehensive color picker component built with Vue 3 Composition API and TypeScript. The ColorPicker provides an intuitive interface for selecting colors from a curated palette with support for customizable dot styling, smart positioning using Floating UI, and comprehensive color information display.
+
+## Installation/Import
+
+```typescript
+import { ColorPicker } from "@umbra-ui/core";
+import type { Color, ColorGroup } from "@umbra-ui/core";
+import { colors, colorPickerColors, colorGroups } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+const selectedColor = ref<Color>(colorPickerColors.gray700);
+
+const handleColorChange = (color: Color) => {
+  console.log("Selected color:", color);
+  console.log("Color name:", color.name);
+  console.log("Color weight:", color.weight);
+  console.log("Color hex:", color.hex);
+};
+</script>
+
+<template>
+  <div class="app">
+    <h2>Choose a Color</h2>
+
+    <ColorPicker
+      v-model:color="selectedColor"
+      @update:color="handleColorChange"
+    />
+
+    <div v-if="selectedColor" class="color-info">
+      <div
+        class="color-preview"
+        :style="{ backgroundColor: selectedColor.hex }"
+      />
+      <div class="color-details">
+        <h3>{{ selectedColor.name }}({{ selectedColor.weight }})</h3>
+        <p>{{ selectedColor.hex }}</p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.app {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.color-info {
+  margin-top: 20px;
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 8px;
+}
+
+.color-preview {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  border: 2px solid #e9ecef;
+}
+
+.color-details h3 {
+  margin: 0 0 4px 0;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.color-details p {
+  margin: 0;
+  color: #6c757d;
+  font-family: monospace;
+}
+</style>
+```
+
+## Props
+
+| Prop Name              | Type               | Required | Default                                        | Description                                     |
+| ---------------------- | ------------------ | -------- | ---------------------------------------------- | ----------------------------------------------- |
+| `color`                | `Color`            | Yes      | `colorPickerColors.gray700`                    | Currently selected color                        |
+| `pickerOffsetX`        | `number`           | No       | `0`                                            | Horizontal offset for picker positioning        |
+| `preventPopup`         | `boolean`          | No       | `false`                                        | Whether to prevent the popup from opening       |
+| `dotSize`              | `number \| string` | No       | `"1.25rem"`                                    | Size of the color dot                           |
+| `dotRadius`            | `number \| string` | No       | `"999px"`                                      | Border radius of the color dot                  |
+| `dotBorderWidth`       | `number`           | No       | `1`                                            | Border width of the color dot                   |
+| `dotBorderColor`       | `string`           | No       | `"var(--colorpicker-dot-border-color)"`        | Border color of the color dot                   |
+| `dotBorderColorActive` | `string`           | No       | `"var(--colorpicker-dot-border-color-active)"` | Border color when picker is open                |
+| `showColorInfo`        | `boolean`          | No       | `true`                                         | Whether to show color information in the picker |
+
+## Color Interface
+
+```typescript
+interface Color {
+  name: string | null;
+  hex: string;
+  weight: number | null;
+}
+```
+
+### Color Properties
+
+| Property | Type             | Description                               |
+| -------- | ---------------- | ----------------------------------------- |
+| `name`   | `string \| null` | Color name (e.g., "Gray", "Blue")         |
+| `hex`    | `string`         | Hexadecimal color value (e.g., "#374151") |
+| `weight` | `number \| null` | Color weight/shade (e.g., 200, 500, 700)  |
+
+## Events
+
+| Event Name     | Payload Type | Description                      |
+| -------------- | ------------ | -------------------------------- |
+| `update:color` | `Color`      | Emitted when a color is selected |
+
+## Available Colors
+
+The ColorPicker includes a comprehensive palette of 200 colors across 25 color groups:
+
+### Color Groups
+
+- **Neutrals**: Gray, Zinc, Neutral, Stone
+- **Warm Colors**: Red, Orange, Amber, Yellow
+- **Cool Colors**: Lime, Green, Emerald, Teal, Cyan, Sky, Blue, Indigo
+- **Purple Tones**: Violet, Purple, Fuchsia
+- **Pink Tones**: Pink, Rose
+
+### Color Weights
+
+Each color group includes 8 weight variations:
+
+- **200**: Lightest shade
+- **300**: Light shade
+- **400**: Medium-light shade
+- **500**: Medium shade (base color)
+- **600**: Medium-dark shade
+- **700**: Dark shade
+- **800**: Darker shade
+- **900**: Darkest shade
+
+### Accessing Colors
+
+```typescript
+import { colorPickerColors, colors, colorGroups } from "@umbra-ui/core";
+
+// Access by name and weight
+const blue500 = colorPickerColors.blue500; // { name: "Blue", hex: "#3B82F6", weight: 500 }
+
+// Access all colors
+const allColors = colors; // Array of all 200 colors
+
+// Access color groups
+const blueGroup = colorGroups.find((group) => group.name === "Blue");
+```
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.color-picker {
+  --picker-button-bg: #ffffff;
+  --picker-button-border: 1px solid #e9ecef;
+  --picker-button-hover-bg: #f8f9fa;
+  --picker-button-hover-border: 1px solid #dee2e6;
+  --picker-button-hover-shadow: rgba(0, 0, 0, 0.1);
+  --picker-button-hover-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-button-selected-bg: #e3f2fd;
+  --picker-button-selected-shadow: rgba(0, 0, 0, 0.1);
+  --picker-button-selected-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-picker-bg: #ffffff;
+  --picker-picker-border: 1px solid #e9ecef;
+  --picker-picker-shadow: rgba(0, 0, 0, 0.1);
+  --picker-picker-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-selection-bar-bg: #f8f9fa;
+  --picker-selection-bar-text: #212529;
+  --picker-selection-bar-border: #e9ecef;
+  --picker-border-light: #e9ecef;
+  --picker-overlay-bg: rgba(0, 0, 0, 0.1);
+  --colorpicker-picker-shadow: none;
+  --colorpicker-color-cell-border: #838383;
+  --colorpicker-color-cell-selected-border: #ffffff;
+  --colorpicker-color-dot-bg: #ffffff;
+  --colorpicker-dot-border-color: #9ca3af;
+  --colorpicker-dot-border-color-active: #374151;
+}
+```
+
+### Container Styling
+
+```css
+.color-picker {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  max-width: fit-content;
+}
+```
+
+### Button Styling
+
+```css
+.color-picker .button {
+  border-radius: 0.353rem;
+  padding: 0.588rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background-color: var(--picker-button-bg);
+  border: var(--picker-button-border);
+  transition: all 0.3s ease;
+}
+```
+
+### Picker Styling
+
+```css
+.color-picker .picker {
+  position: absolute;
+  background-color: var(--picker-picker-bg);
+  border-radius: 0.353rem;
+  z-index: 1000;
+  overflow: auto;
+  box-shadow: var(--colorpicker-picker-shadow);
+  border: var(--picker-picker-border);
+}
+```
+
+### Color Grid Styling
+
+```css
+.color-picker .color_list {
+  display: grid;
+  grid-template-columns: repeat(8, 1fr);
+  gap: 0.706rem;
+  padding: 0.706rem;
+}
+
+.color-picker .color_cell {
+  width: 1.412rem;
+  height: 1.412rem;
+  border: 1px solid var(--colorpicker-color-cell-border);
+  border-radius: 999px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: transform 0.3s ease, scale 0.3s ease;
+}
+```
+
+## Examples
+
+### Theme Color Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+const themeColors = [
+  colorPickerColors.blue500,
+  colorPickerColors.green500,
+  colorPickerColors.purple500,
+  colorPickerColors.orange500,
+  colorPickerColors.red500,
+  colorPickerColors.teal500,
+];
+
+const selectedThemeColor = ref<Color>(colorPickerColors.blue500);
+
+const handleThemeColorChange = (color: Color) => {
+  console.log("Theme color changed to:", color);
+  // Apply theme color to your application
+  document.documentElement.style.setProperty("--primary-color", color.hex);
+};
+</script>
+
+<template>
+  <div class="theme-selector">
+    <div class="selector-header">
+      <h3>Theme Colors</h3>
+      <p>Choose your application's primary color</p>
+    </div>
+
+    <ColorPicker
+      v-model:color="selectedThemeColor"
+      :dot-size="32"
+      :dot-radius="8"
+      :dot-border-width="2"
+      @update:color="handleThemeColorChange"
+    />
+
+    <div class="theme-preview">
+      <div
+        class="preview-header"
+        :style="{ backgroundColor: selectedThemeColor.hex }"
+      >
+        <h4>Preview</h4>
+      </div>
+      <div class="preview-content">
+        <p>
+          This is how your theme will look with {{ selectedThemeColor.name }}({{
+            selectedThemeColor.weight
+          }})
+        </p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.theme-selector {
+  padding: 24px;
+  max-width: 500px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 24px;
+}
+
+.selector-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.theme-preview {
+  margin-top: 24px;
+  border-radius: 8px;
+  overflow: hidden;
+  border: 1px solid #e2e8f0;
+}
+
+.preview-header {
+  padding: 16px;
+  color: white;
+}
+
+.preview-header h4 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.preview-content {
+  padding: 16px;
+  background: #f7fafc;
+}
+
+.preview-content p {
+  margin: 0;
+  color: #4a5568;
+}
+</style>
+```
+
+### Custom Dot Styling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+const selectedColor = ref<Color>(colorPickerColors.emerald500);
+
+const handleColorChange = (color: Color) => {
+  console.log("Selected color:", color);
+};
+</script>
+
+<template>
+  <div class="custom-styling">
+    <h3>Custom Dot Styling</h3>
+
+    <div class="picker-row">
+      <div class="picker-item">
+        <h4>Square Dot</h4>
+        <ColorPicker
+          v-model:color="selectedColor"
+          :dot-size="24"
+          :dot-radius="4"
+          :dot-border-width="2"
+          dot-border-color="#e2e8f0"
+          dot-border-color-active="#4299e1"
+          @update:color="handleColorChange"
+        />
+      </div>
+
+      <div class="picker-item">
+        <h4>Large Round Dot</h4>
+        <ColorPicker
+          v-model:color="selectedColor"
+          :dot-size="40"
+          :dot-radius="999"
+          :dot-border-width="3"
+          dot-border-color="#cbd5e0"
+          dot-border-color-active="#2b6cb0"
+          @update:color="handleColorChange"
+        />
+      </div>
+
+      <div class="picker-item">
+        <h4>Small Dot</h4>
+        <ColorPicker
+          v-model:color="selectedColor"
+          :dot-size="16"
+          :dot-radius="999"
+          :dot-border-width="1"
+          dot-border-color="#a0aec0"
+          dot-border-color-active="#1a365d"
+          @update:color="handleColorChange"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-styling {
+  padding: 24px;
+  max-width: 600px;
+}
+
+.picker-row {
+  display: flex;
+  gap: 32px;
+  margin-top: 20px;
+}
+
+.picker-item {
+  text-align: center;
+}
+
+.picker-item h4 {
+  font-size: 14px;
+  font-weight: 500;
+  color: #4a5568;
+  margin: 0 0 12px 0;
+}
+</style>
+```
+
+### Color Palette Builder
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors, colorGroups } from "@umbra-ui/core";
+import type { Color, ColorGroup } from "@umbra-ui/core";
+
+const selectedColors = ref<Color[]>([
+  colorPickerColors.blue500,
+  colorPickerColors.green500,
+  colorPickerColors.orange500,
+]);
+
+const addColor = (color: Color) => {
+  if (!selectedColors.value.find((c) => c.hex === color.hex)) {
+    selectedColors.value.push(color);
+  }
+};
+
+const removeColor = (colorToRemove: Color) => {
+  selectedColors.value = selectedColors.value.filter(
+    (color) => color.hex !== colorToRemove.hex
+  );
+};
+
+const clearPalette = () => {
+  selectedColors.value = [];
+};
+</script>
+
+<template>
+  <div class="palette-builder">
+    <div class="builder-header">
+      <h3>Color Palette Builder</h3>
+      <p>Build your custom color palette</p>
+    </div>
+
+    <div class="color-picker-section">
+      <h4>Add Colors</h4>
+      <ColorPicker
+        :color="colorPickerColors.gray500"
+        @update:color="addColor"
+      />
+    </div>
+
+    <div class="palette-section">
+      <div class="palette-header">
+        <h4>Your Palette ({{ selectedColors.length }} colors)</h4>
+        <button
+          @click="clearPalette"
+          class="clear-btn"
+          v-if="selectedColors.length > 0"
+        >
+          Clear All
+        </button>
+      </div>
+
+      <div v-if="selectedColors.length === 0" class="empty-palette">
+        <p>
+          No colors selected yet. Choose colors above to build your palette.
+        </p>
+      </div>
+
+      <div v-else class="palette-grid">
+        <div
+          v-for="color in selectedColors"
+          :key="color.hex"
+          class="palette-item"
+        >
+          <div class="palette-color" :style="{ backgroundColor: color.hex }" />
+          <div class="palette-info">
+            <p class="color-name">{{ color.name }}({{ color.weight }})</p>
+            <p class="color-hex">{{ color.hex }}</p>
+          </div>
+          <button @click="removeColor(color)" class="remove-btn">×</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.palette-builder {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.builder-header {
+  margin-bottom: 32px;
+}
+
+.builder-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.builder-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.color-picker-section {
+  margin-bottom: 32px;
+}
+
+.color-picker-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.palette-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 16px;
+}
+
+.palette-header h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0;
+}
+
+.clear-btn {
+  padding: 6px 12px;
+  background: #fed7d7;
+  color: #c53030;
+  border: none;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.clear-btn:hover {
+  background: #feb2b2;
+}
+
+.empty-palette {
+  padding: 32px;
+  text-align: center;
+  background: #f7fafc;
+  border-radius: 8px;
+  border: 2px dashed #cbd5e0;
+}
+
+.empty-palette p {
+  color: #718096;
+  margin: 0;
+}
+
+.palette-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 16px;
+}
+
+.palette-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px;
+  background: #f7fafc;
+  border-radius: 8px;
+  border: 1px solid #e2e8f0;
+}
+
+.palette-color {
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  border: 2px solid #e2e8f0;
+  flex-shrink: 0;
+}
+
+.palette-info {
+  flex: 1;
+}
+
+.color-name {
+  font-size: 14px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 2px 0;
+}
+
+.color-hex {
+  font-size: 12px;
+  color: #718096;
+  font-family: monospace;
+  margin: 0;
+}
+
+.remove-btn {
+  width: 24px;
+  height: 24px;
+  background: #fed7d7;
+  color: #c53030;
+  border: none;
+  border-radius: 50%;
+  font-size: 16px;
+  font-weight: bold;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.2s ease;
+}
+
+.remove-btn:hover {
+  background: #feb2b2;
+}
+</style>
+```
+
+### Brand Color Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+interface BrandColors {
+  primary: Color;
+  secondary: Color;
+  accent: Color;
+  neutral: Color;
+}
+
+const brandColors = ref<BrandColors>({
+  primary: colorPickerColors.blue600,
+  secondary: colorPickerColors.gray600,
+  accent: colorPickerColors.orange500,
+  neutral: colorPickerColors.gray300,
+});
+
+const updateBrandColor = (key: keyof BrandColors, color: Color) => {
+  brandColors.value[key] = color;
+  console.log(`Updated ${key} color:`, color);
+};
+
+const generateCSS = () => {
+  const css = `
+:root {
+  --brand-primary: ${brandColors.value.primary.hex};
+  --brand-secondary: ${brandColors.value.secondary.hex};
+  --brand-accent: ${brandColors.value.accent.hex};
+  --brand-neutral: ${brandColors.value.neutral.hex};
+}`;
+  console.log("Generated CSS:", css);
+  return css;
+};
+</script>
+
+<template>
+  <div class="brand-selector">
+    <div class="selector-header">
+      <h3>Brand Color System</h3>
+      <p>Define your brand's color palette</p>
+    </div>
+
+    <div class="color-sections">
+      <div class="color-section">
+        <h4>Primary Color</h4>
+        <ColorPicker
+          :color="brandColors.primary"
+          @update:color="(color) => updateBrandColor('primary', color)"
+        />
+        <div class="color-details">
+          <p>
+            {{ brandColors.primary.name }}({{ brandColors.primary.weight }})
+          </p>
+          <p class="hex">{{ brandColors.primary.hex }}</p>
+        </div>
+      </div>
+
+      <div class="color-section">
+        <h4>Secondary Color</h4>
+        <ColorPicker
+          :color="brandColors.secondary"
+          @update:color="(color) => updateBrandColor('secondary', color)"
+        />
+        <div class="color-details">
+          <p>
+            {{ brandColors.secondary.name }}({{ brandColors.secondary.weight }})
+          </p>
+          <p class="hex">{{ brandColors.secondary.hex }}</p>
+        </div>
+      </div>
+
+      <div class="color-section">
+        <h4>Accent Color</h4>
+        <ColorPicker
+          :color="brandColors.accent"
+          @update:color="(color) => updateBrandColor('accent', color)"
+        />
+        <div class="color-details">
+          <p>{{ brandColors.accent.name }}({{ brandColors.accent.weight }})</p>
+          <p class="hex">{{ brandColors.accent.hex }}</p>
+        </div>
+      </div>
+
+      <div class="color-section">
+        <h4>Neutral Color</h4>
+        <ColorPicker
+          :color="brandColors.neutral"
+          @update:color="(color) => updateBrandColor('neutral', color)"
+        />
+        <div class="color-details">
+          <p>
+            {{ brandColors.neutral.name }}({{ brandColors.neutral.weight }})
+          </p>
+          <p class="hex">{{ brandColors.neutral.hex }}</p>
+        </div>
+      </div>
+    </div>
+
+    <div class="brand-preview">
+      <h4>Brand Preview</h4>
+      <div class="preview-card">
+        <div
+          class="preview-header"
+          :style="{ backgroundColor: brandColors.primary.hex }"
+        >
+          <h5>Your Brand</h5>
+        </div>
+        <div class="preview-content">
+          <p>This is how your brand colors work together.</p>
+          <button
+            class="preview-btn"
+            :style="{
+              backgroundColor: brandColors.accent.hex,
+              color: brandColors.neutral.hex,
+            }"
+          >
+            Call to Action
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <div class="css-output">
+      <h4>Generated CSS</h4>
+      <pre class="css-code">{{ generateCSS() }}</pre>
+    </div>
+  </div>
+</template>
+
+<style module>
+.brand-selector {
+  padding: 24px;
+  max-width: 800px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 32px;
+}
+
+.selector-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.color-sections {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 24px;
+  margin-bottom: 32px;
+}
+
+.color-section {
+  text-align: center;
+}
+
+.color-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.color-details {
+  margin-top: 12px;
+}
+
+.color-details p {
+  margin: 0 0 4px 0;
+  font-size: 14px;
+  color: #4a5568;
+}
+
+.color-details .hex {
+  font-family: monospace;
+  font-size: 12px;
+  color: #718096;
+}
+
+.brand-preview {
+  margin-bottom: 32px;
+}
+
+.brand-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-card {
+  border-radius: 8px;
+  overflow: hidden;
+  border: 1px solid #e2e8f0;
+}
+
+.preview-header {
+  padding: 16px;
+  color: white;
+}
+
+.preview-header h5 {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+.preview-content {
+  padding: 16px;
+  background: #f7fafc;
+}
+
+.preview-content p {
+  margin: 0 0 16px 0;
+  color: #4a5568;
+}
+
+.preview-btn {
+  padding: 8px 16px;
+  border: none;
+  border-radius: 6px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: opacity 0.2s ease;
+}
+
+.preview-btn:hover {
+  opacity: 0.9;
+}
+
+.css-output h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.css-code {
+  background: #1a202c;
+  color: #e2e8f0;
+  padding: 16px;
+  border-radius: 8px;
+  font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
+  font-size: 14px;
+  line-height: 1.5;
+  overflow-x: auto;
+  margin: 0;
+}
+</style>
+```
+
+### Disabled State Example
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+const selectedColor = ref<Color>(colorPickerColors.blue500);
+const isDisabled = ref(false);
+
+const toggleDisabled = () => {
+  isDisabled.value = !isDisabled.value;
+};
+</script>
+
+<template>
+  <div class="disabled-example">
+    <h3>Disabled State</h3>
+
+    <div class="controls">
+      <button @click="toggleDisabled" class="toggle-btn">
+        {{ isDisabled ? "Enable" : "Disable" }} Color Picker
+      </button>
+    </div>
+
+    <ColorPicker
+      v-model:color="selectedColor"
+      :prevent-popup="isDisabled"
+      :dot-size="28"
+      :dot-border-width="2"
+    />
+
+    <div class="status">
+      <p>Status: {{ isDisabled ? "Disabled" : "Enabled" }}</p>
+      <p>Selected: {{ selectedColor.name }}({{ selectedColor.weight }})</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.disabled-example {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.controls {
+  margin-bottom: 20px;
+}
+
+.toggle-btn {
+  padding: 8px 16px;
+  background: #4299e1;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-weight: 500;
+  transition: background 0.2s ease;
+}
+
+.toggle-btn:hover {
+  background: #3182ce;
+}
+
+.status {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.status p {
+  margin: 0 0 8px 0;
+  color: #4a5568;
+}
+
+.status p:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Color Palette
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ColorPicker } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+// Define custom colors
+const customColors: Color[] = [
+  { name: "Brand Blue", hex: "#1e40af", weight: null },
+  { name: "Brand Green", hex: "#059669", weight: null },
+  { name: "Brand Orange", hex: "#ea580c", weight: null },
+  { name: "Brand Purple", hex: "#7c3aed", weight: null },
+  { name: "Brand Pink", hex: "#db2777", weight: null },
+  { name: "Brand Teal", hex: "#0d9488", weight: null },
+];
+
+const selectedColor = ref<Color>(customColors[0]);
+
+const handleColorChange = (color: Color) => {
+  console.log("Custom color selected:", color);
+};
+</script>
+
+<template>
+  <div class="custom-palette">
+    <h3>Custom Color Palette</h3>
+
+    <ColorPicker
+      v-model:color="selectedColor"
+      @update:color="handleColorChange"
+    />
+
+    <div class="custom-colors">
+      <h4>Available Custom Colors</h4>
+      <div class="color-grid">
+        <div
+          v-for="color in customColors"
+          :key="color.hex"
+          class="color-item"
+          :class="{ active: selectedColor.hex === color.hex }"
+          @click="selectedColor = color"
+        >
+          <div class="color-swatch" :style="{ backgroundColor: color.hex }" />
+          <p class="color-label">{{ color.name }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-palette {
+  padding: 24px;
+  max-width: 500px;
+}
+
+.custom-colors {
+  margin-top: 24px;
+}
+
+.custom-colors h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.color-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
+  gap: 16px;
+}
+
+.color-item {
+  text-align: center;
+  cursor: pointer;
+  padding: 12px;
+  border-radius: 8px;
+  transition: background 0.2s ease;
+}
+
+.color-item:hover {
+  background: #f7fafc;
+}
+
+.color-item.active {
+  background: #e6fffa;
+  border: 2px solid #38b2ac;
+}
+
+.color-swatch {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  margin: 0 auto 8px;
+  border: 2px solid #e2e8f0;
+}
+
+.color-label {
+  font-size: 12px;
+  color: #4a5568;
+  margin: 0;
+}
+</style>
+```
+
+### Color Accessibility Checker
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { ColorPicker, colorPickerColors } from "@umbra-ui/core";
+import type { Color } from "@umbra-ui/core";
+
+const selectedColor = ref<Color>(colorPickerColors.blue500);
+const backgroundColor = ref<Color>(colorPickerColors.white);
+
+// Simple contrast ratio calculation
+const getContrastRatio = (color1: string, color2: string) => {
+  const getLuminance = (hex: string) => {
+    const rgb = parseInt(hex.slice(1), 16);
+    const r = (rgb >> 16) & 0xff;
+    const g = (rgb >> 8) & 0xff;
+    const b = (rgb >> 0) & 0xff;
+
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+      c = c / 255;
+      return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    });
+
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+  };
+
+  const lum1 = getLuminance(color1);
+  const lum2 = getLuminance(color2);
+  const brightest = Math.max(lum1, lum2);
+  const darkest = Math.min(lum1, lum2);
+
+  return (brightest + 0.05) / (darkest + 0.05);
+};
+
+const contrastRatio = computed(() => {
+  return getContrastRatio(selectedColor.value.hex, backgroundColor.value.hex);
+});
+
+const accessibilityLevel = computed(() => {
+  const ratio = contrastRatio.value;
+  if (ratio >= 7) return { level: "AAA", color: "#059669" };
+  if (ratio >= 4.5) return { level: "AA", color: "#d97706" };
+  if (ratio >= 3) return { level: "AA Large", color: "#dc2626" };
+  return { level: "Fail", color: "#dc2626" };
+});
+</script>
+
+<template>
+  <div class="accessibility-checker">
+    <h3>Color Accessibility Checker</h3>
+
+    <div class="color-inputs">
+      <div class="color-input">
+        <h4>Text Color</h4>
+        <ColorPicker v-model:color="selectedColor" :dot-size="24" />
+      </div>
+
+      <div class="color-input">
+        <h4>Background Color</h4>
+        <ColorPicker v-model:color="backgroundColor" :dot-size="24" />
+      </div>
+    </div>
+
+    <div class="preview-section">
+      <h4>Preview</h4>
+      <div
+        class="preview-text"
+        :style="{
+          color: selectedColor.hex,
+          backgroundColor: backgroundColor.hex,
+        }"
+      >
+        This is how your text will look with these colors.
+      </div>
+    </div>
+
+    <div class="accessibility-results">
+      <h4>Accessibility Results</h4>
+      <div class="results-grid">
+        <div class="result-item">
+          <span class="result-label">Contrast Ratio:</span>
+          <span class="result-value">{{ contrastRatio.toFixed(2) }}:1</span>
+        </div>
+        <div class="result-item">
+          <span class="result-label">WCAG Level:</span>
+          <span
+            class="result-value"
+            :style="{ color: accessibilityLevel.color }"
+          >
+            {{ accessibilityLevel.level }}
+          </span>
+        </div>
+      </div>
+
+      <div class="recommendations">
+        <h5>Recommendations:</h5>
+        <ul>
+          <li v-if="contrastRatio < 4.5">
+            Consider using a darker text color or lighter background for better
+            readability
+          </li>
+          <li v-if="contrastRatio >= 4.5 && contrastRatio < 7">
+            Good contrast! Consider aiming for AAA level (7:1) for even better
+            accessibility
+          </li>
+          <li v-if="contrastRatio >= 7">
+            Excellent contrast! This meets WCAG AAA standards
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.accessibility-checker {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.color-inputs {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 24px;
+  margin-bottom: 32px;
+}
+
+.color-input {
+  text-align: center;
+}
+
+.color-input h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-section {
+  margin-bottom: 32px;
+}
+
+.preview-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-text {
+  padding: 24px;
+  border-radius: 8px;
+  font-size: 18px;
+  font-weight: 500;
+  text-align: center;
+  border: 2px solid #e2e8f0;
+}
+
+.accessibility-results h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.results-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.result-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px;
+  background: #f7fafc;
+  border-radius: 6px;
+}
+
+.result-label {
+  font-weight: 500;
+  color: #4a5568;
+}
+
+.result-value {
+  font-weight: 600;
+  color: #2d3748;
+}
+
+.recommendations {
+  padding: 16px;
+  background: #f0f9ff;
+  border-radius: 8px;
+  border-left: 4px solid #0ea5e9;
+}
+
+.recommendations h5 {
+  font-size: 14px;
+  font-weight: 600;
+  color: #0c4a6e;
+  margin: 0 0 8px 0;
+}
+
+.recommendations ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.recommendations li {
+  font-size: 14px;
+  color: #0c4a6e;
+  margin-bottom: 4px;
+}
+</style>
+```
+
+## Performance Considerations
+
+- **Floating UI**: Smart positioning with automatic updates and cleanup
+- **Teleport**: Overlay and picker are teleported to body for proper z-index management
+- **Event Cleanup**: Proper cleanup of auto-update listeners on unmount
+- **Color Grid**: Efficient 8-column grid layout for optimal performance
+- **Computed Styles**: Dot styles are computed reactively for smooth animations
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for keyboard interaction
+- **Screen Reader Support**: Proper ARIA labels and semantic structure
+- **Focus Management**: Focus is properly managed during interactions
+- **Color Information**: Displays color names, weights, and hex values
+- **High Contrast**: Supports high contrast mode with appropriate borders
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 88+
+- **CSS Features**: Uses CSS Grid and modern layout features
+- **JavaScript**: Requires ES2020+ support
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Picker not positioning correctly**: Ensure the trigger button has proper positioning context
+2. **Colors not displaying**: Check that the colors array is properly imported
+3. **Dot not updating**: Verify the v-model binding is correctly set up
+4. **Overlay not closing**: Ensure the overlay click handler is properly bound
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { ColorPicker } from "@umbra-ui/core";
+
+const selectedColor = ref(null);
+
+// Watch for changes
+watch(selectedColor, (newColor) => {
+  console.log("Selected color changed:", newColor);
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `v-model:color`
+- Event names have been updated to use kebab-case
+- Color system has been updated with comprehensive palette
+- Floating UI integration has been improved
+
+### Breaking Changes
+
+- Removed `value` prop in favor of `v-model:color`
+- Changed event names from camelCase to kebab-case
+- Updated color prop to use Color interface instead of string
+- Modified CSS class naming convention