@equal-experts/kuat-vue 0.13.0 → 0.13.1

package/agent-docs/external/kuat-agent-rules/kuat-docs/rules/types/web/product/technical.md

@@ -0,0 +1,488 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations
+---
+
+# Technical Guidelines
+
+Technical setup and integration guide for Equal Experts web applications using the Kuat Design System.
+
+---
+
+**Prerequisites:** Load [foundations](../../../foundations/) first.
+
+---
+
+## Quick reference
+
+- **Stack:** Application → Kuat Blocks → Kuat custom components → shadcn components → kuat-core (tokens, theme).
+- **Priority:** Prefer Kuat Blocks, then Kuat components, then shadcn; custom build only when none fit.
+- **Setup:** Install `@equal-experts/kuat-core`; preset Tailwind; import `kuat-core/variables.css`; init shadcn (Slate, CSS vars); add components as needed.
+- **Theming:** CSS variables from kuat-core; dark mode via class or media; persist preference in localStorage if needed.
+- **Tokens:** Use Tailwind utilities and CSS variables from design tokens; avoid hardcoded colours/spacing.
+- **Rules (app consumers):** Agent rules are bundled in `@equal-experts/kuat-react` / `kuat-vue` at `agent-docs/` — version matches the installed package. See [consumption-architecture.md](../../../../setup/consumption-architecture.md).
+- **Component usage:** Resolve IDs via [component-registry.md](./component-registry.md); canonical guides in package or overlay `components/`.
+
+*Full detail follows.*
+
+---
+
+## Consumer setup (applications)
+
+For step-by-step install in a new app, prefer the **package README** (`@equal-experts/kuat-react`) and bundled `agent-docs/AGENTS.md` after install. This file summarises the stack; duplicate setup prose is intentionally reduced.
+
+Override bundled rules with a `kuat-agent-docs` git clone only when you need slides, marketing, or bleeding-edge upstream guidance (`KUAT_RULES_PATH`).
+
+---
+
+## Overview
+
+The Kuat Design System uses a layered architecture:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Application                                   │
+├─────────────────────────────────────────────────────┤
+│  Kuat Blocks (Header, Footer, etc.)                 │  ← From kuat-react/vue
+├─────────────────────────────────────────────────────┤
+│  Kuat Custom Components (ButtonGroup)               │  ← From kuat-react/vue
+├─────────────────────────────────────────────────────┤
+│  shadcn Components (Button, Dialog, etc.)           │  ← Installed directly
+├─────────────────────────────────────────────────────┤
+│  kuat-core (Design Tokens, Theme)                   │  ← Foundation
+└─────────────────────────────────────────────────────┘
+```
+
+**Component Priority:**
+1. **Kuat Blocks** - Pre-built compositions for common patterns
+2. **Kuat Components** - Custom components not in shadcn (e.g., ButtonGroup)
+3. **shadcn Components** - Standard UI components themed by kuat-core
+4. **Custom Build** - Only when none of the above fit
+
+---
+
+## Quick Start (React)
+
+### Step 1: Install kuat-core
+
+```bash
+pnpm add @equal-experts/kuat-core
+```
+
+### Step 2: Configure Tailwind CSS
+
+```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;
+```
+
+### Step 3: Import Design Tokens
+
+```typescript
+// main.tsx or App.tsx
+import '@equal-experts/kuat-core/variables.css';
+import './styles.css'; // Your app styles
+```
+
+### Step 4: Initialize shadcn
+
+```bash
+npx shadcn@latest init
+```
+
+When prompted, use these settings:
+- Style: Default
+- Base color: Slate
+- CSS variables: Yes
+- Tailwind config: tailwind.config.ts
+- Components path: src/components
+- Utils path: src/lib/utils
+
+### Step 5: Install shadcn Components
+
+```bash
+# Install components as needed
+npx shadcn@latest add button
+npx shadcn@latest add dialog
+npx shadcn@latest add dropdown-menu
+```
+
+### Step 6: Install Kuat Custom Components (Optional)
+
+If you need Kuat-specific components like ButtonGroup:
+
+```bash
+pnpm add @equal-experts/kuat-react
+```
+
+```tsx
+// Only import custom components, not standard ones
+import { ButtonGroup, ButtonGroupText } from '@equal-experts/kuat-react';
+import { Button } from '@/components/ui/button'; // Your shadcn copy
+
+function Example() {
+  return (
+    <ButtonGroup>
+      <Button>Option A</Button>
+      <Button>Option B</Button>
+      <Button>Option C</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+---
+
+## Quick Start (Vue)
+
+### Step 1: Install kuat-core
+
+```bash
+pnpm add @equal-experts/kuat-core
+```
+
+### Step 2: Configure Tailwind CSS
+
+```typescript
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+import kuatPreset from '@equal-experts/kuat-core';
+
+export default {
+  presets: [kuatPreset],
+  content: [
+    './src/**/*.{vue,js,ts}',
+    './node_modules/@equal-experts/kuat-vue/**/*.{vue,js,ts}',
+  ],
+} satisfies Config;
+```
+
+### Step 3: Import Design Tokens
+
+```typescript
+// main.ts
+import '@equal-experts/kuat-core/variables.css';
+import './style.css';
+import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#app');
+```
+
+### Step 4: Initialize shadcn-vue
+
+```bash
+npx shadcn-vue@latest init
+```
+
+### Step 5: Install shadcn-vue Components
+
+```bash
+npx shadcn-vue@latest add button
+npx shadcn-vue@latest add dialog
+```
+
+### Step 6: Install Kuat Custom Components (Optional)
+
+```bash
+pnpm add @equal-experts/kuat-vue
+```
+
+```vue
+<script setup lang="ts">
+import { ButtonGroup, ButtonGroupText } from '@equal-experts/kuat-vue';
+import { Button } from '@/components/ui/button';
+</script>
+
+<template>
+  <ButtonGroup>
+    <Button>Option A</Button>
+    <Button>Option B</Button>
+  </ButtonGroup>
+</template>
+```
+
+---
+
+## Project Structure
+
+After setup, your project should look like:
+
+```
+your-project/
+├── src/
+│   ├── components/
+│   │   └── ui/              # shadcn components (installed directly)
+│   │       ├── button.tsx
+│   │       ├── dialog.tsx
+│   │       └── ...
+│   ├── lib/
+│   │   └── utils.ts         # cn() utility from shadcn
+│   ├── App.tsx
+│   └── main.tsx
+├── tailwind.config.ts       # Uses kuatPreset
+├── components.json          # shadcn CLI config
+└── package.json
+```
+
+---
+
+## Framework Integration Guides
+
+### Next.js (App Router)
+
+**tailwind.config.ts**
+
+```typescript
+import type { Config } from 'tailwindcss';
+import kuatPreset from '@equal-experts/kuat-core';
+
+export default {
+  presets: [kuatPreset],
+  content: [
+    './app/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+} satisfies Config;
+```
+
+**app/layout.tsx**
+
+```tsx
+import '@equal-experts/kuat-core/variables.css';
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className="bg-background text-foreground min-h-screen">
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+### Vite + React
+
+**vite.config.ts**
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+**src/main.tsx**
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import '@equal-experts/kuat-core/variables.css';
+import './index.css';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+### Vite + Vue
+
+**vite.config.ts**
+
+```typescript
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss()],
+});
+```
+
+**src/main.ts**
+
+```typescript
+import { createApp } from 'vue';
+import '@equal-experts/kuat-core/variables.css';
+import './style.css';
+import App from './App.vue';
+
+createApp(App).mount('#app');
+```
+
+---
+
+## Theming
+
+shadcn components are automatically themed when you:
+
+1. Import `@equal-experts/kuat-core/variables.css`
+2. Use the kuat Tailwind preset
+
+The CSS variables from kuat-core provide:
+- Brand colors (EE Blue, Transform Teal, etc.)
+- Typography (Lexend, JetBrains Mono, Lora)
+- Spacing scale (8-point grid)
+- Border radius values
+- Light/dark mode support
+
+### Dark Mode
+
+Apply the `.dark` class to your root element:
+
+```tsx
+<html className="dark">
+  <body>
+    <App />
+  </body>
+</html>
+```
+
+Or toggle dynamically:
+
+```typescript
+document.documentElement.classList.toggle('dark');
+```
+
+### Persisting User Preference
+
+```typescript
+const THEME_KEY = 'kuat-theme';
+
+function initTheme() {
+  const saved = localStorage.getItem(THEME_KEY);
+  
+  if (saved === 'dark') {
+    document.documentElement.classList.add('dark');
+  } else if (saved === 'light') {
+    document.documentElement.classList.remove('dark');
+  } else {
+    // Use system preference
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    document.documentElement.classList.toggle('dark', prefersDark);
+  }
+}
+
+function setTheme(theme: 'light' | 'dark' | 'system') {
+  localStorage.setItem(THEME_KEY, theme);
+  
+  if (theme === 'dark') {
+    document.documentElement.classList.add('dark');
+  } else if (theme === 'light') {
+    document.documentElement.classList.remove('dark');
+  } else {
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    document.documentElement.classList.toggle('dark', prefersDark);
+  }
+}
+```
+
+---
+
+## Design Token Reference
+
+### Available CSS Variables
+
+```css
+/* Semantic Colors */
+--background, --foreground
+--primary, --primary-foreground
+--secondary, --secondary-foreground
+--muted, --muted-foreground
+--accent, --accent-foreground
+--destructive, --destructive-foreground
+--card, --card-foreground
+--popover, --popover-foreground
+--border, --input, --ring
+
+/* Sidebar Colors */
+--sidebar, --sidebar-foreground
+--sidebar-primary, --sidebar-primary-foreground
+--sidebar-accent, --sidebar-accent-foreground
+--sidebar-border, --sidebar-ring
+
+/* Brand Colors (full palettes) */
+--ee-blue-50 through --ee-blue-950
+--tech-blue-50 through --tech-blue-950
+--transform-teal-50 through --transform-teal-950
+--equal-ember-50 through --equal-ember-950
+
+/* Typography */
+--font-sans, --font-serif, --font-mono
+
+/* Layout */
+--radius, --spacing, --tracking-normal
+```
+
+### Tailwind Utility Classes
+
+```html
+<!-- Colors -->
+<div class="bg-background text-foreground">
+<div class="bg-primary text-primary-foreground">
+<div class="bg-sidebar text-sidebar-foreground">
+<div class="border-border">
+
+<!-- Border Radius -->
+<div class="rounded-sm">  <!-- Small -->
+<div class="rounded-md">  <!-- Medium -->
+<div class="rounded-lg">  <!-- Large -->
+```
+
+---
+
+## Troubleshooting
+
+### Components not styled correctly
+
+1. Verify `@equal-experts/kuat-core/variables.css` is imported before other styles
+2. Check that `kuatPreset` is in your Tailwind config `presets` array
+3. Ensure shadcn components are in the Tailwind `content` paths
+
+### TypeScript errors
+
+1. Ensure `@types/react` (React) or `vue` (Vue) are installed
+2. Set `moduleResolution` to `bundler` or `node16` in tsconfig
+
+### Dark mode not working
+
+1. Verify `.dark` class is applied to `<html>` or a parent element
+2. Check that CSS variables are imported
+
+### Build errors
+
+1. Check Node version: Requires Node.js 18 or higher
+2. Verify package versions: Ensure Tailwind CSS v4 is installed
+3. Clear caches: Run `rm -rf node_modules && pnpm install`
+
+---
+
+## Related Documentation
+
+- [Design Rules](./design.md) - Layout and visual design
+- [Component Decision Tree](./component-decision-tree.md) - Component selection
+- [Component registry](./component-registry.md) - Stable IDs → package/overlay guides
+- [consumption-architecture.md](../../../../setup/consumption-architecture.md) - Entry points and npm bundling
+- [Examples](./examples/) - Illustrative patterns only ([DEPRECATIONS.md](./DEPRECATIONS.md))

package/agent-docs/kuat-docs/rules/README.md

@@ -0,0 +1,148 @@
+# Kuat rules index
+
+Single entry point for **Equal Experts** canonical rules (vendored copy) and **Kuat**-specific implementation notes. Generic brand doctrine is **not** duplicated here—link targets live under [`external/kuat-agent-rules`](../../external/kuat-agent-rules).
+
+> Policy: [Rules source of truth](../setup/rules-source-of-truth.md). Task-loading order for upstream: [`LOADING.md`](../../external/kuat-agent-rules/kuat-docs/rules/LOADING.md).
+
+**Path prefix (this repo):** `external/kuat-agent-rules/kuat-docs/rules/`
+
+---
+
+## Canonical EE rules (vendored)
+
+Use these files in the synced tree. Paths below are relative to the repo root.
+
+### Rules index & loading
+
+| Resource | Path |
+|----------|------|
+| Rules README | [`external/kuat-agent-rules/kuat-docs/rules/README.md`](../../external/kuat-agent-rules/kuat-docs/rules/README.md) |
+| Task loading | [`external/kuat-agent-rules/kuat-docs/rules/LOADING.md`](../../external/kuat-agent-rules/kuat-docs/rules/LOADING.md) |
+
+### Foundations — design
+
+| Topic | Path |
+|-------|------|
+| Design language | [`.../foundations/design/design-language.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/design-language.md) |
+| Colours | [`.../foundations/design/colours.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/colours.md) |
+| Typography | [`.../foundations/design/typography.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/typography.md) |
+| Spacing | [`.../foundations/design/spacing.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/spacing.md) |
+| Borders | [`.../foundations/design/borders.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/borders.md) |
+
+### Foundations — logo
+
+| Topic | Path |
+|-------|------|
+| Logo | [`.../foundations/logo.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/logo.md) |
+
+### Foundations — content
+
+| Topic | Path |
+|-------|------|
+| Content index | [`.../foundations/content/README.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/README.md) |
+| Voice and tone | [`.../foundations/content/voice-and-tone.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/voice-and-tone.md) |
+| Writing style | [`.../foundations/content/writing-style.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/writing-style.md) |
+| Formatting | [`.../foundations/content/formatting.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/formatting.md) |
+| Punctuation | [`.../foundations/content/punctuation.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/punctuation.md) |
+| Numbers | [`.../foundations/content/numbers.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/numbers.md) |
+
+### Types — web — product
+
+| Topic | Path |
+|-------|------|
+| Product design (layouts / navigation scenarios) | [`.../types/web/product/design.md`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/product/design.md) |
+| Product content | [`.../types/web/product/content/product-content.md`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/product/content/product-content.md) |
+| Product content (directory) | [`.../types/web/product/content/`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/product/content/) |
+
+### Types — web — marketing
+
+| Topic | Path |
+|-------|------|
+| Marketing website | [`.../types/web/marketing/website.md`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/marketing/website.md) |
+| Marketing content | [`.../types/web/marketing/content/marketing-content.md`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/marketing/content/marketing-content.md) |
+| Marketing content (directory) | [`.../types/web/marketing/content/`](../../external/kuat-agent-rules/kuat-docs/rules/types/web/marketing/content/) |
+
+---
+
+## Kuat implementation (this monorepo)
+
+High-level EE design language is in [`design-language.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/design-language.md). The sections below are **Kuat-only**: how tokens and packages map to code.
+
+### What is Kuat?
+
+Kuat is the design decision layer for Equal Experts web UIs: tokens (`@equal-experts/kuat-core`), components (`@equal-experts/kuat-react`, `@equal-experts/kuat-vue`), blocks, and documentation.
+
+### Token architecture
+
+**Layer 1 — Brand colours:** EE Blue, Transform Teal, Tech Blue, Equal Ember (see upstream colours doc).
+
+**Layer 2 — Semantic tokens** (examples): `--primary`, `--secondary`, `--accent`, `--background`, `--foreground`, `--muted`, `--destructive`, `--border`, `--input`, `--ring`.
+
+**Layer 3 — Component tokens** (examples): `--card`, `--card-foreground`, `--sidebar`, `--sidebar-foreground`, `--popover`, `--popover-foreground`.
+
+### Theming
+
+- **Light:** default semantic tokens.
+- **Dark:** add `.dark` on the root; semantic tokens switch; follow upstream usage for brand colours.
+
+### Package layout
+
+```
+@equal-experts/kuat-core/
+├── src/variables.css
+└── tailwind.config.ts
+
+@equal-experts/kuat-react/ → src/components/
+@equal-experts/kuat-vue/   → src/components/
+```
+
+### Integration docs
+
+- [Integration guide](../setup/integration.md)
+- [Kuat core integration](../setup/kuat-core-integration.md)
+
+---
+
+## Local rule documents (not mirrored above)
+
+These files live only under `kuat-docs/rules/` and add Kuat or scenario-specific guidance:
+
+| Area | Entry |
+|------|--------|
+| Layout primitives | [design/layouts.md](./design/layouts.md) |
+| Components | [components/README.md](./components/README.md), [patterns.md](./components/patterns.md) |
+| Accessibility | [accessibility/README.md](./accessibility/README.md) |
+| Scenarios | [scenarios/README.md](./scenarios/README.md) |
+
+---
+
+## Quick navigation
+
+| Category | Notes |
+|----------|--------|
+| **EE canonical** | Tables above → `external/kuat-agent-rules` |
+| **Kuat tokens & packages** | Section *Kuat implementation* |
+| **[Design — layouts](./design/layouts.md)** | Kuat layout primitives + upstream scenario links |
+| **[Accessibility](./accessibility/)** | WCAG-oriented local guides |
+| **[Components](./components/)** | Naming, variants, patterns |
+| **[Scenarios](./scenarios/)** | Applied flows (auth, dashboards, …) |
+
+---
+
+## Implementation examples
+
+Code samples are not in this file:
+
+- [examples/react/](../examples/react/)
+- [examples/vue/](../examples/vue/)
+- [examples/css/](../examples/css/)
+
+---
+
+## For AI agents
+
+1. **Default:** Load **this file** (`kuat-docs/rules/README.md`), then open the specific upstream file(s) from the tables (same paths under `external/kuat-agent-rules/...`).
+2. **Design tokens / brand colour decisions:** [`foundations/design/colours.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/design/colours.md) (and spacing/typography/borders as needed).
+3. **Content voice / UX copy:** [`foundations/content/voice-and-tone.md`](../../external/kuat-agent-rules/kuat-docs/rules/foundations/content/voice-and-tone.md) plus product or marketing content docs above.
+4. **Layout structure in code:** [design/layouts.md](./design/layouts.md).
+5. **Components:** [components/patterns.md](./components/patterns.md) + relevant `examples/{framework}/`.