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

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/actions.md

@@ -0,0 +1,45 @@
+# Actions (Buttons and Links)
+
+Guidance for button labels and link text in product interfaces.
+
+---
+
+## Buttons
+
+**Do:**
+- Use verb-driven labels
+- Be specific about what happens
+- Keep labels short (1–3 words ideal)
+- Use sentence case
+
+**Don't:**
+- Use vague labels like "OK" or "Submit"
+- Make labels overly long
+- Use ALL CAPS
+- Include instructions in button labels
+
+**Good examples:**
+- [Save and close]
+- [Delete expense]
+- [Send invoice now]
+- [Connect bank]
+
+**Bad examples:**
+- [OK] (ambiguous)
+- [SUBMIT FORM NOW] (shouty, vague)
+- [Click here to continue] (generic)
+
+---
+
+## Links
+
+- Use descriptive link text that states the destination or action
+- Avoid "click here", "read more", or "learn more" without context
+- See [content formatting](../../../content/formatting.md) for link guidelines
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Confirmations](./confirmations.md)

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/confirmations.md

@@ -0,0 +1,51 @@
+# Confirmations
+
+When and how to write confirmation dialogs for destructive or high-impact actions.
+
+---
+
+## When to Use Confirmations
+
+**Use for:**
+- Destructive actions (delete, remove)
+- Actions that can't be undone
+- Actions with significant consequences
+
+**Don't use for:**
+- Actions easily undone
+- Low-stakes decisions
+- Frequent actions
+
+---
+
+## Confirmation Pattern
+
+1. **Clear question or statement** – What is about to happen?
+2. **Consequences** – What will be affected? (list if helpful)
+3. **Irreversibility** – State if the action can't be undone
+4. **Primary action** – Specific, verb-driven (e.g. "Delete permanently")
+5. **Cancel** – "Cancel" or "Keep [item]"
+
+---
+
+## Example
+
+```
+Delete client account?
+
+This will permanently delete [Client Name] and all associated:
+- Invoices (12)
+- Payments (8)
+- Transaction history
+
+You can't undo this action.
+
+[Delete permanently]  [Cancel]
+```
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Actions](./actions.md)

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/empty-states.md

@@ -0,0 +1,37 @@
+# Empty States
+
+How to write copy when there's no data or content to show yet.
+
+---
+
+## Principles
+
+**Do:**
+- Explain why the state is empty
+- Provide a clear next action
+- Use a positive, encouraging tone
+
+**Don't:**
+- Leave the user guessing
+- Use negative or blaming language
+- Offer multiple competing actions without a clear primary one
+
+---
+
+## Example
+
+```
+No invoices yet
+
+Create your first invoice to get paid faster.
+It takes less than 2 minutes.
+
+[Create invoice]
+```
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Actions](./actions.md)

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/errors.md

@@ -0,0 +1,48 @@
+# Errors
+
+How to write error messages that help users fix the problem.
+
+---
+
+## Error Message Formula
+
+1. **What went wrong** – Be specific
+2. **Why it happened** – If it helps the user (e.g. which field, what rule)
+3. **How to fix it** – Actionable next step
+
+---
+
+## Do
+
+- Be specific about the problem
+- Use plain language
+- Provide actionable next steps
+- Take responsibility where appropriate ("We couldn't save..." rather than "You entered invalid data")
+
+---
+
+## Don't
+
+- Blame the user
+- Use technical jargon or error codes in the UI
+- Be vague ("An error occurred")
+- Leave the user without a next step
+
+---
+
+## Example
+
+```
+Can't save invoice
+
+The customer email "john@example,com" has a comma instead of a period.
+
+Fix the email address and try again.
+```
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Forms](./forms.md) – Validation messages

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/forms.md

@@ -0,0 +1,68 @@
+# Forms
+
+Content guidance for forms: labels, placeholders, helper text, validation, and structure.
+
+---
+
+## Labels
+
+**Do:**
+- Always use a visible label (not only a placeholder)
+- Keep labels short and clear
+- Use sentence case
+- Position labels above fields (or consistent with your design system)
+
+**Don't:**
+- Use placeholder as the only label (placeholders disappear on focus and aren’t always read by assistive tech)
+- Make labels overly long
+- Hide labels on focus
+
+---
+
+## Placeholders
+
+- Use for short hints or examples (e.g. "e.g. name@example.com")
+- Don’t put critical instructions only in placeholders
+- Keep placeholder text brief; move longer guidance to helper text
+
+---
+
+## Helper Text
+
+- Use for optional instructions, format requirements, or context
+- Place below the field or with the label
+- Keep it concise; link to full help if needed
+
+---
+
+## Validation Messages
+
+- Show validation at the right time (e.g. on blur or submit, depending on pattern)
+- Be specific: "Password must be at least 8 characters" not "Invalid password"
+- Tie the message to the field (inline or next to the field) so users know what to fix
+- See [Errors](./errors.md) for the problem–cause–fix pattern
+
+---
+
+## Form Structure
+
+- Group related fields (e.g. contact details, payment)
+- Use clear section headings for long forms
+- Order fields in a logical flow (e.g. match the user’s mental model or task order)
+- Use progressive disclosure for optional or advanced fields so the form doesn’t feel overwhelming
+
+---
+
+## Mobile
+
+- Keep form copy short; every word counts on small screens
+- Consider shorter labels or stacked layout if space is tight
+- Ensure tap targets and font sizes meet accessibility guidelines
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Errors](./errors.md)
+- [Accessibility foundations](../../../accessibility/accessibility.md)

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/content/product-content.md

@@ -0,0 +1,128 @@
+# Product Content Guidelines
+
+UX writing and content guidelines for Equal Experts web applications.
+
+---
+
+## Overview
+
+Product content is the text inside product interfaces, designed to help users complete tasks. It's more concise than marketing content and action-oriented.
+
+**Core purpose:** Give users exactly what they need, exactly when they need it, to complete their task successfully.
+
+**Tone:** Helpful, concise, action-oriented, respectful
+
+---
+
+## Product Voice Formula
+
+`[Action] + [Object] + [Benefit if needed]`
+
+**Examples:**
+- "Save invoice" (action + object)
+- "Export to CSV" (action + object + format)
+- "Archive project · Free up space" (action + object · benefit)
+
+---
+
+## Key Differences from Marketing
+
+| Aspect | Marketing | Product |
+|--------|-----------|---------|
+| Purpose | Persuade, inform | Enable task completion |
+| Length | Can be expansive | Must be concise |
+| Tone | Conversational | Action-oriented |
+| Style | Storytelling | Direct, functional |
+| Context | User chose to read | User is trying to do |
+
+---
+
+## Foundational Principles
+
+### 1. Understand the Audience
+
+Before writing, know:
+- **Who** sees this? (All users? Specific segments?)
+- **When** do they see it? (First login? After error?)
+- **What** are they trying to do?
+- **How** are they feeling? (Confident? Frustrated?)
+
+### 2. Keep Users Focused
+
+- Surface information at moment of need
+- Don't make users remember for later
+- Remove info when no longer relevant
+- Avoid "just in case" content
+
+### 3. Get to the Point
+
+- Lead with most important information
+- Remove filler words and phrases
+- Every word should earn its place
+
+**Common filler to remove:**
+- "Please note that..."
+- "At this time..."
+- "In order to..."
+- "You may wish to..."
+- "It appears that..."
+
+### 4. Make It Accessible
+
+- Ensure proper heading hierarchy
+- Write descriptive link text
+- Provide alt text for images
+- Keep form labels clear and persistent
+- Error messages must be actionable
+
+---
+
+## Common Mistakes
+
+| Mistake | Bad | Good |
+|---------|-----|------|
+| Explaining obvious | "Click the button below to continue" | [Continue] |
+| Technical language | "Authentication failed for endpoint" | "We couldn't log you in" |
+| Being vague | "An error occurred" | "Password must be 8+ characters" |
+| Overusing exclamation | "Success! Invoice sent!" | "Invoice sent" |
+| Apologizing unnecessarily | "Sorry, no results found" | "No results found" |
+| Marketing speak | "Leverage our innovative AI-powered categorization" | "Auto-categorize expenses" |
+
+---
+
+## Product Content Checklist
+
+**Context and Timing:**
+- [ ] Content appears at right moment
+- [ ] Information directly relevant
+- [ ] Content disappears when not relevant
+
+**Clarity and Conciseness:**
+- [ ] Every word carries meaning
+- [ ] As short as possible while clear
+- [ ] Most important info first
+
+**Usability:**
+- [ ] Users can complete task without leaving for help
+- [ ] Button labels describe action clearly
+- [ ] Form labels clear and persistent
+- [ ] Error messages explain problem and fix
+
+**Accessibility:**
+- [ ] Accessible to screen readers
+- [ ] Labels connected to inputs
+- [ ] Error messages associated with fields
+- [ ] Logical heading hierarchy
+
+---
+
+## Related Documentation
+
+- [Voice and tone](../../../brand/voice-and-tone.md) - Voice, tone, style
+- [Actions](./actions.md) - Buttons and links
+- [Confirmations](./confirmations.md) - Confirmation dialogs
+- [Empty states](./empty-states.md) - Empty state copy
+- [Errors](./errors.md) - Error messages
+- [Forms](./forms.md) - Form content
+- [Design](../design.md) - Visual design guidelines
+- [Component Decision Tree](../component-decision-tree.md) - Component development

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

@@ -0,0 +1,177 @@
+# Product Design Rules
+
+Design guidelines for Equal Experts web applications and product interfaces.
+
+---
+
+## 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 [logo guidelines](../../brand/logo.md).
+
+---
+
+## 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 [borders](../../design-language/borders.md) for border styling
+- Follow [spacing](../../design-language/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
+
+- [Reference home](../../README.md) - Brand and design language
+- [Accessibility](./accessibility.md) - Technical accessibility implementation
+- [Component Decision Tree](./component-decision-tree.md) - Component selection
+- [Product Content](./content/product-content.md) - UX writing guidelines
+- [Patterns](./patterns/) - Applied patterns for specific page types

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

@@ -0,0 +1,65 @@
+# Product Email Rules
+
+Guidelines for Equal Experts transactional and product-related emails.
+
+---
+
+## 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 [content foundations](../../content/writing-style.md) 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
+
+- [Reference home](../../README.md) - Brand and design language
+- [Product Content](./content/product-content.md) - UX writing guidelines
+- [Marketing Emails](../web-marketing/emails.md) - Marketing email guidelines

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/README.md

@@ -0,0 +1,10 @@
+# Web Product Patterns
+
+Applied layout and design patterns for web-application page types.
+
+| Pattern | 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 |