@equal-experts/kuat-react 0.14.0-beta.0 → 0.14.0-beta.2

package/README.md

@@ -53,23 +53,34 @@ Add this to your project `AGENTS.md` (or `.cursorrules`) so agent workflows stay
 ### Peer dependencies
 
 Install peers for the components you use before running `dev` or `build`.
+`react`/`react-dom` are always required. Embla (carousel) and Sonner ship as
+bundled dependencies, so you don't install those.
 
-| Components you use | Required peers |
+| Components you use | Peers to install |
 |---|---|
-| `Button`, `KuatHeader` | `@radix-ui/react-slot`, `lucide-react` |
-| `Accordion` | `@radix-ui/react-accordion` |
+| `Button`, `ButtonGroup`, `IconButton` | `@radix-ui/react-slot` |
+| `Accordion` | `@radix-ui/react-accordion`, `lucide-react` |
 | `AlertDialog` | `@radix-ui/react-alert-dialog` |
-| `Select` / `KuatSelect` | `@radix-ui/react-select`, `@radix-ui/react-separator` |
-| `Checkbox` / `CheckboxField` | `@radix-ui/react-checkbox` |
-| `RadioGroup` / `RadioField` | `@radix-ui/react-radio-group` |
+| `Select` | `@radix-ui/react-select`, `lucide-react` |
+| `DropdownMenu` | `@radix-ui/react-dropdown-menu`, `lucide-react` |
+| `Checkbox` / `CheckboxField` | `@radix-ui/react-checkbox`, `lucide-react` |
+| `Radio` / `RadioField` | `@radix-ui/react-radio-group` |
 | `Switch` / `SwitchField` | `@radix-ui/react-switch` |
-| `Toggle` / `ToggleGroup` | `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group` |
-| `Sonner` | `sonner` |
+| `Toggle`, `ToggleGroup` | `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group` |
+| `Separator` | `@radix-ui/react-separator` |
+| `Carousel`, `KuatCarousel` | `lucide-react` |
+| `Breadcrumb`, `KuatHeader` | `lucide-react` |
+| `Sonner` | — (bundled, no peer to install) |
+| `Badge`, `Field`, `Input`, `Textarea`, `ContentCard`, `KuatRadialProgress` | none |
+
+> **Tip:** if you use the Kuat agent plugin in Claude Code, run
+> `/kuat-add <component>` to add a component and install its peers automatically,
+> instead of wiring the table above by hand.
 
 Example peer install for a broad setup:
 
 ```bash
-pnpm add @radix-ui/react-slot @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-switch @radix-ui/react-toggle @radix-ui/react-toggle-group lucide-react sonner
+pnpm add @radix-ui/react-slot @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-select @radix-ui/react-dropdown-menu @radix-ui/react-separator @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-switch @radix-ui/react-toggle @radix-ui/react-toggle-group lucide-react
 ```
 
 ---
@@ -124,63 +135,52 @@ import { KuatCarousel } from '@equal-experts/kuat-react/kuat-carousel';
 
 ## Recommended setup
 
-### 1. Tailwind
-
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import kuatPreset from '@equal-experts/kuat-core';
-
-export default {
-  presets: [kuatPreset],
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@equal-experts/kuat-react/**/*.{js,ts,jsx,tsx}',
-  ],
-} satisfies Config;
-```
-
-### 2. Tailwind runtime stylesheet (required for Tailwind v4)
+### 1. Tailwind v4 + Kuat tokens (CSS-first)
 
-Create a global stylesheet and load Tailwind:
+Add the Tailwind v4 plugin to your build (e.g. `@tailwindcss/vite`), then create
+a global stylesheet that imports Tailwind and the Kuat tokens. The tokens must
+be pulled in **through Tailwind** (a CSS `@import`) so the `@theme` block in
+`variables.css` is processed and the token utilities (`bg-primary`,
+`text-foreground`, `rounded-lg`, …) are generated:
 
 ```css
-/* src/tailwind.css */
+/* src/index.css */
+@import "@equal-experts/kuat-core/fonts.css"; /* fonts; or a <link> — see kuat-core README */
 @import "tailwindcss";
+@import "@equal-experts/kuat-core/variables.css";
 ```
 
-### 3. Design tokens and Kuat styles (once per app entrypoint)
+> A plain JS `import "@equal-experts/kuat-core/variables.css"` loads the raw
+> variables but does **not** feed the `@theme` block to Tailwind, so the token
+> utilities never generate (with no error). Always `@import` the tokens through
+> Tailwind, as above.
+>
+> The legacy JS preset (`presets: [kuatPreset]`) is **deprecated** and is not
+> auto-loaded by Tailwind v4 — don't use it. See the kuat-core README.
+
+### 2. Component styles (once per app entrypoint)
+
+Kuat component CSS is pre-compiled, so a JS import is correct here:
 
 ```typescript
 // main.tsx
-import '@equal-experts/kuat-core/variables.css';
-import '@equal-experts/kuat-react/styles';
-import './tailwind.css';
-import './app.css';
+import '@equal-experts/kuat-react/styles'; // pre-compiled component CSS
+import './index.css';                       // Tailwind + Kuat tokens (from step 1)
+import './app.css';                          // your app styles, last
 ```
 
-Import order matters: load Kuat tokens and Kuat styles before app-specific styles.
+Import order matters: load Kuat styles before app-specific styles.
 
 If you scaffolded from a starter template (for example Vite), remove or neutralize template CSS that resets fonts/layout globally (for example `src/index.css` with `:root { font: ... }`, `body { ... }`, `#root { ... }`). These rules can override Kuat typography and spacing.
 
-Typical cleanup for a smoke setup:
-
-```typescript
-// Keep in main.tsx
-import '@equal-experts/kuat-core/variables.css';
-import '@equal-experts/kuat-react/styles';
-import './tailwind.css';
-// Remove template global CSS import if it overrides root/body fonts or layout
-```
-
-### 4. shadcn for gaps only
+### 3. shadcn for gaps only
 
 ```bash
 npx shadcn@latest init
 npx shadcn@latest add dialog dropdown-menu   # examples — skip `button` if you use Kuat Button
 ```
 
-### 5. Use Kuat + shadcn together
+### 4. Use Kuat + shadcn together
 
 ```tsx
 import { Button, ButtonGroup, Field } from '@equal-experts/kuat-react';
@@ -242,7 +242,7 @@ Use this quick smoke test after installation to verify imports, styles, and Tail
 ### 1. Add a smoke component
 
 ```tsx
-import { Button, Field, KuatCarousel, KuatCarouselContent, KuatCarouselItem } from '@equal-experts/kuat-react';
+import { Button, Field, FieldLabel, Input, KuatCarousel, KuatCarouselContent, KuatCarouselItem } from '@equal-experts/kuat-react';
 
 export function KuatInstallSmoke() {
   return (
@@ -250,8 +250,8 @@ export function KuatInstallSmoke() {
       <h1 className="text-4xl font-bold">Kuat install smoke test</h1>
 
       <Field>
-        <label htmlFor="name">Name</label>
-        <input id="name" placeholder="Test input" />
+        <FieldLabel htmlFor="name">Name</FieldLabel>
+        <Input id="name" placeholder="Test input" />
       </Field>
 
       <Button variant="primary">Primary action</Button>

package/agent-docs/AGENTS.md

@@ -4,7 +4,7 @@ Rules for this install live under `agent-docs/` in `@equal-experts/kuat-core`, `
 
 1. Run `ensure-rules.sh` from kuat-agent-docs skills (symlinked) — expect `RULES_SOURCE=package` when cwd has node_modules.
 2. Load `agent-docs/rules/LOADING-consumer.md`.
-3. Load component guides via `agent-docs/components.manifest.json`.
+3. Load component guides via `agent-docs/components/components.manifest.json`.
 4. Skills: `kuat-review`, `kuat-create` from [kuat-agent-docs](https://github.com/equalexperts/kuat-agent-docs).
 
-**Version:** 0.14.0-beta.0 · **Rules snapshot:** 538afc80d437
+**Version:** 0.14.0-beta.2 · **Rules snapshot:** 9b0e773d809b

package/agent-docs/README.md

@@ -14,4 +14,4 @@ Curated agent docs bundled with `@equal-experts/kuat-core`, `@equal-experts/kuat
 node scripts/agent-docs/bundle-for-core.mjs
 ```
 
-Built against upstream ref: `538afc80d437`
+Built against upstream ref: `9b0e773d809b`

package/agent-docs/manifest.json

@@ -1,8 +1,8 @@
 {
-  "packageVersion": "0.14.0-beta.0",
+  "packageVersion": "0.14.0-beta.2",
   "rules": {
-    "snapshotRef": "538afc80d4372a6c6cdcd75c4d35782b5988a664",
-    "snapshotDate": "2026-06-24T13:14:07.261Z",
+    "snapshotRef": "9b0e773d809beedff9cd663ecddc2b6be0b69897",
+    "snapshotDate": "2026-07-01T10:17:15.975Z",
     "sourceRepo": "equalexperts/kuat-agent-docs",
     "loadingPath": "agent-docs/rules/LOADING-consumer.md"
   }

package/agent-docs/rules/LOADING-consumer.md

@@ -2,7 +2,7 @@
 
 **Package:** @equal-experts/kuat-core (and mirrored in kuat-react / kuat-vue agent-docs)
 
-**Snapshot:** 538afc80d437
+**Snapshot:** 9b0e773d809b
 
 ## Default load (web product / marketing UI)
 

package/dist/components/ui/carousel/carousel.d.ts

@@ -1,7 +1,7 @@
 import { default as useEmblaCarousel, UseEmblaCarouselType } from 'embla-carousel-react';
 import * as React from "react";
 type CarouselApi = UseEmblaCarouselType[1];
-type CarouselOptions = UseEmblaCarouselType[0];
+type CarouselOptions = Parameters<typeof useEmblaCarousel>[0];
 type CarouselPlugins = Parameters<typeof useEmblaCarousel>[1];
 type CarouselOrientation = "horizontal" | "vertical";
 export type CarouselItemBasis = 1 | 2 | 3;