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

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

@@ -0,0 +1,155 @@
+# 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). Upstream is now a passive reference library — start at [`reference/README.md`](../../external/kuat-agent-rules/reference/README.md).
+
+**Path prefix (this repo):** `external/kuat-agent-rules/reference/`
+
+---
+
+## Canonical EE rules (vendored)
+
+Use these files in the synced tree. Paths below are relative to the repo root.
+
+### Reference index & loading
+
+| Resource | Path |
+|----------|------|
+| Reference index | [`external/kuat-agent-rules/reference/README.md`](../../external/kuat-agent-rules/reference/README.md) |
+| Migration map (old→new paths) | [`external/kuat-agent-rules/reference/MIGRATION-MAP.md`](../../external/kuat-agent-rules/reference/MIGRATION-MAP.md) |
+
+### Foundations — design language
+
+| Topic | Path |
+|-------|------|
+| Design language | [`.../design-language/design-language.md`](../../external/kuat-agent-rules/reference/design-language/design-language.md) |
+| Colours | [`.../design-language/colours.md`](../../external/kuat-agent-rules/reference/design-language/colours.md) |
+| Typography | [`.../design-language/typography.md`](../../external/kuat-agent-rules/reference/design-language/typography.md) |
+| Spacing | [`.../design-language/spacing.md`](../../external/kuat-agent-rules/reference/design-language/spacing.md) |
+| Borders | [`.../design-language/borders.md`](../../external/kuat-agent-rules/reference/design-language/borders.md) |
+
+### Foundations — brand
+
+| Topic | Path |
+|-------|------|
+| Brand | [`.../brand/brand.md`](../../external/kuat-agent-rules/reference/brand/brand.md) |
+| Logo | [`.../brand/logo.md`](../../external/kuat-agent-rules/reference/brand/logo.md) |
+| Voice and tone | [`.../brand/voice-and-tone.md`](../../external/kuat-agent-rules/reference/brand/voice-and-tone.md) |
+
+### Foundations — content
+
+| Topic | Path |
+|-------|------|
+| Content index | [`.../content/README.md`](../../external/kuat-agent-rules/reference/content/README.md) |
+| Writing style | [`.../content/writing-style.md`](../../external/kuat-agent-rules/reference/content/writing-style.md) |
+| Formatting | [`.../content/formatting.md`](../../external/kuat-agent-rules/reference/content/formatting.md) |
+| Punctuation | [`.../content/punctuation.md`](../../external/kuat-agent-rules/reference/content/punctuation.md) |
+| Numbers | [`.../content/numbers.md`](../../external/kuat-agent-rules/reference/content/numbers.md) |
+
+### Foundations — accessibility
+
+| Topic | Path |
+|-------|------|
+| Accessibility | [`.../accessibility/accessibility.md`](../../external/kuat-agent-rules/reference/accessibility/accessibility.md) |
+
+### Media types — web product
+
+| Topic | Path |
+|-------|------|
+| Product design (layouts / navigation patterns) | [`.../media-types/web-product/design.md`](../../external/kuat-agent-rules/reference/media-types/web-product/design.md) |
+| Product content | [`.../media-types/web-product/content/product-content.md`](../../external/kuat-agent-rules/reference/media-types/web-product/content/product-content.md) |
+| Product content (directory) | [`.../media-types/web-product/content/`](../../external/kuat-agent-rules/reference/media-types/web-product/content/) |
+
+### Media types — web marketing
+
+| Topic | Path |
+|-------|------|
+| Marketing website | [`.../media-types/web-marketing/website.md`](../../external/kuat-agent-rules/reference/media-types/web-marketing/website.md) |
+| Marketing content | [`.../media-types/web-marketing/content/marketing-content.md`](../../external/kuat-agent-rules/reference/media-types/web-marketing/content/marketing-content.md) |
+| Marketing content (directory) | [`.../media-types/web-marketing/content/`](../../external/kuat-agent-rules/reference/media-types/web-marketing/content/) |
+
+---
+
+## Kuat implementation (this monorepo)
+
+High-level EE design language is in [`design-language.md`](../../external/kuat-agent-rules/reference/design-language/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:** [`design-language/colours.md`](../../external/kuat-agent-rules/reference/design-language/colours.md) (and spacing/typography/borders as needed).
+3. **Content voice / UX copy:** [`brand/voice-and-tone.md`](../../external/kuat-agent-rules/reference/brand/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}/`.

package/agent-docs/kuat-docs/rules/design/layouts.md

@@ -0,0 +1,394 @@
+# Layout Primitives
+
+Reusable layout building blocks for the Kuat Design System. This document defines layout types, content regions, and structural guidelines - independent of framework.
+
+For scenario-specific guidance (dashboards, authentication, marketing pages), see [Scenarios](../scenarios/).
+
+**Upstream (brand layout patterns):** Product interfaces and dashboards follow [`media-types/web-product/design.md`](../../../external/kuat-agent-rules/reference/media-types/web-product/design.md). Marketing sites and campaigns follow [`media-types/web-marketing/website.md`](../../../external/kuat-agent-rules/reference/media-types/web-marketing/website.md). This file focuses on **Kuat layout primitives** used in code, not on replacing those reference guides.
+
+---
+
+## Overview
+
+Layouts are the structural foundation of every page. Kuat provides five layout primitives that can be combined and configured for different use cases.
+
+**Key principle:** Choose the layout primitive that best supports your content and navigation needs, then configure it for your specific scenario.
+
+---
+
+## Layout Types
+
+### 1. Horizontal Navigation Layout
+
+Header bar with navigation, full-width content below.
+
+```
+┌─────────────────────────────────────────┐
+│ Header Bar                              │
+│ [Logo]    [Nav Items]    [Actions]      │
+├─────────────────────────────────────────┤
+│                                         │
+│           Main Content Area             │
+│           (Full width)                  │
+│                                         │
+├─────────────────────────────────────────┤
+│ Footer (optional)                       │
+└─────────────────────────────────────────┘
+```
+
+**Use when:**
+- Limited navigation items (5-7 max)
+- Content is the primary focus
+- Simple information architecture
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Header height | 64-80px |
+| Header padding | 16-24px horizontal, 16px vertical |
+| Content max-width | 1200-1400px (or full width) |
+| Content padding | 24-32px |
+
+**Variants:**
+- Light header (`bg-background`) - Marketing, public-facing
+- Dark header (`bg-sidebar`) - Applications, dashboards
+
+---
+
+### 2. Sidebar Navigation Layout
+
+Fixed or collapsible sidebar with content area.
+
+```
+┌──────┬──────────────────────────────────┐
+│      │ Top Bar (optional)               │
+│ Side │ [Breadcrumbs]      [Actions]     │
+│ bar  │──────────────────────────────────┤
+│      │                                  │
+│ [Logo│       Main Content Area          │
+│ Nav  │                                  │
+│ Items│                                  │
+│     ]│                                  │
+└──────┴──────────────────────────────────┘
+```
+
+**Use when:**
+- Complex navigation (8+ items)
+- Hierarchical structure
+- Persistent navigation needed
+- Application interfaces
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Sidebar width | 240-280px expanded |
+| Sidebar collapsed | 64px (icons only) |
+| Top bar height | 48-64px |
+| Content padding | 24-32px |
+
+**Variants:**
+- Dark sidebar (`bg-sidebar`) - Standard for apps
+- Light sidebar (`bg-muted`) - Documentation sites
+
+---
+
+### 3. Single Column Layout
+
+Centered content with no persistent navigation.
+
+```
+┌─────────────────────────────────────────┐
+│              [Logo] (optional)          │
+├─────────────────────────────────────────┤
+│                                         │
+│     ┌─────────────────────────┐         │
+│     │                         │         │
+│     │    Centered Content     │         │
+│     │    (max-width card)     │         │
+│     │                         │         │
+│     └─────────────────────────┘         │
+│                                         │
+├─────────────────────────────────────────┤
+│         Footer (minimal/optional)       │
+└─────────────────────────────────────────┘
+```
+
+**Use when:**
+- Focused single task (login, registration)
+- Error pages (404, 500)
+- Confirmation/success pages
+- Minimal distraction needed
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Content max-width | 400-480px |
+| Content padding | 24-32px |
+| Vertical alignment | Centered (min-height: 100vh) |
+| Background | `bg-background` or `bg-muted` |
+
+---
+
+### 4. Multi-Column Layout
+
+Grid-based content regions for complex pages.
+
+```
+┌─────────────────────────────────────────┐
+│ Header                                  │
+├─────────────────────────────────────────┤
+│ ┌─────────┐ ┌─────────┐ ┌─────────┐    │
+│ │ Column  │ │ Column  │ │ Column  │    │
+│ │   1     │ │   2     │ │   3     │    │
+│ └─────────┘ └─────────┘ └─────────┘    │
+│                                         │
+│ ┌───────────────────┐ ┌───────────────┐│
+│ │    Column 1       │ │   Column 2    ││
+│ └───────────────────┘ └───────────────┘│
+├─────────────────────────────────────────┤
+│ Footer                                  │
+└─────────────────────────────────────────┘
+```
+
+**Use when:**
+- Dashboard overviews
+- Feature/comparison pages
+- Card-based content displays
+
+**Column Configurations:**
+
+| Configuration | Use Case |
+|---------------|----------|
+| 2 columns (50/50) | Comparison, side-by-side |
+| 2 columns (66/33) | Main content + sidebar info |
+| 3 columns (equal) | Feature grids, card displays |
+| 4 columns (equal) | KPI dashboards, metrics |
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Column gap | 16-24px |
+| Row gap | 16-24px |
+| Container max-width | 1200-1400px |
+
+---
+
+### 5. Split Layout
+
+Two-panel layout for focused comparison or workflow.
+
+```
+┌────────────────────┬────────────────────┐
+│                    │                    │
+│    Left Panel      │    Right Panel     │
+│                    │                    │
+│                    │                    │
+│                    │                    │
+└────────────────────┴────────────────────┘
+```
+
+**Use when:**
+- Side-by-side comparison
+- Code editor + preview
+- List + detail view
+- Documentation with table of contents
+
+**Split Ratios:**
+
+| Ratio | Use Case |
+|-------|----------|
+| 50/50 | Equal comparison |
+| 60/40 | Primary + secondary |
+| 70/30 | Main content + table of contents |
+| 33/67 | Navigation + main content |
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Divider | 1px border or resizable handle |
+| Min panel width | 240px |
+| Panel padding | 16-24px |
+
+---
+
+## Content Regions
+
+### Header Region
+
+| Property | Light Variant | Dark Variant |
+|----------|---------------|--------------|
+| Background | `bg-background` | `bg-sidebar` |
+| Text | `text-foreground` | `text-sidebar-foreground` |
+| Logo | Full-color | White monochrome |
+| Height | 64-80px | 64-72px |
+
+### Footer Region
+
+| Property | Value |
+|----------|-------|
+| Background | `bg-muted` or `bg-background` |
+| Padding | 32-48px vertical |
+| Content | Logo, links, legal text |
+
+### Main Content Region
+
+| Property | Value |
+|----------|-------|
+| Background | `bg-background` |
+| Padding | 24-32px |
+| Max-width | Varies by layout (1200-1400px typical) |
+
+### Sidebar Region
+
+| Property | Value |
+|----------|-------|
+| Background | `bg-sidebar` (dark) or `bg-muted` (light) |
+| Width | 240-280px expanded, 64px collapsed |
+| Padding | 16px |
+| Scroll | Independent scroll from main content |
+
+---
+
+## Navigation Color Tokens
+
+For dark navigation (horizontal bar or sidebar):
+
+| Token | Purpose |
+|-------|---------|
+| `--sidebar` | Navigation background (Tech Blue) |
+| `--sidebar-foreground` | Text color (White) |
+| `--sidebar-primary` | Primary accent (EE Blue) |
+| `--sidebar-primary-foreground` | Text on primary |
+| `--sidebar-accent` | Hover/active background |
+| `--sidebar-accent-foreground` | Text on accent |
+| `--sidebar-border` | Border color |
+| `--sidebar-ring` | Focus ring color |
+
+---
+
+## Spacing Guidelines
+
+Follow the 8-point grid system:
+
+| Element | Spacing |
+|---------|---------|
+| Navigation height | 64-80px (multiples of 8) |
+| Sidebar width | 240-280px (multiples of 8) |
+| Padding | 16px, 24px, 32px (multiples of 8) |
+| Content gap | 16px, 24px (multiples of 8) |
+
+---
+
+## Layout Accessibility
+
+**Reference:** [accessibility/technical.md](../accessibility/technical.md)
+
+### Landmark Roles
+
+Every layout must include proper landmarks:
+
+| Region | HTML Element | Role |
+|--------|--------------|------|
+| Header | `<header>` | banner |
+| Navigation | `<nav>` | navigation |
+| Main content | `<main>` | main |
+| Sidebar | `<aside>` | complementary |
+| Footer | `<footer>` | contentinfo |
+
+### Skip Links
+
+For layouts with significant navigation, include a skip link:
+
+```html
+<a href="#main-content" class="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+```
+
+### Focus Order
+
+- Focus order must follow visual order
+- Sidebar navigation focuses before main content
+- Modal/drawer navigation traps focus when open
+
+### Keyboard Navigation
+
+- All navigation items reachable via Tab
+- Arrow keys for navigating within menus
+- Escape closes mobile/overlay navigation
+
+---
+
+## Responsive Behavior
+
+### Breakpoints
+
+| Breakpoint | Width | Typical Use |
+|------------|-------|-------------|
+| Mobile | < 640px | Single column, overlay nav |
+| Tablet | 640-1024px | Collapsed sidebar, simplified nav |
+| Desktop | > 1024px | Full layout with all features |
+
+### Horizontal Navigation
+
+| Breakpoint | Behavior |
+|------------|----------|
+| Mobile | Collapse to hamburger menu |
+| Tablet | Show primary nav, hide secondary |
+| Desktop | Full navigation visible |
+
+### Sidebar Navigation
+
+| Breakpoint | Behavior |
+|------------|----------|
+| Mobile | Overlay/drawer, hidden by default |
+| Tablet | Collapsible (default collapsed) |
+| Desktop | Full sidebar visible (240-280px) |
+
+### Content Grids
+
+| Breakpoint | Columns |
+|------------|---------|
+| Mobile | 1 column (stacked) |
+| Tablet | 2 columns |
+| Desktop | 3-4 columns |
+
+---
+
+## Applied Patterns
+
+For scenario-specific guidance on how to use these layout primitives:
+
+| Scenario | Recommended Layout | Reference |
+|----------|-------------------|-----------|
+| Authentication | Single Column | [scenarios/authentication.md](../scenarios/authentication.md) |
+| Dashboards | Sidebar Navigation | [scenarios/dashboards.md](../scenarios/dashboards.md) |
+| Forms & Settings | Sidebar or Single Column | [scenarios/forms.md](../scenarios/forms.md) |
+| Documentation | Sidebar + Split | [scenarios/documentation.md](../scenarios/documentation.md) |
+| Marketing Pages | Horizontal Navigation | [scenarios/marketing-pages.md](../scenarios/marketing-pages.md) |
+
+---
+
+## Implementation Examples
+
+For code examples implementing these layouts:
+
+| Framework | Guide |
+|-----------|-------|
+| React | [examples/react/layouts.md](../../examples/react/layouts.md) |
+| Vue | [examples/vue/layouts.md](../../examples/vue/layouts.md) |
+| Other | [setup/kuat-core-integration.md](../../setup/kuat-core-integration.md) |
+
+---
+
+## Related Documentation
+
+- [Spacing](./spacing.md) - 8-point grid system
+- [Colours](./colours.md) - Color tokens
+- [Logo](./logo.md) - Logo usage and variants
+- [Accessibility](../accessibility/technical.md) - Technical accessibility

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

@@ -0,0 +1,83 @@
+# Scenario Patterns
+
+Applied layout and design patterns for specific use cases.
+
+Each scenario combines foundational EE rules (indexed in [`rules/README.md`](../README.md), files under `external/kuat-agent-rules`) with `rules/accessibility/` into actionable guidance for building complete page types.
+
+---
+
+## When to Use Scenarios
+
+Load a scenario guide when:
+
+- Building a specific page type (login, dashboard, pricing page)
+- Need composition guidance beyond foundational design rules
+- Want consistent patterns for common UI challenges
+
+---
+
+## Available Scenarios
+
+| Scenario | Use For | Base Layout |
+|----------|---------|-------------|
+| [authentication.md](./authentication.md) | Login, registration, password flows, MFA | Single Column |
+| [dashboards.md](./dashboards.md) | Analytics, data tables, metrics, reporting | Sidebar Navigation |
+| [forms.md](./forms.md) | Settings, multi-step forms, data entry | Varies |
+| [documentation.md](./documentation.md) | Docs sites, knowledge bases, API reference | Sidebar + Split |
+| [marketing-pages.md](./marketing-pages.md) | Landing pages, pricing, features, case studies | Horizontal Navigation |
+
+---
+
+## Scenario Structure
+
+Each scenario file follows a consistent structure:
+
+| Section | Purpose |
+|---------|---------|
+| **Principles** | Core UX principles, user goals, success metrics |
+| **Layout** | Which base layout to use, page structure, regions |
+| **Design** | Color tokens, typography, spacing, components |
+| **Content** | Content hierarchy, microcopy, error messaging |
+| **Accessibility** | Scenario-specific a11y requirements (references base docs) |
+| **Implementation** | Component composition, state patterns, responsive behavior |
+| **Best Practices** | Do's/Don'ts, common mistakes, edge cases |
+
+---
+
+## How Scenarios Reference Foundations
+
+Scenarios build on foundational documentation:
+
+```
+┌─────────────────────────────────────────┐
+│             SCENARIOS                   │
+│  (authentication, dashboards, etc.)     │
+├─────────────────────────────────────────┤
+│  References:                            │
+│  ├── rules/README.md (EE canonical)    │
+│  ├── external/kuat-agent-rules/...     │
+│  ├── rules/design/layouts.md           │
+│  ├── rules/accessibility/*.md          │
+│  └── rules/components/ (as needed)     │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## For AI Agents
+
+When building a specific page type:
+
+1. Load the relevant scenario file
+2. Follow the recommended base layout from `rules/design/layouts.md`
+3. Reference accessibility requirements from `rules/accessibility/`
+4. Use design tokens from the EE foundations linked in [`rules/README.md`](../README.md) (e.g. `design-language/colours.md`, `typography.md` under `external/kuat-agent-rules/reference`)
+
+---
+
+## Related Documentation
+
+- [Layout Primitives](../design/layouts.md) - Base layout building blocks
+- [Accessibility](../accessibility/) - WCAG requirements
+- [Rules index](../README.md) - EE canonical design/content paths and Kuat notes
+- [Design — layouts](../design/layouts.md) - Layout primitives