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

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

@@ -0,0 +1,120 @@
+# Formatting
+
+How to use bold, capitalisation, headings, links, lists, and abbreviations in Equal Experts content.
+
+---
+
+## Quick Reference
+
+- **Capitalisation:** Sentence case for headings, buttons, and body copy; capitals only for proper nouns and product names
+- **Bold:** Use sparingly, only to draw attention to a key point
+- **Italics:** Use only to denote a quote
+- **Underline:** Use only to indicate a link
+- **Links:** Descriptive link text, not "click here" or raw URLs
+- **Lists:** Use sparingly; punctuate by whether items are full sentences
+- **Acronyms:** Spell out on first use, then use the short form
+
+---
+
+## Capitalisation
+
+### Sentence case
+
+Use sentence case for:
+- Headings, subheadings, and content titles (no full stop)
+- Button and link labels
+- List items
+- Body copy
+
+**Examples:**  
+"Helping ease the path to AI adoption in the enterprise"  
+"Save and continue"  
+"Contact the team"
+
+### Capitals in body copy
+
+Within the body of the content, use a capital letter only for a **proper noun** (for example a customer or product name). Don't use title case for general headings or UI labels.
+
+---
+
+## Bold, Italics, and Underline
+
+- **Bold:** Use sparingly, only when you want to draw attention to a key point: "Building a culture of innovation? You need **Experts** by your side."
+- *Italics:* Use **only to denote a quote**. Don't use italics for emphasis, titles of works, or technical terms.
+- <u>Underline:</u> Use **only to indicate the presence of a link**. Don't underline for emphasis.
+
+---
+
+## Headings
+
+- Use headings and subheadings to break up text and help readers scan or jump to what they need
+- Write them in **sentence case with no full stop**, and keep them concise and informative: "Why autonomous agents could be the best thing to happen to AI"
+- One H1 per page or screen; use a logical hierarchy (H1 → H2 → H3) and don't skip levels
+
+---
+
+## Links
+
+- Provide a link whenever you refer to something on another website or page
+- Link text should tell people where they're going and why they'd want to visit — link the relevant keywords, written as a normal sentence
+- Don't use words that wouldn't make sense without the link, and avoid "click here" or "read this" — they're bad for accessibility
+
+| Prefer | Avoid |
+|--------|--------|
+| Find out more on our Design service page | Click here for more |
+| Read the accessibility guidelines | Read this |
+| Contact the team | https://example.com/contact |
+
+---
+
+## Lists
+
+Use bullet points for items in no particular order; use a numbered list when the order matters. Use lists sparingly — too many in one piece dilutes their impact. Introduce a list with text followed by a colon.
+
+**Items that are not full sentences:** start each with a lower-case letter, follow each with a comma, end the penultimate item with "and", and end the last item with a full stop:
+
+> Equal Experts can help your business in many ways. We can:
+> - solve complex business problems,
+> - upskill your staff and
+> - scale your business for the future.
+
+**Items that are full sentences:** punctuate them like sentences, with a capital letter and a full stop:
+
+> Inceptions are based on principles and paradigms that we know make the difference:
+> - We validate that our solution is desirable, viable and feasible.
+> - We deliver the most valuable outcomes when we focus on the problem and the outcome.
+
+---
+
+## Buttons
+
+- Button text should describe the resulting **action** and be clear and concise
+- **Capitalise only the first word** ("Save and continue", "Contact us")
+- For product UI button patterns, see [web-product actions](../media-types/web-product/content/actions.md)
+
+---
+
+## Abbreviations and Acronyms
+
+- Spell out on first use with the short form in parentheses: "The Planning and Resource Allocation Committee (PRAC) decided to continue." Then use the short form: "We meet with the PRAC every two weeks."
+- This **isn't required for well-known acronyms** (for example NHS, BBC)
+- **Latin abbreviations** (e.g., etc., i.e.) may be used, but must be used correctly, in the right context, and with full stops
+
+---
+
+## Emojis and Hashtags
+
+Use emojis and hashtags thoughtfully, mainly in social media posts.
+
+- Don't add too many emojis; they should complement the text, not replace it. Check the post still makes sense if the emoji is removed
+- Make sure an emoji is appropriate and doesn't carry an alternative meaning online
+- Use **camel case** for hashtags so they're readable for assistive technology: #BlackLivesMatter, not #blacklivesmatter
+- Use 3–5 hashtags on LinkedIn and 1–2 on X; look for relevant event, industry, or topic tags
+
+---
+
+## Related Documentation
+
+- [Voice and tone](../brand/voice-and-tone.md)
+- [Writing style](./writing-style.md)
+- [Numbers](./numbers.md) - Dates, currency, units

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

@@ -0,0 +1,87 @@
+# Numbers
+
+Guidance for numbers, dates, times, and currency in Equal Experts content.
+
+---
+
+## Quick Reference
+
+- **Words vs figures:** Spell out one to ten; use figures for 11 and above
+- **Always figures:** Percentages, measurements, and currency always use figures and symbols (10%, 1.61m, £4m)
+- **Dates:** Day before month, no "th"/"st", never "the" (13 April, not the 13th of April)
+- **Times:** 12-hour uses a full stop (11.30am); 24-hour uses a colon (13:00). Don't mix the two
+- **Currency:** Default to a generic £ for global content; use local currency for single-country content
+- **Large numbers:** Use commas for thousands (3,000); abbreviate very large round numbers (1k, 2m)
+
+---
+
+## Words or Figures
+
+- Spell out whole numbers from **one to ten**: "We worked with the client for two months."
+- Use **figures for 11 and above**: "Our work involved 35 teams across the organisation."
+- If a number is the **first word of a sentence**, spell it out: "Eleven people worked in the team."
+- If a paragraph has **multiple figures**, use figures throughout so readers can compare easily: "There were 2 people in the team when we started, and 22 when we finished."
+
+**Exception:** percentages, measurements, and currency always use figures and symbols, even below 11 (see below).
+
+---
+
+## Ordinals
+
+- Spell out **first to tenth**: "She was the first person to see the problem."
+- Use figures with **st, nd, rd, th** for larger ordinals: "The 19th president of the United States was Rutherford B Hayes."
+
+---
+
+## Percentages, Measurements, and Currency
+
+Always use figures and symbols, regardless of the one-to-ten rule.
+
+- **Percentages:** Use the % symbol with the figure (10%, 12.5%). For a range, "40–60%" (en dash, no space)
+- **Measurements:** "The average height of a woman in the UK is 1.61m." Leave a space when spelling out units in prose where it reads naturally
+- **Currency:** See [Money and currency](#money-and-currency) below
+
+---
+
+## Large Numbers
+
+- Use commas as thousand separators: "We reviewed 3,000 lines of code."
+- For very large round numbers, combine a figure with a word or letter, or abbreviate to 1k or 2m: "The population of the earth is now more than 7 billion people." / "The budget came in at just under £2m."
+- Keep formatting consistent across tables and lists.
+
+---
+
+## Money and Currency
+
+- The default currency is a **generic £** sign on anything that may be referenced globally
+- If content is intended for a **single country**, adopt the local currency: "Our US-based client has seen efficiencies in the region of $1.3m."
+- Abbreviate large round amounts: "The cost savings for our client were £4m."
+
+---
+
+## Dates
+
+- Always put the **date before the month** — even in US-focused content, for clarity: "Easter this year is on 13 April." / "Armistice Day is on 11 November."
+- Don't use "th", "st", "nd", or "rd" with dates, and never precede the number with "the"
+- **Shorten periods** of time where it isn't ambiguous: "The First World War (1914–18)."
+- For a **financial year**, use the format "2020–21": "The company did better in 2020–21 than in 2019–20."
+- Use the **day of the week with a date** only for emphasis or to avoid confusion: "The Agile on the Beach conference starts on Friday 13 April."
+- In code, data, and other technical fields where an unambiguous machine format is needed, ISO 8601 (YYYY-MM-DD) is acceptable; it is the exception, not the prose style.
+
+---
+
+## Time
+
+- Use either the 12-hour or 24-hour clock — **not both** in the same text
+- **12-hour clock:** Use a full stop between hours and minutes, with am/pm: "The meeting starts at 11.30am and ends at 1pm."
+- **24-hour clock:** Use a colon and omit am/pm: "The meeting starts at 11:30 and ends at 13:00."
+- Use **"noon"** or **"midnight"** instead of "12", "12 noon", or "12 midnight"
+- When you use "from" with a start time or date, pair it with "to" for the end — not a dash: "The third financial quarter runs from October to December."
+- Specify a time zone when the reader needs to act or compare across regions ("2.30pm GMT")
+
+---
+
+## Related Documentation
+
+- [Formatting](./formatting.md) - Capitalisation, lists
+- [Punctuation](./punctuation.md) - En dash for ranges, "from … to"

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/{kuat-docs/rules/foundations → reference}/content/writing-style.md

@@ -31,7 +31,7 @@ Prefer the subject doing the action. It's clearer and more direct.
 | 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.
+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."
 
 ---
 
@@ -83,9 +83,14 @@ Use everyday contractions so content sounds natural and approachable.
 - 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](./voice-and-tone.md) - Principles and audience
+- [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/{kuat-docs/rules/foundations/design → reference/design-language}/borders.md

@@ -148,8 +148,9 @@ Borders must meet WCAG 2.1 Level AA for graphical objects:
 
 For platform-specific border guidance:
 
-- **Web** - See [types/web/](../types/web/)
-- **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/)
+- **Graphics** - See [media-types/imagery/patterns/graphics/](../media-types/imagery/patterns/graphics/)
 
 ---
 

package/agent-docs/external/kuat-agent-rules/{kuat-docs/rules/foundations/design → reference/design-language}/colours.md

@@ -1,7 +1,15 @@
 # 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
@@ -11,7 +19,7 @@ Equal Experts uses four core brand color palettes:
 ### EE Blue (Primary)
 
 **Purpose:** Trust, professionalism, technology  
-**Value:** `oklch(0.645 0.163 237.5)` / `#0066CC`
+**Value:** `oklch(0.645 0.163 237.5)` / `#1795d4` (kuat-core `--ee-blue-500`)
 
 **Use for:**
 - Primary actions and CTAs
@@ -22,7 +30,7 @@ Equal Experts uses four core brand color palettes:
 ### Transform Teal (Secondary)
 
 **Purpose:** Transformation, growth, innovation  
-**Value:** `oklch(0.645 0.120 185.0)`
+**Value:** `oklch(0.645 0.120 185.0)` / `#269c9e` (kuat-core `--transform-teal-500`)
 
 **Use for:**
 - Secondary actions
@@ -33,7 +41,7 @@ Equal Experts uses four core brand color palettes:
 ### Tech Blue (Supporting)
 
 **Purpose:** Technical, professional, structural  
-**Value:** `oklch(0.435 0.090 240.0)`
+**Value:** `oklch(0.435 0.090 240.0)` / `#22567c` (kuat-core `--tech-blue-500`)
 
 **Use for:**
 - Dark backgrounds
@@ -44,7 +52,7 @@ Equal Experts uses four core brand color palettes:
 ### Equal Ember (Accent)
 
 **Purpose:** Energy, warmth, attention  
-**Value:** `oklch(0.625 0.200 65.0)`
+**Value:** `oklch(0.625 0.200 65.0)` / `#f07c00` (kuat-core `--equal-ember-500`)
 
 **Use for:**
 - Special highlights (use sparingly)
@@ -67,6 +75,25 @@ Each brand color has a scale from 50 (lightest) to 950 (darkest):
 
 ---
 
+## 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:
@@ -159,15 +186,16 @@ All color combinations must meet **WCAG AA** standards:
 
 For platform-specific color usage:
 
-- **Web** - See [types/web/](../types/web/) for CSS variables and tokens
-- **Slides** - See [types/slides/](../types/slides/)
-- **Graphics** - See [types/graphics/](../types/graphics/)
-- **Charts** - See [types/charts-data/](../types/charts-data/)
+- **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.md) - Brand principles
+- [Brand Guidelines](../brand/brand.md) - Brand principles
 - [Typography](./typography.md) - Font colors and text styling
-- [Logo](./logo.md) - Logo color variants
+- [Logo](../brand/logo.md) - Logo color variants

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

@@ -52,7 +52,7 @@ Support different contexts - light/dark, print/digital, large/small formats.
 | 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](../logo.md) |
+| Logo | Usage, sizing, variants, placement | [logo.md](../brand/logo.md) |
 
 ---
 
@@ -93,24 +93,25 @@ The design language adheres to **WCAG 2.1 Level AA**:
 
 ## Platform-Specific Rules
 
-After understanding these general principles, load the appropriate type-specific rules:
+Type-specific rules build on these general principles:
 
 | Platform | Directory | Description |
 |----------|-----------|-------------|
-| Web | [types/web/](../../types/web/) | Websites and web applications |
-| Slides | [types/slides/](../../types/slides/) | Presentations |
-| Photography | [types/photography/](../../types/photography/) | Photo guidelines |
-| Graphics | [types/graphics/](../../types/graphics/) | Icons, illustrations, infographics |
-| Charts/Data | [types/charts-data/](../../types/charts-data/) | Data visualization |
+| 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.md) - Brand principles and identity
-- [Logo](../logo.md) - Logo usage guidelines
+- [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
-- [Content](../content/README.md) - Writing style and usage
+- [Writing style](../content/writing-style.md) - Writing style and usage

package/agent-docs/external/kuat-agent-rules/{kuat-docs/rules/foundations/design → reference/design-language}/spacing.md

@@ -118,9 +118,10 @@ Use consistent spacing relationships:
 
 For platform-specific spacing guidance:
 
-- **Web** - 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/)
 
 ---
 

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

@@ -0,0 +1,29 @@
+# Design tokens — source of truth
+
+This folder holds the **canonical design tokens** for the Equal Experts design system, **upstream** in `kuat-agent-rules`. It is the single source of truth; everything else is generated from it.
+
+- **`colors.tokens.json`** — brand colour palettes (EE Blue, Tech Blue, Transform Teal, Equal Ember) + aliases, in [W3C Design Tokens](https://tr.designtokens.org/format/) format. `$value` is hex; OKLCH is preserved in `$extensions`.
+
+## Generated artifacts (do not hand-edit — regenerate from here)
+
+| Artifact | Repo | Note |
+|----------|------|------|
+| `reference/design-language/colours.md` | kuat-agent-rules | human-readable mirror |
+| `@equal-experts/kuat-core` `src/variables.css` | kuat-mono (**downstream**) | CSS implementation; consumes these tokens via the upstream→mono sync |
+
+## Rules
+
+- **Change colours here, then regenerate.** Never hand-edit `colours.md` or `variables.css` — they drift (that's how EE Blue became `#0066CC`). The drift check fails if a generated artifact diverges from these tokens.
+- **Direction is one-way:** tokens (upstream) → `colours.md` + kuat-core (downstream). Never generate these tokens *from* kuat-core.
+- **Support scales** (slate/red/indigo) are not brand colours and live only in kuat-core.
+
+## How to regenerate (Phase 7)
+
+```bash
+npm run tokens:generate   # rewrite reference/design-language/colours.md from this token file
+npm run tokens:check      # CI drift gate — exits 1 if colours.md diverges from the tokens
+```
+
+- The generator is `skills/scripts/generate-tokens.mjs`; `colours.md` carries a `GENERATED FILE — DO NOT EDIT BY HAND` banner. Prose lives in the generator template — change it there and regenerate.
+- `tokens:check` runs in `.github/workflows/drift-check.yml` and inside the reference review gate (`npm run reference:check`).
+- The **downstream** `@equal-experts/kuat-core` `variables.css` half is generated in **kuat-mono** from the synced tokens (Phase 7 Run B — see `docs/migration/phase-7-kuat-mono-handoff.md`). The contributor workflow for colour changes is the repo-local `generate-tokens` skill (`.claude/skills/generate-tokens/`).

package/agent-docs/external/kuat-agent-rules/reference/design-language/tokens/colors.tokens.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://tr.designtokens.org/format/",
+  "$description": "Equal Experts brand COLOUR tokens — the SINGLE SOURCE OF TRUTH (upstream, in kuat-agent-rules). Downstream artifacts are GENERATED from this file: reference/design-language/colours.md (human-readable) and @equal-experts/kuat-core src/variables.css (CSS). Never hand-edit those; change colours HERE. kuat-core is downstream — do not invert. Support scales (slate/red/indigo) are NOT brand colours and live only in kuat-core. Format: W3C Design Tokens; $value is hex, oklch preserved in $extensions.",
+  "color": {
+    "ee-blue": {
+      "$description": "EE Blue — primary brand colour (trust, technology). Scale 50 (light) → 950 (dark).",
+      "50":  { "$type": "color", "$value": "#e6f5fc", "$extensions": { "oklch": "oklch(0.945 0.028 237.5)" } },
+      "100": { "$type": "color", "$value": "#b3e2f7", "$extensions": { "oklch": "oklch(0.885 0.055 237.5)" } },
+      "200": { "$type": "color", "$value": "#80cff2", "$extensions": { "oklch": "oklch(0.825 0.082 237.5)" } },
+      "300": { "$type": "color", "$value": "#4dbced", "$extensions": { "oklch": "oklch(0.765 0.109 237.5)" } },
+      "400": { "$type": "color", "$value": "#26a8e3", "$extensions": { "oklch": "oklch(0.705 0.136 237.5)" } },
+      "500": { "$type": "color", "$value": "#1795d4", "$extensions": { "oklch": "oklch(0.645 0.163 237.5)" } },
+      "600": { "$type": "color", "$value": "#1378ae", "$extensions": { "oklch": "oklch(0.585 0.145 237.5)" } },
+      "700": { "$type": "color", "$value": "#105c88", "$extensions": { "oklch": "oklch(0.525 0.127 237.5)" } },
+      "800": { "$type": "color", "$value": "#0c4062", "$extensions": { "oklch": "oklch(0.365 0.109 237.5)" } },
+      "900": { "$type": "color", "$value": "#08243c", "$extensions": { "oklch": "oklch(0.245 0.082 237.5)" } },
+      "950": { "$type": "color", "$value": "#04121e", "$extensions": { "oklch": "oklch(0.145 0.055 237.5)" } }
+    },
+    "tech-blue": {
+      "$description": "Tech Blue — dark/structural (navigation, sidebar, depth).",
+      "50":  { "$type": "color", "$value": "#e8eef3", "$extensions": { "oklch": "oklch(0.935 0.015 240.0)" } },
+      "100": { "$type": "color", "$value": "#bdcfdc", "$extensions": { "oklch": "oklch(0.835 0.030 240.0)" } },
+      "200": { "$type": "color", "$value": "#92b0c5", "$extensions": { "oklch": "oklch(0.735 0.045 240.0)" } },
+      "300": { "$type": "color", "$value": "#6791ae", "$extensions": { "oklch": "oklch(0.635 0.060 240.0)" } },
+      "400": { "$type": "color", "$value": "#447496", "$extensions": { "oklch": "oklch(0.535 0.075 240.0)" } },
+      "500": { "$type": "color", "$value": "#22567c", "$extensions": { "oklch": "oklch(0.435 0.090 240.0)" } },
+      "600": { "$type": "color", "$value": "#1b4563", "$extensions": { "oklch": "oklch(0.365 0.080 240.0)" } },
+      "700": { "$type": "color", "$value": "#15354a", "$extensions": { "oklch": "oklch(0.295 0.070 240.0)" } },
+      "800": { "$type": "color", "$value": "#0e2431", "$extensions": { "oklch": "oklch(0.205 0.060 240.0)" } },
+      "900": { "$type": "color", "$value": "#071218", "$extensions": { "oklch": "oklch(0.125 0.040 240.0)" } },
+      "950": { "$type": "color", "$value": "#03090c", "$extensions": { "oklch": "oklch(0.075 0.025 240.0)" } }
+    },
+    "transform-teal": {
+      "$description": "Transform Teal — secondary (transformation, growth).",
+      "50":  { "$type": "color", "$value": "#e9f6f6", "$extensions": { "oklch": "oklch(0.945 0.020 185.0)" } },
+      "100": { "$type": "color", "$value": "#bfe7e7", "$extensions": { "oklch": "oklch(0.885 0.040 185.0)" } },
+      "200": { "$type": "color", "$value": "#95d8d9", "$extensions": { "oklch": "oklch(0.825 0.060 185.0)" } },
+      "300": { "$type": "color", "$value": "#6bc9ca", "$extensions": { "oklch": "oklch(0.765 0.080 185.0)" } },
+      "400": { "$type": "color", "$value": "#48b8b9", "$extensions": { "oklch": "oklch(0.705 0.100 185.0)" } },
+      "500": { "$type": "color", "$value": "#269c9e", "$extensions": { "oklch": "oklch(0.645 0.120 185.0)" } },
+      "600": { "$type": "color", "$value": "#1f7d7e", "$extensions": { "oklch": "oklch(0.545 0.105 185.0)" } },
+      "700": { "$type": "color", "$value": "#175e5f", "$extensions": { "oklch": "oklch(0.445 0.090 185.0)" } },
+      "800": { "$type": "color", "$value": "#103f3f", "$extensions": { "oklch": "oklch(0.305 0.075 185.0)" } },
+      "900": { "$type": "color", "$value": "#081f20", "$extensions": { "oklch": "oklch(0.185 0.055 185.0)" } },
+      "950": { "$type": "color", "$value": "#040f10", "$extensions": { "oklch": "oklch(0.105 0.035 185.0)" } }
+    },
+    "equal-ember": {
+      "$description": "Equal Ember — warm accent (energy, attention; use sparingly).",
+      "50":  { "$type": "color", "$value": "#fff3e6", "$extensions": { "oklch": "oklch(0.975 0.035 65.0)" } },
+      "100": { "$type": "color", "$value": "#ffdbb3", "$extensions": { "oklch": "oklch(0.925 0.070 65.0)" } },
+      "200": { "$type": "color", "$value": "#ffc380", "$extensions": { "oklch": "oklch(0.875 0.105 65.0)" } },
+      "300": { "$type": "color", "$value": "#ffab4d", "$extensions": { "oklch": "oklch(0.825 0.140 65.0)" } },
+      "400": { "$type": "color", "$value": "#ff941a", "$extensions": { "oklch": "oklch(0.775 0.175 65.0)" } },
+      "500": { "$type": "color", "$value": "#f07c00", "$extensions": { "oklch": "oklch(0.625 0.200 65.0)" } },
+      "600": { "$type": "color", "$value": "#c06300", "$extensions": { "oklch": "oklch(0.525 0.180 65.0)" } },
+      "700": { "$type": "color", "$value": "#904a00", "$extensions": { "oklch": "oklch(0.425 0.160 65.0)" } },
+      "800": { "$type": "color", "$value": "#603100", "$extensions": { "oklch": "oklch(0.325 0.140 65.0)" } },
+      "900": { "$type": "color", "$value": "#301900", "$extensions": { "oklch": "oklch(0.225 0.120 65.0)" } },
+      "950": { "$type": "color", "$value": "#180c00", "$extensions": { "oklch": "oklch(0.125 0.100 65.0)" } }
+    }
+  },
+  "brand": {
+    "$description": "Named brand aliases — the canonical reference points. Use these, not raw scale steps.",
+    "ee-blue":        { "$type": "color", "$value": "{color.ee-blue.500}" },
+    "tech-blue":      { "$type": "color", "$value": "{color.tech-blue.500}" },
+    "transform-teal": { "$type": "color", "$value": "{color.transform-teal.500}" },
+    "equal-ember":    { "$type": "color", "$value": "{color.equal-ember.500}" },
+    "ee-blue-accent": { "$type": "color", "$value": "{color.ee-blue.50}" },
+    "dark-data":      { "$type": "color", "$value": "#212526", "$description": "Primary text dark." },
+    "the-cloud":      { "$type": "color", "$value": "#f5f5f5", "$description": "Light surface." },
+    "byte-white":     { "$type": "color", "$value": "#ffffff" }
+  },
+  "alias": {
+    "$description": "Semantic role → brand mapping (mirrors kuat-core ee-light). Support-scale-backed roles (muted/border/ring/destructive) resolve to non-brand scales in kuat-core and are intentionally omitted here except destructive.",
+    "primary":     { "$type": "color", "$value": "{brand.ee-blue}" },
+    "secondary":   { "$type": "color", "$value": "{brand.transform-teal}" },
+    "sidebar":     { "$type": "color", "$value": "{brand.tech-blue}", "$description": "Dark navigation." },
+    "accent":      { "$type": "color", "$value": "{brand.ee-blue-accent}" },
+    "foreground":  { "$type": "color", "$value": "{brand.dark-data}" },
+    "background":  { "$type": "color", "$value": "{brand.byte-white}" },
+    "muted":       { "$type": "color", "$value": "{brand.the-cloud}" },
+    "destructive": { "$type": "color", "$value": "#dc2626", "$description": "Red 600 (support scale, not brand)." }
+  }
+}