BubbleMatrix
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.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.stories.tsxExport DefaultImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
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.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { BubbleMatrix } from '@cloakedinc/design-system';BubbleMatrixBubbleMatrixProps
packages/design-system/src/components/visualizations/BubbleMatrix/BubbleMatrix.tsx:14
| Prop | Type | Presence | Notes |
|---|---|---|---|
items | readonly CategoryDatum[] | Required | Category values used to render axis bubbles and plot dots. |
value | number | undefined | Optional | Total value highlighted by the scan visualization. |
progress | number | undefined | Optional | Optional progress value from 0-100 used for static scan positioning.Source default: 0 |
ariaLabel | string | undefined | Optional | Accessible label for meaningful chart content. |
testId | string | undefined | Optional | Optional test selector. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A canvas scan-field of category bubbles — a decorative "we are combing your data" visual, not a precise chart.
When to use
Reach for BubbleMatrix as the centerpiece of a scanning or monitoring surface, where the point
is texture and motion rather than exact reads. Bubble size loosely encodes each value,
progress (0-100) positions the scan sweep, and value is the headline total.
Because magnitudes are felt, not measured, pick a different chart whenever the reader needs to
compare categories accurately: CategoryBars for readable ranked values, ActionOrbs for a
proportional small-set summary. Pick BurstGraph when you want a single big center value with
category points radiating out instead of a scan field.
Not currently used in the app.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- 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.
Allowed Design Choices
- 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
None specifiedMeasurements
- Id
- badge-diameter
- Label
- Category badge diameter
- Kind
- example-only
- Token
- --cds-size-20
- Value
- 40
- Unit
- px
- Applies To
- 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
- Applies To
- 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.
Typography And Color
- 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.
Content Adaptation
- 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.
Motion Haptics
- 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.