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

package/agent-docs/external/kuat-agent-rules/kuat-docs/rules/foundations/content/voice-and-tone.md

@@ -1,263 +0,0 @@
-# Voice and Tone
-
-Universal voice and tone for Equal Experts content. Applies to all platforms and media. Read this before any platform-specific content guide.
-
----
-
-## Overview
-
-These guidelines ensure consistent voice and tone across all Equal Experts communications, regardless of platform or medium.
-
----
-
-## Quick Reference
-
-**Always:**
-- Be clear and direct
-- Focus on audience needs
-- Use plain language
-- Be specific, not vague
-
-**Never:**
-- Use "revolutionize", "transform", "disrupt" without specific evidence
-- Hide behind jargon
-- Speak down to audience
-- Be vague or ambiguous
-
----
-
-## Content Voice and Tone
-
-### Universal Principles
-
-#### Clear and Direct
-- Get to the point quickly
-- Use plain language
-- Avoid unnecessary words
-- Be specific, not vague
-
-#### Helpful and Respectful
-- Anticipate audience needs
-- Provide guidance when needed
-- Respect audience's time and intelligence
-- Never talk down to people
-
-#### Confident but Humble
-- Show expertise through clarity
-- Admit when something isn't available
-- Provide alternatives when possible
-- Build trust through honesty
-
-#### Consistent and Predictable
-- Use the same terms for the same concepts
-- Follow established patterns
-- Maintain consistent tone across touchpoints
-- Set clear expectations
-
----
-
-## Content Principles
-
-### 1. Audience-First Thinking
-
-Before creating content, define:
-- The specific aim
-- The target audience
-- How it helps the audience achieve their goals
-- What question it answers
-
-### 2. Clarity Over Cleverness
-
-Prioritize:
-- Clear communication
-- Easy comprehension
-- Quick understanding
-
-Avoid:
-- Clever wordplay that obscures meaning
-- Jokes that might confuse
-- Metaphors that require explanation
-- Industry jargon without context
-
-### 3. Be Clear and Concise
-
-- Use plain English where possible
-- Don't use 10 words when 3 will do
-- Avoid jargon-laden complexity
-- Give yourself the best chance of being read and understood
-
-### 4. Consistency Matters
-
-- Use the same terms for the same concepts
-- Follow established patterns
-- Maintain consistent tone
-- Set clear expectations
-
-### 5. Test, Iterate and Learn
-
-Test new content, improve based on feedback, share learnings across the team.
-
----
-
-## Audience Considerations
-
-### Technical Audiences (Developers, Engineers)
-
-**Tone:** Pragmatic, evidence-based, respectful of expertise
-
-**Use:**
-- Specific technical details
-- Code examples and practical patterns
-- Trade-offs and architectural decisions
-
-**Avoid:**
-- Over-simplification
-- Buzzwords without substance
-- Marketing language
-
-### Business Stakeholders (Product Owners, Leaders)
-
-**Tone:** Outcome-focused, clear, strategic
-
-**Use:**
-- Business metrics and outcomes
-- Efficiency gains and ROI
-- Impact statements
-
-**Avoid:**
-- Deep technical detail without context
-- Acronyms without explanation
-- Technology for technology's sake
-
-### General Audiences
-
-**Tone:** Helpful, clear, accessible
-
-**Use:**
-- Plain language
-- Clear explanations
-- Practical examples
-
-**Avoid:**
-- Any unnecessary words
-- Corporate speak
-- Jargon or technical terms
-
----
-
-## Common Anti-Patterns
-
-### Buzzword Bingo
-Using trendy terminology without substance.
-
-❌ "Leveraging synergistic blockchain-enabled AI solutions"  
-✅ "We automated invoice processing using existing APIs"
-
-### Feature Dump
-Listing features without context or benefit.
-
-❌ "Features: Dashboard, Reports, Analytics, Integrations"  
-✅ "The dashboard surfaces the three metrics teams check daily"
-
-### Vague Promise
-Making claims without evidence or specifics.
-
-❌ "We'll dramatically improve your performance"  
-✅ "Teams typically see 40-60% reduction in deployment time"
-
-### Over-Explanation
-Explaining things that don't need explanation.
-
-❌ "Click the button below to continue to the next screen"  
-✅ [Continue]
-
----
-
-## Content Quality Checklist
-
-### The Clarity Test
-Can it be understood in 30 seconds of skimming?
-
-### The Purpose Test
-Does this answer a specific question or solve a problem?
-
-### The Consistency Test
-Does it use consistent terminology and follow established patterns?
-
-### The Audience Test
-Is this appropriate for the intended audience?
-
-### The Accessibility Test
-Does it work for all people, including those using assistive technologies?
-
----
-
-## Tone Adaptation Guide
-
-### For Seriousness Levels
-
-**Standard:** Friendly, approachable, professional  
-**High Stakes:** Serious, direct, solution-focused  
-**Celebratory:** Warm, enthusiastic, appreciative  
-**Difficult News:** Empathetic, honest, supportive
-
----
-
-## For AI Content Generation
-
-### Before Generating
-
-Confirm:
-1. **Content type** - What format?
-2. **Audience** - Who will read this?
-3. **Purpose** - What outcome does this serve?
-4. **Context** - Do you have enough information?
-
-**If unclear, ask clarifying questions.**
-
-### While Generating
-
-**Do:**
-- Use specific examples
-- Include evidence when claiming results
-- Default to plain English
-- Apply appropriate tone for audience
-
-**Don't:**
-- Generate generic content
-- Make claims without evidence
-- Use "revolutionize", "transform", "disrupt" without proof
-- Write like typical AI-generated content
-
-### After Generating
-
-Apply quality tests:
-1. Clarity Test
-2. Purpose Test
-3. Consistency Test
-4. Audience Test
-5. Accessibility Test
-
-**Red flags:**
-- Generic phrases applicable to any context
-- Lack of specific examples
-- Over-use of buzzwords
-- Tone mismatch with audience
-
----
-
-## Platform-Specific Content
-
-For platform-specific content guidance:
-
-- **Web Marketing** - See [types/web/marketing/](../../types/web/marketing/)
-- **Web Product** - See [types/web/product/](../../types/web/product/)
-- **Slides** - See [types/slides/](../../types/slides/)
-
----
-
-## Related Documentation
-
-- [Brand Guidelines](../brand.md) - Brand voice and values
-- [Writing style](./writing-style.md) - Active voice, plain language, conventions
-- [Design](../design/README.md) - Visual design principles

package/agent-docs/external/kuat-agent-rules/kuat-docs/rules/foundations/design/README.md

@@ -1,28 +0,0 @@
-# Design Rules
-
-Visual design tokens and principles for Equal Experts. Apply across all platforms (web, slides, graphics, photography).
-
----
-
-## Overview
-
-These rules define the design language: colours, typography, spacing, borders, and high-level design principles. Load with [foundations brand and logo](../brand.md) and [foundations content](../content/) as needed.
-
----
-
-## Files
-
-| File | Description |
-|------|-------------|
-| [design-language.md](./design-language.md) | Design principles and token overview |
-| [colours.md](./colours.md) | Brand colour palette and usage |
-| [typography.md](./typography.md) | Fonts and type scale |
-| [spacing.md](./spacing.md) | Spacing system |
-| [borders.md](./borders.md) | Border philosophy and specifications |
-
----
-
-## Related
-
-- [Foundations](../README.md) – Brand, logo, accessibility
-- [Content](../content/README.md) – Writing and style

package/agent-docs/external/kuat-agent-rules/kuat-docs/rules/types/web/marketing/scenarios/README.md

@@ -1,18 +0,0 @@
-# Marketing Scenarios
-
-Applied layout and design patterns for marketing website page types.
-
----
-
-## Available Scenarios
-
-| Scenario | Use For | Base Layout |
-|----------|---------|-------------|
-| [marketing-pages.md](./marketing-pages.md) | Landing pages, pricing, features, case studies | Horizontal Navigation |
-
----
-
-## Related Documentation
-
-- [Marketing Website](../website.md) - Marketing website guidelines
-- [Foundations Accessibility](../../../../foundations/accessibility.md) - Accessibility principles

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

@@ -1,28 +0,0 @@
-# Web product — deprecations
-
-Assets superseded by package/overlay component guides and consumption architecture.
-
----
-
-| Asset | Status | Replacement |
-|-------|--------|-------------|
-| [examples/react/components.md](./examples/react/components.md) | Deprecated | `shadcn:button` etc. → package `agent-docs/components/{slug}.md` |
-| [examples/vue/components.md](./examples/vue/components.md) | Deprecated | Same |
-| Full CVA source listings in examples | Deprecated | [component-registry.md](./component-registry.md) + overlay docs |
-| Duplicate consumer setup in [technical.md](./technical.md) | Trimmed | Package README + `agent-docs/AGENTS.md` |
-| [kuat-docs/.tmp/documentation-agent.md](../../../.tmp/documentation-agent.md) | Moved | `kuat-mono/contribution-docs/component-documentation-agent.md` (mono plan) |
-
----
-
-## Examples directory policy
-
-[examples/](./examples/) remains for **create** sessions as illustrative token/layout syntax. Do **not** treat example component source as canonical API.
-
-Load [examples/README.md](./examples/README.md) for scope. Prefer component IDs when generating UI.
-
----
-
-## Related
-
-- [component-registry.md](./component-registry.md)
-- [consumption-architecture.md](../../../../setup/consumption-architecture.md)

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

@@ -1,65 +0,0 @@
-# Web product rules
-
-Guidelines for Equal Experts web applications, dashboards, internal tools, and product emails.
-
----
-
-**Prerequisites:** Load [foundations](../../../foundations/) first.
-
-**Architecture:** [consumption-architecture.md](../../../../setup/consumption-architecture.md) — entry points and package bundling.
-
----
-
-## Core files
-
-| File | Purpose |
-|------|---------|
-| [design.md](./design.md) | Layout, navigation, product visual patterns |
-| [accessibility.md](./accessibility.md) | Product accessibility requirements |
-| [technical.md](./technical.md) | Stack, tokens, integration (summary; consumer setup in package README) |
-| [component-decision-tree.md](./component-decision-tree.md) | Which component source to use (Blocks → Kuat → shadcn → custom) |
-| [component-registry.md](./component-registry.md) | Stable component IDs → overlay/package docs |
-| [review-context.md](./review-context.md) | Product context for review at `product_ux` / `full` depth |
-| [review-checklist.md](./review-checklist.md) | Review checklist |
-
----
-
-## Subdirectories
-
-| Directory | Purpose |
-|-----------|---------|
-| [content/](./content/) | UX copy (actions, errors, forms, confirmations) |
-| [scenarios/](./scenarios/) | Page-type patterns (auth, forms, dashboards, documentation) |
-| [examples/](./examples/) | Framework code samples — **create only**; see [DEPRECATIONS.md](./DEPRECATIONS.md) |
-
----
-
-## Component-level guides
-
-Per-component usage, variants, API, and accessibility behaviour live in the **implementation overlay** or **npm package** `agent-docs/components/`, not in this upstream tree.
-
-1. Look up the ID in [component-registry.md](./component-registry.md).
-2. Resolve `components/{slug}.md` via `components.manifest.json` in:
-   - `node_modules/@equal-experts/kuat-react/agent-docs/`, or
-   - `KUAT_RULES_OVERLAY_PATH` (e.g. `kuat-mono/kuat-docs/`).
-
-Upstream scenarios cite IDs (e.g. `shadcn:button`) — load the matching component doc when implementing or reviewing that primitive.
-
----
-
-## LOADING summary
-
-| Intent | Load |
-|--------|------|
-| **review** | design, accessibility, component-decision-tree, review-context, review-checklist + relevant scenario; skip `examples/` |
-| **create** | Above + scenarios/content as needed + `examples/` when generating code |
-
-Full index: [LOADING.md](../../../LOADING.md).
-
----
-
-## Related
-
-- [Web rules parent](../README.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/review-checklist.md

@@ -1,57 +0,0 @@
-# Web Product — Review Checklist
-
-Use for **review** intent at any depth. Pair with [review-context.md](./review-context.md) when depth is `product_ux` or `full`.
-
-**See also:** [design.md](./design.md), [accessibility.md](./accessibility.md), [component-decision-tree.md](./component-decision-tree.md), [kuat-review](../../../../skills/kuat-review/SKILL.md).
-
----
-
-## Brand compliance (all depths)
-
-- [ ] Colours from approved palette / semantic tokens — no arbitrary hex in UI
-- [ ] Typography uses defined scale (Lexend, type roles)
-- [ ] Spacing follows 4px grid
-- [ ] Logo usage follows [foundations/logo.md](../../../foundations/logo.md) if present
-- [ ] Border radius: 0px static content, 6px interactive, 4px inputs
-
----
-
-## Accessibility (all depths)
-
-- [ ] Single logical H1 per view (or equivalent page title pattern)
-- [ ] Heading hierarchy is sequential
-- [ ] Text contrast meets WCAG AA (4.5:1 body, 3:1 large text/UI)
-- [ ] Focus states visible for keyboard users
-- [ ] Images have appropriate alt text (decorative: empty alt)
-- [ ] Interactive controls have accessible names
-
-See [accessibility.md](./accessibility.md) for full requirements.
-
----
-
-## Product patterns (all depths)
-
-- [ ] Product layout uses dark navigation pattern where applicable ([design.md](./design.md))
-- [ ] Components sourced per [component-decision-tree.md](./component-decision-tree.md)
-- [ ] Primitives match component guides for cited IDs (`shadcn:button`, `kuat:*`) from package `agent-docs/` or overlay
-- [ ] No inline styles for themeable properties — use design tokens
-
----
-
-## Product / UX fit (`product_ux` or `full` only)
-
-**Blocked** until [review-context.md](./review-context.md) items are supplied. Do not score this section without user story and scope.
-
-- [ ] Primary actions and labels support the stated job-to-be-done ([content/actions.md](./content/actions.md))
-- [ ] Copy enables task completion — not marketing tone ([content/product-content.md](./content/product-content.md))
-- [ ] Errors, empty, and loading states match scoped flows (see relevant [scenarios/](./scenarios/) file)
-- [ ] Form labels and validation align with scenario rules if applicable
-- [ ] Screen content reflects stated success criteria from review context — cite evidence
-
-If context missing: mark section **Blocked** and list required items under Open questions.
-
----
-
-## Report usage
-
-Map failures to [kuat-review](../../../../skills/kuat-review/SKILL.md) violation table. Cite the rule file for each finding.

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

@@ -1,44 +0,0 @@
-# Web Product — Review Context
-
-Product and research context to gather **before** reviewing web features at `product_ux` or `full` depth. See skill [kuat-review](../../../../skills/kuat-review/SKILL.md).
-
-**Skip this file** when review depth is `brand_compliance` only — note in the report that UX/content fit is out of scope.
-
----
-
-## Mandatory questions
-
-Ask for anything missing in the grouped intake message:
-
-| Context | Ask for |
-|---------|---------|
-| **User story / job-to-be-done** | Who is the user, what are they trying to do, what outcome counts as success? |
-| **Research & evidence** | Insights, interview themes, analytics, usability findings — or explicit "none yet" |
-| **Constraints** | Deadlines, tech limits, policy, must-use patterns |
-| **Scope** | Which screens/states (happy path only vs errors, empty, loading, edge cases) |
-| **Known decisions** | What discovery already decided (avoid relitigating settled choices) |
-
----
-
-## Optional but useful
-
-- Competitor or reference examples the team used
-- Prior iteration feedback
-- Accessibility audit or QA results
-- Links to tickets, PRDs, or Figma flows
-
----
-
-## If context is withheld
-
-- Proceed at `brand_compliance` if the user confirms, or
-- Produce **provisional** UX notes with assumptions listed under **Open questions** in the report
-- Do **not** invent user stories or research conclusions
-
----
-
-## Related
-
-- [review-checklist.md](./review-checklist.md)
-- [kuat-review/SKILL.md](../../../../skills/kuat-review/SKILL.md)
-- [content/product-content.md](./content/product-content.md)

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

@@ -1,82 +0,0 @@
-# Product Scenarios
-
-Applied layout and design patterns for web application page types.
-
-Each scenario combines foundational rules and web product rules into actionable guidance for building complete pages.
-
----
-
-## When to Use Scenarios
-
-Load a scenario guide when:
-
-- Building a specific page type (login, dashboard, settings)
-- Need composition guidance beyond foundational design rules
-- Want consistent patterns for common UI challenges
-
----
-
-## Available Scenarios
-
-| Scenario | Use 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 |
-
----
-
-## Scenario Structure
-
-Each scenario file follows a consistent structure:
-
-| Section | Purpose |
-|---------|---------|
-| **Principles** | Core UX principles, user goals, success metrics |
-| **Layout** | Which base layout to use, page structure, regions |
-| **Design** | Color tokens, typography, spacing, components |
-| **Content** | Content hierarchy, microcopy, error messaging |
-| **Accessibility** | Scenario-specific a11y requirements (references base docs) |
-| **Implementation** | Component composition, state patterns, responsive behavior |
-| **Best Practices** | Do's/Don'ts, common mistakes, edge cases |
-
----
-
-## How Scenarios Reference Foundations
-
-Scenarios build on foundational documentation:
-
-```
-┌─────────────────────────────────────────┐
-│             SCENARIOS                   │
-│  (authentication, dashboards, etc.)     │
-├─────────────────────────────────────────┤
-│  References:                            │
-│  ├── rules/foundations/*                │
-│  ├── rules/types/web/product/design.md  │
-│  ├── rules/types/web/product/           │
-│  │   accessibility.md                   │
-│  └── rules/foundations/accessibility.md│
-└─────────────────────────────────────────┘
-```
-
----
-
-## For AI Agents
-
-When building a specific page type:
-
-1. Load the relevant scenario file
-2. Follow the recommended base layout from product design rules
-3. Reference accessibility requirements from foundations and web accessibility docs
-4. Use design tokens from foundations colours and typography
-
----
-
-## Related Documentation
-
-- [Product Design](../design.md) - Layout patterns
-- [Product Accessibility](../accessibility.md) - Technical implementation
-- [Foundations Accessibility](../../../../foundations/accessibility.md) - Principles
-- [Foundations](../../../../foundations/) - Brand design rules