docs: README for RadioButtonField component (#844)

packages/forma-36-react-components/src/components/CheckboxField/README.mdx

@@ -1,4 +1,4 @@
-Use CheckboxField to give users the possibility to select multiple elements, zero, one or more items. This component can be used for example in forms or terms and conditions. It contains a checkbox with its label. For a single choice, please consider using RadioButton component.
+Use CheckboxField to give users the possibility to select multiple elements, zero, one or more items. This component can be used for example in forms or terms and conditions. It contains a checkbox with its label. For a single choice, please consider using [RadioButtonField component](https://f36.contentful.com/components/radio-button-field/).
 
 ## Table of contents
 

packages/forma-36-react-components/src/components/RadioButtonField/README.mdx

@@ -0,0 +1,71 @@
+Use RadioButtonField to give users the possibility to select only one option from a number of choices. It contains a radio input with its label. If needed the component can display an error message and hint message. For a multiple-choice, please consider using [ChecboxField component](https://f36.contentful.com/components/checkbox-field/).
+
+## Table of contents
+
+- [How to use RadioButtonField](#how-to-use-radioButtonField)
+- [Code examples](#component-variations)
+- [Content recommendations](#content-recommendations)
+- [Accessibility](#accessibility)
+
+## How to use RadioButtonField
+
+- RadioButtonField should be used in a group. Please include at least two or more choices for users
+- Options provided for users should be mutually exclusive.
+- Make sure choices don’t overlap. Avoid patterns like: 1990-2000, 2000-2010.
+- Be explicit about the action that will follow if the radio button is selected
+
+## Code examples
+
+Basic usage
+
+```jsx
+// import {RadioButtonField} from '@contentful/forma-36-react-components';
+
+<RadioButtonField labelText="Label text" id="randomId" />
+```
+
+Example with 2 options with helper text displayed
+
+```jsx
+// import {RadioButtonField} from '@contentful/forma-36-react-components';
+
+function RadioButtonFieldExample() {
+  const [activeOption, setActiveOption] = React.useState('yes');
+
+  return (
+    <Flex flexDirection="column">
+      <RadioButtonField
+        name="radio option 1"
+        id="randomId1"
+        value="yes"
+        checked={activeOption === 'yes'}
+        onChange={(e) => {
+          setActiveOption(e.target.value);
+        }}
+        labelText="Radio button checked"
+        helpText="Helper text displayed below"
+      />
+      <RadioButtonField
+        name="radio option 2"
+        id="randomId2"
+        value="no"
+        checked={activeOption === 'no'}
+        onChange={(e) => {
+          setActiveOption(e.target.value);
+        }}
+        labelText="Second option"
+        helpText="Helper text displayed below"
+      />
+    </Flex>
+  );
+}
+```
+
+## Content recommendations
+
+- Labels should be concise and provide context.
+- Use sentence-style capitalization (only the first word in a phrase and any proper nouns capitalized)
+
+## Accessibility
+
+- Radio buttons should have a clear and concise label.

packages/forma-36-website/src/pages/components/radio-button-field/index.mdx

@@ -2,21 +2,6 @@
 title: 'Radio button field'
 type: 'component'
 status: 'stable'
-github: 'https://github.com/contentful/forma-36/tree/master/packages/forma-36-react-components/src/components/RadioButton'
-storybook: 'https://f36-storybook.contentful.com/?path=/story/components-radiobutton--default'
+github: 'https://github.com/contentful/forma-36/tree/master/packages/forma-36-react-components/src/components/RadioButtonField'
+storybook: 'https://f36-storybook.contentful.com/?path=/story/form-elements-radiobuttonfield--basic'
 ---
-
-Detailed documentation will be provided soon. For now, please have a look into the storybook for implementation details.
-
-```jsx
-<>
-  <RadioButtonField
-    labelText="Radio button label"
-    helpText="This is a helptext"
-    name="someOption"
-    checked={true}
-    value="yes"
-    id="termsCheckbox"
-  />
-</>
-```