{ "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": "list", "name": "List", "category": "Organization", "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": "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--sections", "name": "Sections", "title": "Cloaked Design System/Organization/List", "exportName": "Sections", "source_path": "packages/design-system/src/components/organization/List/List.stories.tsx", "source_digest": "aa28d22a497f9df5ced7229de8762f21680597515a8cfed52daab2d4b364eda7", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list--sections&viewMode=story" }, { "id": "cloaked-design-system-organization-list--plain-rows", "name": "Plain Rows", "title": "Cloaked Design System/Organization/List", "exportName": "PlainRows", "source_path": "packages/design-system/src/components/organization/List/List.stories.tsx", "source_digest": "aa28d22a497f9df5ced7229de8762f21680597515a8cfed52daab2d4b364eda7", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list--plain-rows&viewMode=story" }, { "id": "cloaked-design-system-organization-list--disclosure", "name": "Disclosure", "title": "Cloaked Design System/Organization/List", "exportName": "Disclosure", "source_path": "packages/design-system/src/components/organization/List/List.stories.tsx", "source_digest": "aa28d22a497f9df5ced7229de8762f21680597515a8cfed52daab2d4b364eda7", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list--disclosure&viewMode=story" }, { "id": "cloaked-design-system-organization-list--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Organization/List", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/organization/List/List.stories.tsx", "source_digest": "aa28d22a497f9df5ced7229de8762f21680597515a8cfed52daab2d4b364eda7", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-list--dark-theme&viewMode=story" } ], "name": "List", "id": "list", "category": "Organization" }, "stories_source": { "path": "packages/design-system/src/components/organization/List/List.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Avatar } from '../../primitives/Avatar/Avatar';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { List } from './List';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Organization/List',\n component: List,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Rich list container that stacks `List.Item` rows with an automatic hairline between ' +\n \"adjacent rows. The container owns separators — a row's own `divider` is ignored inside a \" +\n '`List`, so leave it off children here. Group rows under a labeled band with `List.Section` ' +\n '(use `SectionHeader` instead for a heading that stands alone outside a list). Reveal extra ' +\n 'rows inline with a single `List.Disclosure`, or show independent panels with `Accordion`. ' +\n 'Works standalone, not only inside `Card`.',\n },\n },\n },\n argTypes: {\n children: {\n ...disabledControl,\n description: '`List.Item` rows, `List.Section` groups, and/or `Divider` boundaries in render order.',\n },\n ariaLabel: {\n control: 'text',\n description: 'Accessible label announced for the list (maps to `aria-label`).',\n },\n className: disabledControl,\n style: disabledControl,\n testId: {\n control: 'text',\n description: 'Test selector on the list container.',\n },\n },\n decorators: [\n Story => (\n
\n \n
\n ),\n ],\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Sections: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Rows grouped under `List.Section` labels; the container draws hairlines between adjacent rows.',\n },\n },\n },\n render: () => (\n \n \n }\n title='Monitoring data broker sites'\n description='Watching data broker sites for your info'\n />\n }\n title='Dark web monitoring'\n description=\"We'll alert you on any new leaks\"\n />\n \n\n \n }\n title='Next scan'\n description='Starting soon'\n value='Aug 11'\n />\n \n \n ),\n};\n\nexport const PlainRows: Story = {\n parameters: {\n docs: {\n description: { story: 'Ungrouped pressable rows — `onPress` + `chevron`, each with its own `testId`.' },\n },\n },\n render: () => (\n \n {}}\n testId='list-stop-tracking'\n />\n {}}\n testId='list-remove-data'\n />\n \n ),\n};\n\nexport const Disclosure: Story = {\n parameters: {\n docs: { description: { story: '`List.Disclosure` reveals extra rows inline, sharing the list separators.' } },\n },\n render: () => (\n \n \n \n \n \n \n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: {\n docs: { description: { story: 'Section grouping and row hairlines on the dark theme surface.' } },\n },\n render: () => (\n \n \n }\n title='Monitoring data broker sites'\n description='Watching data broker sites for your info'\n />\n }\n title='Dark web monitoring'\n description=\"We'll alert you on any new leaks\"\n />\n \n \n }\n title='Next scan'\n description='Starting soon'\n value='Aug 11'\n />\n \n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "List", "status": "preview", "version": "1.3.0", "summary": "A rich list container that stacks rows with automatic hairlines, groups them with sections, and reveals extras inline via disclosure." }, "parts": [ { "id": "root", "label": "Root", "description": "List surface that owns separators between adjacent rows.", "required": true }, { "id": "item", "label": "List.Item", "description": "Base row with leading, title, description, value, and trailing slots." }, { "id": "section", "label": "List.Section", "description": "Labeled band that groups rows." }, { "id": "disclosure", "label": "List.Disclosure", "description": "Show-more row that reveals extra rows inline. The trigger centers its label and chevron." }, { "id": "selection", "label": "List.Item.Selection", "description": "Selection row with a check or radio control, trailing by default or replacing the leading icon via selectionPlacement='leading'." }, { "id": "progress", "label": "List.Item.Progress", "description": "Row with inline or trailing progress." }, { "id": "stat", "label": "List.Item.Stat", "description": "Compact label and value row." }, { "id": "empty", "label": "List.Item.Empty", "description": "Placeholder row for an empty list." }, { "id": "icon", "label": "List.Item.Icon", "description": "Leading icon helper for a row." } ], "allowedDesignChoices": { "variants": { "container": { "label": "Container", "description": "The single list surface; rows come from List.Item helpers." } }, "sizes": {} }, "variants": [ { "id": "container", "label": "Container", "description": "Row container with automatic separators.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "row-min-height", "label": "Rich row minimum height", "kind": "exact", "token": "--cds-size-80", "value": 80, "unit": "px", "appliesTo": [ "item" ] }, { "id": "compact-row-min-height", "label": "Compact row minimum height", "kind": "exact", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "item", "stat" ] }, { "id": "selection-row-min-height", "label": "Selection row minimum height, copy only", "kind": "at-least", "token": "--cds-size-64", "value": 64, "unit": "px", "appliesTo": [ "selection" ] }, { "id": "row-gap", "label": "Row content gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "item" ] }, { "id": "row-inset", "label": "Row horizontal inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "item" ] } ], "layout": { "alignment": "Leading, body, value, and trailing align on the row center line.", "flow": "Rows stack vertically; the container inserts a hairline between adjacent rows and expands sections into labeled bands.", "notes": [ "Use SectionHeader for a heading that stands alone outside a list.", "Use Accordion for independent expandable panels." ] }, "typographyAndColor": { "typography": [ { "label": "Title", "description": "Row titles use the body ramp.", "token": "--cds-type-body-size" }, { "label": "Description", "description": "Row descriptions use the body-small ramp.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Text", "description": "Row text uses primary text color.", "token": "--cds-text-primary" }, { "label": "Separator", "description": "Adjacent rows are divided with the divider color.", "token": "--cds-divider" } ] }, "states": [ { "id": "default", "label": "Default", "description": "Static rows separated by hairlines." }, { "id": "pressable", "label": "Pressable", "description": "A row with onPress becomes a tap target, usually with a chevron." }, { "id": "selected", "label": "Selected", "description": "A selection row reflects its selected state." }, { "id": "disabled", "label": "Disabled", "description": "A dimmed row that cannot be pressed; a disabled selection row still announces its selection state." } ], "behavior": [ { "label": "Owns separators", "description": "The container draws separators, so a row's own divider is ignored inside a List." }, { "label": "Grouping", "description": "List.Section expands into a labeled band followed by its divider-off rows." }, { "label": "Section-aware disclosure separators", "description": "Revealed rows inside List.Disclosure get separators like the root, but never adjacent to a Divider, so a section header's own hairline is not doubled." }, { "label": "Tag-only sizing", "description": "A row whose only trailing content is a tag keeps the plain row's height: the tag substitutes for the value text, not for a leading tile, so it does not promote the row to the rich 80px accessory height. Adding a chevron or custom trailing alongside the tag does." }, { "label": "Selection placement", "description": "selectionPlacement='leading' renders the selection control in the leading slot, replacing the leading icon — the iOS edit-mode treatment for icon-led rows. Default stays trailing." } ], "accessibility": [ { "label": "List semantics", "description": "The container exposes role=list and owns a role=listitem wrapper for each content row; section dividers are labels rather than counted rows. Set ariaLabel to name the list. Standalone row components do not claim listitem semantics." }, { "label": "Row targets", "description": "Pressable rows are buttons with their own testId and accessible name." } ], "contentAdaptation": [ { "label": "Row helpers", "description": "Selection, Progress, Stat, Empty, and Icon helpers shape rows for different content." }, { "label": "Truncation", "description": "Titles and values truncate to one line while descriptions can wrap." } ], "motionHaptics": { "motion": [ { "label": "Disclosure", "description": "List.Disclosure animates revealed rows inline; base rows do not animate." } ], "haptics": [ { "label": "Row haptic", "description": "Pressable and selection rows request feedback through their own behavior." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/organization/List/List.spec.json", "guidance": { "summary": "A rich list container that stacks rows with automatic hairlines, groups them with sections, and reveals extras inline via disclosure.", "guidance": [ { "heading": "Overview", "body": "The container for stacked `List.Item` rows — it draws an automatic hairline between adjacent rows\nand groups them with `List.Section`." }, { "heading": "When to use", "body": "Reach for `List` any time you render a vertical run of rows that share separators — activity feeds,\nsettings, action lists. The container owns the dividers, so a row's own `divider` prop is ignored\ninside a `List`. See the [List.Item](/docs/cloaked-design-system-organization-list-item--docs) docs for the\nrow parts (leading, title, value, chevron, progress, selection).\n\n- Sections whose bodies stay collapsed until tapped? Use `Accordion` (independent chrome) or\n `List.Disclosure` for a single inline \"show more\" that shares these separators.\n- A self-contained block of grouped content (heading + body + actions), not a row run? Use `Card`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/organization/List/List.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-list", "json": "/data/visual/components/list.json", "storybook": "/storybook/?path=/story/cloaked-design-system-organization-list--sections" } }