{ "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": "listitem", "name": "ListItem", "category": "Organization / List", "contract_status": "preview", "contract_kind": "source-derived", "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": null, "spec_origin": "local-authored", "local_spec_source_status": "preview", "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-organization-list-item--playground", "name": "Playground", "title": "Cloaked Design System/Organization/List/Item", "exportName": "Playground", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--playground&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--text-card-padding", "name": "Text Card Padding", "title": "Cloaked Design System/Organization/List/Item", "exportName": "TextCardPadding", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--text-card-padding&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--text-sheet-padding", "name": "Text Sheet Padding", "title": "Cloaked Design System/Organization/List/Item", "exportName": "TextSheetPadding", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--text-sheet-padding&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--text-zero-value", "name": "Text Zero Value", "title": "Cloaked Design System/Organization/List/Item", "exportName": "TextZeroValue", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--text-zero-value&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--icon-tile-leading", "name": "Icon Tile Leading", "title": "Cloaked Design System/Organization/List/Item", "exportName": "IconTileLeading", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--icon-tile-leading&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--arrow", "name": "Arrow", "title": "Cloaked Design System/Organization/List/Item", "exportName": "Arrow", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--arrow&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--selection-multiple", "name": "Selection Multiple", "title": "Cloaked Design System/Organization/List/Item", "exportName": "SelectionMultiple", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--selection-multiple&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--selection-single", "name": "Selection Single", "title": "Cloaked Design System/Organization/List/Item", "exportName": "SelectionSingle", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--selection-single&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--avatar-initials-leading", "name": "Avatar Initials Leading", "title": "Cloaked Design System/Organization/List/Item", "exportName": "AvatarInitialsLeading", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--avatar-initials-leading&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--custom-leading-marker", "name": "Custom Leading Marker", "title": "Cloaked Design System/Organization/List/Item", "exportName": "CustomLeadingMarker", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--custom-leading-marker&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--progress-variants", "name": "Progress Variants", "title": "Cloaked Design System/Organization/List/Item", "exportName": "ProgressVariants", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--progress-variants&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--with-tag", "name": "With Tag", "title": "Cloaked Design System/Organization/List/Item", "exportName": "WithTag", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--with-tag&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--with-status", "name": "With Status", "title": "Cloaked Design System/Organization/List/Item", "exportName": "WithStatus", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--with-status&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--mixed-list", "name": "Mixed List", "title": "Cloaked Design System/Organization/List/Item", "exportName": "MixedList", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--mixed-list&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--empty-state", "name": "Empty State", "title": "Cloaked Design System/Organization/List/Item", "exportName": "EmptyState", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--empty-state&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--stat", "name": "Stat", "title": "Cloaked Design System/Organization/List/Item", "exportName": "Stat", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--stat&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--icon-plate", "name": "Icon Plate", "title": "Cloaked Design System/Organization/List/Item", "exportName": "IconPlate", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--icon-plate&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--tone-matrix", "name": "Tone Matrix", "title": "Cloaked Design System/Organization/List/Item", "exportName": "ToneMatrix", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--tone-matrix&viewMode=story" }, { "id": "cloaked-design-system-organization-list-item--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Organization/List/Item", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "source_digest": "dde33cb538e065f7c9228b2dcaf91feae5c9a37cd1f40fd8b84d52fc664863c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list-item--dark-theme&viewMode=story" } ], "name": "ListItem", "id": "listitem", "category": "Organization / List" }, "stories_source": { "path": "packages/design-system/src/components/organization/ListItem/ListItem.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { List } from '../List/List';\nimport { Avatar } from '../../primitives/Avatar/Avatar';\nimport { IconTile } from '../../primitives/IconTile/IconTile';\nimport { Tag } from '../../primitives/Tag/Tag';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { hapticArgType, selectArgType, STATUS_TONE_OPTIONS } from '../../../storybook/controlOptions';\nimport { FEATURE_TONES } from '../../../styles/featureTone';\nimport {\n LIST_ITEM_PLAYGROUND_ARG_TYPES,\n LIST_ITEM_PLAYGROUND_ARGS,\n SelectionExample,\n renderListItemPlayground,\n renderMixedList,\n renderProgressExamples,\n renderStatRows,\n renderToneMatrix,\n type ListItemPlaygroundArgs,\n} from './ListItemRow/ListItemRow.stories.fixtures';\nimport type { ListItemTone } from './ListItem';\nimport styles from './ListItem.stories.module.scss';\n\nconst LIST_ITEM_TONES = [...STATUS_TONE_OPTIONS, 'brand', ...FEATURE_TONES] as const satisfies readonly ListItemTone[];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Organization/List/Item',\n component: List.Item,\n parameters: {\n docs: {\n description: {\n component:\n 'Slot-first list row: compose it from named slots rather than subclassing — `leadingGlyph` ' +\n '+ `tone` (or a custom `leading` node), `overline`/`title`/`description`, and a trailing edge ' +\n '(`value`, `tag`, `statusLabel`, or `trailing`/`trailingIcon`). Behavior variants come from ' +\n 'compound parts: `List.Item.Selection` (checkbox/radio rows), `List.Item.Progress` ' +\n '(bar/ring/steps), `List.Item.Stat` (key-value), `List.Item.Empty`, and the `List.Item.Icon` ' +\n 'tone plate. A pressable row (`onPress`) auto-reveals a chevron. Inside a `List` the container ' +\n \"owns separators, so a row's own `divider` is ignored there.\",\n },\n },\n },\n argTypes: {\n leading: {\n control: false,\n description:\n 'Custom leading node (`Avatar`, brand logo, or a `List.Item.Icon` plate). Overrides `leadingGlyph`.',\n },\n leadingGlyph: {\n ...selectArgType(['data-removal', 'dark-web-monitoring', 'guard', 'password', 'check', 'phone']),\n description: 'DS icon rendered as a tone `IconTile` in the leading slot; colored by `tone`.',\n },\n trailing: {\n control: false,\n description: 'Custom trailing node, rendered before `trailingIcon`.',\n },\n trailingIcon: {\n control: false,\n description: 'Icon slot after trailing content (e.g. `List.Item.ArrowIcon`).',\n },\n tag: {\n control: false,\n description: 'Trailing `Tag` slot.',\n },\n onPress: {\n control: false,\n description: 'Press handler. A pressable row auto-shows a chevron unless `chevron` overrides it.',\n },\n padding: {\n ...selectArgType(['card', 'sheet', 'flush']),\n description: 'Row padding preset: `card` (in-card), `sheet` (bottom-sheet), `flush` (no inline padding).',\n },\n dividerMode: {\n ...selectArgType(['full-bleed', 'inset']),\n description: 'Bottom hairline alignment: `full-bleed` edge-to-edge, or `inset` under the content.',\n },\n tone: {\n ...selectArgType(LIST_ITEM_TONES),\n description:\n 'Tone for the generated leading `IconTile`: status | `brand` | feature (monitoring/guard/identity).',\n },\n statusTone: {\n ...selectArgType(STATUS_TONE_OPTIONS),\n description: 'Color treatment for the `statusLabel` status text.',\n },\n haptic: {\n ...hapticArgType,\n description: 'Haptic on press for interactive rows. Defaults to `true` (`light`).',\n },\n },\n decorators: [\n Story => (\n
\n \n
\n ),\n ],\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: StoryObj = {\n args: LIST_ITEM_PLAYGROUND_ARGS,\n argTypes: LIST_ITEM_PLAYGROUND_ARG_TYPES,\n render: args => renderListItemPlayground(args),\n};\n\nexport const TextCardPadding: Story = {\n args: { title: 'Spam calls blocked', value: '1847' },\n};\n\nexport const TextSheetPadding: Story = {\n args: { padding: 'sheet', title: 'Spam calls blocked', value: '1847' },\n};\n\nexport const TextZeroValue: Story = {\n args: { title: 'Data removed', value: 0 },\n};\n\nexport const IconTileLeading: Story = {\n args: {\n leadingGlyph: 'data-removal',\n tone: 'monitoring',\n title: 'Data removal',\n value: '1,847',\n statusLabel: 'Active',\n statusTone: 'success',\n },\n};\n\nexport const Arrow: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Pressable row with a trailing `ArrowIcon` affordance instead of the default chevron.',\n },\n },\n },\n args: {\n leadingGlyph: 'guard',\n tone: 'guard',\n title: 'spokeo.com',\n description: 'Click to solve the CAPTCHA',\n trailingIcon: ,\n onPress: () => {},\n testId: 'list-item-arrow',\n },\n};\n\nexport const SelectionMultiple: StoryObj = {\n parameters: {\n docs: { description: { story: '`List.Item.Selection` with `selectionMode=\"multiple\"` — a checkbox row.' } },\n },\n render: () => ,\n};\n\nexport const SelectionSingle: StoryObj = {\n parameters: {\n docs: { description: { story: '`List.Item.Selection` with `selectionMode=\"single\"` — a radio row.' } },\n },\n render: () => ,\n};\n\nexport const AvatarInitialsLeading: Story = {\n args: {\n leading: ,\n title: 'SSN was leaked on dark web',\n description: 'Bank account was opened',\n },\n};\n\nexport const CustomLeadingMarker: Story = {\n args: {\n leading: ,\n title: 'Verified broker match',\n description: 'Uses IconTile directly only when a custom marker is needed',\n },\n};\n\nexport const ProgressVariants: StoryObj = {\n parameters: {\n docs: { description: { story: '`List.Item.Progress` in all three kinds — `steps`, `ring`, and `bar`.' } },\n },\n render: () => renderProgressExamples(),\n};\n\nexport const WithTag: Story = {\n args: {\n leadingGlyph: 'guard',\n tone: 'warning',\n title: 'Spam call blocked',\n description: '(322) 142-8932',\n tag: (\n \n SMS\n \n ),\n },\n};\n\nexport const WithStatus: Story = {\n args: {\n leadingGlyph: 'dark-web-monitoring',\n tone: 'monitoring',\n title: 'Dark web monitoring',\n statusLabel: 'Active',\n statusTone: 'success',\n },\n};\n\nexport const MixedList: StoryObj = {\n parameters: {\n docs: {\n description: { story: 'Progress, tagged, and avatar rows composed together — a realistic activity list.' },\n },\n },\n render: () => renderMixedList(),\n};\n\nexport const EmptyState: StoryObj = {\n parameters: {\n docs: { description: { story: '`List.Item.Empty` — the placeholder row shown when a list has no items.' } },\n },\n render: () => ,\n};\n\nexport const Stat: StoryObj = {\n parameters: {\n docs: {\n description: {\n story: '`List.Item.Stat` — a key-value statistic row with an inset divider (set `divider={false}` on the last).',\n },\n },\n },\n render: () => renderStatRows(),\n};\n\nexport const IconPlate: StoryObj = {\n parameters: {\n docs: {\n description: {\n story:\n 'The `List.Item.Icon` tone plate across all 9 `ListItemTone` values. A standard row builds this ' +\n 'for you from `leadingGlyph` + `tone`; reach for it directly only for a custom `leading` marker.',\n },\n },\n },\n render: () => (\n \n {LIST_ITEM_TONES.map(tone => (\n \n ))}\n \n ),\n};\n\nexport const ToneMatrix: StoryObj = {\n parameters: {\n docs: {\n description: {\n story: 'Every `ListItemTone` on the generated leading `IconTile`: status, `brand`, and product-feature tones.',\n },\n },\n },\n render: () => renderToneMatrix(),\n};\n\nexport const DarkTheme: StoryObj = {\n globals: { theme: 'dark' },\n parameters: {\n docs: { description: { story: 'A progress row on the dark theme surface.' } },\n },\n render: () => (\n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "ListItem", "status": "preview", "version": "0.1.0-preview.1", "summary": "A row composed from leading, text and trailing slots, with selection, progress, stat, empty and icon helpers. Public consumers import List and use List.Item; ListItem is not a separate package-root export." }, "parts": [ { "id": "root", "label": "Row target", "description": "Full-width row; becomes a button only when an action or selection callback exists.", "required": true }, { "id": "leading", "label": "Leading visual", "description": "Custom content or a generated tone tile; leading selection replaces this slot.", "required": false }, { "id": "body", "label": "Text body", "description": "Required title plus optional overline, description and inline progress.", "required": true }, { "id": "value", "label": "Value", "description": "Optional right-aligned value in the title line.", "required": false }, { "id": "trailing", "label": "Trailing accessory", "description": "One accessory selected by precedence, followed by a derived or explicit chevron.", "required": false }, { "id": "separator", "label": "Divider", "description": "Optional row-owned hairline; List supplies container separators.", "required": false }, { "id": "selection", "label": "Selection mark", "description": "Check or dot mark backed by the row interaction semantics.", "required": false }, { "id": "progress", "label": "Progress", "description": "Ring at the trailing edge, or bar/steps under the copy.", "required": false } ], "allowedDesignChoices": { "variants": { "row": { "label": "List.Item" }, "selection": { "label": "List.Item.Selection" }, "progress": { "label": "List.Item.Progress" }, "stat": { "label": "List.Item.Stat" }, "empty": { "label": "List.Item.Empty" }, "icon": { "label": "List.Item.Icon" } }, "sizes": { "sm": { "label": "Compact", "description": "48px minimum, 8px gap and block padding." }, "md": { "label": "Default", "description": "Content-dependent 48px, 64px or 80px minimum; progress can increase it." } }, "selectionModes": { "single": { "label": "Single", "description": "Radio semantics; pressing the selected row reports true." }, "multiple": { "label": "Multiple", "description": "Checkbox semantics; activation reports the inverse selected state." } }, "selectionPlacements": { "leading": { "label": "Leading", "description": "Replaces an existing leading visual to preserve its column." }, "trailing": { "label": "Trailing", "description": "Default; suitable for rows without a leading visual." } }, "surfaces": { "page": { "label": "Page" }, "surface": { "label": "Surface" } }, "padding": { "card": { "label": "Card" }, "sheet": { "label": "Sheet" }, "flush": { "label": "Flush" } } }, "variants": [ { "id": "row", "label": "Base row", "description": "Informational or pressable row composed from slots.", "platforms": [ "web" ] }, { "id": "selection", "label": "Selection row", "description": "Use onSelectedChange with a controlled selected value. Choose single or multiple selection.", "platforms": [ "web" ] }, { "id": "progress", "label": "Progress row", "description": "A number is shorthand for a trailing ring; a progress object chooses ring, bar or steps.", "platforms": [ "web" ] }, { "id": "stat", "label": "Statistic row", "description": "Noninteractive label/value helper; it has its own divider prop.", "platforms": [ "web" ] }, { "id": "empty", "label": "Empty placeholder", "description": "A centered message for an empty list, not a loading indicator.", "platforms": [ "web" ] }, { "id": "icon", "label": "Leading icon helper", "description": "Tone plate for a custom leading node; generated leadingGlyph tiles do not need it.", "platforms": [ "web" ] } ], "sizes": [ { "id": "sm", "label": "Compact", "description": "Small density overrides rich-row height and removes inline inset; the container supplies spacing." }, { "id": "md", "label": "Default", "description": "Default density grows with leading/trailing accessories, description, selection and progress." } ], "measurements": [ { "id": "base-min-height", "label": "Base row minimum height", "kind": "at-least", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "root" ] }, { "id": "rich-min-height", "label": "Rich row minimum height", "kind": "at-least", "token": "--cds-size-80", "value": 80, "unit": "px", "appliesTo": [ "root" ], "notes": "Applies to md rows with leading content, trailing content or description; a tag-only trailing slot does not promote the row." }, { "id": "selection-min-height", "label": "Copy-only selection minimum height", "kind": "at-least", "token": "--cds-size-64", "value": 64, "unit": "px", "appliesTo": [ "selection" ], "notes": "For trailing selection with card padding and no description or leading slot; compact density is excluded." }, { "id": "row-gap", "label": "Default row gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "root" ] }, { "id": "compact-gap", "label": "Compact row gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "root" ] }, { "id": "row-inset", "label": "Default inline inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "root" ] }, { "id": "selection-gap", "label": "Trailing selection gap", "kind": "exact", "token": "--cds-space-24", "value": 24, "unit": "px", "appliesTo": [ "selection" ] }, { "id": "empty-min-height", "label": "Empty placeholder minimum height", "kind": "at-least", "token": "--cds-size-240", "value": 240, "unit": "px", "appliesTo": [ "root" ] } ], "layout": { "alignment": "Leading visual, text body and trailing accessory align centrally; the body flexes while accessories keep their width.", "flow": "Slots run left to right; overline, title, description and inline progress stack within the body.", "notes": [ "Accessory precedence is trailing, tag, status, selection, trailing progress, then trailingIcon. A chevron can follow the chosen accessory.", "Explicit value wins over a progress label. Custom leading content wins over a generated glyph tile.", "A selected leading control occupies the existing 40px md or 32px sm visual column. Use trailing selection for icon-less rows to avoid adding a column.", "List suppresses a direct List.Item divider. Compound Selection, Progress and Stat members retain their own divider; set divider=false when the container already draws separators." ] }, "typographyAndColor": { "typography": [ { "label": "Title and value", "description": "Use the body ramp.", "token": "--cds-type-body-size" }, { "label": "Description", "description": "Uses body-small with a local 1.2 line-height.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Primary text", "description": "Title and value.", "token": "--cds-text-primary" }, { "label": "Secondary text", "description": "Overline, description, stat label and empty message.", "token": "--cds-text-secondary" }, { "label": "Default surface", "description": "Default and selected row background.", "token": "--cds-bg-surface" }, { "label": "Page surface", "description": "Page-level row background.", "token": "--cds-bg-page" }, { "label": "Divider", "description": "Row-owned and container separators.", "token": "--cds-divider" } ] }, "states": [ { "id": "informational", "label": "Informational", "description": "Without callbacks the row is not a press target." }, { "id": "pressable", "label": "Pressable", "description": "onPress produces a button and normally a chevron; caller-owned trailing content or chevron=false suppresses the automatic chevron." }, { "id": "selected", "label": "Selected", "description": "The host supplies selected. Single activation reports true; multiple activation reports the inverse value." }, { "id": "disabled", "label": "Disabled", "description": "Prevents action and selection callbacks and dims the row. Disabled interactive selection still exposes its state." }, { "id": "progress", "label": "Progress", "description": "Rings render trailing, bars and steps inline. The host owns progress updates." }, { "id": "empty", "label": "Empty", "description": "List.Item.Empty renders its message in a centered 240px-minimum block." } ], "behavior": [ { "label": "Controlled selection", "description": "Selection is host-owned. No callback means no row button; the helper uses a disabled, read-only form control to expose that selection state." }, { "label": "Navigation and disclosure", "description": "Base onPress is host-owned. ariaControls and expanded can describe a disclosure target but do not implement expansion." }, { "label": "Separator ownership", "description": "Use List for list structure and separator ownership. Standalone rows do not claim listitem semantics; compound members need an explicit divider decision." }, { "label": "No nested interactive slots", "description": "A pressable row is already the single control. Keep leading and trailing content noninteractive within it." } ], "accessibility": [ { "label": "Button, checkbox and radio roles", "description": "Interactive rows are native buttons. Selection rows expose checkbox or radio role and aria-checked; their visible title labels them and their description is associated when present." }, { "label": "Names and disabled state", "description": "ariaLabel can replace visible naming when needed. Native disabled blocks keyboard and pointer activation; the selected state stays represented." }, { "label": "Group behavior belongs to the host", "description": "Single selection announces radio semantics, but this row family does not implement radio-group arrow-key movement or enforce one chosen row. The consumer must define and verify group behavior." }, { "label": "Visible keyboard focus", "description": "Interactive rows inherit the shared focus-visible outline. Its inset offset preserves the indicator within clipped list or card containers; disabled native buttons do not receive keyboard focus." }, { "label": "List ownership", "description": "List wraps content rows with role=listitem. A standalone row is a generic container or control, not a listitem by itself." } ], "contentAdaptation": [ { "label": "Clamping", "description": "Title and description default to one-line truncation. Positive titleLines and descriptionLines enable multi-line clamping; overline and value remain single-line. Value has a 46% maximum width." }, { "label": "Empty versus pending", "description": "Use Empty for a known empty result. It does not represent pending data, errors or a retry action." }, { "label": "Review dense combinations", "description": "Verify long titles, descriptions, values, tags, localized copy and large text at narrow widths. Do not combine every slot by default." } ], "motionHaptics": { "motion": [ { "label": "Press feedback", "description": "Interactive rows use the shared fast press transform and opacity change; reduced-motion removes the transform. Progress and selection visuals use their own primitives." } ], "haptics": [ { "label": "Action feedback", "description": "Enabled action and selection callbacks request light feedback by default; haptic can override or disable it. Delivery depends on provider and host support." } ] }, "platformDifferences": [ { "platforms": [ "ios", "android" ], "description": "Native implementations and platform parity are not verified. Vue also has no local implementation.", "rationale": "This preview was authored from the local React types, implementation, styles and documentation. Native unit, typography, interaction and accessibility mappings require platform review." } ] }, "specification_source": "packages/design-system/src/components/organization/ListItem/ListItem.spec.json", "guidance": { "summary": "A row composed from leading, text and trailing slots, with selection, progress, stat, empty and icon helpers. Public consumers import List and use List.Item; ListItem is not a separate package-root export.", "guidance": [ { "heading": "Overview", "body": "A slot-first list row. Compose the base row from named slots — a leading edge (`leadingGlyph` +\n`tone`, or a custom `leading` node), `overline` / `title` / `description`, and a trailing edge\n(`value`, `tag`, `statusLabel`, or `trailing` / `trailingIcon`). Behavior comes from compound parts\nrather than variant props." }, { "heading": "Use when", "body": "The deciding choice is which compound part you reach for.\n\nA pressable row (`onPress`) normally reveals a chevron. `List` suppresses a direct `List.Item`\ndivider. Compound `Selection`, `Progress` and `Stat` rows keep their own divider setting;\npass `divider={false}` when the container already draws separators." }, { "heading": "Leading and trailing slots", "body": "A leading tone plate from `leadingGlyph` + `tone`, with a trailing value and status." }, { "heading": "Tones", "body": "Every `tone` on the generated leading plate — status, `brand`, and product-feature." } ], "usage": [ { "variant": "List.Item", "use": "The default informational row — leading marker, text, and a trailing value/tag/status. The workhorse (most rows in the app).", "avoid": "Selection, progress, or key-value rows — those have dedicated parts below.", "axis": "Part" }, { "variant": "List.Item.Selection", "use": "Selectable rows — `selectionMode=\"multiple\"` renders a checkbox, `\"single\"` a radio.", "avoid": "Titled option cards with supporting copy — use `SelectionCard`.", "axis": "Part" }, { "variant": "List.Item.Progress", "use": "A row carrying progress — `kind` of `steps`, `ring`, or `bar` (removal progress, multi-step tasks).", "avoid": "A static count — that is a plain row `value`.", "axis": "Part" }, { "variant": "List.Item.Stat", "use": "A key-value statistic row with an inset divider. Not currently used in app code, but the intended part for stat tables.", "avoid": "Rows with a leading marker or press affordance — use the base row.", "axis": "Part" }, { "variant": "List.Item.Empty", "use": "The placeholder row shown when a list has no items.", "avoid": "Loading states — this reads as \"nothing here,\" not \"still fetching.\"", "axis": "Part" }, { "variant": "List.Item.Icon", "use": "The leading tone plate, only when you need a custom `leading` marker. A standard row builds it for you from `leadingGlyph` + `tone`.", "avoid": "The common case — pass `leadingGlyph` + `tone` and let the row build the plate.", "axis": "Part" } ], "examples": [], "source": "packages/design-system/src/components/organization/ListItem/ListItem.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-listitem", "json": "/data/visual/components/listitem.json", "storybook": "/storybook/?path=/story/cloaked-design-system-organization-list-item--playground" } }