{ "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": "bubblematrix", "name": "BubbleMatrix", "category": "Visualizations", "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-visualizations-bubblematrix--default", "name": "Default", "title": "Cloaked Design System/Visualizations/BubbleMatrix", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsx", "source_digest": "cc3d5f5f76b023f0131e5dec799f1631bfe533a7ae8aaf046c1f1d332698c20e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-bubblematrix--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-bubblematrix--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/BubbleMatrix", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsx", "source_digest": "cc3d5f5f76b023f0131e5dec799f1631bfe533a7ae8aaf046c1f1d332698c20e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-bubblematrix--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-bubblematrix--dense", "name": "Dense", "title": "Cloaked Design System/Visualizations/BubbleMatrix", "exportName": "Dense", "source_path": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsx", "source_digest": "cc3d5f5f76b023f0131e5dec799f1631bfe533a7ae8aaf046c1f1d332698c20e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-bubblematrix--dense&viewMode=story" }, { "id": "cloaked-design-system-visualizations-bubblematrix--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/BubbleMatrix", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsx", "source_digest": "cc3d5f5f76b023f0131e5dec799f1631bfe533a7ae8aaf046c1f1d332698c20e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-bubblematrix--dark-theme&viewMode=story" } ], "name": "BubbleMatrix", "id": "bubblematrix", "category": "Visualizations" }, "stories_source": { "path": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { BubbleMatrix } from './BubbleMatrix';\n\nconst items = [\n { id: 'name', label: 'Name', value: 15, color: '#00c876' },\n { id: 'email', label: 'Email', value: 32, color: '#ffd447' },\n { id: 'phone', label: 'Phone', value: 16, color: '#e172eb' },\n { id: 'address', label: 'Address', value: 24, color: '#0067ff' },\n { id: 'family', label: 'Family', value: 13, color: '#003677' },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Visualizations/BubbleMatrix',\n component: BubbleMatrix,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A scan-style scatter of category bubbles — a decorative \"we are combing your data\" ' +\n 'visual, not a precise chart. Bubble size encodes each `value`; `progress` (0–100) ' +\n 'statically positions the scan sweep and `value` is the headline total. Use it as the ' +\n 'centerpiece of a scanning/monitoring surface where the point is texture and motion, ' +\n 'not exact reads. Pick `BurstGraph` instead when you want a single big center value ' +\n 'radiating category points, or `CategoryBars`/`ActionOrbs` when the reader needs to ' +\n 'compare category magnitudes accurately.',\n },\n },\n },\n argTypes: {\n items: { ...disabledControl, description: 'Category values; each becomes a bubble sized to its `value`.' },\n value: { control: { type: 'number' }, description: 'Headline total highlighted by the scan.' },\n progress: {\n control: { type: 'range', min: 0, max: 100, step: 1 },\n description: 'Scan sweep position, 0–100; drives static dot placement (not the bubble sizes).',\n },\n ariaLabel: { control: 'text', description: 'Accessible label; sets `role=\"img\"`.' },\n testId: { control: 'text', description: 'Test selector on the chart root.' },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Default: Story = { args: { items, value: 100, progress: 42, ariaLabel: 'Category scan matrix' } };\n\nexport const Empty: Story = {\n parameters: {\n docs: { description: { story: 'No items — the scan field renders without bubbles.' } },\n },\n args: { items: [], ariaLabel: 'No category bubbles' },\n};\n\nexport const Dense: Story = {\n parameters: {\n docs: { description: { story: 'Doubled values and near-complete `progress` — stress the crowded layout.' } },\n },\n args: {\n items: items.map(item => ({ ...item, value: item.value * 2 })),\n value: 200,\n progress: 76,\n ariaLabel: 'Dense category scan matrix',\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: { items, value: 100, progress: 42, ariaLabel: 'Category scan matrix' },\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "BubbleMatrix", "status": "preview", "version": "1.0.0", "summary": "A scan-style scatter of category badges and nodes drawn on a canvas, a decorative we-are-combing-your-data visual sized by category value rather than a precise chart." }, "parts": [ { "id": "canvas", "label": "Canvas", "description": "The square canvas the scan field is drawn onto.", "required": true }, { "id": "badge", "label": "Category badge", "description": "The per-row badge showing a category value." }, { "id": "node", "label": "Scan node", "description": "A dot placed along a row by the sweep." }, { "id": "legend", "label": "Legend", "description": "The category color key beneath the rows." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Category data and progress change the reading without changing the scan treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A canvas scan field of badges, nodes, and a legend.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "badge-diameter", "label": "Category badge diameter", "kind": "example-only", "token": "--cds-size-20", "value": 40, "unit": "px", "appliesTo": [ "badge" ], "notes": "Badges are drawn on the canvas at a 20-unit radius, matching the --cds-size-20 token; the value is a canvas constant rather than a CSS-token binding, so this is example-only." }, { "id": "node-radius", "label": "Scan node radius", "kind": "example-only", "token": "--cds-size-4", "value": 4, "unit": "px", "appliesTo": [ "node" ], "notes": "Scan nodes are drawn at a 4-unit radius, matching the --cds-size-4 token; the value is a canvas constant rather than a CSS-token binding, so this is example-only." } ], "layout": { "alignment": "The canvas is centered up to its width cap and keeps a square aspect.", "flow": "Category rows stack vertically with badges on the left and a legend beneath.", "notes": [ "The scan field is drawn on a canvas, so its geometry is expressed in canvas units, not CSS tokens." ] }, "typographyAndColor": { "typography": [ { "label": "Legend and badge text", "description": "Canvas legend and badge labels are drawn near the body ramp size.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Field", "description": "The scan field background.", "token": "--cds-bg-surface" }, { "label": "Axis and gray nodes", "description": "Row axes and settled gray nodes.", "token": "--cds-divider" }, { "label": "Playhead", "description": "The sweep playhead is drawn from primary text at reduced opacity.", "token": "--cds-text-primary" }, { "label": "Legend text", "description": "Legend labels use secondary text.", "token": "--cds-text-secondary" } ] }, "states": [ { "id": "scanning", "label": "Scanning", "description": "With motion allowed the sweep animates nodes across the rows." }, { "id": "static", "label": "Static", "description": "Under reduced motion a still frame is drawn from the progress value with no animation." }, { "id": "empty", "label": "Empty", "description": "No items renders nothing, so pair with an upstream empty state." } ], "behavior": [ { "label": "Decorative texture", "description": "Use BubbleMatrix for scanning texture and motion, not for precise magnitude reads." }, { "label": "Static progress", "description": "The progress value positions the static sweep and drives node density per row." }, { "label": "Value density", "description": "Node density per row scales with each category value." } ], "accessibility": [ { "label": "Meaningful chart", "description": "Pass an accessible label on the wrapper so the scan is announced as a meaningful image." }, { "label": "Canvas is hidden", "description": "The inner canvas is hidden from assistive technology; the wrapper label carries the meaning." } ], "contentAdaptation": [ { "label": "Texture over precision", "description": "Use BubbleMatrix for a scanning centerpiece; use CategoryBars or ActionOrbs for accurate comparison." }, { "label": "Center value", "description": "Pick BurstGraph instead when you want a single big center value radiating category points." } ], "motionHaptics": { "motion": [ { "label": "Scan sweep", "description": "A playhead sweeps back and forth, emitting nodes that travel to their badges." }, { "label": "Reduced motion", "description": "When reduced motion is set the sweep is replaced by a single static frame positioned by progress." } ], "haptics": [ { "label": "No feedback", "description": "The chart is a display and requests no haptic feedback." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.spec.json", "guidance": { "summary": "A scan-style scatter of category badges and nodes drawn on a canvas, a decorative we-are-combing-your-data visual sized by category value rather than a precise chart.", "guidance": [ { "heading": "Overview", "body": "A canvas scan-field of category bubbles — a decorative \"we are combing your data\" visual, not a\nprecise chart." }, { "heading": "When to use", "body": "Reach for BubbleMatrix as the centerpiece of a scanning or monitoring surface, where the point\nis texture and motion rather than exact reads. Bubble size loosely encodes each `value`,\n`progress` (0-100) positions the scan sweep, and `value` is the headline total.\n\nBecause magnitudes are felt, not measured, pick a different chart whenever the reader needs to\ncompare categories accurately: `CategoryBars` for readable ranked values, `ActionOrbs` for a\nproportional small-set summary. Pick `BurstGraph` when you want a single big center value with\ncategory points radiating out instead of a scan field.\n\nNot currently used in the app." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.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-bubblematrix", "json": "/data/visual/components/bubblematrix.json", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-bubblematrix--default" } }