{ "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": "burstgraph", "name": "BurstGraph", "category": "Visualizations", "summary": "A radial burst drawn on a canvas, with category-colored points spraying outward distributed by value, for decorative categorical texture.", "documentation": { "summary": "A radial burst drawn on a canvas, with category-colored points spraying outward distributed by value, for decorative categorical texture.", "guidance": [ { "heading": "Overview", "body": "A radial burst around a single headline stat: the `value` + `label` sit in the center while\ncategory points spray outward." }, { "heading": "When to use", "body": "Use BurstGraph as a hero KPI when you want one big number with categorical texture behind it -\nthe points distribute by each `items` value and take their category `color` (falling back to\n`accentColor` when a category has none). Like `BubbleMatrix`, it conveys feel, not precise\nreads.\n\nPick `BubbleMatrix` instead for a scan-field layout, or `CategoryBars`/`ActionOrbs` when the\ncategory magnitudes must be read precisely rather than felt. For a headline number paired with\na real trend line, use `MetricLineChartCard`.\n\nNot currently used in the app." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.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." }, "source": { "path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.tsx", "code": "import React from 'react';\nimport type { BurstGraphProps } from '../types';\nimport { BURST_GRAPH_CANVAS_SIZE, normalizeBurstGraphItems, runBurstGraphAnimation } from '../burstGraphGraphics';\nimport { useReducedMotion } from '../useReducedMotion';\nimport styles from './BurstGraph.module.scss';\n\n/**\n * An animated radial burst whose particles are colored by category weight — decorative texture\n * behind a headline stat, not a readable chart. Use `CategoryBars` when the magnitudes have to be\n * read rather than felt, or `BubbleMatrix` for the same decorative role in a scan-field layout.\n */\nexport function BurstGraph({ items, accentColor, ariaLabel, testId }: BurstGraphProps) {\n const canvasRef = React.useRef(null);\n const reducedMotion = useReducedMotion();\n const safeItems = React.useMemo(() => normalizeBurstGraphItems(items, accentColor), [accentColor, items]);\n\n React.useEffect(() => {\n const canvas = canvasRef.current;\n if (!canvas) return undefined;\n\n return runBurstGraphAnimation({\n canvas,\n items: safeItems,\n reducedMotion,\n });\n }, [reducedMotion, safeItems]);\n\n return (\n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "BurstGraph", "status": "preview", "version": "2.0.0", "summary": "A radial burst drawn on a canvas, with category-colored points spraying outward distributed by value, for decorative categorical texture." }, "parts": [ { "id": "canvas", "label": "Canvas", "description": "The square canvas the burst is drawn onto.", "required": true }, { "id": "ray", "label": "Ray", "description": "A structural line radiating from the hub." }, { "id": "particle", "label": "Particle", "description": "A category-colored point spraying outward from the center." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Category data changes the reading without changing the burst treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A canvas radial burst of category particles.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "particle-size", "label": "Particle size", "kind": "example-only", "token": "--cds-size-8", "value": 8, "unit": "px", "appliesTo": [ "particle" ], "notes": "Particles peak at an 8-unit radius, matching the --cds-size-8 token; the value is a canvas constant rather than a CSS-token binding, and the drawn size is depth- and life-driven, so this is example-only." } ], "layout": { "alignment": "The canvas is centered up to its width cap and keeps a square aspect.", "flow": "Rays and particles radiate from the hub.", "notes": [ "The burst is drawn on a canvas, so its geometry is expressed in canvas units, not CSS tokens." ] }, "typographyAndColor": { "typography": [], "colors": [ { "label": "Rays", "description": "Structural rays and their endpoints.", "token": "--cds-divider" } ] }, "states": [ { "id": "bursting", "label": "Bursting", "description": "With motion allowed particles continuously spawn, travel, and fade." }, { "id": "static", "label": "Static", "description": "Under reduced motion a single settled frame is drawn with no further spawning." }, { "id": "empty", "label": "Empty", "description": "No items shows the empty burst state." } ], "behavior": [ { "label": "Value distribution", "description": "Particle colors are weighted by each category value so bigger categories spray more." }, { "label": "Accent fallback", "description": "Categories with no color fall back to the accent color, then to a default accent." } ], "accessibility": [ { "label": "Meaningful chart", "description": "Pass an accessible label so the burst is announced as a meaningful image." }, { "label": "Decorative burst", "description": "Omit the label to hide the canvas from assistive technology when nearby text carries the meaning." } ], "contentAdaptation": [ { "label": "Decorative texture", "description": "Use BurstGraph for categorical texture; surface any headline count in nearby copy." }, { "label": "Precision elsewhere", "description": "Use CategoryBars or ActionOrbs when category magnitudes must be read precisely." } ], "motionHaptics": { "motion": [ { "label": "Radial burst", "description": "The structure rotates gently while particles spawn, travel outward, and fade." }, { "label": "Reduced motion", "description": "When reduced motion is set a single settled frame is drawn and no further frames are scheduled." } ], "haptics": [ { "label": "No feedback", "description": "The chart is a display and requests no haptic feedback." } ] }, "platformDifferences": [] }, "spec_source": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.spec.json", "guidance_source": { "path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './BurstGraph.stories';\nimport burstGraphSpec from './BurstGraph.spec.json';\n\n\n\n# BurstGraph\n\nA radial burst around a single headline stat: the `value` + `label` sit in the center while\ncategory points spray outward.\n\n\n\n## When to use\n\nUse BurstGraph as a hero KPI when you want one big number with categorical texture behind it -\nthe points distribute by each `items` value and take their category `color` (falling back to\n`accentColor` when a category has none). Like `BubbleMatrix`, it conveys feel, not precise\nreads.\n\nPick `BubbleMatrix` instead for a scan-field layout, or `CategoryBars`/`ActionOrbs` when the\ncategory magnitudes must be read precisely rather than felt. For a headline number paired with\na real trend line, use `MetricLineChartCard`.\n\nNot currently used in the app.\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "items", "type": "readonly CategoryDatum[]", "declared_type": "readonly CategoryDatum[]", "required": true, "description": "Category values used to distribute and color burst points.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 103 } }, { "name": "accentColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional accent color used when no category color is available.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 105 } }, { "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": 107 } }, { "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": 109 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-size-8", "light": "8px", "dark": "8px" }, { "name": "--cds-divider", "light": "#e0ddd6", "dark": "#ffffff1a" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-visualizations-burstgraph--default", "name": "Default", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--accent-color-fallback", "name": "Accent Color Fallback", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "AccentColorFallback", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--accent-color-fallback&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--dense", "name": "Dense", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Dense", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--dense&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--dark-theme&viewMode=story" } ], "name": "BurstGraph", "id": "burstgraph", "category": "Visualizations" }, "stories": [ { "id": "cloaked-design-system-visualizations-burstgraph--default", "name": "Default", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--accent-color-fallback", "name": "Accent Color Fallback", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "AccentColorFallback", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--accent-color-fallback&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--dense", "name": "Dense", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "Dense", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--dense&viewMode=story" }, { "id": "cloaked-design-system-visualizations-burstgraph--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/BurstGraph", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "source_digest": "e3d536afe63750e9189584a9228c8dd9b940271c3971db084b4b281890f66bd5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-burstgraph--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { BurstGraph } from './BurstGraph';\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/BurstGraph',\n component: BurstGraph,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A radial burst of category points spraying outward, distributed and colored by each ' +\n '`items` `value`. Use it as decorative categorical texture; surface any headline count ' +\n 'in surrounding copy rather than the burst itself. Each point takes its category ' +\n '`color`; when a category has none, the burst falls back to `accentColor` (and to its ' +\n 'own default accent when that is also unset). Prefer `BubbleMatrix` for a scan-field ' +\n 'layout, or `CategoryBars`/`ActionOrbs` when the category magnitudes must be read ' +\n 'precisely rather than felt.',\n },\n },\n },\n argTypes: {\n items: { ...disabledControl, description: 'Category values; distribute and color the burst points radially.' },\n accentColor: {\n control: 'color',\n description: 'Fallback point color used for any category missing its own `color`.',\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, ariaLabel: 'Request burst graph' } };\n\nexport const AccentColorFallback: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Items carry no `color`, so every point falls back to `accentColor` — the path used ' +\n 'when categories are unpalettized.',\n },\n },\n },\n args: {\n items: items.map(({ color: _color, ...item }) => item),\n accentColor: '#0067ff',\n ariaLabel: 'Single-accent request burst graph',\n },\n};\n\nexport const Empty: Story = {\n parameters: {\n docs: { description: { story: 'No items — the empty burst state.' } },\n },\n args: { items: [], ariaLabel: 'Empty request burst graph' },\n};\n\nexport const Dense: Story = {\n parameters: {\n docs: { description: { story: 'Doubled category values pack more points into the burst.' } },\n },\n args: {\n items: items.map(item => ({ ...item, value: item.value * 2 })),\n ariaLabel: 'Dense request burst graph',\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: { items, ariaLabel: 'Request burst graph' },\n};\n" }, "links": { "human": "/component-burstgraph", "json": "/data/components/burstgraph.json", "markdown": "/data/components/burstgraph.md", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-burstgraph--default" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "BurstGraph", "public_path": "BurstGraph", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "BurstGraph", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/visualizations/BurstGraph/BurstGraph.tsx", "line": 12 }, "props_type": "BurstGraphProps", "props": [ { "name": "items", "type": "readonly CategoryDatum[]", "declared_type": "readonly CategoryDatum[]", "required": true, "description": "Category values used to distribute and color burst points.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 103 } }, { "name": "accentColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional accent color used when no category color is available.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 105 } }, { "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": 107 } }, { "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": 109 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 46, "name": "CategoryDatum", "code": "export interface CategoryDatum {\n /** Stable category identifier. */\n id: string;\n label: React.ReactNode;\n /** Non-negative category count or magnitude. */\n value: number;\n color?: string;\n}" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 101, "name": "BurstGraphProps", "code": "export interface BurstGraphProps {\n /** Category values used to distribute and color burst points. */\n items: readonly CategoryDatum[];\n /** Optional accent color used when no category color is available. */\n accentColor?: string;\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." }, "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" } }, "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." } ], "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." } }