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

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-marketing/website.md

@@ -10,6 +10,20 @@ Marketing websites are public-facing pages designed to inform, engage, and conve
 
 ---
 
+## Colour Usage
+
+Marketing pages are **core-dominant**: Tier 1 (EE Blue, Transform Teal, Tech Blue, Equal Ember,
+Dark Data, The Cloud, White) for almost everything. Full-page background floods are restricted to
+**Tech Blue or Dark Data** (or The Cloud / white) — EE Blue is used at block/component level only,
+never as a full-page fill.
+
+Extended-palette colours (Logic Lime, Equal Ember) appear only as small pull-outs — dark text on
+them, never body text, never a full flood — and must stay within **~5–10% of a page's total
+area**. See [colour-usage.md](../../design-language/colour-usage.md) for the full tier model and
+[colours.md](../../design-language/colours.md) for values.
+
+---
+
 ## Layout Structure
 
 ```

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

@@ -5,6 +5,7 @@ Reference for Equal Experts web applications, dashboards, internal tools, and pr
 | File | Scope |
 |------|-------|
 | [design.md](./design.md) | Layout, navigation, product visual patterns |
+| [colour-modes.md](./colour-modes.md) | Shadcn light/dark semantic colour mapping |
 | [accessibility.md](./accessibility.md) | Product accessibility requirements |
 | [emails.md](./emails.md) | Transactional / product email patterns |
 | [component-decision-tree.md](./component-decision-tree.md) | Which component source to use (Blocks → Kuat → shadcn → custom) |

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

@@ -355,35 +355,6 @@ Kuat components automatically respect `prefers-reduced-motion`. When building cu
 
 ---
 
-## Testing Checklist
-
-### Keyboard Testing
-
-- [ ] Can reach all interactive elements with Tab
-- [ ] Focus order is logical
-- [ ] Focus indicator is visible
-- [ ] Can activate buttons/links with Enter/Space
-- [ ] Can close modals with Escape
-- [ ] No keyboard traps
-
-### Screen Reader Testing
-
-- [ ] Page has descriptive title
-- [ ] Headings create logical outline
-- [ ] Images have appropriate alt text
-- [ ] Links and buttons have clear labels
-- [ ] Form fields are labelled
-- [ ] Error messages are announced
-
-### Visual Testing
-
-- [ ] Content visible at 200% zoom
-- [ ] Works in both orientations
-- [ ] Colour contrast meets requirements
-- [ ] Information not conveyed by colour alone
-
----
-
 ## Related Documentation
 
 - [Accessibility foundations](../../accessibility/accessibility.md) - Principles and guidelines

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

@@ -0,0 +1,58 @@
+# Colour Modes (Light & Dark)
+
+Shadcn/ui semantic-role mapping for Equal Experts product UI. Product UI runs on a 50–950
+primitive scale with semantic role tokens (`background`, `foreground`, `primary`,
+`primary-foreground`, …) that flip value between light and dark mode while the role name stays
+fixed — components reference `bg-primary text-primary-foreground` and the mode handles the rest.
+
+**Status:** the mapping below is agreed (June 2026 colours lockdown) and is the target for
+`@equal-experts/kuat-core`'s light and dark themes and `token-contract.json` (published
+downstream). Until that release ships, treat the recommended values as the authority for review
+and design work; the shipped `--color-*` CSS custom properties are the implementation of record
+once published — see [colours.md](../../design-language/colours.md) for the upstream token values
+these resolve from.
+
+## Light mode
+
+| Role | Value | Notes |
+|------|-------|-------|
+| `background` / `foreground` | White / Dark Data | 15.5:1 |
+| `card` / `card-foreground` | White / Dark Data | 15.5:1 |
+| `primary` / `primary-foreground` | EE Blue-600 `#1378ae` / White | EE Blue-600, not the brand -500, so white button text reaches AA (4.85:1); brand EE Blue `#1795d4` only passes for large/bold labels |
+| `secondary` / `secondary-foreground` | Transform Teal-50 / Transform Teal-700 | 6.8:1 |
+| `muted` / `muted-foreground` | The Cloud / Server Slate | 6.9:1 |
+| `accent` / `accent-foreground` | EE Blue-50 / EE Blue-700 | 6.5:1 |
+| `destructive` / `destructive-foreground` | Runtime Red / White | 7.8:1 |
+| `ring` | EE Blue-600 | Meets 3:1 UI floor |
+| `border` / `input` | Light neutral | Decorative divider — subtle by design, not a state indicator |
+| `chart-1…5` | Tier 3 order | EE Blue, Equal Ember, Tech Blue, Logic Lime, Packet Plum |
+
+## Dark mode
+
+| Role | Value | Notes |
+|------|-------|-------|
+| `background` / `foreground` | Dark Data / The Cloud | 14.2:1 |
+| `card` / `card-foreground` | Dark surface / The Cloud | 12.5:1 |
+| `primary` / `primary-foreground` | EE Blue (brand -500) / Dark Data | 4.6:1 — on dark surfaces, brand EE Blue itself passes with dark text |
+| `secondary` / `secondary-foreground` | Tech Blue / White | 7.8:1 |
+| `muted` / `muted-foreground` | Dark neutral / Edge Blue | 7.2:1 |
+| `accent` / `accent-foreground` | Tech Blue-900 / Edge Blue | 10.7:1 |
+| `destructive` / `destructive-foreground` | Runtime Red / White | 7.8:1 (unchanged from light mode) |
+| `ring` | EE Blue (brand -500) | — |
+| `border` / `input` | Dark neutral | — |
+| `chart-1…5` | Tier 3 order, dark-adjusted | EE Blue, Equal Ember, Edge Blue, Logic Lime, Signal Yellow (Edge Blue/Signal Yellow swapped in for dark-surface contrast) |
+
+## Interaction states
+
+Hover/active states use **Edge Blue** (the light end of the three-stage blue — see
+[colour-usage.md](../../design-language/colour-usage.md#the-three-stage-blue)), not a raw opacity
+tint of EE Blue. Interactive elements combine a tint-plus-darker-overlay treatment with an
+affordance cue (border-radius, shape) — colour is never the only signal that something is
+clickable.
+
+## Links vs primary actions
+
+`primary` (buttons, key CTAs) uses EE Blue; text links and small text use the semantic `link`
+token, not `primary` — see
+[colour-usage.md](../../design-language/colour-usage.md#links-vs-buttons--the-accessible-blue) for
+why these are deliberately different values.

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/component-decision-tree.md

@@ -206,38 +206,9 @@ import { cn } from "@/lib/utils"
 
 ---
 
-## Testing Checklist
-
-Before shipping a component, verify:
-
-### Functionality
-- [ ] All variants render correctly
-- [ ] Default props work
-- [ ] Custom className can be passed
-- [ ] Component ref is forwarded (React)
-
-### Types
-- [ ] Props are properly typed
-- [ ] Types are exported
-- [ ] No TypeScript errors
-
-### Accessibility
-- [ ] Keyboard navigation works
-- [ ] Screen reader announces correctly
-- [ ] Focus visible and logical
-- [ ] ARIA attributes present
-
-### Styling
-- [ ] Uses design tokens
-- [ ] Works in light and dark mode
-- [ ] Responsive if applicable
-- [ ] Matches design specifications
-
-### Edge Cases
-- [ ] Long text handled
-- [ ] Empty states handled
-- [ ] Loading states (if applicable)
-- [ ] Error states (if applicable)
+## Component testing
+
+Component test strategy and per-component verification (functionality, types, accessibility, styling, edge cases) are **owned by the implementation repo** — `kuat-mono` and the published package — per the upstream/local ownership split (see the repo's `AGENTS.md`). This reference covers component **selection and structure**, not test procedure.
 
 ---
 

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

@@ -8,7 +8,7 @@ Stable IDs link patterns and checklists to per-component guides in the implement
 
 | ID | Display name | Source | Overlay / package doc | Upstream refs |
 |----|--------------|--------|----------------------|---------------|
-| `shadcn:button` | Button | shadcn CLI + `kuat-core` theme | `components/button.md` | [forms](./patterns/forms.md), [authentication](./patterns/authentication.md), [content/actions](./content/actions.md) |
+| `shadcn:button` | Button | shadcn CLI + `kuat-core` theme | `components/button.md` | [complete a form](./patterns/complete-a-form.md), [sign in](./patterns/sign-in.md), [content/actions](./content/actions.md) |
 | `kuat:button-group` | ButtonGroup | `@equal-experts/kuat-react` / `kuat-vue` | `components/button-group.md` | [component-decision-tree](./component-decision-tree.md) |
 | `kuat:kuat-header` | KuatHeader | `@equal-experts/kuat-react` / `kuat-vue` block | `components/kuat-header.md` | [component-decision-tree](./component-decision-tree.md), [design](./design.md) |
 

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

@@ -90,32 +90,6 @@ Before writing, know:
 
 ---
 
-## 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

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

@@ -1,10 +1,19 @@
 # Web Product Patterns
 
-Applied layout and design patterns for web-application page types.
+Outcome-framed patterns for web-application page types, grouped by the user outcome they serve (see the
+[patterns overview](../../../patterns/overview.md)). Each is **single-medium**: its concept and its
+web-product implementation live together in one document.
+
+## Help users to…
+
+| Pattern | For | Base layout |
+|---------|-----|-------------|
+| [Sign in](./sign-in.md) | Login, registration, password flows, MFA | Single column |
+| [Complete a form](./complete-a-form.md) | Settings, multi-step forms, data entry | Varies |
+
+## Pages
 
 | 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 |
+| [Dashboard](./dashboard.md) | Analytics, data tables, metrics, reporting | Sidebar navigation |
+| [Documentation](./documentation.md) | Docs sites, knowledge bases, API reference | Sidebar + split |

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