@equal-experts/kuat-react 0.13.0 → 0.13.1

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

@@ -0,0 +1,207 @@
+---
+scope: type
+platform: web_product
+prerequisites: general
+---
+
+# Product Design Rules
+
+Design guidelines for Equal Experts web applications and product interfaces.
+
+---
+
+**Prerequisites:** Load [foundations](../../../foundations/) first.
+
+**Intent:** Use skill [kuat-review](../../../../skills/kuat-review/SKILL.md) or [kuat-create](../../../../skills/kuat-create/SKILL.md) first.
+
+---
+
+## Before you review
+
+1. Run [kuat-review](../../../../skills/kuat-review/SKILL.md) intake (depth, artifacts, output format).
+2. Gather product context per [review-context.md](./review-context.md) when depth is `product_ux` or `full`.
+3. Apply [review-checklist.md](./review-checklist.md).
+4. **Do not load** [examples/](./examples/) for review-only tasks.
+
+---
+
+## Before you create
+
+1. Run [kuat-create](../../../../skills/kuat-create/SKILL.md).
+2. Load this file, relevant [scenarios/](./scenarios/), and [content/](./content/) as needed.
+3. Load [examples/](./examples/) when implementing UI in React, Vue, or CSS.
+
+---
+
+## Overview
+
+Product layouts are for web applications, dashboards, and internal tools. They use **dark navigation** for clear visual hierarchy, distinguishing them from marketing layouts.
+
+---
+
+## When to Use Product Layout
+
+Use product layout when:
+- Building web applications
+- Creating dashboards or internal tools
+- Data-heavy or interactive interfaces
+- Requires persistent navigation
+- User workflows and task completion
+
+---
+
+## Navigation Patterns
+
+Product layouts use **dark navigation** for clear visual hierarchy. Choose one of two patterns:
+
+### Option 1: Dark Horizontal Navigation
+
+Use when: Limited navigation items (5-7 items)
+
+```
+┌─────────────────────────────────────────┐
+│ Dark Navigation Bar (Tech Blue)         │
+│ [Logo]    [Nav Items]    [User Menu]    │
+├─────────────────────────────────────────┤
+│                                         │
+│         Main Content Area               │
+│         (Light background)              │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Background | `bg-sidebar` (Tech Blue) |
+| Logo | White monochrome (`logo-monochrome-white.svg`), left-aligned |
+| Logo size | 120-150px (min 100px) |
+| Height | 64-72px fixed |
+| Nav items | Horizontal, left-aligned after logo |
+| User menu | Right-aligned |
+
+### Option 2: Dark Sidebar Navigation
+
+Use when: Complex navigation, hierarchical structure, 8+ items
+
+```
+┌──────┬──────────────────────────────────┐
+│      │ Top Bar (Light)                  │
+│ Dark │ [Breadcrumbs]    [User Menu]     │
+│ Side │──────────────────────────────────┤
+│ bar  │                                  │
+│      │   Main Content Area              │
+│ [Logo│   (Light background)             │
+│ Nav] │                                  │
+│      │                                  │
+└──────┴──────────────────────────────────┘
+```
+
+**Specifications:**
+
+| Property | Value |
+|----------|-------|
+| Sidebar background | `bg-sidebar` (Tech Blue) |
+| Sidebar width | 240-280px (collapsible to 64px) |
+| Logo | White monochrome, top of sidebar |
+| Logo size | 120-150px (min 100px) |
+| Top bar background | `bg-background` (light) |
+| Content area | Light background, full remaining width |
+
+---
+
+## Navigation Color Tokens
+
+For dark navigation (horizontal 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 |
+
+---
+
+## Logo Placement
+
+| Location | Logo Variant | Size |
+|----------|--------------|------|
+| Horizontal nav | White monochrome | 120-150px |
+| Sidebar (top) | White monochrome | 120-150px |
+
+**Never use full-color logo on dark backgrounds.**
+
+See [foundations/logo.md](../../../foundations/logo.md) for logo guidelines.
+
+---
+
+## Responsive Behavior
+
+### 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 Areas
+
+### Main Content
+
+- Light background (`bg-background`)
+- Adequate padding (24-32px)
+- Responsive width
+
+### Cards and Panels
+
+- Use `bg-card` token for card backgrounds
+- Follow [foundations/design/borders.md](../../../foundations/design/borders.md) for border styling
+- Follow [foundations/design/spacing.md](../../../foundations/design/spacing.md) for padding
+
+---
+
+## Usage Guidelines
+
+### Do's
+
+1. **Use dark navigation** - Distinguishes product from marketing
+2. **Use white/monochrome logo** - Appropriate for dark backgrounds
+3. **Choose appropriate nav pattern** - Horizontal for simple, sidebar for complex
+4. **Maintain light content areas** - Good contrast for readability
+5. **Follow spacing guidelines** - 8-point grid, consistent padding
+
+### Don'ts
+
+1. **Don't use light navigation** - That's for marketing layouts
+2. **Don't use full-color logo on dark** - Use white monochrome
+3. **Don't combine nav patterns** - Choose horizontal OR sidebar, not both
+4. **Don't ignore mobile** - All layouts must work on small screens
+5. **Don't hardcode colors** - Use design tokens
+
+---
+
+## Related Documentation
+
+- [Foundations](../../../foundations/) - Brand and design language
+- [Accessibility](./accessibility.md) - Technical accessibility implementation
+- [Component Decision Tree](./component-decision-tree.md) - Component selection
+- [Technical Guidelines](./technical.md) - Implementation details
+- [Product Content](./content.md) - UX writing guidelines
+- [Scenarios](./scenarios/) - Applied patterns for specific page types

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

@@ -0,0 +1,71 @@
+# Product Email Rules
+
+Guidelines for Equal Experts transactional and product-related emails.
+
+---
+
+**Status:** Placeholder - details to be defined
+
+**Prerequisites:** Load [foundations](../../../foundations/) first
+
+---
+
+## Overview
+
+Product emails are transactional communications sent from web applications, including confirmations, notifications, and system messages.
+
+---
+
+## Key Principles
+
+1. **Informative** - Provide necessary information clearly
+2. **Actionable** - Include clear next steps when needed
+3. **Timely** - Send at the right moment
+4. **Concise** - Respect user's time
+
+---
+
+## Email Types
+
+- **Confirmation emails** - Account created, payment received
+- **Notification emails** - New activity, status changes
+- **System emails** - Password reset, security alerts
+- **Digest emails** - Summary of activity
+
+---
+
+## Content Guidelines
+
+Follow [foundations/content/](../../../foundations/content/) and [product content](./content/product-content.md) for writing style.
+
+### Subject Lines
+- Be specific about the content
+- Include relevant details (order number, etc.)
+- Keep concise
+
+### Body Content
+- Lead with the most important information
+- Include relevant details
+- Provide clear next steps
+- Link to the application for actions
+
+---
+
+## To Be Defined
+
+- Email template designs
+- Header and footer specifications
+- Logo placement and sizing
+- Color usage in transactional emails
+- Typography for email clients
+- CTA button styling
+- Mobile-first design requirements
+- Accessibility requirements
+
+---
+
+## Related Documentation
+
+- [Foundations](../../../foundations/) - Brand and design language
+- [Product Content](./content/product-content.md) - UX writing guidelines
+- [Marketing Emails](../marketing/emails.md) - Marketing email guidelines

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

@@ -0,0 +1,57 @@
+# Web Product — Review Checklist
+
+Use for **review** intent at any depth. Pair with [review-context.md](./review-context.md) when depth is `product_ux` or `full`.
+
+**See also:** [design.md](./design.md), [accessibility.md](./accessibility.md), [component-decision-tree.md](./component-decision-tree.md), [kuat-review](../../../../skills/kuat-review/SKILL.md).
+
+---
+
+## Brand compliance (all depths)
+
+- [ ] Colours from approved palette / semantic tokens — no arbitrary hex in UI
+- [ ] Typography uses defined scale (Lexend, type roles)
+- [ ] Spacing follows 4px grid
+- [ ] Logo usage follows [foundations/logo.md](../../../foundations/logo.md) if present
+- [ ] Border radius: 0px static content, 6px interactive, 4px inputs
+
+---
+
+## Accessibility (all depths)
+
+- [ ] Single logical H1 per view (or equivalent page title pattern)
+- [ ] Heading hierarchy is sequential
+- [ ] Text contrast meets WCAG AA (4.5:1 body, 3:1 large text/UI)
+- [ ] Focus states visible for keyboard users
+- [ ] Images have appropriate alt text (decorative: empty alt)
+- [ ] Interactive controls have accessible names
+
+See [accessibility.md](./accessibility.md) for full requirements.
+
+---
+
+## Product patterns (all depths)
+
+- [ ] Product layout uses dark navigation pattern where applicable ([design.md](./design.md))
+- [ ] Components sourced per [component-decision-tree.md](./component-decision-tree.md)
+- [ ] Primitives match component guides for cited IDs (`shadcn:button`, `kuat:*`) from package `agent-docs/` or overlay
+- [ ] No inline styles for themeable properties — use design tokens
+
+---
+
+## Product / UX fit (`product_ux` or `full` only)
+
+**Blocked** until [review-context.md](./review-context.md) items are supplied. Do not score this section without user story and scope.
+
+- [ ] Primary actions and labels support the stated job-to-be-done ([content/actions.md](./content/actions.md))
+- [ ] Copy enables task completion — not marketing tone ([content/product-content.md](./content/product-content.md))
+- [ ] Errors, empty, and loading states match scoped flows (see relevant [scenarios/](./scenarios/) file)
+- [ ] Form labels and validation align with scenario rules if applicable
+- [ ] Screen content reflects stated success criteria from review context — cite evidence
+
+If context missing: mark section **Blocked** and list required items under Open questions.
+
+---
+
+## Report usage
+
+Map failures to [kuat-review](../../../../skills/kuat-review/SKILL.md) violation table. Cite the rule file for each finding.

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

@@ -0,0 +1,44 @@
+# Web Product — Review Context
+
+Product and research context to gather **before** reviewing web features at `product_ux` or `full` depth. See skill [kuat-review](../../../../skills/kuat-review/SKILL.md).
+
+**Skip this file** when review depth is `brand_compliance` only — note in the report that UX/content fit is out of scope.
+
+---
+
+## Mandatory questions
+
+Ask for anything missing in the grouped intake message:
+
+| Context | Ask for |
+|---------|---------|
+| **User story / job-to-be-done** | Who is the user, what are they trying to do, what outcome counts as success? |
+| **Research & evidence** | Insights, interview themes, analytics, usability findings — or explicit "none yet" |
+| **Constraints** | Deadlines, tech limits, policy, must-use patterns |
+| **Scope** | Which screens/states (happy path only vs errors, empty, loading, edge cases) |
+| **Known decisions** | What discovery already decided (avoid relitigating settled choices) |
+
+---
+
+## Optional but useful
+
+- Competitor or reference examples the team used
+- Prior iteration feedback
+- Accessibility audit or QA results
+- Links to tickets, PRDs, or Figma flows
+
+---
+
+## If context is withheld
+
+- Proceed at `brand_compliance` if the user confirms, or
+- Produce **provisional** UX notes with assumptions listed under **Open questions** in the report
+- Do **not** invent user stories or research conclusions
+
+---
+
+## Related
+
+- [review-checklist.md](./review-checklist.md)
+- [kuat-review/SKILL.md](../../../../skills/kuat-review/SKILL.md)
+- [content/product-content.md](./content/product-content.md)

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

@@ -0,0 +1,82 @@
+# Product Scenarios
+
+Applied layout and design patterns for web application page types.
+
+Each scenario combines foundational rules and web product rules into actionable guidance for building complete pages.
+
+---
+
+## When to Use Scenarios
+
+Load a scenario guide when:
+
+- Building a specific page type (login, dashboard, settings)
+- 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 |
+
+---
+
+## 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/foundations/*                │
+│  ├── rules/types/web/product/design.md  │
+│  ├── rules/types/web/product/           │
+│  │   accessibility.md                   │
+│  └── rules/foundations/accessibility.md│
+└─────────────────────────────────────────┘
+```
+
+---
+
+## For AI Agents
+
+When building a specific page type:
+
+1. Load the relevant scenario file
+2. Follow the recommended base layout from product design rules
+3. Reference accessibility requirements from foundations and web accessibility docs
+4. Use design tokens from foundations colours and typography
+
+---
+
+## Related Documentation
+
+- [Product Design](../design.md) - Layout patterns
+- [Product Accessibility](../accessibility.md) - Technical implementation
+- [Foundations Accessibility](../../../../foundations/accessibility.md) - Principles
+- [Foundations](../../../../foundations/) - Brand design rules