{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "avatargroup", "name": "AvatarGroup", "category": "Primitives", "summary": "An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.", "documentation": { "summary": "An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.", "guidance": [ { "heading": "Overview", "body": "An overlapping cluster of `Avatar`s for a \"many identities together\" pattern: connected\naccounts, report participants, shared brands. Use a single `Avatar` when only one identity\nis shown." }, { "heading": "Use when", "body": "Each avatar gets a separating ring so the overlap reads cleanly. The ring must match the\nbackground behind the group, so set `surface` to the container it sits on.\n\n`max` caps the rendered avatars and collapses the rest into a trailing \"+N\" chip. For a\ncustom, non-token background, override `ringColor` and `overflowColor` directly." } ], "usage": [ { "variant": "surface", "use": "The group sits on a raised white Card; the ring is white. The default.", "axis": "Surface" }, { "variant": "page", "use": "The group sits on the cream page feed; the ring matches the page canvas.", "axis": "Surface" } ], "examples": [], "source": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." }, "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "code": "import React from 'react';\nimport { cn } from '../../../utilities';\nimport { Avatar } from '../Avatar/Avatar';\nimport type { AvatarProps, AvatarSize } from '../Avatar/Avatar';\nimport { Text } from '../Text/Text';\nimport styles from './AvatarGroup.module.scss';\n\nexport type AvatarGroupSurface = 'page' | 'surface';\nexport type AvatarGroupAvatar = Omit;\n\n/**\n * The ring drawn around each avatar must match the background the group sits on,\n * otherwise the gap between overlapping circles reads as a colored halo.\n */\nconst SURFACE_RING: Record = {\n page: 'var(--cds-bg-page)',\n surface: 'var(--cds-bg-surface)',\n};\n\n/**\n * Props for the overlapping avatar cluster. `max` caps the avatars only — the \"+N\" chip is\n * rendered in addition, so `max={3}` over five avatars shows four circles.\n */\nexport interface AvatarGroupProps {\n /** Avatars in visual order; the first renders leftmost and on top. */\n avatars: AvatarGroupAvatar[];\n /** Size applied to every avatar in the group. */\n size: AvatarSize;\n /** Caps rendered avatars; any extras collapse into a trailing \"+N\" chip. */\n max?: number;\n /** Background the group sits on, used for the separating ring. Defaults to `surface`. */\n surface?: AvatarGroupSurface;\n /** Overrides the separating ring color for custom backgrounds. */\n ringColor?: string;\n /** Overrides the overflow avatar background color. */\n overflowColor?: string;\n /** Overrides the overflow avatar text color. */\n overflowTextColor?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Accessible label for the avatar cluster. */\n ariaLabel?: string;\n /** Selector for the group wrapper. The overflow chip derives `${testId}-overflow`. */\n testId?: string;\n}\n\n/**\n * Renders overlapping avatars for \"many together\" patterns (brands or people).\n */\nexport function AvatarGroup({\n avatars,\n size,\n max,\n surface = 'surface',\n ringColor,\n overflowColor,\n overflowTextColor,\n className,\n style,\n ariaLabel,\n testId,\n}: AvatarGroupProps) {\n const visible = typeof max === 'number' ? avatars.slice(0, max) : avatars;\n const overflow = avatars.length - visible.length;\n\n const rootStyle = {\n ...style,\n '--avatar-group-ring': ringColor ?? SURFACE_RING[surface],\n ...(overflowColor ? { '--avatar-group-overflow-bg': overflowColor } : {}),\n ...(overflowTextColor ? { '--avatar-group-overflow-text': overflowTextColor } : {}),\n } as React.CSSProperties;\n\n return (\n \n {visible.map((avatar, index) => (\n \n \n \n ))}\n {overflow > 0 && (\n \n {`+${overflow}`}\n \n )}\n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "AvatarGroup", "status": "preview", "version": "1.0.0", "summary": "An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count." }, "parts": [ { "id": "group", "label": "Group", "description": "Contains the ordered overlapping identity marks." }, { "id": "avatar", "label": "Avatar", "description": "Reuses Avatar at one shared size for every visible identity." }, { "id": "ring", "label": "Separating ring", "description": "Matches the host surface so overlapping circles remain distinct." }, { "id": "overflow", "label": "Overflow count", "description": "Replaces hidden identities with a final +N circle." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "The group has one overlapping-avatar treatment." } }, "sizes": { "sm": { "label": "Small" }, "md": { "label": "Medium" }, "lg": { "label": "Large" }, "xl": { "label": "Extra large" } }, "surfaces": { "page": { "label": "Page", "description": "Matches the separating ring to the page background." }, "surface": { "label": "Surface", "description": "Matches the separating ring to a card or other raised surface." } } }, "variants": [ { "id": "base", "label": "Base", "description": "One overlapping-avatar treatment whose ring follows the selected surface axis.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "sm", "label": "Small", "description": "Applies the 24-unit Avatar size to every item." }, { "id": "md", "label": "Medium", "description": "Applies the 40-unit Avatar size to every item." }, { "id": "lg", "label": "Large", "description": "Applies the 56-unit Avatar size to every item." }, { "id": "xl", "label": "Extra large", "description": "Applies the 80-unit Avatar size to every item." } ], "measurements": [ { "id": "separating-ring-width", "label": "Separating ring width", "kind": "exact", "token": "--cds-border-width-emphasis", "value": 2, "unit": "px", "appliesTo": [ "ring", "avatar", "overflow" ] }, { "id": "overlap", "label": "Avatar overlap", "kind": "exact", "value": 22, "unit": "%", "appliesTo": [ "avatar", "overflow" ], "notes": "Each item after the first shifts left by 22% of the selected Avatar size." } ], "layout": { "alignment": "All circles share a center line and one selected diameter.", "flow": "Items overlap horizontally; the first identity remains visually on top.", "notes": [ "The group isolates its stacking order from surrounding content.", "The overflow count occupies the same circle geometry as an Avatar." ] }, "typographyAndColor": { "typography": [ { "label": "Overflow count", "description": "The +N count uses the body-small text ramp.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Page ring", "description": "Separates overlapping circles on the page canvas.", "token": "--cds-bg-page" }, { "label": "Surface ring", "description": "Separates overlapping circles on a raised surface.", "token": "--cds-bg-surface" }, { "label": "Overflow text", "description": "Uses secondary text emphasis for the collapsed count.", "token": "--cds-text-secondary" } ] }, "states": [ { "id": "complete", "label": "Complete", "description": "Shows every provided Avatar when no maximum truncates the group." }, { "id": "overflow", "label": "Overflow", "description": "Shows the first maximum identities followed by the hidden-count circle." }, { "id": "empty", "label": "Empty", "description": "Renders an empty group when no identities are supplied." } ], "behavior": [ { "label": "Ordering", "description": "Preserve source order and keep the first identity leftmost and on top." }, { "label": "Maximum", "description": "Collapse only identities after the configured maximum into the +N count." } ], "accessibility": [ { "label": "Cluster label", "description": "Provide one accessible group label when the identities have collective meaning." }, { "label": "Identity labels", "description": "Keep meaningful Avatar alt text or labels; decorative marks may remain unnamed." } ], "contentAdaptation": [ { "label": "Large sets", "description": "Use a maximum to keep dense groups readable and expose the remaining count." }, { "label": "Custom backgrounds", "description": "Override the ring role only when neither page nor surface matches the host background." } ], "motionHaptics": { "motion": [ { "label": "Image loading", "description": "Each image Avatar keeps its own loading and reduced-motion behavior." } ], "haptics": [ { "label": "No feedback", "description": "The group is not interactive and does not request haptic feedback." } ] }, "platformDifferences": [] }, "spec_source": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.spec.json", "guidance_source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec, UsageTable, Do, Dont, Compare } from '../../../../.storybook/blocks';\nimport * as Stories from './AvatarGroup.stories';\nimport avatarGroupSpec from './AvatarGroup.spec.json';\n\n\n\n# AvatarGroup\n\nAn overlapping cluster of `Avatar`s for a \"many identities together\" pattern: connected\naccounts, report participants, shared brands. Use a single `Avatar` when only one identity\nis shown.\n\n\n\n## Use when\n\nEach avatar gets a separating ring so the overlap reads cleanly. The ring must match the\nbackground behind the group, so set `surface` to the container it sits on.\n\n\n\n`max` caps the rendered avatars and collapses the rest into a trailing \"+N\" chip. For a\ncustom, non-token background, override `ringColor` and `overflowColor` directly.\n\n## People and brands\n\n\n\n\n## Overflow\n\n\n\n## Sizes\n\n\n\n## Custom background\n\n\n\n## Dark theme\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "avatars", "type": "AvatarGroupAvatar[]", "declared_type": "AvatarGroupAvatar[]", "required": true, "description": "Avatars in visual order; the first renders leftmost and on top.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 26 } }, { "name": "size", "type": "AvatarSize", "declared_type": "AvatarSize", "required": true, "description": "Size applied to every avatar in the group.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 28 }, "values": [ "lg", "md", "sm", "xl" ], "values_complete": true }, { "name": "max", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Caps rendered avatars; any extras collapse into a trailing \"+N\" chip.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 30 } }, { "name": "surface", "type": "AvatarGroupSurface | undefined", "declared_type": "AvatarGroupSurface", "required": false, "description": "Background the group sits on, used for the separating ring. Defaults to `surface`.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 32 }, "values": [ "page", "surface" ], "values_complete": true, "default": "'surface'", "default_kind": "source-expression" }, { "name": "ringColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the separating ring color for custom backgrounds.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 34 } }, { "name": "overflowColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the overflow avatar background color.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 36 } }, { "name": "overflowTextColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the overflow avatar text color.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 38 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 39 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 40 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for the avatar cluster.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 42 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector for the group wrapper. The overflow chip derives `${testId}-overflow`.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 44 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-border-width-emphasis", "light": "2px", "dark": "2px" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-bg-page", "light": "#f3f1ed", "dark": "#141410" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-primitives-avatargroup--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--brands", "name": "Brands", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Brands", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--brands&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--people", "name": "People", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "People", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--people&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--overflow", "name": "Overflow", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Overflow", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--overflow&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--on-page", "name": "On Page", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "OnPage", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--on-page&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--custom-background", "name": "Custom Background", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "CustomBackground", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--custom-background&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--styled-and-labeled", "name": "Styled And Labeled", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "StyledAndLabeled", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--styled-and-labeled&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--sizes", "name": "Sizes", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Sizes", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--sizes&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--dark-theme&viewMode=story" } ], "name": "AvatarGroup", "id": "avatargroup", "category": "Primitives" }, "stories": [ { "id": "cloaked-design-system-primitives-avatargroup--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--brands", "name": "Brands", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Brands", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--brands&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--people", "name": "People", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "People", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--people&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--overflow", "name": "Overflow", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Overflow", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--overflow&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--on-page", "name": "On Page", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "OnPage", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--on-page&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--custom-background", "name": "Custom Background", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "CustomBackground", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--custom-background&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--styled-and-labeled", "name": "Styled And Labeled", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "StyledAndLabeled", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--styled-and-labeled&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--sizes", "name": "Sizes", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "Sizes", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--sizes&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatargroup--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/AvatarGroup", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "source_digest": "733f838c8d872f8934d3e37f6c26d54b144ae63620d691acf5ae880189367a27", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Text } from '../Text/Text';\nimport { disabledControl, selectArgType, SURFACE_OPTIONS } from '../../../storybook/controlOptions';\nimport { AvatarGroup } from './AvatarGroup';\nimport type { AvatarGroupAvatar } from './AvatarGroup';\nimport type { AvatarSize } from '../Avatar/Avatar';\n\nconst AVATAR_GROUP_SIZES = ['sm', 'md', 'lg', 'xl'] as const satisfies readonly AvatarSize[];\n\nconst brands: AvatarGroupAvatar[] = [\n { type: 'brand', src: 'https://placehold.co/80/0a66c2/ffffff?text=in', alt: 'LinkedIn' },\n { type: 'brand', src: 'https://placehold.co/80/ffffff/4285f4?text=G', alt: 'Google' },\n { type: 'brand', src: 'https://placehold.co/80/0071dc/ffffff?text=W', alt: 'Walmart' },\n];\n\n// Decorative person palette (literal hex, never internal `--cds-color-*` primitives).\nconst people: AvatarGroupAvatar[] = [\n { type: 'initials', initial: 'KA', color: '#5b8def' },\n { type: 'initials', initial: 'JS', color: '#e5794b' },\n { type: 'initials', initial: 'MR', color: '#48b783' },\n { type: 'initials', initial: 'TL', color: '#9b6dd6' },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/AvatarGroup',\n component: AvatarGroup,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Overlapping cluster of `Avatar`s for a \"many identities together\" pattern — connected ' +\n 'accounts, report participants, shared brands. Each avatar gets a separating ring matched to ' +\n 'the `surface` it sits on so the overlap reads cleanly; anything past `max` collapses into a ' +\n 'trailing \"+N\" chip. Use a single `Avatar` when only one identity is shown.',\n },\n },\n },\n args: {\n avatars: brands,\n size: 'md',\n ariaLabel: 'Connected accounts',\n },\n argTypes: {\n avatars: {\n ...disabledControl,\n description: 'Avatars in visual order; the first renders leftmost and on top.',\n },\n size: {\n ...selectArgType(AVATAR_GROUP_SIZES),\n description: 'Size applied to every avatar (sm 24 · md 40 · lg 56 · xl 80).',\n },\n max: {\n control: 'number',\n description: 'Caps rendered avatars; extras collapse into a trailing \"+N\" chip.',\n },\n surface: {\n ...selectArgType(SURFACE_OPTIONS),\n description: 'Background the group sits on; drives the separating ring color. Defaults to `surface`.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\n/** Brand logos clustered together. */\nexport const Brands: Story = { args: { avatars: brands, size: 'md' } };\n\n/** Initials avatars for people. */\nexport const People: Story = { args: { avatars: people, size: 'md' } };\n\n/** `max={3}` collapses the remaining avatar into a \"+N\" chip. */\nexport const Overflow: Story = { args: { avatars: people, size: 'md', max: 3 } };\n\n/** `surface='page'` matches the ring to the page canvas instead of a raised surface. */\nexport const OnPage: Story = { args: { avatars: brands, size: 'md', surface: 'page' } };\n\n/** `ringColor`/`overflowColor` overrides for a custom (non-token) background. */\nexport const CustomBackground: Story = {\n args: {\n avatars: people,\n size: 'md',\n max: 3,\n ringColor: '#de6f4a',\n overflowColor: 'rgba(0, 0, 0, 0.16)',\n overflowTextColor: '#fff',\n },\n decorators: [\n Story => (\n
\n \n
\n ),\n ],\n};\n\n/** `className`/`style` escape hatch plus an `ariaLabel` for the cluster. */\nexport const StyledAndLabeled: Story = {\n args: {\n avatars: people,\n size: 'md',\n ariaLabel: 'People included in this report',\n style: { filter: 'drop-shadow(var(--cds-shadow-card))' },\n },\n};\n\n/** Every size tier, so overlap and ring scale together. */\nexport const Sizes: Story = {\n render: () => (\n \n {AVATAR_GROUP_SIZES.map(size => (\n \n \n \n {size}\n \n \n ))}\n \n ),\n};\n\nexport const DarkTheme: Story = { args: { avatars: people, size: 'md', max: 3 }, globals: { theme: 'dark' } };\n" }, "links": { "human": "/component-avatargroup", "json": "/data/components/avatargroup.json", "markdown": "/data/components/avatargroup.md", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-avatargroup--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "AvatarGroup", "public_path": "AvatarGroup", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "AvatarGroup", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 50 }, "props_type": "AvatarGroupProps", "props": [ { "name": "avatars", "type": "AvatarGroupAvatar[]", "declared_type": "AvatarGroupAvatar[]", "required": true, "description": "Avatars in visual order; the first renders leftmost and on top.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 26 } }, { "name": "size", "type": "AvatarSize", "declared_type": "AvatarSize", "required": true, "description": "Size applied to every avatar in the group.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 28 }, "values": [ "lg", "md", "sm", "xl" ], "values_complete": true }, { "name": "max", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Caps rendered avatars; any extras collapse into a trailing \"+N\" chip.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 30 } }, { "name": "surface", "type": "AvatarGroupSurface | undefined", "declared_type": "AvatarGroupSurface", "required": false, "description": "Background the group sits on, used for the separating ring. Defaults to `surface`.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 32 }, "values": [ "page", "surface" ], "values_complete": true, "default": "'surface'", "default_kind": "source-expression" }, { "name": "ringColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the separating ring color for custom backgrounds.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 34 } }, { "name": "overflowColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the overflow avatar background color.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 36 } }, { "name": "overflowTextColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides the overflow avatar text color.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 38 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 39 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 40 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for the avatar cluster.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 42 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector for the group wrapper. The overflow chip derives `${testId}-overflow`.", "source": { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 44 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx", "line": 6, "name": "AvatarType", "code": "export type AvatarType = 'icon' | 'initials' | 'brand' | 'image';" }, { "path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx", "line": 8, "name": "AvatarSize", "code": "export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';" }, { "path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx", "line": 10, "name": "AvatarBrandFrame", "code": "export type AvatarBrandFrame = 'ring' | 'none';" }, { "path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx", "line": 16, "name": "AvatarProps", "code": "export interface AvatarProps {\n /**\n * Which avatar is rendered. `brand` insets the mark and contains it inside the circle; `image`\n * crops to fill. `icon` and `initials` take `icon`/`initial` instead of `src`.\n */\n type: AvatarType;\n /** Named size, mapped to the sizing token scale. */\n size: AvatarSize;\n /** Rendered as-is for `type='icon'`. The avatar sets no size on it, so size the node yourself. */\n icon?: React.ReactNode;\n /**\n * Initials text for `type='initials'`, and what a `brand`/`image` avatar renders once no source\n * can be shown — omit it and those render nothing. Uppercased by CSS.\n */\n initial?: string;\n /** Background color for initials avatars. */\n color?: string;\n /** Initials text color. Defaults to `--cds-text-on-bold`. */\n initialTextColor?: string;\n /**\n * Edge treatment for `brand` avatars. Use `none` only for a mark you ship and have looked at;\n * a runtime-resolved mark has an unknowable silhouette, so it keeps the ring.\n */\n brandFrame?: AvatarBrandFrame;\n /** Image source for `brand` and `image` avatars. */\n src?: string;\n /** Secondary image tried before initials when the primary source is unavailable. */\n fallbackSrc?: string;\n /** Minimum loaded image dimension before falling back to initials. */\n minImageNaturalWidth?: number;\n /** Minimum loaded fallback image dimension before falling back to initials. */\n fallbackMinImageNaturalWidth?: number;\n /** Maximum loaded image aspect ratio (longer / shorter side) before falling back; rejects wide wordmarks. */\n maxImageAspectRatio?: number;\n /** Maximum loaded fallback image aspect ratio before falling back to initials. */\n fallbackMaxImageAspectRatio?: number;\n /** Accessible image description. */\n alt?: string;\n /** Accessible label for non-image avatars. */\n ariaLabel?: string;\n /** Class hook for composite styling. Applied to the avatar root for every type. */\n className?: string;\n /** Class applied only to the `` of `brand`/`image` avatars (never the initials fallback). */\n imageClassName?: string;\n style?: React.CSSProperties;\n /** Optional test selector. Applied to the avatar root, including a standing-in initials element. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 8, "name": "AvatarGroupSurface", "code": "export type AvatarGroupSurface = 'page' | 'surface';" }, { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 9, "name": "AvatarGroupAvatar", "code": "export type AvatarGroupAvatar = Omit;" }, { "path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx", "line": 24, "name": "AvatarGroupProps", "code": "export interface AvatarGroupProps {\n /** Avatars in visual order; the first renders leftmost and on top. */\n avatars: AvatarGroupAvatar[];\n /** Size applied to every avatar in the group. */\n size: AvatarSize;\n /** Caps rendered avatars; any extras collapse into a trailing \"+N\" chip. */\n max?: number;\n /** Background the group sits on, used for the separating ring. Defaults to `surface`. */\n surface?: AvatarGroupSurface;\n /** Overrides the separating ring color for custom backgrounds. */\n ringColor?: string;\n /** Overrides the overflow avatar background color. */\n overflowColor?: string;\n /** Overrides the overflow avatar text color. */\n overflowTextColor?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Accessible label for the avatar cluster. */\n ariaLabel?: string;\n /** Selector for the group wrapper. The overflow chip derives `${testId}-overflow`. */\n testId?: string;\n}" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." } }