@equal-experts/kuat-vue 0.13.0 → 0.14.0-beta.0

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

@@ -0,0 +1,94 @@
+# Punctuation
+
+Guidance for commas, dashes, apostrophes, and other punctuation in Equal Experts content.
+
+---
+
+## Quick Reference
+
+- **Commas:** We don't use the serial (Oxford) comma unless it's needed to clarify meaning
+- **Dashes:** Use a spaced en dash ( – ) to offset a phrase; an unspaced en dash for ranges (40–60)
+- **Apostrophes:** Use for possessives and contractions; don't use for plurals
+- **Ampersands and plus:** Spell out "and" unless "&" or "+" is part of an official name
+- **Slashes:** Avoid; replace with words or commas
+- **End marks:** Use one — and only one — full stop, exclamation mark, or question mark per sentence
+- **Spaces:** A single space between sentences, never two
+
+---
+
+## Commas
+
+- We **don't use the serial comma** (sometimes called the Oxford comma) unless it's needed to clarify meaning: "Our design service includes user experience, prototyping, content design and user testing."
+- Use the serial comma only to remove ambiguity: "You can meet Janet, a clown and an acrobat" is unclear — add a comma if Janet is not herself the clown and acrobat
+- Use commas to set off non-essential clauses
+- Don't join two independent clauses with only a comma (use a full stop, semicolon, or conjunction)
+
+---
+
+## Dashes and Hyphens
+
+- **En dash to offset a phrase (–):** When offsetting a phrase or aside, use the en dash with a **space on either side**: "Creating paved roads – build and run journeys that support secure deployment – can help reduce infrastructure complexity."
+- **En dash for ranges (–):** Use **unspaced** for ranges: "40–60%", "March–May", "1914–18", "2020–21"
+- **"from … to" not a dash:** When you use "from" with a start point, pair it with "to" rather than a dash: "from October to December"
+- **Hyphen (-):** Use in compound modifiers before a noun: "well-known result", "up-to-date report". Don't hyphenate when the modifier follows the noun: "the result is well known"
+- Equal Experts prefers the spaced en dash over the em dash (—) for breaks and asides.
+
+---
+
+## Apostrophes
+
+- **Possessives:** Add 's for singular (team's, user's); add ' for a plural already ending in s (users', teams')
+- **Contractions:** Use for standard contractions (don't, it's, we're)
+- **Plurals:** Don't use an apostrophe for plurals: "1990s" not "1990's"; "APIs" not "API's"
+
+---
+
+## Ampersands and Plus Symbols
+
+- Use "&" and "+" **only** when they're part of an official title or name: "Johnson & Johnson"
+- Otherwise spell out "and": "artificial intelligence and machine learning", not "AI & ML"
+
+---
+
+## Slashes
+
+- Avoid the slash (/). Replace it with words or commas as appropriate
+- A slash is often ambiguous: "the designer/researcher" — is that one person or two?
+
+---
+
+## Colons and Semicolons
+
+- **Colon:** Use to introduce a list or an explanation that follows from the main clause. **Don't capitalise** the first word after a colon (unless it's a proper noun). One space after a colon: "I encountered two issues: compliance and security."
+- **Semicolon:** Use to link closely related independent clauses, or to separate list items that already contain commas. Use sparingly; often a full stop is clearer.
+
+---
+
+## End Marks
+
+- Use one — but only one — full stop, exclamation mark, or question mark at the end of every sentence
+- Separate sentences with a **single space**, never two
+
+---
+
+## Quotation Marks
+
+- Use **double speech marks** (" ") for direct speech and short quoted phrases
+- Put punctuation that belongs to the quote **inside** the closing marks; punctuation that applies to the whole sentence goes outside
+- **Attribute every quote** to someone, even if anonymised: "…Always there, always on, and always thinking." — Eric Wilson, CEO, Xinja. / "…I can't imagine how much further down the track a go-live like this could be." — CEO, US retail customer
+- Use an **ellipsis (…)** to show where a quote has been shortened, and **square brackets** to clarify unclear elements: "[Equal Experts] have been with us every step of the way… Always there, always on, and always thinking."
+
+---
+
+## Exclamation Marks
+
+- Use rarely; reserve for genuine emphasis or a short, positive confirmation
+- One exclamation mark is enough; never use multiple (!!)
+
+---
+
+## Related Documentation
+
+- [Writing style](./writing-style.md)
+- [Formatting](./formatting.md)
+- [Numbers](./numbers.md) - Ranges, financial years, "from … to"

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

@@ -0,0 +1,96 @@
+# Writing Style
+
+Style and usage principles for Equal Experts content. Be clear, precise, and conversational.
+
+---
+
+## Quick Reference
+
+**Do:**
+- Use active voice
+- Use everyday contractions (we're, it's, don't)
+- Use simple verb tenses (present, past; avoid unnecessary future or perfect)
+- Address the reader as "you"
+- Prefer short sentences
+
+**Don't:**
+- Use passive voice when active is clearer
+- Use formal or stiff phrasing
+- Over-qualify with "in order to", "in the event that"
+- Use jargon without explanation
+
+---
+
+## Active Voice
+
+Prefer the subject doing the action. It's clearer and more direct.
+
+| Prefer | Avoid |
+|--------|--------|
+| The team delivered the project on time | The project was delivered on time by the team |
+| You can save your work here | Work can be saved here |
+| We recommend testing first | It is recommended that testing be performed first |
+
+Use passive only when the actor is unknown or irrelevant, or when you want to emphasise the action over the subject: "The health check saved the client £3 million."
+
+---
+
+## Plain Language
+
+- Use common words instead of formal or obscure ones
+- Prefer short words where they carry the same meaning
+- Explain technical terms on first use
+
+| Prefer | Avoid |
+|--------|--------|
+| use | utilise |
+| help | facilitate |
+| about | with regard to |
+| if | in the event that |
+| before | prior to (when "before" works) |
+
+---
+
+## Contractions
+
+Use everyday contractions so content sounds natural and approachable.
+
+- we're, it's, don't, can't, you'll, that's
+- Avoid overly formal "we have not", "do not" in body copy unless tone requires it (e.g. legal, formal notices)
+
+---
+
+## Verb Tenses
+
+- Use **present** for general truth and instructions: "The dashboard shows recent activity."
+- Use **past** for what happened: "The deployment completed successfully."
+- Use **future** only when necessary: "You will receive a confirmation email."
+- Avoid unnecessary perfect tenses when simple past or present is clearer.
+
+---
+
+## Conciseness
+
+- Cut filler: "Please note that" → often delete; "at this time" → "now" or "currently"
+- One main idea per sentence where possible
+- Start with the most important information
+
+---
+
+## Addressing the Reader
+
+- Speak to the reader as **"you"**
+- Use **"we"** for Equal Experts when it's clear from context
+- Keep "my" vs "your" consistent with the product (e.g. "your account" in product UI)
+
+### Don't "we" all over the content
+
+Describing ourselves as "we" humanises the brand, but using it too often can read as boastful or insincere — especially when we want to emphasise the client, their input, and the collaboration. Balance "we" with the customer's perspective.
+
+---
+
+## Related Documentation
+
+- [Voice and tone](../brand/voice-and-tone.md) - Principles and audience
+- [Formatting](./formatting.md) - Capitalisation, headings, lists
+- [Inclusive language](../accessibility/accessibility.md#inclusive-language) - Accessible, bias-free word choices

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

@@ -0,0 +1,11 @@
+# Design Language
+
+Visual design language for Equal Experts — the tokens and principles that apply across every medium.
+
+| File | Scope |
+|------|-------|
+| [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 |

package/agent-docs/external/kuat-agent-rules/reference/design-language/borders.md

@@ -0,0 +1,160 @@
+# Border Rules
+
+Border specifications for Equal Experts. This document defines border philosophy, widths, radius, and usage guidelines.
+
+---
+
+## Overview
+
+The design system follows a **minimal border philosophy** - borders should only be used when necessary. Prefer spacing and visual hierarchy over borders.
+
+**Key Principle:** Use borders sparingly and purposefully. Spacing and visual hierarchy should be the primary tools for creating separation.
+
+---
+
+## When to Use Borders
+
+### Use Borders For:
+
+1. **Creating separation** between distinct sections needing clear boundaries
+2. **Distinguishing interactive elements** from static content
+3. **Defining component boundaries** where spacing alone is insufficient
+4. **Indicating state changes** (focus states, error states, selection)
+
+### Avoid Borders When:
+
+- Spacing alone can create sufficient separation
+- Visual hierarchy (size, color, weight) can distinguish elements
+- The border would create visual clutter
+- Separation is already clear through other design elements
+
+---
+
+## Border Width
+
+Borders should be **1-4px** in width:
+
+| Width | Usage |
+|-------|-------|
+| 1px | Default for most elements (cards, dividers) |
+| 2px | Emphasized borders, active states |
+| 3-4px | Focus indicators, high-contrast separations |
+
+---
+
+## Border Style
+
+**Always use solid lines.**
+
+The design system does not use:
+- Dashed borders
+- Dotted borders
+- Other border styles
+
+---
+
+## Border Color
+
+Use brand-appropriate colors:
+
+| Usage | Color |
+|-------|-------|
+| Default borders | Light gray (slate-200 light, slate-700 dark) |
+| Focus indicators | EE Blue or appropriate focus color |
+| Error states | Red/destructive color |
+| Success states | Transform Teal |
+
+---
+
+## Border Radius
+
+The design system uses a **minimal radius approach**:
+
+### Default: 0px (No Radius)
+
+Most elements have **no border radius** by default for a clean, modern, geometric aesthetic.
+
+**Elements with no radius:**
+- Static containers
+- Sections
+- Dividers
+- Content blocks
+
+### Interactive Elements: 6px
+
+**Interactive elements** use **6px border radius**:
+
+- Buttons
+- Clickable cards
+- Interactive tiles
+- Tabs
+
+### Form Inputs: 4px
+
+**Form input elements** use **4px border radius**:
+
+- Text inputs
+- Textareas
+- Select dropdowns
+- Search inputs
+
+### Summary
+
+| Element Type | Border Radius |
+|--------------|---------------|
+| Static content | 0px |
+| Interactive elements | 6px |
+| Form inputs | 4px |
+
+---
+
+## Accessibility
+
+### Contrast Requirements
+
+Borders must meet WCAG 2.1 Level AA for graphical objects:
+
+- **Minimum contrast ratio:** 3:1 against adjacent colors
+
+### Testing
+
+- Test borders against background colors
+- Verify visibility in both light and dark contexts
+- Ensure sufficient contrast for all users
+
+---
+
+## Usage Guidelines
+
+### Do's
+
+1. **Use borders purposefully** - Only when spacing is insufficient
+2. **Follow width guidelines** - 1px default, 2px emphasized, 3-4px focus
+3. **Apply radius correctly** - 0px static, 6px interactive, 4px inputs
+4. **Ensure accessibility** - 3:1 minimum contrast ratio
+5. **Be consistent** - Same border treatment for same element types
+
+### Don'ts
+
+1. **Don't overuse borders** - Spacing should be the first option
+2. **Don't use non-solid borders** - No dashed or dotted
+3. **Don't use arbitrary radius** - Only 0px, 4px, or 6px
+4. **Don't break accessibility** - Always verify contrast
+5. **Don't use decorative borders** - Keep them functional
+
+---
+
+## Platform-Specific Borders
+
+For platform-specific border guidance:
+
+- **Web product** - See [media-types/web-product/](../media-types/web-product/)
+- **Web marketing** - See [media-types/web-marketing/](../media-types/web-marketing/)
+- **Graphics** - See [media-types/imagery/patterns/graphics/](../media-types/imagery/patterns/graphics/)
+
+---
+
+## Related Documentation
+
+- [Spacing](./spacing.md) - Spacing as alternative to borders
+- [Colours](./colours.md) - Border colors

package/agent-docs/external/kuat-agent-rules/reference/design-language/colours.md

@@ -0,0 +1,201 @@
+# Colour Rules
+
+<!-- GENERATED FILE — DO NOT EDIT BY HAND.
+     Produced by skills/scripts/generate-tokens.mjs from
+     reference/design-language/tokens/colors.tokens.json (the source of truth).
+     Change colours in the token file, then run `npm run tokens:generate`.
+     CI runs `npm run tokens:check` and fails if this file drifts from the tokens. -->
+
+Brand color specifications for Equal Experts. This document defines the brand colors, palette scales, and usage guidelines.
+
+> **Source of truth:** the canonical colour tokens live **upstream in this repo** at [`tokens/colors.tokens.json`](./tokens/colors.tokens.json) (W3C design-tokens; brand palettes + aliases). **This document is generated from it** by `skills/scripts/generate-tokens.mjs`, and the downstream `@equal-experts/kuat-core` `variables.css` is generated from the same tokens — don't hand-edit either; change colours in the token file and regenerate. (kuat-core is downstream; never the reverse.) Support scales (slate/red/indigo) are *not* brand colours. Hex values below are the authoritative `…-500` brand values; full 50–950 scales + aliases live in the token file.
+
+---
+
+## Brand Colors
+
+Equal Experts uses four core brand color palettes:
+
+### EE Blue (Primary)
+
+**Purpose:** Trust, professionalism, technology  
+**Value:** `oklch(0.645 0.163 237.5)` / `#1795d4` (kuat-core `--ee-blue-500`)
+
+**Use for:**
+- Primary actions and CTAs
+- Brand identity elements
+- Key highlights and focus states
+- Links and interactive elements
+
+### Transform Teal (Secondary)
+
+**Purpose:** Transformation, growth, innovation  
+**Value:** `oklch(0.645 0.120 185.0)` / `#269c9e` (kuat-core `--transform-teal-500`)
+
+**Use for:**
+- Secondary actions
+- Accent elements and badges
+- Success indicators
+- Data visualization (secondary)
+
+### Tech Blue (Supporting)
+
+**Purpose:** Technical, professional, structural  
+**Value:** `oklch(0.435 0.090 240.0)` / `#22567c` (kuat-core `--tech-blue-500`)
+
+**Use for:**
+- Dark backgrounds
+- Navigation areas
+- Technical interfaces
+- Depth and structure
+
+### Equal Ember (Accent)
+
+**Purpose:** Energy, warmth, attention  
+**Value:** `oklch(0.625 0.200 65.0)` / `#f07c00` (kuat-core `--equal-ember-500`)
+
+**Use for:**
+- Special highlights (use sparingly)
+- Warning states
+- Attention-grabbing elements
+- Call-to-action emphasis
+
+---
+
+## Brand Color Palette Scale
+
+Each brand color has a scale from 50 (lightest) to 950 (darkest):
+
+| Range | Usage |
+|-------|-------|
+| 50-200 | Light backgrounds, subtle accents, hover states |
+| 300-500 | Primary brand colors, main actions |
+| 600-800 | Darker variants for depth and contrast |
+| 900-950 | Maximum depth, dark mode, high contrast |
+
+---
+
+## Brand Aliases (semantic roles)
+
+How the brand palettes map to semantic roles in kuat-core `variables.css`. **Use these aliases, not raw scale values.**
+
+| Alias | Maps to | Hex |
+|-------|---------|-----|
+| `--primary` | EE Blue 500 | `#1795d4` |
+| `--secondary` | Transform Teal 500 | `#269c9e` |
+| `--sidebar` (dark nav) | Tech Blue 500 | `#22567c` |
+| `--accent` (`--brand-ee-blue-accent`) | EE Blue 50 | `#e6f5fc` |
+| `--foreground` (`--brand-dark-data`) | text dark | `#212526` |
+| `--background` (`--brand-byte-white`) | white | `#ffffff` |
+| `--muted` (`--brand-the-cloud`) | Slate 100 | `#f5f5f5` |
+| `--destructive` | Red 600 | `#dc2626` |
+
+Support scales (slate, red, indigo) back these aliases but are **not brand colours** — never use them directly as a brand colour.
+
+---
+
+## Neutral Colors
+
+For text, backgrounds, and UI elements:
+
+| Color | Usage |
+|-------|-------|
+| White | Light backgrounds, text on dark |
+| Slate-50 to Slate-200 | Light backgrounds, subtle borders |
+| Slate-300 to Slate-500 | Secondary text, dividers |
+| Slate-600 to Slate-800 | Primary text (light mode) |
+| Slate-900 to Slate-950 | Headings, dark backgrounds |
+| Black | Maximum contrast, specific uses |
+
+---
+
+## Color Format
+
+All colors use **OKLCH** color space:
+
+```
+oklch(lightness chroma hue)
+```
+
+**Benefits:**
+- Perceptual uniformity (equal changes = equal perception)
+- Better color manipulation for consistent scales
+- Modern format with excellent support
+
+**Hex values** are provided for tools that don't support OKLCH.
+
+---
+
+## Light and Dark Mode
+
+Colors should adapt for light and dark contexts:
+
+**Light Mode (default):**
+- Light backgrounds (white, light gray)
+- Dark text (slate-900, slate-950)
+- Brand colors at standard values
+
+**Dark Mode:**
+- Dark backgrounds (slate-900, slate-950)
+- Light text (white, slate-100)
+- Brand colors remain consistent
+- Supporting colors adapt for contrast
+
+---
+
+## Accessibility Requirements
+
+All color combinations must meet **WCAG AA** standards:
+
+| Content Type | Minimum Contrast |
+|--------------|------------------|
+| Normal text (14px and below) | 4.5:1 |
+| Large text (18px+ or 14px+ bold) | 3:1 |
+| Graphical objects/borders | 3:1 |
+
+**Approved Combinations:**
+- Dark text on light backgrounds ✓
+- White text on EE Blue ✓
+- White text on Tech Blue ✓
+- White text on Transform Teal ✓
+- Dark text on Equal Ember (check contrast) ✓
+
+---
+
+## Usage Guidelines
+
+### Do's
+
+1. **Use brand colors consistently** - EE Blue for primary, Transform Teal for secondary
+2. **Pair colors correctly** - Ensure sufficient contrast for text
+3. **Support light and dark contexts** - Colors work in both modes
+4. **Respect brand hierarchy** - Primary for main actions, secondary for alternatives
+5. **Verify accessibility** - Always check contrast ratios
+
+### Don'ts
+
+1. **Don't use non-brand colors** - Stick to the defined palette
+2. **Don't mix brand colors inappropriately** - Each has a specific purpose
+3. **Don't break accessibility** - Always verify contrast ratios
+4. **Don't create custom variations** - Use only defined palette values
+5. **Don't use color alone to convey meaning** - Combine with text, icons, patterns
+
+---
+
+## Platform-Specific Implementation
+
+For platform-specific color usage:
+
+- **Web product** - See [media-types/web-product/](../media-types/web-product/) for CSS variables and tokens
+- **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/)
+- **Charts** - See [media-types/charts-data/](../media-types/charts-data/)
+
+---
+
+## Related Documentation
+
+- [Brand Guidelines](../brand/brand.md) - Brand principles
+- [Typography](./typography.md) - Font colors and text styling
+- [Logo](../brand/logo.md) - Logo color variants

package/agent-docs/external/kuat-agent-rules/reference/design-language/design-language.md

@@ -0,0 +1,117 @@
+# Design Language
+
+High-level design principles for Equal Experts. This document provides the foundation for all visual design decisions.
+
+---
+
+## Overview
+
+The Equal Experts design language ensures consistent, accessible, and brand-compliant outputs across all media types - web, slides, graphics, photography, and more.
+
+---
+
+## Design Principles
+
+### 1. Consistency
+
+Use design tokens everywhere. Never use arbitrary values for colors, spacing, or typography.
+
+**Why:** Consistency builds brand recognition and reduces cognitive load.
+
+### 2. Accessibility
+
+WCAG AA compliance minimum. All color combinations, interactive elements, and content must be accessible.
+
+**Why:** Everyone should be able to access and use Equal Experts materials.
+
+### 3. Simplicity
+
+Minimal borders, clear hierarchy through spacing. Prefer simple solutions over complex ones.
+
+**Why:** Simplicity communicates confidence and professionalism.
+
+### 4. Clarity
+
+Content-first design. Design serves content; never decorate at the expense of clarity.
+
+**Why:** Clear communication is more valuable than visual flourish.
+
+### 5. Flexibility
+
+Support different contexts - light/dark, print/digital, large/small formats.
+
+**Why:** Brand materials must work across many platforms and use cases.
+
+---
+
+## Design Token Categories
+
+| Category | What It Defines | Documentation |
+|----------|-----------------|---------------|
+| Colors | Brand colors, palette scales, usage | [colours.md](./colours.md) |
+| Typography | Fonts, sizes, weights, hierarchy | [typography.md](./typography.md) |
+| Spacing | Padding, margin, gaps, relationships | [spacing.md](./spacing.md) |
+| Borders | Widths, styles, radius, colors | [borders.md](./borders.md) |
+| Logo | Usage, sizing, variants, placement | [logo.md](../brand/logo.md) |
+
+---
+
+## Accessibility Standards
+
+The design language adheres to **WCAG 2.1 Level AA**:
+
+| Requirement | Standard |
+|-------------|----------|
+| Text contrast | 4.5:1 minimum |
+| Large text contrast | 3:1 minimum |
+| Graphical object contrast | 3:1 minimum |
+| Color alone | Never convey meaning through color alone |
+
+---
+
+## Best Practices Summary
+
+### Do's
+
+1. **Use brand colors** - EE Blue, Transform Teal, Tech Blue, Equal Ember
+2. **Follow the spacing scale** - Use defined values (4, 8, 16, 24, 32, 48px)
+3. **Use Lexend font** - It's the brand sans-serif
+4. **Test accessibility** - Verify contrast and readability
+5. **Use official assets** - Logo files from brand repository
+6. **Maintain hierarchy** - Clear visual structure
+
+### Don'ts
+
+1. **Don't use arbitrary values** - Always use tokens
+2. **Don't skip heading levels** - H1 → H2 → H3
+3. **Don't ignore contrast** - Verify all combinations
+4. **Don't modify brand assets** - Use as provided
+5. **Don't overcomplicate** - Simple is better
+6. **Don't prioritize decoration over clarity** - Content first
+
+---
+
+## Platform-Specific Rules
+
+Type-specific rules build on these general principles:
+
+| Platform | Directory | Description |
+|----------|-----------|-------------|
+| Web product | [media-types/web-product/](../media-types/web-product/) | Web applications |
+| Web marketing | [media-types/web-marketing/](../media-types/web-marketing/) | Marketing websites |
+| Slides | [media-types/slides/](../media-types/slides/) | Presentations |
+| Photography | [media-types/imagery/patterns/photography/](../media-types/imagery/patterns/photography/) | Photo guidelines |
+| Graphics | [media-types/imagery/patterns/graphics/](../media-types/imagery/patterns/graphics/) | Icons, illustrations, infographics |
+| Charts/Data | [media-types/charts-data/](../media-types/charts-data/) | Data visualization |
+
+---
+
+## Related Documentation
+
+- [Brand Guidelines](../brand/brand.md) - Brand principles and identity
+- [Logo](../brand/logo.md) - Logo usage guidelines
+- [Colours](./colours.md) - Brand colors
+- [Typography](./typography.md) - Fonts and type scale
+- [Spacing](./spacing.md) - Spacing system
+- [Borders](./borders.md) - Border philosophy
+- [Writing style](../content/writing-style.md) - Writing style and usage