diff --git a/src/components/Dashboard/Dashboard.stories.tsx b/src/components/Dashboard/Dashboard.stories.tsx
index 43022ac1..e50bfc63 100644
--- a/src/components/Dashboard/Dashboard.stories.tsx
+++ b/src/components/Dashboard/Dashboard.stories.tsx
@@ -1453,7 +1453,7 @@ function ProfilePage({ user }: ProfilePageProps) {
                 <div className="flex items-center gap-2">
                   <RecordButton
                     size="sm"
-                    variant="filled"
+                    variant="default"
                     transcriptionState={bioTranscriptionState}
                     showTranscriptionState
                     onRecordingComplete={handleBioRecording}
@@ -1641,7 +1641,7 @@ function VoiceNotesPage() {
               <div className="absolute right-3 bottom-3">
                 <RecordButton
                   size="md"
-                  variant="filled"
+                  variant="default"
                   transcriptionState={quickNoteState}
                   showDuration
                   onRecordingComplete={handleQuickNoteRecording}
diff --git a/src/components/RecordButton/RecordButton.stories.tsx b/src/components/RecordButton/RecordButton.stories.tsx
index 131b9d22..e8b911cd 100644
--- a/src/components/RecordButton/RecordButton.stories.tsx
+++ b/src/components/RecordButton/RecordButton.stories.tsx
@@ -1,8 +1,15 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import * as React from 'react';
-import { RecordButton, type TranscriptionState } from './RecordButton';
+import {
+  RecordButton,
+  type RecordButtonState,
+  type RecordButtonVariant,
+  type RecordButtonSize,
+  type TranscriptionState,
+} from './RecordButton';
 import { Input } from '../Input';
 import { Textarea } from '../Textarea';
+import { AudioPlayer } from '../AudioPlayer';
 
 // ============================================================================
 // Mock Transcription Service
@@ -127,161 +134,324 @@ function useMockStreamingTranscription() {
 }
 
 // ============================================================================
-// Transcription Textarea Component
+// State Card Component
 // ============================================================================
 
-interface TranscriptionTextareaProps {
-  value: string;
-  onChange: (value: string) => void;
-  placeholder?: string;
-  transcriptionState: TranscriptionState;
-  streamingText?: string;
-  rows?: number;
-  className?: string;
+function StateCard({
+  state,
+  label,
+  description,
+  variant = 'default',
+  size = 'md',
+  showWaveform,
+  showPulse,
+}: {
+  state: RecordButtonState;
+  label: string;
+  description: string;
+  variant?: RecordButtonVariant;
+  size?: RecordButtonSize;
+  showWaveform?: boolean;
+  showPulse?: boolean;
+}) {
+  return (
+    <div className="bg-card flex flex-col items-center gap-3 rounded-xl border p-4">
+      <RecordButton
+        state={state}
+        variant={variant}
+        size={size}
+        showWaveform={showWaveform}
+        showPulse={showPulse}
+      />
+      <div className="space-y-0.5 text-center">
+        <p className="text-sm font-medium">{label}</p>
+        <p className="text-muted-foreground max-w-[140px] text-xs">
+          {description}
+        </p>
+      </div>
+    </div>
+  );
 }
 
-/**
- * A textarea that handles transcription states gracefully.
- * Shows appropriate UI for transcribing, streaming, and idle states.
- */
-function TranscriptionTextarea({
-  value,
-  onChange,
-  placeholder = 'Type or record a message...',
-  transcriptionState,
-  streamingText,
-  rows = 3,
-  className,
-}: TranscriptionTextareaProps) {
-  const isTranscribing = transcriptionState === 'transcribing';
-  const isStreaming = transcriptionState === 'streaming';
-  const isProcessing = isTranscribing || isStreaming;
-
-  // Display streaming text when available, otherwise show value
-  const displayValue = isStreaming && streamingText ? streamingText : value;
-
-  // Determine placeholder based on state
-  const getPlaceholder = () => {
-    if (isTranscribing) return 'Transcribing your audio...';
-    if (isStreaming) return '';
-    return placeholder;
+// ============================================================================
+// Variant Row Component
+// ============================================================================
+
+function VariantRow({
+  variant,
+  label,
+}: {
+  variant: RecordButtonVariant;
+  label: string;
+}) {
+  const states: RecordButtonState[] = [
+    'idle',
+    'recording',
+    'processing',
+    'disabled',
+    'error',
+    'success',
+  ];
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-2">
+        <span className="text-sm font-medium">{label}</span>
+        <code className="bg-muted rounded px-1.5 py-0.5 text-xs">
+          variant=&quot;{variant}&quot;
+        </code>
+      </div>
+      <div className="flex flex-wrap gap-4">
+        {states.map((state) => (
+          <div key={state} className="flex flex-col items-center gap-2">
+            <RecordButton state={state} variant={variant} />
+            <span className="text-muted-foreground text-xs">{state}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Interactive Demo Component
+// ============================================================================
+
+function InteractiveDemo() {
+  const [state, setState] = React.useState<RecordButtonState>('idle');
+  const timersRef = React.useRef<NodeJS.Timeout[]>([]);
+
+  const clearTimers = () => {
+    timersRef.current.forEach(clearTimeout);
+    timersRef.current = [];
+  };
+
+  const handleClick = () => {
+    if (state === 'idle') {
+      // Start recording
+      setState('recording');
+    } else if (state === 'recording') {
+      // Stop recording, start processing
+      clearTimers();
+      setState('processing');
+
+      // Simulate processing time
+      const processingTimer = setTimeout(() => {
+        setState('success');
+
+        // Reset to idle after showing success
+        const successTimer = setTimeout(() => {
+          setState('idle');
+        }, 1500);
+        timersRef.current.push(successTimer);
+      }, 2000);
+      timersRef.current.push(processingTimer);
+    }
   };
 
+  React.useEffect(() => {
+    return () => {
+      clearTimers();
+    };
+  }, []);
+
   return (
-    <div className="relative">
-      <Textarea
-        value={displayValue}
-        onChange={(e) => onChange(e.target.value)}
-        placeholder={getPlaceholder()}
-        rows={rows}
-        readOnly={isProcessing}
-        className={`transition-all duration-200 ${isProcessing ? 'bg-neutral-50 dark:bg-neutral-900' : ''} ${isStreaming ? 'border-primary-400 dark:border-primary-600' : ''} ${isTranscribing ? 'border-amber-400 dark:border-amber-600' : ''} ${className || ''} `}
+    <div className="bg-card flex flex-col items-center gap-6 rounded-xl border p-8">
+      <RecordButton
+        state={state}
+        variant="default"
+        size="lg"
+        onClick={handleClick}
+        showPulse
       />
-      {/* Transcription indicator overlay */}
-      {isTranscribing && !displayValue && (
-        <div className="absolute inset-0 flex items-center justify-center rounded-lg bg-neutral-50/80 dark:bg-neutral-900/80">
-          <div className="flex items-center gap-2 text-sm text-neutral-600 dark:text-neutral-400">
-            <svg
-              className="h-4 w-4 animate-spin"
-              fill="none"
-              viewBox="0 0 24 24"
-            >
-              <circle
-                className="opacity-25"
-                cx="12"
-                cy="12"
-                r="10"
-                stroke="currentColor"
-                strokeWidth="4"
-              />
-              <path
-                className="opacity-75"
-                fill="currentColor"
-                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-              />
-            </svg>
-            <span>Transcribing audio...</span>
-          </div>
-        </div>
-      )}
-      {/* Streaming cursor effect */}
-      {isStreaming && (
-        <span className="text-primary-600 dark:text-primary-400 pointer-events-none absolute bottom-3">
-          <span
-            className="inline-block h-4 w-0.5 animate-pulse bg-current"
-            style={{
-              marginLeft: '0.125rem',
-              position: 'relative',
-              top: '0.125rem',
-            }}
-          />
-        </span>
-      )}
+      <div className="space-y-1 text-center">
+        <p className="text-sm font-medium">
+          {state === 'idle' && 'Click to start recording'}
+          {state === 'recording' && 'Recording... Click to stop'}
+          {state === 'processing' && 'Processing audio...'}
+          {state === 'success' && 'Done!'}
+        </p>
+        <p className="text-muted-foreground text-xs">
+          Current state:{' '}
+          <code className="bg-muted rounded px-1 py-0.5">{state}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Press and Hold Demo Component
+// ============================================================================
+
+function PressAndHoldDemo() {
+  const [state, setState] = React.useState<RecordButtonState>('idle');
+  const timersRef = React.useRef<NodeJS.Timeout[]>([]);
+
+  const clearTimers = () => {
+    timersRef.current.forEach(clearTimeout);
+    timersRef.current = [];
+  };
+
+  const handleMouseDown = () => {
+    clearTimers();
+    setState('recording');
+  };
+
+  const handleMouseUp = () => {
+    if (state === 'recording') {
+      clearTimers();
+      setState('processing');
+
+      const processingTimer = setTimeout(() => {
+        setState('success');
+        const successTimer = setTimeout(() => {
+          setState('idle');
+        }, 1000);
+        timersRef.current.push(successTimer);
+      }, 1500);
+      timersRef.current.push(processingTimer);
+    }
+  };
+
+  React.useEffect(() => {
+    return () => {
+      clearTimers();
+    };
+  }, []);
+
+  return (
+    <div className="bg-card flex flex-col items-center gap-6 rounded-xl border p-8">
+      <RecordButton
+        state={state}
+        variant="default"
+        size="lg"
+        onMouseDown={handleMouseDown}
+        onMouseUp={handleMouseUp}
+        onMouseLeave={handleMouseUp}
+        onTouchStart={handleMouseDown}
+        onTouchEnd={handleMouseUp}
+        showWaveform
+        showPulse
+      />
+      <div className="space-y-1 text-center">
+        <p className="text-sm font-medium">
+          {state === 'idle' && 'Press and hold to record'}
+          {state === 'recording' && 'Recording... Release to stop'}
+          {state === 'processing' && 'Processing...'}
+          {state === 'success' && 'Sent!'}
+        </p>
+        <p className="text-muted-foreground text-xs">
+          Shows waveform animation while recording
+        </p>
+      </div>
     </div>
   );
 }
 
+// ============================================================================
+// Meta
+// ============================================================================
+
 const meta: Meta<typeof RecordButton> = {
   title: 'Components/RecordButton',
   component: RecordButton,
   parameters: {
     layout: 'centered',
+    controls: {
+      include: [
+        'state',
+        'size',
+        'variant',
+        'showWaveform',
+        'showPulse',
+        'showDuration',
+        'disabled',
+        'maxDuration',
+      ],
+    },
     docs: {
       description: {
         component: `
-A simple microphone recording button that can be placed anywhere.
-Perfect for adding voice input to text fields, chat inputs, or forms.
+A voice recording button with 6 distinct states for AI applications.
+Supports multiple visual variants, sizes, and interaction patterns.
+
+## States
+- **idle** — Ready to record, waiting for interaction
+- **recording** — Actively capturing audio input
+- **processing** — Transcribing or sending audio
+- **disabled** — No mic permission or unavailable
+- **error** — Recording failed or permission denied
+- **success** — Recording captured successfully
 
 ## Features
-- Compact, embeddable design
-- Recording states: idle, recording, processing
-- Optional duration display while recording
-- Customizable icons
-- Theme-aware styling
-
-## Usage
-
-\`\`\`tsx
-import { RecordButton } from '@mieweb/ui';
-
-// Basic usage
-<RecordButton
-  onRecordingComplete={(blob, duration) => {
-    // Handle the recorded audio
-  }}
-/>
-
-// In an input field
-<div className="relative">
-  <Input className="pr-12" />
-  <div className="absolute right-2 top-1/2 -translate-y-1/2">
-    <RecordButton size="sm" />
-  </div>
-</div>
-\`\`\`
+- 4 visual variants: default, outline, ghost, minimal
+- 3 sizes: sm, md, lg
+- Pulse ring animation during recording
+- Optional waveform visualization
+- Transcription state integration
+- Both controlled and uncontrolled modes
         `,
       },
     },
   },
   tags: ['autodocs'],
   argTypes: {
-    variant: {
+    state: {
       control: 'select',
-      options: ['default', 'filled', 'primary'],
+      options: [
+        'idle',
+        'recording',
+        'processing',
+        'disabled',
+        'error',
+        'success',
+      ],
+      description: 'Current state of the button',
     },
     size: {
       control: 'select',
       options: ['sm', 'md', 'lg'],
+      description: 'Size of the button',
     },
-    maxDuration: {
-      control: { type: 'number', min: 0, max: 300 },
+    variant: {
+      control: 'select',
+      options: ['default', 'outline', 'ghost', 'minimal'],
+      description: 'Visual style variant',
+    },
+    showWaveform: {
+      control: 'boolean',
+      description:
+        'Show animated waveform bars when recording (only visible in recording state)',
+    },
+    showPulse: {
+      control: 'boolean',
+      description:
+        'Show pulse rings when recording (only visible in recording state)',
     },
     showDuration: {
       control: 'boolean',
+      description: 'Show recording duration',
     },
     disabled: {
       control: 'boolean',
+      description: 'Disable the button',
     },
+    maxDuration: {
+      control: { type: 'number', min: 0, max: 300 },
+      description: 'Maximum recording duration in seconds',
+    },
+    // Hide less commonly used props
+    onRecordingComplete: { table: { disable: true } },
+    onRecordingStart: { table: { disable: true } },
+    onRecordingError: { table: { disable: true } },
+    mimeType: { table: { disable: true } },
+    className: { table: { disable: true } },
+    'aria-label': { table: { disable: true } },
+    idleIcon: { table: { disable: true } },
+    recordingIcon: { table: { disable: true } },
+    transcriptionState: { table: { disable: true } },
+    showTranscriptionState: { table: { disable: true } },
   },
 };
 
@@ -289,791 +459,513 @@ export default meta;
 type Story = StoryObj<typeof RecordButton>;
 
 // ============================================================================
-// Basic Examples
+// Default (Controllable Preview)
 // ============================================================================
 
+/**
+ * Use the controls panel to preview different states, variants, and sizes.
+ * This is a controlled preview - use the "Live Recording" story to test actual recording.
+ */
 export const Default: Story = {
-  args: {},
-};
-
-export const WithDuration: Story = {
   args: {
-    showDuration: true,
-    maxDuration: 30,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Shows recording duration while recording.',
-      },
-    },
+    state: 'idle',
+    variant: 'default',
+    size: 'md',
+    showWaveform: true,
+    showPulse: true,
+    showDuration: false,
+    disabled: false,
   },
 };
 
 // ============================================================================
-// Variants
+// Live Recording Demo
 // ============================================================================
 
-export const DefaultVariant: Story = {
-  args: {
-    variant: 'default',
+/**
+ * A fully functional recording button. Click to start recording,
+ * click again to stop. The recorded audio will play back below.
+ */
+export const LiveRecording: Story = {
+  render: function LiveRecordingStory() {
+    const [lastRecording, setLastRecording] = React.useState<{
+      blob: Blob;
+      duration: number;
+      url: string;
+    } | null>(null);
+
+    const handleRecordingComplete = (blob: Blob, duration: number) => {
+      const url = URL.createObjectURL(blob);
+      setLastRecording({ blob, duration, url });
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RecordButton
+          onRecordingComplete={handleRecordingComplete}
+          showWaveform
+          showPulse
+          showDuration
+        />
+        <p className="text-muted-foreground text-sm">
+          Click to start recording
+        </p>
+        {lastRecording && (
+          <div className="w-72">
+            <AudioPlayer
+              src={lastRecording.url}
+              title={`Recording (${lastRecording.duration.toFixed(1)}s)`}
+              variant="compact"
+              size="sm"
+              showTime
+            />
+          </div>
+        )}
+      </div>
+    );
   },
 };
 
-export const FilledVariant: Story = {
+// ============================================================================
+// State Previews
+// ============================================================================
+
+export const Recording: Story = {
   args: {
-    variant: 'filled',
+    state: 'recording',
+    showWaveform: true,
+    showPulse: true,
   },
 };
 
-export const PrimaryVariant: Story = {
+export const Processing: Story = {
   args: {
-    variant: 'primary',
+    state: 'processing',
   },
 };
 
-// ============================================================================
-// Sizes
-// ============================================================================
-
-export const Small: Story = {
+export const Disabled: Story = {
   args: {
-    size: 'sm',
+    state: 'disabled',
   },
 };
 
-export const Medium: Story = {
+export const Error: Story = {
   args: {
-    size: 'md',
+    state: 'error',
   },
 };
 
-export const Large: Story = {
+export const Success: Story = {
   args: {
-    size: 'lg',
+    state: 'success',
   },
 };
 
-export const AllSizes: Story = {
+// ============================================================================
+// All States Overview
+// ============================================================================
+
+export const AllStates: Story = {
   render: () => (
-    <div className="flex items-center gap-4">
-      <div className="text-center">
-        <RecordButton size="sm" />
-        <p className="mt-2 text-xs text-neutral-500">Small</p>
-      </div>
-      <div className="text-center">
-        <RecordButton size="md" />
-        <p className="mt-2 text-xs text-neutral-500">Medium</p>
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-lg font-semibold tracking-tight">All States</h2>
+        <p className="text-muted-foreground text-sm">
+          The 6 essential states a mic button needs to cover all use cases.
+        </p>
       </div>
-      <div className="text-center">
-        <RecordButton size="lg" />
-        <p className="mt-2 text-xs text-neutral-500">Large</p>
+      <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-6">
+        <StateCard
+          state="idle"
+          label="Idle"
+          description="Ready to record, waiting for interaction"
+        />
+        <StateCard
+          state="recording"
+          label="Recording"
+          description="Actively capturing audio input"
+        />
+        <StateCard
+          state="processing"
+          label="Processing"
+          description="Transcribing or sending audio"
+        />
+        <StateCard
+          state="disabled"
+          label="Disabled"
+          description="No mic permission or unavailable"
+        />
+        <StateCard
+          state="error"
+          label="Error"
+          description="Recording failed or permission denied"
+        />
+        <StateCard
+          state="success"
+          label="Success"
+          description="Recording captured successfully"
+        />
       </div>
     </div>
   ),
+  parameters: {
+    layout: 'padded',
+  },
 };
 
 // ============================================================================
-// In Context Examples
+// Variants
 // ============================================================================
 
-export const InInputField: Story = {
-  render: function InInputFieldStory() {
-    const [recordings, setRecordings] = React.useState<
-      Array<{ id: string; duration: number }>
-    >([]);
-
-    return (
-      <div className="w-80 space-y-3">
-        <div className="relative">
-          <Input placeholder="Type or record a message..." className="pr-12" />
-          <div className="absolute top-1/2 right-2 -translate-y-1/2">
-            <RecordButton
-              size="sm"
-              onRecordingComplete={(blob, duration) => {
-                setRecordings((prev) => [
-                  ...prev,
-                  { id: Date.now().toString(), duration },
-                ]);
-              }}
-            />
-          </div>
-        </div>
-        {recordings.length > 0 && (
-          <div className="text-xs text-neutral-500">
-            {recordings.length} recording(s) captured
-          </div>
-        )}
+export const Variants: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-lg font-semibold tracking-tight">Variants</h2>
+        <p className="text-muted-foreground text-sm">
+          Four visual styles to match different UI contexts.
+        </p>
       </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'RecordButton embedded inside an input field.',
-      },
-    },
-  },
-};
-
-export const InTextarea: Story = {
-  render: function InTextareaStory() {
-    return (
-      <div className="w-80">
-        <div className="relative">
-          <Textarea
-            placeholder="Write your message or record audio..."
-            rows={4}
-            className="pb-10"
-          />
-          <div className="absolute right-2 bottom-2 flex items-center gap-2">
-            <RecordButton size="sm" variant="filled" showDuration />
-          </div>
-        </div>
+      <div className="bg-card space-y-8 rounded-xl border p-6">
+        <VariantRow variant="default" label="Default" />
+        <VariantRow variant="outline" label="Outline" />
+        <VariantRow variant="ghost" label="Ghost" />
+        <VariantRow variant="minimal" label="Minimal" />
       </div>
-    );
-  },
+    </div>
+  ),
   parameters: {
-    docs: {
-      description: {
-        story: 'RecordButton at the bottom of a textarea.',
-      },
-    },
+    layout: 'padded',
   },
 };
 
-export const ChatInputExample: Story = {
-  render: function ChatInputExampleStory() {
-    const [message, setMessage] = React.useState('');
-    const [attachments, setAttachments] = React.useState<
-      Array<{ name: string; duration: number }>
-    >([]);
-
-    const handleRecording = (blob: Blob, duration: number) => {
-      const name = `recording-${new Date().toISOString()}.webm`;
-      setAttachments((prev) => [...prev, { name, duration }]);
-    };
+// ============================================================================
+// Sizes
+// ============================================================================
 
-    return (
-      <div className="w-96 space-y-2 rounded-lg border border-neutral-200 p-3 dark:border-neutral-700">
-        {attachments.length > 0 && (
-          <div className="flex flex-wrap gap-2">
-            {attachments.map((att, i) => (
-              <div
-                key={i}
-                className="flex items-center gap-1 rounded bg-neutral-100 px-2 py-1 text-xs dark:bg-neutral-800"
-              >
-                <svg
-                  className="h-3 w-3"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  strokeWidth={2}
-                  stroke="currentColor"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z"
-                  />
-                </svg>
-                <span>{Math.round(att.duration)}s</span>
-                <button
-                  onClick={() =>
-                    setAttachments((prev) => prev.filter((_, j) => j !== i))
-                  }
-                  className="ml-1 text-neutral-400 hover:text-neutral-600"
-                >
-                  ×
-                </button>
-              </div>
-            ))}
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-lg font-semibold tracking-tight">Sizes</h2>
+        <p className="text-muted-foreground text-sm">
+          Three sizes for different contexts and layouts.
+        </p>
+      </div>
+      <div className="bg-card flex flex-wrap items-end gap-8 rounded-xl border p-6">
+        {(['sm', 'md', 'lg'] as RecordButtonSize[]).map((size) => (
+          <div key={size} className="flex flex-col items-center gap-3">
+            <RecordButton size={size} />
+            <div className="text-center">
+              <p className="text-sm font-medium">{size.toUpperCase()}</p>
+              <code className="text-muted-foreground text-xs">
+                size=&quot;{size}&quot;
+              </code>
+            </div>
           </div>
-        )}
-        <div className="flex items-end gap-2">
-          <textarea
-            value={message}
-            onChange={(e) => setMessage(e.target.value)}
-            placeholder="Type a message..."
-            rows={1}
-            className="focus:ring-primary-500 flex-1 resize-none rounded-lg border border-neutral-200 bg-transparent px-3 py-2 text-sm focus:ring-2 focus:outline-none dark:border-neutral-700"
-          />
-          <RecordButton
-            variant="filled"
-            onRecordingComplete={handleRecording}
-            showDuration
-          />
-          <button className="bg-primary-600 hover:bg-primary-700 h-9 rounded-lg px-4 text-sm font-medium text-white">
-            Send
-          </button>
-        </div>
+        ))}
       </div>
-    );
-  },
+    </div>
+  ),
   parameters: {
-    docs: {
-      description: {
-        story: 'Full chat input example with recording attachments.',
-      },
-    },
+    layout: 'padded',
   },
 };
 
 // ============================================================================
-// States
+// Recording Animations
 // ============================================================================
 
-export const Disabled: Story = {
-  args: {
-    disabled: true,
-  },
-};
-
-export const WithMaxDuration: Story = {
-  args: {
-    maxDuration: 10,
-    showDuration: true,
-  },
+export const RecordingAnimations: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-lg font-semibold tracking-tight">
+          Recording Animations
+        </h2>
+        <p className="text-muted-foreground text-sm">
+          Different visual feedback options for the recording state.
+        </p>
+      </div>
+      <div className="grid gap-4 sm:grid-cols-3">
+        <div className="bg-card flex flex-col items-center gap-4 rounded-xl border p-6">
+          <RecordButton state="recording" showPulse showWaveform={false} />
+          <div className="space-y-1 text-center">
+            <p className="text-sm font-medium">Pulse + Stop Icon</p>
+            <p className="text-muted-foreground text-xs">
+              Default recording state with pulse rings
+            </p>
+          </div>
+        </div>
+        <div className="bg-card flex flex-col items-center gap-4 rounded-xl border p-6">
+          <RecordButton state="recording" showPulse showWaveform />
+          <div className="space-y-1 text-center">
+            <p className="text-sm font-medium">Pulse + Waveform</p>
+            <p className="text-muted-foreground text-xs">
+              Shows audio activity with waveform bars
+            </p>
+          </div>
+        </div>
+        <div className="bg-card flex flex-col items-center gap-4 rounded-xl border p-6">
+          <RecordButton state="recording" showPulse={false} showWaveform />
+          <div className="space-y-1 text-center">
+            <p className="text-sm font-medium">Waveform Only</p>
+            <p className="text-muted-foreground text-xs">
+              Subtle animation without pulse rings
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
   parameters: {
-    docs: {
-      description: {
-        story: 'Automatically stops recording after 10 seconds.',
-      },
-    },
+    layout: 'padded',
   },
 };
 
 // ============================================================================
-// Callbacks
+// Interactive Demos
 // ============================================================================
 
-export const WithCallbacks: Story = {
-  args: {
-    showDuration: true,
-    onRecordingStart: () => console.log('Recording started'),
-    onRecordingComplete: (blob, duration) =>
-      console.log('Recording complete:', { blob, duration }),
-    onError: (error) => console.error('Error:', error),
-  },
+export const InteractiveDemos: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-lg font-semibold tracking-tight">
+          Interactive Demos
+        </h2>
+        <p className="text-muted-foreground text-sm">
+          Try the different interaction patterns.
+        </p>
+      </div>
+      <div className="grid gap-6 md:grid-cols-2">
+        <div className="space-y-3">
+          <div className="flex items-center gap-2">
+            <span className="text-sm font-medium">Toggle Pattern</span>
+            <span className="bg-muted rounded-full px-2 py-0.5 text-xs">
+              Click to toggle
+            </span>
+          </div>
+          <InteractiveDemo />
+        </div>
+        <div className="space-y-3">
+          <div className="flex items-center gap-2">
+            <span className="text-sm font-medium">Press & Hold Pattern</span>
+            <span className="bg-muted rounded-full px-2 py-0.5 text-xs">
+              Hold to record
+            </span>
+          </div>
+          <PressAndHoldDemo />
+        </div>
+      </div>
+    </div>
+  ),
   parameters: {
-    docs: {
-      description: {
-        story: 'Check the console for callback events.',
-      },
-    },
+    layout: 'padded',
   },
 };
 
 // ============================================================================
-// Custom Icons
+// With Duration
 // ============================================================================
 
-export const CustomIcons: Story = {
-  args: {
-    idleIcon: (
-      <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 20 20">
-        <path
-          fillRule="evenodd"
-          d="M7 4a3 3 0 016 0v4a3 3 0 11-6 0V4zm4 10.93A7.001 7.001 0 0017 8a1 1 0 10-2 0A5 5 0 015 8a1 1 0 00-2 0 7.001 7.001 0 006 6.93V17H6a1 1 0 100 2h8a1 1 0 100-2h-3v-2.07z"
-          clipRule="evenodd"
-        />
-      </svg>
-    ),
-    recordingIcon: (
-      <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 20 20">
-        <path
-          fillRule="evenodd"
-          d="M10 18a8 8 0 100-16 8 8 0 000 16zM8 7a1 1 0 00-1 1v4a1 1 0 001 1h4a1 1 0 001-1V8a1 1 0 00-1-1H8z"
-          clipRule="evenodd"
-        />
-      </svg>
-    ),
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Using custom icons for idle and recording states.',
-      },
-    },
+export const WithDuration: Story = {
+  render: function WithDurationStory() {
+    return (
+      <div className="space-y-4">
+        <p className="text-muted-foreground text-sm">
+          Click to start recording and see the duration timer.
+        </p>
+        <RecordButton showDuration maxDuration={30} />
+      </div>
+    );
   },
 };
 
 // ============================================================================
-// Transcription Examples
+// In Input Field
 // ============================================================================
 
-/**
- * Batch Transcription Mode
- *
- * Records audio, then sends it to a transcription service and waits for the result.
- * The textarea shows a loading state while transcription is in progress.
- */
-export const BatchTranscription: Story = {
-  render: function BatchTranscriptionStory() {
-    const [text, setText] = React.useState('');
-    const { state, transcribe, reset } = useMockBatchTranscription();
+export const InInputField: Story = {
+  render: function InInputFieldStory() {
+    const [inputValue, setInputValue] = React.useState('');
 
-    const handleRecordingComplete = async (blob: Blob, duration: number) => {
-      const result = await transcribe(blob, duration);
-      setText((prev) => (prev ? `${prev}\n\n${result}` : result));
+    const handleRecordingComplete = (blob: Blob, duration: number) => {
+      // In a real app, you'd send the blob to a transcription service
+      setInputValue(
+        `[Voice message: ${duration.toFixed(1)}s, ${(blob.size / 1024).toFixed(1)}KB]`
+      );
     };
 
     return (
-      <div className="w-96 space-y-3">
-        <div className="text-sm font-medium text-neutral-700 dark:text-neutral-300">
-          Batch Transcription Demo
-        </div>
-        <p className="text-xs text-neutral-500 dark:text-neutral-400">
-          Record audio, then wait for the full transcription. The textarea
-          becomes read-only during processing.
+      <div className="w-96 space-y-4">
+        <p className="text-muted-foreground text-sm">
+          RecordButton embedded in an input field. Click the mic to record.
         </p>
-
-        <TranscriptionTextarea
-          value={text}
-          onChange={setText}
-          transcriptionState={state}
-          placeholder="Click the mic to record and transcribe..."
-          rows={4}
-        />
-
-        <div className="flex items-center justify-between">
-          <RecordButton
-            variant="filled"
-            showDuration
-            transcriptionState={state}
-            showTranscriptionState
-            onRecordingComplete={handleRecordingComplete}
-            maxDuration={30}
+        <div className="relative">
+          <Input
+            placeholder="Type or record a message..."
+            className="pr-14"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
           />
-          {text && (
-            <button
-              onClick={() => {
-                setText('');
-                reset();
-              }}
-              className="text-xs text-neutral-500 hover:text-neutral-700 dark:hover:text-neutral-300"
-            >
-              Clear
-            </button>
-          )}
+          <div className="absolute top-1/2 right-2 -translate-y-1/2">
+            <RecordButton
+              size="sm"
+              variant="ghost"
+              onRecordingComplete={handleRecordingComplete}
+            />
+          </div>
         </div>
+        {inputValue && (
+          <p className="text-muted-foreground text-xs">
+            Value: <code className="bg-muted rounded px-1">{inputValue}</code>
+          </p>
+        )}
       </div>
     );
   },
-  parameters: {
-    docs: {
-      description: {
-        story: `
-**Batch Transcription Mode**
-
-This mode is for "send it, wait, and get transcription back" workflows:
-
-1. User clicks record and speaks
-2. User stops recording
-3. Audio is sent to transcription service
-4. Textarea shows loading state (read-only)
-5. Full transcription appears when complete
-
-Best for: High accuracy needs, offline processing, longer recordings.
-        `,
-      },
-    },
-  },
 };
 
-/**
- * Real-time Streaming Transcription
- *
- * Text appears word-by-word as the user speaks.
- * Shows a cursor effect to indicate live transcription.
- */
-export const StreamingTranscription: Story = {
-  render: function StreamingTranscriptionStory() {
+// ============================================================================
+// Transcription Integration
+// ============================================================================
+
+export const BatchTranscription: Story = {
+  render: function BatchTranscriptionStory() {
     const [text, setText] = React.useState('');
-    const { state, partialText, startStreaming, stopStreaming, reset } =
-      useMockStreamingTranscription();
+    const {
+      state,
+      text: transcribedText,
+      transcribe,
+      reset,
+    } = useMockBatchTranscription();
 
-    const handleRecordingStart = () => {
-      startStreaming();
+    const handleRecordingComplete = async (blob: Blob, duration: number) => {
+      await transcribe(blob, duration);
     };
 
-    const handleRecordingComplete = () => {
-      stopStreaming();
-      // After processing, append the final text
-      setTimeout(() => {
-        setText((prev) => {
-          const newText = partialText || 'Transcription complete.';
-          return prev ? `${prev}\n\n${newText}` : newText;
-        });
-      }, 600);
-    };
+    React.useEffect(() => {
+      if (transcribedText) {
+        setText(transcribedText);
+      }
+    }, [transcribedText]);
 
     return (
-      <div className="w-96 space-y-3">
-        <div className="text-sm font-medium text-neutral-700 dark:text-neutral-300">
-          Real-time Streaming Demo
+      <div className="w-96 space-y-4">
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium">Batch Transcription</h3>
+          <p className="text-muted-foreground text-xs">
+            Record audio, then transcribe after recording completes.
+          </p>
+        </div>
+        <div className="relative">
+          <Textarea
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            placeholder="Record a message to transcribe..."
+            rows={4}
+            className={state === 'transcribing' ? 'bg-muted' : ''}
+          />
         </div>
-        <p className="text-xs text-neutral-500 dark:text-neutral-400">
-          Text appears as you speak. Watch the words stream in real-time.
-        </p>
-
-        <TranscriptionTextarea
-          value={text}
-          onChange={setText}
-          transcriptionState={state}
-          streamingText={partialText}
-          placeholder="Click the mic to start live transcription..."
-          rows={4}
-        />
-
         <div className="flex items-center justify-between">
           <RecordButton
-            variant="filled"
-            showDuration
             transcriptionState={state}
             showTranscriptionState
-            onRecordingStart={handleRecordingStart}
             onRecordingComplete={handleRecordingComplete}
-            maxDuration={60}
-          />
-          {(text || partialText) && (
-            <button
-              onClick={() => {
-                setText('');
-                reset();
-              }}
-              className="text-xs text-neutral-500 hover:text-neutral-700 dark:hover:text-neutral-300"
-            >
-              Clear
-            </button>
-          )}
-        </div>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: `
-**Real-time Streaming Mode**
-
-This mode shows text appearing word-by-word as the user speaks:
-
-1. User clicks record
-2. Transcription starts immediately
-3. Words appear in the textarea as they're recognized
-4. A blinking cursor indicates live transcription
-5. When stopped, final processing occurs
-
-Best for: Immediate feedback, live captioning, real-time note-taking.
-        `,
-      },
-    },
-  },
-};
-
-/**
- * Transcription States Demonstration
- *
- * Shows all possible transcription states for testing and documentation.
- */
-export const TranscriptionStates: Story = {
-  render: function TranscriptionStatesStory() {
-    const [currentState, setCurrentState] =
-      React.useState<TranscriptionState>('idle');
-
-    const states: TranscriptionState[] = [
-      'idle',
-      'recording',
-      'transcribing',
-      'streaming',
-      'complete',
-      'error',
-    ];
-
-    return (
-      <div className="w-96 space-y-4">
-        <div className="text-sm font-medium text-neutral-700 dark:text-neutral-300">
-          Transcription State Tester
-        </div>
-
-        <div className="flex flex-wrap gap-2">
-          {states.map((state) => (
-            <button
-              key={state}
-              onClick={() => setCurrentState(state)}
-              className={`rounded px-2 py-1 text-xs font-medium transition-colors ${
-                currentState === state
-                  ? 'bg-primary-600 text-white'
-                  : 'bg-neutral-100 text-neutral-700 hover:bg-neutral-200 dark:bg-neutral-800 dark:text-neutral-300 dark:hover:bg-neutral-700'
-              }`}
-            >
-              {state}
-            </button>
-          ))}
-        </div>
-
-        <TranscriptionTextarea
-          value={
-            currentState === 'complete'
-              ? 'This is the transcribed text that appeared after processing.'
-              : ''
-          }
-          onChange={() => {}}
-          transcriptionState={currentState}
-          streamingText={
-            currentState === 'streaming'
-              ? 'This text is streaming in word by word...'
-              : undefined
-          }
-          placeholder="Select a state above to preview..."
-          rows={3}
-        />
-
-        <div className="flex items-center gap-4">
-          <RecordButton
-            variant="filled"
-            transcriptionState={currentState}
-            showTranscriptionState
-            disabled={currentState !== 'idle'}
           />
-          <div className="text-xs text-neutral-500">
-            Current state: <code className="font-mono">{currentState}</code>
-          </div>
-        </div>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Interactive demo of all transcription states. Click buttons to preview each state.',
-      },
-    },
-  },
-};
-
-/**
- * Full Chat with Voice Transcription
- *
- * Complete chat interface with voice-to-text transcription.
- */
-export const ChatWithTranscription: Story = {
-  render: function ChatWithTranscriptionStory() {
-    const [message, setMessage] = React.useState('');
-    const [messages, setMessages] = React.useState<
-      Array<{ id: string; text: string; isVoice: boolean }>
-    >([]);
-    const { state, transcribe, reset } = useMockBatchTranscription();
-
-    const handleSend = () => {
-      if (!message.trim()) return;
-      setMessages((prev) => [
-        ...prev,
-        { id: Date.now().toString(), text: message, isVoice: false },
-      ]);
-      setMessage('');
-    };
-
-    const handleRecordingComplete = async (blob: Blob, duration: number) => {
-      const result = await transcribe(blob, duration);
-      setMessages((prev) => [
-        ...prev,
-        { id: Date.now().toString(), text: result, isVoice: true },
-      ]);
-      reset();
-    };
-
-    return (
-      <div className="flex h-96 w-96 flex-col rounded-lg border border-neutral-200 dark:border-neutral-700">
-        {/* Messages */}
-        <div className="flex-1 space-y-2 overflow-auto p-3">
-          {messages.length === 0 && (
-            <div className="flex h-full items-center justify-center text-sm text-neutral-400">
-              Send a message or record audio
-            </div>
-          )}
-          {messages.map((msg) => (
-            <div
-              key={msg.id}
-              className="flex items-start gap-2 rounded-lg bg-neutral-100 p-2 dark:bg-neutral-800"
-            >
-              {msg.isVoice && (
-                <svg
-                  className="mt-0.5 h-4 w-4 shrink-0 text-neutral-400"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  strokeWidth={2}
-                  stroke="currentColor"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z"
-                  />
-                </svg>
-              )}
-              <p className="text-sm">{msg.text}</p>
-            </div>
-          ))}
-        </div>
-
-        {/* Input */}
-        <div className="border-t border-neutral-200 p-3 dark:border-neutral-700">
-          <TranscriptionTextarea
-            value={message}
-            onChange={setMessage}
-            transcriptionState={state}
-            placeholder="Type or record..."
-            rows={2}
-            className="mb-2"
-          />
-          <div className="flex items-center justify-between">
-            <RecordButton
-              variant="filled"
-              size="sm"
-              showDuration
-              transcriptionState={state}
-              showTranscriptionState
-              onRecordingComplete={handleRecordingComplete}
-              maxDuration={30}
-            />
-            <button
-              onClick={handleSend}
-              disabled={!message.trim() || state !== 'idle'}
-              className="bg-primary-600 hover:bg-primary-700 disabled:bg-primary-400 rounded-lg px-4 py-1.5 text-sm font-medium text-white transition-colors disabled:cursor-not-allowed"
-            >
-              Send
-            </button>
-          </div>
+          <button
+            onClick={() => {
+              reset();
+              setText('');
+            }}
+            className="text-muted-foreground hover:text-foreground text-xs"
+          >
+            Reset
+          </button>
         </div>
       </div>
     );
   },
   parameters: {
-    docs: {
-      description: {
-        story:
-          'Complete chat interface demonstrating voice-to-text integration.',
-      },
-    },
+    layout: 'padded',
   },
 };
 
-/**
- * Form Field with Voice Input
- *
- * Shows how to add voice transcription to a standard form field.
- */
-export const FormFieldWithVoice: Story = {
-  render: function FormFieldWithVoiceStory() {
-    const [name, setName] = React.useState('');
-    const [description, setDescription] = React.useState('');
-    const { state, transcribe, reset } = useMockBatchTranscription();
-    const [activeField, setActiveField] = React.useState<
-      'name' | 'description' | null
-    >(null);
+export const StreamingTranscription: Story = {
+  render: function StreamingTranscriptionStory() {
+    const [text, setText] = React.useState('');
+    const {
+      state,
+      text: finalText,
+      partialText,
+      startStreaming,
+      stopStreaming,
+      reset,
+    } = useMockStreamingTranscription();
+
+    React.useEffect(() => {
+      if (finalText) {
+        setText(finalText);
+      }
+    }, [finalText]);
 
-    const handleRecordingComplete = async (blob: Blob, duration: number) => {
-      const result = await transcribe(blob, duration);
-      if (activeField === 'name') {
-        setName(result);
-      } else if (activeField === 'description') {
-        setDescription(result);
+    const handleClick = () => {
+      if (state === 'idle') {
+        startStreaming();
+      } else if (state === 'streaming') {
+        stopStreaming();
       }
-      setActiveField(null);
-      reset();
     };
 
     return (
       <div className="w-96 space-y-4">
-        <div className="text-sm font-medium text-neutral-700 dark:text-neutral-300">
-          Voice-Enabled Form
-        </div>
-
-        {/* Name field */}
         <div className="space-y-1">
-          <label
-            htmlFor="voice-form-name"
-            className="text-sm font-medium text-neutral-700 dark:text-neutral-300"
-          >
-            Name
-          </label>
-          <div className="relative">
-            <Input
-              id="voice-form-name"
-              value={name}
-              onChange={(e) => setName(e.target.value)}
-              placeholder="Enter your name..."
-              className="pr-12"
-              readOnly={state !== 'idle' && activeField === 'name'}
-            />
-            <div className="absolute top-1/2 right-2 -translate-y-1/2">
-              <RecordButton
-                size="sm"
-                variant="default"
-                transcriptionState={activeField === 'name' ? state : 'idle'}
-                onRecordingStart={() => setActiveField('name')}
-                onRecordingComplete={handleRecordingComplete}
-                disabled={state !== 'idle' && activeField !== 'name'}
-              />
-            </div>
-          </div>
+          <h3 className="text-sm font-medium">Streaming Transcription</h3>
+          <p className="text-muted-foreground text-xs">
+            See text appear word-by-word as you speak.
+          </p>
         </div>
-
-        {/* Description field */}
-        <div className="space-y-1">
-          <label
-            htmlFor="voice-form-description"
-            className="text-sm font-medium text-neutral-700 dark:text-neutral-300"
+        <div className="relative">
+          <Textarea
+            value={state === 'streaming' ? partialText : text}
+            onChange={(e) => setText(e.target.value)}
+            placeholder="Record to see streaming transcription..."
+            rows={4}
+            readOnly={state === 'streaming' || state === 'transcribing'}
+            className={state === 'streaming' ? 'border-primary' : ''}
+          />
+        </div>
+        <div className="flex items-center justify-between">
+          <RecordButton
+            state={
+              state === 'streaming'
+                ? 'recording'
+                : state === 'transcribing'
+                  ? 'processing'
+                  : state === 'complete'
+                    ? 'success'
+                    : 'idle'
+            }
+            onClick={handleClick}
+            showWaveform
+            showPulse
+          />
+          <button
+            onClick={() => {
+              reset();
+              setText('');
+            }}
+            className="text-muted-foreground hover:text-foreground text-xs"
           >
-            Description
-          </label>
-          <div className="relative">
-            <Textarea
-              id="voice-form-description"
-              value={description}
-              onChange={(e) => setDescription(e.target.value)}
-              placeholder="Describe your project..."
-              rows={3}
-              className={`pr-12 ${
-                state !== 'idle' && activeField === 'description'
-                  ? 'bg-neutral-50 dark:bg-neutral-900'
-                  : ''
-              }`}
-              readOnly={state !== 'idle' && activeField === 'description'}
-            />
-            <div className="absolute top-2 right-2">
-              <RecordButton
-                size="sm"
-                variant="default"
-                transcriptionState={
-                  activeField === 'description' ? state : 'idle'
-                }
-                onRecordingStart={() => setActiveField('description')}
-                onRecordingComplete={handleRecordingComplete}
-                disabled={state !== 'idle' && activeField !== 'description'}
-              />
-            </div>
-          </div>
+            Reset
+          </button>
         </div>
-
-        {/* Submit */}
-        <button
-          className="bg-primary-600 hover:bg-primary-700 w-full rounded-lg py-2 text-sm font-medium text-white"
-          disabled={state !== 'idle'}
-        >
-          Submit
-        </button>
       </div>
     );
   },
   parameters: {
-    docs: {
-      description: {
-        story:
-          'Standard form with voice input capability on multiple fields. Shows how to integrate voice transcription into existing forms.',
-      },
-    },
+    layout: 'padded',
   },
 };
diff --git a/src/components/RecordButton/RecordButton.tsx b/src/components/RecordButton/RecordButton.tsx
index 1e4fd598..53fa6fed 100644
--- a/src/components/RecordButton/RecordButton.tsx
+++ b/src/components/RecordButton/RecordButton.tsx
@@ -1,12 +1,21 @@
 import * as React from 'react';
-import { cva, type VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export type RecordButtonState = 'idle' | 'recording' | 'processing';
+export type RecordButtonState =
+  | 'idle'
+  | 'recording'
+  | 'processing'
+  | 'disabled'
+  | 'error'
+  | 'success';
+
+export type RecordButtonVariant = 'default' | 'outline' | 'ghost' | 'minimal';
+export type RecordButtonSize = 'sm' | 'md' | 'lg';
 
 /** Transcription state for integration with transcription services */
 export type TranscriptionState =
@@ -26,25 +35,20 @@ export interface TranscriptionResult {
   confidence?: number;
 }
 
-export interface RecordButtonProps extends VariantProps<
-  typeof recordButtonVariants
+export interface RecordButtonProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  'children'
 > {
-  /** Callback when recording is complete with the audio blob */
-  onRecordingComplete?: (blob: Blob, duration: number) => void;
-  /** Callback when recording starts */
-  onRecordingStart?: () => void;
-  /** Callback when an error occurs */
-  onError?: (error: Error) => void;
-  /** Maximum recording duration in seconds (0 for unlimited) */
-  maxDuration?: number;
-  /** Audio MIME type */
-  mimeType?: string;
-  /** Whether the button is disabled */
-  disabled?: boolean;
-  /** Additional class name */
-  className?: string;
-  /** Accessible label */
-  'aria-label'?: string;
+  /** Current state of the button */
+  state?: RecordButtonState;
+  /** Size of the button */
+  size?: RecordButtonSize;
+  /** Visual style variant */
+  variant?: RecordButtonVariant;
+  /** Show waveform bars when recording (instead of stop icon) */
+  showWaveform?: boolean;
+  /** Show pulse rings when recording */
+  showPulse?: boolean;
   /** Show recording duration while recording */
   showDuration?: boolean;
   /** Custom idle icon */
@@ -55,98 +59,63 @@ export interface RecordButtonProps extends VariantProps<
   transcriptionState?: TranscriptionState;
   /** Show transcription state indicator */
   showTranscriptionState?: boolean;
-}
-
-// ============================================================================
-// Variants
-// ============================================================================
-
-const recordButtonVariants = cva(
-  [
-    'relative inline-flex items-center justify-center',
-    'rounded-full 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',
-  ],
-  {
-    variants: {
-      variant: {
-        default: [
-          'text-neutral-500 hover:text-neutral-700 hover:bg-neutral-100',
-          'dark:text-neutral-400 dark:hover:text-neutral-200 dark:hover:bg-neutral-800',
-        ],
-        filled: [
-          'bg-neutral-100 text-neutral-600 hover:bg-neutral-200',
-          'dark:bg-neutral-800 dark:text-neutral-300 dark:hover:bg-neutral-700',
-        ],
-        primary: [
-          'bg-primary-600 text-white hover:bg-primary-700',
-          'dark:bg-primary-500 dark:hover:bg-primary-600',
-        ],
-      },
-      size: {
-        sm: 'h-7 w-7',
-        md: 'h-9 w-9',
-        lg: 'h-11 w-11',
-      },
-    },
-    defaultVariants: {
-      variant: 'default',
-      size: 'md',
-    },
-  }
-);
-
-const recordingIndicatorVariants = cva(
-  [
-    'absolute -top-1 -right-1',
-    'flex items-center justify-center',
-    'rounded-full bg-red-500 text-white',
-    'animate-pulse',
-  ],
-  {
-    variants: {
-      size: {
-        sm: 'h-3 w-3',
-        md: 'h-4 w-4',
-        lg: 'h-5 w-5',
-      },
-    },
-    defaultVariants: {
-      size: 'md',
-    },
-  }
-);
 
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function formatDuration(seconds: number): string {
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
+  // Recording callbacks (for uncontrolled usage)
+  /** Callback when recording is complete with the audio blob */
+  onRecordingComplete?: (blob: Blob, duration: number) => void;
+  /** Callback when recording starts */
+  onRecordingStart?: () => void;
+  /** Callback when a recording error occurs */
+  onRecordingError?: (error: Error) => void;
+  /** Maximum recording duration in seconds (0 for unlimited) */
+  maxDuration?: number;
+  /** Audio MIME type */
+  mimeType?: string;
 }
 
 // ============================================================================
 // Icons
 // ============================================================================
 
-function MicrophoneIcon({ className }: { className?: string }) {
+function MicIcon({ className }: { className?: string }) {
   return (
     <svg
-      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
       fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M12 2a3 3 0 0 0-3 3v7a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3Z" />
+      <path d="M19 10v2a7 7 0 0 1-14 0v-2" />
+      <line x1="12" x2="12" y1="19" y2="22" />
+    </svg>
+  );
+}
+
+function MicOffIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
       viewBox="0 0 24 24"
-      strokeWidth={2}
+      fill="none"
       stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
       aria-hidden="true"
     >
-      <path
-        strokeLinecap="round"
-        strokeLinejoin="round"
-        d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z"
-      />
+      <line x1="2" x2="22" y1="2" y2="22" />
+      <path d="M18.89 13.23A7.12 7.12 0 0 0 19 12v-2" />
+      <path d="M5 10v2a7 7 0 0 0 12 5" />
+      <path d="M15 9.34V5a3 3 0 0 0-5.68-1.33" />
+      <path d="M9 9v3a3 3 0 0 0 5.12 2.12" />
+      <line x1="12" x2="12" y1="19" y2="22" />
     </svg>
   );
 }
@@ -154,9 +123,10 @@ function MicrophoneIcon({ className }: { className?: string }) {
 function StopIcon({ className }: { className?: string }) {
   return (
     <svg
-      className={className}
-      fill="currentColor"
+      xmlns="http://www.w3.org/2000/svg"
       viewBox="0 0 24 24"
+      fill="currentColor"
+      className={className}
       aria-hidden="true"
     >
       <rect x="6" y="6" width="12" height="12" rx="2" />
@@ -164,257 +134,571 @@ function StopIcon({ className }: { className?: string }) {
   );
 }
 
-function SpinnerIcon({ className }: { className?: string }) {
+function CheckIcon({ className }: { className?: string }) {
   return (
     <svg
-      className={cn('animate-spin', className)}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
       fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+function LoadingSpinner({ className }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
       viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn('animate-spin', className)}
       aria-hidden="true"
     >
-      <circle
-        className="opacity-25"
-        cx="12"
-        cy="12"
-        r="10"
-        stroke="currentColor"
-        strokeWidth="4"
+      <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+    </svg>
+  );
+}
+
+// ============================================================================
+// Pulse Ring Animation (for recording state)
+// ============================================================================
+
+function PulseRings({ variant }: { variant: RecordButtonVariant }) {
+  const ringColor = variant === 'minimal' ? 'bg-red-500/30' : 'bg-red-400/40';
+
+  return (
+    <>
+      <span
+        className={cn('absolute inset-0 animate-ping rounded-full', ringColor)}
+        style={{ animationDuration: '1.5s' }}
       />
-      <path
-        className="opacity-75"
-        fill="currentColor"
-        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+      <span
+        className={cn('absolute inset-0 animate-ping rounded-full', ringColor)}
+        style={{ animationDuration: '1.5s', animationDelay: '0.5s' }}
       />
-    </svg>
+    </>
   );
 }
 
+// ============================================================================
+// Waveform Animation (for recording state)
+// ============================================================================
+
+function WaveformBars({ size }: { size: RecordButtonSize }) {
+  const barHeight = size === 'sm' ? 'h-2' : size === 'md' ? 'h-3' : 'h-4';
+
+  return (
+    <div className="flex items-center gap-0.5">
+      {[0, 1, 2, 3, 4].map((i) => (
+        <span
+          key={i}
+          className={cn(
+            'animate-waveform w-0.5 rounded-full bg-current',
+            barHeight
+          )}
+          style={{
+            animationDelay: `${i * 0.1}s`,
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ============================================================================
+// Style Variants
+// ============================================================================
+
+const recordButtonVariants = cva(
+  [
+    'relative inline-flex items-center justify-center rounded-full',
+    'transition-all duration-200',
+    'outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+  ],
+  {
+    variants: {
+      variant: {
+        default: '',
+        outline: 'border-2',
+        ghost: '',
+        minimal: '',
+      },
+      size: {
+        sm: 'size-10',
+        md: 'size-12',
+        lg: 'size-14',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'md',
+    },
+  }
+);
+
+const iconSizes: Record<RecordButtonSize, string> = {
+  sm: 'size-4',
+  md: 'size-5',
+  lg: 'size-6',
+};
+
+// ============================================================================
+// State Styles
+// ============================================================================
+
+function getStateStyles(
+  state: RecordButtonState,
+  variant: RecordButtonVariant
+): string {
+  const styles: Record<
+    RecordButtonVariant,
+    Record<RecordButtonState, string>
+  > = {
+    default: {
+      idle: 'bg-primary/10 text-primary hover:bg-primary/20',
+      recording: 'bg-red-500/10 text-red-500 hover:bg-red-500/20',
+      processing: 'bg-primary/10 text-primary cursor-wait',
+      disabled: 'bg-muted text-muted-foreground cursor-not-allowed opacity-50',
+      error: 'bg-destructive/10 text-destructive',
+      success: 'bg-success/10 text-success',
+    },
+    outline: {
+      idle: 'border-primary/50 text-primary bg-transparent hover:bg-primary/10 hover:border-primary',
+      recording:
+        'border-red-500/50 text-red-500 bg-transparent hover:bg-red-500/10 hover:border-red-500',
+      processing: 'border-primary/50 text-primary bg-transparent cursor-wait',
+      disabled:
+        'border-muted text-muted-foreground bg-transparent cursor-not-allowed opacity-50',
+      error: 'border-destructive/50 text-destructive bg-transparent',
+      success: 'border-success/50 text-success bg-transparent',
+    },
+    ghost: {
+      idle: 'text-primary hover:bg-primary/10',
+      recording: 'text-red-500 hover:bg-red-500/10',
+      processing: 'text-primary bg-primary/5 cursor-wait',
+      disabled: 'text-muted-foreground cursor-not-allowed opacity-50',
+      error: 'text-destructive',
+      success: 'text-success',
+    },
+    minimal: {
+      idle: 'text-primary hover:text-primary/80',
+      recording: 'text-red-500 hover:text-red-500/80',
+      processing: 'text-primary cursor-wait',
+      disabled: 'text-muted-foreground/40 cursor-not-allowed',
+      error: 'text-destructive',
+      success: 'text-success',
+    },
+  };
+
+  return styles[variant][state];
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function formatDuration(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}
+
 // ============================================================================
 // Main Component
 // ============================================================================
 
 /**
- * A simple microphone recording button that can be placed anywhere.
- * Perfect for adding voice input to text fields, chat inputs, or forms.
+ * A voice recording button with 6 states and 4 visual variants.
+ * Supports pulse animations, waveform visualization, and transcription integration.
+ *
+ * ## Controlled vs Uncontrolled Mode
+ *
+ * **Uncontrolled mode** (default): The component manages its own recording state.
+ * Use `onRecordingComplete`, `onRecordingStart`, and `onRecordingError` callbacks.
+ *
+ * **Controlled mode**: When the `state` prop is provided, the component becomes
+ * controlled and you must manage state changes externally. Note: In controlled mode,
+ * the internal MediaRecorder functionality is disabled - you must implement your own
+ * recording logic.
+ *
+ * ## State Precedence
+ *
+ * When multiple state-controlling props are provided, they follow this precedence:
+ * 1. `disabled` prop (highest priority)
+ * 2. `transcriptionState` prop
+ * 3. `state` prop
+ * 4. Internal state (uncontrolled)
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Uncontrolled with recording callbacks
  * <RecordButton
- *   onRecordingComplete={(blob, duration) => {
- *     console.log('Recorded:', blob, duration);
- *   }}
+ *   onRecordingComplete={(blob, duration) => console.log('Recorded:', blob)}
+ *   onRecordingError={(error) => console.error('Recording failed:', error)}
  * />
  *
- * // In an input field
- * <div className="relative">
- *   <Input className="pr-12" />
- *   <div className="absolute right-2 top-1/2 -translate-y-1/2">
- *     <RecordButton size="sm" onRecordingComplete={handleRecording} />
- *   </div>
- * </div>
+ * // Controlled state (requires external recording implementation)
+ * <RecordButton state="idle" onClick={handleClick} />
+ *
+ * // Different variants
+ * <RecordButton variant="outline" size="lg" />
  *
- * // With max duration
- * <RecordButton maxDuration={30} showDuration />
+ * // With waveform animation
+ * <RecordButton state="recording" showWaveform showPulse />
  * ```
  */
-function RecordButton({
-  onRecordingComplete,
-  onRecordingStart,
-  onError,
-  maxDuration = 0,
-  mimeType = 'audio/webm',
-  disabled = false,
-  variant,
-  size,
-  className,
-  'aria-label': ariaLabel,
-  showDuration = false,
-  idleIcon,
-  recordingIcon,
-  transcriptionState,
-  showTranscriptionState = false,
-}: RecordButtonProps) {
-  const [state, setState] = React.useState<RecordButtonState>('idle');
-  const [duration, setDuration] = React.useState(0);
-
-  const mediaRecorderRef = React.useRef<MediaRecorder | null>(null);
-  const streamRef = React.useRef<MediaStream | null>(null);
-  const chunksRef = React.useRef<Blob[]>([]);
-  const timerRef = React.useRef<number | undefined>(undefined);
-  const startTimeRef = React.useRef<number>(0);
-
-  const isRecording = state === 'recording';
-  const isProcessing = state === 'processing';
-  const isTranscribing =
-    transcriptionState === 'transcribing' || transcriptionState === 'streaming';
-
-  // Cleanup on unmount
-  React.useEffect(() => {
-    return () => {
-      if (timerRef.current) {
-        clearInterval(timerRef.current);
-      }
-      if (streamRef.current) {
-        streamRef.current.getTracks().forEach((track) => track.stop());
-      }
+const RecordButton = React.forwardRef<HTMLButtonElement, RecordButtonProps>(
+  (
+    {
+      className,
+      variant = 'default',
+      size = 'md',
+      state: controlledState,
+      showWaveform = false,
+      showPulse = true,
+      disabled,
+      showDuration = false,
+      idleIcon,
+      recordingIcon,
+      transcriptionState,
+      showTranscriptionState = false,
+      onRecordingComplete,
+      onRecordingStart,
+      onRecordingError,
+      maxDuration = 0,
+      mimeType = 'audio/webm',
+      onClick,
+      ...props
+    },
+    ref
+  ) => {
+    // Internal state for uncontrolled usage
+    const [internalState, setInternalState] =
+      React.useState<RecordButtonState>('idle');
+    const [duration, setDuration] = React.useState(0);
+
+    const mediaRecorderRef = React.useRef<MediaRecorder | null>(null);
+    const streamRef = React.useRef<MediaStream | null>(null);
+    const chunksRef = React.useRef<Blob[]>([]);
+    const timerRef = React.useRef<number | undefined>(undefined);
+    const startTimeRef = React.useRef<number>(0);
+    const timeoutsRef = React.useRef<NodeJS.Timeout[]>([]);
+
+    // Helper to track and manage timeouts
+    const addTimeout = (callback: () => void, delay: number) => {
+      const id = setTimeout(() => {
+        callback();
+        // Remove from tracking after execution
+        timeoutsRef.current = timeoutsRef.current.filter((t) => t !== id);
+      }, delay);
+      timeoutsRef.current.push(id);
+      return id;
     };
-  }, []);
-
-  const stopRecording = React.useCallback(() => {
-    if (timerRef.current) {
-      clearInterval(timerRef.current);
-    }
-
-    if (
-      mediaRecorderRef.current &&
-      mediaRecorderRef.current.state !== 'inactive'
-    ) {
-      mediaRecorderRef.current.stop();
-    }
-
-    if (streamRef.current) {
-      streamRef.current.getTracks().forEach((track) => track.stop());
-    }
-  }, []);
-
-  const startRecording = React.useCallback(async () => {
-    if (disabled || isRecording || isProcessing) return;
-
-    try {
-      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-      streamRef.current = stream;
-
-      const options = { mimeType };
-      if (!MediaRecorder.isTypeSupported(mimeType)) {
-        mediaRecorderRef.current = new MediaRecorder(stream);
-      } else {
-        mediaRecorderRef.current = new MediaRecorder(stream, options);
-      }
 
-      chunksRef.current = [];
+    const clearAllTimeouts = () => {
+      timeoutsRef.current.forEach(clearTimeout);
+      timeoutsRef.current = [];
+    };
 
-      mediaRecorderRef.current.ondataavailable = (e) => {
-        if (e.data.size > 0) {
-          chunksRef.current.push(e.data);
+    // Use controlled state if provided, otherwise internal state
+    const isControlled = controlledState !== undefined;
+    const currentState = isControlled ? controlledState : internalState;
+
+    // Map transcription state to button state if provided
+    // Precedence: disabled prop → transcriptionState → state prop → internal state
+    const effectiveState: RecordButtonState = disabled
+      ? 'disabled'
+      : transcriptionState === 'error'
+        ? 'error'
+        : transcriptionState === 'transcribing' ||
+            transcriptionState === 'streaming'
+          ? 'processing'
+          : transcriptionState === 'complete'
+            ? 'success'
+            : currentState;
+
+    // Dev mode warnings for conflicting states
+    React.useEffect(() => {
+      // Only warn in development
+      if (typeof window === 'undefined') return;
+
+      // Warn when disabled is true but other state props suggest a different visual state
+      if (
+        disabled &&
+        ((controlledState && controlledState !== 'disabled') ||
+          transcriptionState)
+      ) {
+        console.warn(
+          '[RecordButton]: `disabled` prop takes precedence over both `state` and `transcriptionState`. ' +
+            'When `disabled` is true, the button will always appear disabled.'
+        );
+      }
+
+      // Warn when both controlled state and transcriptionState are provided and conflict
+      if (controlledState !== undefined && transcriptionState !== undefined) {
+        const mappedTranscriptionState: RecordButtonState | undefined =
+          transcriptionState === 'error'
+            ? 'error'
+            : transcriptionState === 'transcribing' ||
+                transcriptionState === 'streaming'
+              ? 'processing'
+              : transcriptionState === 'complete'
+                ? 'success'
+                : undefined;
+
+        if (
+          mappedTranscriptionState !== undefined &&
+          mappedTranscriptionState !== controlledState
+        ) {
+          console.warn(
+            '[RecordButton]: `transcriptionState` takes precedence over `state`. ' +
+              `Received state="${controlledState}" and transcriptionState="${transcriptionState}". ` +
+              'This may lead to unexpected visual states.'
+          );
+        }
+      }
+    }, [disabled, controlledState, transcriptionState]);
+
+    const iconSize = iconSizes[size];
+    const isRecording = effectiveState === 'recording';
+    const isDisabled =
+      effectiveState === 'disabled' || effectiveState === 'processing';
+
+    // Cleanup on unmount
+    React.useEffect(() => {
+      return () => {
+        if (timerRef.current) {
+          clearInterval(timerRef.current);
+        }
+        clearAllTimeouts();
+        if (streamRef.current) {
+          streamRef.current.getTracks().forEach((track) => track.stop());
         }
       };
+    }, []);
 
-      mediaRecorderRef.current.onstop = () => {
-        setState('processing');
-
-        const blob = new Blob(chunksRef.current, { type: mimeType });
-        const finalDuration = duration;
-
-        // Small delay to show processing state
-        setTimeout(() => {
-          onRecordingComplete?.(blob, finalDuration);
-          setState('idle');
-          setDuration(0);
-        }, 200);
-      };
+    const stopRecording = React.useCallback(() => {
+      if (timerRef.current) {
+        clearInterval(timerRef.current);
+      }
 
-      mediaRecorderRef.current.start(100);
-      startTimeRef.current = Date.now();
-      setState('recording');
-      onRecordingStart?.();
+      if (
+        mediaRecorderRef.current &&
+        mediaRecorderRef.current.state !== 'inactive'
+      ) {
+        mediaRecorderRef.current.stop();
+      }
 
-      timerRef.current = window.setInterval(() => {
-        const elapsed = (Date.now() - startTimeRef.current) / 1000;
-        setDuration(elapsed);
+      if (streamRef.current) {
+        streamRef.current.getTracks().forEach((track) => track.stop());
+      }
+    }, []);
+
+    const startRecording = React.useCallback(async () => {
+      // Guard: don't start if disabled, already recording, or processing
+      if (
+        disabled ||
+        effectiveState === 'recording' ||
+        effectiveState === 'processing'
+      )
+        return;
+
+      try {
+        const stream = await navigator.mediaDevices.getUserMedia({
+          audio: true,
+        });
+        streamRef.current = stream;
+
+        const options = { mimeType };
+        if (!MediaRecorder.isTypeSupported(mimeType)) {
+          mediaRecorderRef.current = new MediaRecorder(stream);
+        } else {
+          mediaRecorderRef.current = new MediaRecorder(stream, options);
+        }
 
-        if (maxDuration > 0 && elapsed >= maxDuration) {
-          stopRecording();
+        chunksRef.current = [];
+
+        mediaRecorderRef.current.ondataavailable = (e) => {
+          if (e.data.size > 0) {
+            chunksRef.current.push(e.data);
+          }
+        };
+
+        mediaRecorderRef.current.onstop = () => {
+          if (!isControlled) {
+            setInternalState('processing');
+          }
+
+          const blob = new Blob(chunksRef.current, { type: mimeType });
+          const finalDuration = duration;
+
+          // Small delay to show processing state
+          addTimeout(() => {
+            onRecordingComplete?.(blob, finalDuration);
+            if (!isControlled) {
+              setInternalState('success');
+              // Reset to idle after showing success
+              addTimeout(() => {
+                setInternalState('idle');
+              }, 1500);
+            }
+            setDuration(0);
+          }, 200);
+        };
+
+        mediaRecorderRef.current.start(100);
+        startTimeRef.current = Date.now();
+
+        if (!isControlled) {
+          setInternalState('recording');
         }
-      }, 100);
-    } catch (error) {
-      onError?.(error as Error);
-      setState('idle');
-    }
-  }, [
-    disabled,
-    isRecording,
-    isProcessing,
-    mimeType,
-    maxDuration,
-    duration,
-    onRecordingComplete,
-    onRecordingStart,
-    onError,
-    stopRecording,
-  ]);
-
-  const handleClick = React.useCallback(() => {
-    if (isRecording) {
-      stopRecording();
-    } else {
-      startRecording();
-    }
-  }, [isRecording, startRecording, stopRecording]);
-
-  const iconSize =
-    size === 'sm' ? 'h-4 w-4' : size === 'lg' ? 'h-6 w-6' : 'h-5 w-5';
-
-  const getIcon = () => {
-    if (isProcessing || isTranscribing) {
-      return <SpinnerIcon className={iconSize} />;
-    }
-    if (isRecording) {
-      return recordingIcon || <StopIcon className={iconSize} />;
-    }
-    return idleIcon || <MicrophoneIcon className={iconSize} />;
-  };
+        onRecordingStart?.();
+
+        timerRef.current = window.setInterval(() => {
+          const elapsed = (Date.now() - startTimeRef.current) / 1000;
+          setDuration(elapsed);
+
+          if (maxDuration > 0 && elapsed >= maxDuration) {
+            stopRecording();
+          }
+        }, 100);
+      } catch (error) {
+        onRecordingError?.(error as Error);
+        if (!isControlled) {
+          setInternalState('error');
+          // Reset to idle after showing error
+          addTimeout(() => {
+            setInternalState('idle');
+          }, 2000);
+        }
+      }
+    }, [
+      disabled,
+      effectiveState,
+      isControlled,
+      mimeType,
+      maxDuration,
+      duration,
+      onRecordingComplete,
+      onRecordingStart,
+      onRecordingError,
+      stopRecording,
+    ]);
+
+    const handleClick = React.useCallback(
+      (e: React.MouseEvent<HTMLButtonElement>) => {
+        // Call external onClick if provided
+        onClick?.(e);
+
+        // Handle internal recording logic only if not fully controlled
+        if (!isControlled) {
+          if (effectiveState === 'recording') {
+            stopRecording();
+          } else if (effectiveState === 'idle') {
+            startRecording();
+          }
+        }
+      },
+      [onClick, isControlled, effectiveState, startRecording, stopRecording]
+    );
+
+    // Determine which icon to show
+    const renderIcon = () => {
+      switch (effectiveState) {
+        case 'recording':
+          if (showWaveform) {
+            return <WaveformBars size={size} />;
+          }
+          return recordingIcon || <StopIcon className={iconSize} />;
+        case 'processing':
+          return <LoadingSpinner className={iconSize} />;
+        case 'disabled':
+        case 'error':
+          return <MicOffIcon className={iconSize} />;
+        case 'success':
+          return <CheckIcon className={iconSize} />;
+        default:
+          return idleIcon || <MicIcon className={iconSize} />;
+      }
+    };
 
-  const getAriaLabel = () => {
-    if (ariaLabel) return ariaLabel;
-    if (isTranscribing) return 'Transcribing audio';
-    if (isProcessing) return 'Processing recording';
-    if (isRecording) return 'Stop recording';
-    return 'Start recording';
-  };
+    const getAriaLabel = () => {
+      switch (effectiveState) {
+        case 'recording':
+          return 'Stop recording';
+        case 'processing':
+          return 'Processing recording';
+        case 'disabled':
+          return 'Recording unavailable';
+        case 'error':
+          return 'Recording failed';
+        case 'success':
+          return 'Recording complete';
+        default:
+          return 'Start recording';
+      }
+    };
 
-  const getTranscriptionLabel = () => {
-    if (transcriptionState === 'streaming') return 'Listening...';
-    if (transcriptionState === 'transcribing') return 'Transcribing...';
-    return null;
-  };
+    const getTranscriptionLabel = () => {
+      if (transcriptionState === 'streaming') return 'Listening...';
+      if (transcriptionState === 'transcribing') return 'Transcribing...';
+      return null;
+    };
 
-  return (
-    <div className="relative inline-flex items-center gap-2">
-      <button
-        type="button"
-        onClick={handleClick}
-        disabled={disabled || isProcessing || isTranscribing}
-        className={cn(
-          recordButtonVariants({ variant, size }),
-          isRecording && 'text-red-600 dark:text-red-400',
-          isTranscribing && 'text-primary-600 dark:text-primary-400',
-          className
+    return (
+      <div className="relative inline-flex items-center gap-2">
+        <button
+          ref={ref}
+          type="button"
+          disabled={isDisabled}
+          onClick={handleClick}
+          {...props}
+          className={cn(
+            recordButtonVariants({ variant, size }),
+            getStateStyles(effectiveState, variant),
+            className
+          )}
+          aria-label={getAriaLabel()}
+          aria-pressed={effectiveState === 'recording' ? true : undefined}
+          aria-busy={effectiveState === 'processing' ? true : undefined}
+        >
+          {/* Pulse animation for recording state */}
+          {effectiveState === 'recording' && showPulse && (
+            <PulseRings variant={variant} />
+          )}
+
+          {/* Icon */}
+          <span className="relative z-10">{renderIcon()}</span>
+        </button>
+
+        {/* Duration display */}
+        {showDuration && isRecording && (
+          <span className="text-destructive font-mono text-xs tabular-nums">
+            {formatDuration(duration)}
+          </span>
         )}
-        aria-label={getAriaLabel()}
-        aria-pressed={isRecording}
-      >
-        {getIcon()}
-        {isRecording && !isTranscribing && (
-          <span
-            className={cn(recordingIndicatorVariants({ size }))}
-            aria-hidden="true"
-          />
+
+        {/* Transcription state label */}
+        {showTranscriptionState && getTranscriptionLabel() && (
+          <span className="text-primary text-xs font-medium">
+            {getTranscriptionLabel()}
+          </span>
         )}
-      </button>
-      {showDuration && isRecording && (
-        <span className="font-mono text-xs text-red-600 tabular-nums dark:text-red-400">
-          {formatDuration(duration)}
-        </span>
-      )}
-      {showTranscriptionState && getTranscriptionLabel() && (
-        <span className="text-primary-600 dark:text-primary-400 text-xs font-medium">
-          {getTranscriptionLabel()}
-        </span>
-      )}
-    </div>
-  );
-}
+      </div>
+    );
+  }
+);
 
 RecordButton.displayName = 'RecordButton';
 
@@ -422,9 +706,4 @@ RecordButton.displayName = 'RecordButton';
 // Exports
 // ============================================================================
 
-export {
-  RecordButton,
-  recordButtonVariants,
-  recordingIndicatorVariants,
-  formatDuration,
-};
+export { RecordButton, recordButtonVariants, formatDuration };
diff --git a/src/components/RecordButton/index.ts b/src/components/RecordButton/index.ts
index c7a40ec4..e8817ac0 100644
--- a/src/components/RecordButton/index.ts
+++ b/src/components/RecordButton/index.ts
@@ -1,10 +1,11 @@
 export {
   RecordButton,
   recordButtonVariants,
-  recordingIndicatorVariants,
   formatDuration,
   type RecordButtonProps,
   type RecordButtonState,
+  type RecordButtonVariant,
+  type RecordButtonSize,
   type TranscriptionState,
   type TranscriptionResult,
 } from './RecordButton';
diff --git a/src/styles/base.css b/src/styles/base.css
index 553391b3..3b392e28 100644
--- a/src/styles/base.css
+++ b/src/styles/base.css
@@ -171,3 +171,21 @@ kbd {
     transition-duration: 0.01ms !important;
   }
 }
+
+/* ============================================
+   Waveform Animation (for RecordButton)
+   ============================================ */
+
+@keyframes waveform {
+  0%,
+  100% {
+    transform: scaleY(0.3);
+  }
+  50% {
+    transform: scaleY(1);
+  }
+}
+
+.animate-waveform {
+  animation: waveform 0.5s ease-in-out infinite;
+}