From 1f9edc2f1e06f8db921889ce61dad8bddb577849 Mon Sep 17 00:00:00 2001
From: Michael Winter <36558508+mcwinter07@users.noreply.github.com>
Date: Thu, 19 Dec 2024 15:06:28 +1100
Subject: [PATCH] Create LinkButton component (#5298)

* create LinkButton component and stories and update button exports

* update button references to LinkButton

* add missing isDisabled props to LinkButton

* add stickersheets for LinkButton

* add docs section and story on links that open in a new tab

* update docs content on native nav, children, press events and tabs

* update style import from button to resolve build compile issue

* update next.js config guidance for client side routing

* update LinkButton external links and add usage guidelines

* update overview on spec and guidance page

* update stickersheet to new grid structure

* update shared Button and LinkButton type name

* update docs imports and minor errors

* fix lint issues and update stories

* update docs position and reversed storydocs

* move LinkButton to rc component folder and update import paths

* add LinkButton to v3 actions exports

* move LinkButton to root components folder and update import paths
---
 .changeset/hip-queens-divide.md               |   7 +
 .../src/LinkButton/LinkButton.module.css      |   4 +
 .../components/src/LinkButton/LinkButton.tsx  |  71 +++++
 .../_docs/LinkButton--api-specification.mdx   | 281 ++++++++++++++++++
 .../_docs/LinkButton--usage-guidelines.mdx    |  29 ++
 .../_docs/LinkButton.doc.stories.tsx          | 136 +++++++++
 .../_docs/LinkButton.spec.stories.tsx         |  80 +++++
 .../_docs/LinkButton.stickersheet.stories.tsx | 130 ++++++++
 packages/components/src/LinkButton/index.ts   |   1 +
 .../components/src/__rc__/Button/Button.tsx   |  12 +-
 .../_docs/Button--api-specification.mdx       |  10 +-
 .../Button/_docs/Button--usage-guidelines.mdx |   7 +-
 packages/components/src/index.ts              |   3 +-
 13 files changed, 755 insertions(+), 16 deletions(-)
 create mode 100644 .changeset/hip-queens-divide.md
 create mode 100644 packages/components/src/LinkButton/LinkButton.module.css
 create mode 100644 packages/components/src/LinkButton/LinkButton.tsx
 create mode 100644 packages/components/src/LinkButton/_docs/LinkButton--api-specification.mdx
 create mode 100644 packages/components/src/LinkButton/_docs/LinkButton--usage-guidelines.mdx
 create mode 100644 packages/components/src/LinkButton/_docs/LinkButton.doc.stories.tsx
 create mode 100644 packages/components/src/LinkButton/_docs/LinkButton.spec.stories.tsx
 create mode 100644 packages/components/src/LinkButton/_docs/LinkButton.stickersheet.stories.tsx
 create mode 100644 packages/components/src/LinkButton/index.ts

diff --git a/.changeset/hip-queens-divide.md b/.changeset/hip-queens-divide.md
new file mode 100644
index 00000000000..8852b3688fe
--- /dev/null
+++ b/.changeset/hip-queens-divide.md
@@ -0,0 +1,7 @@
+---
+'@kaizen/components': minor
+---
+
+Add LinkButton component
+
+- Adds LinkButton component, stories and documentation to actions group
diff --git a/packages/components/src/LinkButton/LinkButton.module.css b/packages/components/src/LinkButton/LinkButton.module.css
new file mode 100644
index 00000000000..3fbad5c386a
--- /dev/null
+++ b/packages/components/src/LinkButton/LinkButton.module.css
@@ -0,0 +1,4 @@
+.linkButton {
+  /* Reset */
+  text-decoration: inherit;
+}
diff --git a/packages/components/src/LinkButton/LinkButton.tsx b/packages/components/src/LinkButton/LinkButton.tsx
new file mode 100644
index 00000000000..25e2af42317
--- /dev/null
+++ b/packages/components/src/LinkButton/LinkButton.tsx
@@ -0,0 +1,71 @@
+import React, { forwardRef } from 'react'
+import { Link as RACLink, type LinkProps as RACLinkProps } from 'react-aria-components'
+import { type ButtonUIProps } from '~components/__rc__/Button'
+import buttonStyles from '~components/__rc__/Button/Button.module.css'
+import { ButtonContent } from '~components/__rc__/Button/subcomponents'
+import { useReversedColors } from '~components/__utilities__/v3'
+import { mergeClassNames } from '~components/utils/mergeClassNames'
+import styles from './LinkButton.module.css'
+
+export type LinkButtonProps = ButtonUIProps &
+  Omit<RACLinkProps, 'children'> & {
+    /** Used as the label for the LinkButton. */
+    children: RACLinkProps['children']
+  }
+
+export const LinkButton = forwardRef(
+  (
+    {
+      children,
+      variant = 'primary',
+      size = 'medium',
+      icon,
+      iconPosition = 'start',
+      hasHiddenLabel = false,
+      isFullWidth = false,
+      isDisabled,
+      className,
+      isReversed,
+      ...otherProps
+    }: LinkButtonProps,
+    ref: React.ForwardedRef<HTMLAnchorElement>,
+  ) => {
+    const shouldUseReverse = useReversedColors()
+    const isReversedVariant = isReversed ?? shouldUseReverse
+
+    return (
+      <RACLink
+        ref={ref}
+        className={mergeClassNames(
+          styles.linkButton,
+          buttonStyles.button,
+          buttonStyles[size],
+          hasHiddenLabel && buttonStyles[`${size}IconButton`],
+          isDisabled && buttonStyles.isDisabled,
+          isReversedVariant ? buttonStyles[`${variant}Reversed`] : buttonStyles[variant],
+          isFullWidth && buttonStyles.fullWidth,
+          className,
+        )}
+        isDisabled={isDisabled}
+        {...otherProps}
+      >
+        {(racStateProps) => {
+          const childIsFunction = typeof children === 'function'
+
+          return (
+            <ButtonContent
+              size={size}
+              icon={icon}
+              iconPosition={iconPosition}
+              hasHiddenLabel={hasHiddenLabel}
+            >
+              {childIsFunction ? children(racStateProps) : children}
+            </ButtonContent>
+          )
+        }}
+      </RACLink>
+    )
+  },
+)
+
+LinkButton.displayName = 'LinkButton'
diff --git a/packages/components/src/LinkButton/_docs/LinkButton--api-specification.mdx b/packages/components/src/LinkButton/_docs/LinkButton--api-specification.mdx
new file mode 100644
index 00000000000..caa54c5e586
--- /dev/null
+++ b/packages/components/src/LinkButton/_docs/LinkButton--api-specification.mdx
@@ -0,0 +1,281 @@
+import { Canvas, Meta, Controls, ArgTypes, DocsStory } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
+import * as exampleStories from './LinkButton.doc.stories'
+
+<Meta title="Components/LinkButton/API Specification" />
+
+# LinkButton API Specification
+
+Updated Dec 18, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/LinkButton/v3"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-17364"
+  designGuidelines="/?path=/docs/actions-linkbutton-linkbutton-v3-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames={'LinkButton'} />
+
+## Overview
+
+`LinkButton` allows users to navigate to another page or resource. It shares the same visual styles and interaction states as the <LinkTo pageId="actions-button-button-v3-usage-guidelines--docs">Button</LinkTo> component, but is intended for navigational purposes and downloading documents.
+
+The following example and table showcases the essential props that enable the core functionality of `LinkButton`. For the remaining suite of API options refer to [this section](#additional-api-options).
+
+<Canvas of={exampleStories.Playground} />
+
+<Controls
+  of={exampleStories.Playground}
+  include={[
+    'className',
+    'children',
+    'href',
+    'target',
+    'download',
+    'onPress',
+    'routerOptions',
+    'hasHiddenLabel',
+    'size',
+    'variant',
+    'icon',
+    'iconPosition',
+    'isReversed',
+    'isFullWidth',
+    'isDisabled',
+  ]}
+/>
+
+## API
+
+This is built on top of [React Aria's Link component](https://react-spectrum.adobe.com/react-aria/Link.html) and is the counterpart to the <LinkTo pageId="actions-button-button-v3-api-specification--docs">Kaizen Button</LinkTo>, handling icons, variants and sizes in the same way. It provides a semantic wrapper for navigational buttons and allows for native `href` navigation and client side routing with [additional configuration](#client-side-routing).
+
+### Navigation and native anchor attributes
+
+Out of the box, the `LinkButton` offers majority of the native behavior and functionality on the `anchor` tag. `href` will trigger new page loads, `download` will download the referenced document, and `target` can be used to open links in new tabs or windows.
+
+<Canvas of={exampleStories.DownloadIconButton} />
+
+While client side routing is possible, the `LinkButton` is agnostic to the routing technology chosen. Refer to our general set up guide to get started with [client side routing](#client-side-routing).
+
+#### Opening new tabs and accessibility considerations
+
+The general recommendation is to limit the number of links that open a new tab or window on a single page. While there are valid scenarios that can help avoid loss of data and or progress, as with links in forms, opening new tabs can be disorienting for users - especially for those who have difficulty perceiving visual content.
+
+In order to provide advance warning to all users, it is recommended that links using `target="_blank"` be accompanied by a visual indicator and audible warning. As shown in the following example, additional context can be provided via a visually hidden element within the `children` of the component.
+
+<Canvas of={exampleStories.LinkButtonOpensInNewTab} />
+
+For more context on this recommendation, we recommend taking a look at the [W3C page on the G200 success criteria](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
+
+### Variants
+
+`LinkButton` supports the following variants: `primary`, `secondary` and `tertiary`. If the `variant` prop is not specified, the default will be `primary`.
+
+<Canvas of={exampleStories.LinkButtonVariants} />
+
+Reversed variants are handled via the `ReversedColors` Provider.
+
+<DocsStory of={exampleStories.LinkButtonVariantsReversed} expanded={false} />
+
+To enable the reversed theme, you will need to wrap the component or application in the `ReversedColors` provider, ie:
+
+```tsx
+import { RouterProvider } from 'react-aria-components'
+import { Button } from '@kaizen/components/v3/actions'
+import { ReversedColors } from '@kaizen/components/v3/utilities'
+// application code
+
+return (
+  <ReversedColors isReversed={true}>
+    <LinkButton {...LinkbuttonProps} />
+  </ReversedColors>
+)
+```
+
+### Sizes
+
+LinkButton supports the following sizes: `small`, `medium` and `large`. If the `size` prop is not specified, the default will be `medium`.
+
+<Canvas of={exampleStories.LinkButtonSizes} />
+
+### `onPress`
+
+As with <LinkTo pageId="actions-button-button-v3-usage-guidelines--docs">Button</LinkTo>, `LinkButton`'s API uses React Aria's `onPress` instead of `onClick`. Functionally this does not change the way we pass click events to a `LinkButton`. Consumers can safely replace `onClick` with `onPress` without any additional changes, ie:
+
+```tsx
+<Button
+  label="Download doc"
+  href="https://cultureamp.com/a-pdf-doc.pdf"
+  download
+  onClick={(e) => trackDownloadEvent(e)}
+/>
+```
+
+Can be replaced with the following:
+
+```tsx
+<LinkButton
+  href="https://cultureamp.com/a-pdf-doc.pdf"
+  download
+  onPress={(e) => trackDownloadEvent(e)}
+>
+  Download doc
+</LinkButton>
+```
+
+You can read more about the development and reason behind this pattern [here](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html#touch-interactions).
+
+### LinkButton content and children
+
+Labels and any `LinkButton` content can be passed to the component via `children`. For icons as content, refer to the [next section](#icons-and-positioning).
+
+```tsx
+<LinkButton href="#link">Label</LinkButton>
+```
+
+While in most cases, `children` will be a `ReactNode`, `LinkButton` also accepts a render function with React Aria's `LinkRenderProps`. This allows for more advanced styling and rendering options by hooking into React Aria's internal Link state. You can read more about this [here](https://react-spectrum.adobe.com/react-aria/Link.html#styling).
+
+### Icons and positioning
+
+The `icon` property abstracts the need to handle positioning and sizing logic for icons within the `LinkButton`. When paired with the [Icon component](/docs/illustrations-icon-icon-future-api-specification--docs), this will scale the icon to the `LinkButton`'s `size` prop.
+
+<Canvas of={exampleStories.LinkButtonWithIconStart} />
+
+Set the position of the icon using the `iconPosition` prop. This will ensure content is flipped in `RTL` layouts. Note that icons will need the [shouldMirrorInRTL](/docs/illustrations-icon-icon-future-api-specification--docs#mirror-in-rtl) prop set to `true` when mirroring is required.
+
+<Canvas of={exampleStories.LinkButtonWithIconEnd} />
+
+### Icon-only `LinkButton` and `hasHiddenLabel`
+
+To achieve an icon-only `LinkButton` (previously: `IconButton`) use the `icon` prop and set `hasHiddenLabel` to `true`. This will visually hide the button's `children`, while still announcing the content to screen readers.
+
+<Canvas of={exampleStories.IconLinkButton} />
+
+This pattern ensures that the `LinkButton`'s accessible name is determined by its children, which helps to announce relevant content to the screen readers. You can learn more about this [accessible pattern here](https://cultureamp.atlassian.net/wiki/spaces/PA/pages/3833331831/Accessible+button+and+link+labels).
+
+### Full width LinkButtons
+
+If a `LinkButton` is statically the full width of a container you can use the `isFullWidth` property.
+
+<Canvas of={exampleStories.LinkButtonFullWidth} />
+
+For resizing on smaller screens, consider using the `className` prop to leverage CSS media or container queries, ie: `<LinkButton className="w-full md:w-[initial]">Label</LinkButton>`.
+
+## Client side routing
+
+To enable client side routing with the `LinkButton`, you will need to wrap your application in a [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#routerprovider) from the `react-aria-components` library. The allows you to set the `navigation` method that performs the client side routing in the `LinkButton` component. Refer to the framework specific guidance below for [Next.js](#nextjs-config-example) or [React Router](#react-router-config-example).
+
+### Next.js config example
+
+The following example demonstrates how you might use the React Aria's `RouterProvider` with `Next.js`'s Pages router. This will allow the `LinkButton` to navigate using the `router.push` method.
+
+```tsx
+// ...imports
+import type { AppProps } from 'next/app'
+import { type NextRouter } from 'next/router'
+import { RouterProvider as RacRouterProvider } from 'react-aria-components'
+
+// This provides the correct types for `routerOptions` based on the routing solution. As the component agnostic to routing technology this must defined here
+declare module 'react-aria-components' {
+  interface RouterConfig {
+    // index 2 is the types for the pages routerOptions
+    routerOptions: NonNullable<Parameters<NextRouter['push']>[2]>
+  }
+}
+
+function App({ Component, pageProps, router }: AppProps) {
+  return (
+    <FrontendServices {...config}>
+      {/* application code */}
+      <RacRouterProvider navigate={(href, opts) => router.push(href, undefined, opts)}>
+        <Component {...pageProps} />
+      </RacRouterProvider>
+      {/* application code */}
+    </FrontendServices>
+  )
+}
+
+export default App
+```
+
+The implementation in your application would then look something like this:
+
+```tsx
+import { useRouter } from 'next/router'
+import { LinkButton } from '@kaizen/components/v3/actions'
+
+const Component = () => {
+  const router = useRouter()
+
+  return (
+    <>
+      <LinkButton href="http://google.com">External link</LinkButton>
+      <LinkButton href={`${router.pathname}/path-1`}>Internal link</LinkButton>
+      <LinkButton href={`${router.pathname}/path-2`} routerOptions={{ scroll: false }}>
+        Link with routerOptions
+      </LinkButton>
+    </>
+  )
+}
+```
+
+Additional config options for Next.js can be found in the React Aria's documentation on the [RouterProvider](https://react-spectrum.adobe.com/react-aria/routing.html#nextjs), including the alternative setup for the [App router](https://react-spectrum.adobe.com/react-aria/routing.html##app-router).
+
+### React Router config example
+
+The following example demonstrates how to use the `RouterProvider` with `React Router`'s. This will allow the `LinkButton` to navigate using the `useNavigate` hook.
+
+```tsx
+import { RouterProvider } from 'react-aria-components'
+import { BrowserRouter, NavigateOptions, useHref, useNavigate } from 'react-router-dom'
+
+declare module 'react-aria-components' {
+  interface RouterConfig {
+    routerOptions: NavigateOptions
+  }
+}
+
+function ReactRouterApp() {
+  const navigate = useNavigate()
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* ...application code */}
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        {/* ...routes */}
+      </Routes>
+    </RouterProvider>
+  )
+}
+
+export default App
+```
+
+If your application is on a version below 5.3.x, you will have to use the `useHistory` hook instead. See our example [here](https://cultureamp.atlassian.net/wiki/spaces/TV/pages/4235920479/RFC+Kaizen+Link+component#Routing-with-RAC-Link-🧭).
+
+Additional notes can be found in the React Aria's documentation on the using the `RouterProvider` with [React Router](https://react-spectrum.adobe.com/react-aria/routing.html#react-router).
+
+## Additional API options
+
+The following table is a collection of additional React Aria and native HTML props that are exposed from the [React Aria Link API](https://react-spectrum.adobe.com/react-aria/Link.html). These are not required for the implementation of `LinkButton` but can be used to extend its functionality. Refer back to the [overview section](#overview) for the core props that enable most use cases.
+
+<ArgTypes
+  of={exampleStories.Playground}
+  exclude={[
+    'className',
+    'children',
+    'href',
+    'target',
+    'download',
+    'routerOptions',
+    'hasHiddenLabel',
+    'size',
+    'variant',
+    'onPress',
+    'icon',
+    'iconPosition',
+    'isFullWidth',
+    'isDisabled',
+  ]}
+/>
diff --git a/packages/components/src/LinkButton/_docs/LinkButton--usage-guidelines.mdx b/packages/components/src/LinkButton/_docs/LinkButton--usage-guidelines.mdx
new file mode 100644
index 00000000000..e439ee4ea08
--- /dev/null
+++ b/packages/components/src/LinkButton/_docs/LinkButton--usage-guidelines.mdx
@@ -0,0 +1,29 @@
+import { Canvas, Meta, Controls } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
+import * as LinkButton from './LinkButton.doc.stories'
+
+<Meta title="Components/LinkButton/Usage Guidelines" />
+
+# LinkButton
+
+Updated Dec 18, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Button/v3"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-17364"
+  apiSpecification="/?path=/docs/actions-linkbutton-linkbutton-v3-api-specification--docs"
+/>
+
+<KAIOInstallation exportNames={['LinkButton']} family="actions" version="3" />
+
+## Overview
+
+`LinkButton` allows users to navigate to another page or resource. It shares the same visual styles and interaction states as the <LinkTo pageId="actions-button-button-v3-usage-guidelines--docs">Button</LinkTo> component, but is intended for navigational purposes and downloading documents.
+
+<Canvas of={LinkButton.Playground} />
+
+<Controls
+  of={LinkButton.Playground}
+  include={['href', 'variant', 'size', 'isDisabled', 'icon', 'iconPosition']}
+  className="mb-64"
+/>
diff --git a/packages/components/src/LinkButton/_docs/LinkButton.doc.stories.tsx b/packages/components/src/LinkButton/_docs/LinkButton.doc.stories.tsx
new file mode 100644
index 00000000000..302bfaa274e
--- /dev/null
+++ b/packages/components/src/LinkButton/_docs/LinkButton.doc.stories.tsx
@@ -0,0 +1,136 @@
+import React from 'react'
+import { type Meta, type StoryObj } from '@storybook/react'
+import { VisuallyHidden } from '~components/VisuallyHidden'
+import { Icon } from '~components/__rc__/Icon'
+import { LinkButton } from '../index'
+
+const meta = {
+  title: 'Components/LinkButton',
+  component: LinkButton,
+  args: {
+    children: 'Label',
+    href: '#link-button-clicked',
+  },
+  argTypes: {
+    icon: {
+      options: ['delete', 'arrow', 'plus'],
+      mapping: {
+        delete: <Icon isPresentational name="delete" />,
+        arrow: <Icon isPresentational name="arrow_forward" />,
+        add: <Icon isPresentational name="add" />,
+      },
+    },
+  },
+} satisfies Meta<typeof LinkButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+
+export const LinkButtonOpensInNewTab: Story = {
+  args: {
+    children: (
+      <>
+        Label
+        <VisuallyHidden> opens a new tab</VisuallyHidden>
+      </>
+    ),
+    href: 'https://www.google.com',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+    icon: <Icon isPresentational name="open_in_new" shouldMirrorInRTL />,
+    iconPosition: 'end',
+  },
+}
+
+export const LinkButtonVariants: Story = {
+  render: ({ children: _, ...otherArgs }) => (
+    <>
+      <LinkButton {...otherArgs} variant="primary">
+        Primary
+      </LinkButton>
+      <LinkButton {...otherArgs} variant="secondary">
+        Secondary
+      </LinkButton>
+      <LinkButton {...otherArgs} variant="tertiary">
+        Tertiary
+      </LinkButton>
+    </>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkButtonVariantsReversed: Story = {
+  ...LinkButtonVariants,
+  parameters: {
+    reverseColors: true,
+  },
+}
+
+export const LinkButtonSizes: Story = {
+  render: (args) => (
+    <>
+      <LinkButton {...args} size="small">
+        Small
+      </LinkButton>
+      <LinkButton {...args} size="medium">
+        Medium
+      </LinkButton>
+      <LinkButton {...args} size="large">
+        Large
+      </LinkButton>
+    </>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="flex gap-8 items-center">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const LinkButtonWithIconStart: Story = {
+  args: {
+    icon: <Icon isPresentational name="delete" />,
+  },
+}
+
+export const LinkButtonWithIconEnd: Story = {
+  args: {
+    icon: <Icon isPresentational name="arrow_forward" shouldMirrorInRTL />,
+    iconPosition: 'end',
+  },
+}
+
+export const IconLinkButton: Story = {
+  args: {
+    children: 'Remove highlights from: May 8, 2024',
+    icon: <Icon isPresentational name="delete" />,
+    hasHiddenLabel: true,
+  },
+}
+
+export const DownloadIconButton: Story = {
+  args: {
+    children: 'Download the kaizen design system badge',
+    href: './static/media/kaizen-badge.svg',
+    icon: <Icon isPresentational name="download" />,
+    hasHiddenLabel: true,
+    download: true,
+  },
+}
+
+export const LinkButtonFullWidth: Story = {
+  args: {
+    isFullWidth: true,
+  },
+}
diff --git a/packages/components/src/LinkButton/_docs/LinkButton.spec.stories.tsx b/packages/components/src/LinkButton/_docs/LinkButton.spec.stories.tsx
new file mode 100644
index 00000000000..e861f30cb7d
--- /dev/null
+++ b/packages/components/src/LinkButton/_docs/LinkButton.spec.stories.tsx
@@ -0,0 +1,80 @@
+import React from 'react'
+import { type Meta, type StoryObj } from '@storybook/react'
+import { expect, userEvent, waitFor, within } from '@storybook/test'
+import { VisuallyHidden } from '~components/VisuallyHidden'
+import { Icon } from '~components/__rc__/Icon'
+import { LinkButton } from '../index'
+
+const meta = {
+  title: 'Components/LinkButton/LinkButton tests',
+  component: LinkButton,
+  args: {
+    children: 'Label',
+  },
+} satisfies Meta<typeof LinkButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const IconLinkButtonWithHiddenLabel: Story = {
+  args: {
+    hasHiddenLabel: true,
+    icon: <Icon name="add" isPresentational />,
+    children: (
+      <span>
+        Hidden label <span>is</span> <span>accessible</span>
+      </span>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole('link')
+
+    expect(linkButton).toHaveAccessibleName('Hidden label is accessible')
+  },
+}
+
+export const RACRenderPropsWithChildren: Story = {
+  render: ({ children: _, ...otherArgs }) => (
+    <LinkButton {...otherArgs}>
+      {({ isFocusVisible }) => (
+        <>
+          Label
+          <VisuallyHidden>{isFocusVisible ? ' is focused' : ' is unfocused'}</VisuallyHidden>
+          <Icon
+            name={isFocusVisible ? 'thumb_up' : 'thumb_down'}
+            isPresentational
+            isFilled={true}
+            className="ms-8 [--icon-size:16]"
+          />
+        </>
+      )}
+    </LinkButton>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole('link')
+
+    await step('link icon reflects unfocused state', async () => {
+      await waitFor(() => expect(linkButton).toHaveAccessibleName('Label is unfocused'))
+    })
+
+    await step('focus on link and update icon', async () => {
+      await userEvent.tab()
+      await waitFor(() => expect(linkButton).toHaveAccessibleName('Label is focused'))
+    })
+  },
+}
+
+export const RACRenderPropsWithClassName: Story = {
+  args: {
+    className: ({ isFocusVisible }) => (isFocusVisible ? '!bg-gray-300' : ''),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.parentElement!)
+    const linkButton = canvas.getByRole('link')
+    await linkButton.focus()
+    expect(linkButton).toHaveClass('!bg-gray-300')
+  },
+}
diff --git a/packages/components/src/LinkButton/_docs/LinkButton.stickersheet.stories.tsx b/packages/components/src/LinkButton/_docs/LinkButton.stickersheet.stories.tsx
new file mode 100644
index 00000000000..356c6e5d7a7
--- /dev/null
+++ b/packages/components/src/LinkButton/_docs/LinkButton.stickersheet.stories.tsx
@@ -0,0 +1,130 @@
+import React from 'react'
+import { type Meta } from '@storybook/react'
+import { within } from '@storybook/test'
+import { Icon } from '~components/__rc__/Icon'
+import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
+import { LinkButton, type LinkButtonProps } from '../index'
+
+export default {
+  title: 'Components/LinkButton',
+  parameters: {
+    chromatic: { disable: false },
+    controls: { disable: true },
+  },
+} satisfies Meta
+
+const variants = ['primary', 'secondary', 'tertiary'] satisfies LinkButtonProps['variant'][]
+const sizes = ['small', 'medium', 'large'] satisfies LinkButtonProps['size'][]
+
+const StickerSheetTemplate: StickerSheetStory = {
+  render: ({ isReversed }) => (
+    <>
+      <StickerSheet
+        title="Button"
+        headers={['Base', 'Icon start', 'Icon end', 'hasHiddenLabel', 'isDisabled']}
+        isReversed={isReversed}
+      >
+        {variants.map((variant) =>
+          sizes.map((size) => (
+            <StickerSheet.Row
+              key={size + variant}
+              isReversed={isReversed}
+              header={`${variant} (${size})`}
+            >
+              <LinkButton variant={variant} size={size}>
+                Label
+              </LinkButton>
+              <LinkButton icon={<Icon name="add" isPresentational />} variant={variant} size={size}>
+                Label
+              </LinkButton>
+              <LinkButton
+                icon={<Icon name="arrow_forward" shouldMirrorInRTL isPresentational />}
+                iconPosition="end"
+                variant={variant}
+                size={size}
+              >
+                Label
+              </LinkButton>
+              <LinkButton
+                icon={<Icon name="delete" isPresentational />}
+                variant={variant}
+                hasHiddenLabel
+                size={size}
+              >
+                Label
+              </LinkButton>
+              <LinkButton
+                icon={<Icon name="arrow_forward" shouldMirrorInRTL isPresentational />}
+                iconPosition="end"
+                variant={variant}
+                size={size}
+                isDisabled
+              >
+                Label
+              </LinkButton>
+            </StickerSheet.Row>
+          )),
+        )}
+      </StickerSheet>
+      <StickerSheet
+        title="Pseudo states"
+        headers={['isHovered', 'isFocusVisible', 'isPressed']}
+        isReversed={isReversed}
+      >
+        {variants.map((variant) => (
+          <StickerSheet.Row key={variant} isReversed={isReversed} header={variant}>
+            <LinkButton data-testid="testid__button-hover" variant={variant}>
+              Label
+            </LinkButton>
+            <LinkButton data-testid="testid__button-focus" variant={variant}>
+              Label
+            </LinkButton>
+            <LinkButton data-testid="testid__button-pressed" variant={variant}>
+              Label
+            </LinkButton>
+          </StickerSheet.Row>
+        ))}
+      </StickerSheet>
+    </>
+  ),
+  play: ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const focusButtons = canvas.getAllByTestId('testid__button-focus')
+    const hoverButtons = canvas.getAllByTestId('testid__button-hover')
+    const pressedButton = canvas.getAllByTestId('testid__button-pressed')
+
+    focusButtons.forEach((button) => {
+      button.setAttribute('data-focus-visible', 'true')
+    })
+    hoverButtons.forEach((button) => {
+      button.setAttribute('data-hovered', 'true')
+    })
+    pressedButton.forEach((button) => {
+      button.setAttribute('data-pressed', 'true')
+    })
+  },
+}
+
+export const StickerSheetDefault: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (Default)',
+}
+
+export const StickerSheetRTL: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (RTL)',
+  parameters: {
+    textDirection: 'rtl',
+  },
+}
+
+export const StickerSheetReversed: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: 'Sticker Sheet (Reversed)',
+  parameters: {
+    reverseColors: true,
+  },
+  args: {
+    isReversed: true,
+  },
+}
diff --git a/packages/components/src/LinkButton/index.ts b/packages/components/src/LinkButton/index.ts
new file mode 100644
index 00000000000..793960cd0c1
--- /dev/null
+++ b/packages/components/src/LinkButton/index.ts
@@ -0,0 +1 @@
+export * from './LinkButton'
diff --git a/packages/components/src/__rc__/Button/Button.tsx b/packages/components/src/__rc__/Button/Button.tsx
index eaaea2eb3b7..5b9201a1de2 100644
--- a/packages/components/src/__rc__/Button/Button.tsx
+++ b/packages/components/src/__rc__/Button/Button.tsx
@@ -6,9 +6,8 @@ import { ButtonContent, PendingContent } from './subcomponents'
 import { type ButtonSizes, type ButtonVariants, type PendingButtonProps } from './types'
 import styles from './Button.module.css'
 
-type ButtonBaseProps = Omit<RACButtonProps, 'children'> & {
-  /** Used as the label for the button. */
-  children: RACButtonProps['children']
+/** Shared UI props between Button and LinkButton */
+export type ButtonUIProps = {
   /** Visually hides the Button's child content used as the label and the `pendingLabel`. Use for icon-only `Button`. @default "false" */
   hasHiddenLabel?: boolean
   /** The visual style of the button.
@@ -30,7 +29,12 @@ type ButtonBaseProps = Omit<RACButtonProps, 'children'> & {
   isReversed?: boolean
 }
 
-export type ButtonProps = ButtonBaseProps & PendingButtonProps
+export type ButtonProps = ButtonUIProps &
+  PendingButtonProps &
+  Omit<RACButtonProps, 'children'> & {
+    /** Used as the label for the button. */
+    children: RACButtonProps['children']
+  }
 
 export const Button = forwardRef(
   (
diff --git a/packages/components/src/__rc__/Button/_docs/Button--api-specification.mdx b/packages/components/src/__rc__/Button/_docs/Button--api-specification.mdx
index cb01e2e9963..c337ad0c816 100644
--- a/packages/components/src/__rc__/Button/_docs/Button--api-specification.mdx
+++ b/packages/components/src/__rc__/Button/_docs/Button--api-specification.mdx
@@ -1,5 +1,5 @@
 import { Canvas, Meta, Controls, ArgTypes, DocsStory } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
 import * as exampleStories from './Button.docs.stories'
 import * as specStories from './Button.spec.stories'
 
@@ -15,11 +15,11 @@ Updated Nov 19, 2024
   designGuidelines="/?path=/docs/actions-button-button-v3-usage-guidelines--docs"
 />
 
-<KAIOInstallation exportNames={['Button']} family="actions" version="3" />
+<KAIOInstallation exportNames={'Button'} family="actions" version="3" />
 
 ## Overview
 
-`Button` allows users to perform an action. If the component needs to navigate somewhere and can be opened in a new tab, use a [link instead](#buttons-and-links).
+`Button` allows users to perform an action. If the component needs to navigate somewhere and can be opened in a new tab, use a <LinkTo pageId="components-linkbutton-api-specification--docs">LinkButton</LinkTo> instead.
 
 The following example and table showcases the essential props that enable the core functionality of `Button`. For the remaining suite of API options refer to [this section](#additional-api-options).
 
@@ -50,7 +50,7 @@ The following example and table showcases the essential props that enable the co
 
 The `Button` component does not support the `href` property or have any inbuilt routing support. This component is intended as a semantic button and should only be used to perform actions on a page. We advise against passing in an `anchor` tag as a child of the `Button` as this can lead to accessibility issues.
 
-A `LinkButton` component will be provided in the future to handle routing and navigation use cases. In the meantime, we recommend staying on [Button V1](/docs/actions-button-button-v1--docs) if an `href` is needed.
+A separate <LinkTo pageId="components-linkbutton-api-specification--docs">LinkButton</LinkTo> component has been created to handle page navigation and client side routing.
 
 ## API
 
@@ -93,7 +93,7 @@ One key change to the `Button`&apos;s API is the shift from `onClick` to React A
 Functionally this does not change the way we pass actions into `Button`. Consumers can safely replace `onClick` with `onPress` without any additional changes, ie:
 
 ```tsx
-<Button label="Submit" onClick={(e) => sumbit(e)} />
+<Button label="Submit" onClick={(e) => submit(e)} />
 ```
 
 Can safely be replaced with the following:
diff --git a/packages/components/src/__rc__/Button/_docs/Button--usage-guidelines.mdx b/packages/components/src/__rc__/Button/_docs/Button--usage-guidelines.mdx
index 7ffe0c5fc1e..bedd644b723 100644
--- a/packages/components/src/__rc__/Button/_docs/Button--usage-guidelines.mdx
+++ b/packages/components/src/__rc__/Button/_docs/Button--usage-guidelines.mdx
@@ -1,5 +1,5 @@
 import { Canvas, Meta, Controls } from '@storybook/blocks'
-import { ResourceLinks, Installation } from '~storybook/components'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
 import * as Button from './Button.docs.stories'
 
 <Meta title="Components/Button/Button (v3)/Usage Guidelines" />
@@ -14,10 +14,7 @@ Updated July 12, 2024
   apiSpecification="/?path=/docs/actions-button-button-v3-api-specification--docs"
 />
 
-<Installation
-  installCommand="pnpm add @kaizen/components"
-  importStatement='import { Button } from "@kaizen/components/v3/actions"'
-/>
+<KAIOInstallation exportNames={['Button']} family="actions" version="3" />
 
 ## Overview
 
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index a28bf3506a2..b143f0060e8 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -30,6 +30,7 @@ export * from './KaizenProvider'
 export * from './Label'
 export * from './LabelledMessage'
 export * from './LikertScaleLegacy'
+export * from './LinkButton'
 export * from './Loading'
 export * from './Menu'
 export * from './Modal'
@@ -61,5 +62,3 @@ export * from './utils'
 export * from './VisuallyHidden'
 export * from './Well'
 export * from './Workflow'
-export * from './Menu'
-export * from './Button'