@equal-experts/kuat-react 0.14.0 → 0.15.0-beta.1

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/{forms.md → complete-a-form.md}

@@ -1,19 +1,19 @@
-# Form Scenarios
+# Help users to complete a form
 
-Patterns for forms, settings pages, multi-step wizards, and data entry interfaces.
+**User goal:** Complete a form efficiently — understand what's needed, correct mistakes easily, and not
+lose work in progress.
 
----
+> **Pattern:** *Help users to…* · single-medium (web-product) — concept and implementation together.
+> Covers forms, settings pages, multi-step wizards, and data entry interfaces.
 
-## Principles
-
-### User Goals
+## Context
 
-- **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
+Forms are where users hand over information to get something done, and every field is friction between
+them and their task. They want to complete the task efficiently, understand what each field needs and
+why, fix errors without re-entering data, and trust that their progress won't be lost. This covers
+public forms, app settings, multi-step wizards, and inline data entry.
 
-### UX Principles
+## Principles
 
 | Principle | Implementation |
 |-----------|----------------|
@@ -22,16 +22,11 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Helpful feedback | Specific, actionable error messages |
 | Progress preservation | Save work, confirm destructive actions |
 
-### Success Metrics
+Success shows up as: form completion rate, time to complete, error rate and recovery, and abandonment rate.
 
-- Form completion rate
-- Time to complete
-- Error rate and recovery
-- Abandonment rate
+## Solution in web-product
 
----
-
-## Layout
+### Layout
 
 **Base Layout:** Varies by context
 
@@ -42,7 +37,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Multi-step wizards | Single Column or Horizontal Navigation |
 | Inline editing | Within parent layout |
 
-### Card-Based Form (Settings, Profile)
+#### Card-Based Form (Settings, Profile)
 
 ```
 ┌─────────────────────────────────────┐
@@ -55,7 +50,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 └─────────────────────────────────────┘
 ```
 
-### Multi-Step Wizard
+#### Multi-Step Wizard
 
 ```
 ┌─────────────────────────────────────┐
@@ -72,7 +67,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 └─────────────────────────────────────┘
 ```
 
-### Specifications
+#### Specifications
 
 | Element | Value |
 |---------|-------|
@@ -82,11 +77,9 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Section spacing | 32px between cards |
 | Settings page max-width | 800px |
 
----
-
-## Design
+### Design
 
-### Color Tokens
+#### Color Tokens
 
 | Element | Token |
 |---------|-------|
@@ -98,7 +91,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Error state | `border-destructive`, `text-destructive` |
 | Success indicator | `text-green-600` |
 
-### Typography
+#### Typography
 
 | Element | Style |
 |---------|-------|
@@ -110,7 +103,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Error text | `text-sm text-destructive` |
 | Required indicator | `text-destructive` (asterisk) |
 
-### Spacing
+#### Spacing
 
 | Element | Value |
 |---------|-------|
@@ -119,11 +112,9 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Between fields | 24px |
 | Button group gap | 16px |
 
----
+### Content
 
-## Content
-
-### Field Labels
+#### Field Labels
 
 | Requirement | Example |
 |-------------|---------|
@@ -131,7 +122,7 @@ Patterns for forms, settings pages, multi-step wizards, and data entry interface
 | Required indicator | "Email address *" |
 | Optional indicator | "Phone number (optional)" |
 
-### Helper Text
+#### Helper Text
 
 Use to:
 - Explain format requirements
@@ -144,7 +135,7 @@ Email address *
 We'll send your receipt to this address.
 ```
 
-### Error Messages
+#### Error Messages
 
 | Quality | Bad | Good |
 |---------|-----|------|
@@ -152,7 +143,7 @@ We'll send your receipt to this address.
 | Actionable | "Error" | "Please enter a valid date (DD/MM/YYYY)" |
 | Polite | "Wrong!" | "Please check this field" |
 
-### Button Labels
+#### Button Labels
 
 | Action | Label |
 |--------|-------|
@@ -162,9 +153,7 @@ We'll send your receipt to this address.
 | Cancel | "Cancel", "Discard changes" |
 | Delete | "Delete", "Remove" |
 
----
-
-## Accessibility
+### Accessibility
 
 **Base requirements:** See [accessibility foundations](../../../accessibility/accessibility.md) and [web accessibility](../accessibility.md)
 
@@ -179,7 +168,7 @@ We'll send your receipt to this address.
 | Focus management | Focus first error after failed submission |
 | No time limits | Allow unlimited time (or generous extension) |
 
-### Form Validation Pattern
+#### Form Validation Pattern
 
 **Critical: Validate on submit, not on blur**
 
@@ -191,18 +180,16 @@ We'll send your receipt to this address.
 | Error summary | Show summary above form with field links |
 | Focus first error | Move focus to first invalid field |
 
-### Grouping
+#### Grouping
 
 Use `<fieldset>` and `<legend>` for:
 - Radio button groups
 - Checkbox groups
 - Related fields (e.g., address components)
 
----
-
-## Implementation
+### Implementation
 
-### Field Layout Patterns
+#### Field Layout Patterns
 
 **Vertical (Default):**
 
@@ -233,7 +220,7 @@ Best for: Settings pages with many fields
 
 Best for: Related fields (names, addresses)
 
-### Button Placement
+#### Button Placement
 
 **Component guide:** `shadcn:button` — the `components/button.md` guide for button behaviour lives in the consumer package `agent-docs/` or overlay (see [component-registry.md](../component-registry.md)).
 
@@ -259,7 +246,7 @@ Best for: Related fields (names, addresses)
 | Left | Back (`variant="outline"`) |
 | Right | Next/Submit (`variant="default"`) |
 
-### Settings Page Pattern
+#### Settings Page Pattern
 
 Multiple card sections, each independently saveable:
 
@@ -281,7 +268,7 @@ Multiple card sections, each independently saveable:
 | Section max-width | 800px |
 | Alignment | Left-aligned (not centered) |
 
-### Multi-Step Wizard Pattern
+#### Multi-Step Wizard Pattern
 
 **Progress Indicator:**
 
@@ -301,7 +288,7 @@ Multiple card sections, each independently saveable:
 - Warn before leaving with unsaved changes
 - Handle session timeout gracefully
 
-### Responsive Behavior
+#### Responsive Behavior
 
 | Breakpoint | Grid Fields | Button Layout |
 |------------|-------------|---------------|
@@ -309,8 +296,6 @@ Multiple card sections, each independently saveable:
 | Tablet | 2 columns | Horizontal |
 | Desktop | As designed | Horizontal |
 
----
-
 ## Best Practices
 
 ### Do's
@@ -352,10 +337,15 @@ Multiple card sections, each independently saveable:
 | Session timeout | Save draft, prompt re-auth |
 | Network failure | Queue submission, retry automatically |
 
----
+## Examples
+
+The card-based form above (600px max-width, section title in the header, fields stacked with 24px
+spacing, and `[Cancel] [Save]` in the footer) is the canonical mid-fidelity frame. The same frame
+scales up to independently saveable settings sections and, with a progress indicator and Back / Next
+controls, to multi-step wizards.
 
-## Related Documentation
+## Related
 
 - [Product Design](../design.md) - Layout options
 - [Web Accessibility](../accessibility.md) - Form validation pattern
-- [Authentication Pattern](./authentication.md) - Login/registration forms
+- [Help users to sign in](./sign-in.md) - Login/registration forms

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/{dashboards.md → dashboard.md}

@@ -1,19 +1,19 @@
-# Dashboard Scenarios
+# Dashboard
 
-Patterns for data dashboards, analytics views, metrics displays, and reporting interfaces.
+**User goal:** See the key metrics at a glance, understand trends over time, and move from data to a
+confident decision — drilling into detail only when needed.
 
----
+> **Pattern:** *Pages* · single-medium (web-product) — concept and implementation together.
+> Covers analytics views, metrics displays, data tables, and reporting interfaces.
 
-## Principles
-
-### User Goals
+## Context
 
-- **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
+A dashboard exists to turn data into decisions. Users arrive wanting insights quickly, with the most
+important metrics visible at a glance, patterns and changes over time made legible, and clear paths from
+what the numbers say to what to do next — while keeping the option to explore deeper when a question
+demands it.
 
-### UX Principles
+## Principles
 
 | Principle | Implementation |
 |-----------|----------------|
@@ -22,22 +22,18 @@ Patterns for data dashboards, analytics views, metrics displays, and reporting i
 | Consistent data | Same time periods, units, formats |
 | Actionable context | Explain what numbers mean |
 
-### Success Metrics
+Success shows up as: time to find key information, decision confidence, filter usage patterns, and
+drill-down completion rates.
 
-- Time to find key information
-- Decision confidence
-- Filter usage patterns
-- Drill-down completion rates
+## Solution in web-product
 
----
-
-## Layout
+### Layout
 
 **Base Layout:** Sidebar Navigation
 
 Dashboards benefit from persistent navigation and maximum content width.
 
-### Metrics Dashboard Structure
+#### Metrics Dashboard Structure
 
 ```
 ┌──────┬──────────────────────────────────┐
@@ -57,7 +53,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 └──────┴──────────────────────────────────┘
 ```
 
-### Data Table Dashboard Structure
+#### Data Table Dashboard Structure
 
 ```
 ┌──────┬──────────────────────────────────┐
@@ -76,7 +72,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 └──────┴──────────────────────────────────┘
 ```
 
-### Specifications
+#### Specifications
 
 | Element | Value |
 |---------|-------|
@@ -85,11 +81,9 @@ Dashboards benefit from persistent navigation and maximum content width.
 | KPI card grid | 4 columns desktop, 2 tablet, 1 mobile |
 | Grid gap | 16-24px |
 
----
-
-## Design
+### Design
 
-### Color Tokens
+#### Color Tokens
 
 | Element | Token |
 |---------|-------|
@@ -101,7 +95,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Negative trend | `text-destructive` |
 | Neutral | `text-muted-foreground` |
 
-### KPI Card Pattern
+#### KPI Card Pattern
 
 | Element | Specification |
 |---------|---------------|
@@ -111,7 +105,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Value | `text-2xl font-bold` or `text-3xl font-bold` |
 | Trend | Small text with arrow icon |
 
-### Chart Container Pattern
+#### Chart Container Pattern
 
 | Element | Specification |
 |---------|---------------|
@@ -120,7 +114,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Header | Title left, controls right |
 | Min height | 300px primary, 200px secondary |
 
-### Typography Hierarchy
+#### Typography Hierarchy
 
 | Element | Style |
 |---------|-------|
@@ -131,11 +125,9 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Chart titles | `text-base font-medium` |
 | Table headers | `text-sm font-medium` |
 
----
+### Content
 
-## Content
-
-### KPI Cards
+#### KPI Cards
 
 **Structure:**
 
@@ -152,7 +144,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 | "Active Users" | "2,847" | "-3% vs last week" |
 | "Conversion Rate" | "4.2%" | "No change" |
 
-### Chart Headers
+#### Chart Headers
 
 ```
 ┌─────────────────────────────────────┐
@@ -168,7 +160,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 - Period selector for time range
 - Overflow menu for export, settings
 
-### Empty States
+#### Empty States
 
 | Scenario | Message |
 |----------|---------|
@@ -177,16 +169,14 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Loading error | "Unable to load data" + "Retry" button |
 | New user | "No activity yet" + guidance to get started |
 
-### Loading States
+#### 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
+### Accessibility
 
 **Base requirements:** See [accessibility foundations](../../../accessibility/accessibility.md) and [web accessibility](../accessibility.md)
 
@@ -200,18 +190,16 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Focus order | KPIs first, then filters, then main content |
 | Live regions | Use `aria-live` for updating data |
 
-### Data Visualisation
+#### 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
+### Implementation
 
-### Filter Patterns
+#### Filter Patterns
 
 **Filter Bar (above content):**
 
@@ -236,7 +224,7 @@ Use for complex filtering (10+ filter options):
 - Range sliders
 - "Apply" and "Clear" actions at bottom
 
-### Data Table Patterns
+#### Data Table Patterns
 
 | Element | Implementation |
 |---------|----------------|
@@ -246,7 +234,7 @@ Use for complex filtering (10+ filter options):
 | Pagination | Bottom of table with page size selector |
 | Empty state | Centered message in table body |
 
-### State Management
+#### State Management
 
 | State | Handling |
 |-------|----------|
@@ -256,7 +244,7 @@ Use for complex filtering (10+ filter options):
 | Stale | Show "Last updated" timestamp |
 | Refreshing | Show subtle loading indicator, keep data visible |
 
-### Responsive Behavior
+#### Responsive Behavior
 
 | Breakpoint | KPI Grid | Charts | Tables |
 |------------|----------|--------|--------|
@@ -264,8 +252,6 @@ Use for complex filtering (10+ filter options):
 | Tablet | 2 columns | Full width | Horizontal scroll |
 | Desktop | 4 columns | Grid layout | Full table |
 
----
-
 ## Best Practices
 
 ### Do's
@@ -305,9 +291,14 @@ Use for complex filtering (10+ filter options):
 | Real-time data | Show update indicator, timestamp |
 | Export large datasets | Async export with notification |
 
----
+## Examples
+
+The sidebar-navigation frame above is the canonical mid-fidelity dashboard: a row of KPI cards across the
+top (4 columns on desktop), a primary chart below, and secondary charts beneath that. The data-table
+variant swaps the chart stack for a filters bar, a scrollable table, and pagination — same shell, different
+content body.
 
-## Related Documentation
+## Related
 
 - [Product Design](../design.md) - Sidebar Navigation layout
 - [Accessibility foundations](../../../accessibility/accessibility.md) - Color and contrast