Cloaked Design SystemStatus

Spinner

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

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

7 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/status/Spinner/Spinner.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

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

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Spinner } from '@cloakedinc/design-system';

SpinnerSpinnerProps

packages/design-system/src/components/status/Spinner/Spinner.tsx:27

Prop	Type	Presence	Notes
`size`	`SpinnerSize`	Required	Named diameter: 16, 24, or 32px.
`tone`	`SpinnerTone`	Required	Color treatment; use `inverse` on dark or colored surfaces.
`ariaLabel`	`string \| undefined`	Optional	Accessible label, which also sets `role="status"`. Omit for decorative spinners.
`className`	`string \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Optional test selector.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Indeterminate loading indicator for when duration is unknown — inline in a button or centered while a screen loads. Use Progress instead whenever completion can be a 0-100 value; a spinner says "working," never "how far."

Use when

tone matches the surface the spinner sits on.

App loading states use secondary today; primary and inverse are available for their surfaces.

size is sm, md, or lg. Set ariaLabel for meaningful loads (it becomes role="status"); omit it for decorative spinners so the element is aria-hidden.

Usage by variant

Choice	Use when	Avoid when
`Tone: primary`	A prominent loading state on a light surface.
`Tone: secondary`	A lower-emphasis inline load beside secondary text — the app default in practice.
`Tone: inverse`	A dark or colored surface where primary would disappear.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: Rotating ring whose diameter and stroke follow the size, and color follows the tone.
Required: true

Allowed Design Choices

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

Label: Small
Description: 16-unit ring for inline loading.

Label: Medium
Description: 24-unit ring for standalone loading.

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
Applies To: root

Id: diameter-md
Label: Diameter (medium)
Kind: exact
Token: --cds-size-24
Value: 24
Unit: px
Applies To: root

Id: diameter-lg
Label: Diameter (large)
Kind: exact
Token: --cds-size-32
Value: 32
Unit: px
Applies To: root

Id: stroke-default
Label: Stroke width (small)
Kind: exact
Token: --cds-border-width-default
Value: 1
Unit: px
Applies To: root

Id: stroke-emphasis
Label: Stroke width (medium and large)
Kind: exact
Token: --cds-border-width-emphasis
Value: 2
Unit: px
Applies To: 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.

Typography And Color

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.

Content Adaptation

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.

Motion Haptics

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.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1