{ "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": "categorybars", "name": "CategoryBars", "category": "Visualizations", "summary": "Horizontal labeled bars for a ranked breakdown of a handful of named categories with their counts visible, the read-the-numbers chart in the family.", "documentation": { "summary": "Horizontal labeled bars for a ranked breakdown of a handful of named categories with their counts visible, the read-the-numbers chart in the family.", "guidance": [ { "heading": "Overview", "body": "Horizontal labeled bars — a ranked breakdown of a handful of named categories with their counts\nvisible." }, { "heading": "When to use", "body": "This is the \"read the actual numbers\" chart: reach for it when the reader must compare the\nmagnitudes of a small set of named categories and see the exact counts. Each row takes its\n`color`; omit `color` and rows cycle the default category palette.\n\nPrefer it over `ActionOrbs` (a looser proportional 2-4 category summary) and\n`BubbleMatrix`/`BurstGraph` (decorative) whenever precision matters. Use `BarChart` instead when\nthe x-axis is time rather than categories.\n\nNot currently used in the app." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.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/CategoryBars/CategoryBars.tsx", "code": "import React, { useMemo } from 'react';\nimport { Text } from '../../primitives/Text/Text';\nimport { getDefaultVisualizationColor } from '../defaultColors';\nimport type { CategoryBarsProps } from '../types';\nimport styles from './CategoryBars.module.scss';\n\n/**\n * Ranked horizontal bars with each category's count printed beside it — the chart to reach for\n * when the exact numbers must be readable. Bar length scales to the largest value in `items`, so\n * use `CompositionBar` when the interesting quantity is each category's share of a total.\n */\nexport function CategoryBars({ items, ariaLabel, testId }: CategoryBarsProps) {\n const maxValue = useMemo(() => Math.max(...items.map(item => item.value), 1), [items]);\n\n if (items.length === 0) return null;\n\n return (\n \n {items.map((item, index) => {\n const value = Math.max(0, item.value);\n const style = {\n '--category-color': item.color ?? getDefaultVisualizationColor(index),\n '--category-percent': `${Math.min(100, (value / maxValue) * 100)}%`,\n } as React.CSSProperties;\n\n return (\n
\n \n {item.label}\n \n
\n );\n })}\n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "CategoryBars", "status": "preview", "version": "1.0.0", "summary": "Horizontal labeled bars for a ranked breakdown of a handful of named categories with their counts visible, the read-the-numbers chart in the family." }, "parts": [ { "id": "list", "label": "List", "description": "The column of category rows.", "required": true }, { "id": "row", "label": "Row", "description": "A label, track, and value aligned in a three-column grid." }, { "id": "track", "label": "Track", "description": "The rail whose fill length scales to the category value." }, { "id": "value", "label": "Value", "description": "The right-aligned numeric count for the row." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Category data changes the reading without changing the row treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A column of labeled category rows with proportional bars and counts.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "track-height", "label": "Track height", "kind": "exact", "token": "--cds-size-4", "value": 4, "unit": "px", "appliesTo": [ "track" ] }, { "id": "row-gap", "label": "Row gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "list" ] }, { "id": "column-gap", "label": "Row column gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "row" ] } ], "layout": { "alignment": "Each row is a label, a stretching track, and a right-aligned value in a three-column grid.", "flow": "Rows stack top to bottom in a column.", "notes": [ "The track column stretches while the label and value columns size to content." ] }, "typographyAndColor": { "typography": [ { "label": "Row label and value", "description": "The category label and count use the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Row label and value", "description": "Label and count use primary text.", "token": "--cds-text-primary" }, { "label": "Track", "description": "The unfilled rail behind each bar.", "token": "--cds-bg-page" } ] }, "states": [ { "id": "ranked", "label": "Ranked", "description": "Rows render in order with bars scaled to the largest value." }, { "id": "default-palette", "label": "Default palette", "description": "Rows without a color cycle the built-in category palette." }, { "id": "empty", "label": "Empty", "description": "No rows renders nothing, so pair with an upstream empty state." } ], "behavior": [ { "label": "Scaled to max", "description": "Bar length scales to the largest category value in the set." }, { "label": "Palette fallback", "description": "Rows take their own color, or cycle the default category palette when none is given." }, { "label": "Readable counts", "description": "Each row shows its formatted numeric count beside the bar." } ], "accessibility": [ { "label": "Meaningful chart", "description": "Pass an accessible label so the row set is announced as a meaningful image." }, { "label": "Track is presentational", "description": "The bar track is hidden from assistive technology since the label and count carry the meaning." } ], "contentAdaptation": [ { "label": "Read the numbers", "description": "Use CategoryBars when the reader must compare category magnitudes with the actual counts visible." }, { "label": "Categories over time", "description": "Use BarChart instead when the x-axis is time rather than named categories." } ], "motionHaptics": { "motion": [ { "label": "No intrinsic motion", "description": "The rows do not animate on mount; a parent may transition the whole chart." } ], "haptics": [ { "label": "No feedback", "description": "The chart is a display and requests no haptic feedback." } ] }, "platformDifferences": [] }, "spec_source": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.spec.json", "guidance_source": { "path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './CategoryBars.stories';\nimport categoryBarsSpec from './CategoryBars.spec.json';\n\n\n\n# CategoryBars\n\nHorizontal labeled bars — a ranked breakdown of a handful of named categories with their counts\nvisible.\n\n\n\n## When to use\n\nThis is the \"read the actual numbers\" chart: reach for it when the reader must compare the\nmagnitudes of a small set of named categories and see the exact counts. Each row takes its\n`color`; omit `color` and rows cycle the default category palette.\n\nPrefer it over `ActionOrbs` (a looser proportional 2-4 category summary) and\n`BubbleMatrix`/`BurstGraph` (decorative) whenever precision matters. Use `BarChart` instead when\nthe x-axis is time rather than categories.\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 rows rendered in order.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 61 } }, { "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": 63 } }, { "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": 65 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-size-4", "light": "4px", "dark": "4px" }, { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-space-8", "light": "8px", "dark": "8px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-bg-page", "light": "#f3f1ed", "dark": "#141410" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-visualizations-categorybars--default", "name": "Default", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--default-palette", "name": "Default Palette", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "DefaultPalette", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--default-palette&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--dense", "name": "Dense", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Dense", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--dense&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--dark-theme&viewMode=story" } ], "name": "CategoryBars", "id": "categorybars", "category": "Visualizations" }, "stories": [ { "id": "cloaked-design-system-visualizations-categorybars--default", "name": "Default", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--default-palette", "name": "Default Palette", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "DefaultPalette", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--default-palette&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--empty", "name": "Empty", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Empty", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--empty&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--dense", "name": "Dense", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "Dense", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--dense&viewMode=story" }, { "id": "cloaked-design-system-visualizations-categorybars--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/CategoryBars", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "source_digest": "74e726978adc4d1adaf15b04b173837e188989eb1d6e5d771248aeb03a179227", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-categorybars--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { CategoryBars } from './CategoryBars';\n\nconst items = [\n { id: 'name', label: 'Name', value: 4, color: '#00c876' },\n { id: 'email', label: 'Email', value: 4, color: '#ffd447' },\n { id: 'phone', label: 'Phone', value: 3, color: '#e172eb' },\n { id: 'address', label: 'Address', value: 2, color: '#0067ff' },\n { id: 'family', label: 'Family', value: 1, color: '#003677' },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Visualizations/CategoryBars',\n component: CategoryBars,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Horizontal labeled bars — a ranked breakdown of a handful of named categories with ' +\n 'their counts visible. This is the \"read the actual numbers\" chart: reach for it when ' +\n 'the reader must compare category magnitudes accurately, over `ActionOrbs` (a looser ' +\n 'proportional 2–4 category summary) or `BubbleMatrix`/`BurstGraph` (decorative). Use ' +\n '`BarChart` instead when the x-axis is time rather than categories. Each row takes its ' +\n '`color`; omit `color` and rows cycle the default category palette.',\n },\n },\n },\n argTypes: {\n items: {\n ...disabledControl,\n description:\n 'Category rows rendered in order; bar length scales to `value`. 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: 'Category counts' } };\n\nexport const DefaultPalette: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Items omit `color`, so rows 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 counts with default palette',\n },\n};\n\nexport const Empty: Story = {\n parameters: {\n docs: { description: { story: 'No rows — pair with an EmptyState upstream.' } },\n },\n args: { items: [], ariaLabel: 'No category counts' },\n};\n\nexport const Dense: Story = {\n parameters: {\n docs: { description: { story: 'More rows to check spacing and label wrapping.' } },\n },\n args: {\n items: [\n ...items,\n { id: 'relatives', label: 'Relatives', value: 8, color: '#6f2cff' },\n { id: 'age', label: 'Age', value: 2, color: '#ff6b00' },\n ],\n ariaLabel: 'Dense category counts',\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: { items, ariaLabel: 'Category counts' },\n};\n" }, "links": { "human": "/component-categorybars", "json": "/data/components/categorybars.json", "markdown": "/data/components/categorybars.md", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-categorybars--default" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "CategoryBars", "public_path": "CategoryBars", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "CategoryBars", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.tsx", "line": 12 }, "props_type": "CategoryBarsProps", "props": [ { "name": "items", "type": "readonly CategoryDatum[]", "declared_type": "readonly CategoryDatum[]", "required": true, "description": "Category rows rendered in order.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 61 } }, { "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": 63 } }, { "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": 65 } } ], "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": 59, "name": "CategoryBarsProps", "code": "export interface CategoryBarsProps {\n /** Category rows rendered in order. */\n items: readonly CategoryDatum[];\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." } }