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

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.14.0 · **Rules snapshot:** 57ee7c45da82
+**Version:** 0.15.0-beta.1 · **Rules snapshot:** 038a985b57fe

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: `57ee7c45da82`
+Built against upstream ref: `038a985b57fe`

package/agent-docs/components/callout.md

@@ -0,0 +1,66 @@
+# Callout (`kuat:callout`)
+
+## Overview
+
+Inline banner for surfacing a status message tied to a section of content: info, positive, warning, or issue. Supports a required title, an optional description, a per-type icon (shown by default, can be hidden), and an optional link-style action. Exported from `@equal-experts/kuat-react` / `@equal-experts/kuat-vue`.
+
+## When to use
+
+- Persistent, in-page status messages tied to a section of content (e.g. explaining what a view shows, or that a save failed)
+- Confirmations, warnings, or errors that should stay visible until the user navigates away or dismisses them via the action link
+
+## When not to use
+
+- Transient, self-dismissing notifications — use `Sonner`
+- Form field-level validation — use `Field`'s error slot
+- A single inline icon+label with no message — use `Badge`
+
+## Variants
+
+Four semantic `type` values, each with its own background tint and left border/icon accent:
+
+- `info` (default) — ee-blue tint, `Info` icon
+- `positive` — uptime-green tint, `CheckCircle2` icon
+- `warning` — equal-ember tint, `AlertTriangle` icon
+- `issue` — runtime-red tint, `XCircle` icon
+
+## States
+
+- **Icon shown / hidden** — `icon` prop, default `true`. The icon glyph is chosen automatically from `type`; consumers cannot swap it independently.
+- **With / without description** — omit `description` to render title only.
+- **With / without action** — omit `action` to render no link. Only a link-style action ships in this release; additional action kinds (e.g. a button) may be added in future without changing the `title`/`description`/`icon` API.
+
+## Content guidance
+
+- Title should be a short, complete statement of the status — it's the only text guaranteed to be read, since colour is never the sole signal (icon shape + title wording both carry the meaning, independent of the accent colour).
+- Description is for supporting detail, not another restatement of the title.
+- Action label should describe the action's effect (e.g. "Close message"), not just "Click here".
+
+## Behaviour
+
+- Root element renders `role="status"` (polite live region) — appropriate for a persistent banner already present in the page, as opposed to a toast that should interrupt.
+- The action renders as a real `<a href>` (with optional `target` and `onClick`), not a button — it's always a navigation/link affordance in this release.
+
+## Accessibility
+
+- Status is never conveyed by colour alone: the icon shape (circle-i / check / triangle / x) and the title wording both signal the type independent of colour (WCAG 1.4.1).
+- The icon and title text share the same neutral `--foreground` token — only the left border stripe and background use the per-type accent colour, so the icon remains legible regardless of type.
+- All four `background`/`foreground` token pairs (`--callout-info`, `--callout-positive`, `--callout-warning`, `--callout-issue`, each with a `-foreground` counterpart) are covered by `pnpm tokens:contrast-check` in both light and dark mode.
+- Icon is `aria-hidden="true"` — it's decorative reinforcement of the title text, not a separate accessible element.
+
+## API
+
+Import from `@equal-experts/kuat-react` (subpath: `@equal-experts/kuat-react/callout`) or `@equal-experts/kuat-vue` (subpath: `@equal-experts/kuat-vue/callout`).
+
+- `type?: "info" | "positive" | "warning" | "issue"` — default `"info"`
+- `title` — required
+- `description?` — optional
+- `icon?: boolean` — default `true`
+- `action?: { label: string; href: string; target?: string; onClick?: (event) => void }` — optional
+
+See Storybook (`Feedback/Callout`) for live examples of every type and combination.
+
+## Related components
+
+- `shadcn:sonner` (Kuat `Sonner`) — transient, self-dismissing toast notifications
+- `kuat:field` — inline form-field validation messages

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

@@ -18,6 +18,12 @@
       "displayName": "KuatHeader",
       "path": "components/kuat-header.md",
       "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
+    },
+    "kuat:callout": {
+      "slug": "callout",
+      "displayName": "Callout",
+      "path": "components/callout.md",
+      "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
     }
   }
 }

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

@@ -99,11 +99,37 @@ When using colour for status (red/amber/green):
 3. **Include legend** - Always explain what colours mean
 4. **Consider colour blindness** - Red/green are commonly confused
 
+### Status / RAG Colour Values
+
+The semantic layer in [colours.md](../design-language/colours.md#semantic--rag-colours) fixes the
+status set — always pair with the listed shape/icon, never colour alone:
+
+| State | Colour | Required text | Ratio |
+|-------|--------|----------------|-------|
+| Error / danger | Runtime Red `#a3152b` | White | 7.8:1 AAA |
+| Warning | Equal Ember `#f07c00` | Dark Data (white **fails**, 2.8:1) | 5.6:1 AA |
+| Success | Uptime Green `#11821b` | White | 5.0:1 AA |
+| Info / call-out | Index Indigo `#352361` | White | 13.4:1 AAA |
+
+Runtime Red and Uptime Green collapse under protanopia — the icon/shape/label partner is what
+makes RAG status colour-blind safe, not the colour itself.
+
+### Accessible Link Colour (WIP)
+
+EE Blue (`#1795d4`) fails body-text contrast (3.3:1 on white) and is reserved for buttons, icons,
+and larger CTAs. Text links and small text use the semantic `link` token (`#0080be`) instead —
+see [colour-usage.md](../design-language/colour-usage.md#links-vs-buttons--the-accessible-blue).
+This value is deliberately just under the 4.5:1 AA threshold (4.34:1 on white, ≈97%) to stay close
+to EE Blue, pending validation in real link contexts; a strict-AA fallback (`#007cb9`, 4.58:1)
+exists if that validation doesn't hold.
+
 ### Charts and Data Visualisation
 
 - Use patterns or textures in addition to colours
-- Ensure adjacent colours have sufficient contrast
+- Ensure adjacent colours have sufficient contrast (3:1 minimum, WCAG 1.4.11)
+- Never place EE Blue and Transform Teal adjacent — near-identical lightness (1.01:1)
 - Provide data tables as alternatives to charts
+- Full CVD rules and the categorical sequence: [colours.md](../design-language/colours.md#data-visualisation--categorical-order)
 
 ---
 

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

@@ -0,0 +1,107 @@
+# Colour Usage
+
+Tier, pairing, and role rules for the Equal Experts palette. This is the prose companion to
+[colours.md](./colours.md) (generated — the token-derived swatches and values live there); this
+file states the rules that govern *when* each tier applies. See
+[accessibility.md](../accessibility/accessibility.md) for contrast targets and the never-colour-alone
+rule, and each medium's own reference (`media-types/<medium>/`) for how a tier applies there.
+
+Source: the June 2026 Nick Orme / Ed Ford colours lockdown.
+
+---
+
+## The tier model
+
+Colour is governed by **what it is allowed to do**, not by which palette it belongs to.
+
+| Tier | Contents | Where |
+|------|----------|-------|
+| **Tier 1 — Core** | The four brand hues (EE Blue, Transform Teal, Tech Blue, Equal Ember) + neutrals (Dark Data, The Cloud, Byte White) | Default for almost everything: product UI, adverts, the body of most slide decks |
+| **Tier 2 — Extended accents** | The ten extended-palette colours | Exception only: small pull-out highlights, keyed diagrams, illustration accents. Capped at roughly 5–10% of a page's area |
+| **Tier 3 — Data encoding** | The `categorical-1…8` sequence | Charts and data visualisation only |
+| **Semantic / RAG** | `error`, `warning`, `success`, `info`, `link`, `interaction-state` | Cross-cutting — sits above all tiers, may appear in any scenario, reserved for meaning and never reused decoratively |
+
+Core is what almost everyone should use almost all the time. The extended colours exist for
+defined situations, used sparingly — flooding a layout with them reads as a different brand.
+
+---
+
+## Background floods
+
+Full-page background floods are restricted to **Dark Data** or **Tech Blue** (or light greys /
+The Cloud). **EE Blue, Transform Teal, and Equal Ember are not full-page fills** — they are
+block/component-level backgrounds and accent/CTA colours only. A full-page EE Blue background is
+too bright and swallows CTAs; the same logic applies to Transform Teal and Equal Ember.
+
+---
+
+## The three-stage blue
+
+The blue family forms a deliberate three-step ramp:
+
+**Tech Blue** (dark) → **EE Blue** (mid) → **Edge Blue** (light).
+
+Edge Blue is the light end, brought in specifically for hover/active interaction states — it has
+a defined product-UI role, not just decoration.
+
+---
+
+## Adjacency and pairing rules
+
+- **Never place EE Blue and Transform Teal adjacent** in a categorical sequence, fill, or chart.
+  They share near-identical lightness (1.01:1 contrast) — indistinguishable in greyscale and for
+  many colour-vision-deficient viewers. Use one or the other per chart, not both.
+- **The Fruity combination is decoration-only.** Runtime Red, Cursor Coral, Uptime Green, Logic
+  Lime, Signal Yellow, and Patch Peach together collapse under protanopia (Runtime Red and Uptime
+  Green become indistinguishable). Never use Fruity to encode data, status, or categories.
+- **White text on Equal Ember fails** (2.8:1) — Equal Ember always takes Dark Data text.
+- Dark-surface extended colours (Index Indigo, Packet Plum, Runtime Red, Uptime Green, Server
+  Slate) take white text; bright-surface extended colours (Logic Lime, Edge Blue, Signal Yellow,
+  Cursor Coral, Patch Peach) take Dark Data text — see [colours.md](./colours.md#pairing-summary)
+  for the generated pairing table.
+
+---
+
+## Server Slate vs the EE neutral scale
+
+Server Slate is a distinct **brand grey** (a peer of the other extended colours, its own 50–950
+scale). The EE neutral scale (Byte White → Dark Data) is a separate **UI neutral** scale for
+surfaces, borders, and text. The two are kept apart because they serve different jobs: Server
+Slate carries brand identity in a near-neutral tone; the neutral scale is the plain structural
+scale product UI is built on.
+
+---
+
+## Links vs buttons — the accessible blue
+
+EE Blue (`#1795d4`) fails body-text contrast (3.3:1 on white) but is retained for buttons, icons,
+and larger CTAs, where it remains iconic and visually acceptable. Text links and small text use
+the semantic `link` token instead (`#0080be`), a darkened EE Blue that keeps close to the brand
+hue.
+
+**The `link` value is WIP.** It is set deliberately just under the 4.5:1 AA threshold (4.34:1 on
+white, ≈97%) to stay as close to EE Blue as possible — a brand-fidelity-over-strict-compliance
+call, pending validation in real link contexts. A strict-AA fallback (`#007cb9`, 4.58:1) exists if
+that validation doesn't hold up. Don't hard-code the current hex in a consuming app; reference the
+`link` token so the value can move without a second migration.
+
+---
+
+## Named combinations
+
+Brand groups colours into five named combinations — **Core, Data, Digital, Fruity, Ocean** — used
+as mood/theme groupings for marketing and slide decks (Ocean reads cool/corporate, Fruity reads
+energetic, and so on). These are theme palettes, not data-series orders: for charts, use the
+Tier 3 categorical sequence in [colours.md](./colours.md), not a named combination. Fruity in
+particular must never encode data (see above).
+
+---
+
+## Related
+
+- [colours.md](./colours.md) — generated token values: brand colours, the extended palette, the
+  neutral scale, semantic roles, and the data-viz categorical order.
+- [accessibility.md](../accessibility/accessibility.md) — contrast targets and the
+  never-colour-alone rule.
+- `media-types/<medium>/` — how a tier applies in web product, web marketing, charts, slides, and
+  imagery.

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

@@ -88,24 +88,99 @@ How the brand palettes map to semantic roles in kuat-core `variables.css`. **Use
 | `--foreground` (`--brand-dark-data`) | text dark | `#212526` |
 | `--background` (`--brand-byte-white`) | white | `#ffffff` |
 | `--muted` (`--brand-the-cloud`) | Slate 100 | `#f5f5f5` |
-| `--destructive` | Red 600 | `#dc2626` |
+| `--destructive` | Runtime Red 600 | `#a3152b` |
 
 Support scales (slate, red, indigo) back these aliases but are **not brand colours** — never use them directly as a brand colour.
 
 ---
 
-## Neutral Colors
+## Extended Palette (exception-only)
+
+Added in the June 2026 colours lockdown. **Core is primary; extended is exception-only** — see
+[colour-usage.md](./colour-usage.md) for the tier model (data viz, keyed diagrams, small pull-outs).
+Each is a flat peer scale (50–950), anchored at its measured lightness step, not forced to 500.
+
+| Colour | Role | Value | Text on it |
+|--------|------|-------|------------|
+| Index Indigo | Info / call-out | `#352361` (step 800) | White |
+| Packet Plum | Expressive accent / dark surface | `#853d7b` (step 600) | White |
+| Runtime Red | Error / danger | `#a3152b` (step 600) | White |
+| Uptime Green | Success | `#11821b` (step 500) | White |
+| Server Slate | Near-neutral brand grey (distinct from the EE neutral scale) | `#4c5659` (step 600) | White |
+| Logic Lime | Bright pull-out accent · display alias "Lime" | `#b1d923` (step 300) | Dark Data |
+| Edge Blue | Hover/active state — light end of the 3-stage blue | `#a1c8e2` (step 200) | Dark Data |
+| Signal Yellow | Bright pull-out accent · display alias "Sunflower" | `#ffd930` (step 300) | Dark Data |
+| Cursor Coral | Decorative pull-out (not error) | `#ff5c5c` (step 400) | Dark Data |
+| Patch Peach | Light warm pull-out accent | `#fca84e` (step 300) | Dark Data |
 
-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 |
+## EE Neutral Scale
+
+Monotonic Byte White → Dark Data, distinct from Server Slate (a brand grey, not a UI neutral):
+
+| Step | Value | Alias |
+|------|-------|-------|
+| 50 | `#ffffff` | **Byte White** |
+| 100 | `#f5f5f5` | **The Cloud** |
+| 200 | `#dbdbdb` |  |
+| 300 | `#c1c2c2` |  |
+| 400 | `#a7a9a9` |  |
+| 500 | `#8f9192` |  |
+| 600 | `#777a7a` | **Overcast** |
+| 700 | `#606364` |  |
+| 800 | `#4a4d4e` |  |
+| 900 | `#35393a` |  |
+| 950 | `#212526` | **Dark Data** |
+
+---
+
+## Semantic / RAG Colours
+
+Cross-cutting roles that mean a *specific thing* and may appear in any scenario — reserved for
+meaning, never reused decoratively. Always pair with an icon/shape/label (WCAG 1.4.1 — never
+colour alone).
+
+| Role | Value | Required text | Notes |
+|------|-------|----------------|-------|
+| Error / danger | `#a3152b` | White | 7.8:1 AAA · replaces support #dc2626 |
+| Warning | `#f07c00` | Dark Data | 5.6:1 AA · white text FAILS (2.8:1) |
+| Success | `#11821b` | White | 5.0:1 AA |
+| Info / call-out | `#352361` | White | 13.4:1 AAA |
+| Text link / small text | `#0080be` | is the text | WIP — ~97% of AA on white (4.34:1), deliberately close to EE Blue; strict-AA fallback #007cb9 |
+| Interaction state (hover/active) | `#a1c8e2` | Dark Data | 8.8:1 AAA |
+| Error, on dark surfaces | `#d98786` | — | lighter step for on-dark text |
+| Success, on dark surfaces | `#72b070` | — | lighter step for on-dark text |
+| Info, on dark surfaces | `#a49ec1` | — | lighter step for on-dark text |
+
+---
+
+## Data Visualisation — Categorical Order
+
+Tier 3 sequence for charts/data viz only. Use in order; stop when there are enough categories.
+CVD-checked, lightness-separated. Never place EE Blue and Transform Teal adjacent.
+
+1. **EE Blue** `#1795d4`
+2. **Equal Ember** `#f07c00`
+3. **Tech Blue** `#22567c`
+4. **Logic Lime** `#b1d923`
+5. **Packet Plum** `#853d7b`
+6. **Edge Blue** `#a1c8e2`
+7. **Runtime Red** `#a3152b`
+8. **Signal Yellow** `#ffd930`
+
+---
+
+## Pairing Summary
+
+**Dark surfaces (white text):** Index Indigo, Packet Plum, Runtime Red, Uptime Green, Server Slate, Dark Data.
+
+**Bright surfaces (Dark Data text):** Logic Lime, Edge Blue, Signal Yellow, Cursor Coral, Patch Peach, EE Blue, Transform Teal, Equal Ember.
+
+**Do not pair:**
+- EE Blue `#1795d4` and Transform Teal `#269c9e` adjacent in a categorical sequence — 1.01:1 luminance, indistinguishable in greyscale/CVD.
+- The Fruity combination (Runtime Red, Cursor Coral, Uptime Green, Logic Lime, Signal Yellow, Patch Peach) for any data encoding — collapses under protanopia. Decoration only.
+- White text on Equal Ember `#f07c00` — fails at 2.8:1; use Dark Data.
 
 ---