{ "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": "card", "name": "Card", "category": "Cards", "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-cards-card--playground", "name": "Playground", "title": "Cloaked Design System/Cards/Card", "exportName": "Playground", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--playground&viewMode=story" }, { "id": "cloaked-design-system-cards-card--basic", "name": "Basic", "title": "Cloaked Design System/Cards/Card", "exportName": "Basic", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--basic&viewMode=story" }, { "id": "cloaked-design-system-cards-card--radii", "name": "Radii", "title": "Cloaked Design System/Cards/Card", "exportName": "Radii", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--radii&viewMode=story" }, { "id": "cloaked-design-system-cards-card--highlighted-prompt", "name": "Highlighted Prompt", "title": "Cloaked Design System/Cards/Card", "exportName": "HighlightedPrompt", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--highlighted-prompt&viewMode=story" }, { "id": "cloaked-design-system-cards-card--pressable", "name": "Pressable", "title": "Cloaked Design System/Cards/Card", "exportName": "Pressable", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--pressable&viewMode=story" }, { "id": "cloaked-design-system-cards-card--metric-summary", "name": "Metric Summary", "title": "Cloaked Design System/Cards/Card", "exportName": "MetricSummary", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--metric-summary&viewMode=story" }, { "id": "cloaked-design-system-cards-card--sectioned-rows", "name": "Sectioned Rows", "title": "Cloaked Design System/Cards/Card", "exportName": "SectionedRows", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--sectioned-rows&viewMode=story" }, { "id": "cloaked-design-system-cards-card--visualization-content", "name": "Visualization Content", "title": "Cloaked Design System/Cards/Card", "exportName": "VisualizationContent", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--visualization-content&viewMode=story" }, { "id": "cloaked-design-system-cards-card--split-layout", "name": "Split Layout", "title": "Cloaked Design System/Cards/Card", "exportName": "SplitLayout", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--split-layout&viewMode=story" }, { "id": "cloaked-design-system-cards-card--metric-with-unit", "name": "Metric With Unit", "title": "Cloaked Design System/Cards/Card", "exportName": "MetricWithUnit", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--metric-with-unit&viewMode=story" }, { "id": "cloaked-design-system-cards-card--pressable-footer", "name": "Pressable Footer", "title": "Cloaked Design System/Cards/Card", "exportName": "PressableFooter", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--pressable-footer&viewMode=story" }, { "id": "cloaked-design-system-cards-card--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Cards/Card", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--dark-theme&viewMode=story" }, { "id": "cloaked-design-system-cards-card--delta-overflow", "name": "Delta Overflow", "title": "Cloaked Design System/Cards/Card", "exportName": "DeltaOverflow", "source_path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "source_digest": "5a515213100764f15ba28a3d23d00e478eda823ad2470e33803452a1c9907b02", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-cards-card--delta-overflow&viewMode=story" } ], "name": "Card", "id": "card", "category": "Cards" }, "stories_source": { "path": "packages/design-system/src/components/cards/Card/Card.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport React from 'react';\nimport { RiskMeter } from '../../visualizations/RiskMeter/RiskMeter';\nimport { Button } from '../../primitives/Button/Button';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { Tag } from '../../primitives/Tag/Tag';\nimport { Text } from '../../primitives/Text/Text';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { List } from '../../organization/List/List';\nimport { disabledControl, hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport { Card } from './Card';\nimport {\n CARD_PLAYGROUND_ARG_TYPES,\n CARD_PLAYGROUND_ARGS,\n renderCardPlayground,\n deltaOverflowStory,\n renderMetricSummary,\n renderSectionedRows,\n renderVisualizationContent,\n type CardPlaygroundArgs,\n} from './CardRoot/CardRoot.stories.fixtures';\nimport styles from './Card.stories.module.scss';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Cards/Card',\n component: Card,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'The generic surface primitive. Compose it from typed slots rather than raw markup: `Card.Header` / ' +\n '`Card.Body` / `Card.Footer` for regions, `Card.Title` / `Card.Description` for text, `Card.Metric` / ' +\n '`Card.Delta` / `Card.StatusIndicator` for summary figures, and `Card.Stack` for ad-hoc grouping. ' +\n 'Slots own their own padding, so the root usually keeps `padding=\"none\"`. Pass `onPress` to make the ' +\n 'whole card a tap target, or `Card.Footer onPress` for a pressable footer only. Reach for ' +\n '`SelectionCard` when the card is a selectable option instead of a container.',\n },\n },\n },\n argTypes: {\n children: disabledControl,\n onPress: disabledControl,\n testId: disabledControl,\n surface: {\n ...selectArgType(['default', 'highlight']),\n description: 'Background treatment — `highlight` tints the card for prompts and CTAs.',\n },\n radius: {\n ...selectArgType(['xs', 'sm', 'md', 'lg', 'xl']),\n description: 'Corner radius token. Defaults to `lg`.',\n },\n layout: {\n ...selectArgType(['stack', 'split']),\n description: 'Top-level slot direction: `stack` (column) or `split` (row).',\n },\n padding: {\n ...selectArgType(['none', 'default']),\n description: 'Outer padding on the card shell. Slots carry their own padding, so this is usually `none`.',\n },\n haptic: hapticArgType,\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: StoryObj = {\n args: CARD_PLAYGROUND_ARGS,\n argTypes: CARD_PLAYGROUND_ARG_TYPES,\n render: args => renderCardPlayground(args),\n};\n\nexport const Basic: Story = {\n parameters: {\n docs: {\n description: { story: 'Header (title + description) over a body list — the canonical slot composition.' },\n },\n },\n render: () => (\n
\n \n \n Summary\n Composable surface with typed layout slots.\n \n \n \n \n \n \n \n \n
\n ),\n};\n\nexport const Radii: Story = {\n parameters: {\n docs: { description: { story: 'Every `radius` token from `xs` to `xl`. Cards default to `lg`.' } },\n },\n render: () => (\n
\n \n {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map(radius => (\n \n \n \n radius = {radius}\n \n \n {radius}\n \n \n \n ))}\n \n
\n ),\n};\n\nexport const HighlightedPrompt: Story = {\n parameters: {\n docs: {\n description: { story: '`surface=\"highlight\"` tints the card to steer users toward a short next step.' },\n },\n },\n render: () => (\n
\n \n \n Setup task\n Prompt users toward a short next step.\n }\n ariaLabel='Open prompt'\n testId='card-prompt-open'\n />\n \n \n
\n ),\n};\n\nexport const Pressable: Story = {\n parameters: {\n docs: { description: { story: '`onPress` turns the whole card into a button (`pressable` on press).' } },\n },\n render: () => (\n
\n {}} testId='card-pressable-example'>\n \n \n Open details\n \n \n \n \n
\n ),\n};\n\nexport const MetricSummary: Story = {\n parameters: {\n docs: {\n description: {\n story: '`Card.Metric` + `Card.Delta` in a header, a body stat list, and a footer link — the summary-card pattern.',\n },\n },\n },\n render: () => renderMetricSummary(),\n};\n\nexport const SectionedRows: Story = {\n parameters: {\n docs: { description: { story: 'A padding-free body hosting a `List.Section` of leading-avatar rows.' } },\n },\n render: () => renderSectionedRows(),\n};\n\nexport const VisualizationContent: Story = {\n parameters: {\n docs: {\n description: { story: 'A body can host visualizations directly — here a `RiskMeter` above a `LineChart`.' },\n },\n },\n render: () => renderVisualizationContent(),\n};\n\nexport const SplitLayout: Story = {\n parameters: {\n docs: {\n description: {\n story: '`layout=\"split\"` lays the card\\'s top-level slots in a row instead of a column — pair a metric with supporting content.',\n },\n },\n },\n render: () => (\n
\n \n \n \n \n \n \n \n \n \n
\n ),\n};\n\nexport const MetricWithUnit: Story = {\n parameters: {\n docs: {\n description: {\n story: '`Card.Metric` with a `unit` suffix and a downward `Card.Delta` (`direction=\"down\"`) for a declining figure.',\n },\n },\n },\n render: () => (\n
\n \n \n Exposure score\n \n \n \n \n \n \n
\n ),\n};\n\nexport const PressableFooter: Story = {\n parameters: {\n docs: {\n description: {\n story: 'A pressable `Card.Footer` — pass `onPress` to make just the footer a tap target with its own `testId`.',\n },\n },\n },\n render: () => (\n
\n \n \n \n Weekly summary\n \n \n 3 new broker listings found.\n \n \n {}}\n testId='card-footer-pressable'\n >\n \n View report\n \n \n \n \n
\n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n render: () => (\n
\n \n \n Summary\n Composable surface with typed layout slots.\n \n \n \n \n \n \n \n \n
\n ),\n};\n\nexport const DeltaOverflow: Story = deltaOverflowStory;\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Card", "status": "preview", "version": "1.0.0", "summary": "The generic surface primitive, composed from typed slots for regions, text, and summary figures, and optionally pressable." }, "parts": [ { "id": "root", "label": "Root", "description": "Surface shell carrying the surface, radius, layout, and padding.", "required": true }, { "id": "header", "label": "Card.Header", "description": "Top region slot, usually title and status." }, { "id": "body", "label": "Card.Body", "description": "Main region slot for content and lists." }, { "id": "footer", "label": "Card.Footer", "description": "Bottom region slot, optionally pressable." }, { "id": "stack", "label": "Card.Stack", "description": "Ad-hoc grouping slot within a region." }, { "id": "title", "label": "Card.Title", "description": "Region heading; wraps to as many lines as the copy needs." }, { "id": "description", "label": "Card.Description", "description": "Supporting region text." }, { "id": "metric", "label": "Card.Metric", "description": "Large metric value with optional unit." }, { "id": "delta", "label": "Card.Delta", "description": "Change label: a caret or trend marker with the movement, toned success, warning, danger, or neutral. Tone follows the direction unless the figure's sentiment runs against its arrow." } ], "allowedDesignChoices": { "variants": { "container": { "label": "Container", "description": "The single generic surface; content comes from slots." } }, "sizes": {}, "surfaces": { "default": { "label": "Default", "description": "Raised surface background." }, "highlight": { "label": "Highlight", "description": "Tinted background for prompts and CTAs." } }, "radii": { "xs": { "label": "Extra small" }, "sm": { "label": "Small" }, "md": { "label": "Medium" }, "lg": { "label": "Large", "description": "The default corner radius." }, "xl": { "label": "Extra large" } }, "paddings": { "none": { "label": "None", "description": "No outer padding; slots own their padding." }, "default": { "label": "Default", "description": "16-unit outer padding on the shell." } }, "layouts": { "stack": { "label": "Stack", "description": "Top-level slots flow in a column." }, "split": { "label": "Split", "description": "Top-level slots flow in a row." } } }, "variants": [ { "id": "container", "label": "Container", "description": "Generic slotted surface.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "surface-radius", "label": "Default corner radius", "kind": "exact", "token": "--cds-radius-lg", "value": 20, "unit": "px", "appliesTo": [ "root" ] }, { "id": "split-gap", "label": "Split layout gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "root" ] }, { "id": "default-padding", "label": "Default outer padding", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "root" ] } ], "layout": { "alignment": "Slots stack in a column by default, or lay out in a row under the split layout.", "flow": "The shell hosts typed slots; slots own their own padding, so the shell usually keeps padding none.", "notes": [ "Use SelectionCard when the card is a selectable option rather than a container." ] }, "typographyAndColor": { "typography": [ { "label": "Title", "description": "Card.Title uses the body ramp emphasis.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Default surface", "description": "The default surface uses the raised background.", "token": "--cds-bg-surface" }, { "label": "Highlight surface", "description": "The highlight surface uses the banner container tint.", "token": "--cds-banner-container" }, { "label": "Text", "description": "Card content uses primary text.", "token": "--cds-text-primary" }, { "label": "Delta label", "description": "Card.Delta's marker and label mix 60% of the tone's solid colour with 40% primary text for readable contrast on the unchanged subtle fill. Success is shown; danger, warning and neutral follow the same calculation. This local adaptation remains preview pending human sign-off.", "token": "--cds-status-success-solid" }, { "label": "Delta fill", "description": "The delta pill sits on the matching subtle tint for its tone.", "token": "--cds-status-success-subtle" } ] }, "states": [ { "id": "default", "label": "Default", "description": "Static container surface." }, { "id": "highlight", "label": "Highlight", "description": "Tinted prompt surface." }, { "id": "pressable", "label": "Pressable", "description": "onPress makes the whole card a tap target with tap feedback." } ], "behavior": [ { "label": "Slot composition", "description": "Compose regions and figures from typed slots rather than raw markup." }, { "label": "Pressable", "description": "onPress makes the card a button; a pressable footer targets just the footer. The two are mutually exclusive — a pressable footer inside a pressable card would nest interactive controls." }, { "label": "Silhouette measurement", "description": "silhouette marks the card as a measurement target so a page can record its settled geometry for a loading placeholder. Presence-only and non-visual: it renders a data attribute and changes nothing about the card itself." } ], "accessibility": [ { "label": "Pressable name", "description": "Give a pressable card an accessible label when visible copy is insufficient." }, { "label": "Structure", "description": "Slots keep a predictable region order for assistive tech." } ], "contentAdaptation": [ { "label": "Region padding", "description": "Slots carry their own padding tokens so the shell stays padding-free." }, { "label": "Split content", "description": "The split layout pairs a metric with supporting content in a row." } ], "motionHaptics": { "motion": [ { "label": "Press feedback", "description": "Pressable cards apply tap feedback on press." } ], "haptics": [ { "label": "Press haptic", "description": "Pressable cards request a light haptic on a successful press." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/cards/Card/Card.spec.json", "guidance": { "summary": "The generic surface primitive, composed from typed slots for regions, text, and summary figures, and optionally pressable.", "guidance": [ { "heading": "Overview", "body": "The generic surface primitive. Compose it from typed slots — `Card.Header` / `Card.Body` /\n`Card.Footer`, `Card.Title` / `Card.Description`, `Card.Metric` / `Card.Delta` — rather than raw\nmarkup. `surface` encodes emphasis. For a selectable option, use `SelectionCard`." }, { "heading": "Use when", "body": "`surface` is the semantic decision: a plain container versus a tinted prompt.\n\nSlots own their own padding, so the root usually keeps `padding=\"none\"`. `layout=\"split\"` lays the\ntop-level slots in a row instead of a column; it is available but not currently used in app code —\n`stack` is the norm." }, { "heading": "Composition", "body": "Header (title + description) over a body list — the canonical slot arrangement.\n\nThe summary-card pattern pairs `Card.Metric` + `Card.Delta` in a header with a body stat list and a\nfooter link." }, { "heading": "Pressable", "body": "Pass `onPress` to turn the whole card into a tap target, or `Card.Footer onPress` for a pressable\nfooter only." } ], "usage": [ { "variant": "default", "use": "The standard container for grouping content, metrics, and lists. Nearly every card in the app is `default`.", "avoid": "A moment you want to actively steer the user toward — that earns `highlight`.", "axis": "Surface" }, { "variant": "highlight", "use": "A tinted surface that steers users toward a short next step — a setup prompt or inline CTA (ProfileSetupCard).", "avoid": "Ordinary content. Rare by design — at most one per screen so the highlight keeps its pull.", "axis": "Surface" } ], "examples": [], "source": "packages/design-system/src/components/cards/Card/Card.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-card", "json": "/data/visual/components/card.json", "storybook": "/storybook/?path=/story/cloaked-design-system-cards-card--playground" } }