@equal-experts/kuat-react 0.3.1 → 0.4.0

package/README.md

@@ -1,18 +1,30 @@
 # @equal-experts/kuat-react
 
-A guide for integrating the Kuat Design System React component library into your application.
+Custom React components and blocks for the Kuat Design System.
 
 ---
 
-## Installation
+## Architecture
 
-### Prerequisites
+This package provides **custom components** and **blocks** that are unique to Kuat. For standard UI components (Button, Dialog, etc.), install them directly via shadcn CLI with kuat-core theming.
 
-- React 18.2.0 or higher
-- Node.js 18 or higher
-- A package manager (npm, pnpm, or yarn)
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Application                                   │
+├─────────────────────────────────────────────────────┤
+│  Kuat Blocks (from this package)                    │
+├─────────────────────────────────────────────────────┤
+│  Kuat Components (from this package)                │
+├─────────────────────────────────────────────────────┤
+│  shadcn Components (installed directly)             │
+├─────────────────────────────────────────────────────┤
+│  @equal-experts/kuat-core (design tokens)           │
+└─────────────────────────────────────────────────────┘
+```
 
-### Install the Package
+---
+
+## Installation
 
 ```bash
 # Using pnpm (recommended)
@@ -25,217 +37,100 @@ npm install @equal-experts/kuat-react
 yarn add @equal-experts/kuat-react
 ```
 
-### Install Peer Dependencies
-
-The library requires React, React DOM, and Radix UI packages as peer dependencies. Install only the packages you need based on which components you use:
-
-```bash
-# Required peer dependencies
-pnpm add react react-dom
-
-# Install Radix UI packages as needed (examples for common components)
-pnpm add @radix-ui/react-slot @radix-ui/react-dialog @radix-ui/react-dropdown-menu
-
-# Optional: Install lucide-react for icons (or use your preferred icon library)
-pnpm add lucide-react
-```
-
-**Note:** `@equal-experts/kuat-core` is bundled with this package. You don't need to install it separately when using kuat-react. However, if you want to use design tokens without React 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 React components, install `@equal-experts/kuat-core` instead:
+### Peer Dependencies
 
 ```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';
+pnpm add react react-dom @radix-ui/react-slot
 ```
 
-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**
+---
 
-```bash
-# Only install peer dependencies for Button
-pnpm add react react-dom @radix-ui/react-slot
-```
+## What's Included
 
-```tsx
-// Import from subpath - only Button and its dependencies are required
-import { Button } from "@equal-experts/kuat-react/button";
-```
+### Custom Components
 
-**Component Peer Dependencies:**
+Components unique to Kuat, not available in shadcn:
 
-- **Button**: `react`, `react-dom`, `@radix-ui/react-slot`
-- **Accordion**: `react`, `react-dom`, `@radix-ui/react-accordion`, `lucide-react`
-- **AlertDialog**: `react`, `react-dom`, `@radix-ui/react-alert-dialog`
-- **Badge**: `react`, `react-dom` (no additional Radix UI dependencies)
+| 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:
 
-```tsx
-// This requires ALL peer dependencies to be installed
-import { Button, Accordion, AlertDialog } from "@equal-experts/kuat-react";
-```
+| Block | Description |
+|-------|-------------|
+| `KuatHeader` | Brand header with logo, navigation, actions |
+| `KuatFooter` | Brand footer with links and legal |
+| `KuatSearchPattern` | Search input with suggestions |
 
-**lucide-react Version Support:**
+### Utilities
 
-The package supports `lucide-react` versions `^0.344.0 || >=0.400.0`, including the latest versions (0.562.0+).
+| 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:
 
-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-react
 ```
 
-#### 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}",
-    "./node_modules/@equal-experts/kuat-react/**/*.{js,ts,jsx,tsx}", // Include Kuat components
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@equal-experts/kuat-react/**/*.{js,ts,jsx,tsx}',
   ],
-  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)
+### Step 3: Import Styles
 
 ```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import tailwindcss from "@tailwindcss/vite";
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-});
-```
-
-### 2. Import Styles
-
-Import the Kuat Design System styles in your application's entry point:
-
-```typescript
-// main.tsx or App.tsx
-import "@equal-experts/kuat-react/styles";
-```
-
-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:
-
-```css
-:root {
-  --font-sans: 'Your Sans Font', sans-serif;
-  --font-serif: 'Your Serif Font', serif;
-  --font-mono: 'Your Mono Font', monospace;
-}
-```
-
----
-
-## Basic Usage
-
-### 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-react/button";
+// main.tsx
+import '@equal-experts/kuat-core/variables.css';
 ```
 
-**Option 2: Main Package Import**
+### Step 4: Install shadcn Components
 
-```typescript
-// Import from main package - requires all peer dependencies
-import { Button } from "@equal-experts/kuat-react";
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button dialog dropdown-menu
 ```
 
-### Use in Your App
+### Step 5: Use Components Together
 
 ```tsx
-// Recommended: Subpath import
-import { Button } from "@equal-experts/kuat-react/button";
+// Kuat custom components from this package
+import { ButtonGroup, ButtonGroupText } from '@equal-experts/kuat-react';
 
-// Or: Main package import
-// import { Button } from "@equal-experts/kuat-react";
+// shadcn components from your local installation
+import { Button } from '@/components/ui/button';
 
-function App() {
+function Example() {
   return (
-    <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>
   );
 }
 ```
@@ -244,274 +139,138 @@ function App() {
 
 ## Component Examples
 
-### Button
+### ButtonGroup
 
-The Button component supports multiple variants and sizes:
+Groups buttons together with seamless borders:
 
 ```tsx
-import { Button } from "@equal-experts/kuat-react";
-
-function ButtonExamples() {
-  return (
-    <div className="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>
-
-      {/* With onClick */}
-      <Button onClick={() => alert("Clicked!")}>
-        Click me
-      </Button>
-
-      {/* Disabled */}
-      <Button disabled>Disabled</Button>
-
-      {/* As child (for composition) */}
-      <Button asChild>
-        <a href="/link">Link Button</a>
-      </Button>
-    </div>
-  );
-}
+import { ButtonGroup } from '@equal-experts/kuat-react';
+import { Button } from '@/components/ui/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>
 ```
 
-### TypeScript Support
+### cn() Utility
 
-All components are fully typed:
+Merge class names with Tailwind conflict resolution:
 
 ```tsx
-import { Button, type ButtonProps } from "@equal-experts/kuat-react";
-
-// ButtonProps includes all standard button HTML attributes
-const CustomButton: React.FC<ButtonProps> = (props) => {
-  return <Button {...props} />;
-};
-```
-
----
-
-## Styling and Theming
-
-### Using Design Tokens
+import { cn } from '@equal-experts/kuat-react';
 
-The Kuat Design System provides CSS variables for all design tokens. Use them in your custom components:
-
-```tsx
-function CustomComponent() {
+function MyComponent({ className, ...props }) {
   return (
     <div
-      className="bg-background text-foreground p-4 rounded-lg"
-      style={{
-        borderColor: "var(--border)",
-      }}
-    >
-      Custom styled component
-    </div>
-  );
-}
-```
-
-### Dark Mode
-
-Dark mode is supported via the `.dark` class. Apply it to your root element:
-
-```tsx
-// In your root component or HTML
-<html className="dark">
-  <body>
-    <App />
-  </body>
-</html>
-```
-
-Or toggle dynamically:
-
-```tsx
-import { useState } from "react";
-
-function App() {
-  const [isDark, setIsDark] = useState(false);
-
-  return (
-    <div className={isDark ? "dark" : ""}>
-      <button onClick={() => setIsDark(!isDark)}>
-        Toggle theme
-      </button>
-      {/* Your app */}
-    </div>
+      className={cn(
+        'bg-background text-foreground p-4',
+        className
+      )}
+      {...props}
+    />
   );
 }
 ```
 
-### Customizing Colors
-
-Override CSS variables to customize the theme:
-
-```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 */
-}
-```
-
 ---
 
-## Advanced Usage
+## Migration Guide
 
-### Composing Components
+If you were importing standard components from this package, migrate to direct shadcn installation:
 
-Use the `asChild` prop to compose components:
+### Before (Deprecated)
 
 ```tsx
-import { Button } from "@equal-experts/kuat-react";
-import { Link } from "react-router-dom";
-
-function NavigationButton() {
-  return (
-    <Button asChild variant="ghost">
-      <Link to="/dashboard">Dashboard</Link>
-    </Button>
-  );
-}
+import { Button, Dialog, Badge } from '@equal-experts/kuat-react';
 ```
 
-### Using Variants Programmatically
-
-Import and use variant functions:
+### After (Recommended)
 
 ```tsx
-import { buttonVariants } from "@equal-experts/kuat-react";
-import { cn } from "@equal-experts/kuat-react";
+// Standard components from your local shadcn installation
+import { Button } from '@/components/ui/button';
+import { Dialog } from '@/components/ui/dialog';
+import { Badge } from '@/components/ui/badge';
 
-function CustomButton({ className, ...props }) {
-  return (
-    <button
-      className={cn(buttonVariants({ variant: "outline", size: "lg" }), className)}
-      {...props}
-    />
-  );
-}
+// Kuat-specific components from this package
+import { ButtonGroup } from '@equal-experts/kuat-react';
 ```
 
----
-
-## Troubleshooting
-
-### Styles Not Loading
-
-1. **Check import order**: Ensure you import `@equal-experts/kuat-react/styles` before your own styles
-2. **Verify Tailwind config**: Make sure `@equal-experts/kuat-react` is included in your `content` paths
-3. **Check build output**: Ensure the CSS file is being included in your build
-
-### TypeScript Errors
+### Migration Steps
 
-1. **Install types**: Ensure `@types/react` and `@types/react-dom` are installed
-2. **Check TypeScript version**: Requires TypeScript 5.3 or higher
-3. **Verify imports**: Use named imports, not default imports
-
-### Components Not Rendering
-
-1. **Check React version**: Requires React 18.2.0 or higher
-2. **Verify peer dependencies**: Ensure `react` and `react-dom` are installed
-3. **Check console**: Look for runtime errors in the browser console
+1. Ensure `@equal-experts/kuat-core` is installed
+2. Initialize shadcn: `npx shadcn@latest init`
+3. Install needed components: `npx shadcn@latest add button dialog badge`
+4. Update imports to use local components
+5. Keep imports for Kuat-specific components (ButtonGroup, etc.)
 
 ---
 
-## Package Structure
+## Deprecated Exports
 
-```
-@equal-experts/kuat-react
-├── 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
-```
+The following exports are deprecated and will be removed in the next major version. Install them directly via shadcn CLI instead:
 
----
+| Component | Replacement |
+|-----------|-------------|
+| `Button` | `npx shadcn@latest add button` |
+| `Accordion` | `npx shadcn@latest add accordion` |
+| `AlertDialog` | `npx shadcn@latest add alert-dialog` |
+| `Badge` | `npx shadcn@latest add badge` |
 
-## Additional Resources
-
-- **shadcn/ui Documentation**: [https://ui.shadcn.com](https://ui.shadcn.com)
-- **Tailwind CSS v4**: [https://tailwindcss.com](https://tailwindcss.com)
-- **Radix UI Documentation**: [https://www.radix-ui.com](https://www.radix-ui.com)
+These components are still exported for backward compatibility but will be themed correctly only when using kuat-core.
 
 ---
 
-## 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:
+## TypeScript Support
 
-```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
+All components are fully typed:
 
-**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.
+```tsx
+import { ButtonGroup } from '@equal-experts/kuat-react';
+import type { ComponentProps } from 'react';
 
-**Documentation:** https://github.com/equal-experts/kuat-mono/tree/main/kuat-docs
+type ButtonGroupProps = ComponentProps<typeof ButtonGroup>;
 ```
 
-### 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/
-```
+## Dark Mode
 
-Then update your snippet: `Check the documentation in kuat-docs/rules/ before making design decisions`
+Dark mode is supported via the `.dark` class on your root element:
 
-### Verification
+```tsx
+<html className="dark">
+  <body>
+    <App />
+  </body>
+</html>
+```
 
-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/ui Documentation](https://ui.shadcn.com)

package/package.json

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