{ "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", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "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_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" }, "specification": { "$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": [] }, "specification_source": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.spec.json", "guidance": { "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." }, "links": { "human": "/component-avatargroup", "json": "/data/visual/components/avatargroup.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-avatargroup--playground" } }