@equal-experts/kuat-vue 0.3.1 → 0.4.0

package/README.md

@@ -1,18 +1,30 @@
 # @equal-experts/kuat-vue
 
-A guide for integrating the Kuat Design System Vue component library into your application.
+Custom Vue components and blocks for the Kuat Design System.
 
 ---
 
-## Installation
+## Architecture
+
+This package provides **custom components** and **blocks** that are unique to Kuat. For standard UI components (Button, Dialog, etc.), install them directly via shadcn-vue CLI with kuat-core theming.
 
-### Prerequisites
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Application                                   │
+├─────────────────────────────────────────────────────┤
+│  Kuat Blocks (from this package)                    │
+├─────────────────────────────────────────────────────┤
+│  Kuat Components (from this package)                │
+├─────────────────────────────────────────────────────┤
+│  shadcn-vue Components (installed directly)         │
+├─────────────────────────────────────────────────────┤
+│  @equal-experts/kuat-core (design tokens)           │
+└─────────────────────────────────────────────────────┘
+```
 
-- Vue 3.4.0 or higher
-- Node.js 18 or higher
-- A package manager (npm, pnpm, or yarn)
+---
 
-### Install the Package
+## Installation
 
 ```bash
 # Using pnpm (recommended)
@@ -25,566 +37,264 @@ npm install @equal-experts/kuat-vue
 yarn add @equal-experts/kuat-vue
 ```
 
-### Install Peer Dependencies
-
-The library requires Vue, Radix Vue, and Reka UI as peer dependencies:
+### Peer Dependencies
 
 ```bash
-# Required peer dependencies
 pnpm add vue radix-vue reka-ui
-
-# Optional: Install lucide-vue-next for icons (or use your preferred icon library)
-pnpm add lucide-vue-next
 ```
 
-**Note:** `@equal-experts/kuat-core` is bundled with this package. You don't need to install it separately when using kuat-vue. However, if you want to use design tokens without Vue components, you can install [`@equal-experts/kuat-core`](https://www.npmjs.com/package/@equal-experts/kuat-core) standalone. See the [kuat-core documentation](https://github.com/equalexperts/kuat-mono/tree/main/packages/kuat-core) for framework-agnostic usage.
-
-### Using Design Tokens Without Components
-
-If you only need design tokens (CSS variables, Tailwind preset) without Vue components, install `@equal-experts/kuat-core` instead:
-
-```bash
-pnpm add @equal-experts/kuat-core
-```
-
-Then import the CSS variables and optionally use the Tailwind preset:
-
-```typescript
-// Import CSS variables
-import '@equal-experts/kuat-core/variables.css';
-
-// Or use as a Tailwind preset
-import kuatPreset from '@equal-experts/kuat-core';
-```
-
-See the [kuat-core documentation](https://github.com/equalexperts/kuat-mono/tree/main/packages/kuat-core) for detailed usage with Svelte, Angular, Astro, and other frameworks.
-
-### Recommended: Use Subpath Imports
-
-To avoid installing all peer dependencies when you only need specific components, use **subpath imports**. This allows you to import only the components you need and only install their required peer dependencies.
+---
 
-**Example: Only using Button**
+## What's Included
 
-```bash
-# Only install peer dependencies for Button
-pnpm add vue radix-vue reka-ui
-```
+### Custom Components
 
-```vue
-<script setup>
-// Import from subpath - only Button and its dependencies are required
-import { Button } from "@equal-experts/kuat-vue/button";
-</script>
-```
-
-**Component Peer Dependencies:**
+Components unique to Kuat, not available in shadcn-vue:
 
-- **Button**: `vue`, `radix-vue`, `reka-ui`
-- **Accordion**: `vue`, `radix-vue`, `reka-ui`, `lucide-vue-next`
-- **AlertDialog**: `vue`, `radix-vue`, `reka-ui`
-- **Badge**: `vue`, `radix-vue`, `reka-ui`
+| Component | Description |
+|-----------|-------------|
+| `ButtonGroup` | Groups buttons together with proper styling |
+| `ButtonGroupText` | Text element within a button group |
+| `ButtonGroupSeparator` | Separator between button group items |
 
-**Using Main Export (All Components):**
+### Blocks (Coming Soon)
 
-If you import from the main package, you'll need all peer dependencies:
+Pre-built compositions for common patterns:
 
-```vue
-<script setup>
-// This requires ALL peer dependencies to be installed
-import { Button, Accordion, AlertDialog } from "@equal-experts/kuat-vue";
-</script>
-```
+| Block | Description |
+|-------|-------------|
+| `KuatHeader` | Brand header with logo, navigation, actions |
+| `KuatFooter` | Brand footer with links and legal |
+| `KuatSearchPattern` | Search input with suggestions |
 
-**lucide-vue-next Version Support:**
+### Utilities
 
-The package supports `lucide-vue-next` versions `^0.344.0 || >=0.400.0`, including the latest versions.
+| Utility | Description |
+|---------|-------------|
+| `cn()` | Class name merger using clsx + tailwind-merge |
 
 ---
 
-## Setup
+## Recommended Setup
 
-### 1. Configure Tailwind CSS
+For the best experience, combine this package with kuat-core and shadcn-vue:
 
-The Kuat Design System uses Tailwind CSS v4. You'll need to configure Tailwind in your project.
-
-#### Install Tailwind CSS v4
+### Step 1: Install Dependencies
 
 ```bash
-pnpm add -D tailwindcss@next @tailwindcss/vite
+pnpm add @equal-experts/kuat-core @equal-experts/kuat-vue
 ```
 
-#### Create `tailwind.config.ts`
+### Step 2: Configure Tailwind
 
 ```typescript
-import type { Config } from "tailwindcss";
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+import kuatPreset from '@equal-experts/kuat-core';
 
-const config: Config = {
+export default {
+  presets: [kuatPreset],
   content: [
-    "./src/**/*.{js,ts,jsx,tsx,vue}",
-    "./node_modules/@equal-experts/kuat-vue/**/*.{js,ts,vue}", // Include Kuat components
+    './src/**/*.{vue,js,ts}',
+    './node_modules/@equal-experts/kuat-vue/**/*.{vue,js,ts}',
   ],
-  theme: {
-    extend: {
-      colors: {
-        background: "var(--background)",
-        foreground: "var(--foreground)",
-        primary: {
-          DEFAULT: "var(--primary)",
-          foreground: "var(--primary-foreground)",
-        },
-        secondary: {
-          DEFAULT: "var(--secondary)",
-          foreground: "var(--secondary-foreground)",
-        },
-        // ... other color tokens from @equal-experts/kuat-core
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-      fontFamily: {
-        sans: ["var(--font-sans)"],
-        serif: ["var(--font-serif)"],
-        mono: ["var(--font-mono)"],
-      },
-    },
-  },
-  plugins: [],
-};
-
-export default config;
+} satisfies Config;
 ```
 
-#### Configure Vite (if using Vite)
-
-```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
-import vue from "@vitejs/plugin-vue";
-import tailwindcss from "@tailwindcss/vite";
-
-export default defineConfig({
-  plugins: [vue(), tailwindcss()],
-});
-```
-
-### 2. Import Styles
-
-Import the Kuat Design System styles in your application's entry point:
+### Step 3: Import Styles
 
 ```typescript
 // main.ts
-import { createApp } from "vue";
-import App from "./App.vue";
-import "@equal-experts/kuat-vue/styles";
-
-createApp(App).mount("#app");
-```
-
-This imports the bundled CSS file which includes all design tokens from `@equal-experts/kuat-core` (no need to install `@equal-experts/kuat-core` separately).
-
-**Note:** The styles include:
-- Design tokens from `@equal-experts/kuat-core` (colors, spacing, typography)
-- Tailwind CSS base styles
-- Component-specific styles
-
-### 3. (Optional) Configure Fonts
-
-The Kuat Design System uses Lexend (sans-serif), Lora (serif), and JetBrains Mono (monospace) fonts. These are loaded via Google Fonts in the core package.
-
-If you want to use different fonts or load them differently, you can override the CSS variables:
+import { createApp } from 'vue';
+import '@equal-experts/kuat-core/variables.css';
+import App from './App.vue';
 
-```css
-:root {
-  --font-sans: 'Your Sans Font', sans-serif;
-  --font-serif: 'Your Serif Font', serif;
-  --font-mono: 'Your Mono Font', monospace;
-}
+createApp(App).mount('#app');
 ```
 
----
-
-## Basic Usage
+### Step 4: Install shadcn-vue Components
 
-### Import Components
-
-You can import components in two ways:
-
-**Option 1: Subpath Import (Recommended for single components)**
-
-```typescript
-// Import only Button - only requires Button's peer dependencies
-import { Button } from "@equal-experts/kuat-vue/button";
+```bash
+npx shadcn-vue@latest init
+npx shadcn-vue@latest add button dialog dropdown-menu
 ```
 
-**Option 2: Main Package Import**
+### Step 5: Use Components Together
 
-```typescript
-// Import from main package - requires all peer dependencies
-import { Button } from "@equal-experts/kuat-vue";
-```
+```vue
+<script setup lang="ts">
+// Kuat custom components from this package
+import { ButtonGroup, ButtonGroupText } from '@equal-experts/kuat-vue';
 
-### Use in Your App
+// shadcn-vue components from your local installation
+import { Button } from '@/components/ui/button';
+</script>
 
-```vue
 <template>
-  <div>
-    <Button>Click me</Button>
-    <Button variant="outline">Outline button</Button>
+  <ButtonGroup>
+    <Button variant="outline">Edit</Button>
+    <Button variant="outline">Save</Button>
     <Button variant="destructive">Delete</Button>
-  </div>
+  </ButtonGroup>
 </template>
-
-<script setup lang="ts">
-// Recommended: Subpath import
-import { Button } from "@equal-experts/kuat-vue/button";
-
-// Or: Main package import
-// import { Button } from "@equal-experts/kuat-vue";
-</script>
 ```
 
 ---
 
 ## Component Examples
 
-### Button
+### ButtonGroup
 
-The Button component supports multiple variants and sizes:
-
-```vue
-<template>
-  <div class="space-x-4">
-    <!-- Variants -->
-    <Button variant="default">Default</Button>
-    <Button variant="destructive">Destructive</Button>
-    <Button variant="outline">Outline</Button>
-    <Button variant="secondary">Secondary</Button>
-    <Button variant="ghost">Ghost</Button>
-    <Button variant="link">Link</Button>
-
-    <!-- Sizes -->
-    <Button size="sm">Small</Button>
-    <Button size="default">Default</Button>
-    <Button size="lg">Large</Button>
-    <Button size="icon">🚀</Button>
-    <Button size="icon-sm">📱</Button>
-    <Button size="icon-lg">💻</Button>
-
-    <!-- With click handler -->
-    <Button @click="handleClick">
-      Click me
-    </Button>
-
-    <!-- Disabled -->
-    <Button disabled>Disabled</Button>
-
-    <!-- As child (for composition) -->
-    <Button as-child>
-      <a href="/link">Link Button</a>
-    </Button>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { Button } from "@equal-experts/kuat-vue";
-
-function handleClick() {
-  alert("Clicked!");
-}
-</script>
-```
-
-### TypeScript Support
-
-All components are fully typed:
+Groups buttons together with seamless borders:
 
 ```vue
 <script setup lang="ts">
-import { Button, type ButtonVariants } from "@equal-experts/kuat-vue";
-
-const variant: ButtonVariants["variant"] = "outline";
-const size: ButtonVariants["size"] = "lg";
+import { ButtonGroup, ButtonGroupText } from '@equal-experts/kuat-vue';
+import { Button } from '@/components/ui/button';
 </script>
 
 <template>
-  <Button :variant="variant" :size="size">
-    Typed Button
-  </Button>
+  <!-- Horizontal (default) -->
+  <ButtonGroup>
+    <Button variant="outline">Left</Button>
+    <Button variant="outline">Center</Button>
+    <Button variant="outline">Right</Button>
+  </ButtonGroup>
+
+  <!-- Vertical -->
+  <ButtonGroup orientation="vertical">
+    <Button variant="outline">Top</Button>
+    <Button variant="outline">Middle</Button>
+    <Button variant="outline">Bottom</Button>
+  </ButtonGroup>
+
+  <!-- With text label -->
+  <ButtonGroup>
+    <ButtonGroupText>Filter:</ButtonGroupText>
+    <Button variant="outline">All</Button>
+    <Button variant="outline">Active</Button>
+    <Button variant="outline">Completed</Button>
+  </ButtonGroup>
 </template>
 ```
 
----
-
-## Styling and Theming
-
-### Using Design Tokens
+### cn() Utility
 
-The Kuat Design System provides CSS variables for all design tokens. Use them in your custom components:
+Merge class names with Tailwind conflict resolution:
 
 ```vue
-<template>
-  <div class="custom-component">
-    Custom styled component
-  </div>
-</template>
+<script setup lang="ts">
+import { cn } from '@equal-experts/kuat-vue';
 
-<style scoped>
-.custom-component {
-  background-color: var(--background);
-  color: var(--foreground);
-  padding: var(--spacing);
-  border-color: var(--border);
-  border-radius: var(--radius);
-}
-</style>
-```
+const props = defineProps<{
+  class?: string;
+}>();
 
-Or with Tailwind classes:
+const containerClass = cn(
+  'bg-background text-foreground p-4',
+  props.class
+);
+</script>
 
-```vue
 <template>
-  <div class="bg-background text-foreground p-4 rounded-lg border border-border">
-    Custom styled component
+  <div :class="containerClass">
+    <slot />
   </div>
 </template>
 ```
 
-### Dark Mode
+---
 
-Dark mode is supported via the `.dark` class. Apply it to your root element:
+## Migration Guide
 
-```vue
-<!-- In your root component -->
-<template>
-  <div :class="{ dark: isDark }">
-    <App />
-  </div>
-</template>
+If you were importing standard components from this package, migrate to direct shadcn-vue installation:
 
-<script setup lang="ts">
-import { ref } from "vue";
+### Before (Deprecated)
 
-const isDark = ref(false);
+```vue
+<script setup lang="ts">
+import { Button, Dialog, Badge } from '@equal-experts/kuat-vue';
 </script>
 ```
 
-Or toggle dynamically:
+### After (Recommended)
 
 ```vue
-<template>
-  <div :class="{ dark: isDark }">
-    <button @click="isDark = !isDark">
-      Toggle theme
-    </button>
-    <!-- Your app -->
-  </div>
-</template>
-
 <script setup lang="ts">
-import { ref } from "vue";
+// Standard components from your local shadcn-vue installation
+import { Button } from '@/components/ui/button';
+import { Dialog } from '@/components/ui/dialog';
+import { Badge } from '@/components/ui/badge';
 
-const isDark = ref(false);
+// Kuat-specific components from this package
+import { ButtonGroup } from '@equal-experts/kuat-vue';
 </script>
 ```
 
-### Customizing Colors
-
-Override CSS variables to customize the theme:
+### Migration Steps
 
-```css
-/* In your global CSS file */
-:root {
-  --primary: oklch(0.645 0.163 237.5); /* Your primary color */
-  --primary-foreground: oklch(1.0 0.0 0.0); /* White */
-}
-
-.dark {
-  --primary: oklch(0.585 0.145 237.5); /* Darker primary for dark mode */
-  --primary-foreground: oklch(1.0 0.0 0.0); /* White */
-}
-```
+1. Ensure `@equal-experts/kuat-core` is installed
+2. Initialize shadcn-vue: `npx shadcn-vue@latest init`
+3. Install needed components: `npx shadcn-vue@latest add button dialog badge`
+4. Update imports to use local components
+5. Keep imports for Kuat-specific components (ButtonGroup, etc.)
 
 ---
 
-## Advanced Usage
+## Deprecated Exports
 
-### Composing Components
+The following exports are deprecated and will be removed in the next major version. Install them directly via shadcn-vue CLI instead:
 
-Use the `as-child` prop to compose components:
+| Component | Replacement |
+|-----------|-------------|
+| `Button` | `npx shadcn-vue@latest add button` |
+| `Accordion` | `npx shadcn-vue@latest add accordion` |
+| `AlertDialog` | `npx shadcn-vue@latest add alert-dialog` |
+| `Badge` | `npx shadcn-vue@latest add badge` |
 
-```vue
-<template>
-  <Button as-child variant="ghost">
-    <router-link to="/dashboard">Dashboard</router-link>
-  </Button>
-</template>
+These components are still exported for backward compatibility but will be themed correctly only when using kuat-core.
 
-<script setup lang="ts">
-import { Button } from "@equal-experts/kuat-vue";
-</script>
-```
+---
 
-### Using Variants Programmatically
+## TypeScript Support
 
-Import and use variant functions:
+All components are fully typed:
 
 ```vue
-<template>
-  <button :class="buttonClass">
-    Custom Button
-  </button>
-</template>
-
 <script setup lang="ts">
-import { buttonVariants } from "@equal-experts/kuat-vue";
-import { cn } from "@equal-experts/kuat-vue";
+import { ButtonGroup } from '@equal-experts/kuat-vue';
+import type { ButtonGroupVariants } from '@equal-experts/kuat-vue';
 
-const buttonClass = cn(
-  buttonVariants({ variant: "outline", size: "lg" }),
-  "custom-class"
-);
+const orientation: ButtonGroupVariants['orientation'] = 'horizontal';
 </script>
 ```
 
-### Global Component Registration
-
-Register components globally if preferred:
-
-```typescript
-// main.ts
-import { createApp } from "vue";
-import App from "./App.vue";
-import * as KuatComponents from "@equal-experts/kuat-vue";
-
-const app = createApp(App);
-
-// Register all components globally
-Object.entries(KuatComponents).forEach(([name, component]) => {
-  if (name !== "default" && typeof component === "object") {
-    app.component(name, component);
-  }
-});
+---
 
-app.mount("#app");
-```
+## Dark Mode
 
-Then use without importing:
+Dark mode is supported via the `.dark` class on your root element:
 
 ```vue
 <template>
-  <Button>No import needed</Button>
+  <div :class="{ dark: isDark }">
+    <App />
+  </div>
 </template>
-```
-
----
-
-## Troubleshooting
-
-### Styles Not Loading
-
-1. **Check import order**: Ensure you import `@equal-experts/kuat-vue/styles` before your own styles
-2. **Verify Tailwind config**: Make sure `@equal-experts/kuat-vue` is included in your `content` paths
-3. **Check build output**: Ensure the CSS file is being included in your build
-4. **Vue SFC**: If using Single File Components, ensure styles are processed correctly
-
-### TypeScript Errors
-
-1. **Install types**: Ensure Vue TypeScript support is configured
-2. **Check TypeScript version**: Requires TypeScript 5.3 or higher
-3. **Verify imports**: Use named imports, not default imports
-4. **Vue TSConfig**: Ensure your `tsconfig.json` includes Vue file types
-
-### Components Not Rendering
-
-1. **Check Vue version**: Requires Vue 3.4.0 or higher
-2. **Verify peer dependencies**: Ensure `vue` is installed
-3. **Check console**: Look for runtime errors in the browser console
-4. **Build mode**: Ensure you're using the correct build mode (ES modules)
-
----
-
-## Package Structure
-
-```
-@equal-experts/kuat-vue
-├── dist/
-│   ├── index.js          # Compiled JavaScript
-│   ├── index.d.ts        # TypeScript definitions
-│   └── index.css         # Compiled styles
-└── src/
-    ├── components/       # Component source files
-    ├── lib/             # Utilities
-    └── styles.css        # Style source
-```
-
----
-
-## Additional Resources
-
-- **shadcn-vue Documentation**: [https://www.shadcn-vue.com](https://www.shadcn-vue.com)
-- **Tailwind CSS v4**: [https://tailwindcss.com](https://tailwindcss.com)
-- **Vue 3 Documentation**: [https://vuejs.org](https://vuejs.org)
-- **Radix Vue Documentation**: [https://www.radix-vue.com](https://www.radix-vue.com)
-
----
-
-## Documentation for AI Agents
-
-The Kuat Design System includes LLM-optimized documentation for AI assistants.
-
-### Quick Setup
-
-Add this snippet to your existing `.cursorrules`, `CLAUDE.md`, or agent config:
-
-```markdown
-## Kuat Design System
-
-This project uses the Kuat Design System for all UI work.
-
-**What it provides:**
-Design tokens, component patterns, layout guidance, and content guidelines for building consistent, accessible interfaces.
-
-**When to use it:**
-You MUST reference the Kuat documentation when:
-- Creating or modifying UI components
-- Making color, typography, spacing, or layout decisions
-- Writing user-facing content
-
-**How to use it:**
-1. Check the documentation before making design decisions
-2. Follow existing patterns; do not invent new ones
-3. If the documentation doesn't cover your case, ask before proceeding
-
-**Quick reference (when docs unavailable):**
-Semantic tokens only (`bg-primary` not `bg-blue-500`), 8-point spacing grid, 6px radius for interactive elements, WCAG AA contrast.
 
-**Documentation:** https://github.com/equal-experts/kuat-mono/tree/main/kuat-docs
-```
-
-### Need Full Documentation Locally?
-
-For component patterns, layouts, or content guidelines, clone the docs:
-
-```bash
-git clone --filter=blob:none --sparse https://github.com/equal-experts/kuat-mono.git
-cd kuat-mono && git sparse-checkout set kuat-docs
-cp -r kuat-docs /path/to/your-project/
+<script setup lang="ts">
+import { ref } from 'vue';
+const isDark = ref(false);
+</script>
 ```
 
-Then update your snippet: `Check the documentation in kuat-docs/rules/ before making design decisions`
-
-### Verification
-
-Test your setup with these prompts:
-- "Create a card component" → Agent should reference Kuat docs
-- "What color for the primary button?" → Agent should check docs or use semantic tokens
-- "Add spacing between form fields" → Agent should reference spacing rules
+Components automatically adapt when using kuat-core design tokens.
 
 ---
 
-## Support
-
-For issues, questions, or contributions, please refer to the main repository documentation or open an issue in the project repository.
+## Related Documentation
 
+- [Consumer Setup Guide](https://github.com/equalexperts/kuat-mono/blob/master/kuat-docs/setup/consumer-setup.md)
+- [kuat-core Integration](https://github.com/equalexperts/kuat-mono/blob/master/kuat-docs/setup/kuat-core-integration.md)
+- [Component Patterns](https://github.com/equalexperts/kuat-mono/blob/master/kuat-docs/rules/components/patterns.md)
+- [shadcn-vue Documentation](https://www.shadcn-vue.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equal-experts/kuat-vue",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",