docs: update component prop naming with variant docs

.github/skills/style-guide/docs/component-prop-naming.md

@@ -14,6 +14,8 @@ Use these conventions when creating, editing, or evaluating props for Primer Rea
   - [Use `hide` or `show` for visibility-related props](#use-hide-or-show-for-visibility-related-props)
   - [Prefer named modes for behavior with multiple options](#prefer-named-modes-for-behavior-with-multiple-options)
   - [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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
@@ -141,3 +143,67 @@ type ExampleProps = {
   selectionVariant?: 'single' | 'multiple'
 }
 ```
+
+## Use the variant prop to communicate purpose
+
+The variant prop is used when a component has multiple semantic variants that
+are mutually exclusive. It is used to indicate which variant to use for a
+component. When naming variants for a component, each variant should be a
+semantic description of the variant's purpose rather than its appearance.
+
+For example, consider a `Banner` component. This component is used to
+communicate information to the user. The `variant` prop could be used to
+indicate the purpose of the information within the banner. For example:
+
+```tsx
+// Prefer
+type BannerProps = {
+  variant?: 'info' | 'warning' | 'error' | 'success'
+}
+
+// Avoid
+type BannerProps = {
+  variant?: 'blue' | 'yellow' | 'red' | 'green'
+}
+```
+
+It's important the `variant` is semantic and communicates the purpose of the
+component rather than its appearance. This allows for more flexibility in the
+future if the appearance of the component changes.
+
+## Avoid using the variant prop to communicate appearance
+
+The variant prop is exclusively meant to communicate the purpose of a component.
+It must not be used to communicate the appearance of a component. For example:
+
+```tsx
+// Avoid
+type ExampleSizeProps = {
+  variant?: 'large' | 'medium' | 'small'
+}
+
+// Prefer
+type ExampleSizeProps = {
+  size?: 'large' | 'medium' | 'small'
+}
+
+// Avoid
+type ExamplePaddingProps = {
+  variant?: 'inset' | 'flush'
+}
+
+// Prefer
+type ExamplePaddingProps = {
+  padding?: 'inset' | 'flush'
+}
+
+// Avoid
+type ExampleAppearanceProps = {
+  variant?: 'square' | 'rounded'
+}
+
+// Prefer
+type ExampleAppearanceProps = {
+  shape?: 'square' | 'rounded'
+}
+```