From 2902d002659c70fdf4d39fc50b97c25b5b79f64a Mon Sep 17 00:00:00 2001
From: geoquant <1237781+geoquant@users.noreply.github.com>
Date: Fri, 24 Apr 2026 15:57:39 -0700
Subject: [PATCH] docs(button): add LinkButton section

---
 .../src/components/demos/ButtonDemo.tsx       | 23 +++++++++++++++++--
 .../src/pages/components/button.mdx           | 16 +++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/packages/kumo-docs-astro/src/components/demos/ButtonDemo.tsx b/packages/kumo-docs-astro/src/components/demos/ButtonDemo.tsx
index 47992f685c..9a46642c98 100644
--- a/packages/kumo-docs-astro/src/components/demos/ButtonDemo.tsx
+++ b/packages/kumo-docs-astro/src/components/demos/ButtonDemo.tsx
@@ -1,5 +1,5 @@
-import { Button } from "@cloudflare/kumo";
-import { PlusIcon } from "@phosphor-icons/react";
+import { Button, LinkButton } from "@cloudflare/kumo";
+import { ArrowSquareOutIcon, PlusIcon } from "@phosphor-icons/react";
 
 export function ButtonBasicDemo() {
   return (
@@ -122,3 +122,22 @@ export function ButtonTitleDemo() {
     </div>
   );
 }
+
+/** Demonstrates using LinkButton for navigation actions that should look like buttons. */
+export function ButtonLinkAsButtonDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <LinkButton href="/components/link" variant="secondary">
+        Read Link docs
+      </LinkButton>
+      <LinkButton
+        href="https://developers.cloudflare.com"
+        variant="ghost"
+        icon={ArrowSquareOutIcon}
+        external
+      >
+        Cloudflare Docs
+      </LinkButton>
+    </div>
+  );
+}
diff --git a/packages/kumo-docs-astro/src/pages/components/button.mdx b/packages/kumo-docs-astro/src/pages/components/button.mdx
index 38864e5388..e9ab8ddef3 100644
--- a/packages/kumo-docs-astro/src/pages/components/button.mdx
+++ b/packages/kumo-docs-astro/src/pages/components/button.mdx
@@ -23,6 +23,7 @@ import {
   ButtonLoadingDemo,
   ButtonDisabledDemo,
   ButtonTitleDemo,
+  ButtonLinkAsButtonDemo,
 } from "~/components/demos/ButtonDemo";
 
 {/* Demo */}
@@ -216,6 +217,21 @@ export default function Example() {
   >
     <ButtonTitleDemo client:visible />
   </ComponentExample>
+
+### Link as Button
+
+<p>
+  Use `LinkButton` when the interaction should navigate somewhere but still look
+  like a button. Use `Button` for in-place actions like submitting, opening, or
+  toggling UI.
+</p>
+<ComponentExample
+  demo="ButtonLinkAsButtonDemo"
+  vrSection="link-as-button"
+  vrTitle="Link as Button"
+>
+  <ButtonLinkAsButtonDemo client:visible />
+</ComponentExample>
 </ComponentSection>
 
 {/* API Reference */}