@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/knowledge/alert.ts

@@ -0,0 +1,234 @@
+/**
+ * alert.ts — Gold-standard design knowledge for Alert components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const alertKnowledge: ComponentKnowledge = {
+  description:
+    "Status notification | Inline feedback message | Contextual information banner",
+
+  stateSpecifications: [
+    {
+      state: "Info",
+      visualChange: "Blue-tinted background with info circle icon; neutral informational tone",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "General information or tips that do not require immediate action",
+    },
+    {
+      state: "Success",
+      visualChange: "Green-tinted background with checkmark circle icon; positive confirmation tone",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Operation completed successfully — confirms the user's action",
+    },
+    {
+      state: "Warning",
+      visualChange: "Yellow/amber-tinted background with triangle exclamation icon; cautionary tone",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Potential issue that the user should be aware of but can proceed",
+    },
+    {
+      state: "Error",
+      visualChange: "Red-tinted background with circle X icon; urgent negative tone",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Critical failure or validation error requiring user attention or correction",
+    },
+    {
+      state: "Dismissing",
+      visualChange: "Alert fades out over 200ms and collapses height to 0; surrounding content reflows",
+      opacity: "1 → 0",
+      cursorWeb: "default",
+      usage: "User clicks the dismiss/close button to remove the alert",
+    },
+    {
+      state: "Hover (Dismiss Button)",
+      visualChange: "Close icon background shifts to hover token; icon color darkens",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse enters the dismiss button hit area",
+    },
+  ],
+
+  propertyDescriptions: {
+    severity: "Visual tone and icon selection — info, success, warning, or error — controls background tint and icon",
+    title: "Optional bold heading text displayed above the description for quick scanning",
+    description: "Body text explaining the alert message in detail; supports plain text or rich content",
+    dismissible: "When true, a close button appears allowing the user to remove the alert from view",
+    icon: "Severity-specific icon rendered at the leading edge; auto-selected by severity or overridden manually",
+    action: "Optional action button or link rendered at the trailing edge or below the description",
+    onDismiss: "Callback fired when the dismiss button is clicked; used to remove the alert from state",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Compact",
+      height: "40px",
+      paddingLR: "12px",
+      fontSize: "13px",
+      iconSize: "16px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Standard",
+      height: "auto",
+      paddingLR: "16px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Large",
+      height: "auto",
+      paddingLR: "20px",
+      fontSize: "14px",
+      iconSize: "24px",
+      borderRadius: "10px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Info Background",
+      tokenName: "$alert-info-bg",
+      role: "Light blue tinted background for informational alerts",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Success Background",
+      tokenName: "$alert-success-bg",
+      role: "Light green tinted background for success alerts",
+      fallback: "#ECFDF3",
+    },
+    {
+      property: "Warning Background",
+      tokenName: "$alert-warning-bg",
+      role: "Light amber tinted background for warning alerts",
+      fallback: "#FFFAEB",
+    },
+    {
+      property: "Error Background",
+      tokenName: "$alert-error-bg",
+      role: "Light red tinted background for error alerts",
+      fallback: "#FEF3F2",
+    },
+    {
+      property: "Border",
+      tokenName: "$alert-border",
+      role: "Left accent border or full border matching severity color at medium intensity",
+      fallback: "currentColor at 40% opacity",
+    },
+    {
+      property: "Title Text",
+      tokenName: "$alert-title-text",
+      role: "Heading text color — darker shade of the severity color for hierarchy",
+      fallback: "#101828",
+    },
+    {
+      property: "Icon Color",
+      tokenName: "$alert-icon",
+      role: "Severity icon fill color — matches the severity's primary color",
+      fallback: "severity-dependent",
+    },
+  ],
+
+  structureRules: [
+    "Container uses horizontal Auto Layout: icon on the left, content area fills, dismiss button on the right",
+    "Content area uses vertical Auto Layout: title (optional) above description, with $spacing-xs gap",
+    "A 3-4px accent border on the left edge (or full border) uses the severity color at medium intensity",
+    "Icon is vertically aligned to the first line of text, not centered to the full container height",
+    "Dismiss button is a small icon button (16-20px) positioned in the top-right corner of the container",
+    "Action buttons or links are placed below the description with $spacing-sm top margin",
+    "Alert container fills the available width of its parent — never fixed width",
+  ],
+
+  typeHierarchyRules: [
+    "Title uses Semi-Bold (600) at the same font-size as description for emphasis without size change",
+    "Description uses Regular weight (400) at the component's base font-size",
+    "Action link text uses Medium weight (500) with underline on hover",
+    "Text uses sentence case throughout — no all-caps severity labels",
+    "Title and description can be combined on a single line for compact alerts",
+    "Line height is 1.5 for comfortable reading of multi-line descriptions",
+  ],
+
+  interactionRules: [
+    { event: "Dismiss Click", trigger: "pointerup on close button", action: "Fire onDismiss callback; animate alert out with fade and height collapse" },
+    { event: "Action Click", trigger: "pointerup on action button/link", action: "Fire the action handler; alert may remain or dismiss based on context" },
+    { event: "Focus Dismiss", trigger: "Tab key to close button", action: "Show focus ring on dismiss button" },
+    { event: "Keydown Enter", trigger: "Enter on focused dismiss button", action: "Dismiss alert (same as click)" },
+    { event: "Keydown Escape", trigger: "Escape while alert or its children are focused", action: "Dismiss alert if dismissible; otherwise no action" },
+    { event: "Auto-Dismiss", trigger: "Timer expires (if configured)", action: "Fade out and remove alert after specified duration (e.g., 5000ms)" },
+    { event: "Hover Dismiss", trigger: "pointerenter on close button", action: "Show hover state on the dismiss icon button" },
+  ],
+
+  contentGuidance: [
+    "Write clear, actionable alert messages — tell users what happened and what to do next",
+    "Use the title for a concise summary (3-8 words) and the description for details",
+    "Match severity to the actual urgency: info for tips, success for confirmations, warning for caution, error for failures",
+    "Include an action button or link when the user can take a specific corrective step",
+    "Avoid stacking more than 2-3 alerts simultaneously — prioritize the most important message",
+    "Error alerts should explain the cause and suggest a resolution, not just state the failure",
+    "Do not use alerts for marketing or promotional content — use banners instead",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Alert fills full width; action button stacks below description; dismiss button touch target 44px" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Alert spans container width; inline action button if space allows" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard layout with icon, content, and dismiss button in a single row" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Alert max-width may be capped by parent container; does not stretch infinitely" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Alerts must communicate their severity and content to assistive technology. Persistent alerts use role='alert'; status updates use role='status'.",
+    requirements: [
+      { requirement: "role='alert'", level: "A", notes: "Error and warning alerts use role='alert' to trigger assertive announcements by screen readers" },
+      { requirement: "role='status'", level: "A", notes: "Info and success alerts use role='status' for polite announcements that do not interrupt" },
+      { requirement: "aria-live", level: "A", notes: "Dynamically injected alerts must use aria-live='assertive' (errors) or 'polite' (info/success)" },
+      { requirement: "Icon + Text", level: "A", notes: "Severity must be conveyed by both color AND icon/text — never by color alone" },
+      { requirement: "Dismiss Label", level: "A", notes: "Close button must have aria-label='Dismiss' or 'Close alert' for screen readers" },
+      { requirement: "Contrast", level: "AA", notes: "Text-to-background: 4.5:1; icon and border to background: 3:1 for each severity" },
+      { requirement: "Focus Management", level: "AA", notes: "After dismissal, focus moves to a logical next element — not lost in the void" },
+    ],
+    outro: [
+      "Screen readers should announce severity, title, and description when the alert appears",
+      "Auto-dismissing alerts must remain visible long enough for screen reader users to hear the full message",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Severity Variants", platform: "All", expectedResult: "Each severity (info, success, warning, error) renders correct background, icon, and border color" },
+    { check: "Dismiss Animation", platform: "Web", expectedResult: "Alert fades out over 200ms and collapses height; surrounding content reflows smoothly" },
+    { check: "Dismiss Focus", platform: "Web", expectedResult: "After dismissal, focus moves to the next focusable element in the DOM" },
+    { check: "Action Button", platform: "All", expectedResult: "Action button renders inline or below description; fires handler on click" },
+    { check: "Icon Alignment", platform: "All", expectedResult: "Severity icon aligns to the first line of text, not vertically centered" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces severity and message via role='alert' or role='status' appropriately" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab reaches dismiss button and action link; Enter activates them" },
+    { check: "Auto-Dismiss", platform: "Web", expectedResult: "When configured, alert disappears after timeout; mouse hover pauses the timer" },
+    { check: "Title + Description", platform: "All", expectedResult: "Title renders bold above description; omitting title still renders correctly" },
+    { check: "Full Width", platform: "All", expectedResult: "Alert spans the full width of its container without horizontal overflow" },
+    { check: "Contrast per Severity", platform: "All", expectedResult: "All four severity variants pass 4.5:1 text and 3:1 non-text contrast" },
+  ],
+
+  dos: [
+    "Use the appropriate severity level that matches the actual urgency of the message",
+    "Include a specific icon for each severity to reinforce the meaning beyond color alone",
+    "Write actionable descriptions that tell users what happened and what to do next",
+    "Allow users to dismiss non-critical alerts (info, success) with a close button",
+    "Keep error alerts persistent until the underlying issue is resolved",
+    "Place alerts near the relevant content or at the top of the page for global messages",
+    "Use a left accent border to reinforce the severity color and visual grouping",
+  ],
+
+  donts: [
+    "Do not use color alone to communicate severity — always pair with an icon and text",
+    "Do not stack more than 3 alerts at once — consolidate or prioritize messages",
+    "Do not auto-dismiss error alerts — they require user attention and action",
+    "Do not use alerts for lengthy content — keep messages under 3 sentences",
+    "Do not place alerts inside other alerts or inside modals unless contextually appropriate",
+    "Do not use warning severity for informational messages — match the tone to the content",
+    "Do not remove the alert from the DOM without an exit animation — sudden disappearance is jarring",
+  ],
+};

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/knowledge/avatar-group.ts

@@ -0,0 +1,270 @@
+/**
+ * avatar-group.ts — Gold-standard design knowledge for Avatar Group components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const avatarGroupKnowledge: ComponentKnowledge = {
+  description:
+    "Overlapping row of avatars | Displays multiple users or entities | Shows overflow count for truncated members",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Avatars render in an overlapping horizontal row with a consistent negative margin; overflow indicator shows '+N' count",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Resting state displaying the visible set of avatars and the overflow count if applicable",
+    },
+    {
+      state: "Hover (Avatar)",
+      visualChange: "Individual avatar scales up slightly (1.05) and gains a subtle elevation shadow; z-index raises above siblings",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters an individual avatar within the group to preview identity",
+    },
+    {
+      state: "Hover (Overflow)",
+      visualChange: "Overflow indicator background darkens one step; cursor changes to pointer to indicate clickability",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters the '+N' overflow indicator — typically opens a popover with the full member list",
+    },
+    {
+      state: "Focus (Avatar)",
+      visualChange: "2px focus ring offset by 2px from the avatar's circular edge, using $focus-ring token",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Individual avatar receives keyboard focus via Tab for interaction (profile link, tooltip, etc.)",
+    },
+    {
+      state: "Focus (Overflow)",
+      visualChange: "2px focus ring on the overflow indicator circle; background shifts to focus state",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Overflow indicator receives keyboard focus via Tab key navigation",
+    },
+    {
+      state: "Loading",
+      visualChange: "Avatar circles display a skeleton pulse animation; images have not yet loaded",
+      opacity: "0.6",
+      cursorWeb: "default",
+      usage: "Avatar images are being fetched; placeholder skeletons indicate loading progress",
+    },
+  ],
+
+  propertyDescriptions: {
+    avatars: "Array of avatar data objects, each containing src (image URL), alt (accessible name), fallback (initials or icon), and optional href",
+    maxVisible: "Maximum number of avatars to render before truncating with an overflow indicator — common values are 3, 4, or 5",
+    size: "Dimensional preset controlling avatar diameter, font size for initials, and overlap offset (Small, Medium, Large, X-Large)",
+    total: "Total count of members represented by the group; used to calculate the overflow indicator count (total - maxVisible)",
+    onOverflowClick: "Callback fired when the '+N' overflow indicator is clicked; typically opens a popover or modal with the full list",
+    spacing: "Negative margin between adjacent avatars controlling the overlap amount; defaults to -8px for Medium size",
+    borderColor: "Color of the ring/border around each avatar that separates overlapping avatars visually; typically matches the page background",
+    borderWidth: "Width of the separator ring around each avatar; default is 2px",
+    direction: "Stack direction for the overlap — 'left' (default) means later avatars overlap to the left; 'right' reverses the stack",
+    tooltip: "When true, hovering an individual avatar shows a tooltip with the person's name",
+    interactive: "When true, individual avatars are clickable/focusable and fire an onClick handler; default is false",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "24px",
+      paddingLR: "0px",
+      fontSize: "10px",
+      iconSize: "12px",
+      borderRadius: "12px (full circle)",
+    },
+    {
+      size: "Medium",
+      height: "32px",
+      paddingLR: "0px",
+      fontSize: "12px",
+      iconSize: "16px",
+      borderRadius: "16px (full circle)",
+    },
+    {
+      size: "Large",
+      height: "40px",
+      paddingLR: "0px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "20px (full circle)",
+    },
+    {
+      size: "X-Large",
+      height: "48px",
+      paddingLR: "0px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "24px (full circle)",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Avatar Background",
+      tokenName: "$avatar-bg",
+      role: "Fallback background color when no image is provided — initials are rendered on this fill",
+      fallback: "#E5E7EB",
+    },
+    {
+      property: "Avatar Text",
+      tokenName: "$avatar-initials-text",
+      role: "Text color for initials rendered inside the avatar circle",
+      fallback: "#374151",
+    },
+    {
+      property: "Border Ring",
+      tokenName: "$avatar-group-ring",
+      role: "Ring color separating overlapping avatars — matches the underlying page surface",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Overflow Background",
+      tokenName: "$avatar-overflow-bg",
+      role: "Background fill for the '+N' overflow indicator circle",
+      fallback: "#F3F4F6",
+    },
+    {
+      property: "Overflow Text",
+      tokenName: "$avatar-overflow-text",
+      role: "Text color for the '+N' count inside the overflow indicator",
+      fallback: "#374151",
+    },
+    {
+      property: "Overflow Hover Background",
+      tokenName: "$avatar-overflow-hover-bg",
+      role: "Background fill for the overflow indicator on hover",
+      fallback: "#E5E7EB",
+    },
+    {
+      property: "Image Object Fit",
+      tokenName: "$avatar-image-fit",
+      role: "Object-fit value for avatar images — cover ensures the image fills the circle without distortion",
+      fallback: "cover",
+    },
+    {
+      property: "Skeleton Pulse",
+      tokenName: "$skeleton-pulse",
+      role: "Animation for loading skeleton state of avatar circles",
+      fallback: "pulse 1.5s ease-in-out infinite",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator ring for interactive avatars and overflow indicator",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+    {
+      property: "Transition",
+      tokenName: "$transition-avatar",
+      role: "Smooth transition for hover scale and shadow effects on individual avatars",
+      fallback: "150ms ease-in-out",
+    },
+  ],
+
+  structureRules: [
+    "Avatar group uses horizontal Auto Layout with negative spacing (overlap) between avatar items",
+    "Each avatar is a circular container with overflow hidden clipping the image or initials to a circle",
+    "A 2px solid border ring in the page background color is applied to each avatar to visually separate overlapping circles",
+    "Avatars are stacked with increasing z-index from left to right — the rightmost avatar appears on top",
+    "The overflow indicator is the last element in the row, styled as a circle with the same diameter as the avatars",
+    "Overflow indicator renders '+N' text centered within the circle where N is (total - maxVisible)",
+    "If total equals maxVisible or fewer, the overflow indicator is not rendered",
+    "When interactive is true, each avatar is wrapped in a focusable button or anchor element",
+    "Tooltip containers are absolutely positioned above/below each avatar and appear on hover with a short delay",
+  ],
+
+  typeHierarchyRules: [
+    "Initials text uses font-weight Semi-Bold (600) and is sized proportionally to the avatar diameter",
+    "Overflow count text uses font-weight Medium (500) at the same font size as initials",
+    "Tooltip text uses Regular (400) weight at the Small body font size (12px)",
+    "All text within avatars is uppercase for initials — single or double character maximum",
+    "Overflow count always uses the plus symbol followed by the number — '+3', not '3 more'",
+  ],
+
+  interactionRules: [
+    { event: "Hover Avatar", trigger: "pointerenter on individual avatar", action: "Scale avatar to 1.05, raise z-index, and show tooltip with name if tooltip is enabled" },
+    { event: "Click Avatar", trigger: "pointerup on individual avatar", action: "Fire the avatar's onClick handler if interactive is true; typically navigates to profile" },
+    { event: "Hover Overflow", trigger: "pointerenter on overflow indicator", action: "Darken background to hover token; show cursor pointer" },
+    { event: "Click Overflow", trigger: "pointerup on overflow indicator", action: "Fire onOverflowClick callback; typically opens a popover or modal with the full member list" },
+    { event: "Focus Avatar", trigger: "Tab key focuses an interactive avatar", action: "Show focus ring around the avatar circle; announce the person's name" },
+    { event: "Focus Overflow", trigger: "Tab key focuses the overflow indicator", action: "Show focus ring; announce 'N more members' to screen readers" },
+    { event: "Enter / Space", trigger: "Enter or Space on a focused avatar or overflow", action: "Fire the same action as a click on that element" },
+    { event: "Image Error", trigger: "Avatar image fails to load", action: "Fall back to initials or default icon placeholder" },
+  ],
+
+  contentGuidance: [
+    "Always provide meaningful alt text for each avatar — use the person's full name, not just initials",
+    "Overflow indicator should clearly communicate the additional count — use '+N' format consistently",
+    "When displaying teams or groups, order avatars by relevance (most recently active or most relevant first)",
+    "Limit maxVisible to 3-5 avatars — more than 5 visible avatars creates visual clutter",
+    "Provide a tooltip or popover on the overflow indicator so users can discover who else is included",
+    "Initials fallback should use first and last name initials — 'JD' for John Doe, not just 'J'",
+    "Avatar images should be appropriately sized for the avatar diameter — avoid loading full-resolution photos",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Reduce maxVisible to 3; use Small size; overflow indicator is touch-friendly at 44px minimum" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Display up to 4 visible avatars at Medium size; overflow opens a bottom sheet on tap" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Display up to 5 visible avatars at Medium or Large size; overflow opens a popover" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Avatar sizes remain capped at X-Large — do not scale proportionally with viewport" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Avatar groups must convey group membership and count to assistive technologies, with individual avatars identified by name and the overflow count clearly announced.",
+    requirements: [
+      { requirement: "Group Role", level: "A", notes: "The container must use role='group' with an aria-label describing the group (e.g., 'Team members')" },
+      { requirement: "Avatar Alt Text", level: "A", notes: "Each avatar image must have meaningful alt text — the person's name, not 'avatar' or 'user'" },
+      { requirement: "Overflow Announcement", level: "A", notes: "Overflow indicator must have an aria-label like 'Show 5 more members' — not just '+5'" },
+      { requirement: "Focusable Elements", level: "A", notes: "When interactive, each avatar and the overflow indicator must be focusable via Tab key" },
+      { requirement: "Keyboard Activation", level: "A", notes: "Enter and Space must activate the focused avatar or overflow indicator" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Initials text and overflow count must meet 4.5:1 contrast against their background fills" },
+      { requirement: "Touch Target", level: "AA", notes: "Interactive avatars and overflow indicator must have 44x44px minimum touch area" },
+      { requirement: "Decorative Images", level: "A", notes: "If avatars are purely decorative (non-interactive, no tooltip), use aria-hidden='true' on images" },
+    ],
+    outro: [
+      "Verify with screen readers that the group label, individual avatar names, and overflow count are all announced in sequence",
+      "Ensure that the focus order follows the visual order — left to right for LTR, right to left for RTL",
+      "Test that image load failures gracefully fall back to initials with correct alt text preserved",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Overlap Rendering", platform: "All", expectedResult: "Avatars overlap with consistent negative margin; border rings separate each circle" },
+    { check: "Overflow Count", platform: "All", expectedResult: "'+N' indicator shows correct count based on total minus maxVisible" },
+    { check: "Image Fallback", platform: "All", expectedResult: "Failed image loads fall back to initials or default icon without layout shift" },
+    { check: "Hover Scale", platform: "Web", expectedResult: "Hovered avatar scales to 1.05 and raises above siblings smoothly" },
+    { check: "Tooltip Display", platform: "Web", expectedResult: "Hovering an avatar shows the person's name in a tooltip after a short delay" },
+    { check: "Overflow Click", platform: "Web", expectedResult: "Clicking '+N' fires onOverflowClick callback; typically opens a member list popover" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab moves focus through interactive avatars and overflow; Enter/Space activates" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces group label, each avatar name, and overflow count with meaningful text" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Overlap direction reverses; focus order matches visual right-to-left layout" },
+    { check: "Skeleton Loading", platform: "All", expectedResult: "Loading state shows pulsing skeleton circles in the correct layout positions" },
+    { check: "Size Variants", platform: "All", expectedResult: "Each size (sm/md/lg/xl) renders correct diameter, font size, and overlap amount" },
+    { check: "Contrast", platform: "All", expectedResult: "Initials and overflow text pass 4.5:1 contrast against their background fills" },
+    { check: "Touch Target", platform: "Mobile", expectedResult: "Interactive avatars have 44x44px minimum touch area even at Small size" },
+  ],
+
+  dos: [
+    "Use avatar groups to represent team membership, collaborators, or participants in a shared context",
+    "Always provide a border ring that matches the page background to visually separate overlapping avatars",
+    "Include an overflow indicator with a clickable action to reveal the full member list",
+    "Order avatars by relevance — most recently active or most relevant members should appear first",
+    "Provide meaningful alt text for each avatar using the person's full name",
+    "Use consistent avatar sizes within a single group — never mix sizes",
+    "Implement image fallback to initials or a default icon for failed or missing image loads",
+  ],
+
+  donts: [
+    "Do not display more than 5 visible avatars — use the overflow indicator for additional members",
+    "Do not omit the overflow indicator when the total exceeds maxVisible — users need to know more exist",
+    "Do not use random or auto-generated colors for initials backgrounds — use consistent, accessible tokens",
+    "Do not remove the border ring between overlapping avatars — they become visually indistinguishable",
+    "Do not use vague alt text like 'avatar' or 'user' — always use the person's name",
+    "Do not make avatars interactive without providing keyboard focus management and ARIA roles",
+    "Do not load full-resolution photos for small avatar circles — serve appropriately sized thumbnails",
+  ],
+};