chore(website): fixes three documentation issues (#1303)

* chore: remove maintainers private link

* chore: misc fixes

* chore: pr feedback

README.md

@@ -47,10 +47,6 @@ Follow the prompts shown to you in your terminal.
 
 Instructions on how to use the cli tool can be found [here](https://github.com/atlassian/changesets/blob/master/packages/cli/README.md), but all you should need to do is generate a changeset and commit it with your Pull Request.
 
-### Maintainers
-
-This project is maintained by the [design systems team](https://github.com/orgs/twilio-labs/teams/design-systems).
-
 ### Hosted Storybook
 
 [Storybook](https://main--5e53448165911c0022e68c74.chromatic.com)

packages/paste-website/src/component-examples/TooltipExamples.ts

@@ -23,3 +23,23 @@ render(
   <StateHookExample />
 )
 `.trim();
+
+export const NonPasteChildComponentExample = `
+const FancyButton = React.forwardRef((props, ref) => (
+  <button ref={ref} {...props} style={{backgroundColor: 'white', border: '1px solid #000', color: '#000', borderRadius: '5px', padding: '5px'}}>
+    Fancy button: {props.children}
+  </button>
+));
+
+const NonPasteChildComponent = () => {
+  return (
+    <Tooltip text="Forwarding refs correctly!">
+      <FancyButton>Fancy!</FancyButton>
+    </Tooltip>
+  );
+};
+
+render(
+  <NonPasteChildComponent />
+)
+`.trim();

packages/paste-website/src/pages/components/popover/index.mdx

@@ -81,15 +81,17 @@ above your UI.
 
 ### Popover compared to Tooltip
 
-<AspectRatio ratio="16:9">
-  <iframe
-    src="https://www.loom.com/embed/f70204bd8a4f4f21a5b1ded17f4559d1"
-    frameborder="0"
-    webkitallowfullscreen="true"
-    mozallowfullscreen="true"
-    allowfullscreen={true}
-  ></iframe>
-</AspectRatio>
+<Box marginBottom="space70">
+  <AspectRatio ratio="16:9">
+    <iframe
+      src="https://www.loom.com/embed/f70204bd8a4f4f21a5b1ded17f4559d1"
+      frameborder="0"
+      webkitallowfullscreen="true"
+      mozallowfullscreen="true"
+      allowfullscreen={true}
+    ></iframe>
+  </AspectRatio>
+</Box>
 
 ### Accessibility
 

packages/paste-website/src/pages/components/tooltip/index.mdx

@@ -17,7 +17,7 @@ import Changelog from '@twilio-paste/tooltip/CHANGELOG.md';
 import {useTooltipState, Tooltip} from '@twilio-paste/tooltip';
 import {Callout, CalloutTitle, CalloutText} from '../../../components/callout';
 import {SidebarCategoryRoutes} from '../../../constants';
-import {StateHookTabsExample} from '../../../component-examples/TooltipExamples';
+import {StateHookTabsExample, NonPasteChildComponentExample} from '../../../component-examples/TooltipExamples';
 
 export const pageQuery = graphql`
   {
@@ -82,22 +82,28 @@ the keyboard or on mouse hover. Tooltip follows the
 
 ### Tooltip compared to Popover
 
-<AspectRatio ratio="16:9">
-  <iframe
-    src="https://www.loom.com/embed/f70204bd8a4f4f21a5b1ded17f4559d1"
-    frameborder="0"
-    webkitallowfullscreen="true"
-    mozallowfullscreen="true"
-    allowfullscreen={true}
-  ></iframe>
-</AspectRatio>
+<Box marginBottom="space70">
+  <AspectRatio ratio="16:9">
+    <iframe
+      src="https://www.loom.com/embed/f70204bd8a4f4f21a5b1ded17f4559d1"
+      frameborder="0"
+      webkitallowfullscreen="true"
+      mozallowfullscreen="true"
+      allowfullscreen={true}
+    ></iframe>
+  </AspectRatio>
+</Box>
 
-#### Accessibility
+### Accessibility
 
 A tooltip **must only** be placed on a **natively focusable** HTML element. Good candidates include a [Paste Button](/components/button) or a [Paste Anchor](/components/anchor) if the tip also links to a help article.
 
 **Do not** place tooltips on non-focusable elements, like an icon.
 
+If your tooltip wraps a natively focusable HTML element that includes only an icon, make sure you set the prop `decorative={false}`, and
+give the icon a title. The title of the icon should be the accessible name for the button action, like "Delete phone number". The tooltip provides the additional context, like "You can delete phone numbers every 7 days".
+This ensures the icon and tooltip are accessible to screen readers. Refer to the [focusable element example](#focusable-element) for implementation.
+
 ## Examples
 
 ### Basic Tooltip
@@ -155,19 +161,24 @@ A tooltip **must** be placed on a **focusable** element, such as an anchor or bu
 </Box>`}
 </LivePreview>
 
-<Callout>
-  <CalloutTitle>Icons and tooltips</CalloutTitle>
-  <CalloutText>
-    If your tooltip wraps an element that includes only an icon, make sure you set the `decorative` prop to false, and
-    give the icon a title. The title of the icon should describe what the icon is representing, and the tooltip
-    describes what that means. This ensures the icon and tooltip ara accessible to screen readers.
-  </CalloutText>
-</Callout>
+### Tooltips require their children to forwardRefs
+
+If you want to add a Tooltip around a React component, you must make sure that component [forwards refs](https://reactjs.org/docs/forwarding-refs.html). All Paste components do this by default, so this is only a concern when placing Tooltips around other types of components.
+
+<LivePreview
+  scope={{
+    Tooltip,
+  }}
+  noInline
+  language="jsx"
+>
+  {NonPasteChildComponentExample}
+</LivePreview>
 
 ### Using state hooks
 
 <Callout variant="warning">
-  <CalloutTitle>🚨Power user move!🚨</CalloutTitle>
+  <CalloutTitle>🚨 Power user move! 🚨</CalloutTitle>
   <CalloutText>
     Only use this property if you are a power user. It's very easy to break your implementation and unfortunately the
     Paste team will not be able to debug this for you. Proceed with extreme caution.

packages/paste-website/src/pages/icons/usage-guidelines/index.mdx

@@ -43,9 +43,8 @@ export const pageQuery = graphql`
 
 <Callout>
   <CalloutText>
-      Our icon set is still limited, and more will be added over time. Please <Anchor href="https://github.com/twilio-labs/paste/issues">
-      file an icon request
-    </Anchor> or follow the guide on <SiteLink to="/icons/how-to-add-an-icon">how to add an icon</SiteLink>.
+    Can't find the icon you need? Check <Anchor href="https://streamlineicons.com/">Streamline</Anchor> and contribute
+    it to the library following <SiteLink to="/icons/how-to-add-an-icon">our guidelines.</SiteLink>
   </CalloutText>
 </Callout>
 
@@ -71,13 +70,13 @@ A title is required so assistive technology can infer equal meaning as a sighted
 
 <DoDont>
   <Do title="Do" body="Use title text that gives context and meaning to the icon." center>
-    <PlusIcon decorative={false} title="Add to cart" />
+    <PlusIcon decorative={false} title="Add to cart" /> (Title: "Add to cart")
     <Box position="absolute" right={0} bottom={0}>
       (Hover over icon for tooltip)
     </Box>
   </Do>
   <Dont title="Avoid" body="Avoid title text that only describes the icon image." center>
-    <PlusIcon decorative={false} title="Plus" />
+    <PlusIcon decorative={false} title="Plus" /> (Title: "Plus")
     <Box position="absolute" right={0} bottom={0}>
       (Hover over icon for tooltip)
     </Box>