{ "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": "avatar", "name": "Avatar", "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-avatar--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--icon", "name": "Icon", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Icon", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--icon&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--initials", "name": "Initials", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Initials", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--initials&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--brand", "name": "Brand", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Brand", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--brand&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--image", "name": "Image", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Image", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--image&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--sizes", "name": "Sizes", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "Sizes", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--sizes&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--styled-and-labeled", "name": "Styled And Labeled", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "StyledAndLabeled", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--styled-and-labeled&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--brand-loading", "name": "Brand Loading", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "BrandLoading", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--brand-loading&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--brand-frame-none", "name": "Brand Frame None", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "BrandFrameNone", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--brand-frame-none&viewMode=story" }, { "id": "cloaked-design-system-primitives-avatar--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Avatar", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "source_digest": "2b2029f9451102c8927bb922908a8c4e63aa196de0afd9efab1a3cad3d1734c5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-avatar--dark-theme&viewMode=story" } ], "name": "Avatar", "id": "avatar", "category": "Primitives" }, "stories_source": { "path": "packages/design-system/src/components/primitives/Avatar/Avatar.stories.tsx", "code": "import React, { useEffect, useState } from 'react';\nimport { SECOND } from '../../../utilities';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { disabledControl, selectArgType } from '../../../storybook/controlOptions';\nimport { Icon as GlyphIcon } from '../Icon/Icon';\nimport { Avatar, type AvatarSize, type AvatarType } from './Avatar';\n\nconst AVATAR_TYPES = ['icon', 'initials', 'brand', 'image'] as const satisfies readonly AvatarType[];\nconst AVATAR_SIZES = ['sm', 'md', 'lg', 'xl'] as const satisfies readonly AvatarSize[];\n\n// Decorative person palette. `Avatar.color` is a free-form CSS color, not a token slot, so demo\n// swatches use literal hex — never the internal `--cds-color-*` primitives, which are DS-only.\nconst DEMO_AVATAR_COLORS = ['#5b8def', '#e5794b', '#48b783', '#9b6dd6'] as const;\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Avatar',\n component: Avatar,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Represents a single person, account, or brand — an identity mark, rendered as an ' +\n 'icon, initials, brand logo, or photo. Reach for `IconTile` instead when the circle is a ' +\n 'category affordance whose tone carries meaning (a colored glyph), and for `AvatarGroup` ' +\n 'when several identities cluster together. The `brand`/`image` types fall back to `initial` ' +\n 'when the source fails or is rejected as too small / too wide (a wordmark).',\n },\n },\n },\n args: {\n type: 'initials',\n size: 'md',\n initial: 'K',\n color: DEMO_AVATAR_COLORS[0],\n },\n argTypes: {\n type: {\n ...selectArgType(AVATAR_TYPES),\n description: 'Rendering mode: `icon` glyph, `initials`, `brand` logo, or cover `image`.',\n },\n size: {\n ...selectArgType(AVATAR_SIZES),\n description: 'Named size mapped to sizing tokens (sm 24 · md 40 · lg 56 · xl 80).',\n },\n icon: {\n ...disabledControl,\n description: 'Glyph node rendered by `icon` avatars.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const Icon: Story = { args: { type: 'icon', size: 'md', icon: } };\n\n/** Monogram fallback; `color` sets the circle background. */\nexport const Initials: Story = {\n args: { type: 'initials', size: 'md', initial: 'K', color: DEMO_AVATAR_COLORS[0] },\n};\n\n/** Contained logo (padded, aspect-preserving) for company/service identity. */\nexport const Brand: Story = { args: { type: 'brand', size: 'md', src: 'https://placehold.co/40', alt: 'Brand' } };\n\n/** Edge-to-edge cover photo for user identity. */\nexport const Image: Story = { args: { type: 'image', size: 'md', src: 'https://placehold.co/80', alt: 'User' } };\n\n/** All four size tiers at a fixed tone. */\nexport const Sizes: Story = {\n render: () => (\n \n {AVATAR_SIZES.map((size, index) => (\n \n ))}\n \n ),\n};\n\n/** `className`/`style` and `ariaLabel` escape hatches on an initials avatar. */\nexport const StyledAndLabeled: Story = {\n args: {\n type: 'initials',\n size: 'md',\n initial: 'QA',\n ariaLabel: 'Quality assurance',\n color: DEMO_AVATAR_COLORS[2],\n style: { boxShadow: 'var(--cds-shadow-card)' },\n },\n};\n\n// Inline asset keeps the demo deterministic and offline-safe (no network fetch in CI/snapshots).\nconst BRAND_LOGO_PREVIEW_SRC =\n 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSc4MCcgaGVpZ2h0PSc4MCc+PHJlY3Qgd2lkdGg9JzgwJyBoZWlnaHQ9JzgwJyByeD0nMTgnIGZpbGw9JyM0RjQ2RTUnLz48dGV4dCB4PSc0MCcgeT0nNDAnIGZvbnQtZmFtaWx5PSctYXBwbGUtc3lzdGVtLFNlZ29lIFVJLHNhbnMtc2VyaWYnIGZvbnQtc2l6ZT0nNDQnIGZvbnQtd2VpZ2h0PSc2MDAnIGZpbGw9JyNGRkZGRkYnIHRleHQtYW5jaG9yPSdtaWRkbGUnIGRvbWluYW50LWJhc2VsaW5lPSdjZW50cmFsJz5DPC90ZXh0Pjwvc3ZnPg==';\n\n/** Holds back the source briefly so the shimmer placeholder and fade-in are visible. */\nfunction BrandLoadingDemo() {\n const [src, setSrc] = useState(undefined);\n\n useEffect(() => {\n const timeout = setTimeout(() => setSrc(BRAND_LOGO_PREVIEW_SRC), 1.6 * SECOND);\n return () => clearTimeout(timeout);\n }, []);\n\n return ;\n}\n\n/** Shimmer placeholder → fade-in once the `brand` source resolves. */\nexport const BrandLoading: Story = { render: () => };\n\n/** Ringless brand chip, for a bundled mark whose own silhouette already reads as an edge. */\nexport const BrandFrameNone: Story = {\n args: { type: 'brand', size: 'lg', src: BRAND_LOGO_PREVIEW_SRC, alt: 'Brand logo', brandFrame: 'none' },\n};\n\nexport const DarkTheme: Story = {\n args: { type: 'initials', size: 'md', initial: 'K', color: DEMO_AVATAR_COLORS[0] },\n globals: { theme: 'dark' },\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Avatar", "status": "preview", "version": "1.2.0", "summary": "A circular identity mark for a person, account, or brand, with resilient image fallbacks." }, "parts": [ { "id": "container", "label": "Container", "description": "Owns the circular crop, background role, and selected size." }, { "id": "identity", "label": "Identity content", "description": "Shows an icon, initials, contained brand mark, or edge-to-edge image." }, { "id": "placeholder", "label": "Loading placeholder", "description": "Shimmers while a brand or image source is loading." } ], "allowedDesignChoices": { "variants": { "icon": { "label": "Icon" }, "initials": { "label": "Initials" }, "brand": { "label": "Brand" }, "image": { "label": "Image" } }, "sizes": { "sm": { "label": "Small" }, "md": { "label": "Medium" }, "lg": { "label": "Large" }, "xl": { "label": "Extra large" } }, "brandFrame": { "ring": { "label": "Ring", "description": "Default. Hairline edge for a mark whose silhouette is unknown at author time." }, "none": { "label": "None", "description": "No edge, for a bundled mark whose own shape has been checked." } } }, "variants": [ { "id": "icon", "label": "Icon", "description": "Centers a glyph when an account is represented by an icon rather than a logo.", "platforms": [ "ios", "android", "web" ] }, { "id": "initials", "label": "Initials", "description": "Shows an uppercase monogram and serves as the final image fallback.", "platforms": [ "ios", "android", "web" ] }, { "id": "brand", "label": "Brand", "description": "Contains a brand mark without cropping its aspect ratio.", "platforms": [ "ios", "android", "web" ] }, { "id": "image", "label": "Image", "description": "Crops a person image edge to edge with cover behavior.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "sm", "label": "Small", "description": "24-unit compact identity mark." }, { "id": "md", "label": "Medium", "description": "40-unit default identity mark." }, { "id": "lg", "label": "Large", "description": "56-unit prominent identity mark." }, { "id": "xl", "label": "Extra large", "description": "80-unit hero identity mark." } ], "measurements": [ { "id": "sm-diameter", "label": "Small diameter", "kind": "exact", "token": "--cds-size-24", "value": 24, "unit": "px", "appliesTo": [ "container", "sm" ] }, { "id": "md-diameter", "label": "Medium diameter", "kind": "exact", "token": "--cds-size-40", "value": 40, "unit": "px", "appliesTo": [ "container", "md" ] }, { "id": "lg-diameter", "label": "Large diameter", "kind": "exact", "token": "--cds-size-56", "value": 56, "unit": "px", "appliesTo": [ "container", "lg" ] }, { "id": "xl-diameter", "label": "Extra-large diameter", "kind": "exact", "token": "--cds-size-80", "value": 80, "unit": "px", "appliesTo": [ "container", "xl" ] }, { "id": "brand-mark-inset", "label": "Brand mark inset", "kind": "exact", "value": 12, "unit": "%", "appliesTo": [ "identity", "brand" ], "notes": "Proportional padding so the brand mark stays inside the circular clip. Empirically fit to live favicon-service/brandfetch assets, which carry some internal transparent margin: the measured LinkedIn/YouTube/Reddit marks lose up to ~12.2% of opaque pixels to the crop at 0% inset, and 12% takes all three to zero. It is not a geometric guarantee — a true edge-to-edge square with hard corners needs ~14.65%, since its corners sit 0.537x the diameter from center against a 0.5x radius." }, { "id": "brand-ring-width", "label": "Brand chip ring width", "kind": "exact", "token": "--cds-border-width-default", "value": 1, "unit": "px", "appliesTo": [ "container", "brand" ], "notes": "Inset hairline ring on the brand chip, painted as `box-shadow: inset` rather than `border` so it doesn't perturb the box model the avatar's fixed size and the brand mark's 12% inset both depend on. Brand marks arrive as a circular badge, a wide rounded rect, and a square with no shared silhouette; the ring gives every shape one consistent edge. Present by default and suppressed by `brandFrame='none'`, which is reserved for a bundled mark whose silhouette the author has checked — a runtime-resolved mark keeps the ring because its shape cannot be known." } ], "layout": { "alignment": "Identity content is centered. Person/cover images fill the circular crop edge to edge; brand marks are inset and contained, so they never reach the crop.", "flow": "The avatar is an inline, non-shrinking circle.", "notes": [ "Brand images use contain behavior with a 12% inset while person images use cover behavior edge to edge.", "The brand chip carries an inset hairline ring unless `brandFrame='none'`; the image chip never does.", "Initials scale with the selected diameter." ] }, "typographyAndColor": { "typography": [ { "label": "Initials foundation", "description": "Initials begin from the body-small ramp before scaling with the avatar diameter.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Default initials container", "description": "Uses the theme-aware bold fill unless a consumer supplies an identity color.", "token": "--cds-bg-bold" }, { "label": "Default initials text", "description": "Maintains contrast on the bold fill.", "token": "--cds-text-on-bold" }, { "label": "Image surface", "description": "Backs brand and image content while it loads.", "token": "--cds-bg-surface" }, { "label": "Brand chip ring", "description": "Hairline ring around the brand chip so mixed brand-mark silhouettes read as one consistent shape. Suppressed by `brandFrame='none'`.", "token": "--cds-divider" } ] }, "states": [ { "id": "ready", "label": "Ready", "description": "Shows the chosen icon, initials, or loaded image." }, { "id": "loading", "label": "Loading", "description": "Shows a circular shimmer while an image source resolves." }, { "id": "fallback-image", "label": "Fallback image", "description": "Tries the secondary source when the primary source fails validation or loading." }, { "id": "fallback-initials", "label": "Fallback initials", "description": "Shows initials when no acceptable image source remains." } ], "behavior": [ { "label": "Image validation", "description": "Reject images that fall below configured natural-width or aspect-ratio limits." }, { "label": "Fallback order", "description": "Try the primary image, then fallback image, then initials when supplied." } ], "accessibility": [ { "label": "Images", "description": "Use alt text for meaningful images and an empty alt value for decorative identity marks." }, { "label": "Non-image marks", "description": "Give icon avatars an accessible label; initials fall back to the visible monogram." } ], "contentAdaptation": [ { "label": "Initials", "description": "Keep monograms short enough to remain legible at the selected size." }, { "label": "Brand assets", "description": "Prefer compact marks over wide wordmarks; aspect-ratio validation may reject a wide source." } ], "motionHaptics": { "motion": [ { "label": "Image arrival", "description": "Fade a loaded bitmap over the placeholder; remove the fade for reduced motion. Reveal a bitmap that was already decoded at mount outright — no placeholder, no fade — so a list of cached avatars does not animate content that was never absent. An image whose source was decoded earlier in the session still shows its placeholder until its own bitmap arrives, then skips the fade." } ], "haptics": [ { "label": "No feedback", "description": "Avatar is not interactive and does not request haptic feedback." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/primitives/Avatar/Avatar.spec.json", "guidance": { "summary": "A circular identity mark for a person, account, or brand, with resilient image fallbacks.", "guidance": [ { "heading": "Overview", "body": "A single identity mark for one person, account, or brand, rendered as an icon, initials,\na brand logo, or a photo. For several identities together use `AvatarGroup`." }, { "heading": "Use when", "body": "Pick `type` for what the mark represents. `brand`/`image` fall back to `initial` when the\nsource fails or is rejected as too small or too wide (a wordmark).\n\n`size` maps to the token scale: `sm` 24, `md` 40, `lg` 56, `xl` 80. Reach for `IconTile`\ninstead when the circle is a category affordance whose color carries meaning." }, { "heading": "Loading", "body": "Brand and image sources shimmer, then fade in once resolved." } ], "usage": [ { "variant": "brand", "use": "A contained, padded, aspect-preserving company or service logo. The common case, resolved from brand assets.", "avoid": "A person — use initials or image.", "axis": "Type" }, { "variant": "initials", "use": "A monogram, used as the fallback when no logo or photo is available. `color` sets the circle background.", "avoid": "When a real logo or photo exists — show it.", "axis": "Type" }, { "variant": "icon", "use": "A glyph identity mark, for accounts represented by an icon rather than a logo.", "avoid": "A category tile whose tone carries meaning — use `IconTile`.", "axis": "Type" }, { "variant": "image", "use": "An edge-to-edge cover photo for a person. (No current app consumers.)", "avoid": "A logo — use brand, which pads and preserves aspect ratio.", "axis": "Type" } ], "examples": [], "source": "packages/design-system/src/components/primitives/Avatar/Avatar.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-avatar", "json": "/data/visual/components/avatar.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-avatar--playground" } }