feat: normalise component displayName conventions

.changeset/displayname-consistency.md

@@ -0,0 +1,11 @@
+---
+'@primer/react': patch
+---
+
+Normalise component `displayName` strings to the canonical `Parent.Slot` convention, and add `displayName` to compound sub-components and `forwardRef`-wrapped components that were missing it.
+
+- Renames sub-component `displayName` strings that were using camelCase without a separator to the canonical `Parent.Slot` convention: `BannerPrimaryAction` → `Banner.PrimaryAction`, `BannerSecondaryAction` → `Banner.SecondaryAction`, `Summary` → `Details.Summary`, `TimelineItem|Body|Break` → `Timeline.Item|Body|Break`, `ParentLink|TitleArea` → `PageHeader.ParentLink|TitleArea`, `HorizontalDivider|VerticalDivider` → `PageLayout.HorizontalDivider|VerticalDivider`.
+- Adds `displayName` to compound sub-components where the runtime function name doesn't match the canonical name users see (e.g. `Visual` → `Blankslate.Visual`, `SegmentedControlButton` → `SegmentedControl.Button`, `Panel` → `SelectPanel`, `FormControlCaption` → `FormControl.Caption`, etc.) and to `forwardRef`-wrapped components with anonymous inner arrow functions where DevTools would otherwise show `ForwardRef`.
+- Adds a contributor skill at `.github/skills/display-name/SKILL.md` documenting when `displayName` is required vs redundant, the canonical naming convention, and how it interacts with the slot system.
+
+No runtime behaviour changes.

.github/copilot-instructions.md

@@ -162,6 +162,10 @@ When working on UI components, always use the `primer-storybook` MCP tools to ac
 
 When building, modifying, or wrapping compound components that use child-component "slots" (anything involving `__SLOT__`, `useSlots`, `isSlot`, or `asSlot`), reference the `.github/skills/slots/SKILL.md` file. It documents when to add slot markers, naming conventions for `Symbol(...)` descriptions, the public slot APIs, and common pitfalls.
 
+## `displayName`
+
+When authoring or reviewing a component and deciding whether to set `displayName`, reference the `.github/skills/display-name/SKILL.md` file. It covers when `displayName` is needed (compound sub-components, anonymous `forwardRef` wrappers, slot sub-components) vs when modern React's `Function.name` inference makes it redundant, plus the canonical `Parent.Slot` naming convention.
+
 ## Known Issues and Workarounds
 
 **Timing Expectations:**

.github/skills/display-name/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: display-name
+description: "Use when: authoring or reviewing a component in Primer React, deciding whether to set `displayName`, and choosing the right string for it. Covers the criteria (when it's needed vs redundant), the canonical naming convention, and interaction with the slot system."
+---
+
+# `displayName` in Primer React
+
+`Component.displayName` controls how the component appears in React DevTools, error stacks, and one of the slot system's dev-mode warnings. This skill documents when to set it, when not to, and how to name it.
+
+## TL;DR
+
+- **Set `displayName` whenever the runtime function name doesn't match the canonical name you want users to see** — i.e. compound sub-components (`Banner.PrimaryAction`) or `forwardRef` wrappers around anonymous arrow functions.
+- **Skip `displayName` when the function/variable name already matches the canonical name.** Modern React + bundlers infer it from `Function.name` and assigning to a `const`. Adding `X.displayName = 'X'` is noise.
+- **Always use `Parent.Slot` dot notation** for sub-components, never camelCase concatenation (`TimelineItem` ❌, `Timeline.Item` ✅).
+
+## When to set `displayName`
+
+Set it in these cases:
+
+### 1. Compound sub-components where the function name doesn't match the canonical name
+
+```tsx
+// The function/variable name is the bare slot name, but DevTools should
+// show the dot-notation compound name.
+function Visual(...) { ... }
+Visual.displayName = 'Blankslate.Visual'
+
+const SegmentedControlButton = forwardRef(...)
+SegmentedControlButton.displayName = 'SegmentedControl.Button'
+
+const Panel = (...) => ...
+Panel.displayName = 'SelectPanel' // exported as `SelectPanel`, not `Panel`
+```
+
+### 2. `forwardRef` (or `memo`) wrapping an anonymous arrow function
+
+```tsx
+// ❌ Without displayName, DevTools shows "ForwardRef"
+// (variable-name inference works in React 18+ but is unreliable under minification).
+const Octicon = React.forwardRef((props, ref) => ...)
+Octicon.displayName = 'Octicon'
+```
+
+### 3. Sub-components in the slot system
+
+When a child does not match a configured slot by its `__SLOT__` marker, the slot system compares the child's `displayName` with the slot component's `displayName` in development. A matching name produces a warning that recommends `asSlot(wrapper, ParentSlotComponent)` to copy the marker. Setting an explicit `displayName` on each slot sub-component keeps this warning useful.
+
+## When you can skip `displayName`
+
+Skip it in these cases — adding it is pure noise:
+
+### 1. Named function components whose name matches the canonical name
+
+```tsx
+// ✅ `Function.name === 'Pagehead'` already; DevTools picks it up.
+export function Pagehead({...}) { ... }
+// No displayName needed.
+
+// Same for arrow functions assigned to a const:
+export const VisuallyHidden = ({...}) => { ... }
+// `VisuallyHidden.name === 'VisuallyHidden'` via variable-name inference.
+```
+
+### 2. `forwardRef` with a named inner function whose name matches
+
+```tsx
+// ✅ React 18+ uses the inner function name.
+const Label = React.forwardRef(function Label(props, ref) { ... })
+// No displayName needed.
+```
+
+### 3. `forwardRef` wrapping a `const` whose name matches (in React 18+)
+
+```tsx
+// In React 18 + modern bundlers, DevTools infers "Select" from the const assignment.
+const Select = React.forwardRef<HTMLSelectElement, SelectProps>((props, ref) => ...)
+// Skip displayName for the root, BUT set it on Select.Option / Select.OptGroup if
+// those wrap something whose name differs.
+```
+
+> Caveat: under aggressive minification (terser `keep_fnames: false`), `Function.name` becomes a short hash. If you ship a minified bundle and want DevTools to remain accurate in production builds, you can set `displayName` defensively. Primer's published build does not currently minify function names, so we treat `displayName` as optional in the cases above.
+
+## Naming convention
+
+| Component shape | Convention | Example |
+| --------------------------- | ----------------------- | ------------------------------------------ |
+| Top-level (root) component | `'ComponentName'` | `'Dialog'`, `'ActionList'` |
+| Sub-component of a compound | `'Parent.Slot'` | `'Dialog.Header'`, `'PageLayout.Pane'` |
+| Nested sub-component | `'Parent.Slot.SubSlot'` | `'ActionList.GroupHeading.TrailingAction'` |
+
+### Don't
+
+- `'TimelineItem'` — use `'Timeline.Item'`.
+- `'BannerPrimaryAction'` — use `'Banner.PrimaryAction'`.
+- `'ParentLink'` (PageHeader) — use `'PageHeader.ParentLink'`.
+- `'DEPRECATED_Tooltip'` or lifecycle annotations — handle deprecation via JSDoc/changesets, not the symbol/displayName.
+- `'My-Component'` (kebab-case) or `'my.component'` (lowercase) — always PascalCase tokens separated by dots.
+
+### Match the `Symbol(...)` description
+
+If the component has a `__SLOT__` marker, its `Symbol(...)` description should match the `displayName` so DevTools and crash logs use the same canonical name:
+
+```tsx
+Header.displayName = 'Dialog.Header'
+Header.__SLOT__ = Symbol('Dialog.Header')
+```
+
+See the `slots` skill for more on the slot system.
+
+Slot matching uses symbol identity, not the symbol description. The separate dev-mode wrapper warning compares component `displayName` values.
+
+## Checklist for a new compound component
+
+1. Top-level component: usually skip `displayName` — let the function name carry through.
+2. Each sub-component (e.g. `Foo.Bar`, `Foo.Baz`):
+ - Set `Sub.displayName = 'Foo.Bar'` after the declaration.
+ - If it's a slot sub-component, also set `Sub.__SLOT__ = Symbol('Foo.Bar')` with the matching description.
+3. If you use `forwardRef`/`memo` with an anonymous arrow inner function, either:
+ - Promote to a named inner: `forwardRef(function Foo(props, ref) { ... })`, or
+ - Set `Foo.displayName = 'Foo'` explicitly.
+
+## Quick decision tree
+
+```
+Is the function/variable name already the same as the canonical name?
+├── Yes → Is it forwardRef(arrow)?
+│ ├── Yes (anonymous inner) → Set displayName
+│ └── No (named or const) → Skip; DevTools infers
+└── No → Always set displayName (and match any __SLOT__ Symbol)
+```

packages/react/src/ActionBar/ActionBar.tsx

@@ -504,3 +504,7 @@ export const VerticalDivider = () => {
  />
  )
 }
+ActionBarIconButton.displayName = 'ActionBar.IconButton'
+ActionBarGroup.displayName = 'ActionBar.Group'
+ActionBarMenu.displayName = 'ActionBar.Menu'
+VerticalDivider.displayName = 'ActionBar.VerticalDivider'

packages/react/src/ActionList/Description.tsx

@@ -84,4 +84,5 @@ export const Description: FCWithSlotMarker<React.PropsWithChildren<ActionListDes
  }
 }
 
+Description.displayName = 'ActionList.Description'
 Description.__SLOT__ = Symbol('ActionList.Description')

packages/react/src/ActionList/Divider.tsx

@@ -22,4 +22,5 @@ export const Divider: FCWithSlotMarker<React.PropsWithChildren<ActionListDivider
  )
 }
 
+Divider.displayName = 'ActionList.Divider'
 Divider.__SLOT__ = Symbol('ActionList.Divider')

packages/react/src/ActionList/TrailingAction.tsx

@@ -76,4 +76,5 @@ export const TrailingAction = forwardRef(
  },
 ) as PolymorphicForwardRefComponent<'button' | 'a', ActionListTrailingActionProps>
 
+TrailingAction.displayName = 'ActionList.TrailingAction'
 TrailingAction.__SLOT__ = Symbol('ActionList.TrailingAction')

packages/react/src/Banner/Banner.tsx

@@ -273,7 +273,7 @@ const BannerPrimaryAction = forwardRef(({children, className, ...rest}, forwarde
  )
 }) as PolymorphicForwardRefComponent<'button', BannerPrimaryActionProps>
 
-BannerPrimaryAction.displayName = 'BannerPrimaryAction'
+BannerPrimaryAction.displayName = 'Banner.PrimaryAction'
 
 export type BannerSecondaryActionProps = Omit<ButtonProps, 'variant'>
 
@@ -291,6 +291,6 @@ const BannerSecondaryAction = forwardRef(({children, className, ...rest}, forwar
  )
 }) as PolymorphicForwardRefComponent<'button', BannerSecondaryActionProps>
 
-BannerSecondaryAction.displayName = 'BannerSecondaryAction'
+BannerSecondaryAction.displayName = 'Banner.SecondaryAction'
 
 export {BannerPrimaryAction, BannerSecondaryAction}

packages/react/src/Blankslate/Blankslate.tsx

@@ -145,3 +145,8 @@ export type {
  BlankslatePrimaryActionProps,
  BlankslateSecondaryActionProps,
 }
+Visual.displayName = 'Blankslate.Visual'
+Heading.displayName = 'Blankslate.Heading'
+Description.displayName = 'Blankslate.Description'
+PrimaryAction.displayName = 'Blankslate.PrimaryAction'
+SecondaryAction.displayName = 'Blankslate.SecondaryAction'

packages/react/src/DataTable/ErrorDialog.tsx

@@ -37,3 +37,5 @@ export function ErrorDialog({title = 'Error', children, onRetry, onDismiss}: Tab
  </ConfirmationDialog>
  )
 }
+
+ErrorDialog.displayName = 'Table.ErrorDialog'

packages/react/src/DataTable/Pagination.tsx

@@ -385,3 +385,5 @@ function usePagination(config: PaginationConfig): PaginationResult {
  selectNextPage,
  }
 }
+
+Pagination.displayName = 'Table.Pagination'

packages/react/src/DataTable/Table.tsx

@@ -408,3 +408,17 @@ export {
  TableCellPlaceholder,
  TableSkeleton,
 }
+
+TableHead.displayName = 'Table.Head'
+TableBody.displayName = 'Table.Body'
+TableHeader.displayName = 'Table.Header'
+TableSortHeader.displayName = 'Table.SortHeader'
+TableRow.displayName = 'Table.Row'
+TableCell.displayName = 'Table.Cell'
+TableCellPlaceholder.displayName = 'Table.CellPlaceholder'
+TableContainer.displayName = 'Table.Container'
+TableTitle.displayName = 'Table.Title'
+TableSubtitle.displayName = 'Table.Subtitle'
+TableDivider.displayName = 'Table.Divider'
+TableActions.displayName = 'Table.Actions'
+TableSkeleton.displayName = 'Table.Skeleton'

packages/react/src/Details/Details.tsx

@@ -57,7 +57,7 @@ function Summary<As extends React.ElementType>({as, children, ...props}: Summary
  </Component>
  )
 }
-Summary.displayName = 'Summary'
+Summary.displayName = 'Details.Summary'
 
 export {Summary}
 

packages/react/src/FilteredActionList/FilteredActionListInput.tsx

@@ -57,3 +57,5 @@ export function FilteredActionListInput({
  </div>
  )
 }
+
+FilteredActionListInput.displayName = 'FilteredActionList.Input'

packages/react/src/FilteredActionList/FilteredActionListLoaders.tsx

@@ -52,3 +52,5 @@ function LoadingSkeleton({rows = 10, ...props}: {rows: number}): JSX.Element {
  </div>
  )
 }
+
+FilteredActionListBodyLoader.displayName = 'FilteredActionList.BodyLoader'

packages/react/src/FormControl/FormControlCaption.tsx

@@ -26,6 +26,7 @@ function FormControlCaption({id, children, className, style}: FormControlCaption
  )
 }
 
+FormControlCaption.displayName = 'FormControl.Caption'
 FormControlCaption.__SLOT__ = Symbol('FormControl.Caption')
 
 export {FormControlCaption}

packages/react/src/FormControl/FormControlLabel.tsx

@@ -57,6 +57,7 @@ const FormControlLabel: FCWithSlotMarker<
  )
 }
 
+FormControlLabel.displayName = 'FormControl.Label'
 FormControlLabel.__SLOT__ = Symbol('FormControl.Label')
 
 export default FormControlLabel

packages/react/src/FormControl/FormControlLeadingVisual.tsx

@@ -21,6 +21,7 @@ const FormControlLeadingVisual: FCWithSlotMarker<React.PropsWithChildren<{style?
  )
 }
 
+FormControlLeadingVisual.displayName = 'FormControl.LeadingVisual'
 FormControlLeadingVisual.__SLOT__ = Symbol('FormControl.LeadingVisual')
 
 export default FormControlLeadingVisual

packages/react/src/PageHeader/PageHeader.tsx

@@ -232,7 +232,7 @@ const ParentLink = React.forwardRef<HTMLAnchorElement, ParentLinkProps>(
  )
  },
 ) as PolymorphicForwardRefComponent<'a', ParentLinkProps>
-ParentLink.displayName = 'ParentLink'
+ParentLink.displayName = 'PageHeader.ParentLink'
 
 // ContextBar
 // Generic slot for any component above the title region. Use it for custom breadcrumbs and other navigation elements instead of ParentLink.
@@ -300,7 +300,7 @@ const TitleArea = React.forwardRef<HTMLDivElement, React.PropsWithChildren<Title
  )
  },
 ) as PolymorphicForwardRefComponent<'div', TitleAreaProps>
-TitleArea.displayName = 'TitleArea'
+TitleArea.displayName = 'PageHeader.TitleArea'
 
 // PageHeader.LeadingAction and PageHeader.TrailingAction should only be visible on regular viewports.
 // So they come as hidden on narrow viewports by default and their visibility can be managed by their `hidden` prop.

packages/react/src/PageLayout/PageLayout.tsx

@@ -178,7 +178,7 @@ const HorizontalDivider = memo<React.PropsWithChildren<DividerProps>>(
  },
 )
 
-HorizontalDivider.displayName = 'HorizontalDivider'
+HorizontalDivider.displayName = 'PageLayout.HorizontalDivider'
 
 type VerticalDividerProps = DividerProps & {
  draggable?: boolean
@@ -200,7 +200,7 @@ const VerticalDivider = memo<React.PropsWithChildren<VerticalDividerProps>>(
  },
 )
 
-VerticalDivider.displayName = 'VerticalDivider'
+VerticalDivider.displayName = 'PageLayout.VerticalDivider'
 
 type SidebarDividerProps = {
  position: 'start' | 'end'

packages/react/src/Pagehead/Pagehead.tsx

@@ -12,4 +12,5 @@ const Pagehead = ({as: BaseComponent = 'div', className, ...rest}: PageheadProps
 export type PageheadProps = React.ComponentPropsWithoutRef<'div'> & {
  as?: React.ElementType
 }
+
 export default Pagehead

packages/react/src/SegmentedControl/SegmentedControlButton.tsx

@@ -76,4 +76,5 @@ const SegmentedControlButton: FCWithSlotMarker<React.PropsWithChildren<Segmented
 
 export default SegmentedControlButton
 
+SegmentedControlButton.displayName = 'SegmentedControl.Button'
 SegmentedControlButton.__SLOT__ = Symbol('SegmentedControl.Button')

packages/react/src/SegmentedControl/SegmentedControlIconButton.tsx

@@ -64,6 +64,7 @@ export const SegmentedControlIconButton: FCWithSlotMarker<React.PropsWithChildre
  )
 }
 
+SegmentedControlIconButton.displayName = 'SegmentedControl.IconButton'
 SegmentedControlIconButton.__SLOT__ = Symbol('SegmentedControl.IconButton')
 
 export default SegmentedControlIconButton

packages/react/src/SelectPanel/SelectPanel.tsx

@@ -1079,6 +1079,8 @@ const SecondaryLink: React.FC<LinkButtonProps & ButtonProps> = props => {
  )
 }
 
+Panel.displayName = 'SelectPanel'
+
 export const SelectPanel = Object.assign(Panel, {
  __SLOT__: Symbol('SelectPanel'),
  SecondaryActionButton: SecondaryButton,

packages/react/src/SelectPanel/SelectPanelMessage.tsx

@@ -59,3 +59,5 @@ export const SelectPanelMessage: React.FC<SelectPanelMessageProps> = ({
  </div>
  )
 }
+
+SelectPanelMessage.displayName = 'SelectPanel.Message'

packages/react/src/Stack/Stack.tsx

@@ -157,3 +157,4 @@ const StackItem = forwardRef(({as: Component = 'div', children, grow, shrink, cl
 
 export {Stack, StackItem}
 export type {StackProps, StackItemProps}
+StackItem.displayName = 'Stack.Item'

packages/react/src/Timeline/Timeline.tsx

@@ -82,7 +82,7 @@ const TimelineItem = React.forwardRef<HTMLDivElement | HTMLLIElement, TimelineIt
  },
 )
 
-TimelineItem.displayName = 'TimelineItem'
+TimelineItem.displayName = 'Timeline.Item'
 
 export type TimelineBadgeVariant = (typeof TimelineBadgeVariants)[number]
 
@@ -112,7 +112,7 @@ const TimelineBody = React.forwardRef<HTMLDivElement, TimelineBodyProps>(({class
  return <div {...props} className={clsx(className, classes.TimelineBody)} ref={forwardRef} />
 })
 
-TimelineBody.displayName = 'TimelineBody'
+TimelineBody.displayName = 'Timeline.Body'
 
 export type TimelineBreakProps = {
  /** Class name for custom styling */
@@ -144,7 +144,7 @@ const TimelineBreak = React.forwardRef<HTMLDivElement | HTMLLIElement, TimelineB
  },
 )
 
-TimelineBreak.displayName = 'TimelineBreak'
+TimelineBreak.displayName = 'Timeline.Break'
 
 export type TimelineActionsProps = {
  /** Class name for custom styling */

packages/react/src/TooltipV2/Tooltip.tsx

@@ -409,4 +409,5 @@ export const Tooltip: ForwardRefExoticComponent<
  },
 )
 
+Tooltip.displayName = 'Tooltip'
 Tooltip.__SLOT__ = Symbol('Tooltip')

packages/react/src/TopicTag/TopicTagGroup.tsx

@@ -14,3 +14,5 @@ function TopicTagGroup({children, className, ...rest}: TopicTagGroupProps) {
 
 export {TopicTagGroup}
 export type {TopicTagGroupProps}
+
+TopicTagGroup.displayName = 'TopicTag.Group'