@equal-experts/kuat-react 0.13.0 → 0.13.1

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

@@ -0,0 +1,68 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, component-decision-tree.md
+---
+
+# Component registry
+
+Stable IDs link upstream scenarios and checklists to per-component guides in the implementation overlay or npm `agent-docs/`.
+
+---
+
+## How to use
+
+1. Scenario or checklist cites an ID (e.g. `shadcn:button`).
+2. Resolve via `components.manifest.json`:
+   - Package: `node_modules/@equal-experts/kuat-react/agent-docs/components.manifest.json`
+   - Overlay: `{KUAT_RULES_OVERLAY_PATH}/components.manifest.json`
+3. Load `components/{slug}.md` from the manifest `path` field.
+
+**Slug:** ID without namespace prefix (`shadcn:button` → `button`).
+
+---
+
+## Registry (pilot)
+
+| ID | Display name | Source | Overlay / package doc | Upstream refs |
+|----|--------------|--------|----------------------|---------------|
+| `shadcn:button` | Button | shadcn CLI + `kuat-core` theme | `components/button.md` | [forms](./scenarios/forms.md), [authentication](./scenarios/authentication.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) |
+
+Expand this table in `kuat-mono` as component docs are added. Keep IDs stable; add new rows rather than renaming IDs.
+
+---
+
+## ID conventions
+
+| Prefix | Meaning | Example |
+|--------|---------|---------|
+| `kuat:` | Exported from Kuat packages or Kuat-specific | `kuat:button-group` |
+| `shadcn:` | App-installed shadcn primitive, EE-themed via kuat-core | `shadcn:dialog` |
+| `kuat:kuat-*` | Kuat blocks (compositions) | `kuat:kuat-header` |
+
+---
+
+## Manifest shape (downstream)
+
+```json
+{
+  "components": {
+    "shadcn:button": {
+      "path": "components/button.md",
+      "sources": ["shadcn:button", "@equal-experts/kuat-core"]
+    }
+  }
+}
+```
+
+Authoritative manifest lives in `kuat-mono` and is published inside each package `agent-docs/`.
+
+---
+
+## Related
+
+- [component-decision-tree.md](./component-decision-tree.md)
+- [consumption-architecture.md](../../../../setup/consumption-architecture.md)
+- [DEPRECATIONS.md](./DEPRECATIONS.md)

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

@@ -0,0 +1,29 @@
+# Product Content Rules
+
+UX writing and content patterns for Equal Experts web applications.
+
+---
+
+## Overview
+
+Product content is the text inside product interfaces: buttons, errors, forms, confirmations, empty states. Load [foundations content](../../../../foundations/content/voice-and-tone.md) first, then [product-content.md](./product-content.md).
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| [product-content.md](./product-content.md) | Core principles, voice formula, checklist |
+| [actions.md](./actions.md) | Buttons and links |
+| [confirmations.md](./confirmations.md) | Confirmation dialogs |
+| [empty-states.md](./empty-states.md) | Empty state copy |
+| [errors.md](./errors.md) | Error messages |
+| [forms.md](./forms.md) | Form labels, placeholders, validation, structure |
+
+---
+
+## Related
+
+- [Foundations content](../../../../foundations/content/README.md)
+- [Product design](../design.md)

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

@@ -0,0 +1,51 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, foundations/content/voice-and-tone.md, product/content/product-content.md
+---
+
+# 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 [foundations content formatting](../../../../foundations/content/formatting.md) for link guidelines
+
+---
+
+## Related
+
+- [Product content](./product-content.md)
+- [Confirmations](./confirmations.md)

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

@@ -0,0 +1,57 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, product/content/product-content.md
+---
+
+# 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/kuat-docs/rules/types/web/product/content/empty-states.md

@@ -0,0 +1,43 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, product/content/product-content.md
+---
+
+# 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/kuat-docs/rules/types/web/product/content/errors.md

@@ -0,0 +1,54 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, product/content/product-content.md
+---
+
+# 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/kuat-docs/rules/types/web/product/content/forms.md

@@ -0,0 +1,74 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, product/content/product-content.md
+---
+
+# 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)
+- [Foundations accessibility](../../../../foundations/accessibility.md)

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

@@ -0,0 +1,138 @@
+---
+scope: type
+platform: web_product
+prerequisites: foundations, foundations/content/voice-and-tone.md
+---
+
+# Product Content Guidelines
+
+UX writing and content guidelines for Equal Experts web applications.
+
+---
+
+**Prerequisites:** Load [foundations](../../../../foundations/) first, especially [voice and tone](../../../../foundations/content/voice-and-tone.md).
+
+---
+
+## 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
+
+- [Foundations content](../../../../foundations/content/README.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