feat: refactor Button component for improved clarity and semantic naming conventions

kelvink96 · kelvink96 · commit 58fa6cf0201f · 2025-12-31T01:59:35.000+03:00
diff --git a/apps/docs/stories/button.stories.tsx b/apps/docs/stories/button.stories.tsx
@@ -18,12 +18,19 @@ const meta: Meta<typeof Button> = {
   argTypes: {
     variant: {
       control: "select",
-      options: ["primary", "secondary", "outline", "ghost", "destructive"],
+      options: [
+        "default",
+        "destructive",
+        "outline",
+        "secondary",
+        "ghost",
+        "link",
+      ],
       description: "The visual style variant of the button",
     },
     size: {
       control: "select",
-      options: ["sm", "md", "lg", "icon"],
+      options: ["default", "sm", "lg", "icon", "icon-sm", "icon-lg"],
       description: "The size of the button",
     },
     asChild: {
@@ -41,13 +48,13 @@ export default meta;
 type Story = StoryObj<typeof Button>;
 
 /**
- * Default Primary Button
+ * Default Button
  */
-export const Primary: Story = {
+export const Default: Story = {
   args: {
-    children: "Primary Button",
-    variant: "primary",
-    size: "md",
+    children: "Button",
+    variant: "default",
+    size: "default",
   },
 };
 
@@ -111,6 +118,18 @@ export const Large: Story = {
   },
 };
 
+/**
+ * Link Variant
+ *
+ * Renders as a text link with underline on hover
+ */
+export const Link: Story = {
+  args: {
+    children: "Link Button",
+    variant: "link",
+  },
+};
+
 /**
  * Icon Button (Square)
  */
@@ -121,6 +140,26 @@ export const Icon: Story = {
   },
 };
 
+/**
+ * Small Icon Button
+ */
+export const IconSmall: Story = {
+  args: {
+    children: "×",
+    size: "icon-sm",
+  },
+};
+
+/**
+ * Large Icon Button
+ */
+export const IconLarge: Story = {
+  args: {
+    children: "☰",
+    size: "icon-lg",
+  },
+};
+
 /**
  * Disabled State
  */
@@ -158,11 +197,12 @@ export const AsLink: Story = {
 export const AllVariants: Story = {
   render: () => (
     <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
-      <Button variant="primary">Primary</Button>
-      <Button variant="secondary">Secondary</Button>
+      <Button variant="default">Default</Button>
+      <Button variant="destructive">Destructive</Button>
       <Button variant="outline">Outline</Button>
+      <Button variant="secondary">Secondary</Button>
       <Button variant="ghost">Ghost</Button>
-      <Button variant="destructive">Destructive</Button>
+      <Button variant="link">Link</Button>
     </div>
   ),
 };
@@ -174,11 +214,32 @@ export const AllVariants: Story = {
  */
 export const AllSizes: Story = {
   render: () => (
-    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+    <div
+      style={{
+        display: "flex",
+        gap: "1rem",
+        alignItems: "center",
+        flexWrap: "wrap",
+      }}
+    >
       <Button size="sm">Small</Button>
-      <Button size="md">Medium</Button>
+      <Button size="default">Default</Button>
       <Button size="lg">Large</Button>
+    </div>
+  ),
+};
+
+/**
+ * All Icon Sizes Showcase
+ *
+ * Shows all icon button sizes side by side
+ */
+export const AllIconSizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Button size="icon-sm">×</Button>
       <Button size="icon">→</Button>
+      <Button size="icon-lg">☰</Button>
     </div>
   ),
 };
diff --git a/packages/react/src/components/button/button.spec.tsx b/packages/react/src/components/button/button.spec.tsx
@@ -35,11 +35,12 @@ describe("Button", () => {
 
     it("renders all variant options", () => {
       const variants = [
-        "primary",
-        "secondary",
+        "default",
+        "destructive",
         "outline",
+        "secondary",
         "ghost",
-        "destructive",
+        "link",
       ] as const;
 
       variants.forEach((variant) => {
@@ -51,7 +52,14 @@ describe("Button", () => {
     });
 
     it("renders all size options", () => {
-      const sizes = ["sm", "md", "lg", "icon"] as const;
+      const sizes = [
+        "default",
+        "sm",
+        "lg",
+        "icon",
+        "icon-sm",
+        "icon-lg",
+      ] as const;
 
       sizes.forEach((size) => {
         const { container } = render(<Button size={size}>Button</Button>);
@@ -162,6 +170,27 @@ describe("Button", () => {
     });
   });
 
+  describe("Link Variant", () => {
+    it("renders link variant with underline styles", () => {
+      const { container } = render(<Button variant="link">Link Button</Button>);
+      const button = container.firstChild as HTMLElement;
+      expect(button).toHaveClass("text-primary-500");
+      expect(button).toHaveClass("underline-offset-4");
+    });
+
+    it("link variant can be used with asChild for actual links", () => {
+      render(
+        <Button asChild variant="link">
+          <a href="/docs">Read Docs</a>
+        </Button>,
+      );
+
+      const link = screen.getByRole("link", { name: /read docs/i });
+      expect(link).toBeInTheDocument();
+      expect(link).toHaveAttribute("href", "/docs");
+    });
+  });
+
   describe("Polymorphism (asChild)", () => {
     it("renders as a link when asChild is true", () => {
       render(
@@ -177,7 +206,7 @@ describe("Button", () => {
 
     it("applies button styles to child element", () => {
       const { container } = render(
-        <Button asChild variant="primary">
+        <Button asChild variant="default">
           <a href="/home">Link</a>
         </Button>,
       );
diff --git a/packages/react/src/components/button/button.tsx b/packages/react/src/components/button/button.tsx
@@ -46,45 +46,62 @@ const buttonVariants = cva(
        *
        * These use our design tokens from \@prism/tokens
        * mapped through Tailwind's \@theme directive
+       *
+       * Educational Note:
+       * - 'default' is the primary action style (instead of 'primary')
+       * - 'link' renders as text with underline, useful for in-text actions
+       * - shadcn/ui uses this naming convention for better semantic clarity
        */
       variant: {
-        primary: [
+        default: [
           "bg-primary-500 text-white",
           "hover:bg-primary-600",
           "focus-visible:ring-primary-500",
         ].join(" "),
-        secondary: [
-          "bg-neutral-200 text-neutral-900",
-          "hover:bg-neutral-300",
-          "focus-visible:ring-neutral-500",
+        destructive: [
+          "bg-error-main text-white",
+          "hover:bg-error-dark",
+          "focus-visible:ring-error-main",
         ].join(" "),
         outline: [
           "border-2 border-neutral-300 bg-transparent",
           "hover:bg-neutral-100",
           "focus-visible:ring-neutral-500",
         ].join(" "),
+        secondary: [
+          "bg-neutral-200 text-neutral-900",
+          "hover:bg-neutral-300",
+          "focus-visible:ring-neutral-500",
+        ].join(" "),
         ghost: [
           "bg-transparent",
           "hover:bg-neutral-100",
           "focus-visible:ring-neutral-500",
         ].join(" "),
-        destructive: [
-          "bg-error-main text-white",
-          "hover:bg-error-dark",
-          "focus-visible:ring-error-main",
+        link: [
+          "text-primary-500 underline-offset-4",
+          "hover:underline",
+          "focus-visible:ring-0", // Links don't need ring focus, underline is enough
         ].join(" "),
       },
 
       /**
        * Size variants
        *
        * Use spacing tokens from \@prism/tokens
+       *
+       * Educational Note:
+       * - Icon buttons are square (equal width/height)
+       * - Icon sizes (sm, md, lg) match their text button counterparts
+       * - This creates visual consistency across your UI
        */
       size: {
+        default: "h-10 px-4 text-base",
         sm: "h-8 px-3 text-sm",
-        md: "h-10 px-4 text-base",
         lg: "h-12 px-6 text-lg",
-        icon: "h-10 w-10", // Square button for icons
+        icon: "h-10 w-10", // Default icon size
+        "icon-sm": "h-8 w-8", // Small icon button
+        "icon-lg": "h-12 w-12", // Large icon button
       },
     },
 
@@ -94,8 +111,8 @@ const buttonVariants = cva(
      * Applied when no variant props are specified
      */
     defaultVariants: {
-      variant: "primary",
-      size: "md",
+      variant: "default",
+      size: "default",
     },
   },
 );
diff --git a/packages/vitest-config/react.ts b/packages/vitest-config/react.ts
@@ -13,15 +13,15 @@
 import { defineConfig, mergeConfig } from "vitest/config";
 import react from "@vitejs/plugin-react";
 
-import baseConfig from "./base";
+import baseConfig from "@prism/vitest-config/base";
 
 export default mergeConfig(
   baseConfig,
   defineConfig({
     plugins: [react()],
 
     test: {
-      // Use happy-dom for React component testing
+      // Use happy-dom for React component testing/
       // Faster and lighter than jsdom
       environment: "happy-dom",
 
