{ "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": "compositionbar", "name": "CompositionBar", "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-compositionbar--default", "name": "Default", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-compositionbar--clustered", "name": "Clustered", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "Clustered", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--clustered&viewMode=story" }, { "id": "cloaked-design-system-visualizations-compositionbar--one-dominant", "name": "One Dominant", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "OneDominant", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--one-dominant&viewMode=story" }, { "id": "cloaked-design-system-visualizations-compositionbar--default-palette", "name": "Default Palette", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "DefaultPalette", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--default-palette&viewMode=story" }, { "id": "cloaked-design-system-visualizations-compositionbar--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-compositionbar--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/CompositionBar", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "source_digest": "a991d9b384039a828eba358a29fca69d4b9543c2310169554371c795841a912d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-compositionbar--dark-theme&viewMode=story" } ], "name": "CompositionBar", "id": "compositionbar", "category": "Visualizations" }, "stories_source": { "path": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { PII_CATEGORY_COLOR_VARS } from '../../../tokens/piiCategories';\nimport { CompositionBar } from './CompositionBar';\n\nconst items = [\n { id: 'family', label: 'Family', value: 322, color: PII_CATEGORY_COLOR_VARS.family },\n { id: 'name', label: 'Name', value: 311, color: PII_CATEGORY_COLOR_VARS.name },\n { id: 'address', label: 'Address', value: 298, color: PII_CATEGORY_COLOR_VARS.address },\n { id: 'email', label: 'Email', value: 292, color: PII_CATEGORY_COLOR_VARS.email },\n { id: 'phone', label: 'Phone', value: 283, color: PII_CATEGORY_COLOR_VARS.phone },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Visualizations/CompositionBar',\n component: CompositionBar,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A single horizontal bar split into proportional, color-coded segments — each ' +\n \"category's share of the total. Reach for it over `CategoryBars` when the counts \" +\n 'are open-ended (no fixed maximum): a share of the whole reads honestly at any scale, ' +\n 'where length-scaled-to-max would peg the leader near full and imply a ceiling that ' +\n 'does not exist. Each segment takes its `color`; omit `color` and segments cycle the ' +\n 'default category palette. Pair it with a labeled legend for the exact counts.',\n },\n },\n },\n argTypes: {\n items: {\n ...disabledControl,\n description:\n 'Category segments rendered in order; width is each value ÷ the sum. Omit `color` for the default palette.',\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: 'Share of records removed by category' } };\n\nexport const Clustered: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Near-equal values render as near-equal segments — an honest \"spread evenly\" read where scaled bars would all look full.',\n },\n },\n },\n args: { items, ariaLabel: 'Evenly spread category shares' },\n};\n\nexport const OneDominant: Story = {\n parameters: {\n docs: { description: { story: 'A single large category claims most of the bar.' } },\n },\n args: {\n items: [\n { id: 'name', label: 'Name', value: 812, color: PII_CATEGORY_COLOR_VARS.name },\n { id: 'email', label: 'Email', value: 143, color: PII_CATEGORY_COLOR_VARS.email },\n { id: 'phone', label: 'Phone', value: 96, color: PII_CATEGORY_COLOR_VARS.phone },\n { id: 'address', label: 'Address', value: 41, color: PII_CATEGORY_COLOR_VARS.address },\n { id: 'family', label: 'Family', value: 22, color: PII_CATEGORY_COLOR_VARS.family },\n ],\n ariaLabel: 'One dominant category share',\n },\n};\n\nexport const DefaultPalette: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Segments omit `color`, so they cycle the built-in category palette — the fallback path.',\n },\n },\n },\n args: {\n items: items.map(({ color: _color, ...item }) => item),\n ariaLabel: 'Category shares with default palette',\n },\n};\n\nexport const Empty: Story = {\n parameters: {\n docs: { description: { story: 'Zero total renders nothing — pair with an EmptyState upstream.' } },\n },\n args: { items: [], ariaLabel: 'No category shares' },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: { items, ariaLabel: 'Share of records removed by category' },\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "CompositionBar", "status": "preview", "version": "1.0.0", "summary": "A single horizontal bar split into proportional, color-coded segments — each category's share of the total, the composition read for open-ended counts with no fixed maximum." }, "parts": [ { "id": "bar", "label": "Bar", "description": "The full-width pill track that holds the segments.", "required": true }, { "id": "segment", "label": "Segment", "description": "A colored slice whose width is one category's share of the total." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Category data changes the segment widths and colors without changing the bar treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "One pill bar of proportional category segments.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "bar-height", "label": "Bar height", "kind": "exact", "token": "--cds-size-16", "value": 16, "unit": "px", "appliesTo": [ "bar" ] } ], "layout": { "alignment": "Segments sit flush in a single row, each sized to its share of the total.", "flow": "Segments render left to right in the order given.", "notes": [ "The bar is a full-width pill (`--cds-radius-full`) that clips its segments to rounded ends.", "Segment widths are shares of the summed whole, not of the largest value.", "Zero-value categories are dropped so no invisible slivers accumulate." ] }, "typographyAndColor": { "typography": [], "colors": [ { "label": "Segment", "description": "Each segment uses its own `item.color` — canonically one of the PII category tokens (`PII_CATEGORY_COLOR_VARS`), one per category — or cycles the default category palette when none is given.", "token": "--cds-pii-category-name" } ] }, "states": [ { "id": "composition", "label": "Composition", "description": "Segments render in order, each sized to its share of the total." }, { "id": "default-palette", "label": "Default palette", "description": "Segments without a color cycle the built-in category palette." }, { "id": "empty", "label": "Empty", "description": "A zero total renders nothing, so pair with an upstream empty state." } ], "behavior": [ { "label": "Share of the whole", "description": "Segment width is each value divided by the sum, so the bar always fills and never implies a fixed maximum." }, { "label": "Palette fallback", "description": "Segments take their own color, or cycle the default category palette when none is given." }, { "label": "Drops empty slices", "description": "Categories at or below zero are omitted rather than rendered as invisible segments." } ], "accessibility": [ { "label": "Meaningful chart", "description": "Pass an accessible label so the bar is announced as a meaningful image." }, { "label": "Pair with a legend", "description": "The bar shows proportion only; surface category labels and exact counts in an adjacent legend." } ], "contentAdaptation": [ { "label": "Open-ended counts", "description": "Use CompositionBar when a running total has no goal or maximum and the reader needs the mix, not exact magnitudes." }, { "label": "Read the numbers", "description": "Use CategoryBars instead when the reader must compare exact category magnitudes side by side." } ], "motionHaptics": { "motion": [ { "label": "No intrinsic motion", "description": "Segments do not animate on mount; a parent may transition the whole bar." } ], "haptics": [ { "label": "No feedback", "description": "The chart is a display and requests no haptic feedback." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.spec.json", "guidance": { "summary": "A single horizontal bar split into proportional, color-coded segments — each category's share of the total, the composition read for open-ended counts with no fixed maximum.", "guidance": [ { "heading": "Overview", "body": "A single horizontal bar split into proportional, color-coded segments — each category's share of\nthe total." }, { "heading": "When to use", "body": "Reach for it when the counts are **open-ended** — a running total with no fixed maximum or goal.\nA share of the whole reads honestly at any scale: a brand-new user and a power user both see a\nmeaningful mix. `CategoryBars` scales length to the largest value, which pegs the leader near full\nand implies a ceiling that does not exist, so prefer this when the question is \"what's the mix?\"\nrather than \"read the exact magnitudes.\"\n\nEach segment takes its `color`; omit `color` and segments cycle the default category palette. Pair\nit with a labeled legend when the reader also needs the exact counts." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.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-compositionbar", "json": "/data/visual/components/compositionbar.json", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-compositionbar--default" } }