From 878ce35e6460b9f5317a4efe29b01c982d744995 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 11:43:00 -0500
Subject: [PATCH 01/11] allows FormControl.Label to render as a span or legend
 and updates the SegmentedControl example to render the label as a span

---
 docs/content/SegmentedControl.mdx     |  4 +++-
 src/FormControl/FormControl.docs.json |  6 ++++++
 src/FormControl/_FormControlLabel.tsx | 13 +++++--------
 src/_InputLabel.tsx                   |  8 ++++----
 src/utils/story-helpers.tsx           |  2 +-
 5 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/docs/content/SegmentedControl.mdx b/docs/content/SegmentedControl.mdx
index 9db26a21813..d5121d2224a 100644
--- a/docs/content/SegmentedControl.mdx
+++ b/docs/content/SegmentedControl.mdx
@@ -133,7 +133,9 @@ render(Controlled)
 
 ```jsx live
 <FormControl>
-  <FormControl.Label id="scLabel-horiz">File view</FormControl.Label>
+  <FormControl.Label id="scLabel-horiz" as="span">
+    File view
+  </FormControl.Label>
   <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
     <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
     <SegmentedControl.Button>Raw</SegmentedControl.Button>
diff --git a/src/FormControl/FormControl.docs.json b/src/FormControl/FormControl.docs.json
index 25b0cf834cb..1ee9f06913d 100644
--- a/src/FormControl/FormControl.docs.json
+++ b/src/FormControl/FormControl.docs.json
@@ -49,6 +49,12 @@
           "defaultValue": "false",
           "description": "Whether the label should be visually hidden"
         },
+        {
+          "name": "as",
+          "type": "'label' | 'legend' | 'span'",
+          "defaultValue": "'label'",
+          "description": "The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'"
+        }
         {
           "name": "sx",
           "type": "SystemStyleObject"
diff --git a/src/FormControl/_FormControlLabel.tsx b/src/FormControl/_FormControlLabel.tsx
index 323b1081248..9ae1e7d3bf4 100644
--- a/src/FormControl/_FormControlLabel.tsx
+++ b/src/FormControl/_FormControlLabel.tsx
@@ -1,6 +1,6 @@
 import React from 'react'
 import {SxProp} from '../sx'
-import InputLabel from '../_InputLabel'
+import InputLabel, {LegendOrSpanProps, LabelProps} from '../_InputLabel'
 import {FormControlContext} from './FormControl'
 import {Slot} from './slots'
 
@@ -9,15 +9,12 @@ export type Props = {
    * Whether the label should be visually hidden
    */
   visuallyHidden?: boolean
+  id?: string
 } & SxProp
 
-const FormControlLabel: React.FC<React.PropsWithChildren<{htmlFor?: string; id?: string} & Props>> = ({
-  children,
-  htmlFor,
-  id,
-  visuallyHidden,
-  sx,
-}) => (
+const FormControlLabel: React.FC<
+  React.PropsWithChildren<{htmlFor?: string} & (LegendOrSpanProps | LabelProps) & Props>
+> = ({children, htmlFor, id, visuallyHidden, sx}) => (
   <Slot name="Label">
     {({disabled, id: formControlId, required}: FormControlContext) => (
       <InputLabel
diff --git a/src/_InputLabel.tsx b/src/_InputLabel.tsx
index 3023b9c29c8..e1804c7398f 100644
--- a/src/_InputLabel.tsx
+++ b/src/_InputLabel.tsx
@@ -10,17 +10,17 @@ type BaseProps = SxProp & {
   id?: string
 }
 
-type LabelProps = BaseProps & {
+export type LabelProps = BaseProps & {
   htmlFor?: string
   as?: 'label'
 }
 
-type LegendProps = BaseProps & {
-  as: 'legend'
+export type LegendOrSpanProps = BaseProps & {
+  as: 'legend' | 'span'
   htmlFor?: undefined
 }
 
-type Props = LabelProps | LegendProps
+type Props = LabelProps | LegendOrSpanProps
 
 const InputLabel: React.FC<React.PropsWithChildren<Props>> = ({
   children,
diff --git a/src/utils/story-helpers.tsx b/src/utils/story-helpers.tsx
index e86349cf240..633949393e6 100644
--- a/src/utils/story-helpers.tsx
+++ b/src/utils/story-helpers.tsx
@@ -29,7 +29,7 @@ export type CheckboxOrRadioGroupArgs = CheckboxOrRadioGroupWrapperArgs &
   CheckboxOrRadioGroupValidationMessageArgs
 
 type FormControlParentArgs = Pick<ComponentProps<typeof FormControl>, 'required' | 'disabled'>
-type FormControlLabelArgs = ComponentProps<typeof FormControl.Label> & {labelChildren?: React.ReactNode}
+type FormControlLabelArgs = Omit<ComponentProps<typeof FormControl.Label>, 'as'> & {labelChildren?: React.ReactNode}
 type FormControlCaptionArgs = ComponentProps<typeof FormControl.Caption> & {captionChildren?: React.ReactNode}
 type FormControlValidationMessageArgs = ComponentProps<typeof FormControl.Validation> & {
   validationChildren?: React.ReactNode

From 656821a70058a41a9457f27c148f00ac84c53092 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 13:19:32 -0500
Subject: [PATCH 02/11] changes SegmentedControl.IconButton to use aria-current
 instead of aria-pressed

---
 src/SegmentedControl/SegmentedControlIconButton.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/SegmentedControl/SegmentedControlIconButton.tsx b/src/SegmentedControl/SegmentedControlIconButton.tsx
index 3ba844b6f67..ad506696ac4 100644
--- a/src/SegmentedControl/SegmentedControlIconButton.tsx
+++ b/src/SegmentedControl/SegmentedControlIconButton.tsx
@@ -47,7 +47,7 @@ export const SegmentedControlIconButton: React.FC<React.PropsWithChildren<Segmen
     <Box as="li" sx={mergedSx}>
       <Tooltip text={ariaLabel}>
         <SegmentedControlIconButtonStyled
-          aria-pressed={selected}
+          aria-current={selected}
           sx={getSegmentedControlButtonStyles({selected, isIconOnly: true})}
           {...rest}
         >

From ef9b17ccd8d85cf3bff806eb0a3c240c4b95182e Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 13:43:22 -0500
Subject: [PATCH 03/11] nicer small screen experience for the SegmentedControl
 story that shows it associated with a label and caption

---
 .../SegmentedControlFeatures.stories.tsx            | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
index 58cc79629bf..b2969cea172 100644
--- a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
+++ b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
@@ -129,10 +129,17 @@ export const IconOnly = () => (
 )
 IconOnly.storyName = 'Icon only'
 
-// TODO: make it possible to use FormControl as a wrapper for SegmentedControl
-// - FormControl.Label needs to accept a prop that lets it render an element that isn't a `<label>`
 export const AssociatedWithALabelAndCaption = () => (
-  <Box display="flex">
+  <Box
+    display="flex"
+    sx={(theme: any) => ({
+      flexDirection: 'column',
+      gap: theme.space[1],
+      [`@media screen and (min-width: ${theme.breakpoints[1]})`]: {
+        flexDirection: 'row',
+      },
+    })}
+  >
     <Box flexGrow={1}>
       <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
         File view

From 4bf53818f9b39e1e07dc2b2debc9af8de1212b4a Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 15:38:17 -0500
Subject: [PATCH 04/11] allows referencing a label for the ActionMenu

---
 src/ActionMenu.tsx                        |  9 ++-
 src/SegmentedControl/SegmentedControl.tsx | 67 +++++++++++++----------
 2 files changed, 46 insertions(+), 30 deletions(-)

diff --git a/src/ActionMenu.tsx b/src/ActionMenu.tsx
index f73caed7493..76990f496f5 100644
--- a/src/ActionMenu.tsx
+++ b/src/ActionMenu.tsx
@@ -101,7 +101,12 @@ type MenuOverlayProps = Partial<OverlayProps> &
      */
     children: React.ReactNode
   }
-const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({children, align = 'start', ...overlayProps}) => {
+const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({
+  children,
+  align = 'start',
+  'aria-labelledby': ariaLabelledby,
+  ...overlayProps
+}) => {
   // we typecast anchorRef as required instead of optional
   // because we know that we're setting it in context in Menu
   const {anchorRef, renderAnchor, anchorId, open, onOpen, onClose} = React.useContext(MenuContext) as MandateProps<
@@ -129,7 +134,7 @@ const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({children,
           value={{
             container: 'ActionMenu',
             listRole: 'menu',
-            listLabelledBy: anchorId,
+            listLabelledBy: ariaLabelledby || anchorId,
             selectionAttribute: 'aria-checked', // Should this be here?
             afterSelect: onClose,
           }}
diff --git a/src/SegmentedControl/SegmentedControl.tsx b/src/SegmentedControl/SegmentedControl.tsx
index c22d3d2cd4f..568a8423f77 100644
--- a/src/SegmentedControl/SegmentedControl.tsx
+++ b/src/SegmentedControl/SegmentedControl.tsx
@@ -9,6 +9,8 @@ import {ResponsiveValue, useResponsiveValue} from '../hooks/useResponsiveValue'
 import {ViewportRangeKeys} from '../utils/types/ViewportRangeKeys'
 import styled from 'styled-components'
 import {defaultSxProp} from '../utils/defaultSxProp'
+import VisuallyHidden from '../_VisuallyHidden'
+import {useId} from '../hooks/useId'
 
 type WidthOnlyViewportRangeKeys = Exclude<ViewportRangeKeys, 'narrowLandscape' | 'portrait' | 'landscape'>
 
@@ -58,6 +60,7 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
 }) => {
   const segmentedControlContainerRef = useRef<HTMLUListElement>(null)
   const {theme} = useTheme()
+  const labelId = useId()
   const isUncontrolled =
     onChange === undefined ||
     React.Children.toArray(children).some(
@@ -102,40 +105,48 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
   if (!ariaLabel && !ariaLabelledby) {
     // eslint-disable-next-line no-console
     console.warn(
-      'Use the `aria-label` or `aria-labelledby` prop to provide an accessible label for assistive technology',
+      'Use the `aria-label` or `aria-labelledby` prop to provide an accessible label for assistive technologies',
     )
   }
 
   return responsiveVariant === 'dropdown' ? (
     // Render the 'dropdown' variant of the SegmentedControlButton or SegmentedControlIconButton
-    <ActionMenu>
-      <ActionMenu.Button leadingIcon={getChildIcon(selectedChild)}>{getChildText(selectedChild)}</ActionMenu.Button>
-      <ActionMenu.Overlay>
-        <ActionList selectionVariant="single">
-          {React.Children.map(children, (child, index) => {
-            const ChildIcon = getChildIcon(child)
-            // Not a valid child element - skip rendering
-            if (!React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child)) {
-              return null
-            }
+    <>
+      <ActionMenu>
+        {/*
+          The aria-label is only provided as a backup when the designer or engineer neglects to show a label for the SegmentedControl.
+          The best thing to do is to have a visual label who's id is referenced using the `aria-labelledby` prop.
+        */}
+        <ActionMenu.Button aria-label={ariaLabel} leadingIcon={getChildIcon(selectedChild)}>
+          {getChildText(selectedChild)}
+        </ActionMenu.Button>
+        <ActionMenu.Overlay aria-labelledby={ariaLabelledby}>
+          <ActionList selectionVariant="single">
+            {React.Children.map(children, (child, index) => {
+              const ChildIcon = getChildIcon(child)
+              // Not a valid child element - skip rendering
+              if (!React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child)) {
+                return null
+              }
 
-            return (
-              <ActionList.Item
-                key={`segmented-control-action-btn-${index}`}
-                selected={index === selectedIndex}
-                onSelect={(event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
-                  isUncontrolled && setSelectedIndexInternalState(index)
-                  onChange && onChange(index)
-                  child.props.onClick && child.props.onClick(event as React.MouseEvent<HTMLLIElement>)
-                }}
-              >
-                {ChildIcon && <ChildIcon />} {getChildText(child)}
-              </ActionList.Item>
-            )
-          })}
-        </ActionList>
-      </ActionMenu.Overlay>
-    </ActionMenu>
+              return (
+                <ActionList.Item
+                  key={`segmented-control-action-btn-${index}`}
+                  selected={index === selectedIndex}
+                  onSelect={(event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
+                    isUncontrolled && setSelectedIndexInternalState(index)
+                    onChange && onChange(index)
+                    child.props.onClick && child.props.onClick(event as React.MouseEvent<HTMLLIElement>)
+                  }}
+                >
+                  {ChildIcon && <ChildIcon />} {getChildText(child)}
+                </ActionList.Item>
+              )
+            })}
+          </ActionList>
+        </ActionMenu.Overlay>
+      </ActionMenu>
+    </>
   ) : (
     // Render a segmented control
     <SegmentedControlList

From 163440f596077cc5934676d1e983f902b68b0e3b Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 15:55:24 -0500
Subject: [PATCH 05/11] fixes a bug where 'defaultSelected' prop would not work

---
 .../SegmentedControl.stories.tsx               |  2 +-
 src/SegmentedControl/SegmentedControl.test.tsx | 18 +++++++++++++++++-
 src/SegmentedControl/SegmentedControl.tsx      |  2 +-
 .../SegmentedControlFeatures.stories.tsx       | 18 +++++++++---------
 4 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/src/SegmentedControl/SegmentedControl.stories.tsx b/src/SegmentedControl/SegmentedControl.stories.tsx
index 806da7a3626..8c91eb06b02 100644
--- a/src/SegmentedControl/SegmentedControl.stories.tsx
+++ b/src/SegmentedControl/SegmentedControl.stories.tsx
@@ -112,7 +112,7 @@ export const Playground: Story<Args> = args => (
     variant={parseVariantFromArgs(args)}
     size={args.size}
   >
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
diff --git a/src/SegmentedControl/SegmentedControl.test.tsx b/src/SegmentedControl/SegmentedControl.test.tsx
index 76e7a077d3d..ea95e54d70b 100644
--- a/src/SegmentedControl/SegmentedControl.test.tsx
+++ b/src/SegmentedControl/SegmentedControl.test.tsx
@@ -45,7 +45,7 @@ describe('SegmentedControl', () => {
     SegmentedControl,
   })
 
-  it('renders with a selected segment', () => {
+  it('renders with a selected segment - controlled', () => {
     const {getByText} = render(
       <SegmentedControl aria-label="File view">
         {segmentData.map(({label}, index) => (
@@ -61,6 +61,22 @@ describe('SegmentedControl', () => {
     expect(selectedButton?.getAttribute('aria-current')).toBe('true')
   })
 
+  it('renders with a selected segment - uncontrolled', () => {
+    const {getByText} = render(
+      <SegmentedControl aria-label="File view">
+        {segmentData.map(({label}, index) => (
+          <SegmentedControl.Button defaultSelected={index === 1} key={label}>
+            {label}
+          </SegmentedControl.Button>
+        ))}
+      </SegmentedControl>,
+    )
+
+    const selectedButton = getByText('Raw').closest('button')
+
+    expect(selectedButton?.getAttribute('aria-current')).toBe('true')
+  })
+
   it('renders the dropdown variant', () => {
     act(() => {
       matchMedia.useMediaQuery(viewportRanges.narrow)
diff --git a/src/SegmentedControl/SegmentedControl.tsx b/src/SegmentedControl/SegmentedControl.tsx
index 568a8423f77..29916e736de 100644
--- a/src/SegmentedControl/SegmentedControl.tsx
+++ b/src/SegmentedControl/SegmentedControl.tsx
@@ -71,7 +71,7 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
   const selectedSegments = React.Children.toArray(children).map(
     child =>
       React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child) &&
-      child.props.selected,
+      (isUncontrolled ? child.props.defaultSelected : child.props.selected),
   )
   const hasSelectedButton = selectedSegments.some(isSelected => isSelected)
   const selectedIndexExternal = hasSelectedButton ? selectedSegments.indexOf(true) : 0
diff --git a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
index b2969cea172..a59038e52ea 100644
--- a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
+++ b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
@@ -11,7 +11,7 @@ export default {
 
 export const Default = () => (
   <SegmentedControl aria-label="File view">
-    <SegmentedControl.Button selected>Preview</SegmentedControl.Button>
+    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
     <SegmentedControl.Button>Raw</SegmentedControl.Button>
     <SegmentedControl.Button>Blame</SegmentedControl.Button>
   </SegmentedControl>
@@ -19,7 +19,7 @@ export const Default = () => (
 
 export const WithIcons = () => (
   <SegmentedControl aria-label="File view">
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -47,7 +47,7 @@ export const Controlled = () => {
 
 export const VariantNarrowHideLabels = () => (
   <SegmentedControl aria-label="File view" variant={{narrow: 'hideLabels', regular: 'default', wide: 'default'}}>
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -62,7 +62,7 @@ VariantNarrowHideLabels.storyName = '[variant: narrow] Hide labels'
 
 export const VariantNarrowActionMenu = () => (
   <SegmentedControl aria-label="File view" variant={{narrow: 'dropdown', regular: 'default', wide: 'default'}}>
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -77,7 +77,7 @@ VariantNarrowActionMenu.storyName = '[variant: narrow] Action menu'
 
 export const FullwidthNarrow = () => (
   <SegmentedControl aria-label="File view" fullWidth={{narrow: true, regular: false, wide: false}}>
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -92,7 +92,7 @@ FullwidthNarrow.storyName = '[fullWidth: narrow]'
 
 export const FullwidthRegular = () => (
   <SegmentedControl aria-label="File view" fullWidth={{narrow: false, regular: true, wide: false}}>
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -107,7 +107,7 @@ FullwidthRegular.storyName = '[fullWidth: regular]'
 
 export const FullwidthAll = () => (
   <SegmentedControl aria-label="File view" fullWidth>
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>
@@ -122,7 +122,7 @@ FullwidthAll.storyName = 'Full width'
 
 export const IconOnly = () => (
   <SegmentedControl aria-label="File view">
-    <SegmentedControl.IconButton selected aria-label={'Preview'} icon={EyeIcon} />
+    <SegmentedControl.IconButton defaultSelected aria-label={'Preview'} icon={EyeIcon} />
     <SegmentedControl.IconButton aria-label={'Raw'} icon={FileCodeIcon} />
     <SegmentedControl.IconButton aria-label={'Blame'} icon={PeopleIcon} />
   </SegmentedControl>
@@ -149,7 +149,7 @@ export const AssociatedWithALabelAndCaption = () => (
       </Text>
     </Box>
     <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
-      <SegmentedControl.Button selected>Preview</SegmentedControl.Button>
+      <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
       <SegmentedControl.Button>Raw</SegmentedControl.Button>
       <SegmentedControl.Button>Blame</SegmentedControl.Button>
     </SegmentedControl>

From 00e55fd9295a12436ba23b74c7691a726c5e19b4 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 16:13:42 -0500
Subject: [PATCH 06/11] updates docs

---
 docs/content/SegmentedControl.mdx     | 80 +++++++++++++--------------
 src/FormControl/FormControl.docs.json |  2 +-
 2 files changed, 39 insertions(+), 43 deletions(-)

diff --git a/docs/content/SegmentedControl.mdx b/docs/content/SegmentedControl.mdx
index d5121d2224a..d6c56925d65 100644
--- a/docs/content/SegmentedControl.mdx
+++ b/docs/content/SegmentedControl.mdx
@@ -9,16 +9,48 @@ storybook: '/react/storybook/?path=/story/components-segmentedcontrol'
 
 import data from '../../src/SegmentedControl/SegmentedControl.docs.json'
 
+<Note variant="warning">
+
+A `SegmentedControl` should not be used in a form as a replacement for something like a [RadioGroup](/RadioGroup) or [Select](/Select). See the [Accessibility section](https://primer.style/design/components/segmented-control#accessibility) of the SegmentedControl interface guidelines for more details.
+
+</Note>
+
 ## Examples
 
-### Uncontrolled (default)
+### With a label above and caption below
 
 ```jsx live
-<SegmentedControl aria-label="File view">
-  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-  <SegmentedControl.Button>Raw</SegmentedControl.Button>
-  <SegmentedControl.Button>Blame</SegmentedControl.Button>
-</SegmentedControl>
+<FormControl>
+  <FormControl.Label id="scLabel-horiz" as="span">
+    File view
+  </FormControl.Label>
+  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
+    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
+    <SegmentedControl.Button>Raw</SegmentedControl.Button>
+    <SegmentedControl.Button>Blame</SegmentedControl.Button>
+  </SegmentedControl>
+  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
+</FormControl>
+```
+
+### With a label and caption on the left
+
+```jsx live
+<Box display="flex">
+  <Box flexGrow={1}>
+    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
+      File view
+    </Text>
+    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
+      Change the way the file is viewed
+    </Text>
+  </Box>
+  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
+    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
+    <SegmentedControl.Button>Raw</SegmentedControl.Button>
+    <SegmentedControl.Button>Blame</SegmentedControl.Button>
+  </SegmentedControl>
+</Box>
 ```
 
 ### Controlled
@@ -109,42 +141,6 @@ render(Controlled)
 </SegmentedControl>
 ```
 
-### With a label and caption on the left
-
-```jsx live
-<Box display="flex">
-  <Box flexGrow={1}>
-    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
-      File view
-    </Text>
-    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
-      Change the way the file is viewed
-    </Text>
-  </Box>
-  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
-    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-    <SegmentedControl.Button>Raw</SegmentedControl.Button>
-    <SegmentedControl.Button>Blame</SegmentedControl.Button>
-  </SegmentedControl>
-</Box>
-```
-
-### With a label above and caption below
-
-```jsx live
-<FormControl>
-  <FormControl.Label id="scLabel-horiz" as="span">
-    File view
-  </FormControl.Label>
-  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
-    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-    <SegmentedControl.Button>Raw</SegmentedControl.Button>
-    <SegmentedControl.Button>Blame</SegmentedControl.Button>
-  </SegmentedControl>
-  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
-</FormControl>
-```
-
 ### With something besides the first option selected
 
 ```jsx live
diff --git a/src/FormControl/FormControl.docs.json b/src/FormControl/FormControl.docs.json
index 1ee9f06913d..8f5aac8fa21 100644
--- a/src/FormControl/FormControl.docs.json
+++ b/src/FormControl/FormControl.docs.json
@@ -54,7 +54,7 @@
           "type": "'label' | 'legend' | 'span'",
           "defaultValue": "'label'",
           "description": "The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'"
-        }
+        },
         {
           "name": "sx",
           "type": "SystemStyleObject"

From b2d52f719240139a47dc3ab59121364b1c22226a Mon Sep 17 00:00:00 2001
From: mperrotti <mperrotti@users.noreply.github.com>
Date: Wed, 25 Jan 2023 21:45:05 +0000
Subject: [PATCH 07/11] Update generated/components.json

---
 generated/components.json | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/generated/components.json b/generated/components.json
index 70b8b9b7889..4842ed255c6 100644
--- a/generated/components.json
+++ b/generated/components.json
@@ -2717,6 +2717,12 @@
               "defaultValue": "false",
               "description": "Whether the label should be visually hidden"
             },
+            {
+              "name": "as",
+              "type": "'label' | 'legend' | 'span'",
+              "defaultValue": "'label'",
+              "description": "The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'"
+            },
             {
               "name": "sx",
               "type": "SystemStyleObject"

From b76a4629472777144b355e264fa1609cd0838a5d Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Wed, 25 Jan 2023 16:48:53 -0500
Subject: [PATCH 08/11] adds changeset

---
 .changeset/eleven-jokes-think.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/eleven-jokes-think.md

diff --git a/.changeset/eleven-jokes-think.md b/.changeset/eleven-jokes-think.md
new file mode 100644
index 00000000000..5ac7c24582a
--- /dev/null
+++ b/.changeset/eleven-jokes-think.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Addresses feedback from the accessibility team about our SegmentedControl component. These changes include an update to ActionMenu that allows u to specify the ID of the DOM node that labels the menu.

From ebe5623af895172389e0c818fe7053da29802736 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Fri, 27 Jan 2023 17:16:31 -0500
Subject: [PATCH 09/11] fixes bug that broke selected segment test

---
 src/SegmentedControl/SegmentedControl.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/SegmentedControl/SegmentedControl.tsx b/src/SegmentedControl/SegmentedControl.tsx
index 29916e736de..8eecf06b710 100644
--- a/src/SegmentedControl/SegmentedControl.tsx
+++ b/src/SegmentedControl/SegmentedControl.tsx
@@ -71,7 +71,7 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
   const selectedSegments = React.Children.toArray(children).map(
     child =>
       React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child) &&
-      (isUncontrolled ? child.props.defaultSelected : child.props.selected),
+      (child.props.defaultSelected || child.props.selected),
   )
   const hasSelectedButton = selectedSegments.some(isSelected => isSelected)
   const selectedIndexExternal = hasSelectedButton ? selectedSegments.indexOf(true) : 0

From 6c29939802d1550081c4fb1e7fb3b1eab8c74f24 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Fri, 27 Jan 2023 17:17:31 -0500
Subject: [PATCH 10/11] fixes styling issue where segment separation border was
 appearing on top of the outline

---
 src/SegmentedControl/SegmentedControl.tsx                 | 3 ---
 .../__snapshots__/SegmentedControl.test.tsx.snap          | 8 ++++++++
 src/SegmentedControl/getSegmentedControlStyles.ts         | 4 ++++
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/SegmentedControl/SegmentedControl.tsx b/src/SegmentedControl/SegmentedControl.tsx
index 8eecf06b710..1bac47b3d1d 100644
--- a/src/SegmentedControl/SegmentedControl.tsx
+++ b/src/SegmentedControl/SegmentedControl.tsx
@@ -9,8 +9,6 @@ import {ResponsiveValue, useResponsiveValue} from '../hooks/useResponsiveValue'
 import {ViewportRangeKeys} from '../utils/types/ViewportRangeKeys'
 import styled from 'styled-components'
 import {defaultSxProp} from '../utils/defaultSxProp'
-import VisuallyHidden from '../_VisuallyHidden'
-import {useId} from '../hooks/useId'
 
 type WidthOnlyViewportRangeKeys = Exclude<ViewportRangeKeys, 'narrowLandscape' | 'portrait' | 'landscape'>
 
@@ -60,7 +58,6 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
 }) => {
   const segmentedControlContainerRef = useRef<HTMLUListElement>(null)
   const {theme} = useTheme()
-  const labelId = useId()
   const isUncontrolled =
     onChange === undefined ||
     React.Children.toArray(children).some(
diff --git a/src/SegmentedControl/__snapshots__/SegmentedControl.test.tsx.snap b/src/SegmentedControl/__snapshots__/SegmentedControl.test.tsx.snap
index 46e1ec3c4f8..c0bb18bff45 100644
--- a/src/SegmentedControl/__snapshots__/SegmentedControl.test.tsx.snap
+++ b/src/SegmentedControl/__snapshots__/SegmentedControl.test.tsx.snap
@@ -27,6 +27,10 @@ exports[`SegmentedControl renders consistently 1`] = `
   width: 1px;
 }
 
+.c1:focus-within:has(:focus-visible) {
+  --separator-color: transparent;
+}
+
 .c1:first-child {
   margin-left: -1px;
 }
@@ -61,6 +65,10 @@ exports[`SegmentedControl renders consistently 1`] = `
   width: 1px;
 }
 
+.c3:focus-within:has(:focus-visible) {
+  --separator-color: transparent;
+}
+
 .c3:first-child {
   margin-left: -1px;
 }
diff --git a/src/SegmentedControl/getSegmentedControlStyles.ts b/src/SegmentedControl/getSegmentedControlStyles.ts
index 1c0651ca4ea..95c7a19bf6e 100644
--- a/src/SegmentedControl/getSegmentedControlStyles.ts
+++ b/src/SegmentedControl/getSegmentedControlStyles.ts
@@ -115,5 +115,9 @@ export const getSegmentedControlListItemStyles = () => ({
   marginTop: '-1px',
   marginBottom: '-1px',
   ':not(:last-child)': borderedSegment,
+  // Needed to hide the segment border when the button is focused. Without this, the segment border overlaps the focus outline.
+  ':focus-within:has(:focus-visible)': {
+    '--separator-color': 'transparent',
+  },
   ...directChildLayoutAdjustments,
 })

From f01f4376ff2d0c9ea61a0f9287ebe657e7f27c64 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Fri, 3 Feb 2023 19:42:09 -0500
Subject: [PATCH 11/11] fixes linting issue

---
 src/SegmentedControl/SegmentedControlFeatures.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
index a59038e52ea..b244058aec4 100644
--- a/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
+++ b/src/SegmentedControl/SegmentedControlFeatures.stories.tsx
@@ -132,7 +132,7 @@ IconOnly.storyName = 'Icon only'
 export const AssociatedWithALabelAndCaption = () => (
   <Box
     display="flex"
-    sx={(theme: any) => ({
+    sx={theme => ({
       flexDirection: 'column',
       gap: theme.space[1],
       [`@media screen and (min-width: ${theme.breakpoints[1]})`]: {