IconCompact: docs

.github/pr-title-checker-config.json

@@ -11,7 +11,7 @@
       "ESLint plugin: ",
       "Tokens: "
     ],
-    "regexp": "^(?=.*(?:Accordion|ActivationCard|Avatar|AvatarGroup|Badge|BannerCallout|BannerOverlay|BannerSlim|BannerUpsell|Box|Button|ButtonGroup|ButtonToggle|ChartGraph|Checkbox|Collage|ColorSchemeProvider|Column|ComboBox|Container|Datapoint|DateRange|DateField|DatePicker|DefaultLabelProvider|DeviceTypeProvider|Divider|Dropdown|GlobalEventsHandlerProvider|Fieldset|Flex|Heading|HelpButton|Icon|IconButton|IconButtonFloating|Image|Label|Layer|Letterbox|Link|List|Mask|Masonry|Modal|ModalAlert|NumberField|OverlayPanel|PageHeader|Pog|Popover|PopoverEducational|Pulsar|RadioButton|RadioGroup|ScrollBoundaryContainer|SearchField|SearchGuide|SegmentedControl|SelectList|Sheet|SheetMobile|SideNavigation|Spinner|Status|Sticky|Switch|Table|TableOfContents|Tabs|Tag|TagData|TapArea|Text|TextCompact|TextUI|TextArea|TextField|TileData|Toast|Tooltip|useFocusVisible|useReducedMotion|Video|WashAnimated|ZIndex-Classes):\\s.*)+",
+    "regexp": "^(?=.*(?:Accordion|ActivationCard|Avatar|AvatarGroup|Badge|BannerCallout|BannerOverlay|BannerSlim|BannerUpsell|Box|Button|ButtonGroup|ButtonToggle|ChartGraph|Checkbox|Collage|ColorSchemeProvider|Column|ComboBox|Container|Datapoint|DateRange|DateField|DatePicker|DefaultLabelProvider|DeviceTypeProvider|Divider|Dropdown|GlobalEventsHandlerProvider|Fieldset|Flex|Heading|HelpButton|Icon|IconButton|IconButtonFloating|IconCompact|Image|Label|Layer|Letterbox|Link|List|Mask|Masonry|Modal|ModalAlert|NumberField|OverlayPanel|PageHeader|Pog|Popover|PopoverEducational|Pulsar|RadioButton|RadioGroup|ScrollBoundaryContainer|SearchField|SearchGuide|SegmentedControl|SelectList|Sheet|SheetMobile|SideNavigation|Spinner|Status|Sticky|Switch|Table|TableOfContents|Tabs|Tag|TagData|TapArea|Text|TextCompact|TextUI|TextArea|TextField|TileData|Toast|Tooltip|useFocusVisible|useReducedMotion|Video|WashAnimated|ZIndex-Classes):\\s.*)+",
     "regexpFlags": "",
     "ignoreLabels": []
   },

docs/docs-components/siteIndex.ts

@@ -149,6 +149,7 @@ const siteIndex: readonly [siteIndexType, ...siteIndexType[]] = [
       'IconButton',
       'IconButtonLink',
       'IconButtonFloating',
+      'IconCompact',
       'Image',
       'Indicator',
       'Label',

docs/examples/iconCompact/builtInIcon.tsx

@@ -0,0 +1,9 @@
+import { Flex, IconCompact } from 'gestalt';
+
+export default function Example() {
+  return (
+    <Flex alignItems="center" height="100%" justifyContent="center" width="100%">
+      <IconCompact accessibilityLabel="Add new Pins" icon="compact-add" />
+    </Flex>
+  );
+}

docs/examples/iconCompact/customIcon.tsx

@@ -0,0 +1,15 @@
+import { Flex, IconCompact } from 'gestalt';
+
+export default function Example() {
+  return (
+    <Flex alignItems="center" height="100%" justifyContent="center" width="100%">
+      <IconCompact
+        accessibilityLabel="Add new Pins"
+        dangerouslySetSvgPath={{
+          __path:
+            'M9.41 1.41a1.41 1.41 0 0 0-2.82 0V6.6H1.4a1.41 1.41 0 1 0 0 2.82h5.2v5.18a1.41 1.41 0 1 0 2.82 0V9.4h5.18a1.41 1.41 0 1 0 0-2.82H9.4z',
+        }}
+      />
+    </Flex>
+  );
+}

docs/examples/iconCompact/main.tsx

@@ -0,0 +1,11 @@
+import { Flex, IconCompact } from 'gestalt';
+
+export default function Example() {
+  return (
+    <Flex alignItems="center" height="100%" justifyContent="center" width="100%">
+      <Flex alignItems="center" gap={2}>
+        <IconCompact accessibilityLabel="Pin" icon="compact-add" />
+      </Flex>
+    </Flex>
+  );
+}

docs/pages/visual-test/IconCompact-list-dark.tsx

@@ -0,0 +1,27 @@
+import { Box, ColorSchemeProvider, Flex, IconCompact, Text } from 'gestalt';
+import icons from 'gestalt/src/icons/compact';
+
+export default function Snapshot() {
+  return (
+    <ColorSchemeProvider colorScheme="dark">
+      <Box color="default" height={2000} width={2000}>
+        <Flex
+          gap={{
+            row: 1,
+            column: 0,
+          }}
+          wrap
+        >
+          {Object.keys(icons).map((name, idk) => (
+            <Box key={name} padding={2} width={100}>
+              <Text size="100">{idk}</Text>
+              {/* @ts-expect-error - TS2322 */}
+              <IconCompact accessibilityLabel="" color="default" icon={name} />
+              <Text size="100">{name}</Text>
+            </Box>
+          ))}
+        </Flex>
+      </Box>
+    </ColorSchemeProvider>
+  );
+}

docs/pages/visual-test/IconCompact-list-vr.tsx

@@ -0,0 +1,27 @@
+import { Box, ColorSchemeProvider, Flex, IconCompact, Text } from 'gestalt';
+import icons from 'gestalt/src/icons-vr-theme/compact';
+
+export default function Snapshot() {
+  return (
+    <ColorSchemeProvider colorScheme="light">
+      <Box color="default" height={2000} width={2000}>
+        <Flex
+          gap={{
+            row: 1,
+            column: 0,
+          }}
+          wrap
+        >
+          {Object.keys(icons).map((name, idk) => (
+            <Box key={name} padding={2} width={100}>
+              <Text size="100">{idk}</Text>
+              {/* @ts-expect-error - TS2322 */}
+              <IconCompact accessibilityLabel="" color="default" icon={name} />
+              <Text size="100">{name}</Text>
+            </Box>
+          ))}
+        </Flex>
+      </Box>
+    </ColorSchemeProvider>
+  );
+}

docs/pages/visual-test/IconCompact-list.tsx

@@ -0,0 +1,27 @@
+import { Box, ColorSchemeProvider, Flex, IconCompact, Text } from 'gestalt';
+import icons from 'gestalt/src/icons/compact';
+
+export default function Snapshot() {
+  return (
+    <ColorSchemeProvider colorScheme="light">
+      <Box color="default" height={2000} width={2000}>
+        <Flex
+          gap={{
+            row: 1,
+            column: 0,
+          }}
+          wrap
+        >
+          {Object.keys(icons).map((name, idk) => (
+            <Box key={name} padding={2} width={100}>
+              <Text size="100">{idk}</Text>
+              {/* @ts-expect-error - TS2322 */}
+              <IconCompact accessibilityLabel="" color="default" icon={name} />
+              <Text size="100">{name}</Text>
+            </Box>
+          ))}
+        </Flex>
+      </Box>
+    </ColorSchemeProvider>
+  );
+}

docs/pages/web/icon.tsx

@@ -10,7 +10,6 @@ import PageHeader from '../../docs-components/PageHeader';
 import QualityChecklist from '../../docs-components/QualityChecklist';
 import SandpackExample from '../../docs-components/SandpackExample';
 import builtInIcon from '../../examples/icon/builtInIcon';
-import compactIcon from '../../examples/icon/compactIcon';
 import customIcon from '../../examples/icon/customIcon';
 import doClarity from '../../examples/icon/doClarity';
 import doIntentional from '../../examples/icon/doIntentional';
@@ -223,20 +222,6 @@ Should be used sparingly and only in places where the UI is very dense and a lar
             title="Custom SVG icon"
           />
         </MainSection.Subsection>
-        <MainSection.Subsection
-          columns={2}
-          description={`Icons are available as part of a Compact Icon set. These icons have a 16x16 viewboxes and are used in places where space is limited. Refer to your designer for guidance on when to use Compact Icons.
-           <br/> They can be used with the \`IconCompact\` component.`}
-          title="Compact icon"
-        >
-          <MainSection.Card
-            cardSize="lg"
-            sandpackExample={
-              <SandpackExample code={compactIcon} name="compact icons" previewHeight={HEIGHT} />
-            }
-            title="Compact Icon"
-          />
-        </MainSection.Subsection>
       </MainSection>
       <MainSection name="Writing">
         <MainSection.Subsection columns={2}>
@@ -266,6 +251,9 @@ Use a descriptive label to describe the Icon
       <MainSection name="Related">
         <MainSection.Subsection
           description={`
+**[IconCompact](/web/iconcompact)**
+Some icons are only available as part of a Compact Icon set. These icons have a 16x16 viewboxes and are used in places where space is limited. Refer to your designer for guidance on when to use Compact Icons.
+
 **[IconButton](/web/iconbutton)**
 Use IconButton when only an icon is needed to represent an action instead of text.
 

docs/pages/web/iconcompact.tsx

@@ -0,0 +1,152 @@
+import { IconCompact } from 'gestalt';
+import AccessibilitySection from '../../docs-components/AccessibilitySection';
+import CombinationNew from '../../docs-components/CombinationNew';
+import docGen, { DocGen, overrideTypes } from '../../docs-components/docgen';
+import GeneratedPropTable from '../../docs-components/GeneratedPropTable';
+import LocalizationSection from '../../docs-components/LocalizationSection';
+import MainSection from '../../docs-components/MainSection';
+import Page from '../../docs-components/Page';
+import PageHeader from '../../docs-components/PageHeader';
+import QualityChecklist from '../../docs-components/QualityChecklist';
+import SandpackExample from '../../docs-components/SandpackExample';
+import builtInIcon from '../../examples/iconCompact/builtInIcon';
+import customIcon from '../../examples/iconCompact/customIcon';
+import main from '../../examples/iconCompact/main';
+
+const HEIGHT = 150;
+
+export default function ComponentPage({ generatedDocGen }: { generatedDocGen: DocGen }) {
+  return (
+    <Page title={generatedDocGen?.displayName}>
+      <PageHeader description={generatedDocGen?.description} name={generatedDocGen?.displayName}>
+        <SandpackExample code={main} hideEditor name="Main example" previewHeight={HEIGHT} />
+      </PageHeader>
+
+      <GeneratedPropTable generatedDocGen={generatedDocGen} />
+
+      <AccessibilitySection
+        description="IconCompacts are a great way to help users who have difficulties with reading, focus attention, and low vision impairments."
+        name={generatedDocGen?.displayName}
+      >
+        <MainSection.Subsection
+          columns={2}
+          description={`
+If the icon appears without text, the IconCompact requires \`accessibilityLabel\`, a text description for screen readers to announce and communicate the represented the icon, as shown in the first example.
+
+Avoid using the generic words like  "image" or "icon"; instead, use verbs that describe the meaning of the icon.
+
+If an icon has a visible label that describes what the icon represents, \`accessibilityLabel\` can be an empty string.
+`}
+          title="ARIA attributes"
+        />
+        <MainSection.Subsection
+          description="Ensure that icons use a contrast ratio of 4.5:1 between icon color and background color."
+          title="Legibility"
+        />
+      </AccessibilitySection>
+
+      <LocalizationSection name={generatedDocGen?.displayName} noDefaultLabelProvider />
+
+      <MainSection name="Variants">
+        <MainSection.Subsection
+          description={`
+        IconCompacts can be created using the following color options. \`brandPrimary\` should only be used to represent the Pinterest logo, as it is not accessible. See the [design tokens](/foundations/design_tokens/overview#Text-color) for more info.`}
+          title="Colors"
+        >
+          <CombinationNew
+            // @ts-expect-error - TS2322 - Type '{ children: ({ color }: { [key: string]: any; }) => Element; color: string[]; }' is not assignable to type 'IntrinsicAttributes & Props'.
+            color={[
+              'default',
+              'disabled',
+              'subtle',
+              'success',
+              'error',
+              'warning',
+              'info',
+              'recommendation',
+              'inverse',
+              'shopping',
+              'brandPrimary',
+              'light',
+              'dark',
+            ]}
+          >
+            {({ color }) => <IconCompact accessibilityLabel="" color={color} icon="compact-add" />}
+          </CombinationNew>
+        </MainSection.Subsection>
+
+        <MainSection.Subsection
+          columns={2}
+          description="IconCompact accepts both Gestalt [icons](/foundations/iconography/library#Search-icon-library) and custom icons, as shown in the second example. For custom icons, follow the [iconography and SVG](/foundations/iconography/library#Custom-SVG-icons) guidelines."
+          title="Custom icon"
+        >
+          <MainSection.Card
+            cardSize="lg"
+            sandpackExample={
+              <SandpackExample code={builtInIcon} name="Built-in icon" previewHeight={HEIGHT} />
+            }
+            title="Built-in icon"
+          />
+          <MainSection.Card
+            cardSize="lg"
+            sandpackExample={
+              <SandpackExample code={customIcon} name="Custom icon" previewHeight={HEIGHT} />
+            }
+            title="Custom SVG icon"
+          />
+        </MainSection.Subsection>
+      </MainSection>
+      <MainSection name="Writing">
+        <MainSection.Subsection columns={2}>
+          <MainSection.Card
+            cardSize="md"
+            description={`
+Use a descriptive label to describe the IconCompact
+- Be succinct. Exclude unnecessary words.
+- Be informative and accurate
+- Write in the active voice
+- Avoid technical jargon
+`}
+            type="do"
+          />
+          <MainSection.Card
+            cardSize="md"
+            description={`
+- Use the words "image" or "icon" in the description label; instead, use words that indicate the purpose of the icon.
+`}
+            type="don't"
+          />
+        </MainSection.Subsection>
+      </MainSection>
+
+      <QualityChecklist component={generatedDocGen?.displayName} />
+
+      <MainSection name="Related">
+        <MainSection.Subsection
+          description={`
+**[IconButton](/web/iconbutton)**
+Use IconButton when only an icon is needed to represent an action instead of text.
+
+**[Button](/web/button)**
+Use Button to allow users to take an action.
+    `}
+        />
+      </MainSection>
+    </Page>
+  );
+}
+
+export async function getServerSideProps(): Promise<{
+  props: {
+    generatedDocGen: DocGen;
+  };
+}> {
+  const generatedDocGen = await docGen('IconCompact');
+  const overriddenDocGen = overrideTypes(generatedDocGen, {
+    icon: (IconCompact?.icons ?? []).map((icon) => `'${icon}'`).join(' | '),
+  });
+
+  return {
+    props: { generatedDocGen: overriddenDocGen },
+  };
+}

packages/gestalt/src/IconCompact.tsx

@@ -63,15 +63,15 @@ type Props = {
 const IconNames: ReadonlyArray<keyof typeof compactIconsVR> = Object.keys(compactIconsVR);
 
 /**
- * [Icons](https://gestalt.pinterest.systems/web/icon) are the symbolic representation of an action or information, providing visual context and improving usability.
+ * [Icons](https://gestalt.pinterest.systems/web/icon) are the symbolic representation of an action or information, providing visual context and improving usability. These icons have a 16x16 viewboxes and are used in places where space is limited. Refer to your designer for guidance on when to use Compact Icons.
+
  *
  * See the [Iconography and SVG guidelines](https://gestalt.pinterest.systems/foundations/iconography/library) to explore the full icon library.
  *
- * ![Icon light mode](https://raw.githubusercontent.com/pinterest/gestalt/master/playwright/visual-test/Icon-list.spec.ts-snapshots/Icon-list-chromium-darwin.png)
- * ![Icon dark mode](https://raw.githubusercontent.com/pinterest/gestalt/master/playwright/visual-test/Icon-list-dark.spec.ts-snapshots/Icon-list-dark-chromium-darwin.png)
+ * ![Icon light mode](https://raw.githubusercontent.com/pinterest/gestalt/master/playwright/visual-test/Icon-list.spec.ts-snapshots/IconCompact-list-chromium-darwin.png)
+ * ![Icon dark mode](https://raw.githubusercontent.com/pinterest/gestalt/master/playwright/visual-test/Icon-list-dark.spec.ts-snapshots/IconCompact-list-dark-chromium-darwin.png)
  *
  */
-
 function IconCompact({
   accessibilityLabel,
   color = 'subtle',

playwright/accessibility/web__iconcompact.spec.ts

@@ -0,0 +1,8 @@
+import { test } from '@playwright/test';
+import expectAccessiblePage from './expectAccessiblePage';
+
+test('IconCompact Accessibility check', async ({ page }) => {
+  await page.goto('/web/iconcompact');
+  // @ts-expect-error - TS2345 - Argument of type '{ page: Page; }' is not assignable to parameter of type '{ page: any; rules: any; }'.
+  await expectAccessiblePage({ page });
+});

playwright/visual-test/IconCompact-list-dark.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from '@playwright/test';
+
+test('IconCompact list dark mode visual regression check', async ({ page }) => {
+  await page.goto('/visual-test/IconCompact-list-dark');
+  const locator = page.locator('[data-test-id="visual-test"]');
+  await expect(locator).toHaveScreenshot('IconCompact-list-dark.png');
+});