# 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.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.tsx

## Guidance

{
  "summary": "Overlapping proportional circles for a small summary set, a hero glance where relative magnitude matters more than exact counts, with a gentle breathing motion.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "Overlapping proportional circles for a small summary set — a hero \"here is what we did for you\"\nglance."
    },
    {
      "heading": "When to use",
      "body": "Use ActionOrbs for roughly 2-4 top-level action categories where relative magnitude matters\nmore than exact counts. Orb areas scale to each `value`, so wildly uneven values read as one\nbig orb plus small satellites. Omit `color` to fall back to the built-in palette; the component\nfills its container width and scales with it.\n\nReach for `CategoryBars` when you need a ranked list with readable numeric values, or `BarChart`\nwhen the data is a time series. For a decorative many-category field, use `BubbleMatrix` or\n`BurstGraph`.\n\nNot currently used in the app."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.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."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "items",
      "type": "readonly ActionOrbDatum[]",
      "declared_type": "readonly ActionOrbDatum[]",
      "required": true,
      "description": "Action categories rendered as proportional orbs.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 127
      }
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible label for meaningful chart content.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 129
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 131
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "ActionOrbs",
    "public_path": "ActionOrbs",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "ActionOrbs",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.tsx",
          "line": 10
        },
        "props_type": "ActionOrbsProps",
        "props": [
          {
            "name": "items",
            "type": "readonly ActionOrbDatum[]",
            "declared_type": "readonly ActionOrbDatum[]",
            "required": true,
            "description": "Action categories rendered as proportional orbs.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 127
            }
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible label for meaningful chart content.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 129
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 131
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 112,
        "name": "ActionOrbDatum",
        "code": "export interface ActionOrbDatum {\n    /** Stable action identifier. */\n    id: string;\n    label: React.ReactNode;\n    /** Non-negative action count. */\n    value: number;\n    color?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 125,
        "name": "ActionOrbsProps",
        "code": "export interface ActionOrbsProps {\n    /** Action categories rendered as proportional orbs. */\n    items: readonly ActionOrbDatum[];\n    /** Accessible label for meaningful chart content. */\n    ariaLabel?: string;\n    /** Optional test selector. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "ActionOrbs",
      "status": "preview",
      "version": "1.0.0",
      "summary": "Overlapping proportional circles for a small summary set, a hero glance where relative magnitude matters more than exact counts, with a gentle breathing motion."
    },
    "parts": [
      {
        "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."
      }
    ],
    "allowedDesignChoices": {
      "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": [],
    "measurements": [
      {
        "id": "orb-radius",
        "label": "Orb corner radius",
        "kind": "exact",
        "token": "--cds-radius-full",
        "value": 9999,
        "unit": "px",
        "appliesTo": [
          "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",
        "appliesTo": [
          "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."
      ]
    },
    "typographyAndColor": {
      "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."
      }
    ],
    "contentAdaptation": [
      {
        "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."
      }
    ],
    "motionHaptics": {
      "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."
        }
      ]
    },
    "platformDifferences": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-radius-full",
      "light": "9999px",
      "dark": "9999px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-inverse",
      "light": "#ffffff",
      "dark": "#ffffff"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "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."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Default](/storybook/iframe.html?id=cloaked-design-system-visualizations-actionorbs--default&viewMode=story) | export: Default | source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.stories.tsx

- [Balanced](/storybook/iframe.html?id=cloaked-design-system-visualizations-actionorbs--balanced&viewMode=story) | export: Balanced | source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.stories.tsx

- [Empty](/storybook/iframe.html?id=cloaked-design-system-visualizations-actionorbs--empty&viewMode=story) | export: Empty | source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.stories.tsx

- [Constrained Width](/storybook/iframe.html?id=cloaked-design-system-visualizations-actionorbs--constrained-width&viewMode=story) | export: ConstrainedWidth | source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-visualizations-actionorbs--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/visualizations/ActionOrbs/ActionOrbs.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.