ionbase-ui 0.26.0 → 0.27.0

package/dist/figma-map.json

@@ -1,8 +1,8 @@
 {
   "package": "ionbase-ui",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "figmaFile": "gaLbGd0QNb1fUl6BjSpfBA",
-  "figmaExported": "2026-08-21",
+  "figmaExported": "2026-08-27",
   "usage": "Given a Figma node id or component name, look it up here for the React component, its import, and how each Figma property maps onto a real prop. Every mapping is verified against both the Figma export and the TypeScript API on each build.",
   "generated": "by scripts/verify-figma-map.mjs — do not edit",
   "byNodeId": {
@@ -729,6 +729,17 @@
         },
         "Icon#74:50": {
           "prop": "icon"
+        },
+        "Show Ring#1009:0": {
+          "prop": "ring"
+        },
+        "Show Top Indicator#1009:25": {
+          "prop": "topIndicator",
+          "note": "Figma needs a boolean because the intent lives on the nested Status Indicator instance; code takes the intent itself, so passing one is what shows the mark. The drawn instance is Intent=Primary with its check glyph, which is what `topIndicator=\"primary\"` renders."
+        },
+        "Show Bottom Indicator#1009:50": {
+          "prop": "bottomIndicator",
+          "note": "As the top indicator — the intent comes from the nested Status Indicator, which a boolean cannot carry. The drawn instance is Intent=Success with no glyph."
         }
       }
     },
@@ -770,6 +781,41 @@
         }
       }
     },
+    "1054:305": {
+      "figmaComponent": "Avatar Gradient",
+      "figmaNodeId": "1054:305",
+      "figmaPage": "Avatar",
+      "component": "AvatarGradient",
+      "import": "import { AvatarGradient } from 'ionbase-ui';",
+      "docs": "components/avatar-gradient/index.html.md",
+      "props": {
+        "Size": {
+          "prop": "size",
+          "values": {
+            "Mini": "mini",
+            "Small": "sm",
+            "Medium": "md",
+            "Large": "lg"
+          }
+        },
+        "Color": {
+          "prop": "color",
+          "values": {
+            "Slate": "slate",
+            "Blue": "blue",
+            "Violet": "violet",
+            "Pink": "pink",
+            "Orange": "orange",
+            "Green": "green",
+            "Red": "red",
+            "Light": "light"
+          }
+        },
+        "Initials#1054:32": {
+          "prop": "initials"
+        }
+      }
+    },
     "126:22724": {
       "figmaComponent": "Border",
       "figmaNodeId": "126:22724",
@@ -1745,6 +1791,17 @@
         },
         "Icon#74:50": {
           "prop": "icon"
+        },
+        "Show Ring#1009:0": {
+          "prop": "ring"
+        },
+        "Show Top Indicator#1009:25": {
+          "prop": "topIndicator",
+          "note": "Figma needs a boolean because the intent lives on the nested Status Indicator instance; code takes the intent itself, so passing one is what shows the mark. The drawn instance is Intent=Primary with its check glyph, which is what `topIndicator=\"primary\"` renders."
+        },
+        "Show Bottom Indicator#1009:50": {
+          "prop": "bottomIndicator",
+          "note": "As the top indicator — the intent comes from the nested Status Indicator, which a boolean cannot carry. The drawn instance is Intent=Success with no glyph."
         }
       }
     },
@@ -1786,6 +1843,41 @@
         }
       }
     },
+    "Avatar Gradient": {
+      "figmaComponent": "Avatar Gradient",
+      "figmaNodeId": "1054:305",
+      "figmaPage": "Avatar",
+      "component": "AvatarGradient",
+      "import": "import { AvatarGradient } from 'ionbase-ui';",
+      "docs": "components/avatar-gradient/index.html.md",
+      "props": {
+        "Size": {
+          "prop": "size",
+          "values": {
+            "Mini": "mini",
+            "Small": "sm",
+            "Medium": "md",
+            "Large": "lg"
+          }
+        },
+        "Color": {
+          "prop": "color",
+          "values": {
+            "Slate": "slate",
+            "Blue": "blue",
+            "Violet": "violet",
+            "Pink": "pink",
+            "Orange": "orange",
+            "Green": "green",
+            "Red": "red",
+            "Light": "light"
+          }
+        },
+        "Initials#1054:32": {
+          "prop": "initials"
+        }
+      }
+    },
     "Border": {
       "figmaComponent": "Border",
       "figmaNodeId": "126:22724",
@@ -2044,7 +2136,8 @@
     "Menu Section Title": "No code counterpart yet. It is a heading inside a menu surface; nothing renders it.",
     "Line": "An internal part of the Scroll Progress rail, not a component a caller composes.",
     "Progress": "As Line — internal to ScrollProgress.",
-    "Progress Heading": "As Line — internal to ScrollProgress."
+    "Progress Heading": "As Line — internal to ScrollProgress.",
+    "Status Indicator": "The dot Avatar draws in its corners, and nothing else composes it. Avatar owns both instances and exposes them as `topIndicator` / `bottomIndicator`, so there is no standalone component for a caller to place — the same call Line, Progress and Progress Heading get for being internal to ScrollProgress. Map it the day a screen needs a status dot away from an avatar."
   },
   "codeUnmapped": {
     "Icon": "Figma has no Icon component; icons are vector assets dropped into slots. Icon is the React wrapper that gives any of them a size rung and an accessible label, so there is nothing on the Figma side to point at.",

package/dist/meta/Avatar.json

@@ -2,7 +2,7 @@
   "name": "Avatar",
   "source": "src/components/Avatar.tsx",
   "propsType": "AvatarProps",
-  "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
+  "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.\n\nTHE MEDIA IS A CHILD, AND IT HAS TO BE\n\nThe box that clips the image is `.ion-avatar__media`, not the root. The root\ncannot clip: a corner indicator sits outside a circle's clip path and would\nbe sliced in half by the `overflow: hidden` that crops the photo. Figma\ndraws exactly this — an unclipped frame holding a clipped `Media` child and\nthe indicators as its siblings.",
   "import": "import { Avatar } from 'ionbase-ui';",
   "status": "stable",
   "summary": "A person or entity marker. Content is chosen by precedence — image, then initials, then icon — not by a type prop.",
@@ -42,21 +42,67 @@
       "square": {
         "use": "organisations, projects, workspaces and other non-human entities"
       }
+    },
+    "topIndicator": {
+      "neutral": {
+        "use": "no state, or a state this system has no colour for"
+      },
+      "primary": {
+        "use": "attention rather than health — a request, an invite, a mention"
+      },
+      "success": {
+        "use": "online, available, verified, complete"
+      },
+      "warning": {
+        "use": "away, idle, needs attention but is not broken"
+      },
+      "error": {
+        "use": "offline, blocked, failed"
+      },
+      "information": {
+        "use": "a neutral fact about the person — a role or a badge, not a state"
+      }
+    },
+    "bottomIndicator": {
+      "neutral": {
+        "use": "no state, or a state this system has no colour for"
+      },
+      "primary": {
+        "use": "attention rather than health — a request, an invite, a mention"
+      },
+      "success": {
+        "use": "online, available, verified, complete"
+      },
+      "warning": {
+        "use": "away, idle, needs attention but is not broken"
+      },
+      "error": {
+        "use": "offline, blocked, failed"
+      },
+      "information": {
+        "use": "a neutral fact about the person — a role or a badge, not a state"
+      }
     }
   },
   "slots": {
     "icon": {
       "accepts": "Icon",
       "note": "the last fallback — rendered only when there is neither `src` nor `initials`"
+    },
+    "topIndicatorIcon": {
+      "accepts": "Icon",
+      "note": "replaces the top indicator's default check glyph. The bottom indicator takes no glyph — Figma draws it bare, and at Mini it is 8px, which nothing legible fits inside."
     }
   },
   "a11y": {
     "guarantees": [
       "`alt` falls back to `initials`, so the avatar is never announced as an unlabelled image",
-      "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph"
+      "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph",
+      "indicator labels are announced wherever they land: folded into the avatar's own `aria-label` when there is no image (the root is `role=\"img\"` and therefore a leaf), and carried as hidden text inside each indicator when there is"
     ],
     "requires": [
-      "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\""
+      "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\"",
+      "`topIndicatorLabel` / `bottomIndicatorLabel` on any indicator that carries meaning. An indicator with no label is decorative, which is the right answer only when the same fact is already stated in text beside it."
     ]
   },
   "antiPatterns": [
@@ -68,43 +114,75 @@
       "dont": "using Avatar as a button",
       "do": "put the Avatar inside a Button or Link",
       "why": "Avatar renders a <span> with no role and takes no focus"
+    },
+    {
+      "dont": "using an indicator's colour as the only carrier of a status",
+      "do": "pass `topIndicatorLabel` / `bottomIndicatorLabel`, or state the status in text nearby",
+      "why": "WCAG 1.4.1. A green dot and a red dot are the same dot to a screen reader, and to a good share of sighted users too"
+    },
+    {
+      "dont": "reaching for `ring` to mean selected or focused",
+      "why": "it is a static brand ring from the design, not a focus indicator. Focus belongs on whatever interactive element wraps the avatar, and that element draws its own"
     }
   ],
   "stylesheet": "src/styles/avatar.css",
   "tokens": [
     "--border-strong",
+    "--border-subtle",
     "--border-width-default",
+    "--border-width-thick",
     "--font-family-sans",
     "--font-weight-medium",
+    "--font-weight-regular",
     "--icon-size-2xs",
     "--icon-size-lg",
     "--icon-size-md",
     "--icon-size-sm",
     "--icon-tertiary",
+    "--ion-avatar-border",
     "--ion-avatar-font-size",
+    "--ion-avatar-font-weight",
     "--ion-avatar-group-overlap",
     "--ion-avatar-icon",
+    "--ion-avatar-indicator-icon",
+    "--ion-avatar-indicator-ring",
+    "--ion-avatar-indicator-size",
     "--ion-avatar-line-height",
     "--ion-avatar-radius",
+    "--ion-avatar-ring-width",
     "--ion-avatar-size",
+    "--ion-avatar-surface",
     "--radius-full",
     "--radius-md",
     "--radius-sm",
     "--radius-xs",
+    "--ring-offset",
+    "--spacing-12",
+    "--spacing-14",
+    "--spacing-16",
     "--spacing-24",
     "--spacing-32",
     "--spacing-40",
     "--spacing-48",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-information",
+    "--surface-inverse",
     "--surface-muted",
+    "--surface-placeholder",
+    "--surface-primary",
+    "--surface-success",
+    "--surface-warning",
+    "--text-on-color",
     "--text-tertiary",
     "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
     "--type-body-line-height",
     "--type-body-sm",
     "--type-body-sm-line-height",
     "--type-caption",
-    "--type-caption-line-height",
-    "--type-h5",
-    "--type-h5-line-height"
+    "--type-caption-line-height"
   ],
   "props": {
     "size": {
@@ -152,10 +230,62 @@
       "required": false,
       "origin": "own",
       "description": "Figma's `Type=Icon`. Rendered when there is neither `src` nor `initials`."
+    },
+    "ring": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Show Ring` — a 1px/2px brand ring drawn inside the avatar's edge."
+    },
+    "topIndicator": {
+      "type": "AvatarIndicatorIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Show Top Indicator`, as the intent of the `Status Indicator`\ninstance it holds. Top-right, and it carries a glyph: this is the corner\nthat says something was verified or requested, not who is online.",
+      "values": [
+        "neutral",
+        "primary",
+        "success",
+        "warning",
+        "error",
+        "information"
+      ]
+    },
+    "topIndicatorIcon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Replaces the top indicator's default check glyph."
+    },
+    "topIndicatorLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the top indicator for assistive tech. Without it the mark is decorative."
+    },
+    "bottomIndicator": {
+      "type": "AvatarIndicatorIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Show Bottom Indicator`. Bottom-right and glyphless — the presence\ndot.",
+      "values": [
+        "neutral",
+        "primary",
+        "success",
+        "warning",
+        "error",
+        "information"
+      ]
+    },
+    "bottomIndicatorLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the bottom indicator for assistive tech. Colour alone is not a status."
     }
   },
   "propCounts": {
-    "own": 6,
+    "own": 12,
     "aria": 0,
     "dom": 278,
     "other": 0

package/dist/meta/AvatarGradient.json

@@ -0,0 +1,239 @@
+{
+  "name": "AvatarGradient",
+  "source": "src/components/AvatarGradient.tsx",
+  "propsType": "AvatarGradientProps",
+  "description": "AvatarGradient is Avatar's initials-only sibling: a lit, bevelled disc for\npeople who have no photo.\n\nIT IS A SEPARATE COMPONENT BECAUSE FIGMA DRAWS A SEPARATE COMPONENT, AND THE\nAXES ARE THE ARGUMENT\n\nIt has `Color`, which Avatar does not. It has no `Shape`, because a gradient\nthis directional only reads on a circle. It has no `Type`, because there is\nno image and no icon to fall back to — the initials are the whole content.\nFolding it into Avatar would mean a `color` prop that does nothing on three\nof Avatar's four states and a `shape` prop that this one has to reject.\n\nThere is no `icon` and no `src` fallback here on purpose. If you have a\nphoto, or nothing at all to put in the circle, that is `Avatar`.",
+  "import": "import { AvatarGradient } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Avatar's initials-only sibling: a lit, bevelled disc in one of eight colours, for people with no photo.",
+  "useWhen": [
+    "someone has no profile image and the fallback should still look deliberate rather than empty",
+    "a list of people reads better when each one is a different colour — the colour is recognisable long before the letters are legible"
+  ],
+  "useInstead": [
+    {
+      "when": "there is a photo, or there may be one later",
+      "use": "Avatar",
+      "why": "Avatar falls back from image to initials to icon on its own; this component has no image to fall back from"
+    },
+    {
+      "when": "the mark needs a square shape, an icon, a ring or a status indicator",
+      "use": "Avatar",
+      "why": "Figma draws none of those on this component, and a gradient this directional only reads on a circle"
+    },
+    {
+      "when": "the thing being marked is a status, count or category rather than a person",
+      "use": "Badge"
+    }
+  ],
+  "variants": {
+    "size": {
+      "mini": {
+        "use": "24px — inline beside body text, dense table rows"
+      },
+      "sm": {
+        "use": "32px — menu rows, compact lists"
+      },
+      "md": {
+        "use": "the default, 40px"
+      },
+      "lg": {
+        "use": "48px — profile headers and detail pages"
+      }
+    },
+    "color": {
+      "slate": {
+        "use": "the default. The one to reach for when nothing about the person suggests a colour"
+      },
+      "blue": {
+        "use": "as slate — one of seven, picked to tell people apart"
+      },
+      "violet": {
+        "use": "as slate"
+      },
+      "pink": {
+        "use": "as slate. See `a11y.knownIssues` before putting it behind text that matters"
+      },
+      "orange": {
+        "use": "as slate. See `a11y.knownIssues`"
+      },
+      "green": {
+        "use": "as slate. Not a status — a green disc here does not mean online, and Avatar's `bottomIndicator` is what does"
+      },
+      "red": {
+        "use": "as slate. Not an error — this is identity, not state. See `a11y.knownIssues`"
+      },
+      "light": {
+        "use": "dark text on a near-white disc, for dense surfaces where seven saturated circles would shout"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "`alt` falls back to `initials`, so the disc is never announced as an unlabelled image"
+    ],
+    "requires": [
+      "`alt` naming the person — \"Ada Lovelace\", not \"AB\". Two letters are not a name, and that is all a screen reader would otherwise get"
+    ],
+    "notes": [
+      "Colour is decoration here, never information. Nothing about which of the eight a person gets should be recoverable, because a screen reader cannot recover it."
+    ],
+    "knownIssues": [
+      {
+        "pairing": "--color-base-white on --color-pink-500",
+        "mode": "Light",
+        "ratio": 3.53,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "default"
+        ],
+        "status": "known, not yet fixed"
+      },
+      {
+        "pairing": "--color-base-white on --color-orange-500",
+        "mode": "Light",
+        "ratio": 3.6,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "default"
+        ],
+        "status": "known, not yet fixed"
+      },
+      {
+        "pairing": "--color-base-white on --color-green-500",
+        "mode": "Light",
+        "ratio": 3.69,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "default"
+        ],
+        "status": "known, not yet fixed"
+      },
+      {
+        "pairing": "--color-base-white on --color-red-500",
+        "mode": "Light",
+        "ratio": 3.78,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "default"
+        ],
+        "status": "known, not yet fixed"
+      }
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "picking the colour from a status — green for online, red for failing",
+      "do": "use Avatar's `bottomIndicator`, or say it in text",
+      "why": "the colour is identity, not state. It is also invisible to assistive tech, so a status expressed only this way is not expressed at all"
+    },
+    {
+      "dont": "hashing a user id to a colour and treating it as stable",
+      "do": "store the chosen colour with the person, the way you would store their avatar",
+      "why": "the palette has eight entries and any hash of it will collide; worse, it silently reassigns everyone the day the palette or the hash changes"
+    },
+    {
+      "dont": "passing more than two letters",
+      "why": "Figma draws two. Three fit at 48 and clip at 24, so it looks correct in the story and wrong in the table"
+    }
+  ],
+  "stylesheet": "src/styles/avatar-gradient.css",
+  "tokens": [
+    "--color-base-white",
+    "--color-blue-500",
+    "--color-blue-600",
+    "--color-gray-100",
+    "--color-gray-200",
+    "--color-gray-500",
+    "--color-gray-600",
+    "--color-gray-900",
+    "--color-green-500",
+    "--color-green-600",
+    "--color-orange-500",
+    "--color-orange-600",
+    "--color-pink-500",
+    "--color-pink-600",
+    "--color-purple-500",
+    "--color-purple-600",
+    "--color-red-500",
+    "--color-red-600",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-regular",
+    "--ion-avatar-gradient-elevation",
+    "--ion-avatar-gradient-font-size",
+    "--ion-avatar-gradient-font-weight",
+    "--ion-avatar-gradient-from",
+    "--ion-avatar-gradient-line-height",
+    "--ion-avatar-gradient-sheen",
+    "--ion-avatar-gradient-sheen-mid",
+    "--ion-avatar-gradient-size",
+    "--ion-avatar-gradient-text",
+    "--ion-avatar-gradient-to",
+    "--radius-full",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-40",
+    "--spacing-48",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "AvatarSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
+      "values": [
+        "sm",
+        "md",
+        "lg",
+        "mini"
+      ]
+    },
+    "color": {
+      "type": "AvatarGradientColor | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Color` variant.",
+      "values": [
+        "slate",
+        "blue",
+        "violet",
+        "pink",
+        "orange",
+        "green",
+        "red",
+        "light"
+      ]
+    },
+    "initials": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The two letters. Figma's `Initials`."
+    },
+    "alt": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Describes the person, not the picture — \"Ada Lovelace\", not \"avatar\".\nWithout it the initials are announced as the letters they are, which is\nnot a name."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/AvatarGroup.json

@@ -64,38 +64,61 @@
   "stylesheet": "src/styles/avatar.css",
   "tokens": [
     "--border-strong",
+    "--border-subtle",
     "--border-width-default",
+    "--border-width-thick",
     "--font-family-sans",
     "--font-weight-medium",
+    "--font-weight-regular",
     "--icon-size-2xs",
     "--icon-size-lg",
     "--icon-size-md",
     "--icon-size-sm",
     "--icon-tertiary",
+    "--ion-avatar-border",
     "--ion-avatar-font-size",
+    "--ion-avatar-font-weight",
     "--ion-avatar-group-overlap",
     "--ion-avatar-icon",
+    "--ion-avatar-indicator-icon",
+    "--ion-avatar-indicator-ring",
+    "--ion-avatar-indicator-size",
     "--ion-avatar-line-height",
     "--ion-avatar-radius",
+    "--ion-avatar-ring-width",
     "--ion-avatar-size",
+    "--ion-avatar-surface",
     "--radius-full",
     "--radius-md",
     "--radius-sm",
     "--radius-xs",
+    "--ring-offset",
+    "--spacing-12",
+    "--spacing-14",
+    "--spacing-16",
     "--spacing-24",
     "--spacing-32",
     "--spacing-40",
     "--spacing-48",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-information",
+    "--surface-inverse",
     "--surface-muted",
+    "--surface-placeholder",
+    "--surface-primary",
+    "--surface-success",
+    "--surface-warning",
+    "--text-on-color",
     "--text-tertiary",
     "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
     "--type-body-line-height",
     "--type-body-sm",
     "--type-body-sm-line-height",
     "--type-caption",
-    "--type-caption-line-height",
-    "--type-h5",
-    "--type-h5-line-height"
+    "--type-caption-line-height"
   ],
   "props": {
     "size": {