{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "radiogroup", "name": "RadioGroup", "category": "Forms", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "visual_reference": { "stories": [ { "id": "cloaked-design-system-forms-radiogroup--playground", "name": "Playground", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Playground", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--playground&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-field", "name": "With Field", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithField", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-field&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--label-only", "name": "Label Only", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "LabelOnly", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--label-only&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-disabled-option", "name": "With Disabled Option", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithDisabledOption", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-disabled-option&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--disabled", "name": "Disabled", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Disabled", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--disabled&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--state-matrix", "name": "State Matrix", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "StateMatrix", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--state-matrix&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--dark-theme&viewMode=story" } ], "name": "RadioGroup", "id": "radiogroup", "category": "Forms" }, "stories_source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { disabledControl, hapticArgType } from '../../../storybook/controlOptions';\nimport { Field } from '../Field/Field';\nimport { RadioGroup } from './RadioGroup';\n\nconst VOICE_OPTIONS = [\n { value: 'ash', label: 'Ash', description: 'Warm and even' },\n { value: 'alloy', label: 'Alloy', description: 'Bright and direct' },\n { value: 'ballad', label: 'Ballad', description: 'Soft and unhurried' },\n { value: 'coral', label: 'Coral', description: 'Friendly and upbeat' },\n];\n\nconst FREQUENCY_OPTIONS = [\n { value: 'daily', label: 'Daily' },\n { value: 'weekly', label: 'Weekly' },\n { value: 'off', label: 'Off' },\n];\n\nconst SHIMMER_OPTION = { value: 'shimmer', label: 'Shimmer', description: 'Coming soon', disabled: true };\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Forms/RadioGroup',\n component: RadioGroup,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A single-choice control that keeps every `RadioOption` visible at once. Options render as ' +\n 'divider-separated `List.Item.Selection` rows with the control at the trailing edge, so a group ' +\n 'sits flush on the surface rather than as stacked cards. Use it when the list is short (2–5 ' +\n 'options) and seeing all choices aids the decision; reach for `Select` when the list is long or ' +\n 'space is tight. Each option can carry a `description`, and individual options or the whole ' +\n 'group can be `disabled`. Pair with `Field` for a label; only pass the standalone aria props ' +\n 'when used outside `Field`. Each row derives its test id from the group `testId` plus the ' +\n 'option value.',\n },\n },\n },\n args: {\n value: 'ash',\n ariaLabel: 'Assistant voice',\n options: VOICE_OPTIONS,\n testId: 'radio-group-story',\n },\n argTypes: {\n options: {\n ...disabledControl,\n description: 'The `RadioOption[]`; each has a `value`, `label`, optional `description`.',\n },\n onChange: { ...disabledControl, description: 'Called with the newly selected option `value`.' },\n haptic: { ...hapticArgType, description: 'Haptic fired on selection. Defaults to `true` (`selection`).' },\n value: { control: 'text', description: 'Currently selected option `value`.' },\n disabled: { control: 'boolean', description: 'Disables every option in the group.' },\n required: { control: 'boolean', description: 'Marks the group required for assistive technology.' },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const WithField: Story = {\n parameters: {\n docs: { description: { story: 'Wrapped in `Field` so the label and aria wiring come from the field.' } },\n },\n render: () => (\n \n \n \n ),\n};\n\nexport const LabelOnly: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Without descriptions the row tightens from 80px to 64px, so short groups stay compact.',\n },\n },\n },\n args: {\n value: 'weekly',\n ariaLabel: 'Notification frequency',\n options: FREQUENCY_OPTIONS,\n testId: 'radio-group-label-only',\n },\n};\n\nexport const WithDisabledOption: Story = {\n parameters: {\n docs: { description: { story: 'A single option disabled while the rest of the group stays selectable.' } },\n },\n args: {\n options: [SHIMMER_OPTION, ...VOICE_OPTIONS],\n testId: 'radio-group-disabled-option',\n },\n};\n\nexport const Disabled: Story = {\n parameters: { docs: { description: { story: 'The whole group disabled.' } } },\n args: { value: 'ash', disabled: true, testId: 'radio-group-disabled' },\n};\n\nexport const StateMatrix: Story = {\n parameters: {\n docs: { description: { story: 'Described, label-only, one-disabled-option, and fully-disabled groups.' } },\n },\n render: () => (\n \n \n \n \n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: { docs: { description: { story: 'Row, divider, and control tokens on the dark theme.' } } },\n render: () => (\n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "RadioGroup", "status": "preview", "version": "3.0.0", "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows." }, "parts": [ { "id": "group", "label": "Group", "description": "Owns the accessible radio-group name, validation, and required state." }, { "id": "option", "label": "Option row", "description": "Pressable full-width row carrying one option's copy and its selection control." }, { "id": "label", "label": "Option label", "description": "Names the option and provides the row's accessible name." }, { "id": "description", "label": "Option description", "description": "Optional supporting copy beneath the option label." }, { "id": "indicator", "label": "Selection indicator", "description": "Trailing control showing unselected or selected-dot state without duplicating semantics." }, { "id": "divider", "label": "Row divider", "description": "Hairline separating adjacent options; absent after the last option." } ], "allowedDesignChoices": { "variants": { "row": { "label": "Row", "description": "Each option is one full-width selection row on the list surface." } }, "sizes": {} }, "variants": [ { "id": "row", "label": "Row", "description": "Divider-separated single-choice rows with a trailing selection control.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "row-min-height", "label": "Option row height", "kind": "at-least", "token": "--cds-size-80", "value": 80, "unit": "px", "appliesTo": [ "option", "description" ] }, { "id": "compact-row-min-height", "label": "Option row height without description", "kind": "at-least", "token": "--cds-size-64", "value": 64, "unit": "px", "appliesTo": [ "option" ] }, { "id": "row-inset", "label": "Option row inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "option" ] }, { "id": "copy-to-control-gap", "label": "Copy-to-control gap", "kind": "exact", "token": "--cds-space-24", "value": 24, "unit": "px", "appliesTo": [ "option", "indicator" ] }, { "id": "indicator-diameter", "label": "Selection indicator diameter", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "indicator" ] } ], "layout": { "alignment": "Copy fills the leading column and the selection control pins to the trailing edge, both vertically centered.", "flow": "Options stack full-width with a hairline between adjacent rows and none after the last.", "notes": [ "Keep option rows flush to the surface; do not wrap them in per-option cards or radii.", "Use Select when the choice list is too long to keep visible." ] }, "typographyAndColor": { "typography": [ { "label": "Option label", "description": "Use body text for the option name.", "token": "--cds-type-body-size" }, { "label": "Option description", "description": "Use body-small secondary text for supporting copy.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Row surface", "description": "Use the list row surface for every option, selected or not.", "token": "--cds-bg-surface" }, { "label": "Row divider", "description": "Use the shared divider hairline between adjacent options.", "token": "--cds-divider" }, { "label": "Selected indicator", "description": "Use the theme-aware bold fill for the chosen option's control.", "token": "--cds-bg-bold" }, { "label": "Option copy", "description": "Use primary and secondary text emphasis by copy hierarchy.", "token": "--cds-text-primary" } ] }, "states": [ { "id": "unselected", "label": "Unselected", "description": "Shows the neutral empty indicator with no row treatment change." }, { "id": "selected", "label": "Selected", "description": "Fills the trailing indicator and shows the dot; the row itself is unchanged." }, { "id": "option-disabled", "label": "Option disabled", "description": "Dims one row and blocks its press while leaving the rest selectable." }, { "id": "group-disabled", "label": "Group disabled", "description": "Dims and blocks every option in the group." }, { "id": "invalid", "label": "Invalid", "description": "Exposes group-level invalid and described-by relationships supplied by Field." } ], "behavior": [ { "label": "Single selection", "description": "Emit a new option value only when it differs from the controlled value." }, { "label": "Disabled options", "description": "Never emit changes for a disabled option or disabled group." }, { "label": "Row press target", "description": "Treat the whole row as the press target, not just the selection control." } ], "accessibility": [ { "label": "Group name", "description": "Associate a visible Field label or provide an accessible group name." }, { "label": "Option semantics", "description": "Expose each option as a radio whose accessible name is its label and whose description is announced when present." }, { "label": "Validation", "description": "Expose required, invalid, and described-by state on the group without duplicating it on decorative indicators." } ], "contentAdaptation": [ { "label": "Option count", "description": "Keep groups to a short visible set; use Select for long lists." }, { "label": "Descriptions", "description": "Use concise descriptions to clarify consequences, not repeat option labels; omitting them tightens the row." } ], "motionHaptics": { "motion": [ { "label": "Selection state", "description": "Change only the indicator fill and dot; option content must not move." } ], "haptics": [ { "label": "Selection feedback", "description": "Request the selection haptic after a new enabled value is chosen, and none when the current value is re-pressed." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "Web renders each option as a button with radio semantics rather than a native radio input; native platforms map the same option content to their radio accessibility controls.", "rationale": "The row is the press target on every platform, and the shared row treatment matters more here than native input chrome the design hides anyway." } ] }, "specification_source": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.spec.json", "guidance": { "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows.", "guidance": [ { "heading": "Overview", "body": "Manages a set of radios as one mutually-exclusive field — one `value`, labelled `options`, and\ngroup semantics (`role=\"radiogroup\"`). This is the control you reach for, not the bare `Radio`.\n\nOptions render as divider-separated `List.Item.Selection` rows with the control at the trailing\nedge, so a group reads as part of the surface it sits on. Rows are 80px with a `description` and\n64px without." }, { "heading": "When to use", "body": "Use `RadioGroup` for a single choice where every option should stay visible so seeing them all\naids the decision — best at 2–5 options. Pair it with `Field` for the label; only pass the\nstandalone aria props when used outside `Field`. Choosing between the neighbours:\n\n- The list is **long or space is tight**? Use `Select` — don't stack a dozen radios.\n- You need a **compact inline** 2–4 option switch (view/filter) rather than a labelled form field?\n Use `SegmentedControl`.\n- The user may pick **more than one** option? Use `Checkbox`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.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." }, "links": { "human": "/component-radiogroup", "json": "/data/visual/components/radiogroup.json", "storybook": "/storybook/?path=/story/cloaked-design-system-forms-radiogroup--playground" } }