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

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

@@ -0,0 +1,301 @@
+# Authentication Scenarios
+
+Patterns for login, registration, password flows, and account verification.
+
+---
+
+## Principles
+
+### User Goals
+
+- **Get in quickly** - Authentication is a barrier to the actual task
+- **Feel secure** - Trust that credentials are protected
+- **Recover easily** - Forgot password shouldn't be frustrating
+
+### UX Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Minimise friction | Only ask for essential information |
+| Clear feedback | Immediate, helpful error messages |
+| Maintain trust | Security indicators, clear privacy info |
+| Support recovery | Easy password reset, account recovery |
+
+### Success Metrics
+
+- Time to complete login/registration
+- Password reset completion rate
+- Error rate and recovery success
+- Abandonment rate
+
+---
+
+## Layout
+
+**Base Layout:** [Single Column](../design/layouts.md#3-single-column-layout)
+
+Authentication pages should minimise distraction and focus users on the task.
+
+### Page Structure
+
+```
+┌─────────────────────────────────────────┐
+│            [Logo] (centered)            │
+├─────────────────────────────────────────┤
+│                                         │
+│     ┌─────────────────────────┐         │
+│     │      Auth Card          │         │
+│     │      (max 400px)        │         │
+│     │                         │         │
+│     │  [Form Fields]          │         │
+│     │                         │         │
+│     │  [Primary Action]       │         │
+│     │                         │         │
+│     │  [Secondary Link]       │         │
+│     └─────────────────────────┘         │
+│                                         │
+├─────────────────────────────────────────┤
+│     Footer (minimal: legal links)       │
+└─────────────────────────────────────────┘
+```
+
+### Specifications
+
+| Element | Value |
+|---------|-------|
+| Content alignment | Centered (vertical + horizontal) |
+| Card max-width | 400px |
+| Card padding | 32px (`p-8`) |
+| Card background | `bg-card` with `border` |
+| Card radius | 6px (interactive element) |
+| Minimum viewport height | 100vh |
+| Logo placement | Centered above card, or inside card header |
+
+### Header
+
+- **Minimal navigation** - Logo only, no full navigation
+- Logo links to marketing site or app home
+- No distracting elements
+
+### Footer
+
+- Minimal: legal links only (Privacy Policy, Terms)
+- Copyright notice optional
+- No marketing content
+
+---
+
+## Design
+
+### Color Tokens
+
+| Element | Token |
+|---------|-------|
+| Page background | `bg-background` or `bg-muted` |
+| Card background | `bg-card` |
+| Card border | `border` |
+| Primary button | `bg-primary` |
+| Error text | `text-destructive` |
+| Link text | `text-primary` |
+
+### Typography
+
+| Element | Style |
+|---------|-------|
+| Page heading | `text-2xl font-bold` |
+| Subheading | `text-muted-foreground` |
+| Labels | `text-sm font-medium` |
+| Input text | `text-base` |
+| Error messages | `text-sm text-destructive` |
+| Links | `text-sm text-primary underline` |
+
+### Spacing
+
+| Element | Spacing |
+|---------|---------|
+| Between fields | 24px (`space-y-6`) |
+| Label to input | 8px |
+| Input to error | 4px |
+| Form to button | 24px |
+| Button to secondary link | 16px |
+
+---
+
+## Content
+
+### Login Page
+
+**Required Elements:**
+
+1. Logo (centered above card or in card header)
+2. Heading: "Sign in" or "Welcome back"
+3. Email/username field with label
+4. Password field with show/hide toggle
+5. "Forgot password?" link (below password field, right-aligned)
+6. Primary submit button (full width)
+7. Secondary action: "Don't have an account? Sign up"
+
+**Microcopy:**
+
+| Element | Example |
+|---------|---------|
+| Heading | "Sign in to your account" |
+| Email label | "Email address" |
+| Password label | "Password" |
+| Submit button | "Sign in" |
+| Forgot link | "Forgot your password?" |
+| Register link | "Don't have an account? Sign up" |
+
+### Registration Page
+
+**Required Elements:**
+
+1. Logo
+2. Heading: "Create account" or "Get started"
+3. Name field(s) - first/last or full name
+4. Email field
+5. Password field with strength indicator
+6. Terms acceptance checkbox
+7. Primary submit button
+8. Secondary: "Already have an account? Sign in"
+
+**Password Requirements Display:**
+
+- Show requirements list below password field
+- Check/uncheck as requirements are met
+- Unmet: `text-muted-foreground`
+- Met: `text-green-600` with checkmark
+
+### Password Reset Flow
+
+**Step 1: Request Reset**
+
+- Email field only
+- "Send reset link" button
+- Success message (don't reveal if email exists)
+
+**Step 2: Reset Password**
+
+- New password field
+- Confirm password field
+- Password requirements visible
+- "Reset password" button
+
+### MFA / Code Entry
+
+- 6-digit code input (individual boxes or single field)
+- "Resend code" link with countdown timer
+- "Use different method" secondary action
+- Clear instructions on where code was sent
+
+---
+
+## 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 |
+|-------------|----------------|
+| Focus first field | Auto-focus email/username on page load |
+| Form labels | All inputs have visible, associated labels |
+| Error linking | Use `aria-describedby` for error messages |
+| Submit on Enter | Form submits when Enter pressed in any field |
+| Password toggle | Toggle button is keyboard accessible |
+| Error announcement | Screen reader announces errors on submit |
+
+### Form Validation
+
+Follow the standard validation pattern:
+
+- **Validate on submit** - Show all errors after submission attempt
+- **Never disable submit button** - Users can always attempt submission
+- **No inline validation on blur** - Don't interrupt mid-flow
+- **Error summary** - Show summary at top with links to fields
+- **Focus first error** - Move focus to first invalid field
+
+---
+
+## Implementation
+
+### Button Placement
+
+| Button | Position | Variant |
+|--------|----------|---------|
+| Primary (Submit) | Full width | `variant="default"` |
+| Secondary link | Below button, centered | Text link |
+| Forgot password | Below password field, right | Text link |
+
+### Error States
+
+| Error Type | Display Location |
+|------------|-----------------|
+| Field validation | Inline, below field |
+| Invalid credentials | Alert above form |
+| Rate limiting | Alert above form with wait time |
+| Network error | Alert above form with retry option |
+
+### Security Considerations
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Don't reveal email existence | Generic "check your email" messages |
+| Rate limit attempts | Show user-friendly wait message |
+| Password visibility | Toggle with clear state indication |
+| Session timeout | Warn before logging out |
+
+### Responsive Behavior
+
+| Breakpoint | Behavior |
+|------------|----------|
+| Mobile | Card padding reduced to 24px, full width with margin |
+| Tablet | Centered card, 400px max |
+| Desktop | Centered card, 400px max |
+
+---
+
+## Best Practices
+
+### Do's
+
+1. **Keep forms minimal** - Only required fields
+2. **Show password option** - Let users verify their input
+3. **Persist email** - Remember email for returning users (with consent)
+4. **Clear success states** - Confirm successful actions
+5. **Offer alternatives** - Social login, SSO where appropriate
+
+### Don'ts
+
+1. **Don't use CAPTCHAs** as first defense - Use rate limiting first
+2. **Don't reveal** whether an email exists in the system
+3. **Don't require** password confirmation on login
+4. **Don't auto-submit** on field completion
+5. **Don't clear form** on error - Preserve user input
+
+### Common Mistakes
+
+| Mistake | Solution |
+|---------|----------|
+| Disabling submit button | Always allow submission attempts |
+| Inline blur validation | Validate on submit only |
+| Vague errors ("Invalid input") | Specific, actionable messages |
+| No password visibility toggle | Always include toggle |
+| Missing forgot password | Prominent link near password field |
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Expired password reset link | Clear message with option to request new link |
+| Account locked | Explain why, provide recovery path |
+| Email not verified | Offer to resend verification |
+| Session expired mid-flow | Preserve form data, prompt re-authentication |
+
+---
+
+## Related Documentation
+
+- [Layout Primitives](../design/layouts.md) - Single Column layout
+- [Technical Accessibility](../accessibility/technical.md) - Form validation pattern
+- [Forms Scenario](./forms.md) - General form patterns

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

@@ -0,0 +1,314 @@
+# Dashboard Scenarios
+
+Patterns for data dashboards, analytics views, metrics displays, and reporting interfaces.
+
+---
+
+## Principles
+
+### User Goals
+
+- **Get insights quickly** - Key metrics visible at a glance
+- **Understand trends** - Patterns and changes over time
+- **Take action** - Clear paths from data to decisions
+- **Explore deeper** - Drill down into details when needed
+
+### UX Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Information hierarchy | Most important metrics first and largest |
+| Progressive disclosure | Overview first, details on demand |
+| Consistent data | Same time periods, units, formats |
+| Actionable context | Explain what numbers mean |
+
+### Success Metrics
+
+- Time to find key information
+- Decision confidence
+- Filter usage patterns
+- Drill-down completion rates
+
+---
+
+## Layout
+
+**Base Layout:** [Sidebar Navigation](../design/layouts.md#2-sidebar-navigation-layout)
+
+Dashboards benefit from persistent navigation and maximum content width.
+
+### Metrics Dashboard Structure
+
+```
+┌──────┬──────────────────────────────────┐
+│      │ Header: Page Title + Filters     │
+│ Side ├──────────────────────────────────┤
+│ bar  │ ┌────┐ ┌────┐ ┌────┐ ┌────┐     │
+│      │ │KPI │ │KPI │ │KPI │ │KPI │     │
+│      │ └────┘ └────┘ └────┘ └────┘     │
+│      ├──────────────────────────────────┤
+│      │ ┌─────────────────────────────┐  │
+│      │ │      Primary Chart          │  │
+│      │ └─────────────────────────────┘  │
+│      ├──────────────────────────────────┤
+│      │ ┌────────────┐ ┌────────────┐    │
+│      │ │ Secondary  │ │ Secondary  │    │
+│      │ └────────────┘ └────────────┘    │
+└──────┴──────────────────────────────────┘
+```
+
+### Data Table Dashboard Structure
+
+```
+┌──────┬──────────────────────────────────┐
+│      │ Header: Title + Actions          │
+│ Side ├──────────────────────────────────┤
+│ bar  │ Filters Bar                      │
+│      ├──────────────────────────────────┤
+│      │ ┌─────────────────────────────┐  │
+│      │ │                             │  │
+│      │ │      Data Table             │  │
+│      │ │      (scrollable)           │  │
+│      │ │                             │  │
+│      │ └─────────────────────────────┘  │
+│      ├──────────────────────────────────┤
+│      │ Pagination                       │
+└──────┴──────────────────────────────────┘
+```
+
+### Specifications
+
+| Element | Value |
+|---------|-------|
+| Sidebar width | 240-280px (collapsible to 64px) |
+| Content padding | 24-32px |
+| KPI card grid | 4 columns desktop, 2 tablet, 1 mobile |
+| Grid gap | 16-24px |
+
+---
+
+## Design
+
+### Color Tokens
+
+| Element | Token |
+|---------|-------|
+| Page background | `bg-background` |
+| Card background | `bg-card` |
+| Card border | `border` |
+| Sidebar | `bg-sidebar` |
+| Positive trend | `text-green-600` / `text-green-500` (dark) |
+| Negative trend | `text-destructive` |
+| Neutral | `text-muted-foreground` |
+
+### KPI Card Pattern
+
+| Element | Specification |
+|---------|---------------|
+| Container | `bg-card`, `border`, 6px radius |
+| Padding | 24px (`p-6`) |
+| Label | `text-sm text-muted-foreground` |
+| Value | `text-2xl font-bold` or `text-3xl font-bold` |
+| Trend | Small text with arrow icon |
+
+### Chart Container Pattern
+
+| Element | Specification |
+|---------|---------------|
+| Container | `bg-card`, `border`, 6px radius |
+| Padding | 24px (`p-6`) |
+| Header | Title left, controls right |
+| Min height | 300px primary, 200px secondary |
+
+### Typography Hierarchy
+
+| Element | Style |
+|---------|-------|
+| Page title | `text-2xl font-bold` |
+| Section headers | `text-lg font-semibold` |
+| KPI labels | `text-sm text-muted-foreground` |
+| KPI values | `text-2xl font-bold` |
+| Chart titles | `text-base font-medium` |
+| Table headers | `text-sm font-medium` |
+
+---
+
+## Content
+
+### KPI Cards
+
+**Structure:**
+
+1. Label (what the metric is)
+2. Value (the number)
+3. Trend indicator (optional)
+4. Sparkline (optional)
+
+**Example Content:**
+
+| Label | Value | Trend |
+|-------|-------|-------|
+| "Total Revenue" | "$124,500" | "+12% vs last month" |
+| "Active Users" | "2,847" | "-3% vs last week" |
+| "Conversion Rate" | "4.2%" | "No change" |
+
+### Chart Headers
+
+```
+┌─────────────────────────────────────┐
+│ Chart Title          [Period ▼] [⋮]│
+├─────────────────────────────────────┤
+│                                     │
+│           Chart Area                │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+- Title describes what data shows
+- Period selector for time range
+- Overflow menu for export, settings
+
+### Empty States
+
+| Scenario | Message |
+|----------|---------|
+| No data available | "No data available for this time period" |
+| Filtered with no results | "No results match your filters" + "Clear filters" button |
+| Loading error | "Unable to load data" + "Retry" button |
+| New user | "No activity yet" + guidance to get started |
+
+### Loading States
+
+- KPI cards: Skeleton with pulse animation
+- Charts: Skeleton rectangle with centered spinner
+- Tables: 5-10 skeleton rows
+- Show loading indicator, never stale data without indicator
+
+---
+
+## 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 |
+|-------------|----------------|
+| Chart alternatives | Provide data tables as alternatives to visual charts |
+| Color meaning | Never use color alone for status (add icons, labels) |
+| Screen reader | KPI values announced with context ("Revenue: $124,500, up 12%") |
+| Focus order | KPIs first, then filters, then main content |
+| Live regions | Use `aria-live` for updating data |
+
+### Data Visualisation
+
+- Provide text summaries of chart insights
+- Link to accessible data table from each chart
+- Use patterns/textures in addition to colors
+- Ensure legends are keyboard navigable
+
+---
+
+## Implementation
+
+### Filter Patterns
+
+**Filter Bar (above content):**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ [Date Range ▼] [Category ▼] [Status ▼]    [Search] │
+└─────────────────────────────────────────────────────┘
+```
+
+- Horizontal layout
+- Date range picker left
+- Category filters middle
+- Search right
+- Background: `bg-muted/50` or transparent
+
+**Filter Sidebar (within content):**
+
+Use for complex filtering (10+ filter options):
+
+- Collapsible sections
+- Checkbox groups
+- Range sliders
+- "Apply" and "Clear" actions at bottom
+
+### Data Table Patterns
+
+| Element | Implementation |
+|---------|----------------|
+| Sortable columns | Click header to sort, show arrow direction |
+| Row selection | Checkbox in first column |
+| Row actions | Overflow menu or icon buttons |
+| Pagination | Bottom of table with page size selector |
+| Empty state | Centered message in table body |
+
+### State Management
+
+| State | Handling |
+|-------|----------|
+| Loading | Show skeleton, disable interactions |
+| Error | Show error message with retry |
+| Empty | Show contextual empty state |
+| Stale | Show "Last updated" timestamp |
+| Refreshing | Show subtle loading indicator, keep data visible |
+
+### Responsive Behavior
+
+| Breakpoint | KPI Grid | Charts | Tables |
+|------------|----------|--------|--------|
+| Mobile | 1 column | Full width, stacked | Horizontal scroll or card view |
+| Tablet | 2 columns | Full width | Horizontal scroll |
+| Desktop | 4 columns | Grid layout | Full table |
+
+---
+
+## Best Practices
+
+### Do's
+
+1. **Show key metrics first** - Most important KPIs at top
+2. **Provide context** - Explain what numbers mean
+3. **Enable comparison** - Show trends, previous periods
+4. **Allow customisation** - Date ranges, filters
+5. **Cache appropriately** - Don't reload unchanged data
+6. **Indicate data freshness** - Show last updated time
+
+### Don'ts
+
+1. **Don't overwhelm** - 4-6 KPIs maximum on first view
+2. **Don't auto-refresh** without indication
+3. **Don't use misleading scales** - Start axes at zero unless justified
+4. **Don't remove context** - Show units, time periods
+5. **Don't block interactions** during loading
+
+### Common Mistakes
+
+| Mistake | Solution |
+|---------|----------|
+| Too many metrics | Prioritise, use progressive disclosure |
+| No loading states | Add skeletons, spinners |
+| Unclear time periods | Always show selected date range |
+| Color-only status | Add icons, labels for accessibility |
+| Fixed chart sizes | Make charts responsive |
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Very large numbers | Use abbreviations (1.2M, 3.4K) |
+| Zero values | Show "0" not empty or dash |
+| Partial data | Show with caveat ("Data incomplete") |
+| Real-time data | Show update indicator, timestamp |
+| Export large datasets | Async export with notification |
+
+---
+
+## Related Documentation
+
+- [Layout Primitives](../design/layouts.md) - Sidebar Navigation layout
+- [Design Accessibility](../accessibility/design.md) - Color and contrast
+- [Multi-Column Layout](../design/layouts.md#4-multi-column-layout) - Grid patterns