ActionOrbs
Overlapping proportional circles for a small summary set, a hero glance where relative magnitude matters more than exact counts, with a gentle breathing motion.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.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.
Overlapping proportional circles for a small summary set, a hero glance where relative magnitude matters more than exact counts, with a gentle breathing motion.
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 { ActionOrbs } from '@cloakedinc/design-system';ActionOrbsActionOrbsProps
packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.tsx:10
| Prop | Type | Presence | Notes |
|---|---|---|---|
items | readonly ActionOrbDatum[] | Required | Action categories rendered as proportional orbs. |
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
Overlapping proportional circles for a small summary set — a hero "here is what we did for you" glance.
When to use
Use ActionOrbs for roughly 2-4 top-level action categories where relative magnitude matters
more than exact counts. Orb areas scale to each value, so wildly uneven values read as one
big orb plus small satellites. Omit color to fall back to the built-in palette; the component
fills its container width and scales with it.
Reach for CategoryBars when you need a ranked list with readable numeric values, or BarChart
when the data is a time series. For a decorative many-category field, use BubbleMatrix or
BurstGraph.
Not currently used in the app.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- field
- Label
- Field
- Description
- The container the orbs are absolutely placed within, sized by container width.
- Required
- true
- Id
- orb
- Label
- Orb
- Description
- A proportional circle whose area scales to its category value.
- Id
- orb-label
- Label
- Orb label
- Description
- The percentage ink centered inside each orb.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- Category data changes the reading without changing the orb treatment.
- Sizes
Variants
- Id
- base
- Label
- Base
- Description
- Overlapping proportional orbs distributed across the field.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- orb-radius
- Label
- Orb corner radius
- Kind
- exact
- Token
- --cds-radius-full
- Value
- 9999
- Unit
- px
- Applies To
- orb
- Notes
- Each orb is fully rounded (a circle with aspect ratio 1); its diameter is data-driven from the category share, so only the corner radius is fixed.
- Id
- orb-diameter
- Label
- Orb diameter
- Kind
- example-only
- Value
- share-driven
- Unit
- none
- Applies To
- orb
- Notes
- Diameters are a fraction of the container width proportional to each category value, so there is no fixed token size.
Layout
- Alignment
- Orbs are absolutely positioned within a fixed-aspect field and scale with its width.
- Flow
- Overlapping circles layered by z-index, largest reading as the anchor.
- Notes
- The field uses container-query units so orbs scale with the available width.
Typography And Color
- Typography
- Label
- Orb label
- Description
- The percentage inside each orb sits near the body-small ramp.
- Token
- --cds-type-body-small-size
- Colors
- Label
- Orb blend
- Description
- Each orb gradient blends its category color toward the surface.
- Token
- --cds-bg-surface
- Label
- Orb label
- Description
- The percentage ink reads as inverse text over the colored orb.
- Token
- --cds-text-inverse
- Label
- Label shadow
- Description
- A soft shadow tinted from primary text keeps the label legible.
- Token
- --cds-text-primary
States
- Id
- populated
- Label
- Populated
- Description
- Two to four categories render as proportional overlapping orbs.
- Id
- balanced
- Label
- Balanced
- Description
- Equal values render equal orbs, showing the area scaling is honest.
- Id
- empty
- Label
- Empty
- Description
- No items renders nothing, so pair with an upstream empty state.
Behavior
- Label
- Area scaling
- Description
- Orb area scales to each value, so uneven values read as one anchor plus satellites.
- Label
- Small set
- Description
- Keep the set small (roughly two to four categories) so orbs stay legible.
- Label
- Palette fallback
- Description
- Omit a category color to fall back to the built-in action-orb palette.
Accessibility
- Label
- Meaningful chart
- Description
- Pass an accessible label so the field is announced as a meaningful image summarizing the actions.
- Label
- Values in a title
- Description
- Each orb carries a label and percentage title so its meaning is exposed to assistive technology.
Content Adaptation
- Label
- Magnitude over precision
- Description
- Use ActionOrbs for a proportional glance; use CategoryBars when exact counts must be read.
- Label
- Fills its width
- Description
- The field fills and scales with the container, so give it a representative width.
Motion Haptics
- Motion
- Label
- Breathing orbs
- Description
- Orbs gently breathe on a staggered loop to feel alive without demanding attention.
- Label
- Reduced motion
- Description
- When reduced motion is set the breathing stops and orbs hold a still, resolved position.
- Haptics
- Label
- No feedback
- Description
- The chart is a display and requests no haptic feedback.