@equal-experts/kuat-react 0.13.0 → 0.13.1

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

@@ -0,0 +1,333 @@
+# Documentation Scenarios
+
+Patterns for documentation sites, knowledge bases, API references, and content-heavy pages.
+
+---
+
+## Principles
+
+### User Goals
+
+- **Find information quickly** - Search and navigate efficiently
+- **Understand content** - Clear, well-structured explanations
+- **Complete tasks** - Step-by-step guidance that works
+- **Stay oriented** - Know where they are and where to go next
+
+### UX Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Clear structure | Logical hierarchy, consistent organisation |
+| Scannable content | Headings, lists, code blocks |
+| Multiple paths | Search, navigation, breadcrumbs |
+| Progressive detail | Overview first, details on demand |
+
+### Success Metrics
+
+- Search effectiveness (found what they needed)
+- Time to find information
+- Page bounce rate
+- Task completion rate (for tutorials)
+
+---
+
+## Layout
+
+**Base Layout:** [Sidebar Navigation](../design/layouts.md#2-sidebar-navigation-layout) + [Split Layout](../design/layouts.md#5-split-layout)
+
+Documentation uses a three-column layout on desktop:
+
+### Docs Landing Page
+
+Use [Horizontal Navigation](../design/layouts.md#1-horizontal-navigation-layout):
+
+```
+┌─────────────────────────────────────┐
+│ Header: Logo + Main Nav             │
+├─────────────────────────────────────┤
+│ Hero: Docs title + Search           │
+├─────────────────────────────────────┤
+│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐    │
+│ │Cat 1│ │Cat 2│ │Cat 3│ │Cat 4│    │
+│ └─────┘ └─────┘ └─────┘ └─────┘    │
+├─────────────────────────────────────┤
+│ Popular Articles                    │
+├─────────────────────────────────────┤
+│ Footer                              │
+└─────────────────────────────────────┘
+```
+
+### Docs Content Page
+
+Use Sidebar + Split (three-column):
+
+```
+┌──────┬──────────────────────────────────┐
+│ Nav  │ Breadcrumbs          [Search]    │
+│ Side ├──────────────────────────────────┤
+│ bar  │                    ┌───────────┐ │
+│      │ # Page Title       │ On This   │ │
+│      │                    │ Page      │ │
+│ [Doc │ Content...         │ - Section │ │
+│ tree]│                    │ - Section │ │
+│      │ ## Section         │ - Section │ │
+│      │ Content...         └───────────┘ │
+│      │                                  │
+│      │ [Previous]           [Next →]    │
+└──────┴──────────────────────────────────┘
+```
+
+### Specifications
+
+| Element | Value |
+|---------|-------|
+| Left sidebar width | 240-280px |
+| Right sidebar (TOC) | 200-240px |
+| Content max-width | 800px (prose) |
+| Content padding | 32-48px |
+
+---
+
+## Design
+
+### Color Tokens
+
+| Element | Token |
+|---------|-------|
+| Page background | `bg-background` |
+| Left sidebar | `bg-sidebar` (dark) or `bg-muted` (light) |
+| Right sidebar | `bg-background` (transparent) |
+| Code blocks | `bg-muted` |
+| Inline code | `bg-muted` |
+| Links | `text-primary` |
+
+### Typography
+
+| Element | Style |
+|---------|-------|
+| Page title (H1) | `text-3xl font-bold` |
+| Section heading (H2) | `text-2xl font-semibold` |
+| Subsection (H3) | `text-xl font-semibold` |
+| Body text | `text-base` with `leading-7` |
+| Code | `font-mono text-sm` |
+| Sidebar nav | `text-sm` |
+
+### Navigation Sidebar
+
+| Element | Specification |
+|---------|---------------|
+| Background | `bg-sidebar` (dark) or `bg-muted` (light) |
+| Active item | Left border or background highlight |
+| Section headers | Bold, no link |
+| Page links | Normal weight |
+| Sub-pages | Indented, smaller text |
+| Scroll | Independent from content |
+
+### Table of Contents (Right)
+
+| Element | Specification |
+|---------|---------------|
+| Position | Sticky, offset for header |
+| Content | H2 and H3 headings from page |
+| Active tracking | Highlight current section on scroll |
+| Visibility | Hide below 1280px |
+
+---
+
+## Content
+
+### Page Structure
+
+```markdown
+# Page Title           ← H1, one per page
+
+Intro paragraph        ← No heading, describes page purpose
+
+## Major Section       ← H2, main divisions
+
+### Subsection         ← H3, within sections
+
+#### Detail            ← H4, use sparingly
+```
+
+### Navigation Hierarchy
+
+```
+Getting Started        ← Category (bold, not clickable)
+  Introduction         ← Page link
+  Installation         ← Page link (active)
+  Quick Start          ← Page link
+Components             ← Category
+  Button               ← Page link
+    Variants           ← Sub-page (indented)
+    Examples           ← Sub-page
+```
+
+### Breadcrumbs
+
+```
+Docs / Components / Button / Variants
+```
+
+- Show full path to current page
+- All items clickable except current
+- Truncate middle items on mobile if needed
+
+### Previous/Next Navigation
+
+```
+┌─────────────────────────────────────────┐
+│ ← Previous              Next →          │
+│ Installation         Quick Start        │
+└─────────────────────────────────────────┘
+```
+
+- Full width bar at bottom of content
+- Based on sidebar navigation order
+- Show page titles, not just "Previous/Next"
+
+---
+
+## Accessibility
+
+**Base requirements:** See [accessibility/design.md](../accessibility/design.md), [accessibility/content.md](../accessibility/content.md), and [accessibility/technical.md](../accessibility/technical.md)
+
+**Scenario-specific:**
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Heading hierarchy | Proper H1 → H2 → H3 sequence |
+| Skip links | Skip to main content, skip navigation |
+| Landmark regions | nav, main, complementary (TOC) |
+| Search keyboard | Cmd/Ctrl+K shortcut, accessible modal |
+| Code blocks | Scrollable with keyboard, screen reader context |
+| Multiple nav labels | `aria-label` to distinguish left vs right sidebars |
+
+### Code Blocks
+
+- Ensure code blocks are keyboard scrollable
+- Provide language context for screen readers
+- Copy button must be keyboard accessible
+- Don't rely on syntax highlighting alone for meaning
+
+---
+
+## Implementation
+
+### Code Block Patterns
+
+**Inline Code:**
+
+- Use for: function names, file paths, short values
+- Style: `bg-muted`, `font-mono`, `text-sm`, `rounded`
+
+**Code Blocks:**
+
+| Element | Specification |
+|---------|---------------|
+| Background | `bg-muted` or syntax theme |
+| Border radius | 6px |
+| Padding | 16px |
+| Font | JetBrains Mono or system mono |
+| Line numbers | Optional, for reference |
+| Copy button | Top-right corner |
+| Language label | Top-left or top-right |
+
+**Multi-file Examples (Tabs):**
+
+```
+┌─────────────────────────────────────┐
+│ [React] [Vue] [HTML]                │
+├─────────────────────────────────────┤
+│ // Code for selected tab            │
+│ ...                                 │
+└─────────────────────────────────────┘
+```
+
+- Tabs for framework variants
+- Preserve selection across page navigation
+- Accessible tab panel pattern
+
+### Search Patterns
+
+**Search Bar:**
+
+- Prominent on landing page (hero area)
+- Persistent in header on content pages
+- Keyboard shortcut indicator (⌘K or Ctrl+K)
+
+**Search Results:**
+
+- Show in modal/overlay
+- Group by section/category
+- Highlight matching text
+- Keyboard navigation (arrows + enter)
+- Recent searches
+
+### Table of Contents Behavior
+
+| Behavior | Implementation |
+|----------|----------------|
+| Active tracking | Highlight section in viewport |
+| Click to scroll | Smooth scroll to section |
+| Sticky position | Stay visible while scrolling |
+| Hide on small screens | Below 1280px |
+| Collapse | Optionally collapsible |
+
+### Responsive Behavior
+
+| Breakpoint | Left Sidebar | Content | Right Sidebar |
+|------------|--------------|---------|---------------|
+| Mobile | Drawer (hidden) | Full width | Hidden |
+| Tablet | Collapsible | Full width | Hidden |
+| Desktop | Visible (240px) | Centered (max 800px) | Visible (200px) |
+
+---
+
+## Best Practices
+
+### Do's
+
+1. **Use descriptive headings** - Enable scanning and navigation
+2. **Keep pages focused** - One topic per page
+3. **Show code examples** - Demonstrate, don't just describe
+4. **Maintain consistency** - Same structure across all pages
+5. **Update with product** - Keep docs in sync with code
+6. **Provide multiple paths** - Search, nav, links, breadcrumbs
+
+### Don'ts
+
+1. **Don't write walls of text** - Break into sections
+2. **Don't assume knowledge** - Define terms, link to prereqs
+3. **Don't hide important info** - Key points should be scannable
+4. **Don't let docs go stale** - Regular review and updates
+5. **Don't break links** - Use redirects when restructuring
+
+### Common Mistakes
+
+| Mistake | Solution |
+|---------|----------|
+| No search | Add prominent search functionality |
+| Deep nesting | Flatten hierarchy, max 3 levels |
+| Missing navigation | Add prev/next, breadcrumbs |
+| Inconsistent structure | Template for all pages |
+| No code examples | Add runnable examples |
+| Outdated content | Version docs, review process |
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Very long pages | Add TOC, consider splitting |
+| Multi-version docs | Version switcher, clear indicators |
+| API reference | Auto-generate from code, consistent format |
+| External links | Mark with icon, open in new tab |
+| Deprecated content | Clear warnings, link to current |
+
+---
+
+## Related Documentation
+
+- [Layout Primitives](../design/layouts.md) - Sidebar and Split layouts
+- [Content Accessibility](../accessibility/content.md) - Structure and headings
+- [Rules index](../README.md) - Canonical EE typography (`external/kuat-agent-rules`)

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

@@ -0,0 +1,359 @@
+# Form Scenarios
+
+Patterns for forms, settings pages, multi-step wizards, and data entry interfaces.
+
+---
+
+## Principles
+
+### User Goals
+
+- **Complete task efficiently** - Minimal friction to submission
+- **Understand requirements** - Clear what's needed and why
+- **Correct mistakes easily** - Fix errors without re-entering data
+- **Save progress** - Don't lose work unexpectedly
+
+### UX Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Minimal friction | Only ask for necessary information |
+| Clear expectations | Explain what each field needs |
+| Helpful feedback | Specific, actionable error messages |
+| Progress preservation | Save work, confirm destructive actions |
+
+### Success Metrics
+
+- Form completion rate
+- Time to complete
+- Error rate and recovery
+- Abandonment rate
+
+---
+
+## Layout
+
+**Base Layout:** Varies by context
+
+| Context | Recommended Layout |
+|---------|-------------------|
+| Public forms (contact, signup) | [Single Column](../design/layouts.md#3-single-column-layout) |
+| App settings | [Sidebar Navigation](../design/layouts.md#2-sidebar-navigation-layout) |
+| Multi-step wizards | Single Column or Horizontal Navigation |
+| Inline editing | Within parent layout |
+
+### Card-Based Form (Settings, Profile)
+
+```
+┌─────────────────────────────────────┐
+│ Card Header: Section Title          │
+├─────────────────────────────────────┤
+│ Form Fields                         │
+│ ...                                 │
+├─────────────────────────────────────┤
+│ Card Footer:       [Cancel] [Save]  │
+└─────────────────────────────────────┘
+```
+
+### Multi-Step Wizard
+
+```
+┌─────────────────────────────────────┐
+│ Progress: ●───●───○───○             │
+├─────────────────────────────────────┤
+│ Step Title                          │
+│ Step description                    │
+├─────────────────────────────────────┤
+│                                     │
+│ Form Fields for Current Step        │
+│                                     │
+├─────────────────────────────────────┤
+│ [Back]                    [Next →]  │
+└─────────────────────────────────────┘
+```
+
+### Specifications
+
+| Element | Value |
+|---------|-------|
+| Form card max-width | 600px (single-column forms) |
+| Card padding | 24px (`p-6`) |
+| Field spacing | 24px (`space-y-6`) |
+| Section spacing | 32px between cards |
+| Settings page max-width | 800px |
+
+---
+
+## Design
+
+### Color Tokens
+
+| Element | Token |
+|---------|-------|
+| Card background | `bg-card` |
+| Card border | `border` |
+| Input background | `bg-background` |
+| Input border | `border-input` |
+| Input focus | `ring-ring` |
+| Error state | `border-destructive`, `text-destructive` |
+| Success indicator | `text-green-600` |
+
+### Typography
+
+| Element | Style |
+|---------|-------|
+| Section title | `text-lg font-semibold` |
+| Section description | `text-sm text-muted-foreground` |
+| Field label | `text-sm font-medium` |
+| Input text | `text-base` |
+| Helper text | `text-sm text-muted-foreground` |
+| Error text | `text-sm text-destructive` |
+| Required indicator | `text-destructive` (asterisk) |
+
+### Spacing
+
+| Element | Value |
+|---------|-------|
+| Label to input | 8px |
+| Input to helper/error | 4px |
+| Between fields | 24px |
+| Button group gap | 16px |
+
+---
+
+## Content
+
+### Field Labels
+
+| Requirement | Example |
+|-------------|---------|
+| Clear and specific | "Email address" not "Email" |
+| Required indicator | "Email address *" |
+| Optional indicator | "Phone number (optional)" |
+
+### Helper Text
+
+Use to:
+- Explain format requirements
+- Provide examples
+- Clarify why information is needed
+
+```
+Email address *
+[                                    ]
+We'll send your receipt to this address.
+```
+
+### Error Messages
+
+| Quality | Bad | Good |
+|---------|-----|------|
+| Specific | "Invalid input" | "Email must include @ symbol" |
+| Actionable | "Error" | "Please enter a valid date (DD/MM/YYYY)" |
+| Polite | "Wrong!" | "Please check this field" |
+
+### Button Labels
+
+| Action | Label |
+|--------|-------|
+| Submit form | "Save changes", "Submit", "Create account" |
+| Go to next step | "Next", "Continue" |
+| Go back | "Back", "Previous" |
+| Cancel | "Cancel", "Discard changes" |
+| Delete | "Delete", "Remove" |
+
+---
+
+## Accessibility
+
+**Base requirements:** See [accessibility/design.md](../accessibility/design.md), [accessibility/content.md](../accessibility/content.md), and [accessibility/technical.md](../accessibility/technical.md)
+
+**Scenario-specific:**
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Labels | Every input has visible, associated `<label>` |
+| Required fields | Marked with asterisk AND `aria-required` |
+| Error linking | Errors linked via `aria-describedby` |
+| Error summary | Summary at top with links to fields |
+| Focus management | Focus first error after failed submission |
+| No time limits | Allow unlimited time (or generous extension) |
+
+### Form Validation Pattern
+
+**Critical: Validate on submit, not on blur**
+
+| Rule | Implementation |
+|------|----------------|
+| Validate on submit | Show all errors after form submission |
+| Never disable submit | Users can always attempt submission |
+| No blur validation | Don't show errors while user is typing |
+| Error summary | Show summary above form with field links |
+| Focus first error | Move focus to first invalid field |
+
+### Grouping
+
+Use `<fieldset>` and `<legend>` for:
+- Radio button groups
+- Checkbox groups
+- Related fields (e.g., address components)
+
+---
+
+## Implementation
+
+### Field Layout Patterns
+
+**Vertical (Default):**
+
+```
+Label
+[Input field                    ]
+Helper text or error
+```
+
+Best for: Most forms, mobile-first
+
+**Horizontal (Settings):**
+
+```
+Label                [Input field        ]
+Description text
+```
+
+Best for: Settings pages with many fields
+
+**Grid (Related Fields):**
+
+```
+[First Name     ] [Last Name      ]
+[Email                            ]
+[Phone          ] [Extension      ]
+```
+
+Best for: Related fields (names, addresses)
+
+### Button Placement
+
+**Single Form:**
+
+| Position | Button | Variant |
+|----------|--------|---------|
+| Right | Submit/Save | `variant="default"` (primary) |
+| Left of submit | Cancel | `variant="outline"` or `ghost` |
+| Far left or separate | Delete | `variant="destructive"` |
+
+**Form in Modal:**
+
+| Position | Button |
+|----------|--------|
+| Left | Cancel |
+| Right | Submit |
+
+**Multi-step Wizard:**
+
+| Position | Button |
+|----------|--------|
+| Left | Back (`variant="outline"`) |
+| Right | Next/Submit (`variant="default"`) |
+
+### Settings Page Pattern
+
+Multiple card sections, each independently saveable:
+
+```
+┌─ Profile Information ───────────────┐
+│ [Fields...]                         │
+│                          [Save]     │
+└─────────────────────────────────────┘
+        ↓ 32px gap
+┌─ Notification Preferences ──────────┐
+│ [Fields...]                         │
+│                          [Save]     │
+└─────────────────────────────────────┘
+```
+
+| Element | Specification |
+|---------|---------------|
+| Section gap | 32px |
+| Section max-width | 800px |
+| Alignment | Left-aligned (not centered) |
+
+### Multi-Step Wizard Pattern
+
+**Progress Indicator:**
+
+- Show step numbers or names
+- Highlight: completed, current, upcoming
+- Allow clicking completed steps to go back
+
+**Step Transitions:**
+
+- Validate current step before "Next"
+- Show summary on final step before submit
+- Preserve data when going back
+
+**State Management:**
+
+- Save progress to prevent data loss
+- Warn before leaving with unsaved changes
+- Handle session timeout gracefully
+
+### Responsive Behavior
+
+| Breakpoint | Grid Fields | Button Layout |
+|------------|-------------|---------------|
+| Mobile | Stack to single column | Stack vertically |
+| Tablet | 2 columns | Horizontal |
+| Desktop | As designed | Horizontal |
+
+---
+
+## Best Practices
+
+### Do's
+
+1. **Ask only what's needed** - Every field should be justified
+2. **Group related fields** - Logical sections aid completion
+3. **Show progress** - Especially for long/multi-step forms
+4. **Preserve input** - Never clear on error
+5. **Confirm success** - Toast, redirect, or inline confirmation
+6. **Autosave where possible** - Drafts, settings
+
+### Don'ts
+
+1. **Don't validate on blur** - Interrupts user flow
+2. **Don't disable submit** - Users should always try
+3. **Don't use placeholders as labels** - They disappear
+4. **Don't require confirmation for simple saves** - Only for destructive actions
+5. **Don't hide required indicators** - Make them obvious
+
+### Common Mistakes
+
+| Mistake | Solution |
+|---------|----------|
+| Disabling submit button | Keep enabled, show errors on submit |
+| Blur validation | Validate on submit only |
+| Placeholder-only labels | Always use visible labels |
+| Vague errors | Specific, actionable messages |
+| No error summary | Add summary at top with links |
+| Clearing form on error | Preserve all user input |
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Very long forms | Break into steps or sections |
+| Conditional fields | Show/hide smoothly, don't lose data |
+| File uploads | Show progress, handle failures |
+| Unsaved changes | Warn before navigation |
+| Session timeout | Save draft, prompt re-auth |
+| Network failure | Queue submission, retry automatically |
+
+---
+
+## Related Documentation
+
+- [Layout Primitives](../design/layouts.md) - Layout options
+- [Technical Accessibility](../accessibility/technical.md) - Form validation pattern
+- [Authentication Scenario](./authentication.md) - Login/registration forms