# SelectionIndicator

An internal, presentational selection mark shared by public Checkbox, Radio, RadioGroup and list selection rows. It is not a package-root export and must not be used as an interactive control.

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

## Guidance

{
  "summary": "An internal, presentational selection mark shared by public Checkbox, Radio, RadioGroup and list selection rows. It is not a package-root export and must not be used as an interactive control.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "The shared DS 4.5 selection chip — the round check/dot mark that `Checkbox`, `Radio`, and\n`RadioGroup` render. Presentational only (`aria-hidden`); it owns no interaction."
    },
    {
      "heading": "When to use",
      "body": "Effectively never from app code — this is a DS-internal building block and is not exported from\nthe package root. Reach for `Checkbox` (a `check` glyph) or `Radio` / `RadioGroup` (a `dot`), which\nwrap this chip with the correct role, keyboard, and accessibility semantics. It lives here only so\nthe three controls share one visual source of truth; render it directly only when authoring a new\nselection primitive inside the design system itself."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.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": "selected",
      "type": "boolean",
      "declared_type": "boolean",
      "required": true,
      "description": "Fills the chip (`--cds-bg-bold`) and reveals the glyph; unset shows the empty grey chip.",
      "source": {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 14
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "glyph",
      "type": "SelectionGlyph",
      "declared_type": "SelectionGlyph",
      "required": true,
      "description": "Glyph shown when selected — `check` for checkboxes, `dot` for radios.",
      "source": {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 16
      },
      "values": [
        "check",
        "dot"
      ],
      "values_complete": true
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Dims the chip to the disabled treatment; the wrapper still owns blocking interaction.",
      "source": {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 18
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Class hook for the wrapping control to compose focus/layout styling.",
      "source": {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 20
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": null,
    "public_path": null,
    "import_path": null,
    "root_kind": "internal",
    "entrypoints": [
      {
        "name": "SelectionIndicator",
        "signature": 1,
        "visibility": "internal",
        "source": {
          "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
          "line": 27
        },
        "props_type": "SelectionIndicatorProps",
        "props": [
          {
            "name": "selected",
            "type": "boolean",
            "declared_type": "boolean",
            "required": true,
            "description": "Fills the chip (`--cds-bg-bold`) and reveals the glyph; unset shows the empty grey chip.",
            "source": {
              "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
              "line": 14
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "glyph",
            "type": "SelectionGlyph",
            "declared_type": "SelectionGlyph",
            "required": true,
            "description": "Glyph shown when selected — `check` for checkboxes, `dot` for radios.",
            "source": {
              "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
              "line": 16
            },
            "values": [
              "check",
              "dot"
            ],
            "values_complete": true
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Dims the chip to the disabled treatment; the wrapper still owns blocking interaction.",
            "source": {
              "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
              "line": 18
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Class hook for the wrapping control to compose focus/layout styling.",
            "source": {
              "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
              "line": 20
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 6,
        "name": "SelectionGlyph",
        "code": "export type SelectionGlyph = 'check' | 'dot';"
      },
      {
        "path": "packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.tsx",
        "line": 12,
        "name": "SelectionIndicatorProps",
        "code": "interface SelectionIndicatorProps {\n    /** Fills the chip (`--cds-bg-bold`) and reveals the glyph; unset shows the empty grey chip. */\n    selected: boolean;\n    /** Glyph shown when selected — `check` for checkboxes, `dot` for radios. */\n    glyph: SelectionGlyph;\n    /** Dims the chip to the disabled treatment; the wrapper still owns blocking interaction. */\n    disabled?: boolean;\n    /** Class hook for the wrapping control to compose focus/layout styling. */\n    className?: 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": "SelectionIndicator",
      "status": "preview",
      "version": "0.1.0-preview.1",
      "summary": "An internal, presentational selection mark shared by public Checkbox, Radio, RadioGroup and list selection rows. It is not a package-root export and must not be used as an interactive control."
    },
    "parts": [
      {
        "id": "chip",
        "label": "Circular container",
        "description": "Hosts the selected or unselected fill.",
        "required": true
      },
      {
        "id": "glyph",
        "label": "Selection mark",
        "description": "Check icon for multiple choice or a small filled dot for single choice; absent when unselected.",
        "required": false
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "check": {
          "label": "Check",
          "description": "Multiple-choice visual."
        },
        "dot": {
          "label": "Dot",
          "description": "Single-choice visual."
        }
      },
      "sizes": {}
    },
    "variants": [
      {
        "id": "check",
        "label": "Check",
        "description": "selected=true renders a 24px check icon with stroke width 2.",
        "platforms": [
          "web"
        ]
      },
      {
        "id": "dot",
        "label": "Dot",
        "description": "selected=true renders an 8px filled circle.",
        "platforms": [
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "default-diameter",
        "label": "Default chip diameter",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "chip"
        ],
        "notes": "A private --selection-indicator-size hook lets owning controls replace an existing visual footprint; this is not a public size prop."
      },
      {
        "id": "dot-diameter",
        "label": "Selected dot diameter",
        "kind": "exact",
        "token": "--cds-size-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "glyph"
        ]
      },
      {
        "id": "radius",
        "label": "Circular shape",
        "kind": "exact",
        "token": "--cds-radius-full",
        "value": 9999,
        "unit": "px",
        "appliesTo": [
          "chip"
        ],
        "notes": "The radius token keeps the chip circular at its host-controlled size."
      }
    ],
    "layout": {
      "alignment": "The mark is centered inside the nonshrinking circular chip.",
      "flow": "One container and at most one visible mark.",
      "notes": [
        "Owning controls determine hit area, layout, focus and input semantics. The 32px visual is not a claim about the interactive target size."
      ]
    },
    "typographyAndColor": {
      "typography": [],
      "colors": [
        {
          "label": "Unselected container",
          "description": "Theme-specific empty selection fill.",
          "token": "--cds-selection-off-container"
        },
        {
          "label": "Selected container",
          "description": "Bold selection fill.",
          "token": "--cds-bg-bold"
        },
        {
          "label": "Selected mark",
          "description": "Check or dot foreground.",
          "token": "--cds-text-on-bold"
        }
      ]
    },
    "states": [
      {
        "id": "unselected",
        "label": "Unselected",
        "description": "Empty circular container; no check or dot is rendered."
      },
      {
        "id": "selected",
        "label": "Selected",
        "description": "Bold container and the requested check or dot."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Applies disabled opacity to either selected state. It does not block events because this helper owns no interaction."
      }
    ],
    "behavior": [
      {
        "label": "Pure visual state",
        "description": "selected and glyph are required. The helper has no event callbacks and keeps no selection state."
      },
      {
        "label": "Internal composition only",
        "description": "Public consumers should use Checkbox, Radio, RadioGroup or List.Item.Selection. Owning components may supply the private size hook and className."
      }
    ],
    "accessibility": [
      {
        "label": "Hidden decoration",
        "description": "The outer span is always aria-hidden=true. It provides no role, accessible name, focus stop or keyboard handling."
      },
      {
        "label": "Owner responsibilities",
        "description": "The public control must expose its checked and disabled states, accessible name, focus indicator and input behavior. Do not put this helper alone in a user flow."
      }
    ],
    "contentAdaptation": [
      {
        "label": "No text content",
        "description": "This helper does not render a label. Label and explanatory copy belong to its owning control."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Current transition",
          "description": "The local stylesheet transitions background over a literal 0.15s with ease. It has no helper-level reduced-motion override; include this in motion review rather than claiming complete reduced-motion parity."
        }
      ],
      "haptics": [
        {
          "label": "None",
          "description": "The visual helper requests no haptic feedback. Owning controls may do so on valid input."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "ios",
          "android"
        ],
        "description": "Native implementations and platform parity are not verified. Vue also has no local implementation.",
        "rationale": "This preview was authored from the local React types, implementation, styles and documentation. Native unit, typography, interaction and accessibility mappings require platform review."
      }
    ]
  },
  "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-size-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-radius-full",
      "light": "9999px",
      "dark": "9999px"
    },
    {
      "name": "--cds-selection-off-container",
      "light": "#e0ddd6",
      "dark": "#ffffff26"
    },
    {
      "name": "--cds-bg-bold",
      "light": "#0b0b0a",
      "dark": "#ffffff"
    },
    {
      "name": "--cds-text-on-bold",
      "light": "#ffffff",
      "dark": "#141410"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": null,
    "spec_origin": "local-authored",
    "local_spec_source_status": "preview",
    "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."
    },
    {
      "code": "public-export-unavailable",
      "detail": "This is an internal implementation helper, not a package-root export. Use its public parent controls."
    }
  ]
}
```

## Visual states

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

- [States](/storybook/iframe.html?id=cloaked-design-system-primitives-selectionindicator--states&viewMode=story) | export: States | source: packages/design-system/src/components/primitives/SelectionIndicator/SelectionIndicator.stories.tsx

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

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