@equal-experts/kuat-vue 0.15.1 → 0.15.2

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

@@ -1,65 +1,131 @@
 # Product Email Rules
 
-Guidelines for Equal Experts transactional and product-related emails.
+Guidelines for Equal Experts transactional and system emails sent from web applications.
 
 ---
 
 ## Overview
 
-Product emails are transactional communications sent from web applications, including confirmations, notifications, and system messages.
+Product emails are triggered by something the user did or something the system needs to tell them: confirmations, notifications, and system messages. The reader didn't ask for this specific message, but they are expecting the application to send it — the bar is trust and clarity, not persuasion.
 
 ---
 
 ## Key Principles
 
-1. **Informative** - Provide necessary information clearly
-2. **Actionable** - Include clear next steps when needed
-3. **Timely** - Send at the right moment
-4. **Concise** - Respect user's time
+1. **Clean and content-first** — minimal decoration; the message leads and design supports it. Follow the design system's [clarity principle](../../design-language/design-language.md#4-clarity): never decorate at the expense of getting the information across.
+2. **Trustworthy** — instantly recognisable as coming from the product, and clear about exactly which service sent it — no surprises in sender, subject, or content.
+3. **Single-purpose** — one transaction, one message. Don't fold marketing content into a transactional email.
+4. **Timely** — sent as close to the triggering event as the system allows.
+5. **Actionable** — the reader knows what happened, whether they need to do anything, and how.
+6. **Accessible** — works with images blocked, with a screen reader, and at 200% zoom.
 
 ---
 
 ## Email Types
 
-- **Confirmation emails** - Account created, payment received
-- **Notification emails** - New activity, status changes
-- **System emails** - Password reset, security alerts
-- **Digest emails** - Summary of activity
+| Type | Examples |
+|------|----------|
+| Confirmation | Account created, payment received, booking made |
+| Notification | New activity, status change, mention or assignment |
+| System / security | Password reset, email verification, security alert, new-device sign-in |
+| Digest | Periodic roll-up of activity |
+
+---
+
+## Design Guidelines
+
+### Layout
+
+- Content-first: strip the design back to what the message needs. No decorative imagery, banners, or flourishes competing with the information itself.
+- Single column, mobile-first, roughly 600–640px wide.
+- Generous whitespace between sections — follow the [spacing](../../design-language/spacing.md) scale.
+- One primary CTA. Use a secondary text link only when a genuine second action exists (e.g. "or view your account").
+
+### Colour
+
+- Use brand [colour](../../design-language/colours.md) roles, not raw hex values: primary for the CTA, `--destructive` for error/security-alert framing.
+- Never rely on colour alone to signal status — pair with wording ("Error:", "Action needed") as described in [accessibility](../../accessibility/accessibility.md#colour-usage).
+- Avoid full-colour backgrounds behind body copy; they don't survive client dark-mode inversion reliably. Keep the body on a light background with a small brand accent (header bar, logo lockup).
+
+### Typography
+
+- Use the brand typeface with a web-safe fallback stack — many email clients can't load custom webfonts. See [typography](../../design-language/typography.md).
+- Minimum 14–16px body text, 1.5 line height, per [accessibility](../../accessibility/accessibility.md#typography-accessibility).
+
+### Imagery and logo
+
+- Small header logo per [logo guidelines](../../brand/logo.md).
+- Alt text is mandatory on every image. Many clients block images by default, so never put essential information (amounts, dates, codes) only in an image — set it as live text.
+- Use live HTML text for buttons and headlines, not text baked into an image.
+
+### Service identity
+
+Kuat covers many EE-built services, so the reader needs to know at a glance which one sent this email — particularly if they use more than one. That identification doesn't have to sit in the main header lockup: a small label near the header (e.g. "Timesheets", "Expenses") or a clear line in the footer ("This email was sent by [Service], part of Equal Experts") both work. Pick one clear place for it — don't rely on the sender address alone, since many clients hide or truncate it by default.
+
+### Buttons / CTA
+
+- One primary CTA: filled, high-contrast, minimum 44×44px tap target, live text (a "bulletproof" button, not an image).
+- Sentence case, verb-led label — see [buttons](../../content/formatting.md#buttons).
+
+### Footer
+
+- Recognisable sender name, the sending service named per [service identity](#service-identity) above, and a way to reach support.
+- If the email carries any promotional content alongside the transactional message, it needs an unsubscribe/preferences link and the same legal footer as a [marketing email](../web-marketing/emails.md#footer-legalcompliance-minimum) — keep pure transactional email free of that content instead.
 
 ---
 
 ## Content Guidelines
 
-Follow [content foundations](../../content/writing-style.md) and [product content](./content/product-content.md) for writing style.
+Follow [writing style](../../content/writing-style.md) and [formatting](../../content/formatting.md) for tone, voice, and conventions.
+
+### Subject line
+
+- Name the specific outcome, not a generic label: "Your password has been reset", not "Notification".
+- Include identifying details where they help the reader confirm it's theirs (order number, invoice number).
+- No marketing language, hype, or artificial urgency in a system email.
+
+### Preheader
+
+- Extend the subject with the next useful detail; don't waste it on boilerplate.
+
+### Body
+
+- Lead with the outcome or status — skip a greeting preamble.
+- State what happened, why the reader is getting this email, and what to do next (or that nothing is needed).
+- For security-sensitive emails: state any expiry window, and reassure the reader with next steps if they didn't request the action.
+- Use real data the reader will recognise (their name, order number); don't personalise with data you don't actually have.
+- Short paragraphs, one idea each, written for a first-read scan.
+
+---
 
-### Subject Lines
-- Be specific about the content
-- Include relevant details (order number, etc.)
-- Keep concise
+## Common Scenarios
 
-### Body Content
-- Lead with the most important information
-- Include relevant details
-- Provide clear next steps
-- Link to the application for actions
+| Scenario | Must include | Tone |
+|----------|---------------|------|
+| **Password reset** | Reset link/button, expiry window, "didn't request this?" reassurance and next step | Calm, reassuring, no urgency beyond the real expiry |
+| **Welcome / account activation** | What the account gives access to, the activation action, a first next step | Warm, brief, sets expectations for what's next |
+| **Payment / booking confirmation** | What was purchased/booked, amount, date/reference, what happens next | Clear, itemised, confidence-building |
+| **Activity notification** | What happened, who/what triggered it, link to view in the product | Brief, factual, one glance should be enough |
+| **Security alert** | What was detected, when, device/location if known, how to secure the account if it wasn't them | Direct, non-alarmist, action-first |
+| **Digest / summary** | Time period covered, the handful of most relevant items, link to see more | Scannable, prioritised — not a full activity log |
 
 ---
 
-## To Be Defined
+## Accessibility Checklist
 
-- Email template designs
-- Header and footer specifications
-- Logo placement and sizing
-- Color usage in transactional emails
-- Typography for email clients
-- CTA button styling
-- Mobile-first design requirements
-- Accessibility requirements
+- Alt text on every image; decorative images marked as such.
+- Colour contrast meets [accessibility](../../accessibility/accessibility.md#colour-contrast) minimums; status never conveyed by colour alone.
+- All critical information and CTAs exist as live text, not images.
+- Semantic HTML structure (proper headings, real buttons/links) so screen readers and layout tables (marked `role="presentation"`) don't confuse assistive tech.
+- A plain-text version accompanies the HTML email.
+- No auto-playing or flashing content.
 
 ---
 
 ## Related Documentation
 
-- [Reference home](../../README.md) - Brand and design language
-- [Product Content](./content/product-content.md) - UX writing guidelines
-- [Marketing Emails](../web-marketing/emails.md) - Marketing email guidelines
+- [Reference home](../../README.md) — brand and design language
+- [Writing style](../../content/writing-style.md) · [Formatting](../../content/formatting.md) — copy conventions
+- [Accessibility](../../accessibility/accessibility.md) · [Web-product accessibility](./accessibility.md) — technical implementation
+- [Colours](../../design-language/colours.md) · [Typography](../../design-language/typography.md)
+- [Marketing emails](../web-marketing/emails.md) — for the compliance footer required once any promotional content is present

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/figma-build-checklist.md

@@ -0,0 +1,13 @@
+# Figma Build Verification
+
+Figma builds are verified against a procedure, not a passive reference — the checklist itself lives
+with the skill that runs it: `skills/create-design/figma-build-checklist.md`.
+
+That checklist covers the design-system context gate (Kuat vs. a different client's own system),
+live component/variable discovery, token binding, component fidelity, and a pre-handoff self-audit.
+
+## Related
+
+- [Product Design](./design.md) - Kuat layout templates and regions
+- [Component Decision Tree](./component-decision-tree.md) - Kuat-specific component selection
+- [Patterns](./patterns/) - page-type patterns Figma builds should match

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

@@ -10,6 +10,8 @@ web-product implementation live together in one document.
 |---------|-----|-------------|
 | [Sign in](./sign-in.md) | Login, registration, password flows, MFA | Single column |
 | [Complete a form](./complete-a-form.md) | Settings, multi-step forms, data entry | Varies |
+| [Browse and filter](./browse-and-filter.md) | Record lists, directories, search results | Sidebar navigation |
+| [Know the outcome of their action](./give-feedback-on-an-action.md) | Post-action feedback: confirmations, errors, toasts, system status | Varies |
 
 ## Pages
 
@@ -17,3 +19,5 @@ web-product implementation live together in one document.
 |---------|-----|-------------|
 | [Dashboard](./dashboard.md) | Analytics, data tables, metrics, reporting | Sidebar navigation |
 | [Documentation](./documentation.md) | Docs sites, knowledge bases, API reference | Sidebar + split |
+| [Section hub](./section-hub.md) | Category landing pages, navigation hubs | Sidebar navigation |
+| [Detail page](./detail-page.md) | Profiles, business units, single-record views | Sidebar navigation |

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/browse-and-filter.md

@@ -0,0 +1,226 @@
+# Browse and filter
+
+**User goal:** Find a specific item — or a small relevant subset — inside a larger collection, by
+narrowing with search terms and filters rather than scanning everything.
+
+> **Pattern:** *Help users to…* · single-medium (web-product) — concept and implementation together.
+> Covers record lists, admin directories, search results, and any table/list fronted by search and
+> filter controls.
+
+## Context
+
+Users arrive with a question ("which of these match?") rather than a fixed target. They want to narrow
+a large set quickly, understand how many results their filters produced, refine without losing their
+place, and move from a result straight into the record itself.
+
+## Principles
+
+| Principle | Implementation |
+|-----------|-----------------|
+| Filters are visible, not buried | Show active filters as removable chips, not just inside a menu |
+| Results confirm the query | Show a result count alongside the applied filters |
+| Narrowing is reversible | "Clear filters" always available; query state survives back/forward |
+| No dead ends | Empty result sets explain why and offer a way out |
+
+Success shows up as: time to find a specific record, filter usage patterns, zero-result-query rate, and
+click-through rate from result to detail.
+
+## Solution in web-product
+
+### Layout
+
+**Base Layout:** Sidebar Navigation (or Single Column full-width, for a standalone search page)
+
+#### Structure
+
+```
+┌──────┬──────────────────────────────────┐
+│      │ Header: Title + Actions          │
+│ Side ├──────────────────────────────────┤
+│ bar  │ Search + Filter Bar              │
+│      │ [Search input] [Filter▼][Filter▼]│
+│      │ Active filters: [Tag ×][Tag ×]   │
+│      ├──────────────────────────────────┤
+│      │ Results count: "128 results"     │
+│      ├──────────────────────────────────┤
+│      │ ┌─────────────────────────────┐  │
+│      │ │                             │  │
+│      │ │   Results Table / List      │  │
+│      │ │   (scrollable)              │  │
+│      │ │                             │  │
+│      │ └─────────────────────────────┘  │
+│      ├──────────────────────────────────┤
+│      │ Pagination                       │
+└──────┴──────────────────────────────────┘
+```
+
+For 10+ filter dimensions, move filters into a left-hand panel inside the content area instead of a bar:
+
+```
+┌──────┬────────┬─────────────────────────┐
+│      │ Filter │ Header: Title + Actions │
+│ Side │ Panel  ├─────────────────────────┤
+│ bar  │        │ Results count            │
+│      │ [ ] A  ├─────────────────────────┤
+│      │ [ ] B  │ Results Table / List     │
+│      │ [ ] C  │ (scrollable)             │
+│      │ Apply  ├─────────────────────────┤
+│      │ Clear  │ Pagination               │
+└──────┴────────┴─────────────────────────┘
+```
+
+#### Specifications
+
+| Element | Value |
+|---------|-------|
+| Sidebar width | 240-280px (collapsible to 64px) |
+| Filter panel width | 240-280px, when used |
+| Content padding | 24-32px |
+| Filter bar height | 48-56px |
+
+### Design
+
+#### Colour Tokens
+
+| Element | Token |
+|---------|-------|
+| Filter bar background | `bg-muted/50` or transparent |
+| Active filter chip | `bg-secondary`, `text-secondary-foreground` |
+| Results table | `bg-card`, `border` |
+| Result count text | `text-sm text-muted-foreground` |
+
+#### Filter Bar Pattern
+
+```
+┌─────────────────────────────────────────────────────┐
+│ [Search...] [Category ▼] [Status ▼]   [Clear all]  │
+└─────────────────────────────────────────────────────┘
+```
+
+- Search input leftmost
+- Dropdown/select filters follow, left to right in priority order
+- "Clear all" right-aligned, shown only when a filter is active
+
+#### Filter Panel Pattern (10+ options)
+
+- Collapsible sections per filter group
+- Checkbox groups, range sliders as needed
+- "Apply" and "Clear" actions pinned at the bottom of the panel
+
+#### Results Table/List Pattern
+
+| Element | Implementation |
+|---------|-----------------|
+| Sortable columns | Click header to sort, show arrow direction |
+| Row selection | Checkbox in first column, when bulk actions exist |
+| Row click target | Whole row navigates to detail — see [detail page](./detail-page.md) |
+| Row actions | Overflow menu or icon buttons, right-aligned |
+| Pagination | Bottom of table, with a page-size selector |
+| List view (alternative to table) | Card-per-row, for records with more visual content (avatar, thumbnail) |
+
+### Content
+
+#### Active Filter Chips
+
+**Structure:** Filter label + value, with a remove (×) affordance.
+
+**Example:** `Status: Active ×`  `Region: EMEA ×`
+
+#### Result Count
+
+| Scenario | Message |
+|----------|---------|
+| Results found | "128 results" |
+| Single result | "1 result" |
+| Filtered | "12 results for "database migration" in Engineering" |
+
+#### Empty States
+
+| Scenario | Message |
+|----------|---------|
+| No results for query | "No results match your filters" + "Clear filters" button |
+| No records exist yet | "No [records] yet" + guidance to create the first one |
+
+#### Loading States
+
+- Filter bar stays interactive while results load
+- Table: 5-10 skeleton rows
+- Show a loading indicator on re-query; never swap in stale results silently
+
+### Accessibility
+
+**Base requirements:** See [accessibility foundations](../../../accessibility/accessibility.md) and
+[web accessibility](../accessibility.md)
+
+**Scenario-specific:**
+
+| Requirement | Implementation |
+|--------------|------------------|
+| Filter state announced | Screen reader announces the result count after each filter change (`aria-live`) |
+| Keyboard filter removal | Chips removable via keyboard (Delete/Backspace when focused, or a focusable × button) |
+| Table semantics | Use a native `<table>` with `<th scope="col">`; never a div grid for tabular data |
+| Focus order | Search → filters → result count → table → pagination |
+
+### Implementation
+
+#### State Management
+
+| State | Handling |
+|-------|----------|
+| Loading | Show skeleton rows, keep filters interactive |
+| Error | Show error message with retry, preserve entered filters |
+| Empty (no matches) | Contextual empty state with "Clear filters" |
+| Empty (no records) | Contextual empty state with a create action |
+
+#### Responsive Behaviour
+
+| Breakpoint | Filter bar | Filter panel | Table |
+|------------|-------------|----------------|-------|
+| Mobile | Collapses to a single "Filters" button opening a sheet | Sheet/drawer | Card view or horizontal scroll |
+| Tablet | Wraps to two rows | Collapsible, default collapsed | Horizontal scroll |
+| Desktop | Single row | Persistent | Full table |
+
+## Best Practices
+
+### Do's
+
+1. **Show active filters as chips** - Users shouldn't have to reopen a menu to see what's applied
+2. **Confirm the result count** - Alongside the filters that produced it
+3. **Preserve query state** - In the URL, so results are shareable and survive back/forward
+4. **Debounce search input** - Query as the user types, without firing on every keystroke
+
+### Don'ts
+
+1. **Don't hide active filters** - Inside a closed dropdown with no visible indicator
+2. **Don't reset filters** - On pagination or sort
+3. **Don't block the whole page** - While results reload, only the table region should show loading
+
+### Common Mistakes
+
+| Mistake | Solution |
+|---------|----------|
+| Filters and results feel disconnected | Show result count next to active filters |
+| Losing place after navigating back | Persist filters and page in the URL |
+| No indication a query is slow | Add a loading indicator on the results region |
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Zero results | Explain why, offer "Clear filters" |
+| Very large result sets | Paginate or virtualise; never render all rows |
+| Ambiguous search term | Show "Did you mean…" or broaden automatically with a note |
+
+## Examples
+
+The sidebar-navigation frame above is the canonical instance: a search-and-filter bar above a scrollable
+results table, with pagination beneath. [Dashboard](./dashboard.md)'s data-table variant is this pattern
+applied inside a metrics-first page — same filter bar and table, reached from a dashboard rather than a
+standalone directory.
+
+## Related
+
+- [Product Design](../design.md) - Sidebar Navigation layout
+- [Dashboard](./dashboard.md) - Metrics-first pages that also use this pattern's table/filter structure
+- [Detail page](./detail-page.md) - Where a result row leads
+- [Accessibility foundations](../../../accessibility/accessibility.md) - Colour and contrast

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/complete-a-form.md

@@ -89,7 +89,7 @@ Success shows up as: form completion rate, time to complete, error rate and reco
 | Input border | `border-input` |
 | Input focus | `ring-ring` |
 | Error state | `border-destructive`, `text-destructive` |
-| Success indicator | `text-green-600` |
+| Success indicator | `text-success` |
 
 #### Typography
 

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

@@ -53,24 +53,12 @@ Dashboards benefit from persistent navigation and maximum content width.
 └──────┴──────────────────────────────────┘
 ```
 
-#### Data Table Dashboard Structure
+#### Data Table Variant
 
-```
-┌──────┬──────────────────────────────────┐
-│      │ Header: Title + Actions          │
-│ Side ├──────────────────────────────────┤
-│ bar  │ Filters Bar                      │
-│      ├──────────────────────────────────┤
-│      │ ┌─────────────────────────────┐  │
-│      │ │                             │  │
-│      │ │      Data Table             │  │
-│      │ │      (scrollable)           │  │
-│      │ │                             │  │
-│      │ └─────────────────────────────┘  │
-│      ├──────────────────────────────────┤
-│      │ Pagination                       │
-└──────┴──────────────────────────────────┘
-```
+For a data-table-first dashboard, swap the KPI/chart body for the
+[browse and filter](./browse-and-filter.md) pattern — same sidebar-navigation shell, with a
+search/filter bar above a scrollable table and pagination below. See that pattern for the filter-bar,
+filter-panel, and table specifications; they aren't repeated here.
 
 #### Specifications
 
@@ -91,7 +79,7 @@ Dashboards benefit from persistent navigation and maximum content width.
 | Card background | `bg-card` |
 | Card border | `border` |
 | Sidebar | `bg-sidebar` |
-| Positive trend | `text-green-600` / `text-green-500` (dark) |
+| Positive trend | `text-success` |
 | Negative trend | `text-destructive` |
 | Neutral | `text-muted-foreground` |
 
@@ -199,40 +187,11 @@ Dashboards benefit from persistent navigation and maximum content width.
 
 ### Implementation
 
-#### Filter Patterns
-
-**Filter Bar (above content):**
-
-```
-┌─────────────────────────────────────────────────────┐
-│ [Date Range ▼] [Category ▼] [Status ▼]    [Search] │
-└─────────────────────────────────────────────────────┘
-```
-
-- Horizontal layout
-- Date range picker left
-- Category filters middle
-- Search right
-- Background: `bg-muted/50` or transparent
-
-**Filter Sidebar (within content):**
-
-Use for complex filtering (10+ filter options):
-
-- Collapsible sections
-- Checkbox groups
-- Range sliders
-- "Apply" and "Clear" actions at bottom
-
-#### Data Table Patterns
+#### Filter and Table Patterns
 
-| Element | Implementation |
-|---------|----------------|
-| Sortable columns | Click header to sort, show arrow direction |
-| Row selection | Checkbox in first column |
-| Row actions | Overflow menu or icon buttons |
-| Pagination | Bottom of table with page size selector |
-| Empty state | Centered message in table body |
+Filter bar/panel and data table implementation live in
+[browse and filter](./browse-and-filter.md) — this dashboard's data-table variant uses that pattern
+directly rather than a separate spec.
 
 #### State Management
 
@@ -295,10 +254,12 @@ Use for complex filtering (10+ filter options):
 
 The sidebar-navigation frame above is the canonical mid-fidelity dashboard: a row of KPI cards across the
 top (4 columns on desktop), a primary chart below, and secondary charts beneath that. The data-table
-variant swaps the chart stack for a filters bar, a scrollable table, and pagination — same shell, different
-content body.
+variant swaps the chart stack for the [browse and filter](./browse-and-filter.md) pattern — same shell,
+different content body.
 
 ## Related
 
 - [Product Design](../design.md) - Sidebar Navigation layout
+- [Browse and filter](./browse-and-filter.md) - Filter bar/panel and table specification, used by the data-table variant
+- [Detail page](./detail-page.md) - Also reuses this pattern's Chart Container Pattern
 - [Accessibility foundations](../../../accessibility/accessibility.md) - Color and contrast