@tribepad/themis 1.0.0

package/src/elements/Button/Button.stories.tsx

@@ -0,0 +1,670 @@
+/**
+ * Button Component Stories
+ * Storybook stories for Button component demonstrating all variants, sizes, and states
+ *
+ * @see spec.md FR-029 to FR-037 (Button Component Requirements)
+ * @see spec.md FR-045 (Storybook stories requirement)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Button } from './Button';
+import { Trash2, Save, Download, Settings } from 'lucide-react';
+
+const meta = {
+  title: 'Elements/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Accessible button component with React Aria primitives, CVA variant styling, and WCAG 2.2 AAA compliance (7:1 contrast ratio, 44x44px touch targets).',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'],
+      description: 'Button style variant',
+      table: {
+        defaultValue: { summary: 'default' },
+      },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg', 'icon'],
+      description: 'Button size (deprecated - use visualSize for independent sizing)',
+      table: {
+        defaultValue: { summary: 'default' },
+      },
+    },
+    visualSize: {
+      control: 'select',
+      options: ['sm', 'default', 'lg', 'icon', 'dot'],
+      description: 'Visual size of the button (Layer 2). Defaults to size. Use for small visual buttons with large touch targets.',
+      table: {
+        defaultValue: { summary: 'size value' },
+      },
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Show loading spinner',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disable button interaction',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    loadingText: {
+      control: 'text',
+      description: 'Screen reader text during loading',
+      table: {
+        defaultValue: { summary: 'Loading...' },
+      },
+    },
+    shortcut: {
+      control: 'text',
+      description: 'Keyboard shortcut to display on focus (shown only on focus)',
+    },
+    paywall: {
+      control: 'boolean',
+      description: 'Enable paywall state - overrides variant styling with premium appearance',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    paywallRedirect: {
+      control: 'text',
+      description: 'URL to open in new tab when paywalled button is clicked',
+    },
+    paywallDescription: {
+      control: 'text',
+      description: 'Screen reader description for the premium feature (max 200 chars)',
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Default story
+export const Default: Story = {
+  args: {
+    children: 'Button',
+    variant: 'default',
+    size: 'default',
+  },
+};
+
+// Variant stories
+export const Destructive: Story = {
+  args: {
+    children: 'Delete',
+    variant: 'destructive',
+  },
+};
+
+export const Outline: Story = {
+  args: {
+    children: 'Outline',
+    variant: 'outline',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: 'Secondary',
+    variant: 'secondary',
+  },
+};
+
+export const Ghost: Story = {
+  args: {
+    children: 'Ghost',
+    variant: 'ghost',
+  },
+};
+
+export const Link: Story = {
+  args: {
+    children: 'Link',
+    variant: 'link',
+  },
+};
+
+// Size stories
+export const Small: Story = {
+  args: {
+    children: 'Small Button',
+    size: 'sm',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    children: 'Large Button',
+    size: 'lg',
+  },
+};
+
+export const Icon: Story = {
+  args: {
+    children: <Settings />,
+    size: 'icon',
+    'aria-label': 'Settings',
+  },
+};
+
+// State stories
+export const Loading: Story = {
+  args: {
+    children: 'Loading',
+    loading: true,
+  },
+};
+
+export const LoadingWithCustomText: Story = {
+  args: {
+    children: 'Save Changes',
+    loading: true,
+    loadingText: 'Saving your changes...',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    children: 'Disabled',
+    isDisabled: true,
+  },
+};
+
+// Feature stories
+export const WithShortcut: Story = {
+  args: {
+    children: 'Save',
+    shortcut: '⌘S',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Press Tab to focus the button and see the keyboard shortcut appear.',
+      },
+    },
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    children: (
+      <>
+        <Download />
+        Download
+      </>
+    ),
+  },
+};
+
+// Grid of all variants
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap gap-4">
+        <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="link">Link</Button>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All 6 button variants in one view.',
+      },
+    },
+  },
+};
+
+// Grid of all sizes
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button size="sm">Small</Button>
+      <Button size="default">Default</Button>
+      <Button size="lg">Large</Button>
+      <Button size="icon" aria-label="Settings">
+        <Settings />
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All 4 button sizes in one view.',
+      },
+    },
+  },
+};
+
+// Theme integration stories
+export const LightTheme: Story = {
+  args: {
+    children: 'Light Theme Button',
+  },
+  parameters: {
+    backgrounds: { default: 'light' },
+  },
+};
+
+export const DarkTheme: Story = {
+  args: {
+    children: 'Dark Theme Button',
+  },
+  parameters: {
+    backgrounds: { default: 'dark' },
+    docs: {
+      description: {
+        story: 'Button adapts to dark theme via semantic tokens.',
+      },
+    },
+  },
+};
+
+export const HighContrast: Story = {
+  args: {
+    children: 'High Contrast Button',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Button with enhanced outlines for high contrast mode.',
+      },
+    },
+  },
+};
+
+export const ColorblindTheme: Story = {
+  args: {
+    children: 'Colorblind Theme Button',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Button with colorblind-friendly palette (deuteranopia, protanopia, tritanopia support).',
+      },
+    },
+  },
+};
+
+// Real-world examples
+export const FormSubmit: Story = {
+  render: () => (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        alert('Form submitted!');
+      }}
+    >
+      <div className="flex flex-col gap-4">
+        <input
+          type="text"
+          placeholder="Enter your name"
+          className="rounded-md border border-input px-3 py-2"
+        />
+        <Button type="submit">Submit</Button>
+      </div>
+    </form>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Button used as a form submit button.',
+      },
+    },
+  },
+};
+
+export const DeleteConfirmation: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Button variant="outline">Cancel</Button>
+      <Button
+        variant="destructive"
+        onPress={() => alert('Account deleted!')}
+      >
+        <Trash2 />
+        Delete Account
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Destructive action with confirmation pattern.',
+      },
+    },
+  },
+};
+
+export const SaveWithShortcut: Story = {
+  render: () => (
+    <Button
+      shortcut="⌘S"
+      onPress={() => alert('Changes saved!')}
+    >
+      <Save />
+      Save Changes
+    </Button>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Save button with keyboard shortcut hint (visible on focus).',
+      },
+    },
+  },
+};
+
+// Accessibility stories
+export const FocusVisible: Story = {
+  args: {
+    children: 'Focus Me',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Press Tab to see the focus ring. Meets WCAG 2.2 AAA standards with visible focus indicator.',
+      },
+    },
+  },
+};
+
+export const TouchTarget: Story = {
+  args: {
+    children: 'Touch',
+    size: 'sm',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Even small buttons have 44x44px minimum touch targets (exceeds WCAG 2.2 requirement).',
+      },
+    },
+  },
+};
+
+// Paywall stories
+export const Paywall: Story = {
+  args: {
+    children: 'Premium Feature',
+    paywall: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Paywall state indicates a premium feature. Button is visually distinct with golden styling and lightning bolt icon. Clicking does not trigger onPress.',
+      },
+    },
+  },
+};
+
+export const PaywallWithRedirect: Story = {
+  args: {
+    children: 'Upgrade to Pro',
+    paywall: true,
+    paywallRedirect: '/pricing',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Paywalled button with redirect. Clicking opens the upgrade page in a new tab.',
+      },
+    },
+  },
+};
+
+export const PaywallWithDescription: Story = {
+  args: {
+    children: 'AI Analysis',
+    paywall: true,
+    paywallDescription: 'Unlock AI-powered candidate analysis with Pro plan',
+    paywallRedirect: '/pricing?feature=ai-analysis',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Paywall with custom description for screen readers. The description is announced when the button receives focus.',
+      },
+    },
+  },
+};
+
+export const PaywallVariantOverrides: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap gap-4">
+        <Button variant="default" paywall>Default</Button>
+        <Button variant="destructive" paywall>Destructive</Button>
+        <Button variant="outline" paywall>Outline</Button>
+        <Button variant="secondary" paywall>Secondary</Button>
+        <Button variant="ghost" paywall>Ghost</Button>
+        <Button variant="link" paywall>Link</Button>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Paywall state overrides all variant styling with consistent golden appearance.',
+      },
+    },
+  },
+};
+
+export const PaywallAllSizes: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button size="sm" paywall>Small</Button>
+      <Button size="default" paywall>Default</Button>
+      <Button size="lg" paywall>Large</Button>
+      <Button size="icon" paywall aria-label="Premium Settings">
+        <Settings />
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Paywall state works with all button sizes.',
+      },
+    },
+  },
+};
+
+export const PaywallRealWorld: Story = {
+  render: () => (
+    <div className="rounded-lg border border-[var(--border)] p-6">
+      <h3 className="mb-4 text-lg font-semibold">Candidate Report</h3>
+      <div className="flex flex-col gap-3">
+        <Button variant="outline">View Basic Info</Button>
+        <Button variant="outline">Download Resume</Button>
+        <Button
+          paywall
+          paywallRedirect="/pricing?feature=ai-analysis"
+          paywallDescription="AI-powered candidate scoring and skill matching"
+        >
+          Generate AI Analysis
+        </Button>
+        <Button
+          paywall
+          paywallRedirect="/pricing?feature=background-check"
+          paywallDescription="Automated background verification"
+        >
+          Run Background Check
+        </Button>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Real-world example showing free and premium features side by side.',
+      },
+    },
+  },
+};
+
+// Visual Size stories (3-Layer Architecture)
+export const VisualSizeDot: Story = {
+  args: {
+    visualSize: 'dot',
+    variant: 'default',
+    'aria-label': 'Go to slide 1',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Small dot visual (12px) with full 44x44px touch target. Ideal for carousel navigation indicators.',
+      },
+    },
+  },
+};
+
+export const VisualSizeVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-6">
+      <div className="flex flex-col items-center gap-2">
+        <Button visualSize="dot" aria-label="Dot" />
+        <span className="text-xs text-[var(--muted-foreground)]">dot</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Button visualSize="sm">Sm</Button>
+        <span className="text-xs text-[var(--muted-foreground)]">sm</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Button visualSize="default">Default</Button>
+        <span className="text-xs text-[var(--muted-foreground)]">default</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Button visualSize="lg">Large</Button>
+        <span className="text-xs text-[var(--muted-foreground)]">lg</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Button visualSize="icon" aria-label="Icon"><Settings /></Button>
+        <span className="text-xs text-[var(--muted-foreground)]">icon</span>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All visual size options. Each button has a 44x44px touch target regardless of visual size.',
+      },
+    },
+  },
+};
+
+export const IndependentSizing: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center gap-4">
+        <span className="w-40 text-sm">Default button:</span>
+        <Button>Normal Button</Button>
+      </div>
+      <div className="flex items-center gap-4">
+        <span className="w-40 text-sm">size="lg":</span>
+        <Button size="lg">Large Button</Button>
+      </div>
+      <div className="flex items-center gap-4">
+        <span className="w-40 text-sm">visualSize="dot":</span>
+        <Button visualSize="dot" aria-label="Dot indicator" />
+        <span className="text-xs text-[var(--muted-foreground)]">(44x44 touch, 12px visual)</span>
+      </div>
+      <div className="flex items-center gap-4">
+        <span className="w-40 text-sm">size="lg" visualSize="sm":</span>
+        <Button size="lg" visualSize="sm">Small Visual</Button>
+        <span className="text-xs text-[var(--muted-foreground)]">(visualSize overrides size)</span>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the difference between `size` and `visualSize` props. The touch target is always 44x44px, but `visualSize` controls the visual appearance.',
+      },
+    },
+  },
+};
+
+export const CarouselNavigation: Story = {
+  render: () => {
+    const currentSlide = 2;
+    return (
+      <div className="flex flex-col items-center gap-4 rounded-lg bg-[var(--muted)] p-6">
+        <div className="mb-2 text-sm text-[var(--muted-foreground)]">Carousel Navigation Example</div>
+        <div className="h-32 w-64 rounded-lg bg-[var(--background)] flex items-center justify-center">
+          <span className="text-[var(--muted-foreground)]">Slide {currentSlide + 1}</span>
+        </div>
+        <div className="flex">
+          {[0, 1, 2, 3, 4].map((i) => (
+            <Button
+              key={i}
+              visualSize="dot"
+              variant={i === currentSlide ? 'default' : 'secondary'}
+              aria-label={`Go to slide ${i + 1}`}
+              aria-current={i === currentSlide ? 'true' : undefined}
+            />
+          ))}
+        </div>
+        <p className="mt-2 text-xs text-[var(--muted-foreground)]">
+          Each dot has a 44x44px touch target but only 12px visual size
+        </p>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Real-world carousel navigation using dot buttons. Each indicator has a 44x44px touch target (WCAG AAA compliant) but a small visual footprint.',
+      },
+    },
+  },
+};
+
+export const ThreeLayerArchitecture: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="rounded-lg border border-[var(--border)] p-4">
+        <h4 className="mb-2 font-medium">3-Layer Architecture</h4>
+        <ul className="mb-4 text-sm text-[var(--muted-foreground)] list-disc pl-4 space-y-1">
+          <li><strong>Layer 1:</strong> Touch Target (44x44px, transparent) - handles accessibility</li>
+          <li><strong>Layer 2:</strong> Visual Button - colors, size, borders</li>
+          <li><strong>Layer 3:</strong> Content - text, icons, effects</li>
+        </ul>
+        <div className="flex gap-4">
+          <Button>Default</Button>
+          <Button visualSize="sm">Small Visual</Button>
+          <Button visualSize="dot" aria-label="Dot" />
+        </div>
+      </div>
+      <p className="text-xs text-[var(--muted-foreground)]">
+        All buttons above have the same 44x44px touch target. Open DevTools to inspect the layer structure.
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Explains the 3-layer architecture. The touch target (Layer 1) is always 44x44px for accessibility. The visual button (Layer 2) can be any size. Content (Layer 3) sits inside the visual layer.',
+      },
+    },
+  },
+};