Primer API Review

[github-actions]

Summary

Review date: 2026-09-10. This run is a partial audit: 32 of 80 components (78 inventoried directories plus the publicly-exported SideNav/VisuallyHidden, which are missing from the inventory file) are now fully reviewed against all 21 style-guide principles — 20 carried forward unchanged from the prior run, plus 12 newly reviewed this run (Details, Dialog, FeatureFlags, Flash, FormControl via component-api-auditor; Header, Heading, Hidden, InlineMessage, KeybindingHint via a second component-api-auditor batch; SideNav and VisuallyHidden via direct inspection).

Proposed API changes

• Dialog.onClose uses a bare positional string instead of an extensible object (finding)
• Dialog has no rest-parameter pass-through to its root element (finding)
• Dialog's inline style merge places consumer style before the component-owned --dialog-width CSS variable, inverting the documented merge order (finding)
• Dialog's footer-button auto-focus runs in an effect/state-ratchet instead of an event handler (finding)
• useDetails returns a ref for the caller to apply instead of only accepting one (finding)
• useDetails's onClickOutside callback sits directly in an effect dependency array instead of a stabilized ref (finding)
• FormControl has no rest-parameter pass-through to its root element (finding)
• FormControlLabel.visuallyHidden is a part-visibility toggle that doesn't follow hide/show naming (finding)
• Header/Header.Item/Header.Link spread rest props before the hard-coded data-component, letting a consumer-supplied data-component silently win (finding)
• Heading.variant communicates typographic scale (appearance), not semantic purpose (finding)
• Hidden has no rest-parameter pass-through to its root element (finding)
• InlineMessage spreads rest props before its own data-size/data-variant/data-component, letting a consumer override them silently (finding)
• KeybindingHint has no rest-parameter pass-through to its root element (finding)
• KeybindingHint.size uses 'normal' instead of the guide's standard 'medium' scale name (finding)
• SideNav.variant (lightweight/normal) communicates padding/border density (appearance), not purpose (finding)
• Breadcrumbs root has no rest/passthrough props (finding)
• Breadcrumbs.Item selected uses an inert bare string class instead of data-selected (finding)
• Breadcrumbs variant="spacious" communicates padding/density, not purpose (finding)
• Button/ButtonBase variant mixes appearance names (invisible, link) with semantic ones (primary, danger) (finding)
• ButtonBase drops the consumer's onClick entirely while loading is true, instead of merging (finding)
• ButtonGroup silently discards a consumer-forwarded data-component via rest-spread ordering (finding)
• Card computes aria-labelledby via direct mutation of rest instead of intentional merge precedence (finding)
• Checkbox forwards checked/defaultChecked to the native <input> without useControllableState (finding)
• Checkbox.onChange still fires when a group-level onChange calls preventDefault() (finding)
• CheckboxGroup.onChange uses two positional args instead of one extensible object (finding)
• CheckboxGroup skips its internal selection-state update entirely when no onChange is provided (finding)
• CircleBadge.variant duplicates size's scale/appearance role (finding)
• CircleBadge silently overwrites consumer-supplied style instead of merging it (finding)
• ConfirmationDialog accepts no rest params to forward to its underlying Dialog root (finding)
• ConfirmationDialog.onClose uses a bare positional string instead of an extensible object (finding)
• CounterLabel's deprecated scheme prop still duplicates variant as two mode props for one concept (finding)
• DataTable.onToggleSort uses two positional args instead of one extensible object (finding)
• DataTable.Title/DataTable.Subtitle type as accepting full HTMLAttributes but silently drop unrecognized attributes at runtime (finding)
• Pagination.onPageChange uses bare positional args instead of an extensible object (finding)
• PageLayout DragHandle.onDrag uses bare positional args instead of an extensible object (finding)
• ActionBar root has no rest/passthrough props (finding)
• AvatarStack root has no rest/passthrough props (finding)
• Blankslate applies rest params to the wrong element (finding)
• ActionMenu.onOpenChange uses a bare positional boolean (finding)
• AnchoredOverlay onOpen/onClose use multiple/bare positional arguments (finding)
• ActionMenu open/onOpenChange use useProvidedStateOrCreate instead of useControllableState (finding)
• Autocomplete syncs controlled value via an effect instead of useControllableState (finding)
• ActionList List.variant communicates layout/appearance, not purpose (finding)
• ActionList.Item size scale omits small (finding)
• AvatarStack.variant (cascade/stack) communicates appearance, not purpose (finding)
• ActionList.disableFocusZone is a negated, verb-prefixed boolean (finding)
• AnchoredOverlay.displayCloseButton should follow durable-default/hide-show naming (finding)
• AvatarStack.disableExpand mirrors the guide's explicit anti-pattern (finding)
• Autocomplete restores selection range in an effect rather than the triggering handler (finding)

Run details and coverage

Component counts for this run's newly-reviewed set (12 directories; all 21 principles inspected):

Component	pass	finding	not-applicable
Details (+useDetails)	15	2	4
Dialog	13	4	4
FeatureFlags	4	0	17
Flash	8	0	13
FormControl	13	2	6
Header	15	1	5
Heading	13	2	6
Hidden	12	1	8
InlineMessage	15	1	5
KeybindingHint	14	2	5
SideNav (direct inspection; publicly exported, missing from inventory file)	15	2	4
VisuallyHidden (direct inspection; publicly exported, missing from inventory file)	21	0	0
Breadcrumbs, Button (+ButtonBase), ButtonGroup, Card, Checkbox, CheckboxGroup, CircleBadge, ConfirmationDialog, CounterLabel, DataTable, ActionBar, ActionList, ActionMenu, AnchoredOverlay, Autocomplete, Avatar, AvatarStack, Banner, Blankslate, BranchName	carried forward unchanged from prior run (full 21-principle coverage, not rechecked against current source this run)

Evidence sources this run: (1) component-api-auditor sub-agent, batch 1 (Details, Dialog, FeatureFlags, Flash, FormControl) — returned a full 21-principle matrix per component with file:line evidence; spot-checked directly against Dialog.tsx, useDetails.tsx, and FormControlLabel.tsx source and confirmed; (2) component-api-auditor sub-agent, batch 2 (Header, Heading, Hidden, InlineMessage, KeybindingHint) — returned a full matrix per component; spot-checked directly against Header.tsx, Heading.tsx, and InlineMessage.tsx source and confirmed; (3) direct inspection for SideNav and VisuallyHidden, publicly exported from packages/react/src/index.ts but absent from /tmp/gh-aw/data/components.json.

Workflow run: §34501498984

Remaining coverage

Prioritized next bounded batches (5 components each), carried forward from the prior run's list (adjusted to remove now-reviewed components):

1. Label, LabelGroup, Link, NavList, Octicon
2. Overlay, PageHeader, PageLayout, Pagehead, Pagination
3. Popover, Portal, ProgressBar, Radio, RadioGroup
4. RelativeTime, SegmentedControl, Select, SelectPanel, Skeleton
5. SkeletonAvatar, SkeletonText, Spinner, SplitPageLayout, Stack
6. StateLabel, SubNav, TabNav, Text, TextInput
7. TextInputWithTokens, Textarea, Timeline, ToggleSwitch, Token
8. Tooltip, TooltipV2, TopicTag, TreeView, Truncate
9. UnderlineNav, deprecated/DialogV1, deprecated/FilteredSearch, deprecated/UnderlineNav, experimental/IssueLabel
10. experimental/SelectPanel2, experimental/UnderlinePanels, live-region

Note: PageLayout's DragHandle finding is retained from the prior run; batch 2 above should re-verify the rest of PageLayout, Pagehead, and Pagination (currently only Pagination.onPageChange and the DragHandle finding have been checked) against the full 21-principle checklist.

Past findings not rechecked

The following components were carried forward unchanged from the prior run without re-inspection this run: Breadcrumbs, Button (+ButtonBase), ButtonGroup, Card, Checkbox, CheckboxGroup, CircleBadge, ConfirmationDialog, CounterLabel, DataTable, ActionBar, ActionList, ActionMenu, AnchoredOverlay, Autocomplete, Avatar, AvatarStack, Banner, Blankslate, BranchName. Their findings remain listed in "Proposed API changes" above and their evidence is preserved in each component's managed comment.

No new deviations beyond those listed above were found in the 12 components newly reviewed this run. The remaining 48 directories have not been reviewed against the full checklist this run and should not be assumed to pass.

[github-actions]

Breadcrumbs

Prefer applying component rest parameters to the root element rendered by a component (contributor-docs/style.md)

Evidence	Impact	Recommendation
packages/react/src/Breadcrumbs/Breadcrumbs.tsx:16-35 (BreadcrumbsProps has no rest/spread type), :349-360 (root <nav> receives only explicitly named props)	Consumers cannot pass data-testid, id, or other native attributes to the Breadcrumbs root <nav> without an extra wrapper element.	Extend BreadcrumbsProps with React.ComponentPropsWithoutRef<'nav'> and spread {...rest} onto the <nav> at line 350.

Prefer using data-* attributes for states or modifiers instead of CSS class names (contributor-docs/style.md)

Evidence	Impact	Recommendation
packages/react/src/Breadcrumbs/Breadcrumbs.tsx:392 (clsx(className, classes.Item, selected && 'selected')) — no .selected rule exists in Breadcrumbs.module.css	The selected prop's class hook is inert/misleading; only aria-current="page" (line 393) currently drives any behavior, so the class serves no purpose and could mislead future maintainers into believing it affects styling.	Replace selected && 'selected' with `data-selected={selected

Avoid using the variant prop to communicate appearance (component-prop-naming.md)

Evidence	Impact	Recommendation
packages/react/src/Breadcrumbs/Breadcrumbs.tsx:30-34 (doc comment: "increased padding and a more relaxed layout"), CSS at Breadcrumbs.module.css:70-110 (data-variant='normal'/'spacious' blocks control padding/sizing)	variant="spacious" communicates a padding/density/appearance change rather than a semantic purpose. Consumers must guess what "spacious" affects without inspecting CSS, and the name blocks adding a real semantic variant later.	Rename the prop to density?: 'normal' | 'spacious', keeping the same values, freeing variant for future semantic use.

Past findings not rechecked

None — this is the first review of Breadcrumbs.

[github-actions]

Details

useDetails returns a ref instead of only accepting one

Evidence	Impact	Recommendation
hooks/useDetails.tsx:4,12,46-48 — getDetailsProps() returns ref: customRef; hook creates its own backupRef when none passed. Violates hooks accept a ref instead of returning one	Consumers composing multiple ref-based hooks must manually merge the returned ref.	Require callers to always pass ref; stop returning ref from getDetailsProps().

onClickOutside sits in an effect dependency array

Evidence	Impact	Recommendation
hooks/useDetails.tsx:14-27,30-38 — onClickOutsideInternal depends on onClickOutside identity; effect re-subscribes on every change. Violates stable callbacks from hook args	Inline callbacks cause listener churn.	Store onClickOutside in a ref updated via effect; drop it from the dependency array.

[github-actions]

Dialog

onClose uses a bare positional argument

Evidence	Impact	Recommendation
Dialog/Dialog.tsx:114 — onClose: (gesture: 'close-button' | 'escape') => void. Violates extensible callback args	Adding data to the close event requires a breaking change.	Change to onClose: (event: {gesture: 'close-button' | 'escape'}) => void.

No rest-parameter pass-through to the root element

Evidence	Impact	Recommendation
Dialog/Dialog.tsx:64-174 (DialogProps has no rest signature), :415-430 (root <div> gets only named props). Violates rest params to root element	Consumers can't pass data-testid/aria-*/handlers to the dialog element.	Extend DialogProps with React.ComponentPropsWithoutRef<'div'> and spread onto root at :415.

Inline style merge order is inverted

Evidence	Impact	Recommendation
Dialog/Dialog.tsx:425-428 — consumer style spread before component's --dialog-width var. Violates merge shared props (component styles first, consumer second)	A consumer --dialog-width silently wins.	Apply component style object first, then spread consumer style.

Footer-button auto-focus runs in an effect

Evidence	Impact	Recommendation
Dialog/Dialog.tsx:445-461 — Buttons focuses default button in a useEffect gated by a hasRendered ratchet. Violates focus via handlers not effects	Focus moves as a render side effect, not a gesture.	Trigger auto-focus at the mount/ref-callback path instead of an effect keyed on render-count state.

[github-actions]

FormControl

No rest-parameter pass-through to the root element

Evidence	Impact	Recommendation
FormControl/FormControl.tsx:24-44 (only className/style forwarded), :183,196 (root <div>s). Violates rest params to root	Consumers can't pass data-testid/aria-* to the root.	Extend FormControlProps with a scoped React.ComponentPropsWithoutRef<'div'> and spread onto root at lines 183/196.

FormControlLabel.visuallyHidden doesn't follow hide/show naming

Evidence	Impact	Recommendation
FormControl/FormControlLabel.tsx:10 — visuallyHidden?: boolean toggles a named part with a stable default. Violates use hide/show for visibility props	Name doesn't clearly communicate the requested action.	Rename visuallyHidden to hideLabel.

[github-actions]

Header

Rest props spread before the hard-coded data-component

Evidence	Impact	Recommendation
Header/Header.tsx:16,34,52 — {...rest} spread before literal data-component; no Omit carve-out in props (:7-9). Violates merge shared props ("if an attribute must be controlled by the component, do not expose it as a prop")	A consumer-supplied data-component silently overrides Header's own attribute.	Move data-component after the rest spread, or Omit<'data-component'> from the exposed prop types.

[github-actions]

Heading

variant communicates typographic scale, not purpose

Evidence	Impact	Recommendation
Heading/Heading.tsx:13 — variant?: 'large' | 'medium' | 'small' maps to font-size shorthand (Heading.module.css:6-14), matching the guide's explicit "Avoid" example. Violates avoid variant for appearance	variant here describes scale, not semantic purpose.	Rename variant to size (size?: 'small' | 'medium' | 'large', default medium). Breaking rename.

[github-actions]

Hidden

No rest-parameter pass-through to the root element

Evidence	Impact	Recommendation
Hidden/Hidden.tsx:8-13 (only className/style declared), :37,42-50 (root forwards only those). Violates rest params to root	Consumers can't attach data-testid/aria-*/handlers, unlike sibling components.	Extend HiddenProps with React.ComponentPropsWithoutRef<'div'> and spread ...rest onto root.

[github-actions]

InlineMessage

Rest props spread before component-owned data-* attributes

Evidence	Impact	Recommendation
InlineMessage/InlineMessage.tsx:64-69 — {...rest} spread before data-size/data-variant/data-component; type (:8-23) doesn't Omit them. Violates merge shared props	A consumer-supplied data-size/data-variant/data-component is silently overridden with no type-level signal.	Omit these attributes from the public InlineMessageProps type.

[github-actions]

KeybindingHint

No rest-parameter pass-through to the root element

Evidence	Impact	Recommendation
KeybindingHint/props.ts:5-38 (forwards only className), KeybindingHint.tsx:15,27 (no rest spread). Violates rest params to root	Consumers can't pass aria-*/id/handlers.	Extend KeybindingHintProps with React.ComponentPropsWithoutRef<'kbd'> and spread ...rest onto root.

size uses 'normal' instead of 'medium'

Evidence	Impact	Recommendation
KeybindingHint/props.ts:30-33 — size?: 'small' | 'normal'. Violates prefer small/medium/large	Non-standard scale naming.	Rename 'normal' to 'medium' in props.ts:33 and consumers (components/Chord.tsx:9,16).

[github-actions]

SideNav

variant communicates padding/border density, not purpose

Evidence	Impact	Recommendation
SideNav.tsx:11,26-36 — variant?: 'lightweight' | 'normal' only changes padding/border spacing (SideNav.module.css:32,86). Violates avoid variant for appearance	variant describes visual density, not purpose.	Rename to density?: 'compact' | 'default'.

No rest-parameter pass-through to the root element

Evidence	Impact	Recommendation
SideNav.tsx:9-16,38-42 — SideNavBaseProps has no rest signature; root receives no spread. Violates rest params to root	Consumers can't pass data-testid/aria-*/handlers.	Extend with React.ComponentPropsWithoutRef<'nav'> and spread ...rest. Note: SideNav is @deprecated in favor of NavList.