Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/skills/style-guide/docs/component-prop-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ 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)
- [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 -->
Expand Down Expand Up @@ -207,3 +211,49 @@ 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' | 'extra-large'
}
```

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>
}
```

### 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.
Loading