{
  "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": "spinner",
  "name": "Spinner",
  "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-spinner--playground",
        "name": "Playground",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Playground",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--playground&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--small",
        "name": "Small",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Small",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--small&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--medium",
        "name": "Medium",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Medium",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--medium&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--large",
        "name": "Large",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Large",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--large&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--secondary",
        "name": "Secondary",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Secondary",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--secondary&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--inverse",
        "name": "Inverse",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "Inverse",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--inverse&viewMode=story"
      },
      {
        "id": "cloaked-design-system-status-spinner--state-matrix",
        "name": "State Matrix",
        "title": "Cloaked Design System/Status/Spinner",
        "exportName": "StateMatrix",
        "source_path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
        "source_digest": "ec970e4e81a2d63a935646b8b05bf6f9c64d7e3b5abaaecccd1fd49bb550102f",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-status-spinner--state-matrix&viewMode=story"
      }
    ],
    "name": "Spinner",
    "id": "spinner",
    "category": "Status"
  },
  "stories_source": {
    "path": "packages/design-system/src/components/status/Spinner/Spinner.stories.tsx",
    "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Text } from '../../primitives/Text/Text';\nimport { selectArgType } from '../../../storybook/controlOptions';\nimport { Spinner } from './Spinner';\nimport styles from './Spinner.stories.module.scss';\n\nconst SPINNER_SIZE_OPTIONS = ['sm', 'md', 'lg'] as const;\nconst SPINNER_TONE_OPTIONS = ['primary', 'secondary', 'inverse'] as const;\n\nconst meta: Meta<typeof Spinner> = {\n    title: 'Cloaked Design System/Status/Spinner',\n    component: Spinner,\n    parameters: {\n        a11y: { test: 'error' },\n        docs: {\n            description: {\n                component:\n                    'Indeterminate loading indicator for when duration is unknown — inline in a button, or centered ' +\n                    'while a screen loads. Use `Progress` instead whenever you can express completion as a 0–100 ' +\n                    'value; a spinner communicates \"working\" but never \"how far.\" Set `ariaLabel` for meaningful ' +\n                    'loads (it becomes `role=\"status\"`); leave it off for purely decorative spinners so the element ' +\n                    'is `aria-hidden`. Use `tone=\"inverse\"` on dark or colored surfaces.',\n            },\n        },\n    },\n    args: {\n        size: 'md',\n        tone: 'primary',\n        ariaLabel: 'Loading',\n    },\n    argTypes: {\n        size: { ...selectArgType(SPINNER_SIZE_OPTIONS), description: 'Named spinner diameter.' },\n        tone: {\n            ...selectArgType(SPINNER_TONE_OPTIONS),\n            description: 'Color treatment; use `inverse` on dark/colored backgrounds.',\n        },\n        ariaLabel: { control: 'text', description: 'Accessible label; omit for decorative spinners.' },\n    },\n};\nexport default meta;\ntype Story = StoryObj<typeof Spinner>;\n\nexport const Playground: Story = {};\nexport const Small: Story = { args: { size: 'sm' } };\nexport const Medium: Story = { args: { size: 'md' } };\nexport const Large: Story = { args: { size: 'lg' } };\nexport const Secondary: Story = { args: { tone: 'secondary' } };\nexport const Inverse: Story = {\n    parameters: {\n        docs: { description: { story: '`tone=\"inverse\"` on a dark surface, where `primary` would disappear.' } },\n    },\n    args: { tone: 'inverse' },\n    render: args => (\n        <div className={styles.inversePreview}>\n            <Spinner {...args} />\n        </div>\n    ),\n};\n\nexport const StateMatrix: Story = {\n    parameters: {\n        docs: { description: { story: 'Every `tone` across every `size`.' } },\n    },\n    render: () => (\n        <VStack gap={16}>\n            {SPINNER_TONE_OPTIONS.map(tone => (\n                <HStack key={tone} gap={16} align='center'>\n                    <Text variant='body-small' color='secondary'>\n                        {tone}\n                    </Text>\n                    {SPINNER_SIZE_OPTIONS.map(size => (\n                        <Spinner\n                            key={`${tone}-${size}`}\n                            size={size}\n                            tone={tone}\n                            ariaLabel={`${tone} ${size} loading`}\n                        />\n                    ))}\n                </HStack>\n            ))}\n        </VStack>\n    ),\n};\n"
  },
  "specification": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Spinner",
      "status": "preview",
      "version": "1.0.0",
      "summary": "An indeterminate circular loading indicator for states where duration is unknown, sized and toned for inline or centered use."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Rotating ring whose diameter and stroke follow the size, and color follows the tone.",
        "required": true
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "primary": {
          "label": "Primary",
          "description": "Primary text color for light surfaces."
        },
        "secondary": {
          "label": "Secondary",
          "description": "Muted color for quieter loading."
        },
        "inverse": {
          "label": "Inverse",
          "description": "On-bold color for dark or colored surfaces."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small",
          "description": "16-unit ring for inline loading."
        },
        "md": {
          "label": "Medium",
          "description": "24-unit ring for standalone loading."
        },
        "lg": {
          "label": "Large",
          "description": "32-unit ring for centered screen loading."
        }
      }
    },
    "variants": [
      {
        "id": "primary",
        "label": "Primary",
        "description": "Primary text tone.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "secondary",
        "label": "Secondary",
        "description": "Secondary text tone.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "inverse",
        "label": "Inverse",
        "description": "On-bold tone for dark surfaces.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "16-unit diameter with a default-width stroke."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "24-unit diameter with an emphasis stroke."
      },
      {
        "id": "lg",
        "label": "Large",
        "description": "32-unit diameter with an emphasis stroke."
      }
    ],
    "measurements": [
      {
        "id": "diameter-sm",
        "label": "Diameter (small)",
        "kind": "exact",
        "token": "--cds-size-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "diameter-md",
        "label": "Diameter (medium)",
        "kind": "exact",
        "token": "--cds-size-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "diameter-lg",
        "label": "Diameter (large)",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "stroke-default",
        "label": "Stroke width (small)",
        "kind": "exact",
        "token": "--cds-border-width-default",
        "value": 1,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "stroke-emphasis",
        "label": "Stroke width (medium and large)",
        "kind": "exact",
        "token": "--cds-border-width-emphasis",
        "value": 2,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      }
    ],
    "layout": {
      "alignment": "The ring is a self-contained inline-block with no internal layout.",
      "flow": "A single rotating circle with one transparent segment.",
      "notes": [
        "Use Progress whenever completion can be expressed as a 0 to 100 value."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "None",
          "description": "Spinner has no text; type is not applicable but the ramp is noted for parity.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Primary tone",
          "description": "Uses primary text color.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Secondary tone",
          "description": "Uses secondary text color.",
          "token": "--cds-text-secondary"
        },
        {
          "label": "Inverse tone",
          "description": "Uses on-bold color for dark surfaces.",
          "token": "--cds-text-on-bold"
        }
      ]
    },
    "states": [
      {
        "id": "spinning",
        "label": "Spinning",
        "description": "Continuously rotates while mounted."
      },
      {
        "id": "reduced-motion",
        "label": "Reduced motion",
        "description": "Slows the rotation under prefers-reduced-motion."
      }
    ],
    "behavior": [
      {
        "label": "Indeterminate only",
        "description": "Spinner shows working but never how far; it has no value."
      },
      {
        "label": "Meaningful vs decorative",
        "description": "Set ariaLabel for meaningful loads; omit it for decorative spinners."
      }
    ],
    "accessibility": [
      {
        "label": "Status role",
        "description": "With ariaLabel the spinner exposes role=status; without it, it is aria-hidden."
      },
      {
        "label": "Contrast",
        "description": "Use the inverse tone on dark or colored surfaces so the ring stays visible."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Inline vs centered",
        "description": "Small suits inline button loading; large suits centered screen loading."
      },
      {
        "label": "Surface tone",
        "description": "Match the tone to the surface it sits on."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Rotation",
          "description": "The ring spins at a steady rate, slowed under reduced-motion."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "Spinner is non-interactive and requests no haptics."
        }
      ]
    },
    "platformDifferences": []
  },
  "specification_source": "packages/design-system/src/components/status/Spinner/Spinner.spec.json",
  "guidance": {
    "summary": "An indeterminate circular loading indicator for states where duration is unknown, sized and toned for inline or centered use.",
    "guidance": [
      {
        "heading": "Overview",
        "body": "Indeterminate loading indicator for when duration is unknown — inline in a button or\ncentered while a screen loads. Use `Progress` instead whenever completion can be a\n0-100 value; a spinner says \"working,\" never \"how far.\""
      },
      {
        "heading": "Use when",
        "body": "`tone` matches the surface the spinner sits on.\n\nApp loading states use `secondary` today; `primary` and `inverse` are available for\ntheir surfaces.\n\n`size` is `sm`, `md`, or `lg`. Set `ariaLabel` for meaningful loads (it becomes\n`role=\"status\"`); omit it for decorative spinners so the element is `aria-hidden`."
      }
    ],
    "usage": [
      {
        "variant": "primary",
        "use": "A prominent loading state on a light surface.",
        "axis": "Tone"
      },
      {
        "variant": "secondary",
        "use": "A lower-emphasis inline load beside secondary text — the app default in practice.",
        "axis": "Tone"
      },
      {
        "variant": "inverse",
        "use": "A dark or colored surface where primary would disappear.",
        "axis": "Tone"
      }
    ],
    "examples": [],
    "source": "packages/design-system/src/components/status/Spinner/Spinner.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-spinner",
    "json": "/data/visual/components/spinner.json",
    "storybook": "/storybook/?path=/story/cloaked-design-system-status-spinner--playground"
  }
}