@intellihr/blueberry 1.0.0-beta.111 → 1.0.0-beta.113

package/.claude-dist/skills/bb-blueberry/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: bb-blueberry
+description: Use when building or modifying UI in this project — adding components, forms, buttons, inputs, layouts, icons, styling, or anything visual. This project uses @intellihr/blueberry (Mango* React components). Load this skill before touching any UI code.
+allowed-tools: Read, Glob, Grep
+---
+
+## Blueberry + Mango UI
+
+**Blueberry** (`@intellihr/blueberry`) is a React component library. It provides two things:
+
+1. **Mango wrapper components** — React wrappers around `@humanforce/mango-ui` web components, giving them a JSX-friendly API with React props, TypeScript types, and standard React event names (`onChange`, `onBlur`, etc.)
+2. **Custom components** — additional components built from scratch with Vanilla Extract CSS
+
+**Mango UI** (`@humanforce/mango-ui`) is the underlying web component library. In a Blueberry app you should always use the Blueberry wrapper (e.g. `MangoButton`) rather than the raw web component (`mgo-button`) directly.
+
+---
+
+## Priority order
+
+When building UI, follow this order strictly:
+
+1. **Mango wrapper component** — if a `Mango*` component does the job, use it
+2. **Mango utility classes** — for layout, typography, spacing, and colour reach for `mgo-*` classes via `className` before writing any CSS (see `/bb-mango-utility-classes`)
+3. **Design token CSS variables** — when utility classes don't cover the need, use `--mgo-*` tokens in Vanilla Extract styles (see `/bb-mango-styling`)
+4. **Custom CSS** — Vanilla Extract only, last resort when tokens genuinely can't do the job
+5. **No other design systems or UI libraries** — do not introduce Tailwind, MUI, Chakra, Ant Design, or any other component/CSS library
+
+---
+
+## Skills to use
+
+| Task | Skill |
+|---|---|
+| Setting up Blueberry in a new React app | `/bb-setup` |
+| Picking the right component | `/bb-mango-components` |
+| Full props + JSX examples for a specific component | `/bb-mango-<name>` (e.g. `/bb-mango-button`) |
+| Icon names and `MangoIcon` usage | `/bb-icons` |
+| Illustration names and usage | `/bb-mango-illustrations` |
+| Layout, typography, and colour utility classes | `/bb-mango-utility-classes` |
+| Design tokens, CSS variables, borders, colours, typography | `/bb-mango-styling` |
+| Form component best practices (labelling, validation, status) | `/bb-mango-forms` |
+
+---
+
+## All available component skills
+
+### Forms
+- `/bb-mango-text-field` — Single-line text input
+- `/bb-mango-textarea` — Multi-line text input
+- `/bb-mango-checkbox` — Checkbox
+- `/bb-mango-radio-group` — Radio button group
+- `/bb-mango-combobox` — Dropdown select with search
+- `/bb-mango-combobox-chip` — Multi-select chip (used in `MangoCombobox` `valueDisplay`)
+- `/bb-mango-date-field` — Date picker
+
+### Actions
+- `/bb-mango-button` — Button
+- `/bb-mango-icon-button` — Icon-only button
+- `/bb-mango-link` — Inline text link
+
+### Layout
+- `/bb-mango-card` — Elevated content surface
+- `/bb-mango-disclosure` — Collapsible section
+- `/bb-mango-heading` — Styled h1–h6 heading
+- `/bb-mango-split-panel` — Resizable split panel
+
+### Navigation
+- `/bb-mango-app-shell` — App chrome with sidebar and top bar
+- `/bb-mango-breadcrumbs` — Breadcrumb trail
+- `/bb-mango-navigation` — Sidebar navigation
+- `/bb-mango-tabs` — Tabbed content
+- `/bb-mango-workspace-badge` — Workspace/tenant badge
+- `/bb-mango-turn-back` — Error/dead-end page
+
+### Overlays
+- `/bb-mango-modal` — Dialog modal
+- `/bb-mango-wizard-modal` — Multi-step wizard modal
+- `/bb-mango-dropdown-menu` — Trigger + action menu
+- `/bb-mango-tooltip` — Hover tooltip
+
+### Feedback
+- `/bb-mango-callout` — Inline alert/notice
+- `/bb-mango-toast` — Notification toast
+- `/bb-mango-toast-stack` — Toast container
+- `/bb-mango-progress-bar` — Linear progress
+- `/bb-mango-progress-ring` — Circular progress
+- `/bb-mango-empty-state` — Empty state placeholder
+- `/bb-mango-badge` — Notification badge
+- `/bb-mango-tag` — Status label tag
+- `/bb-mango-splash` — Full-screen loading spinner
+
+### Display
+- `/bb-mango-table` — Data table (TanStack Table)
+- `/bb-mango-name-value-list` — Key/value display list
+- `/bb-mango-person` — Avatar + name + info
+- `/bb-mango-avatar` — Avatar
+- `/bb-mango-icon` — Icon by name

package/.claude-dist/skills/bb-icons/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: bb-icons
+description: Icon names and the icon system for Blueberry React apps — finding available icons, complete icon list, how icons work
+allowed-tools: Read, Glob, Grep
+---
+
+## Icons in Blueberry
+
+> **Derived from `mango-icons`** — when that skill is updated with new icon names or system changes, update this skill to match.
+
+For how to use the `MangoIcon` component or pass icons as props, see `/bb-mango-icon`.
+
+Icons render with `fill="currentColor"` — they inherit the text colour of their container and scale with font size.
+
+---
+
+### All available icon names
+
+#### Navigation & Directional
+- `back` — left chevron (previous page/step)
+- `back-far` — double left chevron (skip to start)
+- `back-first` — left chevron with stop bar (first page)
+- `next` — right chevron (next page/step)
+- `next-far` — double right chevron (skip to end)
+- `next-last` — right chevron with stop bar (last page)
+- `indicator-down` — down chevron (disclosure open, dropdown)
+- `indicator-up` — up chevron (disclosure close)
+- `home` — house
+- `external-link` — arrow pointing out of box (opens in new tab)
+- `sidebar` — sidebar panel toggle
+
+#### Actions — General
+- `add` — plus
+- `edit` — pencil
+- `delete` — trash with X
+- `copy` — copy
+- `paste` — paste
+- `close` — X mark (dismiss, remove)
+- `search` — magnifying glass
+- `filter` — funnel
+- `filter-clear` — funnel with slash
+- `upload` — arrow up from tray
+- `download` — arrow down to tray
+- `share` — share nodes
+- `send` — paper plane
+- `archive` — box taped
+- `redo` — turn right arrow
+- `undo` — turn left arrow
+- `refresh` — rotate clockwise (reload)
+- `reset` — rotate (reset to default)
+- `expand-all` — arrows expanding from line
+- `collapse-all` — arrows collapsing to lines
+- `pin` — thumbtack
+
+#### Actions — Specialised
+- `assign-person` — person with plus (assign to user)
+- `add-notification` — bell with plus
+- `start-work` — clock (clock in)
+- `end-work` — checkered flag (clock out)
+- `work-break` — mug with saucer (start break)
+- `end-work-break` — mug with saucer and slash (end break)
+- `action-magic` — lightning bolt (automated action)
+- `ai-magic` — sparkles (AI feature)
+
+#### Status & Feedback
+- `checkmark` — plain check mark
+- `status-positive` — circle with check (success)
+- `status-caution` — triangle with exclamation (warning)
+- `status-critical` — diamond with X (error/critical)
+- `status-pending` — small circle (pending/dot)
+- `status-new` — single sparkle (new item)
+- `status-no-action` — hexagon minus (no action required)
+- `info` — circle with i
+- `help` — circle with question mark
+
+#### UI Controls & Indicators
+- `more` — horizontal ellipsis (overflow menu)
+- `settings` — gear
+- `page-config` — sliders (page/view configuration)
+- `navigation-menu` — hamburger bars
+- `grip` — vertical grip dots (drag handle)
+- `apps` — grid of rounded squares (app switcher)
+- `indeterminate` — minus (checkbox indeterminate state)
+- `radio` — small filled circle (radio button indicator)
+- `show-on` — eye (show password/content)
+- `show-off` — eye with slash (hide password/content)
+- `notifications` — bell
+- `comment` — message with lines
+- `note` — memo / note
+- `task-list` — clipboard with checklist
+
+#### People & Identity
+- `person` — single user silhouette
+- `login` — arrow into bracket (sign in)
+- `logout` — arrow out of bracket (sign out)
+- `lock` — padlock
+- `language` — language/globe symbol
+
+#### Data & Analytics
+- `chart` — bar chart
+- `analytics-dashboard` — column chart (dashboard)
+- `analytics-visualisation` — pie chart
+- `date` — calendar with lines
+- `timezone` — globe (Americas)
+- `percent` — percent sign
+- `dollar-sign` — dollar sign
+- `payroll-dollar` — circle with dollar sign
+
+#### Stars & Ratings
+- `star` — filled star
+- `star-hollow` — outline star
+
+#### Media
+- `play` — play triangle
+- `pause` — pause bars
+
+#### Brand Icons
+- `brand-monogram` — Humanforce monogram
+- `brand-core-hr` — Core HR product mark
+- `brand-payroll` — Payroll product mark
+- `brand-workforce-management` — Workforce Management product mark
+- `brand-financial-wellbeing` — Financial Wellbeing product mark
+- `brand-onboarding` — Onboarding product mark
+- `brand-analytics` — Analytics product mark
+- `brand-talent` — Talent product mark
+- `brand-lms` — Learning Management System product mark
+
+---
+
+### How it works
+
+1. You provide an icon name (e.g. `"indicator-down"`)
+2. The resolver looks it up in the `icons` export from `@humanforce/mango-ui/src/icons/icons.ts`
+3. It returns a data URL: `data:image/svg+xml,${encodeURIComponent(svg)}`
+4. Renders with `fill="currentColor"` — inherits text colour automatically

package/.claude-dist/skills/bb-mango-app-shell/SKILL.md

@@ -58,7 +58,7 @@ import type { TMangoAppShell, TMangoAppShellRef } from '@intellihr/blueberry'
 ### JSX Examples
 
 ```tsx
-import { MangoAppShell, MangoNavigation } from '@intellihr/blueberry'
+import { MangoAppShell, MangoNavigation, MangoWorkspaceBadge } from '@intellihr/blueberry'
 import type { TMangoAppShellRef } from '@intellihr/blueberry'
 
 // Basic usage
@@ -68,22 +68,26 @@ import type { TMangoAppShellRef } from '@intellihr/blueberry'
   logoAlt="My App"
   logoHref="/"
   sidebar={<MangoNavigation items={navItems} />}
+  topLeft={<MangoWorkspaceBadge label="Acme Corp" />}
   topRight={<UserMenu />}
 >
   <MainContent />
 </MangoAppShell>
 
-// With imperative ref control
+// With workspace badge image and imperative ref control
 const appShellRef = React.useRef<TMangoAppShellRef>(null)
 
 <MangoAppShell
   ref={appShellRef}
-  sidebarPinned={false}
-  onSidebarOpen={() => console.log('opened')}
+  logo="/logo.svg"
+  logoShort="/logo-short.svg"
+  logoAlt="My App"
   sidebar={<MangoNavigation items={navItems} />}
+  topLeft={<MangoWorkspaceBadge label="Acme Corp" src="/workspace-logo.png" />}
+  topRight={<MangoAvatar size="small" initials="JS" label="John Smith" />}
 >
   <button onClick={() => appShellRef.current?.toggleSidebar()}>
-    Toggle
+    Toggle sidebar
   </button>
 </MangoAppShell>
 ```

package/.claude-dist/skills/bb-mango-combobox/SKILL.md

@@ -35,6 +35,7 @@ Source: `src/MangoCombobox/MangoCombobox.tsx`
 | `loading` | `boolean` | — | Show loading state in dropdown |
 | `listPlaceholder` | `string` | — | Text shown when no items match |
 | `searchCharacterMinimum` | `string` | — | Min characters before search triggers |
+| `trigger` | `ReactNode` | — | Custom trigger element. Replaces the default button, label, clear button, and chevron. `label` slot is suppressed when set. |
 | `name` | `string` | `id` | HTML name attribute |
 | `testId` | `string` | — | Test identifier |
 
@@ -51,7 +52,7 @@ import type { MgoInputEvent, MgoComboboxSearchEvent } from '@humanforce/mango-ui
 
 // Read new value from onChange
 onChange={(event: MgoInputEvent) => {
-  const newValue = event.detail.value // string or string[]
+  const newValue = event.target.value // string or string[]
 }}
 
 // Server-side search
@@ -72,7 +73,7 @@ const [value, setValue] = React.useState('')
 <MangoCombobox
   id="department"
   value={value}
-  onChange={(e) => setValue(e.detail.value as string)}
+  onChange={(e) => setValue(e.target.value as string)}
   label="Department"
   items={[
     { label: 'Engineering', value: 'engineering' },
@@ -88,7 +89,7 @@ const [values, setValues] = React.useState<string[]>([])
   id="skills"
   value={values}
   isMultiSelect
-  onChange={(e) => setValues(e.detail.value as string[])}
+  onChange={(e) => setValues(e.target.value as string[])}
   label="Skills"
   items={skillOptions}
 />
@@ -97,7 +98,7 @@ const [values, setValues] = React.useState<string[]>([])
 <MangoCombobox
   id="employee"
   value={selectedEmployee}
-  onChange={(e) => setSelectedEmployee(e.detail.value as string)}
+  onChange={(e) => setSelectedEmployee(e.target.value as string)}
   onSearchChange={(e) => fetchEmployees(e.detail.value)}
   searchMode="server"
   label="Employee"
@@ -110,7 +111,7 @@ const [values, setValues] = React.useState<string[]>([])
 <MangoCombobox
   id="role"
   value={role}
-  onChange={(e) => setRole(e.detail.value as string)}
+  onChange={(e) => setRole(e.target.value as string)}
   label="Role"
   status="critical"
   statusText="Please select a role"
@@ -128,7 +129,7 @@ import { MangoCombobox, MangoComboboxChip } from '@intellihr/blueberry'
   id="team-members"
   value={selectedIds}
   isMultiSelect
-  onChange={(e) => setSelectedIds(e.detail.value as string[])}
+  onChange={(e) => setSelectedIds(e.target.value as string[])}
   label="Team members"
   items={memberItems}
   valueDisplay={selectedIds.map((id) => {
@@ -147,9 +148,28 @@ import { MangoCombobox, MangoComboboxChip } from '@intellihr/blueberry'
 />
 ```
 
+### Custom trigger
+
+```tsx
+// Replace the default button with any element (e.g. a MangoButton or MangoIconButton)
+<MangoCombobox
+  id="filter"
+  value={value}
+  onChange={(e) => setValue(e.target.value as string)}
+  trigger={<MangoButton variant="secondary" icon="filter">Filter</MangoButton>}
+  items={filterOptions}
+/>
+```
+
+When `trigger` is provided:
+- The default field button, label, clear button, and chevron are all replaced
+- The `label` prop/slot is suppressed — do not pass `label` alongside `trigger`
+- ARIA is applied automatically by mango-ui
+
 ### Notes
 
 - `items` is an array prop — do not use children for options
-- `onChange` receives `MgoInputEvent`, not a standard React change event — read `event.detail.value`
+- `onChange` receives `MgoInputEvent` — read `event.target.value` for the selected value (string or string[])
 - `valueDisplay` is used to customise multi-select chip rendering; use `MangoComboboxChip` for person-like chips
 - Always hoists the dropdown to avoid z-index clipping
+- `trigger` replaces the entire default trigger — do not combine with `label`

package/.claude-dist/skills/bb-mango-components/SKILL.md

@@ -80,6 +80,7 @@ Use this skill to pick the right component. Then load the component-specific ski
 | `MangoWizardModal` | Multi-step wizard modal. `currentStep` is 1-indexed. |
 | `MangoDropdownMenu` | Trigger + action menu. `trigger` + `items[]` required. |
 | `MangoTooltip` | Hover tooltip. `trigger` + `content` required. |
+| `MangoPopover` | Click-triggered floating panel. `trigger` + `children` required. Optional `header`/`footer`. `ref` gives imperative `show()`/`hide()`. |
 
 ---
 
@@ -94,7 +95,9 @@ Use this skill to pick the right component. Then load the component-specific ski
 | `MangoProgressRing` | Circular progress. `value` (0–100) required. |
 | `MangoEmptyState` | Empty state placeholder. `title` required. |
 | `MangoBadge` | Notification badge. Passed as `badge` prop to Button/IconButton/Navigation items. |
-| `MangoTag` | Status tag. 12 tone options. |
+| `MangoTag` | Status tag. 14 tone options. Optional `icon` prop. |
+| `MangoPipeline` | Filter bar with stage/status counts. `items[]` + `onChange` required. `variant`: tile or compact. |
+| `MangoCopyButton` | Clipboard icon button. `value` required. Auto success/error feedback. |
 | `MangoSplash` | Full-screen loading spinner. Requires parent with defined height. |
 
 ---
@@ -107,7 +110,7 @@ Use this skill to pick the right component. Then load the component-specific ski
 | `MangoNameValueList` | Key/value display list. `items[]` required. |
 | `MangoPerson` | Avatar + name + info. `name` required. |
 | `MangoAvatar` | Avatar. `label` (accessibility) required. |
-| `MangoIcon` | Icon by name. Use `/mango-icons` skill for icon names. |
+| `MangoIcon` | Icon by name. Use `/bb-icons` skill for icon names. |
 
 ---
 
@@ -117,7 +120,8 @@ Every component exports a type alias: `TMangoButton`, `TMangoTextField`, etc.
 Import: `import type { TMangoButton } from '@intellihr/blueberry'`
 
 Exceptions:
-- `MangoBadge`, `MangoCallout`, `MangoHeading`, `MangoTag`, `MangoToast`, `MangoToastStack`, `MangoTurnBack` — no exported type alias
+- `MangoBadge`, `MangoCallout`, `MangoHeading`, `MangoToast`, `MangoToastStack`, `MangoTurnBack` — no exported type alias
 - `MangoTooltip` — exports `IMangoTooltip` (not `TMangoTooltip`)
 - `MangoWizardModal` — exports 4 types: `TMangoWizardModal`, `TMangoWizardModalStepItem`, `TMangoWizardModalStep`, `TMangoWizardModalStepLabel`
 - `MangoAppShell` — exports `TMangoAppShell` + `TMangoAppShellRef`
+- `MangoPopover` — exports `TMangoPopover` + `TMangoPopoverRef`

package/.claude-dist/skills/bb-mango-copy-button/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: bb-mango-copy-button
+description: MangoCopyButton React component — clipboard button with automatic success/error feedback states and tooltip
+allowed-tools: Read, Glob, Grep
+---
+
+## `MangoCopyButton`
+
+Import: `import { MangoCopyButton } from '@intellihr/blueberry'`
+Source: `src/MangoCopyButton/MangoCopyButton.tsx`
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Text to copy to clipboard |
+| `from` | `string` | — | ID of another DOM element to copy from. Supports `id` (text content), `id.property`, or `id[attribute]` |
+| `disabled` | `boolean` | — | Disabled state |
+| `copyLabel` | `string` | — | Tooltip label in default state (default: i18n "Copy") |
+| `successLabel` | `string` | — | Tooltip label after successful copy (default: i18n "Copied") |
+| `errorLabel` | `string` | — | Tooltip label on copy failure (default: i18n "Error") |
+| `tooltipPlacement` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Tooltip position |
+| `onCopy` | `(event: MgoCopyEvent) => void` | — | Called when text is successfully copied |
+| `onError` | `(event: MgoErrorEvent) => void` | — | Called when copy fails |
+| `testId` | `string` | — | Test identifier |
+
+### Exported type
+
+```ts
+import type { TMangoCopyButton } from '@intellihr/blueberry'
+```
+
+### JSX Examples
+
+```tsx
+import { MangoCopyButton } from '@intellihr/blueberry'
+
+// Basic
+<MangoCopyButton value="Text to copy" />
+
+// With custom labels
+<MangoCopyButton
+  value="user@example.com"
+  copyLabel="Copy email"
+  successLabel="Copied!"
+  errorLabel="Failed to copy"
+/>
+
+// Copy from another DOM element by ID (text content)
+<code id="install-cmd">npm install @intellihr/blueberry</code>
+<MangoCopyButton from="install-cmd" copyLabel="Copy command" />
+
+// Copy a property of another element
+<MangoCopyButton from="my-input.value" copyLabel="Copy" />
+
+// With copy callback
+<MangoCopyButton
+  value={apiKey}
+  copyLabel="Copy API key"
+  onCopy={(e) => console.log('Copied:', e.detail.value)}
+/>
+```
+
+### Notes
+
+- Renders as an icon button — no label text is shown; use `copyLabel` for the tooltip
+- Either `value` or `from` must be provided
+- `from` supports: plain `id` (copies text content), `id.property` (property access), `id[attribute]` (attribute access)
+- `onCopy` event detail contains `{ value: string }` — the copied text
+- Feedback state (success/error icon) reverts automatically after a short time

package/.claude-dist/skills/bb-mango-forms/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: bb-mango-forms
+description: Best practices for Blueberry Mango form components — labelling, validation status, help text, required/disabled, form methods. Read this before implementing any form field.
+allowed-tools: Read, Glob, Grep
+---
+
+## Blueberry Mango Form Best Practices
+
+> **Derived from `mango-forms`** — when that skill is updated, sync the relevant parts here, replacing web component/Angular patterns with React/Blueberry equivalents.
+
+Applies to: `MangoTextField`, `MangoTextarea`, `MangoDateField`, `MangoCombobox`, `MangoCheckbox`, `MangoRadioGroup`
+
+---
+
+### Labelling
+
+**Always provide a `label` prop. Never add a native `<label>` element.**
+
+Every Mango wrapper renders its own label internally. Adding a separate native `<label>` will produce a duplicate and break accessibility.
+
+```tsx
+// ❌ WRONG — do not do this
+<label htmlFor="name">Full name</label>
+<MangoTextField id="name" />
+
+// ✅ CORRECT
+<MangoTextField label="Full name" />
+```
+
+---
+
+### Validation Status
+
+All form components share the same `status` / `statusText` props.
+
+| Prop         | Type     | Values                                          | Description                                        |
+| ------------ | -------- | ----------------------------------------------- | -------------------------------------------------- |
+| `status`     | `string` | `'critical'` \| `'caution'` \| `'positive'` \| `''` | Visual validation state                        |
+| `statusText` | `string` | any                                             | Message shown below the field with a status icon   |
+
+**When to use each value:**
+
+- `critical` — validation error, field is invalid
+- `caution` — warning, field is valid but needs attention
+- `positive` — explicit confirmation the value is valid
+- `''` (empty, default) — neutral, no validation state shown
+
+**Always pair `status` with `statusText`** so the user knows what to fix:
+
+```tsx
+// ❌ WRONG — status with no explanation
+<MangoTextField label="Email" status="critical" />
+
+// ✅ CORRECT
+<MangoTextField
+  label="Email"
+  status="critical"
+  statusText="Enter a valid email address."
+/>
+```
+
+---
+
+### Help Text
+
+Use `helpText` for persistent instructional text shown below the field. It is always visible, unlike `statusText` which only shows when a status is set.
+
+```tsx
+<MangoTextField
+  label="Username"
+  helpText="Must be 3–20 characters. Letters, numbers, and underscores only."
+/>
+```
+
+Do not use `helpText` for validation errors — use `status` + `statusText` for that.
+
+---
+
+### Event Handling
+
+Form components expose React-style event props. For components that wrap `mgo-*` web components, events are prefixed with `onMgo`:
+
+```tsx
+// MangoTextField
+<MangoTextField
+  label="Name"
+  onChange={(value: string) => setName(value)}
+/>
+
+// MangoDateField
+<MangoDateField
+  label="Start date"
+  onChange={(isoValue: string) => setDate(isoValue)}
+/>
+
+// MangoCombobox
+<MangoCombobox
+  label="Status"
+  options={options}
+  onChange={(value) => setValue(value)}
+/>
+```
+
+Check each component's own skill (`/bb-mango-text-field`, `/bb-mango-date-field`, etc.) for the exact event prop signature.
+
+---
+
+### Icon Props
+
+Some form components accept `leadingIcon` / `trailingIcon` props. These always expect an **icon name string** from the Mango icon set — not a component or element.
+
+```tsx
+// ✅ CORRECT — pass an icon name string
+<MangoTextField label="Search" leadingIcon="search" />
+
+// ❌ WRONG — do not pass a component
+<MangoTextField label="Search" leadingIcon={<MangoIcon name="search" />} />
+```
+
+For valid icon names, see the `/bb-icons` skill.
+
+---
+
+### Required, Disabled, Readonly
+
+| Prop       | Behaviour                                                                    |
+| ---------- | ---------------------------------------------------------------------------- |
+| `required` | Marks the field as required (shown visually and enforced in form submission) |
+| `disabled` | Field is non-interactive and excluded from form submission                   |
+| `readonly` | Field is non-interactive but included in form submission                     |
+
+---
+
+### Form Validation Methods
+
+Mango form components implement the Constraint Validation API. Access them via a React ref:
+
+```tsx
+import { useRef } from 'react'
+import { MangoTextField } from '@intellihr/blueberry'
+
+const fieldRef = useRef<HTMLElement>(null)
+
+// After a server-side error
+fieldRef.current?.setCustomValidity('This username is already taken.')
+fieldRef.current?.reportValidity()
+
+// To clear
+fieldRef.current?.setCustomValidity('')
+```
+
+| Method                       | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `checkValidity()`            | Returns `true` if valid, `false` if not (no UI shown)          |
+| `reportValidity()`           | Like `checkValidity()` but also shows browser validation UI    |
+| `setCustomValidity(message)` | Set a custom validation message. Pass `''` to clear.           |

package/.claude-dist/skills/bb-mango-heading/SKILL.md

@@ -37,3 +37,4 @@ import { MangoHeading } from '@intellihr/blueberry'
 
 - `level` is a **string** (`'1'` through `'6'`), not a number — pass `level="2"` not `level={2}`
 - Use `MangoHeading` instead of raw `<h1>`–`<h6>` elements to get consistent Mango UI typography
+- **Use sparingly** — `MangoHeading` is intended for main page headings and major section titles. For body text, labels, captions, and supporting text, prefer Mango utility classes (`mgo-text-m`, `mgo-text-s`, `mgo-weight-strong`, etc.) or rely on default slot styling provided by the parent component.

package/.claude-dist/skills/bb-mango-icon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bb-mango-icon
-description: MangoIcon React component — renders an icon by name; use /mango-icons skill for icon names
+description: MangoIcon React component — renders an icon by name; use /bb-icons skill for icon names
 allowed-tools: Read, Glob, Grep
 ---
 
@@ -40,6 +40,6 @@ import { MangoIcon } from '@intellihr/blueberry'
 ### Notes
 
 - The `icon` prop maps to the `name` attribute on the underlying `mgo-icon` web component
-- Use the `/mango-icons` skill to look up available icon names
+- Use the `/bb-icons` skill to look up available icon names
 - Do not set a `library` attribute — the correct library is handled automatically
 - For icon-only buttons, use `MangoIconButton` instead