fix(Link): handle inverse variant for standalone links

- update documentation to explain cases
- add warning for misaligned prop usages
- update snapshots and tests

src/components/Link/Link.module.css

@@ -50,6 +50,10 @@
     text-decoration: none;
   }
 
+  &.link--variant-inverse {
+    color: var(--eds-theme-color-text-utility-inverse);
+  }
+
   /**
    * Sizes - using the presets for type ramp matching body-*
    */

src/components/Link/Link.stories.tsx

@@ -26,7 +26,7 @@ type Story = StoryObj<typeof Link>;
 export const Default: Story = {};
 
 /**
- * When using context, you can specify a trailing icon for the link.
+ * When using standalone context, you can specify a trailing icon for the link.
  *
  * **NOTE**: support for applying the chevron only works when `emphasis` is set to "low".
  */
@@ -40,7 +40,7 @@ export const LinkWithChevron: Story = {
 };
 
 /**
- * When using context, you can specify a trailing icon for the link. When using the open icon, make sure that a new tab/window is opened.
+ * When using standalone context, you can specify a trailing icon for the link. When using the open icon, make sure that a new tab/window is opened.
  */
 export const LinkWithOpenIcon: Story = {
   args: {
@@ -51,7 +51,7 @@ export const LinkWithOpenIcon: Story = {
 };
 
 /**
- * You can add formatting to the link if needed.
+ * You can add formatting to a link if needed.
  */
 export const LinkWithFormattedChildren: Story = {
   args: {
@@ -75,9 +75,11 @@ export const Emphasis: Story = {
         <Link {...args} emphasis="default">
           Default Emphasis
         </Link>
+        <br />
         <Link {...args} emphasis="high">
           High Emphasis
         </Link>
+        <br />
         <Link {...args} emphasis="low">
           Low Emphasis
         </Link>
@@ -87,7 +89,20 @@ export const Emphasis: Story = {
 };
 
 /**
- * We also include an inverse variant, for use on dark backgrounds.
+ * Standalone inverse links take on a specific inverse color.
+ */
+export const StandaloneInverseVariant: Story = {
+  args: {
+    context: 'standalone',
+    variant: 'inverse',
+  },
+  parameters: {
+    backgrounds: { default: 'background-utility-default-high-emphasis' },
+  },
+};
+
+/**
+ * Inline always take on the color of the container. When using an inline link, wrap the text with a proper color text token.
  */
 export const InverseVariant: Story = {
   args: {
@@ -129,7 +144,7 @@ export const LinkInParagraphContext: StoryObj<ExtendArgs> = {
 };
 
 /**
- * Links will inherit the color from the surrounding text color definition (default emphasis, inline links)
+ * Inline links will inherit the color from the surrounding text color definition (default emphasis)
  */
 export const InheritColor: Story = {
   args: {

src/components/Link/Link.test.tsx

@@ -121,5 +121,17 @@ describe('<Link />', () => {
 
       expect(consoleMock).toHaveBeenCalledTimes(1);
     });
+
+    it('warns when variant is used with context inline', () => {
+      const consoleMock = jest.spyOn(console, 'warn');
+      consoleMock.mockImplementation();
+      render(
+        <Link context="inline" variant="inverse">
+          Click
+        </Link>,
+      );
+
+      expect(consoleMock).toHaveBeenCalledTimes(1);
+    });
   });
 });

src/components/Link/Link.tsx

@@ -28,7 +28,9 @@ export type LinkProps<ExtendedElement = unknown> =
      *
      * **Default is `"inline"`**.
      *
-     * Note: Icons will only be visible when `"standalone"` is used
+     * ----
+     *
+     * **Note**: This will only apply when `"standalone"` is used
      */
     context?: 'inline' | 'standalone';
     /**
@@ -42,13 +44,19 @@ export type LinkProps<ExtendedElement = unknown> =
     /**
      * The size of the link (when its context is "standalone").
      *
-     * **NOTE**: when `context` is `"inline"`, size is ignored (and inherits from the associated text container)
+     * ----
+     *
+     * **Note**: This will only apply when `"standalone"` is used
      */
     size?: Extract<Size, 'xs' | 'sm' | 'md' | 'lg' | 'xl'>;
     /**
-     * The variant treatment for links (use "inverse" on dark backgrounds).
+     * The variant treatment for **standalone** links (use "inverse" on dark backgrounds).
      *
      * **Default is `"default"`**.
+     *
+     * ----
+     *
+     * **Note**: This will only apply when `"standalone"` is used
      */
     variant?: 'default' | 'inverse';
   } & ExtendedElement;
@@ -58,6 +66,7 @@ export type LinkProps<ExtendedElement = unknown> =
  *
  * Component for making styled anchor tags. Links allow users to navigate within or between a web page(s) or app(s).
  *
+ * Inline links inherit the color of the surrounding container, while when using `context` set to `standalone`, links have specific colors.
  */
 export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
   (
@@ -96,6 +105,11 @@ export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
       'Inline links cannot show icons',
     );
 
+    assertEdsUsage(
+      [context === 'inline' && variant === 'inverse'],
+      'Variant can only be used when context is "standalone"',
+    );
+
     assertEdsUsage(
       [context === 'inline' && typeof size !== 'undefined'],
       'Size can only be used when context is "standalone"',

src/components/Link/__snapshots__/Link.test.tsx.snap

@@ -24,12 +24,14 @@ exports[`<Link /> Emphasis story renders snapshot 1`] = `
     >
       Default Emphasis
     </a>
+    <br />
     <a
       class="link link--context-standalone link--emphasis-high link--size-md"
       href="http://example.org/"
     >
       High Emphasis
     </a>
+    <br />
     <a
       class="link link--context-standalone link--emphasis-low link--size-md"
       href="http://example.org/"
@@ -216,6 +218,19 @@ exports[`<Link /> LinkWithOpenIcon story renders snapshot 1`] = `
 </div>
 `;
 
+exports[`<Link /> StandaloneInverseVariant story renders snapshot 1`] = `
+<div
+  class="text-utility-default-primary"
+>
+  <a
+    class="link link--context-standalone link--emphasis-default link--size-lg link--variant-inverse"
+    href="http://example.org/"
+  >
+    Link
+  </a>
+</div>
+`;
+
 exports[`<Link /> UsingExtendedLink story renders snapshot 1`] = `
 <div
   class="text-utility-default-primary"