{ "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": "progress", "name": "Progress", "category": "Status", "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-status-progress--bar", "name": "Bar", "title": "Cloaked Design System/Status/Progress", "exportName": "Bar", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--bar&viewMode=story" }, { "id": "cloaked-design-system-status-progress--bar-with-label", "name": "Bar With Label", "title": "Cloaked Design System/Status/Progress", "exportName": "BarWithLabel", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--bar-with-label&viewMode=story" }, { "id": "cloaked-design-system-status-progress--bar-large", "name": "Bar Large", "title": "Cloaked Design System/Status/Progress", "exportName": "BarLarge", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--bar-large&viewMode=story" }, { "id": "cloaked-design-system-status-progress--bar-pulsing", "name": "Bar Pulsing", "title": "Cloaked Design System/Status/Progress", "exportName": "BarPulsing", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--bar-pulsing&viewMode=story" }, { "id": "cloaked-design-system-status-progress--steps", "name": "Steps", "title": "Cloaked Design System/Status/Progress", "exportName": "Steps", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--steps&viewMode=story" }, { "id": "cloaked-design-system-status-progress--steps-with-numbers", "name": "Steps With Numbers", "title": "Cloaked Design System/Status/Progress", "exportName": "StepsWithNumbers", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--steps-with-numbers&viewMode=story" }, { "id": "cloaked-design-system-status-progress--steps-with-labels", "name": "Steps With Labels", "title": "Cloaked Design System/Status/Progress", "exportName": "StepsWithLabels", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--steps-with-labels&viewMode=story" }, { "id": "cloaked-design-system-status-progress--ring", "name": "Ring", "title": "Cloaked Design System/Status/Progress", "exportName": "Ring", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--ring&viewMode=story" }, { "id": "cloaked-design-system-status-progress--ring-with-value", "name": "Ring With Value", "title": "Cloaked Design System/Status/Progress", "exportName": "RingWithValue", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--ring-with-value&viewMode=story" }, { "id": "cloaked-design-system-status-progress--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Status/Progress", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "source_digest": "78c32f89ce19b0ffb37eb334a62cd61da70bf8b9d9a65d243d4a110c9b6b68ee", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-progress--dark-theme&viewMode=story" } ], "name": "Progress", "id": "progress", "category": "Status" }, "stories_source": { "path": "packages/design-system/src/components/status/Progress/Progress.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport React from 'react';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { selectArgType } from '../../../storybook/controlOptions';\nimport { Progress } from './Progress';\nimport type { ProgressSize } from './types';\n\nconst PROGRESS_SIZES = ['sm', 'md', 'lg'] as const satisfies readonly ProgressSize[];\n\nconst sizeArgType = {\n ...selectArgType(PROGRESS_SIZES),\n description: 'Named size tier shared by all three shapes (`sm` compact · `md` · `lg`).',\n};\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Status/Progress',\n component: Progress.Bar,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Determinate progress in three shapes chosen by context. `Progress.Bar` — a value along a ' +\n 'known scale (a percentage that fills as work completes). `Progress.Steps` — a small, fixed ' +\n 'count of discrete stages (onboarding, a setup wizard). `Progress.Ring` — the same value in a ' +\n 'compact circular badge for cards and tight corners. All three take a 0–100 `value` (Steps ' +\n 'derives it from `completed`/`total`). Use `Timeline` instead when each stage carries its own ' +\n 'title, description, and timestamp — Progress.Steps only shows position, not event detail.',\n },\n },\n },\n args: {\n value: 42,\n size: 'sm',\n ariaLabel: 'Removal progress',\n },\n argTypes: {\n value: { control: { type: 'range', min: 0, max: 100 }, description: 'Progress from 0 to 100.' },\n size: sizeArgType,\n pulsing: { control: 'boolean', description: 'Pulses the fill to signal an active/indeterminate state.' },\n showValue: { control: 'boolean', description: 'Shows a rounded percentage when `valueLabel` is unset.' },\n label: { control: 'text', description: 'Optional caption shown above the bar.' },\n valueLabel: { control: false, description: 'Explicit value node shown opposite the label.' },\n ariaLabel: { control: 'text', description: 'Accessible label for meaningful progress.' },\n },\n decorators: [Story =>
{Story()}
],\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Bar: Story = {\n parameters: {\n docs: { description: { story: 'Args-driven linear bar — the default determinate treatment.' } },\n },\n args: {\n value: 42,\n ariaLabel: 'Removal progress',\n },\n};\n\nexport const BarWithLabel: Story = {\n parameters: {\n docs: { description: { story: 'Caption plus a rounded percentage via `label` + `showValue`.' } },\n },\n render: () => ,\n};\n\nexport const BarLarge: Story = {\n parameters: {\n docs: { description: { story: 'The `lg` track height for emphasis on standalone screens.' } },\n },\n render: () => ,\n};\n\nexport const BarPulsing: Story = {\n parameters: {\n docs: { description: { story: '`pulsing` fill for an active/indeterminate-feeling operation.' } },\n },\n render: () => ,\n};\n\nexport const Steps: StoryObj = {\n parameters: {\n docs: { description: { story: 'Args-driven segmented steps — pick this for a small fixed count of stages.' } },\n },\n args: {\n total: 4,\n completed: 2,\n size: 'sm',\n showActiveStep: true,\n ariaLabel: 'Setup progress',\n },\n argTypes: {\n total: { control: { type: 'number', min: 1 }, description: 'Total number of steps.' },\n completed: { control: { type: 'number', min: 0 }, description: 'Number of completed steps.' },\n size: sizeArgType,\n showActiveStep: { control: 'boolean', description: 'Marks the next incomplete step as active.' },\n showStepNumbers: { control: 'boolean', description: 'Renders the step number inside each marker.' },\n showValue: { control: 'boolean', description: 'Shows a compact completed/total value.' },\n label: { control: 'text', description: 'Optional caption shown above the steps.' },\n stepLabels: { control: false, description: 'Optional compact labels beneath each marker.' },\n ariaLabel: { control: 'text', description: 'Accessible label for meaningful progress.' },\n },\n render: args => ,\n};\n\nexport const StepsWithNumbers: StoryObj = {\n parameters: {\n docs: { description: { story: 'Numbered markers with a completed/total value at the `md` size.' } },\n },\n render: () => (\n \n ),\n};\n\nexport const StepsWithLabels: StoryObj = {\n parameters: {\n docs: { description: { story: 'Per-step captions via `stepLabels`, shown at the `lg` size.' } },\n },\n render: () => (\n \n ),\n};\n\nexport const Ring: StoryObj = {\n parameters: {\n docs: { description: { story: 'Args-driven circular badge — the compact form for cards and tight corners.' } },\n },\n args: {\n value: 68,\n size: 'sm',\n ariaLabel: 'Scan progress',\n },\n argTypes: {\n value: { control: { type: 'range', min: 0, max: 100 }, description: 'Progress from 0 to 100.' },\n size: sizeArgType,\n showValue: { control: 'boolean', description: 'Shows a rounded percentage inside the ring.' },\n label: { control: 'text', description: 'Optional caption shown beneath the ring.' },\n valueLabel: { control: false, description: 'Explicit value node shown inside the ring.' },\n ariaLabel: { control: 'text', description: 'Accessible label for meaningful progress.' },\n },\n render: args => ,\n};\n\nexport const RingWithValue: StoryObj = {\n parameters: {\n docs: { description: { story: 'The `lg` ring with an inline percentage and caption.' } },\n },\n render: () => (\n \n \n \n ),\n};\n\nexport const DarkTheme: StoryObj = {\n parameters: {\n docs: { description: { story: 'Ring rendered against the dark theme surface.' } },\n },\n render: () => ,\n globals: { theme: 'dark' },\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Progress", "status": "preview", "version": "1.0.0", "summary": "A determinate progress family in three shapes: a linear Bar, a segmented Steps counter, and a circular Ring." }, "parts": [ { "id": "bar", "label": "Progress.Bar", "description": "Linear track that fills from 0 to 100.", "required": true }, { "id": "steps", "label": "Progress.Steps", "description": "Segmented markers for a small fixed count of stages." }, { "id": "ring", "label": "Progress.Ring", "description": "Circular badge form for cards and tight corners." } ], "allowedDesignChoices": { "variants": { "bar": { "label": "Bar", "description": "Linear determinate track." }, "steps": { "label": "Steps", "description": "Discrete stage markers." }, "ring": { "label": "Ring", "description": "Compact circular badge." } }, "sizes": { "sm": { "label": "Small", "description": "Compact default track, marker, and ring." }, "md": { "label": "Medium", "description": "Mid-scale track, marker, and ring." }, "lg": { "label": "Large", "description": "Emphasis track, marker, and ring." } } }, "variants": [ { "id": "bar", "label": "Bar", "description": "Linear determinate progress.", "platforms": [ "ios", "android", "web" ] }, { "id": "steps", "label": "Steps", "description": "Segmented stage progress.", "platforms": [ "ios", "android", "web" ] }, { "id": "ring", "label": "Ring", "description": "Circular determinate progress.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "sm", "label": "Small", "description": "The compact existing treatment." }, { "id": "md", "label": "Medium", "description": "A mid-scale treatment." }, { "id": "lg", "label": "Large", "description": "An emphasis treatment for standalone screens." } ], "measurements": [ { "id": "bar-track-height-sm", "label": "Bar track height (small)", "kind": "exact", "token": "--cds-size-4", "value": 4, "unit": "px", "appliesTo": [ "bar" ] }, { "id": "bar-track-height-md", "label": "Bar track height (medium)", "kind": "exact", "token": "--cds-size-8", "value": 8, "unit": "px", "appliesTo": [ "bar" ] }, { "id": "bar-track-height-lg", "label": "Bar track height (large)", "kind": "exact", "token": "--cds-size-12", "value": 12, "unit": "px", "appliesTo": [ "bar" ] }, { "id": "ring-diameter-sm", "label": "Ring diameter (small)", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "ring" ] }, { "id": "ring-diameter-md", "label": "Ring diameter (medium)", "kind": "exact", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "ring" ] }, { "id": "ring-diameter-lg", "label": "Ring diameter (large)", "kind": "exact", "token": "--cds-size-64", "value": 64, "unit": "px", "appliesTo": [ "ring" ] }, { "id": "group-gap", "label": "Label and track gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "bar", "steps", "ring" ] }, { "id": "step-dot-size-sm", "label": "Step dot size (small)", "kind": "exact", "token": "--cds-size-8", "value": 8, "unit": "px", "appliesTo": [ "steps" ] }, { "id": "step-dot-size-md", "label": "Step dot size (medium)", "kind": "exact", "token": "--cds-size-12", "value": 12, "unit": "px", "appliesTo": [ "steps" ] }, { "id": "step-dot-size-lg", "label": "Step dot size (large)", "kind": "exact", "token": "--cds-size-16", "value": 16, "unit": "px", "appliesTo": [ "steps" ] } ], "layout": { "alignment": "An optional label and value sit above the bar/steps; the ring centers its value.", "flow": "Each shape is self-contained; Bar and Steps fill their container width while Ring is inline.", "notes": [ "Use Timeline when each stage carries its own title, description, and timestamp." ] }, "typographyAndColor": { "typography": [ { "label": "Caption and value", "description": "Labels and values use the body-small ramp.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Fill", "description": "Completed progress uses the brand accent.", "token": "--cds-brand" }, { "label": "Track", "description": "The unfilled track uses the graph background.", "token": "--cds-graph-bg" } ] }, "states": [ { "id": "determinate", "label": "Determinate", "description": "Fill reflects the current 0 to 100 value." }, { "id": "pulsing", "label": "Pulsing", "description": "The bar fill pulses to signal an active or indeterminate operation." }, { "id": "complete", "label": "Complete", "description": "All steps or full value are filled with the brand accent." } ], "behavior": [ { "label": "Shape choice", "description": "Pick Bar for a scale, Steps for a small fixed count of stages, and Ring for a compact badge." }, { "label": "Value clamping", "description": "Values are clamped to the 0 to 100 range before rendering." } ], "accessibility": [ { "label": "Meaningful progress", "description": "Set ariaLabel to expose role=progressbar with min, max, and current value." }, { "label": "Decorative progress", "description": "Omit ariaLabel to hide purely decorative progress from assistive tech." } ], "contentAdaptation": [ { "label": "Optional value", "description": "showValue renders a rounded percentage or completed/total count opposite the label." }, { "label": "Step labels", "description": "Steps can render numbers inside markers and captions beneath them." } ], "motionHaptics": { "motion": [ { "label": "Fill transition", "description": "The bar fill eases to its new width; the pulsing fill animates until it settles." } ], "haptics": [ { "label": "No feedback", "description": "Progress is non-interactive and requests no haptics." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/status/Progress/Progress.spec.json", "guidance": { "summary": "A determinate progress family in three shapes: a linear Bar, a segmented Steps counter, and a circular Ring.", "guidance": [ { "heading": "Overview", "body": "Determinate progress in three shapes chosen by context. All three take a 0-100\n`value` (`Progress.Steps` derives it from `completed` / `total`)." }, { "heading": "Use when", "body": "Pick the shape by how the progress reads in place, not by preference.\n\n`Progress.Bar` and `Progress.Ring` are both in use today; `Progress.Steps` is\navailable but currently unused in the app." }, { "heading": "Steps", "body": "`Progress.Steps` marks completed, active, and upcoming stages. Add `showStepNumbers`\nfor numbered markers and `stepLabels` for per-step captions." }, { "heading": "Size and pulsing", "body": "`size` is `sm` (default, compact), `md`, or `lg` and is shared by all three shapes;\nreach for `lg` to emphasize progress on a standalone screen. `pulsing` (Bar) animates\nthe fill to signal an active operation." }, { "heading": "Props", "body": "Controls below are for `Progress.Bar`; `Progress.Steps` and `Progress.Ring` expose\ntheir own args in the Steps and Ring stories above." } ], "usage": [ { "variant": "Progress.Bar", "use": "A value along a known scale that fills as work completes — a percentage on a screen or row.", "axis": "Shape" }, { "variant": "Progress.Steps", "use": "A small, fixed count of discrete stages — a setup wizard or onboarding flow.", "avoid": "Stages that each carry a title, description, or timestamp — use Timeline, which shows event detail.", "axis": "Shape" }, { "variant": "Progress.Ring", "use": "The same 0-100 value in a compact circular badge for cards and tight corners.", "axis": "Shape" } ], "examples": [], "source": "packages/design-system/src/components/status/Progress/Progress.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-progress", "json": "/data/visual/components/progress.json", "storybook": "/storybook/?path=/story/cloaked-design-system-status-progress--bar" } }