@equal-experts/kuat-vue 0.15.0-beta.2 → 0.15.2

package/agent-docs/AGENTS.md

@@ -7,4 +7,4 @@ Rules for this install live under `agent-docs/` in `@equal-experts/kuat-core`, `
 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.15.0-beta.2 · **Rules snapshot:** bdf7dafd019a
+**Version:** 0.15.2 · **Rules snapshot:** 2048d9c4b195

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: `bdf7dafd019a`
+Built against upstream ref: `2048d9c4b195`

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

@@ -68,43 +68,56 @@ Use brand-appropriate colors:
 
 ## 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
+The design system uses a **minimal radius approach**, expressed as tokens rather than raw pixel
+values. Tokens live in `@equal-experts/kuat-core` (`variables.css`) as `--radius-none`,
+`--radius-xs`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, all derived from a
+single base `--radius` (currently `0.5rem`). **Never hard-code a radius pixel value** — reference
+the token, or the matching Tailwind utility (`rounded-none`, `rounded-xs`, `rounded-sm`,
+`rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-full`).
+
+### Scale
+
+| Token | Utility | Value | Use for |
+|-------|---------|-------|---------|
+| `--radius-none` | `rounded-none` | 0px | **Default.** Static containers, sections, dividers, content blocks, and floating overlays — dialogs, dropdown/select menus, popovers, toasts. Overlays float above the page but are not themselves interactive, so they take the same flat corner as static content. |
+| `--radius-xs` | `rounded-xs` | 2px | Rare, fine-detail use only — not a general-purpose size |
+| `--radius-sm` | `rounded-sm` | 4px | **Form inputs** — text inputs, textareas, selects, checkboxes, toggles — and card-style option-field wrappers (radio/checkbox/switch "card" appearance) |
+| `--radius-md` | `rounded-md` | 6px | **Interactive elements** — buttons, clickable cards, interactive tiles, tabs, menu items (including items inside an overlay, e.g. a dropdown row — the item is interactive even though its container isn't) |
+| `--radius-lg` | `rounded-lg` | 8px | Reserved — not currently assigned to any component. Available for a future "larger container" category if one is introduced; don't reach for it by default. |
+| `--radius-xl` | `rounded-xl` | 12px | Larger surfaces — bigger modals, feature cards |
+| n/a | `rounded-full` | pill / circle | **Rounded elements** — avatars, pill-shaped tags/badges, status dots, spinners |
+
+### Category rules
+
+- **Static content and floating overlays → `--radius-none`.** Cards, sections, dividers, dialogs,
+  dropdown/select menus, popovers, and toasts are all flat. A floating overlay is still "static" in
+  this sense — it isn't itself the interactive control, it's the surface a control sits on.
+- **Interactive elements → `--radius-md` (6px).** Buttons, clickable cards, tabs, menu items —
+  including menu items inside an otherwise-flat overlay.
+- **Form inputs → `--radius-sm` (4px).** Text inputs, textareas, selects, checkboxes, toggles, and
+  the card-style appearance of radio/checkbox/switch field wrappers.
+- **Pills / circular elements → `rounded-full`.** Use `rounded-full` (`calc(infinity * 1px)`)
+  rather than approximating a pill with a large fixed radius, so it always resolves to a true
+  circle/stadium shape regardless of element size. Use for avatars, the rounded variant of
+  tags/badges, and status/counter dots.
+
+### Known trap: keep the scale monotonic
+
+`--radius-sm/md/lg/xl` are `calc()`'d off the single `--radius` base. If that base is ever changed,
+confirm the derived values still ascend (xs < sm < md < lg < xl) before shipping. A base below
+roughly 6px breaks this — for example `--radius: 0.3rem` previously made `--radius-sm` compute to
+under 1px, smaller than `--radius-xs`, which silently produced near-square corners on several
+components (checkboxes, textareas, menus) despite their code claiming a 4px radius. If you hit this,
+fix the base token — don't route around it with a hard-coded pixel value in a component.
 
 ### Summary
 
-| Element Type | Border Radius |
-|--------------|---------------|
-| Static content | 0px |
-| Interactive elements | 6px |
-| Form inputs | 4px |
+| Element Type | Token | Border Radius |
+|--------------|-------|---------------|
+| Static content & floating overlays | `--radius-none` | 0px |
+| Interactive elements | `--radius-md` | 6px |
+| Form inputs & card-style option fields | `--radius-sm` | 4px |
+| Rounded/pill elements | `rounded-full` | pill / circle |
 
 ---
 
@@ -130,7 +143,7 @@ Borders must meet WCAG 2.1 Level AA for graphical objects:
 
 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
+3. **Apply radius by category** - `--radius-none` static content & overlays, `--radius-md` interactive, `--radius-sm` inputs & card-style fields, `rounded-full` pills/avatars
 4. **Ensure accessibility** - 3:1 minimum contrast ratio
 5. **Be consistent** - Same border treatment for same element types
 
@@ -138,7 +151,7 @@ Borders must meet WCAG 2.1 Level AA for graphical objects:
 
 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
+3. **Don't hard-code radius pixel values** - Use the `--radius-*` tokens/utilities, not literal `px` values, even to match an existing size
 4. **Don't break accessibility** - Always verify contrast
 5. **Don't use decorative borders** - Keep them functional
 

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

@@ -6,63 +6,126 @@ Guidelines for Equal Experts marketing emails and campaigns.
 
 ## Overview
 
-Marketing emails are external communications designed to engage, inform, and convert prospects and customers.
+Marketing emails are external, opted-in communications designed to inform, engage, and convert prospects and customers — newsletters, announcements, invitations, and nurture content. Unlike product emails, the reader hasn't triggered this specific message, so it has to earn its place in the inbox on relevance and value alone.
 
 ---
 
 ## Key Principles
 
-1. **Value-first** - Every email should provide value to the recipient
-2. **Clear purpose** - One primary goal per email
-3. **Scannable** - Easy to read on mobile devices
-4. **Brand-consistent** - Use Equal Experts visual identity
+1. **Permission-based** — send only to people who opted in, and honour unsubscribes immediately.
+2. **Value-first** — the reader gets something (an insight, an offer, useful information) before being asked for anything.
+3. **One clear goal** — a single primary CTA per email; competing asks dilute all of them.
+4. **Relevant and personal** — segment and personalise. Research consistently shows irrelevant content is what makes recipients call an email "spam", regardless of consent status.
+5. **Scannable** — mobile-first, chunked content, clear visual hierarchy; most opens happen on a phone.
+6. **Brand-consistent** — recognisable as Equal Experts in look, tone, and voice.
 
 ---
 
 ## Email Types
 
-- **Newsletter** - Regular updates and insights
-- **Product announcements** - New features and releases
-- **Event invitations** - Webinars, conferences, meetups
-- **Nurture sequences** - Educational content series
-- **Transactional** - Confirmations, receipts (see product emails)
+| Type | Description |
+|------|-------------|
+| Newsletter | Regular round-up of updates, insights, and content |
+| Product announcement | New feature or release news |
+| Event invitation | Webinars, conferences, meetups |
+| Nurture sequence | Educational content delivered over a series |
+| Promotional / campaign | Time-bound offer or call to act |
+
+Transactional messages (confirmations, receipts) follow [product email rules](../web-product/emails.md) even when sent to an external customer.
 
 ---
 
-## To Be Defined
+## Design Guidelines
+
+### Layout
+
+- Single column, mobile-first, roughly 600–640px wide. Multi-column layouts now read as cluttered even on desktop — keep it simple.
+- Lead with a strong headline or high-quality image, then a clear content hierarchy: headline → subheading → chunked body → CTA.
+- One primary CTA per email. More choices measurably reduce the chance any one of them gets clicked. Long-form newsletters are the one common exception, where a few clearly secondary links are acceptable.
+
+### Colour and imagery
+
+- Use the light, marketing-layout treatment (see [website](./website.md)) rather than the dark product navigation.
+- Apply brand [colours](../../design-language/colours.md) by role; reserve the extended/data palette for genuine data content, never for decoration.
+- Prefer full-width, high-quality imagery over small thumbnails or dense multi-image grids — large, clear images test better than cluttered ones.
+- Compress images, keep total email weight reasonable, and always pair images with alt text (many clients block images by default).
+
+### Typography
+
+- Brand typeface with a web-safe fallback stack. Use size and weight to establish hierarchy — see [typography](../../design-language/typography.md) and [formatting](../../content/formatting.md).
 
-- Email template designs
-- Header and footer specifications
-- Logo placement and sizing
-- Color usage in emails
-- Typography for email clients
-- CTA button styling
-- Mobile-first design requirements
-- Accessibility requirements (alt text, etc.)
-- Subject line guidelines
-- Preview text best practices
+### CTA buttons
+
+- Filled, high-contrast, live-text ("bulletproof") buttons, sentence case, verb-led.
+
+### Footer (legal/compliance minimum)
+
+- Recognisable sender identity and registered/physical address.
+- A visible, one-click unsubscribe or preference centre — never hidden, buried, or made deliberately effortful. Making it hard to leave erodes trust faster than losing the subscriber does.
+- A link to the relevant privacy/preferences information.
 
 ---
 
 ## Content Guidelines
 
-Follow [content](../../content/) for writing style.
+Follow [writing style](../../content/writing-style.md) and [formatting](../../content/formatting.md) for tone and conventions.
+
+### Subject line
+
+- Be specific and honest about what's inside. Curiosity-gap or "mystery" framing reads as spam and erodes trust even when it lifts opens.
+- Keep it concise for the mobile preview pane; avoid spam-trigger patterns (excess capitals, exclamation marks, misleading claims).
+
+### Preheader
+
+- Extend the subject with a concrete reason to open — don't waste it on "view in browser" boilerplate.
+
+### Body
+
+- Open with the value to the reader, not company news for its own sake.
+- Personalise with what you actually know about the recipient's interests or activity; a generic blast to everyone is the most common reason recipients call an email irrelevant or spammy.
+- Write in short, scannable chunks. One primary message per email.
+- Give the reader an easy way out. Most people who stop wanting an email won't bother to unsubscribe — they'll just tune out or mark it as spam, which is worse for deliverability than a clean unsubscribe.
+
+---
+
+## Common Scenarios
+
+| Scenario | Must include | Tone |
+|----------|---------------|------|
+| **Newsletter / digest** | A handful of curated, genuinely relevant items; one lead story | Informative, personality allowed, not salesy |
+| **Product announcement** | What's new, why it matters to this reader, one CTA to try/learn more | Confident, benefit-led, brief |
+| **Event invitation** | What, when, where/format, who it's for, one registration CTA | Clear and direct, low-friction to say yes |
+| **Nurture sequence** | One educational idea per email, building toward a later ask | Helpful first, low-pressure |
+| **Promotional / campaign** | The offer, the deadline if any, one CTA | Confident but not hyped; avoid false urgency |
+
+---
+
+## Deliverability and List Health
+
+Kept technology-agnostic here; implementation specifics (sending platform, list architecture) live outside this reference.
+
+- Send only to recipients who've opted in; process unsubscribes immediately.
+- Keep the sending identity consistent so recipients recognise it at a glance.
+- Periodically remove inactive or invalid addresses — sender reputation depends on engagement, not list size.
+- Avoid spam-trigger patterns in subject and body copy (excess capitals, exclamation marks, misleading claims).
+
+---
 
-### Subject Lines
-- Keep under 50 characters for mobile
-- Be specific about content
-- Avoid spam triggers
+## Accessibility Checklist
 
-### Body Content
-- Lead with the most important information
-- Use short paragraphs
-- Include clear CTA
-- Provide value before asking
+- Alt text on every image; decorative images marked as such.
+- Colour contrast meets [accessibility](../../accessibility/accessibility.md#colour-contrast) minimums.
+- Key messages and CTAs exist as live text, not baked into images.
+- A plain-text version accompanies the HTML email.
+- No auto-playing video/audio; limit animated GIFs and provide a static fallback where possible.
 
 ---
 
 ## Related Documentation
 
-- [Reference home](../../README.md) - Brand and design language
-- [Marketing Website](./website.md) - Website guidelines
-- [Content](../../content/) - Writing style
+- [Reference home](../../README.md) — brand and design language
+- [Marketing website](./website.md) — layout and visual patterns
+- [Writing style](../../content/writing-style.md) · [Formatting](../../content/formatting.md)
+- [Accessibility](../../accessibility/accessibility.md)
+- [Colours](../../design-language/colours.md) · [Typography](../../design-language/typography.md)
+- [Product emails](../web-product/emails.md) — transactional messages, including ones sent to external customers

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

@@ -31,6 +31,8 @@ Use when: Limited navigation items (5-7 items)
 
 ```
 ┌─────────────────────────────────────────┐
+│ System Banner (full width, conditional) │
+├─────────────────────────────────────────┤
 │ Dark Navigation Bar (Tech Blue)         │
 │ [Logo]    [Nav Items]    [User Menu]    │
 ├─────────────────────────────────────────┤
@@ -57,7 +59,9 @@ Use when: Limited navigation items (5-7 items)
 Use when: Complex navigation, hierarchical structure, 8+ items
 
 ```
-┌──────┬──────────────────────────────────┐
+┌─────────────────────────────────────────┐
+│ System Banner (full width, conditional) │
+├──────┬──────────────────────────────────┤
 │      │ Top Bar (Light)                  │
 │ Dark │ [Breadcrumbs]    [User Menu]     │
 │ Side │──────────────────────────────────┤
@@ -80,6 +84,164 @@ Use when: Complex navigation, hierarchical structure, 8+ items
 | Top bar background | `bg-background` (light) |
 | Content area | Light background, full remaining width |
 
+#### Region Breakdown
+
+Dark Sidebar Navigation is the default template for internal business tools: three persistent
+regions — sidebar, top bar, main content — host different content per screen without changing
+the shell. A fourth, conditional zone sits above all three when a site-wide status message is
+active.
+
+| Region | Purpose | Composition (top to bottom / left to right) |
+|--------|---------|-----------------------------------------------|
+| System banner | App-wide status (outage, deprecation, access change) | Full width, above the entire shell — spans both sidebar and top bar, not just the content area. Does not overlay or displace the top bar; only present when a site-wide message is active |
+| Sidebar | Wayfinding and workspace context | Workspace/brand switcher → primary navigation → secondary/utility links → account footer |
+| Top bar | Page context and utility actions | Collapse toggle + breadcrumb or page title (left) → site-wide utilities such as search, notifications, theme toggle, external link (right) |
+| Main content | Task surface | Primary content block(s) — a single block, or bento-style blocks for a dashboard-type layout |
+
+Section/page-level feedback (error summary, inline confirmation banner) is not part of this
+system-banner zone — it uses `Callout` as-is at the top of the main content area. See the Main
+content composition table below.
+
+**Sidebar composition:**
+
+| Element | Notes |
+|---------|-------|
+| Workspace/brand switcher | Icon + name, optional subtitle (plan, member count), expand chevron |
+| Primary navigation | Icon + label per item; items with children expand in place (chevron rotates, sub-items indent) |
+| Section labels | Muted, small-caps-style text grouping related nav items (e.g. "Platform", "Projects") |
+| Secondary navigation | Utility links (Help Center, Settings) below primary nav, visually separated |
+| Account footer | Avatar + name + email/identifier, pinned to the sidebar's bottom edge |
+
+**Top bar composition:**
+
+| Element | Notes |
+|---------|-------|
+| Collapse toggle | Icon button, always leftmost |
+| Wayfinding | Breadcrumb trail, or a single page title |
+| Search | Optional; may show a keyboard-shortcut hint |
+| Notifications / messages | Icon buttons with an unread badge or dot |
+| Theme toggle | Optional icon button |
+| External link | Optional labelled button (e.g. link to a repo or docs) |
+
+**Main content composition:**
+
+| Row | Purpose | Notes |
+|-----|---------|-------|
+| Feedback | Page/section-level feedback tied to a submitted action | Top-of-content-area callout or error summary; appears above the page header row when present |
+| Page header | Title + primary actions | Omit if the top bar already carries the page title |
+| Metric/summary row | At-a-glance KPIs | Card grid, 3-4 columns desktop — see [dashboard pattern](./patterns/dashboard.md) |
+| Visualization row | Trends over time | One or two chart cards side by side |
+| Primary work surface | The task itself | Table/list ([browse and filter](./patterns/browse-and-filter.md)), cards ([section hub](./patterns/section-hub.md)), identity + tabs ([detail page](./patterns/detail-page.md)), kanban board, or form — see the relevant [pattern](./patterns/) |
+
+Not every row applies to every screen — a settings page may use only "Page header" plus a form,
+while a metrics dashboard uses all rows below "Feedback." "Feedback" itself only appears when
+there's a submitted action to report on.
+
+---
+
+## Content-Only Layouts
+
+Some screens carry no persistent app navigation — the page itself is the task. Two shapes cover
+this in web-product.
+
+### Option 3: Single Column
+
+Use when: no persistent app navigation is needed — self-contained flows (auth, forms, wizards) or
+structured documents (reports, briefs).
+
+#### Narrow / Centred (Auth, Forms, Wizards)
+
+```
+┌─────────────────────────────────────────┐
+│            [Logo] (centered)            │
+├─────────────────────────────────────────┤
+│                                         │
+│     ┌─────────────────────────┐         │
+│     │      Auth/Form Card      │        │
+│     │      (max 400-480px)     │        │
+│     │      [Form fields]       │        │
+│     │      [Primary action]    │        │
+│     └─────────────────────────┘         │
+│                                         │
+├─────────────────────────────────────────┤
+│     Footer (minimal: legal links)       │
+└─────────────────────────────────────────┘
+```
+
+See [sign-in pattern](./patterns/sign-in.md) and [form pattern](./patterns/complete-a-form.md).
+
+A confirmation page (the end state of a completed form, application, or transaction) uses this
+same narrow/centred variant rather than a distinct layout shape — it's a simple end-state of a
+form flow, not a different page type. See [give feedback on an action
+pattern](./patterns/give-feedback-on-an-action.md).
+
+#### Full-Width / Long-Form (Reports, Briefs, Structured Documents)
+
+```
+┌───────────────────────────────────────────┐
+│ [Logo]        Breadcrumb           Status │
+├───────────────────────────────────────────┤
+│ EYEBROW LABEL                              │
+│ # Document Title                           │
+│ Dek / summary paragraph                    │
+│ Owner · Sponsor · Date · Status            │
+├───────────────────────────────────────────┤
+│ ┌─────────────────────────────────────┐   │
+│ │ Callout: at-a-glance summary         │   │
+│ └─────────────────────────────────────┘   │
+├───────────────────────────────────────────┤
+│ 01  Section heading                        │
+│     Cards / lists / tables                 │
+├───────────────────────────────────────────┤
+│ 02  Section heading                        │
+│     ...                                    │
+├───────────────────────────────────────────┤
+│ Footer: document title · page N/M          │
+└───────────────────────────────────────────┘
+```
+
+**Specifications:**
+
+| Property | Narrow (auth/forms) | Full-width (reports/briefs) |
+|----------|----------------------|-------------------------------|
+| Max content width | 400-480px | 720-960px (readable column) |
+| Top bar | Logo only, minimal | Slim brand bar + breadcrumb + status |
+| Body | Single card | Numbered sections (01, 02…), each self-contained |
+| Section content | Form fields | Callouts, card grids, comparison lists, status/severity tables, timeline/Gantt tables |
+| Footer | Minimal (legal links) | Document metadata (title, page N/M) |
+
+##### Document Header (Full-Width Variant)
+
+| Element | Notes |
+|---------|-------|
+| Eyebrow label | Muted, classifies the document (e.g. "Internal brief — steering group") |
+| Title (H1) | One per page |
+| Dek | One- to two-line summary paragraph |
+| Metadata strip | Label/value pairs (Owner, Sponsor, Date, Status) in a horizontal row |
+
+##### Section Anatomy (Full-Width Variant)
+
+| Element | Notes |
+|---------|-------|
+| Section number | "01", "02"… prefix, muted, left of heading |
+| Section heading | `text-lg` / `text-xl font-semibold` |
+| Section body | Free composition — card grid, two-column comparison, matrix table with legend, or a timeline/Gantt table |
+| Status/severity tags | Colour-coded chips (e.g. severity High/Medium/Low; status Resolved/Deferred/New) — pair colour with text, never colour alone |
+
+### Split Layout (Add-on, Not Standalone)
+
+Split Layout adds a third region — a right-hand rail — to [Sidebar Navigation](#option-2-dark-sidebar-navigation).
+It's an addition, not an alternative: pair it with Option 2 rather than using it alone.
+
+| Property | Value |
+|----------|-------|
+| Right rail width | 200-240px |
+| Visibility | Hidden below 1280px |
+| Content | Contextual to main content (table of contents, inspector, metadata) |
+| Scroll | Independent from main content |
+
+See [documentation pattern](./patterns/documentation.md) for the canonical use.
+
 ---
 
 ## Navigation Color Tokens
@@ -130,6 +292,14 @@ See [logo guidelines](../../brand/logo.md).
 | Tablet | Collapsible (default collapsed) |
 | Desktop | Full sidebar visible (240-280px) |
 
+### Single Column
+
+| Breakpoint | Behavior |
+|------------|----------|
+| Mobile | Full width, reduced side padding |
+| Tablet | Narrow variant stays card-width; full-width variant keeps its readable column |
+| Desktop | Narrow variant centred; full-width variant keeps max content width with side margins |
+
 ---
 
 ## Content Areas
@@ -154,7 +324,7 @@ See [logo guidelines](../../brand/logo.md).
 
 1. **Use dark navigation** - Distinguishes product from marketing
 2. **Use white/monochrome logo** - Appropriate for dark backgrounds
-3. **Choose appropriate nav pattern** - Horizontal for simple, sidebar for complex
+3. **Choose the layout that matches the task** - Horizontal nav for simple apps, sidebar for complex ones, single column when no persistent navigation is needed
 4. **Maintain light content areas** - Good contrast for readability
 5. **Follow spacing guidelines** - 8-point grid, consistent padding
 
@@ -162,7 +332,7 @@ See [logo guidelines](../../brand/logo.md).
 
 1. **Don't use light navigation** - That's for marketing layouts
 2. **Don't use full-color logo on dark** - Use white monochrome
-3. **Don't combine nav patterns** - Choose horizontal OR sidebar, not both
+3. **Don't combine nav patterns** - Choose horizontal OR sidebar, not both (Split Layout is the one sanctioned addition, and only with Sidebar Navigation)
 4. **Don't ignore mobile** - All layouts must work on small screens
 5. **Don't hardcode colors** - Use design tokens
 
@@ -175,3 +345,4 @@ See [logo guidelines](../../brand/logo.md).
 - [Component Decision Tree](./component-decision-tree.md) - Component selection
 - [Product Content](./content/product-content.md) - UX writing guidelines
 - [Patterns](./patterns/) - Applied patterns for specific page types
+- [Figma Build Checklist](./figma-build-checklist.md) - Verification steps for Figma builds, including the EE/Kuat vs. other-client context gate