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

package/README.md

@@ -53,23 +53,34 @@ Add this to your project `AGENTS.md` (or `.cursorrules`) so agent workflows stay
 ### Peer dependencies
 
 Install peers for the components you use before running `dev` or `build`.
+`react`/`react-dom` are always required. Embla (carousel) and Sonner ship as
+bundled dependencies, so you don't install those.
 
-| Components you use | Required peers |
+| Components you use | Peers to install |
 |---|---|
-| `Button`, `KuatHeader` | `@radix-ui/react-slot`, `lucide-react` |
-| `Accordion` | `@radix-ui/react-accordion` |
+| `Button`, `ButtonGroup`, `IconButton` | `@radix-ui/react-slot` |
+| `Accordion` | `@radix-ui/react-accordion`, `lucide-react` |
 | `AlertDialog` | `@radix-ui/react-alert-dialog` |
-| `Select` / `KuatSelect` | `@radix-ui/react-select`, `@radix-ui/react-separator` |
-| `Checkbox` / `CheckboxField` | `@radix-ui/react-checkbox` |
-| `RadioGroup` / `RadioField` | `@radix-ui/react-radio-group` |
+| `Select` | `@radix-ui/react-select`, `lucide-react` |
+| `DropdownMenu` | `@radix-ui/react-dropdown-menu`, `lucide-react` |
+| `Checkbox` / `CheckboxField` | `@radix-ui/react-checkbox`, `lucide-react` |
+| `Radio` / `RadioField` | `@radix-ui/react-radio-group` |
 | `Switch` / `SwitchField` | `@radix-ui/react-switch` |
-| `Toggle` / `ToggleGroup` | `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group` |
-| `Sonner` | `sonner` |
+| `Toggle`, `ToggleGroup` | `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group` |
+| `Separator` | `@radix-ui/react-separator` |
+| `Carousel`, `KuatCarousel` | `lucide-react` |
+| `Breadcrumb`, `KuatHeader` | `lucide-react` |
+| `Sonner` | — (bundled, no peer to install) |
+| `Badge`, `Field`, `Input`, `Textarea`, `ContentCard`, `KuatRadialProgress` | none |
+
+> **Tip:** if you use the Kuat agent plugin in Claude Code, run
+> `/kuat-add <component>` to add a component and install its peers automatically,
+> instead of wiring the table above by hand.
 
 Example peer install for a broad setup:
 
 ```bash
-pnpm add @radix-ui/react-slot @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-switch @radix-ui/react-toggle @radix-ui/react-toggle-group lucide-react sonner
+pnpm add @radix-ui/react-slot @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-select @radix-ui/react-dropdown-menu @radix-ui/react-separator @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-switch @radix-ui/react-toggle @radix-ui/react-toggle-group lucide-react
 ```
 
 ---
@@ -124,63 +135,52 @@ import { KuatCarousel } from '@equal-experts/kuat-react/kuat-carousel';
 
 ## Recommended setup
 
-### 1. Tailwind
-
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import kuatPreset from '@equal-experts/kuat-core';
-
-export default {
-  presets: [kuatPreset],
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@equal-experts/kuat-react/**/*.{js,ts,jsx,tsx}',
-  ],
-} satisfies Config;
-```
-
-### 2. Tailwind runtime stylesheet (required for Tailwind v4)
+### 1. Tailwind v4 + Kuat tokens (CSS-first)
 
-Create a global stylesheet and load Tailwind:
+Add the Tailwind v4 plugin to your build (e.g. `@tailwindcss/vite`), then create
+a global stylesheet that imports Tailwind and the Kuat tokens. The tokens must
+be pulled in **through Tailwind** (a CSS `@import`) so the `@theme` block in
+`variables.css` is processed and the token utilities (`bg-primary`,
+`text-foreground`, `rounded-lg`, …) are generated:
 
 ```css
-/* src/tailwind.css */
+/* src/index.css */
+@import "@equal-experts/kuat-core/fonts.css"; /* fonts; or a <link> — see kuat-core README */
 @import "tailwindcss";
+@import "@equal-experts/kuat-core/variables.css";
 ```
 
-### 3. Design tokens and Kuat styles (once per app entrypoint)
+> A plain JS `import "@equal-experts/kuat-core/variables.css"` loads the raw
+> variables but does **not** feed the `@theme` block to Tailwind, so the token
+> utilities never generate (with no error). Always `@import` the tokens through
+> Tailwind, as above.
+>
+> The legacy JS preset (`presets: [kuatPreset]`) is **deprecated** and is not
+> auto-loaded by Tailwind v4 — don't use it. See the kuat-core README.
+
+### 2. Component styles (once per app entrypoint)
+
+Kuat component CSS is pre-compiled, so a JS import is correct here:
 
 ```typescript
 // main.tsx
-import '@equal-experts/kuat-core/variables.css';
-import '@equal-experts/kuat-react/styles';
-import './tailwind.css';
-import './app.css';
+import '@equal-experts/kuat-react/styles'; // pre-compiled component CSS
+import './index.css';                       // Tailwind + Kuat tokens (from step 1)
+import './app.css';                          // your app styles, last
 ```
 
-Import order matters: load Kuat tokens and Kuat styles before app-specific styles.
+Import order matters: load Kuat styles before app-specific styles.
 
 If you scaffolded from a starter template (for example Vite), remove or neutralize template CSS that resets fonts/layout globally (for example `src/index.css` with `:root { font: ... }`, `body { ... }`, `#root { ... }`). These rules can override Kuat typography and spacing.
 
-Typical cleanup for a smoke setup:
-
-```typescript
-// Keep in main.tsx
-import '@equal-experts/kuat-core/variables.css';
-import '@equal-experts/kuat-react/styles';
-import './tailwind.css';
-// Remove template global CSS import if it overrides root/body fonts or layout
-```
-
-### 4. shadcn for gaps only
+### 3. shadcn for gaps only
 
 ```bash
 npx shadcn@latest init
 npx shadcn@latest add dialog dropdown-menu   # examples — skip `button` if you use Kuat Button
 ```
 
-### 5. Use Kuat + shadcn together
+### 4. Use Kuat + shadcn together
 
 ```tsx
 import { Button, ButtonGroup, Field } from '@equal-experts/kuat-react';
@@ -242,7 +242,7 @@ Use this quick smoke test after installation to verify imports, styles, and Tail
 ### 1. Add a smoke component
 
 ```tsx
-import { Button, Field, KuatCarousel, KuatCarouselContent, KuatCarouselItem } from '@equal-experts/kuat-react';
+import { Button, Field, FieldLabel, Input, KuatCarousel, KuatCarouselContent, KuatCarouselItem } from '@equal-experts/kuat-react';
 
 export function KuatInstallSmoke() {
   return (
@@ -250,8 +250,8 @@ export function KuatInstallSmoke() {
       <h1 className="text-4xl font-bold">Kuat install smoke test</h1>
 
       <Field>
-        <label htmlFor="name">Name</label>
-        <input id="name" placeholder="Test input" />
+        <FieldLabel htmlFor="name">Name</FieldLabel>
+        <Input id="name" placeholder="Test input" />
       </Field>
 
       <Button variant="primary">Primary action</Button>

package/agent-docs/AGENTS.md

@@ -4,7 +4,7 @@ Rules for this install live under `agent-docs/` in `@equal-experts/kuat-core`, `
 
 1. Run `ensure-rules.sh` from kuat-agent-docs skills (symlinked) — expect `RULES_SOURCE=package` when cwd has node_modules.
 2. Load `agent-docs/rules/LOADING-consumer.md`.
-3. Load component guides via `agent-docs/components.manifest.json`.
+3. Load component guides via `agent-docs/components/components.manifest.json`.
 4. Skills: `kuat-review`, `kuat-create` from [kuat-agent-docs](https://github.com/equalexperts/kuat-agent-docs).
 
-**Version:** 0.13.1 · **Rules snapshot:** 67fc215fe87c
+**Version:** 0.14.0-beta.1 · **Rules snapshot:** cb073bf5a888

package/agent-docs/README.md

@@ -14,4 +14,4 @@ Curated agent docs bundled with `@equal-experts/kuat-core`, `@equal-experts/kuat
 node scripts/agent-docs/bundle-for-core.mjs
 ```
 
-Built against upstream ref: `67fc215fe87c`
+Built against upstream ref: `cb073bf5a888`

package/agent-docs/bundle-manifest.json

@@ -18,36 +18,28 @@
       "target": "components"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/foundations/brand.md",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/foundations/brand.md"
+      "source": "external/kuat-agent-rules/reference/brand",
+      "target": "external/kuat-agent-rules/reference/brand"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/foundations/accessibility.md",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/foundations/accessibility.md"
+      "source": "external/kuat-agent-rules/reference/accessibility",
+      "target": "external/kuat-agent-rules/reference/accessibility"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/LOADING.md",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/LOADING.md"
+      "source": "external/kuat-agent-rules/reference/design-language",
+      "target": "external/kuat-agent-rules/reference/design-language"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/foundations/design",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/foundations/design"
+      "source": "external/kuat-agent-rules/reference/content",
+      "target": "external/kuat-agent-rules/reference/content"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/foundations/content",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/foundations/content"
+      "source": "external/kuat-agent-rules/reference/media-types/web-product",
+      "target": "external/kuat-agent-rules/reference/media-types/web-product"
     },
     {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/foundations/logo.md",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/foundations/logo.md"
-    },
-    {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/types/web/product",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/types/web/product"
-    },
-    {
-      "source": "external/kuat-agent-rules/kuat-docs/rules/types/web/marketing",
-      "target": "external/kuat-agent-rules/kuat-docs/rules/types/web/marketing"
+      "source": "external/kuat-agent-rules/reference/media-types/web-marketing",
+      "target": "external/kuat-agent-rules/reference/media-types/web-marketing"
     }
   ],
   "denyPathSegments": [

package/agent-docs/components/components.manifest.json

@@ -3,16 +3,19 @@
   "components": {
     "shadcn:button": {
       "slug": "button",
+      "displayName": "Button",
       "path": "components/button.md",
       "sources": ["shadcn:button", "@equal-experts/kuat-core"]
     },
     "kuat:button-group": {
       "slug": "button-group",
+      "displayName": "ButtonGroup",
       "path": "components/button-group.md",
       "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
     },
     "kuat:kuat-header": {
       "slug": "kuat-header",
+      "displayName": "KuatHeader",
       "path": "components/kuat-header.md",
       "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
     }

package/agent-docs/external/kuat-agent-rules/reference/accessibility/README.md

@@ -0,0 +1,7 @@
+# Accessibility
+
+Equal Experts accessibility standards, applied across every medium.
+
+| File | Scope |
+|------|-------|
+| [accessibility.md](./accessibility.md) | WCAG 2.2 AA standards: contrast, focus, semantics, alt text |

package/agent-docs/external/kuat-agent-rules/{kuat-docs/rules/foundations → reference/accessibility}/accessibility.md

@@ -1,7 +1,3 @@
----
-scope: general
----
-
 # Accessibility
 
 Foundational accessibility requirements for Equal Experts content and products. These rules ensure products and services deliver the best experience for all users.
@@ -371,11 +367,17 @@ Always spell out abbreviations on first use:
 
 ## Inclusive Language
 
+Inclusive language is part of how Equal Experts writes — it helps us be accurate and build trust. Around 16% of people worldwide experience some form of disability, so it matters that we don't unintentionally exclude anyone from accessing or understanding our work. This section is the authoritative source for inclusive word choices across all content; the [writing style](../content/writing-style.md) guidance links here.
+
 ### Guidelines
 
 - Use language that is respectful and free of bias
-- Avoid exclusionary terms or outdated phrases
-- Consider diverse audiences and perspectives
+- Avoid terms that contribute to stigmas around disability or mental illness
+- Make content **gender-neutral** wherever possible, and avoid words and phrases that indicate gender bias
+- Avoid words, images, or situations that reinforce racial, ethnic, or religious stereotypes
+- Be considerate with computer and software terminology such as "master", "slave", and "blacklist" — prefer neutral alternatives (for example "main", "primary/replica", "blocklist")
+- Avoid assumptions: when including someone in a piece of content, ask how they'd like to be identified
+- Avoid idioms where possible, or make sure they're clearly explained — they don't always translate across cultures or for non-native readers
 - When in doubt, research current preferred terminology
 
 ### Person-First Language
@@ -438,7 +440,7 @@ Always spell out abbreviations on first use:
 
 ## Related Documentation
 
-- [Colours](./design/colours.md) - Brand colour palette and contrast
-- [Typography](./design/typography.md) - Font families and type scale
-- [Content](./content/README.md) - Writing style and tone
-- [Web Technical Accessibility](../types/web/product/accessibility.md) - Implementation details
+- [Colours](../design-language/colours.md) - Brand colour palette and contrast
+- [Typography](../design-language/typography.md) - Font families and type scale
+- [Writing style](../content/writing-style.md) - Writing style and tone
+- [Web Technical Accessibility](../media-types/web-product/accessibility.md) - Implementation details

package/agent-docs/external/kuat-agent-rules/reference/brand/README.md

@@ -0,0 +1,9 @@
+# Brand
+
+Equal Experts brand identity: who EE is and how the brand expresses itself.
+
+| File | Scope |
+|------|-------|
+| [brand.md](./brand.md) | Brand principles and identity |
+| [logo.md](./logo.md) | Logo variants, sizing, placement, clear space |
+| [voice-and-tone.md](./voice-and-tone.md) | Voice, tone, audience, content quality |

package/agent-docs/external/kuat-agent-rules/{kuat-docs/rules/foundations → reference/brand}/brand.md

@@ -18,21 +18,31 @@ Equal Experts is a network of experienced software consultants, helping organisa
 
 ## Brand Values
 
-### 1. Expertise Through Experience
+The Equal Experts values act as principles of how we work with our customers. They are intended to give all members of the network autonomy in making decisions that are aligned with the way we want to behave, as well as how we want to be recognised.
 
-We hire only experienced consultants. Our expertise comes from years of hands-on work, not certifications or titles.
+### 1. We deliver as teams of equals
 
-### 2. Equality and Collaboration
+Teams are greater than the sum of their parts. No matter what role people play in a team, they all have something to contribute, and they all have a voice in delivery decisions.
 
-Everyone is equal. We work alongside clients as partners, not vendors. No account managers, no hierarchy - just experts working together.
+### 2. We prioritise outcomes over approach
 
-### 3. Honesty and Transparency
+We work in complex and highly dynamic environments. We’re not interested in a cookie-cutter approach.
 
-We tell clients what they need to hear, not what they want to hear. We're direct about risks, challenges, and realistic outcomes.
+### 3. We narrow our focus but widen our context
 
-### 4. Pragmatism Over Perfection
+We deliver concrete value as early as possible by quickly identifying key opportunities, but framing them within the wider organisational context.
 
-We focus on delivering value, not following processes for their own sake. We choose practical solutions that work in the real world.
+### 4. We bring step-by-step change
+
+It can be tempting to look for a WOW factor, but we know that lasting change is best achieved through small, incremental practices that build towards larger transformation.
+
+### 5. We have a passion for learning over knowing all the answers
+
+We may be experts, but we don’t pretend to know all the answers.
+
+### 6. We seek customer success over our own short-term interests
+
+We thrive by our reputation, so the only way to guarantee our future success is to do what’s right, right now, for our customers.
 
 ---
 
@@ -94,6 +104,6 @@ When representing Equal Experts:
 ## Related Documentation
 
 - [Logo Usage](./logo.md) - Logo variants, sizing, placement
-- [Colours](./design/colours.md) - Brand color palette
-- [Typography](./design/typography.md) - Brand fonts
-- [Content](./content/README.md) - Writing style and tone
+- [Colours](../design-language/colours.md) - Brand color palette
+- [Typography](../design-language/typography.md) - Brand fonts
+- [Reference index](../README.md) - All brand reference guides

package/agent-docs/external/kuat-agent-rules/{kuat-docs/rules/foundations → reference/brand}/logo.md

@@ -121,9 +121,10 @@ The brand mark (without wordmark) should only be used when:
 
 For platform-specific logo placement guidance:
 
-- **Web layouts** - See [types/web/](../types/web/)
-- **Slides** - See [types/slides/](../types/slides/)
-- **Graphics** - See [types/graphics/](../types/graphics/)
+- **Web product** - See [media-types/web-product/](../media-types/web-product/)
+- **Web marketing** - See [media-types/web-marketing/](../media-types/web-marketing/)
+- **Slides** - See [media-types/slides/](../media-types/slides/)
+- **Graphics** - See [media-types/imagery/patterns/graphics/](../media-types/imagery/patterns/graphics/)
 
 ---
 
@@ -148,4 +149,4 @@ All logos are available in the [Equal Experts brand-assets repository](https://g
 ## Related Documentation
 
 - [Brand Guidelines](./brand.md) - Brand principles
-- [Colours](./design/colours.md) - Brand color palette
+- [Colours](../design-language/colours.md) - Brand color palette

package/agent-docs/external/kuat-agent-rules/reference/brand/voice-and-tone.md

@@ -0,0 +1,166 @@
+# Voice and Tone
+
+Universal voice and tone for Equal Experts content. Applies to all platforms and media.
+
+---
+
+## Overview
+
+It's not just *what* we say but *how* we say it that matters. A consistent voice — aligned with our vision, mission, and values — helps us speak to our audience clearly, reflects our culture, and differentiates us from the competition. If the voice isn't reflective of Equal Experts, our work, and our values, we risk key messages being misunderstood or overlooked.
+
+Our **voice** is constant: it's who we are. Our **tone** flexes to suit the audience, channel, and purpose.
+
+---
+
+## Quick Reference
+
+**Always:**
+- Be friendly, clear, and approachable — one human to another
+- Be confident, but never arrogant; back claims with evidence
+- Focus on the audience and their needs
+- Use plain language; be specific, not vague
+- Be consistent across channels and materials
+
+**Never:**
+- Make bold claims without backing them up
+- Hide behind jargon, acronyms, or buzzwords
+- Talk down to, over-simplify for, or patronise the audience
+- Overuse "we" so the content reads as boastful
+- Mix and match tones and styles within a piece
+
+---
+
+## How We Describe Equal Experts
+
+Equal Experts is a global network of technology shapers. We work collaboratively with clients on digital initiatives that deliver long-lasting change and pragmatic innovation. Engaging around 3,000 consultants across five continents, we help solve complex business problems and create leading digital products and services. We decide with data, design for users, deliver at pace, and scale sustainably.
+
+What makes us unique: we engage only senior consultants (averaging around 18 years' experience), we're low-ego and curious, we're vendor-agnostic and don't offer cookie-cutter solutions, and our flexible global delivery model means we're not limited by geography.
+
+---
+
+## Writing in the Equal Experts Voice
+
+**Friendly, clear, and approachable.** We speak from one human to another. Though we work with cutting-edge technology, we're not robots and neither are our customers. Content is clear, concise, and purposeful, but reflects how we'd speak face-to-face. Gentle humour is welcome when it arises naturally, is appropriate, and will be widely understood.
+
+**Confident, but never arrogant.** With a word as powerful as "expert" in our name, we embody it with humility. We show our knowledge through tangible results and a passion for learning. We're confident without being condescending, and knowledgeable without being know-it-alls.
+
+**Focused on the audience.** Our voice adapts to different audiences, channels, and platforms. When we talk about technology, we consider the audience and don't cloud the message with terminology, acronyms, or phrases they're unlikely to understand. We're not dumbing down or patronising — we're meeting the audience where they are.
+
+**Genuine, and a team of equals.** Our voice instils trust in our work and our people. We speak positively about our customers — past and present — emphasising collaboration, transparency, and honesty. We voice our opinions but stay open to compromise for the good of the client or team. We're considerate and intentional with our words, paying close attention to inclusivity and accessibility.
+
+---
+
+## Adapting Tone for the Audience
+
+The Equal Experts voice flexes to the audience and content type. Internal audiences allow a more informal, conversational tone with more room for humour; sales materials dial up confident, persuasive language.
+
+| Audience / channel | Tone |
+|--------------------|------|
+| Case studies (external) | Straightforward and factual, with a focus on storytelling, client collaboration, and results |
+| Blogs (external & internal) | Purposeful and informative, letting the author's personality shine through; answer the audience's questions |
+| Playbooks & informative content | Clear and informative, with evidence-based insights and examples; a strong expert tone |
+| Pitch decks & sales materials | Confident, authoritative, persuasive; definitive statements about our work and impact, always backed by results |
+| Social media | Conversational, friendly, and informal; often addressed to the audience |
+| Internal Blogin & Slack | Friendly, approachable, reflecting the author's personality. Remember NDAs |
+| Knowledge Portal | Deeper, less-polished opinions and insights, useful for the network but not for external view. Remember NDAs |
+
+We don't adapt the tone in a way that compromises our values, and we always read as professional, reliable experts who deliver results.
+
+---
+
+## Content Principles
+
+These principles underpin all our content, from planning to maintenance.
+
+1. **Always be human.** We're humans talking to humans — simple, authentic, and genuine, with personality and humour where it suits.
+2. **Have a clear purpose.** Set the aim, audience, and the goal it serves before you start. What question does this piece answer?
+3. **Know who your audience is.** Understand their situation, behaviours, attitudes, problems, and goals.
+4. **Be clear and concise.** Plain English, the best chance of being read and understood. Don't use ten words when three will do.
+5. **Collaborate with others.** Draw on people with the right skills at the right point in the process.
+6. **Test, iterate, and learn.** Try new content, improve it on feedback and evidence, and share what you learn across the network.
+
+---
+
+## Top Tips
+
+- **Write for all readers.** Some read every word; others skim. Descriptive headers, subheaders, lists, and diagrams help people find what they need
+- **Lead with the key message.** Open with the main or most interesting point, then back it up
+- **Use the active voice.** "We reviewed the code", not "The code was reviewed by Equal Experts"
+- **Be clear, concise, and specific.** Plain English, no slang, no unnecessary jargon or acronyms; don't assume prior knowledge
+- **Write like a human.** Being an expert means removing complexity — be relatable, warm, and friendly
+- **Adapt to the audience.** Suit the situation, the reader, and the subject
+- **Don't "we" all over the content.** Too much "we" reads as boastful; emphasise the client and the collaboration
+- **Be consistent.** Apply the same standards and style throughout; don't mix tones
+
+---
+
+## UK English and Local Markets
+
+We focus on **UK English** for global content, but respect local markets — Australia, the US, Europe, South Africa, and India — where appropriate, adopting local spelling, grammar, and currency in location-specific content.
+
+---
+
+## Audience Considerations
+
+### Technical audiences (developers, engineers)
+
+**Tone:** Pragmatic, evidence-based, respectful of expertise. Use specific technical detail, code examples, and trade-offs. Avoid over-simplification, buzzwords, and marketing language.
+
+### Business stakeholders (product owners, leaders)
+
+**Tone:** Outcome-focused, clear, strategic. Use business metrics, efficiency gains, and impact. Avoid deep technical detail without context and unexplained acronyms.
+
+### General audiences
+
+**Tone:** Helpful, clear, accessible. Use plain language, clear explanations, and practical examples. Avoid corporate speak and jargon.
+
+---
+
+## Common Pitfalls
+
+### Buzzword bingo
+Trendy terminology without substance.
+
+❌ "Leveraging synergistic, AI-enabled solutions"  
+✅ "We automated invoice processing using existing APIs"
+
+### Unbacked claims
+Bold statements without evidence.
+
+❌ "We'll dramatically improve your performance"  
+✅ "The health check saved the client £3 million"
+
+### Over-explanation
+Explaining what needs no explanation.
+
+❌ "Click the button below to continue to the next screen"  
+✅ [Continue]
+
+---
+
+## Content Quality Checklist
+
+- **Clarity:** Can it be understood from a 30-second skim?
+- **Purpose:** Does it answer a specific question or solve a problem?
+- **Consistency:** Does it use consistent terminology and patterns?
+- **Audience:** Is it pitched right for the intended reader?
+- **Accessibility:** Does it work for everyone, including assistive-technology users?
+
+---
+
+## Platform-Specific Content
+
+For platform-specific content guidance:
+
+- **Web Marketing** - See [media-types/web-marketing/](../media-types/web-marketing/)
+- **Web Product** - See [media-types/web-product/](../media-types/web-product/)
+- **Slides** - See [media-types/slides/](../media-types/slides/)
+
+---
+
+## Related Documentation
+
+- [Brand Guidelines](./brand.md) - Brand voice and values
+- [Writing style](../content/writing-style.md) - Active voice, plain language, conventions
+- [Inclusive language](../accessibility/accessibility.md#inclusive-language) - Accessible, bias-free word choices
+- [Design language](../design-language/design-language.md) - Visual design principles

package/agent-docs/external/kuat-agent-rules/reference/content/README.md

@@ -0,0 +1,12 @@
+# Content
+
+How Equal Experts writes — style and usage conventions that apply across every medium. (Voice and tone lives in [brand/](../brand/voice-and-tone.md).)
+
+| File | Scope |
+|------|-------|
+| [writing-style.md](./writing-style.md) | Active voice, plain language, conciseness |
+| [formatting.md](./formatting.md) | Capitalisation, headings, links, lists, acronyms |
+| [numbers.md](./numbers.md) | Dates, times, currency, percentages, units |
+| [punctuation.md](./punctuation.md) | Commas, dashes, apostrophes, quotation marks |
+
+Inclusive, bias-free word choices live in [accessibility/](../accessibility/accessibility.md#inclusive-language) and are cross-linked from [writing-style.md](./writing-style.md).