# StatusIndicator

A quiet inline status: a tone-colored dot beside neutral label text, shared across card and list surfaces.

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

## Guidance

{
  "summary": "A quiet inline status: a tone-colored dot beside neutral label text, shared across card and list surfaces.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A tone-colored dot beside plain label text — the quietest, in-context way to show a\nstatus inside a card or list row. `tone` sets the dot color. Reach for `Tag` when you\nwant a filled standalone pill (emphasis, a count) or the Figma active/inactive\ntreatment."
    },
    {
      "heading": "Use when",
      "body": "`tone` maps to the `--pui-status-*` vocabulary. StatusIndicator has no current\nconsumers in the app — it is the shared primitive that card and list-row statuses are\nmeant to compose, so a status reads identically everywhere."
    }
  ],
  "usage": [
    {
      "variant": "neutral",
      "use": "The default — a quiet, uncolored dot for an inactive or unremarkable state (queued, idle).",
      "axis": "Tone"
    },
    {
      "variant": "info",
      "use": "An in-progress or informational state.",
      "axis": "Tone"
    },
    {
      "variant": "success",
      "use": "A good or complete state — protected, done.",
      "axis": "Tone"
    },
    {
      "variant": "warning",
      "use": "A state that needs attention but is not a failure.",
      "axis": "Tone"
    },
    {
      "variant": "danger",
      "use": "A failed or at-risk state.",
      "axis": "Tone"
    }
  ],
  "examples": [],
  "source": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.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": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
        "line": 13
      }
    },
    {
      "name": "tone",
      "type": "\"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\" | undefined",
      "declared_type": "StatusTone",
      "required": false,
      "description": "Semantic status color for the dot; maps to the `--cds-status-*` tokens. Defaults to `neutral`.",
      "source": {
        "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
        "line": 15
      },
      "values": [
        "danger",
        "info",
        "neutral",
        "success",
        "warning"
      ],
      "values_complete": true,
      "default": "'neutral'",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
        "line": 16
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector.",
      "source": {
        "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
        "line": 18
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "StatusIndicator",
    "public_path": "StatusIndicator",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "StatusIndicator",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
          "line": 25
        },
        "props_type": "StatusIndicatorProps",
        "props": [
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
              "line": 13
            }
          },
          {
            "name": "tone",
            "type": "\"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\" | undefined",
            "declared_type": "StatusTone",
            "required": false,
            "description": "Semantic status color for the dot; maps to the `--cds-status-*` tokens. Defaults to `neutral`.",
            "source": {
              "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
              "line": 15
            },
            "values": [
              "danger",
              "info",
              "neutral",
              "success",
              "warning"
            ],
            "values_complete": true,
            "default": "'neutral'",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
              "line": 16
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector.",
            "source": {
              "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
              "line": 18
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx",
        "line": 12,
        "name": "StatusIndicatorProps",
        "code": "export interface StatusIndicatorProps {\n    children: React.ReactNode;\n    /** Semantic status color for the dot; maps to the `--cds-status-*` tokens. Defaults to `neutral`. */\n    tone?: StatusTone;\n    className?: string;\n    /** Optional test selector. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/styles/statusTone.ts",
        "line": 7,
        "name": "STATUS_TONES",
        "code": "STATUS_TONES = ['neutral', 'info', 'success', 'warning', 'danger'] as const"
      },
      {
        "path": "packages/design-system/src/styles/statusTone.ts",
        "line": 9,
        "name": "StatusTone",
        "code": "export type StatusTone = (typeof STATUS_TONES)[number];"
      }
    ],
    "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": "StatusIndicator",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A quiet inline status: a tone-colored dot beside neutral label text, shared across card and list surfaces."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Pill that seats the dot and label with a rounded surface.",
        "required": true
      },
      {
        "id": "dot",
        "label": "Dot",
        "description": "Tone-colored status dot."
      },
      {
        "id": "label",
        "label": "Label",
        "description": "Neutral status text."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "indicator": {
          "label": "Indicator",
          "description": "The single dot-plus-label treatment."
        }
      },
      "sizes": {},
      "tones": {
        "neutral": {
          "label": "Neutral"
        },
        "info": {
          "label": "Info"
        },
        "success": {
          "label": "Success"
        },
        "warning": {
          "label": "Warning"
        },
        "danger": {
          "label": "Danger"
        }
      }
    },
    "variants": [
      {
        "id": "indicator",
        "label": "Indicator",
        "description": "Dot beside a neutral label.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "min-height",
        "label": "Minimum height",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "content-gap",
        "label": "Dot and label gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "root",
          "dot",
          "label"
        ]
      },
      {
        "id": "corner-radius",
        "label": "Corner radius",
        "kind": "exact",
        "token": "--cds-radius-xl",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      }
    ],
    "layout": {
      "alignment": "Dot and label center vertically inside the pill.",
      "flow": "A single inline pill with a leading dot and trailing label.",
      "notes": [
        "Use Tag when you need a filled pill that stands on its own with a count or emphasis."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Label",
          "description": "Uses the link ramp for compact status text.",
          "token": "--cds-type-link-size"
        }
      ],
      "colors": [
        {
          "label": "Surface",
          "description": "The pill sits on the page background.",
          "token": "--cds-bg-page"
        },
        {
          "label": "Label",
          "description": "Neutral primary text for the label.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Dot",
          "description": "The dot uses the tone solid color.",
          "token": "--cds-status-success-solid"
        }
      ]
    },
    "states": [
      {
        "id": "neutral",
        "label": "Neutral",
        "description": "Neutral tone dot."
      },
      {
        "id": "info",
        "label": "Info",
        "description": "Info tone dot."
      },
      {
        "id": "success",
        "label": "Success",
        "description": "Success tone dot."
      },
      {
        "id": "warning",
        "label": "Warning",
        "description": "Warning tone dot."
      },
      {
        "id": "danger",
        "label": "Danger",
        "description": "Danger tone dot."
      }
    ],
    "behavior": [
      {
        "label": "Tone",
        "description": "Set tone to color only the dot; the label stays neutral for legibility."
      },
      {
        "label": "Shared surface",
        "description": "Reuse it in cards and list rows so a status reads identically everywhere."
      }
    ],
    "accessibility": [
      {
        "label": "Visible meaning",
        "description": "The label text carries the status; the dot is a supporting visual."
      },
      {
        "label": "Contrast",
        "description": "Neutral label text keeps contrast independent of the tone color."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Concise label",
        "description": "Use a short status word; the pill does not wrap."
      },
      {
        "label": "Alignment",
        "description": "The dot stays aligned to the label as surrounding content shifts."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Static",
          "description": "Changing tone recolors the dot without animation."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "StatusIndicator 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-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-space-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-radius-xl",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-type-link-size",
      "light": "0.75rem",
      "dark": "0.75rem"
    },
    {
      "name": "--cds-bg-page",
      "light": "#f3f1ed",
      "dark": "#141410"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-status-success-solid",
      "light": "#008924",
      "dark": "#008924"
    }
  ],
  "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-statusindicator--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/status/StatusIndicator/StatusIndicator.stories.tsx

- [Tone Matrix](/storybook/iframe.html?id=cloaked-design-system-status-statusindicator--tone-matrix&viewMode=story) | export: ToneMatrix | source: packages/design-system/src/components/status/StatusIndicator/StatusIndicator.stories.tsx

- [Long Label](/storybook/iframe.html?id=cloaked-design-system-status-statusindicator--long-label&viewMode=story) | export: LongLabel | source: packages/design-system/src/components/status/StatusIndicator/StatusIndicator.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-status-statusindicator--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/status/StatusIndicator/StatusIndicator.stories.tsx

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