@kaizen/components 1.66.0 → 1.67.0

package/src/__future__/Icon/_docs/Icon--usage-guidelines.mdx

@@ -0,0 +1,145 @@
+import { Canvas, Meta, Controls, Story } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from "~storybook/components"
+import * as IconStories from "./Icon.docs.stories"
+
+<Meta title="Illustrations/Icon/Icon (Future)/Usage Guidelines" />
+
+# Icon (Future)
+
+Updated September 13, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__illustrations__/Icon/v3"
+  apiSpecification="/?path=/docs/illustrations-icon-v3-api-specification--docs"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-3974"
+/>
+
+<KAIOInstallation exportNames="Icon" isFuture />
+
+## Overview
+
+Icons are simplified visual symbols that represent ideas, objects, or actions. They improve comprehension, guide interactivity, and draw attention to important information.
+
+<Canvas of={IconStories.Playground} />
+<Controls of={IconStories.Playground} include={["name", "isFilled"]} />
+
+### When to use
+
+- To support comprehension of an idea, object, or action.
+- To provide visual cues and improving navigation.
+
+### When not to use
+
+- When the meaning of the icon is not immediately clear or could be misinterpreted.
+- When text is necessary to convey specific or detailed information.
+- When using too many icons could clutter the interface and overwhelm the user.
+- When accessibility is a concern and the icon does not have appropriate alternative text or support.
+- When the icon does not align with the overall design language or style of the application.
+
+### Specs
+
+When you need a new icon, use [Google's Material Symbols set](https://fonts.google.com/icons) via the [Figma plugin](https://www.figma.com/community/plugin/1088610476491668236/material-symbols) to add the relevant icons in:
+- **Outlined**
+- **Weight**: 400
+- **Grade**: Normal (0)
+- **Fill**: On or Off
+
+#### Do use icons consistently
+
+Consistent use of icons helps users quickly recognize and understand their function, improving overall usability.
+Refer to the [default set](#default-icon-set) for icons commonly used across the platform.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ConsistentDo} />
+</DosAndDonts>
+
+#### Do use the appropriate fill for the icon context and state
+
+Filled icons can indicate an active state or selection. Unfilled icons often represent a default or inactive state. Not all icons change appearance when toggled between filled and unfilled, so use this distinction thoughtfully.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.FilledUnfilledDo} />
+</DosAndDonts>
+
+#### Do use the correct optical size
+
+Scale the optical size to match the size of the icon - do not mix icon sizes with a different optical size.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.OpticalSizeDo} />
+  <DoOrDont story={IconStories.OpticalSizeDont} isDont />
+</DosAndDonts>
+
+#### Do align the icon vertically
+
+Vertically center the icon by shifting down the baseline of symbols to approximately 11.5% of the type size.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.AlignmentDo} />
+  <DoOrDont story={IconStories.AlignmentDont} isDont />
+</DosAndDonts>
+
+#### Do use icon colors that meet 3:1 contrast ratios with their background
+
+Icons should be easily distinguishable and clearly visible against their background to ensure they are accessible to all users, including those with visual impairments.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ContrastDo} />
+  <DoOrDont story={IconStories.ContrastDont} isDont />
+</DosAndDonts>
+
+#### Do use color purposefully
+
+Where suitable, color can be used to highlight an icon or reinforce its meaning, such as using green for success or red for errors.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ColorPurposefulDo} />
+</DosAndDonts>
+
+#### Don't rely on color alone
+
+Ensure that icons are distinguishable by varying the icon, fill, or labels. Relying only on color can make the interface less accessible to colorblind users.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.DistinguishDo} />
+  <DoOrDont story={IconStories.DistinguishDont} isDont />
+</DosAndDonts>
+
+#### Don't overload your interface with too many icons
+
+Overusing icons can create visual clutter and overwhelm users. Use them sparingly to highlight important actions or information.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.InterfaceDont} isDont />
+</DosAndDonts>
+
+#### Don't rely on icons alone for conveying important information
+
+Icons should support, not replace, text labels, especially for accessibility. Screen readers and other assistive technologies may not always interpret icons correctly.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ImportantInformationDo} />
+  <DoOrDont story={IconStories.ImportantInformationDont} isDont />
+</DosAndDonts>
+
+#### Do use appropriate states on interactive icons
+
+If the icon is interactive, it should have a base, hover, and focus state.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.InteractiveStatesDo} />
+</DosAndDonts>
+
+#### Don't rely on tooltips to covey icon meaning
+
+Important information can be hidden if it's only explained in tooltips, leading to poor user experience. Whenever possible, include a text label or other contextual information alongside the icon to clearly convey its meaning.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.TooltipDont} isDont />
+</DosAndDonts>
+
+## Default icon set
+
+Whilst you have access to all Material Symbols, the following icons match the default set we have in Figma.
+
+<Story of={IconStories.DefaultIconSet} />

package/src/__future__/Icon/_docs/Icon.docs.module.css

@@ -0,0 +1,17 @@
+.interactiveIcon {
+  position: relative;
+  background: none;
+  padding: 0;
+  color: var(--color-blue-500);
+
+  &:hover {
+    color: var(--color-blue-400);
+  }
+}
+
+.interactiveIcon:focus::after {
+  position: absolute;
+  content: "";
+  border: var(--border-focus-ring-border-width) solid var(--color-blue-500);
+  inset: -2px;
+}

package/src/__future__/Icon/_docs/Icon.docs.stories.tsx

@@ -0,0 +1,524 @@
+import React, { useState } from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import classnames from "classnames"
+import { InlineNotification } from "~components/Notification"
+import {
+  TableCard,
+  TableContainer,
+  TableHeader,
+  TableHeaderRowCell,
+  TableRow,
+  TableRowCell,
+} from "~components/Table"
+import { Text } from "~components/Text"
+import { ToggleSwitchField } from "~components/ToggleSwitch"
+import { Button } from "~components/__actions__/v3"
+import { Tag } from "~components/__future__/Tag"
+import { StickerSheet } from "~storybook/components/StickerSheet"
+import { iconDefaultSet } from "../constants"
+import { Icon } from "../index"
+import imgInterfaceDont from "./assets/interface-dont.png"
+import imgTooltipDont from "./assets/tooltip-dont.png"
+import styles from "./Icon.docs.module.css"
+
+const meta = {
+  title: "Illustrations/Icon/Icon (Future)",
+  component: Icon,
+  args: {
+    name: "star",
+    isPresentational: true,
+  },
+  argTypes: {
+    name: { type: "string" },
+    alt: {
+      description: "Set this value when `isPresentational={false}`",
+    },
+  },
+} satisfies Meta<typeof Icon>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  render: args => {
+    if (args.isPresentational) return <Icon {...args} alt={undefined} />
+    return <Icon {...args} alt={args.alt ?? "Fallback string"} />
+  },
+}
+
+export const Filled: Story = {
+  args: { isFilled: true },
+}
+
+export const MirrorInRTL: Story = {
+  render: args => (
+    <StickerSheet>
+      <StickerSheet.Header
+        headings={['dir=["ltr"]', 'dir=["rtl"]']}
+        hasVerticalHeadings
+      />
+      <StickerSheet.Body>
+        <StickerSheet.Row rowTitle="arrow_forward">
+          <div dir="ltr" className="text-center">
+            <Icon {...args} name="arrow_forward" shouldMirrorInRTL />
+          </div>
+          <div dir="rtl" className="text-center">
+            <Icon {...args} name="arrow_forward" shouldMirrorInRTL />
+          </div>
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="format_list_numbered">
+          <div dir="ltr" className="text-center">
+            <Icon {...args} name="format_list_numbered" shouldMirrorInRTL />
+          </div>
+          <div dir="rtl" className="text-center">
+            <Icon {...args} name="format_list_numbered" shouldMirrorInRTL />
+          </div>
+        </StickerSheet.Row>
+      </StickerSheet.Body>
+    </StickerSheet>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `
+<div dir="ltr" className="text-center">
+  <Icon {...props} name="arrow_forward" shouldMirrorInRTL />
+</div>
+<div dir="rtl" className="text-center">
+  <Icon {...props} name="arrow_forward" shouldMirrorInRTL />
+</div>
+<div dir="ltr" className="text-center">
+  <Icon {...props} name="format_list_numbered" shouldMirrorInRTL />
+</div>
+<div dir="rtl" className="text-center">
+  <Icon {...props} name="format_list_numbered" shouldMirrorInRTL />
+</div>
+        `,
+      },
+    },
+  },
+}
+
+export const Color: Story = {
+  render: args => (
+    <div className="flex gap-16">
+      <div className="text-green-500">
+        <Icon {...args} />
+      </div>
+      <Icon {...args} className="text-blue-500" />
+    </div>
+  ),
+}
+
+export const Size: Story = {
+  render: args => (
+    <div className="flex gap-16">
+      <Icon {...args} className="[--icon-size:48]" />
+      <div className="text-[48px]">
+        <Icon {...args} className="text-[1em] [--icon-optical-size:48]" />
+      </div>
+    </div>
+  ),
+}
+
+export const MeaningfulIcon: Story = {
+  render: args => (
+    <Button>
+      <Icon {...args} />
+    </Button>
+  ),
+  args: { isPresentational: false, alt: "Favourite" },
+}
+
+export const PresentationalIcon: Story = {
+  render: args => (
+    <Button>
+      <Icon {...args} /> Favourite
+    </Button>
+  ),
+  args: { isPresentational: true },
+}
+
+const IconSetButton = ({
+  iconName,
+  isFilled,
+}: {
+  iconName: string
+  isFilled: boolean
+}): JSX.Element => {
+  const [copied, setCopied] = useState(false)
+
+  const handleCopy = (): void => {
+    const snippet = isFilled
+      ? `<Icon name="${iconName}" isPresentational isFilled />`
+      : `<Icon name="${iconName}" isPresentational />`
+    navigator.clipboard.writeText(snippet)
+
+    setCopied(true)
+    setTimeout(() => setCopied(false), 1000)
+  }
+
+  return (
+    <li>
+      <button
+        type="button"
+        onClick={handleCopy}
+        className={classnames(
+          "flex flex-col justify-center items-center gap-16",
+          "cursor-pointer h-full w-full p-16 rounded",
+          "bg-gray-100 hover:bg-gray-200"
+        )}
+      >
+        {copied ? (
+          <Tag color="green" classNameOverride="border-1 border-green-500">
+            Copied!
+          </Tag>
+        ) : (
+          <>
+            <Icon name={iconName} isPresentational isFilled={isFilled} />
+            <Text variant="small" tag="span">
+              {iconName}
+            </Text>
+          </>
+        )}
+      </button>
+    </li>
+  )
+}
+
+export const DefaultIconSet: Story = {
+  render: () => {
+    const [isFilled, setIsFilled] = useState(false)
+
+    return (
+      <div className="flex flex-col gap-8">
+        <ToggleSwitchField
+          labelText="Filled"
+          toggledStatus={isFilled ? "on" : "off"}
+          onToggle={() => setIsFilled(!isFilled)}
+        />
+        <ul
+          className="grid list-none gap-16 m-0 p-0"
+          style={{ gridTemplateColumns: "repeat(auto-fit, minmax(11em, 1fr))" }}
+        >
+          {iconDefaultSet.map(iconName => (
+            <IconSetButton
+              key={iconName}
+              iconName={iconName}
+              isFilled={isFilled}
+            />
+          ))}
+        </ul>
+      </div>
+    )
+  },
+}
+
+export const ConsistentDo: Story = {
+  render: () => (
+    <Text variant="body">
+      Edit <Icon name="edit" isPresentational />
+    </Text>
+  ),
+}
+
+export const FilledUnfilledDo: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex items-center gap-4">
+        <Text variant="body">Default state</Text>
+        <Icon name="thumb_up" isPresentational />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">Selected</Text>
+        <Icon name="thumb_up" isPresentational isFilled />
+      </div>
+    </div>
+  ),
+}
+
+export const OpticalSizeDo: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex items-center gap-4">
+        <Text variant="body">20/20</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[20px] [--icon-optical-size:20]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">24/24</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[24px] [--icon-optical-size:24]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">40/40</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[40px] [--icon-optical-size:40]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">48/48</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[48px] [--icon-optical-size:48]"
+        />
+      </div>
+    </div>
+  ),
+}
+
+export const OpticalSizeDont: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex items-center gap-4">
+        <Text variant="body">20/48</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[20px] [--icon-optical-size:48]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">24/40</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[24px] [--icon-optical-size:40]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">40/24</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[40px] [--icon-optical-size:24]"
+        />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">48/20</Text>
+        <Icon
+          name="star"
+          isPresentational
+          className="text-[48px] [--icon-optical-size:20]"
+        />
+      </div>
+    </div>
+  ),
+}
+
+export const AlignmentDo: Story = {
+  render: () => (
+    <img
+      src="https://lh3.googleusercontent.com/twRAsK6vahc7l_yuhhlBzVp1yR_8tsspDL16Xry73IrhYE3ItxmKSqHC6MznHq9EZKfrOgP_a3RDNGLK28JmhHeFiDmiwYrbhBtpxjodrsw=s0"
+      alt="Symbol baseline set lower in relation to symbol."
+      className="w-full"
+    />
+  ),
+}
+
+export const AlignmentDont: Story = {
+  render: () => (
+    <img
+      src="https://lh3.googleusercontent.com/MePU5NYnrFy96fiDdULne6XwFlboyznBeVWD5CTrFwzNdzsMjrvg_ySLfXJVdUNxSkeUT4UH28_Orz916LRN78bhneYBA0dL8YpCQswiERo=s0"
+      alt="Both symbol and text set on same baseline."
+      className="w-full"
+    />
+  ),
+}
+
+export const ContrastDo: Story = {
+  render: () => (
+    <div className="bg-yellow-100 p-16">
+      <Icon name="star" isPresentational className="text-yellow-700" />
+    </div>
+  ),
+}
+
+export const ContrastDont: Story = {
+  render: () => (
+    <div className="bg-yellow-100 p-16">
+      <Icon name="star" isPresentational className="text-yellow-500" />
+    </div>
+  ),
+}
+
+export const ColorPurposefulDo: Story = {
+  render: () => (
+    <>
+      <InlineNotification variant="success">Success</InlineNotification>
+      <InlineNotification variant="warning" noBottomMargin>
+        Error
+      </InlineNotification>
+    </>
+  ),
+}
+
+export const DistinguishDo: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex items-center gap-4">
+        <Text variant="body">Default state</Text>
+        <Icon name="thumb_up" isPresentational />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">Selected</Text>
+        <Icon name="thumb_up" isPresentational isFilled />
+      </div>
+    </div>
+  ),
+}
+
+export const DistinguishDont: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex items-center gap-4">
+        <Text variant="body">Default state</Text>
+        <Icon name="thumb_up" isPresentational />
+      </div>
+      <div className="flex items-center gap-4">
+        <Text variant="body">Selected</Text>
+        <Icon name="thumb_up" isPresentational className="text-blue-500" />
+      </div>
+    </div>
+  ),
+}
+
+export const InterfaceDont: Story = {
+  render: () => (
+    <img
+      src={imgInterfaceDont}
+      alt="Example of a bad interface"
+      className="block m-auto max-w-[600px]"
+    />
+  ),
+}
+
+export const ImportantInformationDo: Story = {
+  render: () => (
+    <TableContainer>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderRowCell
+            labelText="Flag for review"
+            sorting="ascending"
+            width={4 / 12}
+          />
+          <TableHeaderRowCell labelText="Employee" sorting="ascending" />
+        </TableRow>
+      </TableHeader>
+      <TableCard>
+        <TableRow>
+          <TableRowCell width={4 / 12}>
+            <Icon name="flag" alt="Flag" />
+          </TableRowCell>
+          <TableRowCell>
+            <Text tag="div" variant="body">
+              John Johnson
+            </Text>
+          </TableRowCell>
+        </TableRow>
+      </TableCard>
+      <TableCard>
+        <TableRow>
+          <TableRowCell width={4 / 12}>
+            <Icon name="flag" alt="Flag" />
+          </TableRowCell>
+          <TableRowCell>
+            <Text tag="div" variant="body">
+              Michelle Summer
+            </Text>
+          </TableRowCell>
+        </TableRow>
+      </TableCard>
+    </TableContainer>
+  ),
+}
+
+export const ImportantInformationDont: Story = {
+  render: () => (
+    <TableContainer>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderRowCell labelText="" sorting="ascending" />
+          <TableHeaderRowCell labelText="Employee" sorting="ascending" />
+        </TableRow>
+      </TableHeader>
+      <TableCard>
+        <TableRow>
+          <TableRowCell>
+            <Icon name="flag" alt="Flag" />
+          </TableRowCell>
+          <TableRowCell>
+            <Text tag="div" variant="body">
+              John Johnson
+            </Text>
+          </TableRowCell>
+        </TableRow>
+      </TableCard>
+      <TableCard>
+        <TableRow>
+          <TableRowCell>
+            <Icon name="flag" alt="Flag" />
+          </TableRowCell>
+          <TableRowCell>
+            <Text tag="div" variant="body">
+              Michelle Summer
+            </Text>
+          </TableRowCell>
+        </TableRow>
+      </TableCard>
+    </TableContainer>
+  ),
+  parameters: {
+    a11y: { disable: true }, // accessible label fix to be addressed in a separate PR
+  },
+}
+
+const InteractiveIcon = (props: Record<string, any>): JSX.Element => (
+  <button type="button" className={styles.interactiveIcon} {...props}>
+    <Icon name="info" isPresentational isFilled />
+  </button>
+)
+
+export const InteractiveStatesDo: Story = {
+  render: () => (
+    <div className="flex gap-16">
+      <Text variant="body">
+        Base <InteractiveIcon />
+      </Text>
+      <Text variant="body">
+        Hover <InteractiveIcon data-sb-pseudo-styles="hover" />
+      </Text>
+      <Text variant="body">
+        Focus <InteractiveIcon data-sb-pseudo-styles="focus" />
+      </Text>
+    </div>
+  ),
+  parameters: {
+    pseudo: {
+      hover: '[data-sb-pseudo-styles="hover"]',
+      focus: '[data-sb-pseudo-styles="focus"]',
+      focusVisible: '[data-sb-pseudo-styles="focus"]',
+    },
+  },
+}
+
+export const TooltipDont: Story = {
+  render: () => (
+    <img
+      src={imgTooltipDont}
+      alt="Example of a bad use of a tooltip on an icon"
+      className="block m-auto max-w-[600px]"
+    />
+  ),
+}