@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/superpowers/specs/2026-05-12-charting-design.md

@@ -0,0 +1,185 @@
+# VibeChart Components — Design Spec
+**Date:** 2026-05-12  
+**Status:** Approved
+
+## Overview
+
+Three canvas-based chart components for VibeUI: `VibeChartLine`, `VibeChartBar`, `VibeChartPie`. ES2022+, no external dependencies, Bootstrap CSS var color integration, `ResizeObserver`-driven responsiveness.
+
+## Architecture
+
+### File Structure
+
+```
+src/components/
+  VibeChartLine.vue
+  VibeChartBar.vue
+  VibeChartPie.vue
+
+src/components/chart/            ← internal only, not exported
+  chartColors.ts                 ← Bootstrap var resolver + cycler
+  chartTooltip.ts                ← canvas tooltip hit-test + render
+  chartResize.ts                 ← ResizeObserver setup/teardown
+  chartTypes.ts                  ← shared internal types
+```
+
+Three public components consume `chart/` internals directly. Nothing in `chart/` appears in `src/index.ts`. Each component owns its own `draw()` canvas function.
+
+### Approach
+
+- Approach B: three separate components with shared internal utilities
+- No exported composable — `chart/` is private infrastructure
+- No fallbacks, no defensive wrapping — trust the data
+- No animation, snap render only
+
+## Data Shape
+
+```ts
+// src/types.ts additions
+export interface ChartDataset {
+  label: string
+  data: number[]
+  color?: string        // overrides auto color for this series
+}
+
+export interface ChartData {
+  labels: string[]
+  datasets: ChartDataset[]
+}
+
+export type ChartLegendPosition = 'top' | 'bottom' | 'none'
+```
+
+## Props API
+
+### All three components
+
+| Prop | Type | Default |
+|------|------|---------|
+| `data` | `ChartData` | required |
+| `legend` | `ChartLegendPosition` | `'bottom'` |
+| `height` | `number \| string` | `'auto'` (16:9 ratio) |
+
+### VibeChartLine + VibeChartBar only
+
+| Prop | Type | Default |
+|------|------|---------|
+| `show-axes` | `boolean` | `true` |
+| `show-grid` | `boolean` | `true` |
+
+### VibeChartLine only
+
+| Prop | Type | Default |
+|------|------|---------|
+| `smooth` | `boolean` | `false` |
+| `fill` | `boolean` | `false` |
+
+### VibeChartBar only
+
+| Prop | Type | Default |
+|------|------|---------|
+| `stacked` | `boolean` | `false` |
+
+## Canvas Rendering
+
+### Resize
+
+```ts
+// chartResize.ts
+export function useChartResize(
+  container: Ref<HTMLElement | null>,
+  canvas: Ref<HTMLCanvasElement | null>,
+  onResize: (w: number, h: number) => void
+): void
+```
+
+- `ResizeObserver` on container div
+- Canvas pixel dims: `canvas.width = dpr * w`, `ctx.scale(dpr, dpr)` for HiDPI
+- Container: `width: 100%`, height auto = `w * (9/16)` or `height` prop
+- Set up in `onMounted`, torn down in `onUnmounted`
+
+### Draw cycle
+
+- `draw(ctx, data, w, h, props)` — pure function per component
+- `watch(() => props.data, redraw, { deep: true })` triggers on data change
+- Every resize calls `redraw()`
+- ES2022+: `Array.at()`, `Object.hasOwn()`, etc.
+
+## Color System
+
+```ts
+// chartColors.ts
+const BS_VARS = [
+  '--bs-primary', '--bs-success', '--bs-danger',
+  '--bs-warning', '--bs-info', '--bs-secondary',
+  '--bs-dark', '--bs-light'
+]
+
+export function resolveColors(
+  datasets: ChartDataset[],
+  el: HTMLElement
+): string[]
+```
+
+- Per-dataset `color` prop wins
+- Otherwise cycles `--bs-*` vars via `getComputedStyle(el)` at draw time
+- Dark mode automatic — reads current computed value each redraw
+- Cycles with `i % BS_VARS.length` for unlimited datasets
+
+## Tooltip
+
+```ts
+// chartTooltip.ts
+export interface TooltipHit {
+  datasetIndex: number
+  pointIndex: number
+  value: number
+  label: string
+}
+
+export function bindTooltip(
+  canvas: HTMLCanvasElement,
+  hitTest: (x: number, y: number) => TooltipHit | null,
+  redraw: () => void
+): () => void  // returns cleanup fn
+```
+
+- `mousemove` listener on canvas
+- Each component provides its own `hitTest(x, y)` fn
+- On hit: redraws base chart then draws rounded-rect overlay at cursor
+- `mouseleave`: clears tooltip (redraw base only)
+- Single canvas — no overlay element
+
+## Legend
+
+HTML, not canvas. Order in DOM determines visual position.
+
+```html
+<div v-if="legend !== 'none'" :class="['vibe-chart-legend', `vibe-chart-legend--${legend}`]">
+  <span v-for="(ds, i) in data.datasets" :key="i" class="vibe-chart-legend-item">
+    <span class="vibe-chart-legend-swatch" :style="{ background: resolvedColors[i] }"></span>
+    {{ ds.label }}
+  </span>
+</div>
+<canvas ref="canvasEl" />
+```
+
+- `legend="top"`: div before canvas
+- `legend="bottom"`: div after canvas
+- `legend="none"`: v-if removes it
+
+## Exports
+
+`src/types.ts`: add `ChartDataset`, `ChartData`, `ChartLegendPosition`
+
+`src/index.ts`:
+```ts
+export { default as VibeChartLine } from './components/VibeChartLine.vue'
+export { default as VibeChartBar } from './components/VibeChartBar.vue'
+export { default as VibeChartPie } from './components/VibeChartPie.vue'
+export type { ChartData, ChartDataset, ChartLegendPosition } from './types'
+```
+
+`src/components/index.ts`: register all three in plugin.
+
+No new peer dependencies. Zero external imports in chart code.

package/docs/superpowers/specs/2026-05-29-e2e-browser-testing-design.md

@@ -0,0 +1,168 @@
+# E2E Browser Testing — Design
+
+**Date:** 2026-05-29
+**Status:** Approved (design)
+**Topic:** Real-browser test coverage for the Bootstrap-JS + Quill integration paths the happy-dom unit suite cannot reach.
+
+## Problem
+
+The 925-test unit suite runs in happy-dom with Bootstrap JS mocked (`tests/mocks/bootstrap.ts`) and Quill unable to initialize. The integration layer that is hardest to get right — real Popper positioning, Bootstrap show/hide lifecycles and animations, and Quill editor behavior + DOMPurify sanitization — is therefore **unverified**. This is the top risk for a 1.0 commercial launch.
+
+Goal: add a real-browser test layer that executes the actual Bootstrap JS and Quill code paths, covering every interactive component, without slowing the existing unit inner loop.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Scope | All interactive paths: Overlays, Popper-positioned, Motion, Quill | "It all needs to work." |
+| Test framework | Vitest 4 browser mode | Already installed; same API as the 925 unit tests; bundles with our real Vite 8 — no second bundler, no version mismatch, nothing experimental in the framework layer. |
+| Browser driver | Playwright (provider) | Battle-tested headless Chromium driver. |
+| Mount helper | `vitest-browser-vue` (`render` + `expect.element`) | Vitest-native Vue mounting in the browser. |
+| Browsers | Chromium only | Integration bugs (Popper/Bootstrap/Quill) are engine-agnostic; keeps CI lean. Add WebKit later if needed. |
+| CI | Separate required `e2e` job | Blocks merge on failure; parallel to unit job. |
+
+Playwright Component Testing (`@playwright/experimental-ct-vue`) was rejected: it bundles with its own pinned Vite (≠ our Vite 8), and the framework layer is experimental. Vitest browser mode keeps our real Vite 8 pipeline and is stable in Vitest 4.
+
+## Architecture
+
+Two Vitest projects share one Vite 8 pipeline (`extends: true` inherits root `plugins: [vue()]`):
+
+- **`unit`** — happy-dom, `bootstrap → tests/mocks/bootstrap.ts` alias. Today's 925 tests, unchanged. The mock alias is scoped to this project only.
+- **`browser`** — real headless Chromium via the Playwright provider. **No bootstrap alias**, so components' own `import('bootstrap')` resolves the real package and the real Bootstrap JS executes for the first time. Real Quill (`new Quill()`) runs against a real contenteditable.
+
+```ts
+// vite.config.ts — test block
+test: {
+  projects: [
+    {
+      extends: true,
+      test: {
+        name: 'unit',
+        environment: 'happy-dom',
+        include: ['tests/**/*.test.ts'],
+        exclude: ['tests/browser/**'],
+        alias: { bootstrap: path.resolve(__dirname, 'tests/mocks/bootstrap.ts') }
+      }
+    },
+    {
+      extends: true,
+      test: {
+        name: 'browser',
+        include: ['tests/browser/**/*.browser.test.ts'],
+        setupFiles: ['tests/browser/setup.ts'],
+        browser: {
+          enabled: true,
+          provider: 'playwright',
+          headless: true,
+          instances: [{ browser: 'chromium' }]
+        }
+      }
+    }
+  ]
+}
+```
+
+New dev dependencies: `@vitest/browser`, `playwright`, `vitest-browser-vue`.
+
+Real dependency loading in the browser project:
+- Bootstrap CSS + Quill CSS imported once in `tests/browser/setup.ts`.
+- Bootstrap JS: never imported globally — pulled by components via their own dynamic `import('bootstrap')`, exercising the production path.
+- Quill: real package, real editor instance.
+
+## File Layout
+
+```
+tests/
+  browser/
+    setup.ts                      # imports bootstrap + quill CSS; per-test cleanup
+    helpers.ts                    # openModal(), waitForBsEvent(), getQuill()
+    overlays.browser.test.ts      # Modal, Offcanvas, Toast
+    popper.browser.test.ts        # Tooltip, Popover, Dropdown
+    motion.browser.test.ts        # Collapse, Accordion, Carousel, Tabs, Scrollspy
+    wysiwyg.browser.test.ts       # VibeFormWysiwyg / Quill
+```
+
+Mount pattern:
+```ts
+import { render } from 'vitest-browser-vue'
+import { expect, test } from 'vitest'
+import VibeModal from '../../src/components/VibeModal.vue'
+
+test('opens, traps focus, returns focus on close', async () => {
+  const screen = render(VibeModal, { props: { modelValue: true, title: 'Hi' } })
+  await expect.element(screen.getByRole('dialog')).toBeVisible()
+})
+```
+
+## Scripts (`package.json`)
+
+```jsonc
+"test": "vitest --project unit",            // fast inner loop, unchanged default
+"test:run": "vitest run --project unit",    // CI unit (name kept)
+"test:browser": "vitest run --project browser",
+"test:all": "vitest run"                    // both projects
+```
+
+`test` / `test:run` stay pinned to `unit` so the inner loop never pays browser-launch cost.
+
+## Coverage Matrix
+
+Only behavior happy-dom cannot reach (real Bootstrap JS / Popper / Quill). No re-testing prop/class logic the unit suite already covers.
+
+**overlays — Modal / Offcanvas / Toast**
+- Modal: `v-model=true` → `.modal.show` + `.modal-backdrop` present; ESC closes → `v-model=false`; focus returns to trigger on close; backdrop click closes; body scroll lock.
+- Offcanvas: open/close lifecycle, backdrop, ESC, focus return.
+- Toast: autohide timer fires → hidden; `v-model` sync.
+
+**popper — Tooltip / Popover / Dropdown**
+- Tooltip: hover → real Popper positions `.tooltip` with computed `transform`; leave → removed.
+- Popover: click → `.popover` shown + positioned; outside-click dismiss.
+- Dropdown: toggle → `.dropdown-menu.show` + Popper placement; ESC/outside close; keyboard arrow nav.
+
+**motion — Collapse / Accordion / Carousel / Tabs / Scrollspy**
+- Collapse: toggle → `.collapsing` transition → `.collapse.show`.
+- Accordion: opening one closes siblings (real Bootstrap).
+- Carousel: `next()` advances active item; indicators sync.
+- Tabs: click tab → pane `.active` swap, `.fade` handled.
+- Scrollspy: scroll container → active nav link tracks.
+
+**wysiwyg — VibeFormWysiwyg (our glue only; Quill's own behavior is not our project to test)**
+- Real `new Quill()` mounts the editor — proves our dynamic-import + init glue runs (path happy-dom cannot run).
+- Set HTML containing `<script>` / `onerror` → our `sanitizeHtml.ts` (DOMPurify) strips it. This is our security layer, exercised end-to-end in a real browser for the only time.
+
+Explicitly **not** tested (Quill's behavior, not ours): typing → v-model round-trip, toolbar formatting output, disabled/readonly editability.
+
+## CI Wiring
+
+New `e2e` job in `.github/workflows/ci.yml`, parallel to the unit job, required for merge:
+
+```yaml
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:browser
+```
+
+Existing unit job untouched (`npm run test:run` stays the `unit` project). Chromium-only install keeps the job lean.
+
+## Risks & Verification (resolved in a smoke phase before the full suite)
+
+- **`vitest-browser-vue` API shape** — verify `render` + `expect.element` against the installed version with a smoke spec (mount `VibeButton`, assert visible) before writing the four real specs. If the mount API differs, adjust the helper, not the architecture.
+- **Real Bootstrap JS resolution** — confirm the browser project resolves the real `bootstrap` (no mock-alias leak from root) by mounting `VibeModal` and asserting a real `.modal-backdrop` appears (the mock never creates one). Proves real Bootstrap JS executing.
+- **Animation timing** — real CSS transitions are async. Use `expect.element(...).toBeVisible()` polling and Bootstrap `shown.bs.*` events via a `waitForBsEvent` helper; never fixed `setTimeout`.
+- **Quill in CI** — real Quill needs real layout, which headless Chromium provides. This is the exact gap that motivated the work.
+
+No fallback path: each uncertainty resolves to a concrete smoke-phase check before the full suite is authored.
+
+## Out of Scope
+
+- Firefox / WebKit browsers (Chromium only for 1.0).
+- Visual regression / screenshot diffing.
+- Re-testing prop/class/validation logic already covered by the unit suite.

package/docs/utilities/position.md

@@ -0,0 +1,82 @@
+# Positioning Utilities
+
+VibeUI exposes Bootstrap 5.3's position utility classes directly through a Bootstrap CSS import. These are static, declarative classes — pair them with `usePosition` (see `docs/composables/use-position.md`) when you need JS-driven anchoring.
+
+## position-{value}
+
+| Class | Effect |
+|------|--------|
+| `.position-static` | Default flow positioning |
+| `.position-relative` | Relative to its normal position |
+| `.position-absolute` | Relative to nearest positioned ancestor |
+| `.position-fixed` | Relative to the viewport |
+| `.position-sticky` | Switches to fixed when scroll threshold passed |
+
+## top / start / bottom / end
+
+For `.position-absolute`, `.position-fixed`, `.position-sticky`: place the element along a side of the containing box.
+
+| Class | Position |
+|------|----------|
+| `.top-0` / `.top-50` / `.top-100` | 0%, 50%, 100% from top |
+| `.start-0` / `.start-50` / `.start-100` | 0%, 50%, 100% from inline-start |
+| `.bottom-0` / `.bottom-50` / `.bottom-100` | from bottom |
+| `.end-0` / `.end-50` / `.end-100` | from inline-end |
+
+## translate-middle
+
+Shifts the element by –50% on one or both axes — useful for centering relative to its anchor coordinate.
+
+| Class | Effect |
+|------|--------|
+| `.translate-middle` | `translate(-50%, -50%)` |
+| `.translate-middle-x` | `translate(-50%, 0)` |
+| `.translate-middle-y` | `translate(0, -50%)` |
+
+## Common patterns
+
+**Centering a card in its container:**
+
+```html
+<div class="position-relative" style="height: 200px;">
+  <div class="position-absolute top-50 start-50 translate-middle">
+    Centered
+  </div>
+</div>
+```
+
+**Sticky page header:**
+
+```html
+<header class="position-sticky top-0 bg-body z-3">
+  <!-- ... -->
+</header>
+```
+
+**Fixed FAB (floating action button):**
+
+```html
+<VibeButton variant="primary" class="position-fixed bottom-0 end-0 m-3 rounded-circle">
+  +
+</VibeButton>
+```
+
+**Notification badge offset on an avatar:**
+
+```html
+<div class="position-relative d-inline-block">
+  <img src="avatar.png" class="rounded-circle" />
+  <VibeBadge variant="danger" pill class="position-absolute top-0 start-100 translate-middle">
+    3
+  </VibeBadge>
+</div>
+```
+
+## When to reach for `usePosition` instead
+
+- The anchor is dynamic (not a parent in the DOM).
+- You need viewport collision handling (flip / shift).
+- You need to reposition on scroll, resize, or anchor mutation.
+- The placement is computed at runtime (e.g. picker calendars, autocomplete menus).
+
+For those cases, see [`usePosition`](../composables/use-position.md).

package/docs/versioning.md

@@ -0,0 +1,57 @@
+# Versioning & Stability Policy
+
+VibeUI follows [Semantic Versioning](https://semver.org/). This page defines what is covered by that promise so you can embed VibeUI in a long-lived project with confidence.
+
+## The promise
+
+Within a major version (e.g. all of `1.x`), the **public API does not break**. You can upgrade minor and patch releases without code changes.
+
+- **MAJOR** (`2.0.0`) — breaking changes to the public API.
+- **MINOR** (`1.1.0`) — new components, props, events, or composables, backwards-compatible.
+- **PATCH** (`1.0.1`) — bug fixes, internal changes, no API change.
+
+## What counts as public API
+
+Covered by the SemVer promise:
+
+- **Component names** and their registration (global plugin install + named exports).
+- **Props** — names, types, and documented default behavior.
+- **Events** (`emits`) — names and payload shapes.
+- **Slots** — names and slot-prop shapes.
+- **Composables** exported from the package entry (`useColorMode`, `useToast`, `useForm`, `useFormValidation`, `useBreakpoints`, `useId`, `usePosition`, `useBackButton`, etc.) — their call signatures and return shapes.
+- **Directives** exported from the entry (e.g. `vTooltip`).
+- **Published TypeScript types** for all of the above.
+
+## What is explicitly NOT covered
+
+These may change in any release, including patches:
+
+- **Escape hatches prefixed `_unsafe_`** (e.g. `_unsafe_bsInstance`). They expose the underlying Bootstrap/Quill instance and are not a stable interface — using them couples you to third-party internals at your own risk.
+- **Internal modules** not exported from the package entry (anything under `src/utils`, `src/injectionKeys`, internal composables, etc.).
+- **Generated DOM structure / CSS class composition** beyond what Bootstrap itself defines. We target Bootstrap 5.3 markup; we don't promise the exact wrapper nesting.
+- **Console warnings** (dev-only deprecation/validation messages).
+
+## Deprecation policy
+
+When a public API needs to change:
+
+1. The old form keeps working and emits a **dev-only deprecation warning** for at least one **minor** release.
+2. The replacement is documented alongside the deprecation.
+3. Removal happens only in the next **major**.
+
+(Example already in the codebase: the tooltip/popover `content` prop is deprecated in favor of `text` and still functions.)
+
+## Peer dependency policy
+
+VibeUI declares its framework requirements as peer dependencies:
+
+- **`vue` (required, `^3.5`)** and **`bootstrap` (required, `^5.3`)** — supported ranges. Raising the **minimum** supported version of either is a **major** change.
+- **`quill`, `dompurify`, `bootstrap-icons` (optional)** — needed only for `VibeFormWysiwyg` (quill + dompurify) and `VibeIcon` (bootstrap-icons). Absent unless you use those features.
+
+A new major of an upstream peer (Bootstrap 6, Quill 3, Vue 4) is adopted in a **major** VibeUI release, never a minor.
+
+## Recommendations for long-lived projects
+
+- **Pin a version** (`"@velkymx/vibeui": "1.4.2"`) or a tilde range (`~1.4.0`) rather than a wide caret, and upgrade deliberately.
+- Read `CHANGELOG.md` before upgrading minors.
+- The full test suite ships with the source — if you ever need to fork and patch, you inherit the regression safety net (unit + real-browser tests).

package/examples/README.md

@@ -0,0 +1,201 @@
+# VibeUI Examples
+
+This directory contains standalone HTML examples demonstrating how to use VibeUI components, similar to [Bootstrap's examples](https://getbootstrap.com/docs/5.3/examples/).
+
+## 🚀 Quick Start
+
+### Option 1: Open Directly in Browser
+Simply open any `.html` file in your browser:
+1. Build VibeUI first: `cd .. && npm run build`
+2. Open `examples/index.html` in your browser
+
+### Option 2: Use a Local Server
+For the best experience (especially with routing), serve the files:
+
+```bash
+# Using Python
+python -m http.server 8000
+
+# Using Node.js
+npx serve .
+
+# Using PHP
+php -S localhost:8000
+```
+
+Then open http://localhost:8000 in your browser.
+
+### Option 3: GitHub Pages
+The examples work perfectly on GitHub Pages! Just push to a repository and enable GitHub Pages.
+
+## 📁 Examples
+
+- **[index.html](index.html)** - Examples gallery homepage
+- **[starter.html](starter.html)** - Starter template with common components
+- **[album.html](album.html)** - Photo gallery with card grid
+- **[pricing.html](pricing.html)** - Pricing tables with comparison
+- **[dashboard.html](dashboard.html)** - Admin dashboard with sidebar
+
+## 🎯 How They Work
+
+Each example is a **standalone HTML file** that uses:
+
+1. **Vue 3** from CDN (`vue.global.prod.js`)
+2. **Bootstrap 5.3** from CDN
+3. **Bootstrap Icons** from CDN
+4. **VibeUI** from the local `dist/vibeui.umd.js` build
+
+### Example Structure
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+    <!-- Bootstrap Icons -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css">
+    <!-- VibeUI CSS -->
+    <link rel="stylesheet" href="../dist/vibeui.css">
+</head>
+<body>
+    <div id="app">
+        <!-- Use VibeUI components here -->
+        <vibe-button variant="primary">Click me!</vibe-button>
+    </div>
+
+    <!-- Vue 3 -->
+    <script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
+    <!-- Bootstrap JS -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+    <!-- VibeUI -->
+    <script src="../dist/vibeui.umd.js"></script>
+    <script>
+        const { createApp } = Vue;
+        createApp({
+            data() {
+                return {
+                    // Your data here
+                }
+            }
+        }).use(VibeUI.default).mount('#app');
+    </script>
+</body>
+</html>
+```
+
+## 🔧 Using with NPM Package
+
+To use the published VibeUI package from npm instead of the local build:
+
+1. Install VibeUI: `npm install @velkymx/vibeui`
+2. Copy examples to your project
+3. Update the script src to point to your node_modules:
+   ```html
+   <script src="/node_modules/@velkymx/vibeui/dist/vibeui.umd.js"></script>
+   ```
+
+Or use a CDN once VibeUI is published to npm:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@velkymx/vibeui"></script>
+```
+
+## 📦 Components Used
+
+### Starter Example
+- `vibe-navbar`, `vibe-navbar-brand`, `vibe-navbar-toggle`
+- `vibe-container`, `vibe-row`, `vibe-col`
+- `vibe-button`, `vibe-badge`, `vibe-alert`
+- `vibe-card`, `vibe-card-body`
+- `vibe-dropdown`, `vibe-dropdown-item`
+- `vibe-icon`
+
+### Album Example
+- `vibe-navbar`
+- `vibe-container`, `vibe-row`, `vibe-col`
+- `vibe-card`, `vibe-card-body`
+- `vibe-button`, `vibe-button-group`
+- `vibe-icon`
+
+### Pricing Example
+- `vibe-container`, `vibe-row`, `vibe-col`
+- `vibe-card`, `vibe-card-header`, `vibe-card-body`
+- `vibe-button`, `vibe-badge`
+- `vibe-nav`
+- `vibe-icon`
+
+### Dashboard Example
+- `vibe-container`, `vibe-row`, `vibe-col`
+- `vibe-card`, `vibe-card-body`
+- `vibe-list-group`, `vibe-list-group-item`
+- `vibe-button`, `vibe-button-group`, `vibe-badge`
+- `vibe-icon`
+
+## 🎨 Customization
+
+You can customize these examples by:
+
+1. **Modifying the data**: Change the `data()` function in the Vue app
+2. **Adding new components**: Use any VibeUI component from the library
+3. **Styling**: Add your own CSS or modify Bootstrap variables
+4. **Adding features**: Extend the Vue app with methods, computed properties, etc.
+
+## 📝 Example: Adding Your Own Data
+
+```html
+<script>
+const { createApp } = Vue;
+createApp({
+    data() {
+        return {
+            // Your custom data
+            products: [
+                { id: 1, name: 'Product 1', price: 29.99 },
+                { id: 2, name: 'Product 2', price: 39.99 }
+            ]
+        }
+    },
+    methods: {
+        addToCart(product) {
+            console.log('Added to cart:', product);
+        }
+    }
+}).use(VibeUI.default).mount('#app');
+</script>
+```
+
+## 🌐 Deployment
+
+These examples can be deployed anywhere:
+
+- **GitHub Pages**: Push to repo, enable Pages
+- **Netlify**: Drag & drop the folder
+- **Vercel**: Deploy as static site
+- **Any web server**: Upload the files
+
+Just make sure VibeUI is built first (`npm run build` in the root directory).
+
+## 🛠️ Development Workflow
+
+1. Make changes to VibeUI source code
+2. Build VibeUI: `cd .. && npm run build`
+3. Refresh the example in your browser
+4. Changes will be reflected immediately
+
+## ❓ Troubleshooting
+
+**Q: Examples don't load when opened directly**
+A: Make sure you've built VibeUI first: `cd .. && npm run build`
+
+**Q: Components aren't rendering**
+A: Check the browser console for errors. Make sure all script tags are loading correctly.
+
+**Q: Icons not showing**
+A: Verify the Bootstrap Icons CSS is loading from the CDN.
+
+**Q: Getting CORS errors**
+A: Use a local server instead of opening files directly (see Quick Start above).
+
+## 📄 License
+
+These examples are part of VibeUI and are licensed under the MIT License.