{
"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",
"summary": "A determinate progress family in three shapes: a linear Bar, a segmented Steps counter, and a circular Ring.",
"documentation": {
"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."
},
"source": {
"path": "packages/design-system/src/components/status/Progress/Progress.tsx",
"code": "import { Bar } from './ProgressBar/ProgressBar';\nimport { Ring } from './ProgressRing/ProgressRing';\nimport { Steps } from './ProgressSteps/ProgressSteps';\n\nexport type { ProgressBarProps, ProgressRingProps, ProgressStepsProps, ProgressStepState, ProgressSize } from './types';\n\n/**\n * Determinate progress in three shapes: `Bar` for a value on a known scale, `Steps` for a small\n * fixed count of stages, `Ring` for a compact badge. Use `Timeline` when each stage carries its\n * own title, description, or timestamp.\n */\nexport const Progress = {\n Bar,\n Steps,\n Ring,\n};\n"
},
"spec": {
"$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": []
},
"spec_source": "packages/design-system/src/components/status/Progress/Progress.spec.json",
"guidance_source": {
"path": "packages/design-system/src/components/status/Progress/Progress.mdx",
"code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec, UsageTable, Do, Dont, Compare } from '../../../../.storybook/blocks';\nimport * as Stories from './Progress.stories';\nimport progressSpec from './Progress.spec.json';\n\n\n\n# Progress\n\nDeterminate progress in three shapes chosen by context. All three take a 0-100\n`value` (`Progress.Steps` derives it from `completed` / `total`).\n\n\n\n## Use when\n\nPick the shape by how the progress reads in place, not by preference.\n\n\n\n`Progress.Bar` and `Progress.Ring` are both in use today; `Progress.Steps` is\navailable but currently unused in the app.\n\n## Steps\n\n`Progress.Steps` marks completed, active, and upcoming stages. Add `showStepNumbers`\nfor numbered markers and `stepLabels` for per-step captions.\n\n\n\n## Ring\n\n\n\n## Size and pulsing\n\n`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.\n\n\n\n## Dark theme\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\nControls below are for `Progress.Bar`; `Progress.Steps` and `Progress.Ring` expose\ntheir own args in the Steps and Ring stories above.\n\n\n"
},
"props": [],
"prop_shapes": {},
"examples": [],
"tokens": [
{
"name": "--cds-size-4",
"light": "4px",
"dark": "4px"
},
{
"name": "--cds-size-8",
"light": "8px",
"dark": "8px"
},
{
"name": "--cds-size-12",
"light": "12px",
"dark": "12px"
},
{
"name": "--cds-size-32",
"light": "32px",
"dark": "32px"
},
{
"name": "--cds-size-48",
"light": "48px",
"dark": "48px"
},
{
"name": "--cds-size-64",
"light": "64px",
"dark": "64px"
},
{
"name": "--cds-space-8",
"light": "8px",
"dark": "8px"
},
{
"name": "--cds-size-16",
"light": "16px",
"dark": "16px"
},
{
"name": "--cds-type-body-small-size",
"light": "0.875rem",
"dark": "0.875rem"
},
{
"name": "--cds-brand",
"light": "#ff550c",
"dark": "#ff550c"
},
{
"name": "--cds-graph-bg",
"light": "#0b0b0a0d",
"dark": "#ffffff0d"
}
],
"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": [
{
"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"
}
],
"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"
},
"links": {
"human": "/component-progress",
"json": "/data/components/progress.json",
"markdown": "/data/components/progress.md",
"storybook": "/storybook/?path=/story/cloaked-design-system-status-progress--bar"
},
"contract_status": "preview",
"contract_kind": "source-derived",
"approval": "required",
"api": {
"method": "typescript-type-checker",
"typescript_version": "5.9.3",
"public_export": "Progress",
"public_path": "Progress",
"import_path": "@cloakedinc/design-system",
"root_kind": "namespace",
"entrypoints": [
{
"name": "Progress.Bar",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/status/Progress/ProgressBar/ProgressBar.tsx",
"line": 13
},
"props_type": "ProgressBarProps",
"props": [
{
"name": "value",
"type": "number",
"declared_type": "number",
"required": true,
"description": "Progress value from 0 to 100.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 10
}
},
{
"name": "size",
"type": "ProgressSize | undefined",
"declared_type": "ProgressSize",
"required": false,
"description": "Named size for the track height. Defaults to `sm` for the compact existing treatment.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 12
},
"values": [
"lg",
"md",
"sm"
],
"values_complete": true,
"default": "'sm'",
"default_kind": "source-expression"
},
{
"name": "pulsing",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Pulses the fill to signal an active/indeterminate state.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 14
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "label",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Optional caption shown above the bar.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 16
}
},
{
"name": "valueLabel",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Explicit visible value shown opposite the label.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 18
}
},
{
"name": "showValue",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Shows a rounded percentage value when `valueLabel` is not provided.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 20
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "ariaLabel",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Accessible name for the value; omit when the bar is purely decorative.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 22
}
},
{
"name": "testId",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Optional test selector. Lands on the track itself, not the label group.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 24
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
},
{
"name": "Progress.Steps",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/status/Progress/ProgressSteps/ProgressSteps.tsx",
"line": 14
},
"props_type": "ProgressStepsProps",
"props": [
{
"name": "total",
"type": "number",
"declared_type": "number",
"required": true,
"description": "Step count; truncated to a whole number and clamped to 1-12.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 32
}
},
{
"name": "completed",
"type": "number",
"declared_type": "number",
"required": true,
"description": "Steps finished so far; clamped to `0..total`.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 34
}
},
{
"name": "size",
"type": "ProgressSize | undefined",
"declared_type": "ProgressSize",
"required": false,
"description": "Named marker size. Defaults to `sm` for the compact existing treatment.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 36
},
"values": [
"lg",
"md",
"sm"
],
"values_complete": true,
"default": "'sm'",
"default_kind": "source-expression"
},
{
"name": "showActiveStep",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Marks the next incomplete step as active.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 38
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "label",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Optional caption shown above the steps.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 40
}
},
{
"name": "valueLabel",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Explicit visible value shown opposite the label.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 42
}
},
{
"name": "showValue",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Shows a compact completed/total value when `valueLabel` is not provided.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 44
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "showStepNumbers",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Renders step numbers inside each marker.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 46
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "stepLabels",
"type": "readonly ReactNode[] | undefined",
"declared_type": "readonly ReactNode[]",
"required": false,
"description": "Optional compact labels shown beneath each step marker.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 48
}
},
{
"name": "ariaLabel",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Accessible name for the value; omit when the markers are purely decorative.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 50
}
},
{
"name": "testId",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Optional test selector. Lands on the step row itself, not the label group.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 52
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
},
{
"name": "Progress.Ring",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/status/Progress/ProgressRing/ProgressRing.tsx",
"line": 13
},
"props_type": "ProgressRingProps",
"props": [
{
"name": "value",
"type": "number | undefined",
"declared_type": "number",
"required": false,
"description": "Progress value from 0 to 100.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 60
},
"default": "0",
"default_kind": "source-expression"
},
{
"name": "size",
"type": "ProgressSize | undefined",
"declared_type": "ProgressSize",
"required": false,
"description": "Named ring size. Defaults to `sm` for the compact existing treatment.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 62
},
"values": [
"lg",
"md",
"sm"
],
"values_complete": true,
"default": "'sm'",
"default_kind": "source-expression"
},
{
"name": "label",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Optional caption shown beneath the ring.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 64
}
},
{
"name": "valueLabel",
"type": "ReactNode",
"declared_type": "ReactNode",
"required": false,
"description": "Explicit visible value shown inside the ring.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 66
}
},
{
"name": "showValue",
"type": "boolean | undefined",
"declared_type": "boolean",
"required": false,
"description": "Shows a rounded percentage value inside the ring when `valueLabel` is not provided.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 68
},
"values": [
false,
true
],
"values_complete": true,
"default": "false",
"default_kind": "source-expression"
},
{
"name": "ariaLabel",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Accessible name for the value; omit when the ring is purely decorative.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 70
}
},
{
"name": "testId",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Optional test selector. Lands on the ring itself, not the label group.",
"source": {
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 72
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
}
],
"type_sources": [
{
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 3,
"name": "ProgressSize",
"code": "export type ProgressSize = 'sm' | 'md' | 'lg';"
},
{
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 8,
"name": "ProgressBarProps",
"code": "export interface ProgressBarProps {\n /** Progress value from 0 to 100. */\n value: number;\n /** Named size for the track height. Defaults to `sm` for the compact existing treatment. */\n size?: ProgressSize;\n /** Pulses the fill to signal an active/indeterminate state. */\n pulsing?: boolean;\n /** Optional caption shown above the bar. */\n label?: ReactNode;\n /** Explicit visible value shown opposite the label. */\n valueLabel?: ReactNode;\n /** Shows a rounded percentage value when `valueLabel` is not provided. */\n showValue?: boolean;\n /** Accessible name for the value; omit when the bar is purely decorative. */\n ariaLabel?: string;\n /** Optional test selector. Lands on the track itself, not the label group. */\n testId?: string;\n}"
},
{
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 30,
"name": "ProgressStepsProps",
"code": "export interface ProgressStepsProps {\n /** Step count; truncated to a whole number and clamped to 1-12. */\n total: number;\n /** Steps finished so far; clamped to `0..total`. */\n completed: number;\n /** Named marker size. Defaults to `sm` for the compact existing treatment. */\n size?: ProgressSize;\n /** Marks the next incomplete step as active. */\n showActiveStep?: boolean;\n /** Optional caption shown above the steps. */\n label?: ReactNode;\n /** Explicit visible value shown opposite the label. */\n valueLabel?: ReactNode;\n /** Shows a compact completed/total value when `valueLabel` is not provided. */\n showValue?: boolean;\n /** Renders step numbers inside each marker. */\n showStepNumbers?: boolean;\n /** Optional compact labels shown beneath each step marker. */\n stepLabels?: readonly ReactNode[];\n /** Accessible name for the value; omit when the markers are purely decorative. */\n ariaLabel?: string;\n /** Optional test selector. Lands on the step row itself, not the label group. */\n testId?: string;\n}"
},
{
"path": "packages/design-system/src/components/status/Progress/types.ts",
"line": 58,
"name": "ProgressRingProps",
"code": "export interface ProgressRingProps {\n /** Progress value from 0 to 100. */\n value?: number;\n /** Named ring size. Defaults to `sm` for the compact existing treatment. */\n size?: ProgressSize;\n /** Optional caption shown beneath the ring. */\n label?: ReactNode;\n /** Explicit visible value shown inside the ring. */\n valueLabel?: ReactNode;\n /** Shows a rounded percentage value inside the ring when `valueLabel` is not provided. */\n showValue?: boolean;\n /** Accessible name for the value; omit when the ring is purely decorative. */\n ariaLabel?: string;\n /** Optional test selector. Lands on the ring itself, not the label group. */\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."
}
}