From 6453ecdf8a9ab15e34bf111310cea71b62eabc55 Mon Sep 17 00:00:00 2001
From: Robert Gingras <developer+github@three-point-five.dev>
Date: Thu, 9 Jul 2026 08:59:35 -0400
Subject: [PATCH 1/3] fix(Button): restore pointer cursor and make ghost hover
 perceptible

Tailwind v4 preflight resets buttons to cursor: default, so Button lost
the clickable affordance (QuickAction already opts back in with
cursor-pointer; this brings Button to parity).

Ghost's hover tint moves one token step (neutral-100 -> neutral-200,
dark neutral-800 -> neutral-700, actives follow): neutral-100 on a
white page is a ~4% delta most displays cannot show, so the hover state
read as "nothing happens" and users only noticed feedback via the
active state on click.
---
 src/components/Button/Button.tsx | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 1fedec40..1d357746 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -8,7 +8,9 @@ const buttonVariants = cva(
     'inline-flex items-center justify-center gap-2',
     'font-semibold transition-all duration-200',
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
-    'disabled:pointer-events-none disabled:opacity-50',
+    // Web-app affordance: buttons look clickable. (Tailwind v4 preflight
+    // resets buttons to cursor: default; QuickAction already opts back in.)
+    'cursor-pointer disabled:pointer-events-none disabled:opacity-50',
     'active:scale-[0.98]',
   ],
   {
@@ -29,11 +31,14 @@ const buttonVariants = cva(
         ],
         ghost: [
           'bg-transparent text-neutral-600',
-          'hover:bg-neutral-100',
-          'active:bg-neutral-200',
+          // One token step stronger than before: neutral-100 on a white page
+          // is a ~4% delta most displays can't show, so hover read as
+          // "nothing happens" and users only saw the active state on click.
+          'hover:bg-neutral-200',
+          'active:bg-neutral-300',
           'dark:text-neutral-400',
-          'dark:hover:bg-neutral-800',
-          'dark:active:bg-neutral-700',
+          'dark:hover:bg-neutral-700',
+          'dark:active:bg-neutral-600',
         ],
         outline: [
           'border-2 border-primary-800 text-primary-800 bg-transparent',

From 27a000164cd728d1c8700965aba47b966f1718b7 Mon Sep 17 00:00:00 2001
From: Robert Gingras <developer@three-point-five.dev>
Date: Thu, 9 Jul 2026 09:00:44 -0400
Subject: [PATCH 2/3] feat(ButtonLink): navigation links styled as buttons

A polymorphic link that reuses buttonVariants, replacing the
<Link><Button/></Link> anti-pattern (invalid interactive-inside-
interactive HTML, double tab stop, button cursor hiding the link
pointer). Renders <a href> by default; SPA consumers pass their
router's link via `as` (react-router, Next.js) to keep client-side
navigation. Keeps native link affordances: middle-click/Ctrl+click to
a new tab, copy link address, correct assistive-technology semantics.

Deliberately a separate component rather than an `as`/`asChild` prop
on Button: links have no disabled/loading semantics, so each component
keeps an honest API.
---
 .../ButtonLink/ButtonLink.stories.tsx         | 163 ++++++++++++++++++
 src/components/ButtonLink/ButtonLink.test.tsx |  89 ++++++++++
 src/components/ButtonLink/ButtonLink.tsx      |  92 ++++++++++
 src/components/ButtonLink/index.ts            |   1 +
 src/index.ts                                  |   1 +
 tsup.config.ts                                |   1 +
 6 files changed, 347 insertions(+)
 create mode 100644 src/components/ButtonLink/ButtonLink.stories.tsx
 create mode 100644 src/components/ButtonLink/ButtonLink.test.tsx
 create mode 100644 src/components/ButtonLink/ButtonLink.tsx
 create mode 100644 src/components/ButtonLink/index.ts

diff --git a/src/components/ButtonLink/ButtonLink.stories.tsx b/src/components/ButtonLink/ButtonLink.stories.tsx
new file mode 100644
index 00000000..f83f9d86
--- /dev/null
+++ b/src/components/ButtonLink/ButtonLink.stories.tsx
@@ -0,0 +1,163 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as React from 'react';
+import { Plus, ExternalLink, ArrowLeft, Pencil } from 'lucide-react';
+import { ButtonLink } from './ButtonLink';
+
+const meta: Meta<typeof ButtonLink> = {
+  title: 'Components/Forms & Inputs/ButtonLink',
+  component: ButtonLink,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: [
+          'A navigation link styled exactly like `Button`, sharing its `buttonVariants`.',
+          '',
+          'Use it wherever a click **navigates**: it renders a real link element, so users keep',
+          'middle-click / Ctrl+click to open in a new tab, "copy link address", URL preview on',
+          'hover, and assistive technology announces it as a link. Wrapping a `<Button>` in an',
+          'anchor is invalid HTML (interactive inside interactive) and creates a double tab stop —',
+          'this component replaces that pattern.',
+          '',
+          "By default it renders `<a href>`. In single-page apps pass your router's link",
+          'component via `as` to keep client-side navigation, e.g.',
+          '`<ButtonLink as={Link} to="/users/new">…</ButtonLink>` (react-router) or',
+          '`<ButtonLink as={Link} href="/users/new">…</ButtonLink>` (Next.js).',
+          '',
+          'Buttons that *act* (submit, toggle, delete) should remain `Button`; loading and',
+          'disabled semantics intentionally do not exist on links.',
+        ].join('\n'),
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost', 'outline', 'danger', 'link'],
+      description: 'Visual style, identical to Button variants',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'icon'],
+      description: 'Size, identical to Button sizes',
+    },
+    fullWidth: {
+      control: 'boolean',
+      description: 'Stretch to the full width of the container',
+    },
+    as: {
+      control: false,
+      description:
+        "Element or component to render — defaults to 'a'; pass a router link component for SPA navigation",
+    },
+    leftIcon: {
+      control: false,
+      description: 'Icon to display before the link text',
+    },
+    rightIcon: {
+      control: false,
+      description: 'Icon to display after the link text',
+    },
+    href: {
+      control: 'text',
+      description: 'Destination URL (when rendering the default anchor)',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ButtonLink>;
+
+export const Primary: Story = {
+  args: {
+    href: '#',
+    variant: 'primary',
+    children: 'New user',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <ButtonLink href="#" variant="primary">
+        Primary
+      </ButtonLink>
+      <ButtonLink href="#" variant="secondary">
+        Secondary
+      </ButtonLink>
+      <ButtonLink href="#" variant="ghost">
+        Ghost
+      </ButtonLink>
+      <ButtonLink href="#" variant="outline">
+        Outline
+      </ButtonLink>
+      <ButtonLink href="#" variant="danger">
+        Danger
+      </ButtonLink>
+      <ButtonLink href="#" variant="link">
+        Link
+      </ButtonLink>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <ButtonLink href="#" variant="primary" leftIcon={<Plus size={16} />}>
+        New container
+      </ButtonLink>
+      <ButtonLink
+        href="#"
+        variant="ghost"
+        size="sm"
+        leftIcon={<Pencil size={16} />}
+      >
+        Edit
+      </ButtonLink>
+      <ButtonLink href="#" variant="ghost" leftIcon={<ArrowLeft size={16} />}>
+        Back
+      </ButtonLink>
+      <ButtonLink
+        href="https://ui.mieweb.org"
+        target="_blank"
+        rel="noreferrer"
+        variant="outline"
+        rightIcon={<ExternalLink size={16} />}
+      >
+        Storybook
+      </ButtonLink>
+    </div>
+  ),
+};
+
+/**
+ * `as` accepts any component — pass your router's link to keep client-side
+ * navigation. This story stubs one to stay router-agnostic.
+ */
+export const WithRouterLink: Story = {
+  render: () => {
+    // Stand-in for react-router's <Link> / Next.js <Link>
+    const RouterLink = React.forwardRef<
+      HTMLAnchorElement,
+      React.AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }
+    >(function RouterLink({ to, children, ...props }, ref) {
+      return (
+        <a ref={ref} href={to} {...props}>
+          {children}
+        </a>
+      );
+    });
+    return (
+      <ButtonLink
+        as={RouterLink}
+        to="/users/new"
+        variant="primary"
+        leftIcon={<Plus size={16} />}
+      >
+        New user (router link)
+      </ButtonLink>
+    );
+  },
+};
diff --git a/src/components/ButtonLink/ButtonLink.test.tsx b/src/components/ButtonLink/ButtonLink.test.tsx
new file mode 100644
index 00000000..c7ffc34f
--- /dev/null
+++ b/src/components/ButtonLink/ButtonLink.test.tsx
@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import * as React from 'react';
+import { screen } from '@testing-library/react';
+import { renderWithTheme } from '../../test/test-utils';
+import { ButtonLink } from './ButtonLink';
+
+describe('ButtonLink', () => {
+  it('renders an anchor with href by default', () => {
+    renderWithTheme(
+      <ButtonLink href="/docs" variant="primary">
+        Docs
+      </ButtonLink>
+    );
+    const link = screen.getByRole('link', { name: /docs/i });
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', '/docs');
+  });
+
+  it('applies the shared button variant and size classes', () => {
+    renderWithTheme(
+      <ButtonLink href="#" variant="ghost" size="sm">
+        Edit
+      </ButtonLink>
+    );
+    const link = screen.getByRole('link');
+    expect(link).toHaveClass('bg-transparent');
+    expect(link).toHaveClass('h-8');
+    expect(link).toHaveAttribute('data-slot', 'button');
+    expect(link).toHaveAttribute('data-size', 'sm');
+  });
+
+  it('merges a custom className after the variant classes', () => {
+    renderWithTheme(
+      <ButtonLink href="#" variant="ghost" className="bg-red-100">
+        Danger-ish
+      </ButtonLink>
+    );
+    const link = screen.getByRole('link');
+    // tailwind-merge keeps the custom background and drops the variant's
+    expect(link).toHaveClass('bg-red-100');
+    expect(link).not.toHaveClass('bg-transparent');
+  });
+
+  it('renders through a custom component via `as` (router links)', () => {
+    const RouterLink = React.forwardRef<
+      HTMLAnchorElement,
+      React.AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }
+    >(function RouterLink({ to, children, ...props }, ref) {
+      return (
+        <a ref={ref} href={to} data-testid="router-link" {...props}>
+          {children}
+        </a>
+      );
+    });
+
+    renderWithTheme(
+      <ButtonLink as={RouterLink} to="/users/new" variant="primary">
+        New user
+      </ButtonLink>
+    );
+    const link = screen.getByTestId('router-link');
+    expect(link).toHaveAttribute('href', '/users/new');
+    expect(link).toHaveClass('bg-primary-800');
+  });
+
+  it('renders left and right icons in shrink-0 wrappers', () => {
+    renderWithTheme(
+      <ButtonLink
+        href="#"
+        leftIcon={<svg data-testid="left" />}
+        rightIcon={<svg data-testid="right" />}
+      >
+        Iconic
+      </ButtonLink>
+    );
+    expect(screen.getByTestId('left').parentElement).toHaveClass('shrink-0');
+    expect(screen.getByTestId('right').parentElement).toHaveClass('shrink-0');
+  });
+
+  it('forwards refs to the underlying element', () => {
+    const ref = React.createRef<HTMLAnchorElement>();
+    renderWithTheme(
+      <ButtonLink href="#" ref={ref}>
+        Ref
+      </ButtonLink>
+    );
+    expect(ref.current).toBeInstanceOf(HTMLAnchorElement);
+  });
+});
diff --git a/src/components/ButtonLink/ButtonLink.tsx b/src/components/ButtonLink/ButtonLink.tsx
new file mode 100644
index 00000000..68eed277
--- /dev/null
+++ b/src/components/ButtonLink/ButtonLink.tsx
@@ -0,0 +1,92 @@
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+import { cn } from '../../utils/cn';
+import { buttonVariants } from '../Button/Button';
+
+type ButtonLinkOwnProps = VariantProps<typeof buttonVariants> & {
+  /**
+   * Element or component to render. Defaults to a plain anchor; pass a
+   * client-side router's link component (react-router `Link`, Next.js `Link`,
+   * …) to keep SPA navigation.
+   */
+  as?: React.ElementType;
+  /** Optional icon element to render before the link text */
+  leftIcon?: React.ReactElement | null;
+  /** Optional icon element to render after the link text */
+  rightIcon?: React.ReactElement | null;
+};
+
+export type ButtonLinkProps<T extends React.ElementType = 'a'> =
+  ButtonLinkOwnProps & { as?: T } & Omit<
+      React.ComponentPropsWithoutRef<T>,
+      keyof ButtonLinkOwnProps
+    >;
+
+type ButtonLinkComponent = (<T extends React.ElementType = 'a'>(
+  props: ButtonLinkProps<T> & { ref?: React.ComponentPropsWithRef<T>['ref'] }
+) => React.ReactNode) & { displayName?: string };
+
+/**
+ * A navigation link styled exactly like {@link Button}. Use this instead of
+ * wrapping a `<Button>` in an anchor or router link: nesting interactive
+ * elements is invalid HTML, produces a double tab stop, and hides the link
+ * cursor behind the button's. Because it renders a real link it keeps native
+ * link affordances — middle-click / Ctrl+click to open in a new tab, copy
+ * link address, correct semantics for assistive technology.
+ *
+ * Deliberately not a `Button` prop (`as`/`asChild`): buttons and links have
+ * different disabled/loading semantics, so each keeps its own honest API.
+ *
+ * @example
+ * ```tsx
+ * <ButtonLink href="/docs" variant="outline">Docs</ButtonLink>
+ *
+ * // With a client-side router (react-router shown):
+ * <ButtonLink as={Link} to="/users/new" variant="primary" leftIcon={<Plus />}>
+ *   New user
+ * </ButtonLink>
+ * ```
+ */
+const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
+  function ButtonLink(
+    {
+      as,
+      className,
+      variant,
+      size,
+      fullWidth,
+      leftIcon,
+      rightIcon,
+      children,
+      ...props
+    },
+    ref
+  ) {
+    const Comp: React.ElementType = as ?? 'a';
+    const resolvedSize = size ?? 'md';
+    return (
+      <Comp
+        data-slot="button"
+        data-size={resolvedSize}
+        className={cn(
+          buttonVariants({ variant, size: resolvedSize, fullWidth }),
+          className
+        )}
+        ref={ref}
+        {...props}
+      >
+        {React.isValidElement(leftIcon) && (
+          <span className="shrink-0">{leftIcon}</span>
+        )}
+        {children}
+        {React.isValidElement(rightIcon) && (
+          <span className="shrink-0">{rightIcon}</span>
+        )}
+      </Comp>
+    );
+  }
+) as unknown as ButtonLinkComponent;
+
+ButtonLink.displayName = 'ButtonLink';
+
+export { ButtonLink };
diff --git a/src/components/ButtonLink/index.ts b/src/components/ButtonLink/index.ts
new file mode 100644
index 00000000..6269ef3e
--- /dev/null
+++ b/src/components/ButtonLink/index.ts
@@ -0,0 +1 @@
+export { ButtonLink, type ButtonLinkProps } from './ButtonLink';
diff --git a/src/index.ts b/src/index.ts
index 00b344d4..142aca3b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -23,6 +23,7 @@ export * from './components/Breadcrumb';
 export * from './components/BusinessHours';
 export * from './components/BusinessHoursEditor';
 export * from './components/Button';
+export * from './components/ButtonLink';
 export * from './components/Card';
 export * from './components/Checkbox';
 export * from './components/CheckrIntegration';
diff --git a/tsup.config.ts b/tsup.config.ts
index dbcc24e1..01144fb0 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -20,6 +20,7 @@ export default defineConfig({
     'components/Badge/index': 'src/components/Badge/index.ts',
     'components/Breadcrumb/index': 'src/components/Breadcrumb/index.ts',
     'components/Button/index': 'src/components/Button/index.ts',
+    'components/ButtonLink/index': 'src/components/ButtonLink/index.ts',
     'components/Card/index': 'src/components/Card/index.ts',
     'components/Checkbox/index': 'src/components/Checkbox/index.ts',
     'components/Collapsible/index': 'src/components/Collapsible/index.ts',

From a6a0ed5938820191252134e5826ff63632ba9b98 Mon Sep 17 00:00:00 2001
From: Robert Gingras <developer@three-point-five.dev>
Date: Thu, 9 Jul 2026 09:00:45 -0400
Subject: [PATCH 3/3] fix(styles): apply hover styles unconditionally

Tailwind v4 gates the built-in hover variant behind
@media (hover: hover). Browsers in VMs, remote desktops, and some
touchscreen laptops misreport pointer capability as hover-incapable,
silently disabling every hover style in the compiled CSS while :hover
itself still matches mouse movement. MIE apps are mouse-first, so opt
out of the capability gate via @custom-variant, next to the existing
dark variant. Tradeoff is the standard pre-v4 behavior: hover styles
can linger after a tap on touch devices.
---
 src/styles/base.css | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/styles/base.css b/src/styles/base.css
index 73aebe88..07512d98 100644
--- a/src/styles/base.css
+++ b/src/styles/base.css
@@ -6,6 +6,15 @@
 
 @custom-variant dark (&:where(.dark, [data-theme=dark], .dark *, [data-theme=dark] *));
 
+/* Apply hover: styles unconditionally. Tailwind v4 gates the built-in hover
+ * variant behind @media (hover: hover); browsers in VMs, remote desktops, and
+ * some touchscreen laptops misreport pointer capability as hover-incapable,
+ * which silently disables every hover style while :hover itself still matches
+ * mouse movement. MIE apps are mouse-first, so opt out of the capability gate
+ * (the tradeoff is the standard pre-v4 behavior: hover styles can linger
+ * after a tap on touch devices). */
+@custom-variant hover (&:hover);
+
 /* Hide DataVis slider from layout when closed to prevent horizontal overflow */
 .wcdv-slider[aria-hidden='true'] {
   display: none;