docs(avatar, badge): position a badge next to an avatar, not inside it

src/components/avatar/spec.md

@@ -34,9 +34,10 @@
 
 ## Revision history
 
-| Version | Date       | Notes                 |
-| ------: | ---------- | --------------------- |
-|       1 | 2026-09-21 | Initial specification |
+| Version | Date       | Notes                                          |
+| ------: | ---------- | ---------------------------------------------- |
+|       1 | 2026-09-21 | Initial specification                          |
+|       2 | 2026-10-01 | A badge goes next to the avatar, not inside it |
 
 ## Overview
 
@@ -113,14 +114,34 @@ again. Without an image, the initials win over a projected icon; the icon is wha
 
 #### Combining with a badge
 
-An [`igc-badge`](../badge/spec.md) projected into the avatar marks a status on it.
+The default slot holds an icon, not an overlay. The avatar clips its content, renders the initials in place of the
+slot and draws the image over it, so a badge projected into the avatar does not show. To mark a status on the
+avatar, put the avatar and an [`igc-badge`](../badge/spec.md) in a wrapper, and position the badge against the
+wrapper.
 
 ```html
-<igc-avatar initials="ZK">
-  <igc-badge variant="danger" outlined>6</igc-badge>
-</igc-avatar>
+<span class="avatar-status">
+  <igc-avatar initials="ZK" alt="Zoe Kim" shape="circle"></igc-avatar>
+  <igc-badge dot outlined variant="success"></igc-badge>
+</span>
+```
+
+```css
+.avatar-status {
+  position: relative;
+  display: inline-flex;
+}
+
+.avatar-status igc-badge {
+  position: absolute;
+  inset-block-end: 0;
+  inset-inline-end: 0;
+}
 ```
 
+`outlined` separates the badge from the image. A color alone means nothing to assistive technologies, so state the
+status in text next to the avatar as well.
+
 ### Localization
 
 The component has no resource strings. The `alt` text and the initials come from the application and are the
@@ -192,6 +213,8 @@ None applicable.
 - The avatar has no size property; its dimensions come from the styles applied to it.
 - Only one content kind is shown at a time, and the order is fixed: the image, then the initials, then the icon.
 - A projected icon is ignored while `initials` is set.
+- The default slot cannot hold an overlay, such as a badge: the avatar clips it, the initials replace it and the
+  image covers it. See [Combining with a badge](#combining-with-a-badge).
 - The avatar is presentational and has no interactive behavior of its own.
 
 ## Accessibility

src/components/badge/spec.md

@@ -36,9 +36,10 @@
 
 ## Revision history
 
-| Version | Date       | Notes                 |
-| ------: | ---------- | --------------------- |
-|       1 | 2026-09-21 | Initial specification |
+| Version | Date       | Notes                                                    |
+| ------: | ---------- | -------------------------------------------------------- |
+|       1 | 2026-09-21 | Initial specification                                    |
+|       2 | 2026-10-01 | Position the badge in a wrapper; hidden text through CSS |
 
 ## Overview
 
@@ -125,14 +126,36 @@ than for text. An icon next to text, or text alone, keeps the inline padding of
 
 #### Positioning against another element
 
-The badge is commonly projected into the element it marks, for example an [avatar](../avatar/spec.md).
+The badge does not position itself. Put the badge and the element it marks in a wrapper with `position: relative`,
+and position the badge against the wrapper. Logical properties keep the badge on the correct side in a Right-to-Left
+context.
 
 ```html
-<igc-avatar src="/users/1.png">
-  <igc-badge variant="success"></igc-badge>
-</igc-avatar>
+<span class="notifier">
+  <igc-icon-button variant="flat" name="mail" aria-label="Messages"></igc-icon-button>
+  <igc-badge>3<span class="visually-hidden"> unread messages</span></igc-badge>
+</span>
 ```
 
+```css
+.notifier {
+  position: relative;
+  display: inline-flex;
+}
+
+.notifier igc-badge {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: 55%;
+  pointer-events: none;
+}
+```
+
+`pointer-events: none` lets a click on the badge reach the button under it. The `visually-hidden` class is an
+application utility; see [ARIA roles and properties](#aria-roles-and-properties). Do not project the badge into an
+[avatar](../avatar/spec.md#combining-with-a-badge): the avatar clips its content and hides it behind the initials and
+the image.
+
 ### Localization
 
 The component has no resource strings. Its content comes from the application.
@@ -207,8 +230,8 @@ None applicable.
 - The badge has no size property; its dimensions follow its content and the styles applied to it.
 - A dot badge ignores whatever is projected into it.
 - The `icon` part applies only when an icon is the sole projected element.
-- The badge does not position itself; where it sits is decided by the element it is projected into or by the
-  application.
+- The badge does not position itself; the application positions it, usually against a wrapper that also holds
+  the element it marks.
 - The badge is not interactive and emits no events.
 
 ## Accessibility
@@ -218,8 +241,9 @@ None applicable.
 - The badge has `role="status"` with `aria-roledescription="badge"`, so that a change of its content is announced
   politely.
 - The role description is fixed and does not encode the variant, since a color is not a meaning an assistive
-  technology can convey. A badge whose variant carries meaning should state it in its content or in a
-  [visually hidden](../visually-hidden/spec.md) companion.
+  technology can convey. A badge whose variant carries meaning should state it in its content. A count should
+  also state what it counts, for example in text that a visually hidden CSS utility of the application hides from
+  the screen. The library does not export a component for this.
 
 ### Keyboard support