Update token components' APIs

.changeset/six-trains-guess.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Updates the API for token components to align with our size-naming ADR, avatar guidelines, and icon guidelines

docs/content/TextInputWithTokens.mdx

@@ -419,8 +419,8 @@ render(<WithIconAndLoadingIndicator />)
   />
   <PropsTableRow
     name="size"
-    type="'small' | 'medium' | 'large' | 'extralarge'"
-    defaultValue="extralarge"
+    type="'small' | 'medium' | 'large' | 'xlarge'"
+    defaultValue="xlarge"
     description="The size of the tokens and text input"
   />
   <PropsTableRow

docs/content/Token.mdx

@@ -55,7 +55,7 @@ All types of tokens may have the same interactive qualities as links or buttons.
     <Text fontSize={0} display="block" color="fg.subtle">
       With `leadingVisual` passed
     </Text>
-    <Token text="Default Token" leadingVisual={() => <span>✨</span>} />
+    <Token text="Default Token" leadingVisual={GitBranchIcon} />
   </div>
 
   <div>
@@ -81,39 +81,37 @@ All types of tokens may have the same interactive qualities as links or buttons.
         gap: 2
       }}
     >
-      <Token
-        size="small"
-        text="'small' Token"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
-      <Token
-        size="medium"
-        text="'medium' Token"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
-      <Token
-        size="large"
-        text="'large' Token (default)"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
-      <Token
-        size="extralarge"
-        text="'extralarge' Token"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
+      <Token size="small" text="'small' Token" />
+      <Token size="medium" text="'medium' Token" />
+      <Token size="large" text="'large' Token (default)" />
+      <Token size="xlarge" text="'xlarge' Token" />
     </Box>
   </div>
 </Box>
 ```
 
+### With leadingVisual
+
+<Note variant="warning">
+  A <InlineCode>leadingVisual</InlineCode> should not be used with the <InlineCode>small</InlineCode> size option if
+  you're rendering an icon from Octicons
+</Note>
+
+```jsx live
+<Box
+  display="flex"
+  sx={{
+    alignItems: 'start',
+    flexDirection: 'column',
+    gap: 6
+  }}
+>
+  <Token size="medium" text="'medium' Token" leadingVisual={GitBranchIcon} />
+  <Token size="large" text="'large' Token (default)" leadingVisual={GitBranchIcon} />
+  <Token size="xlarge" text="'xlarge' Token" leadingVisual={GitBranchIcon} />
+</Box>
+```
+
 ### Interactive tokens
 
 If any token is interactive (it is a link or a button), it will become focusable, and react to being hovered or focused on.
@@ -267,8 +265,8 @@ Tokens that represent Issue labels should use the `IssueLabelToken` component.
       />
       <IssueLabelToken
         fillColor="#0366d6"
-        size="extralarge"
-        text="'extralarge' Token"
+        size="xlarge"
+        text="'xlarge' Token"
         onRemove={() => {
           console.log('remove me')
         }}
@@ -282,6 +280,11 @@ Tokens that represent Issue labels should use the `IssueLabelToken` component.
 
 Tokens that represent GitHub users should use the `AvatarToken` component.
 
+<Note variant="warning">
+  This component should not be used with the <InlineCode>small</InlineCode> or <InlineCode>medium</InlineCode> size
+  option
+</Note>
+
 ```jsx live
 <Box
   display="flex"
@@ -329,22 +332,6 @@ Tokens that represent GitHub users should use the `AvatarToken` component.
         gap: 2
       }}
     >
-      <AvatarToken
-        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
-        size="small"
-        text="'small' Token"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
-      <AvatarToken
-        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
-        size="medium"
-        text="'medium' Token"
-        onRemove={() => {
-          console.log('remove me')
-        }}
-      />
       <AvatarToken
         avatarSrc="https://avatars.githubusercontent.com/mperrotti"
         size="large"
@@ -355,8 +342,8 @@ Tokens that represent GitHub users should use the `AvatarToken` component.
       />
       <AvatarToken
         avatarSrc="https://avatars.githubusercontent.com/mperrotti"
-        size="extralarge"
-        text="'extralarge' Token"
+        size="xlarge"
+        text="'xlarge' Token"
         onRemove={() => {
           console.log('remove me')
         }}

src/TextInputWithTokens.tsx

@@ -59,7 +59,8 @@ const overflowCountFontSizeMap: Record<TokenSizeKeys, number> = {
   small: 0,
   medium: 1,
   large: 1,
-  extralarge: 2
+  extralarge: 2,
+  xlarge: 2 // will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
 }
 
 // using forwardRef is important so that other components (ex. Autocomplete) can use the ref
@@ -239,7 +240,8 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
     small: 'small',
     medium: 'small',
     large: 'medium',
-    extralarge: 'medium'
+    extralarge: 'medium',
+    xlarge: 'medium' // will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
   }
   const showLeadingLoadingIndicator =
     loading && (loaderPosition === 'leading' || Boolean(LeadingVisual && loaderPosition !== 'trailing'))
@@ -370,7 +372,7 @@ const TextInputWithTokens = React.forwardRef(TextInputWithTokensInnerComponent)
 
 TextInputWithTokens.defaultProps = {
   tokenComponent: Token,
-  size: 'extralarge',
+  size: 'xlarge',
   hideTokenRemoveButtons: false,
   preventTokenWrapping: false,
   loaderPosition: 'auto'

src/Token/AvatarToken.tsx

@@ -5,6 +5,7 @@ import {TokenBaseProps, defaultTokenSize, tokenSizes, TokenSizeKeys} from './Tok
 import Token from './Token'
 import {Avatar} from '..'
 
+// TODO: update props to only accept 'large' and 'xlarge' on the next breaking change
 export interface AvatarTokenProps extends TokenBaseProps {
   avatarSrc: string
 }

src/Token/IssueLabelToken.tsx

@@ -11,10 +11,6 @@ export interface IssueLabelTokenProps extends TokenBaseProps {
    * The color that corresponds to the label
    */
   fillColor?: string
-  /**
-   * Whether the remove button should be rendered in the token
-   */
-  hideRemoveButton?: boolean
 }
 
 const tokenBorderWidthPx = 1

src/Token/Token.tsx

@@ -12,10 +12,6 @@ export interface TokenProps extends TokenBaseProps {
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   leadingVisual?: React.ComponentType<any>
-  /**
-   * Whether the remove button should be rendered in the token
-   */
-  hideRemoveButton?: boolean
 }
 
 const tokenBorderWidthPx = 1
@@ -52,6 +48,7 @@ const LeadingVisualContainer = styled('span')<Pick<TokenBaseProps, 'size'>>`
     switch (props.size) {
       case 'large':
       case 'extralarge':
+      case 'xlarge':
         return css`
           margin-right: ${get('space.2')};
         `

src/Token/TokenBase.tsx

@@ -4,13 +4,19 @@ import {variant} from 'styled-system'
 import {get} from '../constants'
 import sx, {SxProp} from '../sx'
 
-export type TokenSizeKeys = 'small' | 'medium' | 'large' | 'extralarge'
+// TODO: remove invalid "extralarge" size name in next breaking change
+/** @deprecated 'extralarge' to be removed to align with size naming ADR https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md **/
+type ExtraLarge = 'extralarge'
+export type TokenSizeKeys = 'small' | 'medium' | 'large' | 'xlarge' | ExtraLarge
+
+const xlargeSize = '32px'
 
 export const tokenSizes: Record<TokenSizeKeys, string> = {
   small: '16px',
   medium: '20px',
   large: '24px',
-  extralarge: '32px'
+  extralarge: xlargeSize,
+  xlarge: xlargeSize
 }
 
 export const defaultTokenSize: TokenSizeKeys = 'medium'
@@ -22,6 +28,10 @@ export interface TokenBaseProps
    * The function that gets called when a user clicks the remove button, or keys "Backspace" or "Delete" when focused on the token
    */
   onRemove?: () => void
+  /**
+   * Whether the remove button should be rendered in the token
+   */
+  hideRemoveButton?: boolean
   /**
    * Whether the token is selected
    */
@@ -43,6 +53,16 @@ export interface TokenBaseProps
 export const isTokenInteractive = ({as = 'span', onClick, onFocus, tabIndex = -1}: TokenBaseProps) =>
   Boolean(onFocus || onClick || tabIndex > -1 || ['a', 'button'].includes(as))
 
+const xlargeVariantStyles = {
+  fontSize: 1,
+  height: tokenSizes.xlarge,
+  lineHeight: tokenSizes.xlarge,
+  paddingLeft: 3,
+  paddingRight: 3,
+  paddingTop: 0,
+  paddingBottom: 0
+}
+
 const variants = variant<
   {
     fontSize: number
@@ -87,15 +107,8 @@ const variants = variant<
       paddingTop: 0,
       paddingBottom: 0
     },
-    extralarge: {
-      fontSize: 1,
-      height: tokenSizes.extralarge,
-      lineHeight: tokenSizes.extralarge,
-      paddingLeft: 3,
-      paddingRight: 3,
-      paddingTop: 0,
-      paddingBottom: 0
-    }
+    extralarge: xlargeVariantStyles,
+    xlarge: xlargeVariantStyles
   }
 })
 

src/Token/_RemoveTokenButton.tsx

@@ -31,6 +31,11 @@ const variants = variant<{height: string; width: string}, TokenSizeKeys>({
     extralarge: {
       height: tokenSizes.extralarge,
       width: tokenSizes.extralarge
+    },
+    // xlarge will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
+    xlarge: {
+      height: tokenSizes.xlarge,
+      width: tokenSizes.xlarge
     }
   }
 })
@@ -58,6 +63,7 @@ const StyledTokenButton = styled.span<TokenButtonProps & SxProp>`
     switch (props.size) {
       case 'large':
       case 'extralarge':
+      case 'xlarge':
         return css`
           margin-left: ${get('space.2')};
         `