feat: Allow an icon to display with an inverse color

packages/css/src/components/icon/icon.scss

@@ -12,6 +12,10 @@
   fill: currentColor;
 }
 
+.ams-icon--inverse-color {
+  color: var(--ams-icon-inverse-color);
+}
+
 .ams-icon--square {
   aspect-ratio: 1 / 1;
   justify-content: center;

packages/react/src/Icon/Icon.test.tsx

@@ -49,6 +49,14 @@ describe('Icon', () => {
     expect(icon).toHaveClass('ams-icon--square')
   })
 
+  it('renders the inverse color class', () => {
+    const { container } = render(<Icon svg={AlertIcon} inverseColor />)
+
+    const icon = container.querySelector('span:only-child')
+
+    expect(icon).toHaveClass('ams-icon--inverse-color')
+  })
+
   it('renders an additional class name', () => {
     const { container } = render(<Icon svg={AlertIcon} className="large" />)
 

packages/react/src/Icon/Icon.tsx

@@ -10,6 +10,8 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes } from 'react'
 
 export type IconProps = {
+  /** Changes the icon colour for readability on a dark background. */
+  inverseColor?: boolean
   /** The size of the icon. Corresponds with the text levels. */
   size?: 'level-3' | 'level-4' | 'level-5' | 'level-6'
   /** Whether the icon container should be made square. */
@@ -19,11 +21,15 @@ export type IconProps = {
 } & HTMLAttributes<HTMLSpanElement>
 
 export const Icon = forwardRef(
-  ({ className, size = 'level-3', square, svg, ...restProps }: IconProps, ref: ForwardedRef<HTMLElement>) => (
+  (
+    { className, inverseColor, size = 'level-3', square, svg, ...restProps }: IconProps,
+    ref: ForwardedRef<HTMLElement>,
+  ) => (
     <span
       ref={ref}
       className={clsx(
         'ams-icon',
+        inverseColor && 'ams-icon--inverse-color',
         size === 'level-3' && 'ams-icon--size-3',
         size === 'level-4' && 'ams-icon--size-4',
         size === 'level-5' && 'ams-icon--size-5',

proprietary/tokens/src/components/ams/icon.tokens.json

@@ -1,6 +1,9 @@
 {
   "ams": {
     "icon": {
+      "inverse": {
+        "color": { "value": "{ams.brand.color.neutral.0}" }
+      },
       "size-3": {
         "font-size": { "value": "{ams.text.level.3.font-size}" },
         "line-height": { "value": "{ams.text.level.3.line-height}" }

storybook/src/components/Icon/Icon.docs.mdx

@@ -61,3 +61,10 @@ Sometimes it’s useful for the icon to take up square space, for example, with
 ### Level 6
 
 <Canvas of={IconStories.Level6} />
+
+### Inverse colour
+
+Set the `inverseColor` prop if the Icon sits on a dark background.
+This ensures the colour of the icon provides enough contrast.
+
+<Canvas of={IconStories.InverseColour} />

storybook/src/components/Icon/Icon.stories.tsx

@@ -11,6 +11,10 @@ import { Meta, StoryObj } from '@storybook/react'
 const meta = {
   title: 'Components/Media/Icon',
   component: Icon,
+  args: {
+    inverseColor: false,
+    svg: Icons.EmailIcon,
+  },
   argTypes: {
     svg: {
       control: {
@@ -26,11 +30,7 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    svg: Icons.EmailIcon,
-  },
-}
+export const Default: Story = {}
 
 export const WithText: Story = {
   decorators: [
@@ -46,42 +46,40 @@ export const WithText: Story = {
       <Heading size="level-3">Inline text</Heading>
     </>
   ),
-  args: {
-    svg: Icons.EmailIcon,
-  },
 }
 
 export const Square: Story = {
   args: {
-    svg: Icons.EmailIcon,
     square: true,
   },
 }
 
 export const Level3: Story = {
   args: {
-    svg: Icons.EmailIcon,
     size: 'level-3',
   },
 }
 
 export const Level4: Story = {
   args: {
-    svg: Icons.EmailIcon,
     size: 'level-4',
   },
 }
 
 export const Level5: Story = {
   args: {
-    svg: Icons.EmailIcon,
     size: 'level-5',
   },
 }
 
 export const Level6: Story = {
   args: {
-    svg: Icons.EmailIcon,
     size: 'level-6',
   },
 }
+
+export const InverseColour: Story = {
+  args: {
+    inverseColor: true,
+  },
+}