docs(button): add LinkButton section

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>
+  );
+}

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 */}