@equal-experts/kuat-react 0.8.0 → 0.9.2

package/README.md

@@ -27,18 +27,47 @@ React components and blocks for the Kuat Design System: **localized primitives**
 ## Installation
 
 ```bash
-pnpm add @equal-experts/kuat-core @equal-experts/kuat-react
+pnpm add react react-dom @equal-experts/kuat-core @equal-experts/kuat-react
 ```
 
 You need **both** packages: core supplies CSS variables and the Tailwind preset; this package supplies components.
 
+### Agent Guardrails
+
+Add this to your project `AGENTS.md` (or `.cursorrules`) so agent workflows stay Kuat-first:
+
+```markdown
+## Kuat UI Component Selection Rules
+1. Load bundled rules entrypoints from `@equal-experts/kuat-core`:
+   - `node_modules/@equal-experts/kuat-core/agent-docs/kuat-docs/rules/README.md`
+   - `node_modules/@equal-experts/kuat-core/agent-docs/external/kuat-agent-rules/kuat-docs/rules/LOADING.md`
+2. Ensure decisions reference both bundled Equal Experts foundations and web rules (`.../external/kuat-agent-rules/.../foundations/*` and `.../types/web/*`).
+3. Read `kuat-docs/setup/choosing-components.md` before building UI.
+4. Choose sources in order: Kuat blocks -> Kuat components -> shadcn gaps -> custom.
+5. Verify exports in `@equal-experts/kuat-react` before implementing.
+6. Document the chosen source and any exception rationale in PR notes.
+```
+
 ### Peer dependencies
 
-`react` and `react-dom` are required. Radix UI and other peers are listed in this package’s `package.json` under `peerDependencies`—install the primitives that match the components you use.
+Install peers for the components you use before running `dev` or `build`.
+
+| Components you use | Required peers |
+|---|---|
+| `Button`, `KuatHeader` | `@radix-ui/react-slot`, `lucide-react` |
+| `Accordion` | `@radix-ui/react-accordion` |
+| `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` |
+| `Switch` / `SwitchField` | `@radix-ui/react-switch` |
+| `Toggle` / `ToggleGroup` | `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group` |
+| `Sonner` | `sonner` |
+
+Example peer install for a broad setup:
 
 ```bash
-pnpm add react react-dom
-# Add @radix-ui/* and lucide-react as needed for your components — see peerDependencies
+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
 ```
 
 ---
@@ -81,6 +110,14 @@ import { KuatRadialProgress } from '@equal-experts/kuat-react/kuat-radial-progre
 
 See [public-api-inventory.md](https://github.com/equalexperts/kuat-mono/blob/master/kuat-docs/setup/public-api-inventory.md) for the full subpath list.
 
+`KuatCarousel` is exported from both the root barrel and subpath:
+
+```tsx
+import { KuatCarousel } from '@equal-experts/kuat-react';
+// or
+import { KuatCarousel } from '@equal-experts/kuat-react/kuat-carousel';
+```
+
 ---
 
 ## Recommended setup
@@ -101,21 +138,47 @@ export default {
 } satisfies Config;
 ```
 
-### 2. Design tokens (once per app)
+### 2. Tailwind runtime stylesheet (required for Tailwind v4)
+
+Create a global stylesheet and load Tailwind:
+
+```css
+/* src/tailwind.css */
+@import "tailwindcss";
+```
+
+### 3. Design tokens and Kuat styles (once per app entrypoint)
 
 ```typescript
 // main.tsx
 import '@equal-experts/kuat-core/variables.css';
+import '@equal-experts/kuat-react/styles';
+import './tailwind.css';
+import './app.css';
 ```
 
-### 3. shadcn for gaps only
+Import order matters: load Kuat tokens and 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
 
 ```bash
 npx shadcn@latest init
 npx shadcn@latest add dialog dropdown-menu   # examples — skip `button` if you use Kuat Button
 ```
 
-### 4. Use Kuat + shadcn together
+### 5. Use Kuat + shadcn together
 
 ```tsx
 import { Button, ButtonGroup, Field } from '@equal-experts/kuat-react';
@@ -170,6 +233,56 @@ export function Box({ className, ...props }: React.ComponentProps<'div'>) {
 
 ---
 
+## Verification test (human or agent)
+
+Use this quick smoke test after installation to verify imports, styles, and Tailwind are wired correctly.
+
+### 1. Add a smoke component
+
+```tsx
+import { Button, Field, KuatCarousel, KuatCarouselContent, KuatCarouselItem } from '@equal-experts/kuat-react';
+
+export function KuatInstallSmoke() {
+  return (
+    <div className="space-y-6 p-6">
+      <h1 className="text-4xl font-bold">Kuat install smoke test</h1>
+
+      <Field>
+        <label htmlFor="name">Name</label>
+        <input id="name" placeholder="Test input" />
+      </Field>
+
+      <Button variant="primary">Primary action</Button>
+
+      <KuatCarousel opts={{ loop: false }}>
+        <KuatCarouselContent>
+          <KuatCarouselItem>Slide 1</KuatCarouselItem>
+          <KuatCarouselItem>Slide 2</KuatCarouselItem>
+        </KuatCarouselContent>
+      </KuatCarousel>
+    </div>
+  );
+}
+```
+
+### 2. Run checks
+
+```bash
+pnpm build
+pnpm dev
+```
+
+### 3. Pass/fail criteria
+
+- Pass: no unresolved import errors for `@equal-experts/kuat-react/styles` or component imports.
+- Pass: heading renders visibly larger and bold (`text-4xl font-bold` applied).
+- Pass: `Button`, `Field`, and `KuatCarousel` render with Kuat styles (not plain browser defaults).
+- Pass: typography uses Kuat font stack (Lexend for sans) rather than template defaults.
+- Fail: any need to import internal `dist/*.css` files manually.
+- Fail: selecting custom/shadcn carousel without documenting why `@equal-experts/kuat-react` carousel exports were not used.
+
+---
+
 ## Migration (legacy projects)
 
 Older docs suggested installing **all** primitives via shadcn. Kuat now ships many components from this package.

package/dist/accordion.js

@@ -1,10 +1,9 @@
-import { c as n } from "./utils-DLUjLwnh.js";
-/* empty css                */
-import { A as i, c as t, a as e, b as s } from "./accordion-DwQCxX_5.js";
+import { c as r } from "./utils-DLUjLwnh.js";
+import { A as a, c as e, a as i, b as s } from "./accordion-CUlVo4uo.js";
 export {
-  i as Accordion,
-  t as AccordionContent,
-  e as AccordionItem,
+  a as Accordion,
+  e as AccordionContent,
+  i as AccordionItem,
   s as AccordionTrigger,
-  n as cn
+  r as cn
 };

package/dist/alert-dialog.js

@@ -1,17 +1,16 @@
-import { c as r } from "./utils-DLUjLwnh.js";
-/* empty css                */
-import { A as t, i, j as g, d as s, h as A, f as D, e as c, b as n, a as p, g as f, c as m } from "./alert-dialog-CT9DCCMH.js";
+import { c as e } from "./utils-DLUjLwnh.js";
+import { A as o, i as t, j as i, d as g, h as s, f as A, e as D, b as c, a as n, g as f, c as p } from "./alert-dialog-yHaNWLGX.js";
 export {
-  t as AlertDialog,
-  i as AlertDialogAction,
-  g as AlertDialogCancel,
-  s as AlertDialogContent,
-  A as AlertDialogDescription,
-  D as AlertDialogFooter,
-  c as AlertDialogHeader,
-  n as AlertDialogOverlay,
-  p as AlertDialogPortal,
+  o as AlertDialog,
+  t as AlertDialogAction,
+  i as AlertDialogCancel,
+  g as AlertDialogContent,
+  s as AlertDialogDescription,
+  A as AlertDialogFooter,
+  D as AlertDialogHeader,
+  c as AlertDialogOverlay,
+  n as AlertDialogPortal,
   f as AlertDialogTitle,
-  m as AlertDialogTrigger,
-  r as cn
+  p as AlertDialogTrigger,
+  e as cn
 };

package/dist/badge.js

@@ -1,8 +1,7 @@
 import { c as e } from "./utils-DLUjLwnh.js";
-/* empty css                */
-import { B as t, b as m } from "./badge-Yftb6Tdy.js";
+import { B as s, b as t } from "./badge-BZgdEQSD.js";
 export {
-  t as Badge,
-  m as badgeVariants,
+  s as Badge,
+  t as badgeVariants,
   e as cn
 };

package/dist/button-group.js

@@ -1,10 +1,9 @@
-import { c as a } from "./utils-DLUjLwnh.js";
-/* empty css                */
-import { B as u, a as n, b as s, c as e } from "./button-group-BNfxHMty.js";
+import { c as r } from "./utils-DLUjLwnh.js";
+import { B as u, a as p, b as n, c as s } from "./button-group-enIzvVeN.js";
 export {
   u as ButtonGroup,
-  n as ButtonGroupSeparator,
-  s as ButtonGroupText,
-  e as buttonGroupVariants,
-  a as cn
+  p as ButtonGroupSeparator,
+  n as ButtonGroupText,
+  s as buttonGroupVariants,
+  r as cn
 };

package/dist/button.js

@@ -1,8 +1,7 @@
 import { c as a } from "./utils-DLUjLwnh.js";
-/* empty css                */
-import { B as s, b as m } from "./button-DqdoNQqx.js";
+import { B as n, b as s } from "./button-C0a1gFoV.js";
 export {
-  s as Button,
-  m as buttonVariants,
+  n as Button,
+  s as buttonVariants,
   a as cn
 };