# Radio A controlled round single-select control that selects an option without deselecting the current option on a second press. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/primitives/Radio/Radio.tsx ## Guidance { "summary": "A controlled round single-select control that selects an option without deselecting the current option on a second press.", "guidance": [ { "heading": "Overview", "body": "The bare single-select chip (`role=\"radio\"`). Select-only — pressing an unselected radio fires\n`onSelect`; pressing the selected one is a no-op, because exclusive selection is owned by the parent." }, { "heading": "When to use", "body": "You rarely reach for `Radio` directly — for a labeled set of mutually exclusive options use\n`RadioGroup`, which composes this chip with copy, layout, and group semantics. Drop to a bare\n`Radio` only when you are building a custom row layout the group can't express. Compared with its\nsiblings:\n\n- Selecting **more than one** item from a set? Use `Checkbox`.\n- A **compact 2–4 option** switch inline (a view or filter toggle)? Use `SegmentedControl`.\n- A **long list** of choices where space is tight? Use `Select`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/Radio/Radio.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": "Current state, exposed as `aria-checked`.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 14 }, "values": [ false, true ], "values_complete": true }, { "name": "onSelect", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Called when an unselected radio is pressed. A selected radio is a no-op.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 16 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Blocks the press and dims the chip.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 18 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label when no visible label is associated with the radio.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 20 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 21 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for selection. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 23 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the `role=\"radio\"` button; the chip inside is decorative and carries none.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 25 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Radio", "public_path": "Radio", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Radio", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 32 }, "props_type": "RadioProps", "props": [ { "name": "selected", "type": "boolean", "declared_type": "boolean", "required": true, "description": "Current state, exposed as `aria-checked`.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 14 }, "values": [ false, true ], "values_complete": true }, { "name": "onSelect", "type": "(() => void) | undefined", "declared_type": "() => void", "required": false, "description": "Called when an unselected radio is pressed. A selected radio is a no-op.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 16 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Blocks the press and dims the chip.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 18 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label when no visible label is associated with the radio.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 20 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 21 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for selection. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 23 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the `role=\"radio\"` button; the chip inside is decorative and carries none.", "source": { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 25 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Radio/Radio.tsx", "line": 12, "name": "RadioProps", "code": "export interface RadioProps {\n /** Current state, exposed as `aria-checked`. */\n selected: boolean;\n /** Called when an unselected radio is pressed. A selected radio is a no-op. */\n onSelect?: () => void;\n /** Blocks the press and dims the chip. */\n disabled?: boolean;\n /** Accessible label when no visible label is associated with the radio. */\n ariaLabel?: string;\n className?: string;\n /** Haptic feedback for selection. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n /** Selector on the `role=\"radio\"` button; the chip inside is decorative and carries none. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "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": "Radio", "status": "preview", "version": "2.0.0", "summary": "A controlled round single-select control that selects an option without deselecting the current option on a second press." }, "parts": [ { "id": "control", "label": "Control", "description": "Owns radio semantics, focus treatment, interaction, and disabled behavior." }, { "id": "selection-chip", "label": "Selection chip", "description": "Uses the shared internal selection visual without exposing it as a standalone public component." }, { "id": "dot", "label": "Selection dot", "description": "Appears only while this option is selected." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Radio has one round visual treatment." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A round select-only control for one option in an exclusive set.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "control-diameter", "label": "Control diameter", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "control", "selection-chip" ] }, { "id": "selection-dot-diameter", "label": "Selection dot diameter", "kind": "exact", "token": "--cds-size-8", "value": 8, "unit": "px", "appliesTo": [ "dot", "selected" ] } ], "layout": { "alignment": "The selection dot is centered inside the circular chip.", "flow": "The bare control is inline; a parent group composes visible labels and descriptions beside it.", "notes": [ "Use RadioGroup when presenting a complete labeled set of mutually exclusive options." ] }, "typographyAndColor": { "typography": [ { "label": "Composed label", "description": "A visible option label beside the bare control uses the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Unselected chip", "description": "Uses the neutral selection-off container role.", "token": "--cds-selection-off-container" }, { "label": "Selected chip", "description": "Uses the theme-aware bold fill.", "token": "--cds-bg-bold" }, { "label": "Selection dot", "description": "Maintains contrast on the selected fill.", "token": "--cds-text-on-bold" }, { "label": "Focus ring", "description": "Uses the brand accent for keyboard focus.", "token": "--cds-brand" } ] }, "states": [ { "id": "unselected", "label": "Unselected", "description": "Shows the neutral empty chip and reports aria-checked false." }, { "id": "selected", "label": "Selected", "description": "Shows the bold chip with a centered dot and reports aria-checked true." }, { "id": "disabled-unselected", "label": "Disabled unselected", "description": "Keeps the unselected value visible while blocking selection." }, { "id": "disabled-selected", "label": "Disabled selected", "description": "Keeps the selected value visible while blocking selection." }, { "id": "keyboard-focus", "label": "Keyboard focus", "description": "Shows the brand focus ring around the circular control." } ], "behavior": [ { "label": "Select only", "description": "Invoke selection once for an enabled unselected option; pressing the selected option is a no-op." }, { "label": "Parent ownership", "description": "Let the parent group enforce exclusivity and update which option is selected." }, { "label": "Disabled", "description": "Do not invoke selection or haptic feedback while disabled." } ], "accessibility": [ { "label": "Radio semantics", "description": "Expose radio role, the controlled selected value, and native disabled behavior." }, { "label": "Group semantics", "description": "Place related radio controls in a named radiogroup and associate each with visible option text." } ], "contentAdaptation": [ { "label": "Option copy", "description": "Keep the circular control fixed while visible labels and descriptions wrap in the parent layout." } ], "motionHaptics": { "motion": [ { "label": "Selection change", "description": "Change the chip fill and dot visibility without layout movement." } ], "haptics": [ { "label": "Selection feedback", "description": "Request the selection haptic after an enabled new selection unless feedback is disabled." } ] }, "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-size-8", "light": "8px", "dark": "8px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "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" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" } ], "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-primitives-radio--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx - [Unselected](/storybook/iframe.html?id=cloaked-design-system-primitives-radio--unselected&viewMode=story) | export: Unselected | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx - [Selected](/storybook/iframe.html?id=cloaked-design-system-primitives-radio--selected&viewMode=story) | export: Selected | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx - [Disabled](/storybook/iframe.html?id=cloaked-design-system-primitives-radio--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx - [States](/storybook/iframe.html?id=cloaked-design-system-primitives-radio--states&viewMode=story) | export: States | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-radio--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/Radio/Radio.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.