feat: add a helper text to radio buttons options

packages/circuit-ui/components/RadioButton/RadioButton.spec.tsx

@@ -69,6 +69,15 @@ describe('RadioButton', () => {
       const inputEl = screen.getByRole('radio');
       expect(inputEl).toHaveAccessibleName(defaultProps.label);
     });
+
+    it('should have a helper text', () => {
+      const ref = createRef<HTMLInputElement>();
+      render(<RadioButton ref={ref} {...defaultProps} helperText="Some explanation" />);
+      const helperEl = screen.getByTestId(`${defaultProps.value}-helper`);
+      expect(helperEl).toBeInTheDocument();
+      const labelEl = screen.getByText(defaultProps.label);
+      expect(labelEl).toHaveDescription("Some explanation")
+    });
   });
 
   describe('State & Interactions', () => {

packages/circuit-ui/components/RadioButton/RadioButton.tsx

@@ -36,6 +36,10 @@ export interface RadioButtonProps
    * A clear and concise description of the option's purpose.
    */
   label: string;
+  /**
+   * Further details about the option's purpose.
+   */
+  helperText?: string;
   /**
    * Triggers error styles on the component.
    */
@@ -72,7 +76,7 @@ const labelBaseStyles = ({ theme }: StyleProps) => css`
     content: '';
     display: block;
     position: absolute;
-    top: 50%;
+    top: calc(${theme.typography.body.one.lineHeight} / 2) ;
     left: 0;
     transform: translateY(-50%);
     transition: border ${theme.transitions.default};
@@ -87,14 +91,23 @@ const labelBaseStyles = ({ theme }: StyleProps) => css`
     content: '';
     display: block;
     position: absolute;
-    top: 50%;
+    top: calc(${theme.typography.body.one.lineHeight} / 2) ;
     left: ${theme.spacings.bit};
     transform: translateY(-50%) scale(0, 0);
     opacity: 0;
     transition: transform ${theme.transitions.default},
       opacity ${theme.transitions.default};
   }
 `;
+const helperTextBaseStyles = ({ theme }: StyleProps) => css`
+  color: var(--cui-fg-subtle);
+  display: inline-block;
+  position: relative;
+  cursor: pointer;
+  font-size: ${theme.typography.body.two.fontSize};
+  line-height: ${theme.typography.body.two.lineHeight};
+  margin-bottom: ${theme.spacings.bit}
+`;
 
 const labelInvalidStyles = ({ invalid }: LabelElProps) =>
   invalid &&
@@ -113,6 +126,9 @@ const RadioButtonLabel = styled('label')<LabelElProps>(
   labelBaseStyles,
   labelInvalidStyles,
 );
+const RadioButtonHelperText = styled('span')<LabelElProps>(
+    helperTextBaseStyles,
+);
 
 type InputElProps = Pick<RadioButtonProps, 'invalid'>;
 
@@ -149,7 +165,9 @@ const inputBaseStyles = css`
   }
 
   &:disabled + label,
-  &[disabled] + label {
+  &:disabled + label span,
+  &[disabled] + label,
+  &[disabled] + label span {
     pointer-events: none;
     color: var(--cui-fg-normal-disabled);
 
@@ -203,6 +221,7 @@ export const RadioButton = forwardRef(
     {
       onChange,
       label,
+      helperText,
       id: customId,
       name,
       value,
@@ -246,7 +265,7 @@ export const RadioButton = forwardRef(
           name={name}
           id={id}
           value={value}
-          invalid={invalid}
+          invalid={invalid ?? false}
           aria-invalid={invalid && 'true'}
           disabled={disabled}
           checked={checked}
@@ -255,11 +274,23 @@ export const RadioButton = forwardRef(
         />
         <RadioButtonLabel
           htmlFor={id}
-          invalid={invalid}
+          invalid={invalid ?? false}
           className={className}
           style={style}
+          aria-describedby={helperText ? `${id}-helper` : undefined}
         >
           {label}
+            {helperText &&
+                (<>
+                    <br/>
+                    <RadioButtonHelperText
+                    id={`${id}-helper`}
+                    data-testid={`${value}-helper`}
+                >
+                    {helperText}
+                </RadioButtonHelperText>
+                </>)
+            }
         </RadioButtonLabel>
       </Fragment>
     );

packages/circuit-ui/components/RadioButtonGroup/RadioButtonGroup.stories.tsx

@@ -44,8 +44,8 @@ Base.args = {
   label: 'Choose your favourite fruit',
   defaultValue: 'banana',
   options: [
-    { label: 'Apple', value: 'apple' },
-    { label: 'Banana', value: 'banana' },
+    { label: 'Apple', value: 'apple', helperText: "Keeps the doctor away" },
+    { label: 'Banana', value: 'banana', helperText: "Rich in Mg" },
     { label: 'Mango', value: 'mango' },
   ],
   // Storybook displays the default mocked function props poorly,
@@ -89,9 +89,9 @@ Validations.args = {
   label: 'Choose your favourite fruit',
   optionalLabel: 'Optional',
   options: [
-    { label: 'Apple', value: 'apple' },
-    { label: 'Banana', value: 'banana' },
-    { label: 'Mango', value: 'mango' },
+      { label: 'Apple', value: 'apple', helperText: "Keeps the doctor away" },
+      { label: 'Banana', value: 'banana', helperText: "Rich in Mg" },
+      { label: 'Mango', value: 'mango' },
   ],
 };
 
@@ -102,9 +102,9 @@ export const Disabled = (args: RadioButtonGroupProps) => (
       name="fully-disabled"
       disabled
       options={[
-        { label: 'Apple', value: 'apple' },
-        { label: 'Banana', value: 'banana' },
-        { label: 'Mango', value: 'mango' },
+          { label: 'Apple', value: 'apple', helperText: "Keeps the doctor away" },
+          { label: 'Banana', value: 'banana', helperText: "Rich in Mg" },
+          { label: 'Mango', value: 'mango' },
       ]}
       validationHint="All fruits are sold out"
       style={storyStyles}
@@ -113,9 +113,9 @@ export const Disabled = (args: RadioButtonGroupProps) => (
       {...args}
       name="partially-disabled"
       options={[
-        { label: 'Apple', value: 'apple' },
-        { label: 'Banana', value: 'banana' },
-        { label: 'Mango', value: 'mango', disabled: true },
+          { label: 'Apple', value: 'apple', helperText: "Keeps the doctor away" },
+          { label: 'Banana', value: 'banana', helperText: "Rich in Mg", disabled: true },
+          { label: 'Mango', value: 'mango' },
       ]}
       validationHint="Some fruits are sold out"
       style={storyStyles}