@iress-oss/ids-components 6.0.0-beta.7 → 6.0.0-beta.8

package/.ai/components/avatar.md

@@ -0,0 +1,178 @@
+# Avatar
+
+Avatars display user identity in a circular frame, with optional badge and type indicators.
+
+> **Component:** `import { IressAvatar } from '@iress-oss/ids-components'`
+> **Storybook:** [Avatar in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-avatar--docs)
+
+## Quick Start
+
+```tsx
+import { IressAvatar } from '@iress-oss/ids-components';
+
+<IressAvatar>
+  BC
+</IressAvatar>
+```
+
+## When to use
+
+Use avatars to **represent users or entities** in your interface:
+
+- Displaying user profile identity (initials, icons, or images)
+- Showing assignment or ownership of items
+- Indicating shared/joint entities with the `type` icon
+- Stacking multiple users with `AvatarGroup`
+
+## Examples
+
+### Badge
+
+Pass a `badge` object with an `icon` name and optional `mode` colour to show an indicator at the top-right.
+
+```tsx
+<IressAvatar>
+  BC
+</IressAvatar>
+```
+
+[View "WithBadge" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-avatar--with-badge)
+
+### Badge with colour
+
+The badge `mode` accepts any value from the data palette (10-90) or system status spectrum (`danger`, `info`, `success`, `warning`).
+
+```tsx
+<IressAvatar>
+  BC
+</IressAvatar>
+```
+
+[View "WithBadgeColor" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-avatar--with-badge-color)
+
+### Type
+
+Pass a `type` object with an `icon` name to display a secondary circle at the bottom-right, useful for indicating shared entities or roles.
+
+```tsx
+<IressAvatar>
+  J&C
+</IressAvatar>
+```
+
+[View "WithType" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-avatar--with-type)
+
+### Mode
+
+The `mode` prop controls the avatar's background and text colour using the data palette (10-90) or system status colours.
+
+```tsx
+<IressInline gap="xs">
+<IressAvatar mode={10}>
+10
+</IressAvatar>
+<IressAvatar mode={20}>
+20
+</IressAvatar>
+<IressAvatar mode={30}>
+30
+</IressAvatar>
+<IressAvatar mode={40}>
+40
+</IressAvatar>
+<IressAvatar mode={50}>
+<IressIcon name="star" filled aria-label="I am a star" />
+</IressAvatar>
+</IressInline>
+```
+
+[View "Mode" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-avatar--mode)
+
+### Compact
+
+Set `compact={true}` for a smaller avatar with a white stroke border, designed for stacking.
+
+```tsx
+<IressAvatar compact>
+  MT
+</IressAvatar>
+```
+
+[View "Compact" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-avatar--compact)
+
+## Avatar Group
+
+Use `IressAvatarGroup` to stack multiple avatars with proper overlap and z-ordering. The first avatar appears in the foreground.
+
+```tsx
+<IressAvatarGroup compact>
+<IressAvatar mode={30}>MT</IressAvatar>
+<IressAvatar mode={20}>HM</IressAvatar>
+<IressAvatar mode={50}>TL</IressAvatar>
+</IressAvatarGroup>
+```
+
+[View "Compact" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-group--compact)
+
+### Max avatars
+
+Set `max` to limit visible avatars. An overflow indicator shows the remaining count.
+
+```tsx
+<IressAvatarGroup compact max={3}>
+<IressAvatar mode={30}>MT</IressAvatar>
+<IressAvatar mode={20}>HM</IressAvatar>
+<IressAvatar mode={50}>TL</IressAvatar>
+<IressAvatar mode={10}>JD</IressAvatar>
+<IressAvatar mode={40}>AB</IressAvatar>
+</IressAvatarGroup>
+```
+
+[View "MaxAvatars" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-group--max-avatars)
+
+### Custom overflow label
+
+Pass a render prop to `overflowLabel` for full control over the overflow indicator.
+
+```tsx
+<IressAvatarGroup
+compact
+max={2}
+overflowLabel={(count) => `+${count} awesome users`}
+>
+<IressAvatar mode={30}>MT</IressAvatar>
+<IressAvatar mode={20}>HM</IressAvatar>
+<IressAvatar mode={50}>TL</IressAvatar>
+<IressAvatar mode={10}>JD</IressAvatar>
+</IressAvatarGroup>
+```
+
+[View "CustomOverflowLabel" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-group--custom-overflow-label)
+
+## Testing
+
+Query avatars by their accessible role and label:
+
+```tsx
+// Accessible name defaults to text content
+// <IressAvatar>LS</IressAvatar>
+const avatar = screen.getByRole('img', { name: 'LS' });
+
+// Or use aria-label for a custom accessible name
+// <IressAvatar aria-label="Luke Skywalker">LS</IressAvatar>
+const avatar = screen.getByRole('img', { name: 'Luke Skywalker' });
+```
+
+## Props
+
+- **Type:** `IressAvatarProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Avatar/Avatar.d.ts`
+
+```typescript
+import type { IressAvatarProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-avatar--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-avatar--docs)*

package/.ai/components/input.md

@@ -93,9 +93,7 @@ const { success } = useToaster();
           {...args}
           onChange={(e) =>
             success({
-              content: `File uploaded: ${
-                (e.target as HTMLInputElement).files?.[0].name
-              }`,
+              content: `File uploaded: ${e.target.files?.[0].name}`,
             })
           }
         />

package/.ai/index.json

@@ -30,6 +30,15 @@
         "category": "component",
         "storybookUrl": "https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete-recipes--docs"
       },
+      {
+        "name": "Avatar",
+        "description": "Avatars display user identity in a circular frame, with optional badge and type indicators.",
+        "path": "components/avatar.md",
+        "category": "component",
+        "storybookUrl": "https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-avatar--docs",
+        "propsType": "IressAvatarProps",
+        "typeDeclPath": "dist/components/Avatar/Avatar.d.ts"
+      },
       {
         "name": "Button",
         "description": "A button is a clickable item used to perform an action.",

package/.ai/skills/figma-to-ids.md

@@ -109,6 +109,8 @@ When mapping Figma components to IDS, read references/component-mapping.md for t
 | Table              | `IressTable`                                 | Data-driven: `rows`, `columns`, `caption` props |
 | Tag                | `IressTag`                                   | `bordered` for visible border; `element="button"` for clickable, `element="a"` for link; `onClick` alone also auto-renders as button |
 | Pill               | `IressPill`                                  |                            |
+| Avatar             | `IressAvatar`                                | `mode` for colour, `badge` for status indicator, `type` for secondary icon |
+| CompactAvatar      | `IressAvatarGroup` + `IressAvatar compact`   | `max` limits visible; `overflowLabel` render prop for overflow |
 | Tooltip            | `IressTooltip`                               |                            |
 | Icon               | `IressIcon name="..."`                       | Material Symbols name      |
 | Divider            | `IressDivider`                               |                            |
@@ -134,8 +136,8 @@ Map Figma fill/stroke colours to IDS colour tokens:
 | Neutral/10 `#FFFFFF`      | `colour.neutral.10`          | `--iress-colour-neutral-10`          |
 | Neutral/20 `#F5F6F8`      | `colour.neutral.20`          | `--iress-colour-neutral-20`          |
 | Neutral/30 `#E2E6EA`      | `colour.neutral.30`          | `--iress-colour-neutral-30`          |
-| Neutral/80 `#384666`      | `colour.neutral.80`          | `--iress-colour-neutral-80`          |
-| Neutral/90 `#141F4D`      | `colour.neutral.90`          | `--iress-colour-neutral-90`          |
+| Neutral/80 `#141F4D`      | `colour.neutral.80`          | `--iress-colour-neutral-80`          |
+| Neutral/90 `#141F4D`      | `colour.neutral.90` (alias)  | `--iress-colour-neutral-90`          |
 | Success/Fill `#37C49C`    | `colour.system.success.fill` | `--iress-colour-system-success-fill` |
 | Danger/Fill `#C21010`     | `colour.system.danger.fill`  | `--iress-colour-system-danger-fill`  |
 | Warning/Fill `#F0AD03`    | `colour.system.warning.fill` | `--iress-colour-system-warning-fill` |
@@ -161,6 +163,10 @@ IDS base spacing unit = 4px (0.25rem). Map Figma pixel values:
 
 > For values not on the 4px grid, round to the nearest token value.
 
+> **Neutral alias note:** `colour.neutral.90` is a backwards-compatible alias
+> of `colour.neutral.80`. Prefer `colour.neutral.80` in generated IDS code, but
+> map either Figma `Neutral/80` or `Neutral/90` to the same `#141F4D` value.
+
 ## Border Radius
 
 | Figma px | IDS Token  | System Usage        |
@@ -193,6 +199,11 @@ Prefer semantic HTML elements via the `element` prop — they convey meaning to
 
 > **Tip:** When translating Figma frames that contain mixed or unstructured text (e.g. CMS content, markdown, rich text blocks), wrap the content in `IressText` and nest native HTML elements (`<p>`, `<strong>`, `<a>`, `<ul>`, etc.) inside it. This is an allowed pattern that lets `IressText` apply consistent typography while preserving the original content structure.
 
+For neutral text colours, treat `colour.neutral.90` as a backwards-compatible
+alias of `colour.neutral.80` (both resolve to `#141F4D`). Prefer
+`colour.neutral.80` in new IDS implementations, but handle either token name
+when translating older Figma files.
+
 ## Translation Examples
 
 ### Figma: Login Form Frame

package/.ai/skills/ui-translation.md

@@ -69,6 +69,8 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 | Icon                 | `IressIcon`                 | `<IressIcon name="settings" />`                                                                             |
 | Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`; use `bordered` for visible-border style; use `element="button"` for clickable tag, `element="a"` for link tag; `onClick` alone also auto-renders as `<button>` |
 | Pill                 | `IressPill`                 | `<IressPill>Category</IressPill>`                                                                           |
+| Avatar               | `IressAvatar`               | `<IressAvatar aria-label="Jane Doe" mode={10}>JD</IressAvatar>`; use `badge` for status indicators, `type` for secondary icons |
+| Avatar group         | `IressAvatarGroup`          | `<IressAvatarGroup compact max={3}><IressAvatar>...</IressAvatar></IressAvatarGroup>`; stacks avatars with overlap and overflow |
 | Tooltip              | `IressTooltip`              | `<IressTooltip content="Help text"><IressButton>Hover me</IressButton></IressTooltip>`                      |
 
 ## Overlays & Navigation
@@ -228,6 +230,8 @@ When you need to find the right IDS component for a UI element, read references/
 | Icon                 | `IressIcon`                 | `<IressIcon name="settings" />`                                                                             |
 | Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`; use `bordered` for visible-border style; use `element="button"` for clickable tag, `element="a"` for link tag; `onClick` alone also auto-renders as `<button>` |
 | Pill                 | `IressPill`                 | `<IressPill>Category</IressPill>`                                                                           |
+| Avatar               | `IressAvatar`               | `<IressAvatar aria-label="Jane Doe" mode={10}>JD</IressAvatar>`; use `badge` for status indicators, `type` for secondary icons |
+| Avatar group         | `IressAvatarGroup`          | `<IressAvatarGroup compact max={3}><IressAvatar>...</IressAvatar></IressAvatarGroup>`; stacks avatars with overlap and overflow |
 | Tooltip              | `IressTooltip`              | `<IressTooltip content="Help text"><IressButton>Hover me</IressButton></IressTooltip>`                      |
 
 ## Overlays & Navigation