# Spinner

An indeterminate circular loading indicator for states where duration is unknown, sized and toned for inline or centered use.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/status/Spinner/Spinner.tsx

## 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."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "size",
      "type": "SpinnerSize",
      "declared_type": "SpinnerSize",
      "required": true,
      "description": "Named diameter: 16, 24, or 32px.",
      "source": {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 13
      },
      "values": [
        "lg",
        "md",
        "sm"
      ],
      "values_complete": true
    },
    {
      "name": "tone",
      "type": "SpinnerTone",
      "declared_type": "SpinnerTone",
      "required": true,
      "description": "Color treatment; use `inverse` on dark or colored surfaces.",
      "source": {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 15
      },
      "values": [
        "inverse",
        "primary",
        "secondary"
      ],
      "values_complete": true
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible label, which also sets `role=\"status\"`. Omit for decorative spinners.",
      "source": {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 17
      }
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 18
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector.",
      "source": {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 20
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Spinner",
    "public_path": "Spinner",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Spinner",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
          "line": 27
        },
        "props_type": "SpinnerProps",
        "props": [
          {
            "name": "size",
            "type": "SpinnerSize",
            "declared_type": "SpinnerSize",
            "required": true,
            "description": "Named diameter: 16, 24, or 32px.",
            "source": {
              "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
              "line": 13
            },
            "values": [
              "lg",
              "md",
              "sm"
            ],
            "values_complete": true
          },
          {
            "name": "tone",
            "type": "SpinnerTone",
            "declared_type": "SpinnerTone",
            "required": true,
            "description": "Color treatment; use `inverse` on dark or colored surfaces.",
            "source": {
              "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
              "line": 15
            },
            "values": [
              "inverse",
              "primary",
              "secondary"
            ],
            "values_complete": true
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible label, which also sets `role=\"status\"`. Omit for decorative spinners.",
            "source": {
              "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
              "line": 17
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
              "line": 18
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector.",
            "source": {
              "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
              "line": 20
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 5,
        "name": "SpinnerSize",
        "code": "export type SpinnerSize = 'sm' | 'md' | 'lg';"
      },
      {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 6,
        "name": "SpinnerTone",
        "code": "export type SpinnerTone = 'primary' | 'secondary' | 'inverse';"
      },
      {
        "path": "packages/design-system/src/components/status/Spinner/Spinner.tsx",
        "line": 11,
        "name": "SpinnerProps",
        "code": "export interface SpinnerProps {\n    /** Named diameter: 16, 24, or 32px. */\n    size: SpinnerSize;\n    /** Color treatment; use `inverse` on dark or colored surfaces. */\n    tone: SpinnerTone;\n    /** Accessible label, which also sets `role=\"status\"`. Omit for decorative spinners. */\n    ariaLabel?: string;\n    className?: 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."
  },
  "spec": {
    "$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": []
  },
  "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"
    }
  },
  "tokens": [
    {
      "name": "--cds-size-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-size-24",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-size-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-border-width-default",
      "light": "1px",
      "dark": "1px"
    },
    {
      "name": "--cds-border-width-emphasis",
      "light": "2px",
      "dark": "2px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    },
    {
      "name": "--cds-text-on-bold",
      "light": "#ffffff",
      "dark": "#141410"
    }
  ],
  "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."
  },
  "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."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-status-spinner--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [Small](/storybook/iframe.html?id=cloaked-design-system-status-spinner--small&viewMode=story) | export: Small | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [Medium](/storybook/iframe.html?id=cloaked-design-system-status-spinner--medium&viewMode=story) | export: Medium | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [Large](/storybook/iframe.html?id=cloaked-design-system-status-spinner--large&viewMode=story) | export: Large | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [Secondary](/storybook/iframe.html?id=cloaked-design-system-status-spinner--secondary&viewMode=story) | export: Secondary | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [Inverse](/storybook/iframe.html?id=cloaked-design-system-status-spinner--inverse&viewMode=story) | export: Inverse | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

- [State Matrix](/storybook/iframe.html?id=cloaked-design-system-status-spinner--state-matrix&viewMode=story) | export: StateMatrix | source: packages/design-system/src/components/status/Spinner/Spinner.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.