From c428918c1c52a291d6f9ea0a18b209abc2179554 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 12:52:14 -0500
Subject: [PATCH 1/2] Add size prop naming guidelines

Closes github/primer#6732

This PR updates our component prop naming guidance with the canonical size prop conventions from the API audit.

### Changelog

#### New

- Add guidance for named and numeric size props.

#### Changed

- Document small, medium, and large as our standard named scale, with medium as the default.

#### Removed

- None.

### Rollout strategy

- [ ] Patch release
- [ ] Minor release
- [ ] Major release; if selected, include a written rollout or migration plan
- [x] None; this updates internal skill documentation and has no public-facing impact.

### Testing & Reviewing

Review the guidance against the component size audit in github/primer#6732.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 340f1c08-6adb-4055-a220-52a750204d3b
---
 .../style-guide/docs/component-prop-naming.md | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/.github/skills/style-guide/docs/component-prop-naming.md b/.github/skills/style-guide/docs/component-prop-naming.md
index 4949da3fecd..1b18fac037d 100644
--- a/.github/skills/style-guide/docs/component-prop-naming.md
+++ b/.github/skills/style-guide/docs/component-prop-naming.md
@@ -16,6 +16,9 @@ Use these conventions when creating, editing, or evaluating props for Primer Rea
   - [Use a single mode prop instead of mutually exclusive boolean props](#use-a-single-mode-prop-instead-of-mutually-exclusive-boolean-props)
 - [Use the variant prop to communicate purpose](#use-the-variant-prop-to-communicate-purpose)
 - [Avoid using the variant prop to communicate appearance](#avoid-using-the-variant-prop-to-communicate-appearance)
+- [Use the size prop to communicate scale](#use-the-size-prop-to-communicate-scale)
+  - [Prefer small, medium, and large](#prefer-small-medium-and-large)
+  - [Use numeric sizes when precise dimensions are part of the API](#use-numeric-sizes-when-precise-dimensions-are-part-of-the-api)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
@@ -207,3 +210,43 @@ type ExampleAppearanceProps = {
   shape?: 'square' | 'rounded'
 }
 ```
+
+## Use the size prop to communicate scale
+
+Use a `size` prop when a component offers multiple visual scales. Do not use
+`variant` to represent size because `variant` communicates semantic purpose.
+
+### Prefer small, medium, and large
+
+Use `small`, `medium`, and `large` as the standard named size values, with
+`medium` as the default. Components do not need to support every value when a
+size is not meaningful for their design.
+
+```tsx
+// Prefer
+type ExampleProps = {
+  size?: 'small' | 'medium' | 'large'
+}
+
+// Avoid
+type ExampleProps = {
+  size?: 'small' | 'normal' | 'large' | 'xlarge'
+}
+```
+
+Only introduce an additional size name when the standard scale cannot describe
+a distinct, supported use case. Keep shared size names visually compatible when
+components are designed to be used together.
+
+### Use numeric sizes when precise dimensions are part of the API
+
+Numeric sizes are appropriate when consumers need precise dimensions, such as
+for avatars or icons. Prefer named sizes for components that are expected to
+align with other controls without requiring consumers to coordinate pixel
+values.
+
+```tsx
+type AvatarProps = {
+  size?: number | ResponsiveValue<number>
+}
+```

From e38c93038c1e3257e409197bf58270f6b979ff38 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 12:56:21 -0500
Subject: [PATCH 2/2] docs: update style guide with size naming docs

---
 .github/skills/style-guide/docs/component-prop-naming.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/.github/skills/style-guide/docs/component-prop-naming.md b/.github/skills/style-guide/docs/component-prop-naming.md
index 1b18fac037d..016fc5aa9d3 100644
--- a/.github/skills/style-guide/docs/component-prop-naming.md
+++ b/.github/skills/style-guide/docs/component-prop-naming.md
@@ -19,6 +19,7 @@ Use these conventions when creating, editing, or evaluating props for Primer Rea
 - [Use the size prop to communicate scale](#use-the-size-prop-to-communicate-scale)
   - [Prefer small, medium, and large](#prefer-small-medium-and-large)
   - [Use numeric sizes when precise dimensions are part of the API](#use-numeric-sizes-when-precise-dimensions-are-part-of-the-api)
+  - [Extend the scale with `xsmall` and `xlarge` when needed](#extend-the-scale-with-xsmall-and-xlarge-when-needed)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
@@ -230,7 +231,7 @@ type ExampleProps = {
 
 // Avoid
 type ExampleProps = {
-  size?: 'small' | 'normal' | 'large' | 'xlarge'
+  size?: 'small' | 'normal' | 'extra-large'
 }
 ```
 
@@ -250,3 +251,9 @@ type AvatarProps = {
   size?: number | ResponsiveValue<number>
 }
 ```
+
+### Extend the scale with `xsmall` and `xlarge` when needed
+
+When a component needs to support a size smaller than `small` or larger than
+`large`, use `xsmall` and `xlarge` to extend the scale. Avoid introducing
+additional size names unless they are necessary for a distinct use case.