@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/llms.txt

@@ -0,0 +1,19 @@
+# FLOWSTACK UI
+
+Version-aware public Agent Knowledge. Start with a task or exact package; then load only the linked narrow owner routes.
+
+## Packages
+
+- [@flowstack-ui/atom@0.24.0](/packages/atom/0.24.0/index.txt) — 70 components, 0 operations
+- [@flowstack-ui/brick@0.1.11](/packages/brick/0.1.11/index.txt) — 89 components, 0 operations
+- [@flowstack-ui/colors@0.1.1](/packages/colors/0.1.1/index.txt) — 0 components, 6 operations
+- [@flowstack-ui/theme@0.1.1](/packages/theme/0.1.1/index.txt) — 0 components, 7 operations
+
+## Tasks
+
+- [layout](/tasks/layout.txt) — Select layout, surface, spacing, responsive visibility, and structural owners.
+- [forms](/tasks/forms.txt) — Select forms, fields, labels, validation, and input controls.
+- [navigation](/tasks/navigation.txt) — Select navigation landmarks, menus, tabs, pagination, and route affordances.
+- [overlays](/tasks/overlays.txt) — Select dialogs, popovers, transient surfaces, and feedback owners.
+- [data](/tasks/data.txt) — Select tables, grids, lists, trees, feeds, status, and technical-data owners.
+- [theming](/tasks/theming.txt) — Route color operations through Colors and semantic compilation through Theme.

package/public/packages/atom/0.24.0/components/accordion.txt

@@ -0,0 +1,131 @@
+# Accordion
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: accordion
+
+# Accordion agent guide
+
+## Purpose
+
+Coordinate a group of related disclosure sections with linked headings, triggers, panels, expanded state, and keyboard navigation.
+
+## Use when
+
+- Several related sections form one scannable disclosure group and readers should reveal only the details they need.
+
+## Choose something else when
+
+- Only one independent in-flow region needs disclosure. Use Collapsible.
+- Peer controls switch one shared content view rather than independently revealing sections. Use Tabs.
+- Content must layer, dismiss outside, contain focus, or lock document scrolling. Use Dialog, Drawer, or another matching overlay primitive.
+
+## Required composition
+
+- Compose Root > Item > Header > Trigger and place the matching Content as a sibling of Header inside the same Item.
+- Give every Item a stable unique value and choose the Header level from the surrounding document outline.
+- Use landmark=false on Content when many simultaneous regions would make landmark navigation noisy.
+
+## Rules
+
+- **MUST:** Keep each Trigger and Content inside one Item so Atom can own their IDs, expanded state, labeling, and focus navigation.
+- **MUST:** Set Header to the heading level required by the host document; do not rely on the default when it would skip or duplicate the page outline.
+- **MUST:** Use Root controlled or uncontrolled props for expanded state instead of adding competing click handlers or manual ARIA attributes.
+- **MUST:** Treat Accordion as interactive client behavior and keep the client boundary at the smallest composition that owns its state or handlers.
+
+## Common mistakes
+
+- **Avoid:** Using Accordion for one disclosure, placing Trigger outside Header, or writing aria-expanded and aria-controls manually. **Instead:** Use Collapsible for one region and preserve Accordion's complete Item, Header, Trigger, and Content anatomy.
+- **Avoid:** Leaving every Content as a region in a large or multiple-open Accordion. **Instead:** Use landmark=false when the number of regions would make assistive-technology landmark navigation noisy.
+
+## Validation checklist
+
+- Check unique Item values, heading order, Trigger accessible names, aria-expanded and aria-controls relationships, and Content labeling.
+- Test Enter, Space, Home, End, orientation-aware arrow navigation, RTL, disabled items, single and multiple state, and controlled and uncontrolled use.
+- Check mounted and unmounted closed content, focus retention, reduced motion integration, and whether region landmarks remain useful.
+
+## Related guidance
+
+- `collapsible`
+- `tabs`
+- `drawer`
+- `dialog`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "accordion",
+  "name": "Accordion",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate a group of related disclosure sections with linked headings, triggers, panels, expanded state, and keyboard navigation.",
+  "useWhen": [
+    "Several related sections form one scannable disclosure group and readers should reveal only the details they need."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only one independent in-flow region needs disclosure.",
+      "useInstead": "Collapsible"
+    },
+    {
+      "condition": "Peer controls switch one shared content view rather than independently revealing sections.",
+      "useInstead": "Tabs"
+    },
+    {
+      "condition": "Content must layer, dismiss outside, contain focus, or lock document scrolling.",
+      "useInstead": "Dialog, Drawer, or another matching overlay primitive"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item > Header > Trigger and place the matching Content as a sibling of Header inside the same Item.",
+    "Give every Item a stable unique value and choose the Header level from the surrounding document outline.",
+    "Use landmark=false on Content when many simultaneous regions would make landmark navigation noisy."
+  ],
+  "rules": [
+    {
+      "id": "accordion-anatomy",
+      "level": "must",
+      "statement": "Keep each Trigger and Content inside one Item so Atom can own their IDs, expanded state, labeling, and focus navigation."
+    },
+    {
+      "id": "accordion-heading-level",
+      "level": "must",
+      "statement": "Set Header to the heading level required by the host document; do not rely on the default when it would skip or duplicate the page outline."
+    },
+    {
+      "id": "accordion-state-owner",
+      "level": "must",
+      "statement": "Use Root controlled or uncontrolled props for expanded state instead of adding competing click handlers or manual ARIA attributes."
+    },
+    {
+      "id": "accordion-client-boundary",
+      "level": "must",
+      "statement": "Treat Accordion as interactive client behavior and keep the client boundary at the smallest composition that owns its state or handlers."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Accordion for one disclosure, placing Trigger outside Header, or writing aria-expanded and aria-controls manually.",
+      "correction": "Use Collapsible for one region and preserve Accordion's complete Item, Header, Trigger, and Content anatomy."
+    },
+    {
+      "mistake": "Leaving every Content as a region in a large or multiple-open Accordion.",
+      "correction": "Use landmark=false when the number of regions would make assistive-technology landmark navigation noisy."
+    }
+  ],
+  "validation": [
+    "Check unique Item values, heading order, Trigger accessible names, aria-expanded and aria-controls relationships, and Content labeling.",
+    "Test Enter, Space, Home, End, orientation-aware arrow navigation, RTL, disabled items, single and multiple state, and controlled and uncontrolled use.",
+    "Check mounted and unmounted closed content, focus retention, reduced motion integration, and whether region landmarks remain useful."
+  ],
+  "related": [
+    "collapsible",
+    "tabs",
+    "drawer",
+    "dialog"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/alert-dialog.txt

@@ -0,0 +1,112 @@
+# AlertDialog
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: alert-dialog
+
+# AlertDialog agent guide
+
+## Purpose
+
+Require an explicit response to an urgent or consequential decision with alertdialog semantics, safe initial focus, and non-dismissible backdrop behavior.
+
+## Use when
+
+- A destructive, irreversible, security-sensitive, or otherwise consequential action requires the user to choose a safe cancellation or explicit action before continuing.
+
+## Choose something else when
+
+- The surface presents ordinary information, a form, or a task that is not an urgent consequential decision. Use Dialog.
+
+## Required composition
+
+- Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the layer must leave its DOM location. When Overlay is rendered, keep it as a sibling of Content. Inside Content, supply the required accessible name and description with Title and Description or native ARIA relationships, and use Cancel and Action when the decision needs those owned controls.
+
+## Rules
+
+- **MUST:** Keep the fixed alertdialog role and provide both an accessible name with Title or native labeling and an accessible description with Description or native aria-describedby.
+- **MUST:** Make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied.
+- **MUST:** Do not add backdrop dismissal; require Cancel, Action, or an intentional permitted Escape path to resolve the decision.
+- **MUST:** Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership.
+- **MUST:** Use Cancel and Action for the decision controls so close reasons and interaction details remain available to controlled workflows.
+
+## Common mistakes
+
+- **Avoid:** Using AlertDialog for ordinary forms, focusing the destructive Action first, omitting Description, or making the backdrop dismiss the decision. **Instead:** Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal.
+
+## Validation checklist
+
+- Verify alertdialog role, accessible name and description, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.
+- Verify Cancel and Action close reasons, controlled state, permitted Escape behavior, nested top-layer ownership, document scroll lock, background isolation, exit presence, and focus restoration.
+
+## Related guidance
+
+- `dialog`
+- `modal`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "alert-dialog",
+  "name": "AlertDialog",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Require an explicit response to an urgent or consequential decision with alertdialog semantics, safe initial focus, and non-dismissible backdrop behavior.",
+  "useWhen": [
+    "A destructive, irreversible, security-sensitive, or otherwise consequential action requires the user to choose a safe cancellation or explicit action before continuing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The surface presents ordinary information, a form, or a task that is not an urgent consequential decision.",
+      "useInstead": "Dialog"
+    }
+  ],
+  "composition": [
+    "Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the layer must leave its DOM location. When Overlay is rendered, keep it as a sibling of Content. Inside Content, supply the required accessible name and description with Title and Description or native ARIA relationships, and use Cancel and Action when the decision needs those owned controls."
+  ],
+  "rules": [
+    {
+      "id": "alert-dialog-required-semantics",
+      "level": "must",
+      "statement": "Keep the fixed alertdialog role and provide both an accessible name with Title or native labeling and an accessible description with Description or native aria-describedby."
+    },
+    {
+      "id": "alert-dialog-safe-focus",
+      "level": "must",
+      "statement": "Make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied."
+    },
+    {
+      "id": "alert-dialog-no-backdrop-dismissal",
+      "level": "must",
+      "statement": "Do not add backdrop dismissal; require Cancel, Action, or an intentional permitted Escape path to resolve the decision."
+    },
+    {
+      "id": "alert-dialog-sibling-overlay",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership."
+    },
+    {
+      "id": "alert-dialog-owned-actions",
+      "level": "must",
+      "statement": "Use Cancel and Action for the decision controls so close reasons and interaction details remain available to controlled workflows."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AlertDialog for ordinary forms, focusing the destructive Action first, omitting Description, or making the backdrop dismiss the decision.",
+      "correction": "Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal."
+    }
+  ],
+  "validation": [
+    "Verify alertdialog role, accessible name and description, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.",
+    "Verify Cancel and Action close reasons, controlled state, permitted Escape behavior, nested top-layer ownership, document scroll lock, background isolation, exit presence, and focus restoration."
+  ],
+  "related": [
+    "dialog",
+    "modal"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/app-bar.txt

@@ -0,0 +1,96 @@
+# AppBar
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: app-bar
+
+# AppBar agent guide
+
+## Purpose
+
+Provide semantic header structure with start, center, and end regions without inventing navigation or toolbar behavior.
+
+## Use when
+
+- A page or application header needs stable start, center, and end structural regions.
+
+## Choose something else when
+
+- A group of controls needs arrow-key navigation. Use Toolbar inside AppBar.
+
+## Required composition
+
+- Compose AppBar.Root > AppBar.Toolbar > AppBar.Start, AppBar.Center, and AppBar.End; place actual navigation or Toolbar primitives inside the structural sections.
+
+## Rules
+
+- **MUST:** Treat AppBar.Toolbar as structural layout, not an ARIA toolbar.
+- **SHOULD:** Name comparable header landmarks when more than one exists.
+
+## Common mistakes
+
+- **Avoid:** Using AppBar.Toolbar to imply grouped-control keyboard behavior. **Instead:** Compose Toolbar.Root for controls or NavList and NavigationMenu for navigation.
+
+## Validation checklist
+
+- Confirm the root header landmark is appropriate in its page context.
+- Confirm content remains in logical start, center, and end order at zoom and in RTL.
+
+## Related guidance
+
+- `toolbar`
+- `nav-list`
+- `navigation-menu`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "app-bar",
+  "name": "AppBar",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide semantic header structure with start, center, and end regions without inventing navigation or toolbar behavior.",
+  "useWhen": [
+    "A page or application header needs stable start, center, and end structural regions."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A group of controls needs arrow-key navigation.",
+      "useInstead": "Toolbar inside AppBar"
+    }
+  ],
+  "composition": [
+    "Compose AppBar.Root > AppBar.Toolbar > AppBar.Start, AppBar.Center, and AppBar.End; place actual navigation or Toolbar primitives inside the structural sections."
+  ],
+  "rules": [
+    {
+      "id": "appbar-toolbar-structure",
+      "level": "must",
+      "statement": "Treat AppBar.Toolbar as structural layout, not an ARIA toolbar."
+    },
+    {
+      "id": "appbar-landmark-name",
+      "level": "should",
+      "statement": "Name comparable header landmarks when more than one exists."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AppBar.Toolbar to imply grouped-control keyboard behavior.",
+      "correction": "Compose Toolbar.Root for controls or NavList and NavigationMenu for navigation."
+    }
+  ],
+  "validation": [
+    "Confirm the root header landmark is appropriate in its page context.",
+    "Confirm content remains in logical start, center, and end order at zoom and in RTL."
+  ],
+  "related": [
+    "toolbar",
+    "nav-list",
+    "navigation-menu"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/aspect-ratio.txt

@@ -0,0 +1,111 @@
+# AspectRatio
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: aspect-ratio
+
+# AspectRatio agent guide
+
+## Purpose
+
+Reserve stable width-to-height geometry for media, embeds, and placeholders while leaving all content semantics and interaction to the child.
+
+## Use when
+
+- An image, video, iframe, preview, or placeholder needs a predictable box before its content loads.
+
+## Choose something else when
+
+- The content's intrinsic dimensions already provide the intended stable layout or the task needs media loading fallback behavior rather than geometry alone. Use the semantic native media element or Image.
+
+## Required composition
+
+- Wrap one semantic content region in Root, provide a positive finite width-divided-by-height ratio when 16/9 is not correct, and put all image alt text, iframe titles, playback controls, and interactive semantics on the child itself.
+
+## Rules
+
+- **MUST:** Treat Root as geometry only; do not assign it media roles, accessible names, loading state, or interaction that belongs to its child.
+- **MUST:** Express ratio as width divided by height and provide a finite positive number; invalid values normalize to 16/9.
+- **MUST:** Give contained images suitable alt text, iframes descriptive titles, and interactive media its native keyboard and focus behavior.
+- **MUST:** Do not try to override the resolved aspectRatio through consumer style; Atom preserves other style properties but owns the ratio value.
+
+## Common mistakes
+
+- **Avoid:** Treating AspectRatio as an image or video component or moving the child's accessible name to the wrapper. **Instead:** Keep Root structural and retain the native child element with its own semantics and accessible name.
+- **Avoid:** Passing height divided by width or relying on zero, negative, or non-finite input. **Instead:** Pass the intended width divided by height as a finite positive number.
+
+## Validation checklist
+
+- Verify default, square, portrait, and wide ratios; invalid-ratio normalization; reserved layout before loading; and preservation of consumer styles outside aspectRatio.
+- Inspect the final DOM to confirm Root adds no role or ARIA and the child retains correct image, iframe, media, keyboard, and focus semantics.
+- Verify asChild and render composition preserve the authoritative ratio, native props, content, and ref.
+
+## Related guidance
+
+- `image`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "aspect-ratio",
+  "name": "AspectRatio",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Reserve stable width-to-height geometry for media, embeds, and placeholders while leaving all content semantics and interaction to the child.",
+  "useWhen": [
+    "An image, video, iframe, preview, or placeholder needs a predictable box before its content loads."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content's intrinsic dimensions already provide the intended stable layout or the task needs media loading fallback behavior rather than geometry alone.",
+      "useInstead": "the semantic native media element or Image"
+    }
+  ],
+  "composition": [
+    "Wrap one semantic content region in Root, provide a positive finite width-divided-by-height ratio when 16/9 is not correct, and put all image alt text, iframe titles, playback controls, and interactive semantics on the child itself."
+  ],
+  "rules": [
+    {
+      "id": "aspect-ratio-geometry-only",
+      "level": "must",
+      "statement": "Treat Root as geometry only; do not assign it media roles, accessible names, loading state, or interaction that belongs to its child."
+    },
+    {
+      "id": "aspect-ratio-value",
+      "level": "must",
+      "statement": "Express ratio as width divided by height and provide a finite positive number; invalid values normalize to 16/9."
+    },
+    {
+      "id": "aspect-ratio-semantics",
+      "level": "must",
+      "statement": "Give contained images suitable alt text, iframes descriptive titles, and interactive media its native keyboard and focus behavior."
+    },
+    {
+      "id": "aspect-ratio-authority",
+      "level": "must",
+      "statement": "Do not try to override the resolved aspectRatio through consumer style; Atom preserves other style properties but owns the ratio value."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Treating AspectRatio as an image or video component or moving the child's accessible name to the wrapper.",
+      "correction": "Keep Root structural and retain the native child element with its own semantics and accessible name."
+    },
+    {
+      "mistake": "Passing height divided by width or relying on zero, negative, or non-finite input.",
+      "correction": "Pass the intended width divided by height as a finite positive number."
+    }
+  ],
+  "validation": [
+    "Verify default, square, portrait, and wide ratios; invalid-ratio normalization; reserved layout before loading; and preservation of consumer styles outside aspectRatio.",
+    "Inspect the final DOM to confirm Root adds no role or ARIA and the child retains correct image, iframe, media, keyboard, and focus semantics.",
+    "Verify asChild and render composition preserve the authoritative ratio, native props, content, and ref."
+  ],
+  "related": [
+    "image"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/avatar.txt

@@ -0,0 +1,119 @@
+# Avatar
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: avatar
+
+# Avatar agent guide
+
+## Purpose
+
+Represent a person, team, organization, or other named entity with a tracked image, loading or error fallback, and optional nonsemantic grouping.
+
+## Use when
+
+- A picture or short fallback helps users recognize a named entity and the interface can provide sufficient identity context.
+
+## Choose something else when
+
+- The content is a status, count, arbitrary image, or the avatar would be the only source of essential identity. Use Badge, Image, or visible identity text paired with the appropriate content.
+
+## Required composition
+
+- Compose Root with the tracked src, an Image using the same src, and a Fallback that is meaningful while idle, loading, or errored. Add delayMs only to avoid brief fallback flashes. Use Group only for several Avatars and add group semantics explicitly only when the collection needs an announced name.
+
+## Rules
+
+- **MUST:** Pass the source to Root for preloading and use the same source on Image so rendered content matches the tracked loading status.
+- **MUST:** Keep visible identifying text nearby whenever identity is important; do not make an image or initials the sole source of essential identity.
+- **MUST:** Use meaningful Image alt text only when the image communicates identity not already stated nearby; otherwise use alt empty and hide redundant Fallback text from assistive technology.
+- **MUST:** Provide a fallback that remains understandable for missing, loading, and failed images, and choose any loading delay without leaving essential identity temporarily unavailable.
+- **SHOULD:** Keep Group structural by default; add role group and an accessible name only when users benefit from the avatars being announced as one collection.
+
+## Common mistakes
+
+- **Avoid:** Using different Root and Image sources or treating onLoadingStatusChange as proof that an image remains available indefinitely. **Instead:** Keep sources aligned and treat loading status as current rendering state, with a durable fallback.
+- **Avoid:** Repeating an adjacent person's name in Image alt and visible Fallback text. **Instead:** Use a decorative image and aria-hidden fallback when nearby text already supplies the identity.
+
+## Validation checklist
+
+- Verify missing, idle, loading, loaded, changed-source, and error paths; callback status; delayed fallback timing and cleanup; and that Image and Fallback never render as competing identity output.
+- Check meaningful and decorative variants with nearby visible identity text, appropriate alt text, fallback accessibility, and no color- or image-only essential meaning.
+- Verify Group remains nonsemantic unless deliberately labelled and all parts preserve native props, asChild or render composition, and refs.
+
+## Related guidance
+
+- `image`
+- `badge`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "avatar",
+  "name": "Avatar",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Represent a person, team, organization, or other named entity with a tracked image, loading or error fallback, and optional nonsemantic grouping.",
+  "useWhen": [
+    "A picture or short fallback helps users recognize a named entity and the interface can provide sufficient identity context."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is a status, count, arbitrary image, or the avatar would be the only source of essential identity.",
+      "useInstead": "Badge, Image, or visible identity text paired with the appropriate content"
+    }
+  ],
+  "composition": [
+    "Compose Root with the tracked src, an Image using the same src, and a Fallback that is meaningful while idle, loading, or errored. Add delayMs only to avoid brief fallback flashes. Use Group only for several Avatars and add group semantics explicitly only when the collection needs an announced name."
+  ],
+  "rules": [
+    {
+      "id": "avatar-source",
+      "level": "must",
+      "statement": "Pass the source to Root for preloading and use the same source on Image so rendered content matches the tracked loading status."
+    },
+    {
+      "id": "avatar-identity",
+      "level": "must",
+      "statement": "Keep visible identifying text nearby whenever identity is important; do not make an image or initials the sole source of essential identity."
+    },
+    {
+      "id": "avatar-alt",
+      "level": "must",
+      "statement": "Use meaningful Image alt text only when the image communicates identity not already stated nearby; otherwise use alt empty and hide redundant Fallback text from assistive technology."
+    },
+    {
+      "id": "avatar-fallback",
+      "level": "must",
+      "statement": "Provide a fallback that remains understandable for missing, loading, and failed images, and choose any loading delay without leaving essential identity temporarily unavailable."
+    },
+    {
+      "id": "avatar-group",
+      "level": "should",
+      "statement": "Keep Group structural by default; add role group and an accessible name only when users benefit from the avatars being announced as one collection."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using different Root and Image sources or treating onLoadingStatusChange as proof that an image remains available indefinitely.",
+      "correction": "Keep sources aligned and treat loading status as current rendering state, with a durable fallback."
+    },
+    {
+      "mistake": "Repeating an adjacent person's name in Image alt and visible Fallback text.",
+      "correction": "Use a decorative image and aria-hidden fallback when nearby text already supplies the identity."
+    }
+  ],
+  "validation": [
+    "Verify missing, idle, loading, loaded, changed-source, and error paths; callback status; delayed fallback timing and cleanup; and that Image and Fallback never render as competing identity output.",
+    "Check meaningful and decorative variants with nearby visible identity text, appropriate alt text, fallback accessibility, and no color- or image-only essential meaning.",
+    "Verify Group remains nonsemantic unless deliberately labelled and all parts preserve native props, asChild or render composition, and refs."
+  ],
+  "related": [
+    "image",
+    "badge"
+  ]
+}
+```