diff --git a/packages/ui/src/components/composites/Input/index.ts b/packages/ui/src/components/composites/Input/index.ts
new file mode 100644
index 000000000..3d5f36e60
--- /dev/null
+++ b/packages/ui/src/components/composites/Input/index.ts
@@ -0,0 +1,4 @@
+import type { CompositeInputProps, SelectGroup, SelectItem } from './input'
+import { CompositeInput } from './input'
+
+export { CompositeInput, type CompositeInputProps, type SelectGroup, type SelectItem }
diff --git a/packages/ui/src/components/composites/Input/input.tsx b/packages/ui/src/components/composites/Input/input.tsx
new file mode 100644
index 000000000..80c83fe15
--- /dev/null
+++ b/packages/ui/src/components/composites/Input/input.tsx
@@ -0,0 +1,371 @@
+import { cn, toUndefinedIfNull } from '@cherrystudio/ui/utils'
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+import { Edit2Icon, EyeIcon, EyeOffIcon } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { useCallback, useMemo, useState } from 'react'
+
+import type { InputProps } from '../../primitives/input'
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '../../primitives/input-group'
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue
+} from '../../primitives/select'
+
+const inputGroupVariants = cva(
+  [
+    'h-auto',
+    'rounded-xs',
+    'has-[[data-slot=input-group-control]:focus-visible]:ring-ring/40',
+    'has-[[data-slot=input-group-control]:focus-visible]:border-[#3CD45A]'
+  ],
+  {
+    variants: {
+      disabled: {
+        false: null,
+        true: ['bg-background-subtle', 'border-border-hover', 'cursor-not-allowed']
+      }
+    },
+    defaultVariants: {
+      disabled: false
+    }
+  }
+)
+
+const inputVariants = cva(['p-0', 'h-fit', 'min-w-0'], {
+  variants: {
+    size: {
+      sm: ['text-sm', 'leading-4'],
+      md: ['leading-4.5'],
+      lg: ['text-lg', 'leading-5']
+    },
+    variant: {
+      default: [],
+      button: [],
+      email: [],
+      select: []
+    },
+    disabled: {
+      false: null,
+      true: ['text-foreground/40', 'placeholder:text-foreground/40', 'disabled:opacity-100']
+    }
+  },
+  defaultVariants: {
+    size: 'md',
+    variant: 'default',
+    disabled: false
+  }
+})
+
+const inputWrapperVariants = cva(['flex', 'flex-1', 'items-center', 'gap-2'], {
+  variants: {
+    size: {
+      sm: ['p-3xs'],
+      // Why only the md size is fixed height???
+      md: ['p-3xs', 'h-5.5', 'box-content'],
+      lg: ['px-2xs', 'py-3xs']
+    },
+    variant: {
+      default: [],
+      button: 'border-r-[1px]',
+      email: [],
+      select: []
+    },
+    disabled: {
+      false: null,
+      true: 'border-background-subtle'
+    }
+  },
+  defaultVariants: {
+    disabled: false
+  }
+})
+
+const iconVariants = cva([], {
+  variants: {
+    size: {
+      sm: 'size-4.5',
+      md: 'size-5',
+      lg: 'size-6'
+    },
+    disabled: {
+      false: null,
+      true: 'text-foreground/40'
+    }
+  },
+  defaultVariants: {
+    size: 'md',
+    disabled: false
+  }
+})
+
+const iconButtonVariants = cva(['text-foreground/60 cursor-pointer transition-colors', 'hover:shadow-none'], {
+  variants: {
+    disabled: {
+      false: null,
+      true: []
+    }
+  },
+  defaultVariants: {
+    disabled: false
+  }
+})
+
+const buttonVariants = cva(
+  ['py-3xs', 'flex flex-col', 'text-foreground/60 cursor-pointer transition-colors', 'hover:shadow-none'],
+  {
+    variants: {
+      size: {
+        sm: 'px-3xs',
+        md: 'px-3xs',
+        lg: 'px-2xs'
+      },
+      disabled: {
+        false: null,
+        true: ['pointer-events-none']
+      }
+    },
+    defaultVariants: {
+      size: 'md',
+      disabled: false
+    }
+  }
+)
+
+const buttonLabelVariants = cva([], {
+  variants: {
+    size: {
+      // TODO: p/font-family, p/letter-spacing ... p?
+      sm: 'text-sm leading-4',
+      md: 'leading-4.5',
+      lg: 'text-lg leading-5 tracking-normal'
+    },
+    disabled: {
+      false: null,
+      true: ['text-foreground/40']
+    }
+  },
+  defaultVariants: {
+    size: 'md',
+    disabled: false
+  }
+})
+
+const prefixVariants = cva(['font-medium', 'border-r-[1px]', 'text-foreground/60'], {
+  variants: {
+    size: {
+      // TODO: semantic letter-spacing
+      sm: ['text-sm leading-4', 'p-3xs'],
+      md: ['leading-4.5', 'p-3xs'],
+      lg: ['leading-5 tracking-normal', 'px-2xs py-3xs']
+    },
+    disabled: {
+      false: null,
+      true: 'text-foreground/40'
+    }
+  },
+  defaultVariants: {
+    size: 'md',
+    disabled: false
+  }
+})
+
+const selectPrefixVariants = cva(['font-medium', 'border-r-[1px]', 'text-foreground/60', 'p-0'], {
+  variants: {
+    size: {
+      // TODO: semantic letter-spacing
+      sm: 'text-sm leading-4',
+      md: 'leading-4.5',
+      lg: 'leading-5 tracking-normal'
+    },
+    disabled: {
+      false: null,
+      true: 'text-foreground/40'
+    }
+  },
+  defaultVariants: {
+    size: 'md',
+    disabled: false
+  }
+})
+
+const selectTriggerVariants = cva(
+  [
+    'border-none box-content pl-3 aria-expanded:border-none aria-expanded:ring-0 bg-transparent',
+    '*:data-[slot=select-value]:text-foreground',
+    '[&_svg]:text-secondary-foreground!'
+  ],
+  {
+    variants: {
+      size: {
+        sm: ['h-5', 'pl-6 pr-3xs py-3', '*:data-[slot=select-value]:text-sm'],
+        md: ['h-5', 'pl-6 pr-3xs py-[13px]'],
+        lg: ['h-6', 'pl-7 pr-2xs py-3', '*:data-[slot=select-value]:text-lg']
+      }
+    }
+  }
+)
+
+const selectTriggerLabelVariants = cva([], {
+  variants: {
+    size: {
+      // TODO: p/font-family, p/letter-spacing ... p?
+      sm: 'text-sm leading-4',
+      md: 'leading-4.5',
+      lg: 'text-lg leading-5 tracking-normal'
+    }
+  }
+})
+
+function ShowPasswordButton({
+  type,
+  setType,
+  size = 'md',
+  disabled = false
+}: {
+  type: 'text' | 'password'
+  setType: React.Dispatch<React.SetStateAction<'text' | 'password'>>
+  size: VariantProps<typeof inputVariants>['size']
+  disabled: boolean
+}) {
+  const togglePassword = useCallback(() => {
+    if (disabled) return
+    if (type === 'password') {
+      setType('text')
+    } else if (type === 'text') {
+      setType('password')
+    }
+  }, [disabled, setType, type])
+
+  const iconClassName = iconVariants({ size, disabled })
+
+  return (
+    <InputGroupButton onClick={togglePassword} disabled={disabled} className={iconButtonVariants({ disabled })}>
+      {type === 'text' && <EyeIcon className={iconClassName} />}
+      {type === 'password' && <EyeOffIcon className={iconClassName} />}
+    </InputGroupButton>
+  )
+}
+
+interface SelectItem {
+  label: ReactNode
+  value: string
+}
+
+interface SelectGroup {
+  label: ReactNode
+  items: SelectItem[]
+}
+
+interface CompositeInputProps
+  extends Omit<InputProps, 'size' | 'disabled' | 'prefix'>,
+    VariantProps<typeof inputVariants> {
+  buttonProps?: {
+    label?: ReactNode
+    onClick: React.DOMAttributes<HTMLButtonElement>['onClick']
+  }
+  prefix?: ReactNode
+  selectProps?: {
+    groups: SelectGroup[]
+    placeholder?: string
+  }
+}
+
+function CompositeInput({
+  type = 'text',
+  size = 'md',
+  variant = 'default',
+  disabled = false,
+  buttonProps,
+  prefix,
+  selectProps,
+  className,
+  ...rest
+}: CompositeInputProps) {
+  const isPassword = type === 'password'
+  const [htmlType, setHtmlType] = useState<'text' | 'password'>('password')
+
+  const buttonContent = useMemo(() => {
+    if (buttonProps === undefined) {
+      console.warn("CustomizedInput: 'button' variant requires a 'button' prop to be provided.")
+      return null
+    } else {
+      return (
+        <InputGroupButton className={buttonVariants({ size, disabled })} onClick={buttonProps.onClick}>
+          <div className={buttonLabelVariants({ size, disabled })}>{buttonProps.label}</div>
+        </InputGroupButton>
+      )
+    }
+  }, [buttonProps, disabled, size])
+
+  const emailContent = useMemo(() => {
+    if (!prefix) {
+      console.warn('CompositeInput: "email" variant requires a "prefix" prop to be provided.')
+      return null
+    } else {
+      return <div className={prefixVariants({ size, disabled })}>{prefix}</div>
+    }
+  }, [disabled, prefix, size])
+
+  const selectContent = useMemo(() => {
+    if (!selectProps) {
+      console.warn('CompositeInput: "select" variant requires a "selectProps" prop to be provided.')
+      return null
+    } else {
+      return (
+        <div className={selectPrefixVariants({ size, disabled })}>
+          <Select>
+            <SelectTrigger className={selectTriggerVariants({ size })}>
+              <SelectValue placeholder={selectProps.placeholder} className={selectTriggerLabelVariants({ size })} />
+            </SelectTrigger>
+            <SelectContent>
+              {selectProps.groups.map((group, index) => (
+                <SelectGroup key={index}>
+                  <SelectLabel>{group.label}</SelectLabel>
+                  {group.items.map((item) => (
+                    <SelectItem key={item.value} value={item.value}>
+                      {item.label}
+                    </SelectItem>
+                  ))}
+                </SelectGroup>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      )
+    }
+  }, [disabled, selectProps, size])
+
+  return (
+    <InputGroup className={inputGroupVariants({ disabled })}>
+      {variant === 'email' && emailContent}
+      {variant === 'select' && selectContent}
+      <div className={inputWrapperVariants({ size, variant, disabled })}>
+        <InputGroupInput
+          type={isPassword ? htmlType : type}
+          disabled={toUndefinedIfNull(disabled)}
+          className={cn(inputVariants({ size, variant, disabled }), className)}
+          {...rest}
+        />
+        {(variant === 'default' || variant === 'button') && (
+          <>
+            <InputGroupAddon className="p-0">
+              <Edit2Icon className={iconVariants({ size, disabled })} />
+            </InputGroupAddon>
+            <InputGroupAddon align="inline-end" className="p-0">
+              <ShowPasswordButton type={htmlType} setType={setHtmlType} size={size} disabled={!!disabled} />
+            </InputGroupAddon>
+          </>
+        )}
+      </div>
+      {variant === 'button' && buttonContent}
+    </InputGroup>
+  )
+}
+
+export { CompositeInput, type CompositeInputProps, type SelectGroup, type SelectItem }
diff --git a/packages/ui/src/components/index.ts b/packages/ui/src/components/index.ts
index 30777112f..4545e19ce 100644
--- a/packages/ui/src/components/index.ts
+++ b/packages/ui/src/components/index.ts
@@ -49,6 +49,12 @@ export { HelpTooltip, type IconTooltipProps, InfoTooltip, WarnTooltip } from './
 // ImageToolButton
 export { default as ImageToolButton } from './composites/ImageToolButton'
 // Sortable
+export {
+  CompositeInput,
+  type CompositeInputProps,
+  type SelectGroup as CompositeInputSelectGroup,
+  type SelectItem as CompositeInputSelectItem
+} from './composites/Input'
 export { Sortable } from './composites/Sortable'
 
 /* Shadcn Primitive Components */
@@ -58,6 +64,8 @@ export * from './primitives/checkbox'
 export * from './primitives/combobox'
 export * from './primitives/command'
 export * from './primitives/dialog'
+export * from './primitives/input'
+export * from './primitives/input-group'
 export * from './primitives/kbd'
 export * from './primitives/pagination'
 export * from './primitives/popover'
@@ -65,3 +73,4 @@ export * from './primitives/radioGroup'
 export * from './primitives/select'
 export * from './primitives/shadcn-io/dropzone'
 export * from './primitives/tabs'
+export * from './primitives/textarea'
diff --git a/packages/ui/src/components/primitives/input-group.tsx b/packages/ui/src/components/primitives/input-group.tsx
new file mode 100644
index 000000000..8c9ff10fa
--- /dev/null
+++ b/packages/ui/src/components/primitives/input-group.tsx
@@ -0,0 +1,147 @@
+import { Button } from '@cherrystudio/ui/components/primitives/button'
+import type { InputProps } from '@cherrystudio/ui/components/primitives/input'
+import { Input } from '@cherrystudio/ui/components/primitives/input'
+import { Textarea } from '@cherrystudio/ui/components/primitives/textarea'
+import { cn } from '@cherrystudio/ui/utils/index'
+import { cva, type VariantProps } from 'class-variance-authority'
+import * as React from 'react'
+
+function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        'group/input-group border-input bg-background relative flex w-full items-center rounded-md border shadow-xs transition-[color,box-shadow] outline-none',
+        'h-9 min-w-0 has-[>textarea]:h-auto',
+
+        // Variants based on alignment.
+        'has-[>[data-align=inline-start]]:[&>input]:pl-2',
+        'has-[>[data-align=inline-end]]:[&>input]:pr-2',
+        'has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3',
+        'has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3',
+
+        // Focus state.
+        'has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot=input-group-control]:focus-visible]:ring-[3px]',
+
+        // Error state.
+        'has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40',
+
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const inputGroupAddonVariants = cva(
+  "text-muted-foreground flex h-auto items-center justify-center gap-2 py-1.5 text-sm font-medium select-none [&>svg:not([class*='size-'])]:size-4 group-data-[disabled=true]/input-group:opacity-50",
+  {
+    variants: {
+      align: {
+        'inline-start': 'order-first pl-3 has-[>button]:ml-[-0.45rem] has-[>kbd]:ml-[-0.35rem]',
+        'inline-end': 'order-last pr-3 has-[>button]:mr-[-0.45rem] has-[>kbd]:mr-[-0.35rem]',
+        'block-start':
+          'order-first w-full justify-start px-3 pt-3 [.border-b]:pb-3 group-has-[>input]/input-group:pt-2.5',
+        'block-end': 'order-last w-full justify-start px-3 pb-3 [.border-t]:pt-3 group-has-[>input]/input-group:pb-2.5'
+      }
+    },
+    defaultVariants: {
+      align: 'inline-start'
+    }
+  }
+)
+
+function InputGroupAddon({
+  className,
+  align = 'inline-start',
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest('button')) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector('input')?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+const inputGroupButtonVariants = cva('text-sm shadow-none flex gap-2 items-center', {
+  variants: {
+    size: {
+      xs: "h-6 gap-1 px-2 [&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2",
+      sm: 'h-8 px-2.5 gap-1.5 rounded-md has-[>svg]:px-2.5',
+      'icon-xs': 'size-6 p-0 has-[>svg]:p-0',
+      'icon-sm': 'size-8 p-0 has-[>svg]:p-0'
+    }
+  },
+  defaultVariants: {
+    size: 'xs'
+  }
+})
+
+function InputGroupButton({
+  className,
+  type = 'button',
+  variant = 'ghost',
+  size = 'xs',
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, 'size'> & VariantProps<typeof inputGroupButtonVariants>) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      className={cn(
+        "text-muted-foreground flex items-center gap-2 text-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupInput({ className, ...props }: InputProps) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        'flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 dark:bg-transparent',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupTextarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        'flex-1 resize-none rounded-none border-0 bg-transparent py-3 shadow-none focus-visible:ring-0 dark:bg-transparent',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea }
diff --git a/packages/ui/src/components/primitives/input.tsx b/packages/ui/src/components/primitives/input.tsx
new file mode 100644
index 000000000..5a5e29cd5
--- /dev/null
+++ b/packages/ui/src/components/primitives/input.tsx
@@ -0,0 +1,23 @@
+import { cn } from '@cherrystudio/ui/utils'
+import * as React from 'react'
+
+interface InputProps extends React.ComponentProps<'input'> {}
+
+function Input({ className, type, ...props }: InputProps) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        'file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed md:text-sm',
+        'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+        'disabled:opacity-50',
+        'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input, type InputProps }
diff --git a/packages/ui/src/components/primitives/textarea.tsx b/packages/ui/src/components/primitives/textarea.tsx
new file mode 100644
index 000000000..fe9d943b1
--- /dev/null
+++ b/packages/ui/src/components/primitives/textarea.tsx
@@ -0,0 +1,17 @@
+import { cn } from '@cherrystudio/ui/utils'
+import * as React from 'react'
+
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        'border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }
diff --git a/packages/ui/src/utils/index.ts b/packages/ui/src/utils/index.ts
index 8a273ad83..7f0275f99 100644
--- a/packages/ui/src/utils/index.ts
+++ b/packages/ui/src/utils/index.ts
@@ -8,3 +8,25 @@ import { twMerge } from 'tailwind-merge'
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
+
+/**
+ * Converts `null` to `undefined`, otherwise returns the input value.
+ * Useful when interfacing with APIs or libraries that treat `null` and `undefined` differently.
+ * @param data - The value that might be `null`
+ * @returns `undefined` if `data` is `null`, otherwise the original value
+ */
+export const toUndefinedIfNull = <T>(data: T | null): T | undefined => {
+  if (data === null) return undefined
+  else return data
+}
+
+/**
+ * Converts `undefined` to `null`, otherwise returns the input value.
+ * Handy for ensuring consistent representation of absent values.
+ * @param data - The value that might be `undefined`
+ * @returns `null` if `data` is `undefined`, otherwise the original value
+ */
+export const toNullIfUndefined = <T>(data: T | undefined): T | null => {
+  if (data === undefined) return null
+  else return data
+}
diff --git a/packages/ui/stories/components/composites/CompositeInput.stories.tsx b/packages/ui/stories/components/composites/CompositeInput.stories.tsx
new file mode 100644
index 000000000..6428395ec
--- /dev/null
+++ b/packages/ui/stories/components/composites/CompositeInput.stories.tsx
@@ -0,0 +1,1530 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Send } from 'lucide-react'
+import { useState } from 'react'
+
+import { CompositeInput } from '../../../src/components/composites/Input'
+
+const meta: Meta<typeof CompositeInput> = {
+  title: 'Components/Composites/CompositeInput',
+  component: CompositeInput,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A composite input component built on top of InputGroup. Provides pre-configured layouts with icons and optional action buttons. Features automatic password visibility toggle and supports multiple sizes and variants for different use cases.'
+      }
+    }
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    type: {
+      control: { type: 'select' },
+      options: ['text', 'email', 'password', 'number'],
+      description: 'The type of the input'
+    },
+    variant: {
+      control: { type: 'select' },
+      options: ['default', 'button', 'email', 'select'],
+      description: 'The visual variant of the input'
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['sm', 'md', 'lg'],
+      description: 'The size of the input'
+    },
+    disabled: {
+      control: { type: 'boolean' },
+      description: 'Whether the input is disabled'
+    },
+    placeholder: {
+      control: { type: 'text' },
+      description: 'Placeholder text'
+    }
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// Basic Variants
+export const Default: Story = {
+  args: {
+    variant: 'default',
+    placeholder: 'Enter text...'
+  },
+  render: (args) => (
+    <div className="w-80">
+      <CompositeInput {...args} />
+    </div>
+  )
+}
+
+export const DefaultWithValue: Story = {
+  args: {
+    variant: 'default',
+    defaultValue: 'Hello World',
+    placeholder: 'Enter text...'
+  },
+  render: (args) => (
+    <div className="w-80">
+      <CompositeInput {...args} />
+    </div>
+  )
+}
+
+export const EmailVariant: Story = {
+  render: () => (
+    <div className="w-80">
+      <CompositeInput variant="email" type="email" placeholder="example.com" prefix="user@" />
+    </div>
+  )
+}
+
+export const EmailVariantExamples: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Email with @domain prefix</p>
+        <CompositeInput variant="email" type="email" placeholder="example.com" prefix="user@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Email with custom prefix</p>
+        <CompositeInput variant="email" type="email" placeholder="email.com" prefix="contact@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Email with company domain</p>
+        <CompositeInput variant="email" type="email" placeholder="company.com" prefix="admin@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Email with value</p>
+        <CompositeInput
+          variant="email"
+          type="email"
+          placeholder="example.com"
+          prefix="john@"
+          defaultValue="example.com"
+        />
+      </div>
+    </div>
+  )
+}
+
+export const ButtonVariant: Story = {
+  render: () => (
+    <div className="w-80">
+      <CompositeInput
+        variant="button"
+        placeholder="Enter email..."
+        buttonProps={{
+          label: 'Subscribe',
+          onClick: () => alert('Subscribed!')
+        }}
+      />
+    </div>
+  )
+}
+
+export const SelectVariant: Story = {
+  render: () => (
+    <div className="w-80">
+      <CompositeInput
+        variant="select"
+        placeholder="Enter amount..."
+        selectProps={{
+          placeholder: 'Currency',
+          groups: [
+            {
+              label: 'Popular',
+              items: [
+                { label: 'USD', value: 'usd' },
+                { label: 'EUR', value: 'eur' },
+                { label: 'GBP', value: 'gbp' }
+              ]
+            }
+          ]
+        }}
+      />
+    </div>
+  )
+}
+
+export const SelectVariantExamples: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Currency Input</p>
+        <CompositeInput
+          variant="select"
+          placeholder="0.00"
+          type="number"
+          selectProps={{
+            placeholder: 'Currency',
+            groups: [
+              {
+                label: 'Popular',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' },
+                  { label: 'GBP', value: 'gbp' }
+                ]
+              },
+              {
+                label: 'Other',
+                items: [
+                  { label: 'JPY', value: 'jpy' },
+                  { label: 'CNY', value: 'cny' },
+                  { label: 'AUD', value: 'aud' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">URL with Protocol</p>
+        <CompositeInput
+          variant="select"
+          placeholder="example.com"
+          selectProps={{
+            placeholder: 'Protocol',
+            groups: [
+              {
+                label: 'Protocol',
+                items: [
+                  { label: 'https://', value: 'https' },
+                  { label: 'http://', value: 'http' },
+                  { label: 'ftp://', value: 'ftp' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Phone with Country Code</p>
+        <CompositeInput
+          variant="select"
+          placeholder="123-456-7890"
+          type="tel"
+          selectProps={{
+            placeholder: 'Code',
+            groups: [
+              {
+                label: 'Countries',
+                items: [
+                  { label: '+1', value: 'us' },
+                  { label: '+44', value: 'uk' },
+                  { label: '+86', value: 'cn' },
+                  { label: '+81', value: 'jp' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Temperature with Unit</p>
+        <CompositeInput
+          variant="select"
+          placeholder="0"
+          type="number"
+          selectProps={{
+            placeholder: 'Unit',
+            groups: [
+              {
+                label: 'Temperature',
+                items: [
+                  { label: '°C', value: 'celsius' },
+                  { label: '°F', value: 'fahrenheit' },
+                  { label: 'K', value: 'kelvin' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// Password Input with Toggle
+export const PasswordDefault: Story = {
+  args: {
+    variant: 'default',
+    type: 'password',
+    placeholder: 'Enter password...'
+  },
+  render: (args) => (
+    <div className="w-80">
+      <CompositeInput {...args} />
+      <p className="mt-2 text-xs text-muted-foreground">Click the eye icon to toggle password visibility</p>
+    </div>
+  )
+}
+
+export const PasswordWithButton: Story = {
+  render: () => (
+    <div className="w-80">
+      <CompositeInput
+        variant="button"
+        type="password"
+        placeholder="Enter password..."
+        buttonProps={{
+          label: 'Reset',
+          onClick: () => alert('Password reset requested')
+        }}
+      />
+      <p className="mt-2 text-xs text-muted-foreground">Password field with action button and visibility toggle</p>
+    </div>
+  )
+}
+
+// Sizes
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Small (sm)</p>
+        <CompositeInput variant="default" size="sm" placeholder="Small input..." />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Medium (md) - Default</p>
+        <CompositeInput variant="default" size="md" placeholder="Medium input..." />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Large (lg)</p>
+        <CompositeInput variant="default" size="lg" placeholder="Large input..." />
+      </div>
+    </div>
+  )
+}
+
+export const SizesWithButton: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Small (sm) with Button</p>
+        <CompositeInput
+          variant="button"
+          size="sm"
+          placeholder="Small input..."
+          buttonProps={{
+            label: 'Go',
+            onClick: () => {}
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Medium (md) with Button - Default</p>
+        <CompositeInput
+          variant="button"
+          size="md"
+          placeholder="Medium input..."
+          buttonProps={{
+            label: 'Submit',
+            onClick: () => {}
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Large (lg) with Button</p>
+        <CompositeInput
+          variant="button"
+          size="lg"
+          placeholder="Large input..."
+          buttonProps={{
+            label: 'Send',
+            onClick: () => {}
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// Select Sizes
+export const SelectVariantSizes: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Small (sm)</p>
+        <CompositeInput
+          variant="select"
+          size="sm"
+          placeholder="0.00"
+          type="number"
+          selectProps={{
+            placeholder: 'USD',
+            groups: [
+              {
+                label: 'Currency',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' },
+                  { label: 'GBP', value: 'gbp' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Medium (md) - Default</p>
+        <CompositeInput
+          variant="select"
+          size="md"
+          placeholder="0.00"
+          type="number"
+          selectProps={{
+            placeholder: 'USD',
+            groups: [
+              {
+                label: 'Currency',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' },
+                  { label: 'GBP', value: 'gbp' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Large (lg)</p>
+        <CompositeInput
+          variant="select"
+          size="lg"
+          placeholder="0.00"
+          type="number"
+          selectProps={{
+            placeholder: 'USD',
+            groups: [
+              {
+                label: 'Currency',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' },
+                  { label: 'GBP', value: 'gbp' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+export const SelectVariantInteractive: Story = {
+  render: function SelectVariantInteractiveExample() {
+    const [amount, setAmount] = useState('')
+    const [currency] = useState('usd')
+    const [converted, setConverted] = useState<{ value: number; currency: string } | null>(null)
+
+    // Mock exchange rates
+    const rates: Record<string, number> = {
+      usd: 1,
+      eur: 0.92,
+      gbp: 0.79,
+      jpy: 149.5,
+      cny: 7.24,
+      aud: 1.52
+    }
+
+    const handleConvert = () => {
+      const numAmount = parseFloat(amount)
+      if (!isNaN(numAmount) && numAmount > 0) {
+        const convertedValue = numAmount * rates[currency]
+        setConverted({ value: convertedValue, currency })
+      }
+    }
+
+    return (
+      <div className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Currency Converter</h3>
+        <div>
+          <label className="mb-1 block text-sm font-medium">Amount in USD</label>
+          <CompositeInput
+            variant="select"
+            placeholder="0.00"
+            type="number"
+            value={amount}
+            onChange={(e) => {
+              setAmount(e.target.value)
+              setConverted(null)
+            }}
+            selectProps={{
+              placeholder: 'Currency',
+              groups: [
+                {
+                  label: 'Popular',
+                  items: [
+                    { label: 'USD', value: 'usd' },
+                    { label: 'EUR', value: 'eur' },
+                    { label: 'GBP', value: 'gbp' }
+                  ]
+                },
+                {
+                  label: 'Other',
+                  items: [
+                    { label: 'JPY', value: 'jpy' },
+                    { label: 'CNY', value: 'cny' },
+                    { label: 'AUD', value: 'aud' }
+                  ]
+                }
+              ]
+            }}
+          />
+          {amount && !converted && (
+            <p className="mt-1 text-xs text-muted-foreground">Enter amount to convert to selected currency</p>
+          )}
+        </div>
+
+        <button
+          type="button"
+          onClick={handleConvert}
+          disabled={!amount || parseFloat(amount) <= 0}
+          className="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90 disabled:opacity-50">
+          Convert
+        </button>
+
+        {converted && (
+          <div className="rounded-md border bg-muted/20 p-4">
+            <p className="text-sm font-medium">Converted Amount</p>
+            <p className="mt-1 text-2xl font-semibold">
+              {converted.value.toFixed(2)} {converted.currency.toUpperCase()}
+            </p>
+            <p className="mt-1 text-xs text-muted-foreground">
+              {amount} USD = {converted.value.toFixed(2)} {converted.currency.toUpperCase()}
+            </p>
+          </div>
+        )}
+      </div>
+    )
+  }
+}
+
+// All Variants
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Default Variant</p>
+        <CompositeInput variant="default" placeholder="Default variant..." />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Email Variant</p>
+        <CompositeInput variant="email" type="email" placeholder="example.com" prefix="user@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Select Variant</p>
+        <CompositeInput
+          variant="select"
+          placeholder="0.00"
+          type="number"
+          selectProps={{
+            placeholder: 'Currency',
+            groups: [
+              {
+                label: 'Popular',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Button Variant</p>
+        <CompositeInput
+          variant="button"
+          placeholder="Enter text..."
+          buttonProps={{
+            label: 'Submit',
+            onClick: () => {}
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Password (Default Variant)</p>
+        <CompositeInput variant="default" type="password" placeholder="Enter password..." />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Password (Button Variant)</p>
+        <CompositeInput
+          variant="button"
+          type="password"
+          placeholder="Enter password..."
+          buttonProps={{
+            label: 'Reset',
+            onClick: () => {}
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// Email Sizes
+export const EmailVariantSizes: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Small (sm)</p>
+        <CompositeInput variant="email" type="email" size="sm" placeholder="example.com" prefix="user@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Medium (md) - Default</p>
+        <CompositeInput variant="email" type="email" size="md" placeholder="example.com" prefix="user@" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Large (lg)</p>
+        <CompositeInput variant="email" type="email" size="lg" placeholder="example.com" prefix="user@" />
+      </div>
+    </div>
+  )
+}
+
+// States
+export const DisabledState: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-4">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled - Default Variant</p>
+        <CompositeInput variant="default" placeholder="Disabled input" disabled defaultValue="Cannot edit" />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled - Email Variant</p>
+        <CompositeInput
+          variant="email"
+          type="email"
+          placeholder="example.com"
+          prefix="user@"
+          disabled
+          defaultValue="example.com"
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled - Select Variant</p>
+        <CompositeInput
+          variant="select"
+          placeholder="0.00"
+          type="number"
+          disabled
+          defaultValue="100.00"
+          selectProps={{
+            placeholder: 'USD',
+            groups: [
+              {
+                label: 'Currency',
+                items: [
+                  { label: 'USD', value: 'usd' },
+                  { label: 'EUR', value: 'eur' }
+                ]
+              }
+            ]
+          }}
+        />
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled - Button Variant</p>
+        <CompositeInput
+          variant="button"
+          placeholder="Disabled input"
+          disabled
+          buttonProps={{
+            label: 'Submit',
+            onClick: () => {}
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+export const DisabledPassword: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-4">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled Password - Default Variant</p>
+        <CompositeInput
+          variant="default"
+          type="password"
+          placeholder="Disabled password"
+          disabled
+          defaultValue="secret123"
+        />
+        <p className="mt-1 text-xs text-muted-foreground">
+          Password field is disabled, eye icon still visible but non-functional
+        </p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled Password - Button Variant</p>
+        <CompositeInput
+          variant="button"
+          type="password"
+          placeholder="Disabled password"
+          disabled
+          defaultValue="mypassword"
+          buttonProps={{
+            label: 'Reset',
+            onClick: () => {}
+          }}
+        />
+        <p className="mt-1 text-xs text-muted-foreground">Both input and button are disabled</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled Password - Empty</p>
+        <CompositeInput variant="default" type="password" placeholder="Enter password..." disabled />
+      </div>
+    </div>
+  )
+}
+
+export const ValidationError: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Invalid Email - Default Variant</p>
+        <CompositeInput
+          variant="default"
+          type="email"
+          placeholder="email@example.com"
+          defaultValue="invalid-email"
+          aria-invalid
+        />
+        <p className="mt-1 text-xs text-destructive">Please enter a valid email address</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Invalid Email - Email Variant</p>
+        <CompositeInput
+          variant="email"
+          type="email"
+          placeholder="example.com"
+          prefix="user@"
+          defaultValue="invalid domain"
+          aria-invalid
+        />
+        <p className="mt-1 text-xs text-destructive">Email format is incorrect</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Invalid Email - Button Variant</p>
+        <CompositeInput
+          variant="button"
+          type="email"
+          placeholder="Enter your email..."
+          defaultValue="bad@email"
+          aria-invalid
+          buttonProps={{
+            label: 'Subscribe',
+            onClick: () => {}
+          }}
+        />
+        <p className="mt-1 text-xs text-destructive">Please provide a complete email address</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Invalid Password - Too Short</p>
+        <CompositeInput
+          variant="default"
+          type="password"
+          placeholder="Enter password..."
+          defaultValue="123"
+          aria-invalid
+        />
+        <p className="mt-1 text-xs text-destructive">Password must be at least 8 characters long</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Required Field - Empty</p>
+        <CompositeInput variant="default" placeholder="This field is required" aria-invalid />
+        <p className="mt-1 text-xs text-destructive">This field is required</p>
+      </div>
+    </div>
+  )
+}
+
+export const EmailVariantInteractive: Story = {
+  render: function EmailVariantInteractiveExample() {
+    const [domain, setDomain] = useState('')
+    const [error, setError] = useState('')
+
+    const validateDomain = (value: string) => {
+      if (!value) {
+        setError('Domain is required')
+        return false
+      }
+      // Simple domain validation
+      const domainRegex = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?\.[a-zA-Z]{2,}$/
+      if (!domainRegex.test(value)) {
+        setError('Please enter a valid domain (e.g., example.com)')
+        return false
+      }
+      setError('')
+      return true
+    }
+
+    const handleSubmit = () => {
+      if (validateDomain(domain)) {
+        alert(`Email created: user@${domain}`)
+      }
+    }
+
+    return (
+      <div className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Create Email Address</h3>
+        <div>
+          <label className="mb-1 block text-sm font-medium">Email Domain</label>
+          <CompositeInput
+            variant="email"
+            type="email"
+            placeholder="example.com"
+            prefix="user@"
+            value={domain}
+            onChange={(e) => {
+              setDomain(e.target.value)
+              if (error) validateDomain(e.target.value)
+            }}
+            onBlur={() => validateDomain(domain)}
+            aria-invalid={!!error}
+          />
+          {error ? (
+            <p className="mt-1 text-xs text-destructive">{error}</p>
+          ) : domain ? (
+            <p className="mt-1 text-xs text-green-600">✓ Valid email: user@{domain}</p>
+          ) : (
+            <p className="mt-1 text-xs text-muted-foreground">Enter the domain for your email address</p>
+          )}
+        </div>
+        <button
+          type="button"
+          onClick={handleSubmit}
+          disabled={!domain || !!error}
+          className="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90 disabled:opacity-50">
+          Create Email
+        </button>
+      </div>
+    )
+  }
+}
+
+export const ValidationForm: Story = {
+  render: function ValidationFormExample() {
+    const [formData, setFormData] = useState({
+      email: '',
+      password: '',
+      confirmPassword: ''
+    })
+    const [errors, setErrors] = useState<Record<string, string>>({})
+    const [touched, setTouched] = useState<Record<string, boolean>>({})
+
+    const validateEmail = (email: string) => {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+      if (!email) return 'Email is required'
+      if (!emailRegex.test(email)) return 'Please enter a valid email address'
+      return ''
+    }
+
+    const validatePassword = (password: string) => {
+      if (!password) return 'Password is required'
+      if (password.length < 8) return 'Password must be at least 8 characters'
+      return ''
+    }
+
+    const validateConfirmPassword = (confirmPassword: string, password: string) => {
+      if (!confirmPassword) return 'Please confirm your password'
+      if (confirmPassword !== password) return 'Passwords do not match'
+      return ''
+    }
+
+    const handleBlur = (field: string) => {
+      setTouched({ ...touched, [field]: true })
+
+      const newErrors = { ...errors }
+      if (field === 'email') {
+        const error = validateEmail(formData.email)
+        if (error) newErrors.email = error
+        else delete newErrors.email
+      } else if (field === 'password') {
+        const error = validatePassword(formData.password)
+        if (error) newErrors.password = error
+        else delete newErrors.password
+      } else if (field === 'confirmPassword') {
+        const error = validateConfirmPassword(formData.confirmPassword, formData.password)
+        if (error) newErrors.confirmPassword = error
+        else delete newErrors.confirmPassword
+      }
+      setErrors(newErrors)
+    }
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+
+      const newErrors: Record<string, string> = {}
+      const emailError = validateEmail(formData.email)
+      const passwordError = validatePassword(formData.password)
+      const confirmError = validateConfirmPassword(formData.confirmPassword, formData.password)
+
+      if (emailError) newErrors.email = emailError
+      if (passwordError) newErrors.password = passwordError
+      if (confirmError) newErrors.confirmPassword = confirmError
+
+      setErrors(newErrors)
+      setTouched({ email: true, password: true, confirmPassword: true })
+
+      if (Object.keys(newErrors).length === 0) {
+        alert('Form submitted successfully!')
+      }
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Sign Up with Validation</h3>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Email <span className="text-destructive">*</span>
+          </label>
+          <CompositeInput
+            variant="email"
+            type="email"
+            placeholder="email@example.com"
+            value={formData.email}
+            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+            onBlur={() => handleBlur('email')}
+            aria-invalid={touched.email && !!errors.email}
+          />
+          {touched.email && errors.email && <p className="mt-1 text-xs text-destructive">{errors.email}</p>}
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Password <span className="text-destructive">*</span>
+          </label>
+          <CompositeInput
+            variant="default"
+            type="password"
+            placeholder="Enter password..."
+            value={formData.password}
+            onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+            onBlur={() => handleBlur('password')}
+            aria-invalid={touched.password && !!errors.password}
+          />
+          {touched.password && errors.password && <p className="mt-1 text-xs text-destructive">{errors.password}</p>}
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Confirm Password <span className="text-destructive">*</span>
+          </label>
+          <CompositeInput
+            variant="default"
+            type="password"
+            placeholder="Confirm password..."
+            value={formData.confirmPassword}
+            onChange={(e) => setFormData({ ...formData, confirmPassword: e.target.value })}
+            onBlur={() => handleBlur('confirmPassword')}
+            aria-invalid={touched.confirmPassword && !!errors.confirmPassword}
+          />
+          {touched.confirmPassword && errors.confirmPassword && (
+            <p className="mt-1 text-xs text-destructive">{errors.confirmPassword}</p>
+          )}
+        </div>
+
+        <button
+          type="submit"
+          className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+          Create Account
+        </button>
+
+        <p className="text-xs text-muted-foreground">* Fields marked with an asterisk are required</p>
+      </form>
+    )
+  }
+}
+
+// Interactive Examples
+export const SubscribeNewsletter: Story = {
+  render: function SubscribeNewsletterExample() {
+    const [email, setEmail] = useState('')
+    const [submitted, setSubmitted] = useState(false)
+
+    const handleSubscribe = () => {
+      if (email) {
+        setSubmitted(true)
+        setTimeout(() => {
+          setSubmitted(false)
+          setEmail('')
+        }, 3000)
+      }
+    }
+
+    return (
+      <div className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Subscribe to Newsletter</h3>
+        <CompositeInput
+          variant="button"
+          type="email"
+          placeholder="Enter your email..."
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          buttonProps={{
+            label: submitted ? 'Subscribed!' : 'Subscribe',
+            onClick: handleSubscribe
+          }}
+          disabled={submitted}
+        />
+        {submitted && <p className="text-sm text-green-600">Thanks for subscribing!</p>}
+      </div>
+    )
+  }
+}
+
+export const SearchWithAction: Story = {
+  render: function SearchWithActionExample() {
+    const [query, setQuery] = useState('')
+    const [results, setResults] = useState<string[]>([])
+
+    const handleSearch = () => {
+      if (query) {
+        const mockResults = [`Result 1 for "${query}"`, `Result 2 for "${query}"`, `Result 3 for "${query}"`]
+        setResults(mockResults)
+      }
+    }
+
+    return (
+      <div className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Search</h3>
+        <CompositeInput
+          variant="button"
+          placeholder="Enter search query..."
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={(e) => e.key === 'Enter' && handleSearch()}
+          buttonProps={{
+            label: <Send className="size-4" />,
+            onClick: handleSearch
+          }}
+        />
+        {results.length > 0 && (
+          <div className="rounded-md border p-3">
+            <p className="mb-2 text-sm font-medium">Results ({results.length})</p>
+            <ul className="space-y-1">
+              {results.map((result, i) => (
+                <li key={i} className="text-sm text-muted-foreground">
+                  {result}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    )
+  }
+}
+
+export const PasswordReset: Story = {
+  render: function PasswordResetExample() {
+    const [password, setPassword] = useState('')
+    const [showStrength, setShowStrength] = useState(false)
+
+    const getPasswordStrength = (pwd: string) => {
+      if (pwd.length === 0) return { label: '', color: '' }
+      if (pwd.length < 6) return { label: 'Weak', color: 'text-red-600' }
+      if (pwd.length < 10) return { label: 'Medium', color: 'text-yellow-600' }
+      return { label: 'Strong', color: 'text-green-600' }
+    }
+
+    const strength = getPasswordStrength(password)
+
+    return (
+      <div className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Set New Password</h3>
+        <div>
+          <CompositeInput
+            variant="button"
+            type="password"
+            placeholder="Enter new password..."
+            value={password}
+            onChange={(e) => {
+              setPassword(e.target.value)
+              setShowStrength(e.target.value.length > 0)
+            }}
+            buttonProps={{
+              label: 'Update',
+              onClick: () => alert('Password updated!')
+            }}
+          />
+          {showStrength && strength.label && (
+            <p className={`mt-2 text-sm ${strength.color}`}>Password strength: {strength.label}</p>
+          )}
+        </div>
+        <p className="text-xs text-muted-foreground">Password must be at least 8 characters long</p>
+      </div>
+    )
+  }
+}
+
+// Form Examples
+export const LoginForm: Story = {
+  render: function LoginFormExample() {
+    const [formData, setFormData] = useState({
+      email: '',
+      password: ''
+    })
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+      alert(`Logging in with: ${formData.email}`)
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Login</h3>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Email</label>
+          <CompositeInput
+            variant="email"
+            type="email"
+            placeholder="email@example.com"
+            value={formData.email}
+            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Password</label>
+          <CompositeInput
+            variant="default"
+            type="password"
+            placeholder="Enter password..."
+            value={formData.password}
+            onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+          />
+        </div>
+
+        <button
+          type="submit"
+          className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+          Sign In
+        </button>
+      </form>
+    )
+  }
+}
+
+export const SignupForm: Story = {
+  render: function SignupFormExample() {
+    const [formData, setFormData] = useState({
+      name: '',
+      email: '',
+      password: '',
+      confirmPassword: ''
+    })
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+      if (formData.password !== formData.confirmPassword) {
+        alert('Passwords do not match!')
+        return
+      }
+      alert(`Account created for: ${formData.email}`)
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Create Account</h3>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Full Name</label>
+          <CompositeInput
+            variant="default"
+            placeholder="John Doe"
+            value={formData.name}
+            onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Email</label>
+          <CompositeInput
+            variant="email"
+            type="email"
+            placeholder="email@example.com"
+            value={formData.email}
+            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Password</label>
+          <CompositeInput
+            variant="default"
+            type="password"
+            placeholder="Enter password..."
+            value={formData.password}
+            onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Confirm Password</label>
+          <CompositeInput
+            variant="default"
+            type="password"
+            placeholder="Confirm password..."
+            value={formData.confirmPassword}
+            onChange={(e) => setFormData({ ...formData, confirmPassword: e.target.value })}
+          />
+        </div>
+
+        <button
+          type="submit"
+          className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+          Sign Up
+        </button>
+      </form>
+    )
+  }
+}
+
+export const QuickActions: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <h3 className="mb-3 text-base font-semibold">Quick Actions</h3>
+        <div className="space-y-3">
+          <CompositeInput
+            variant="button"
+            placeholder="Send a message..."
+            buttonProps={{
+              label: 'Send',
+              onClick: () => alert('Message sent!')
+            }}
+          />
+
+          <CompositeInput
+            variant="button"
+            type="email"
+            placeholder="Invite user by email..."
+            buttonProps={{
+              label: 'Invite',
+              onClick: () => alert('Invitation sent!')
+            }}
+          />
+
+          <CompositeInput
+            variant="button"
+            placeholder="Add new item..."
+            buttonProps={{
+              label: '+ Add',
+              onClick: () => alert('Item added!')
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// Real World Examples
+export const RealWorldExamples: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      {/* Newsletter Subscription */}
+      <div className="w-96">
+        <h3 className="mb-2 text-base font-semibold">Stay Updated</h3>
+        <p className="mb-3 text-sm text-muted-foreground">Get the latest news and updates delivered to your inbox.</p>
+        <CompositeInput
+          variant="button"
+          type="email"
+          placeholder="Enter your email..."
+          buttonProps={{
+            label: 'Subscribe',
+            onClick: () => {}
+          }}
+        />
+      </div>
+
+      {/* Support Ticket */}
+      <div className="w-96">
+        <h3 className="mb-2 text-base font-semibold">Submit Ticket</h3>
+        <p className="mb-3 text-sm text-muted-foreground">Describe your issue and we'll get back to you.</p>
+        <CompositeInput
+          variant="button"
+          placeholder="Describe your issue..."
+          buttonProps={{
+            label: 'Submit',
+            onClick: () => {}
+          }}
+        />
+      </div>
+
+      {/* Promo Code */}
+      <div className="w-96">
+        <h3 className="mb-2 text-base font-semibold">Have a Promo Code?</h3>
+        <CompositeInput
+          variant="button"
+          placeholder="Enter promo code..."
+          buttonProps={{
+            label: 'Apply',
+            onClick: () => {}
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// Contact Form
+export const ContactForm: Story = {
+  render: function ContactFormExample() {
+    const [formData, setFormData] = useState({
+      name: '',
+      email: '',
+      subject: ''
+    })
+    const [submitted, setSubmitted] = useState(false)
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+      setSubmitted(true)
+      setTimeout(() => {
+        setSubmitted(false)
+        setFormData({ name: '', email: '', subject: '' })
+      }, 3000)
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Contact Us</h3>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Name</label>
+          <CompositeInput
+            variant="default"
+            placeholder="Your name..."
+            value={formData.name}
+            onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Email</label>
+          <CompositeInput
+            variant="email"
+            type="email"
+            placeholder="your@email.com"
+            value={formData.email}
+            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+          />
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">Subject</label>
+          <CompositeInput
+            variant="button"
+            placeholder="How can we help?"
+            value={formData.subject}
+            onChange={(e) => setFormData({ ...formData, subject: e.target.value })}
+            buttonProps={{
+              label: submitted ? '✓ Sent' : 'Send',
+              onClick: (e) => handleSubmit(e as unknown as React.FormEvent)
+            }}
+          />
+        </div>
+
+        {submitted && <p className="text-sm text-green-600">Message sent successfully!</p>}
+      </form>
+    )
+  }
+}
+
+// Accessibility
+export const Accessibility: Story = {
+  render: () => (
+    <div className="w-96 space-y-6">
+      <div>
+        <h3 className="mb-4 text-base font-semibold">Keyboard Navigation</h3>
+        <p className="mb-4 text-sm text-muted-foreground">
+          Use Tab to navigate between inputs and buttons. Press Enter in the input to trigger the button action.
+        </p>
+        <div className="space-y-3">
+          <CompositeInput
+            variant="button"
+            placeholder="First input..."
+            buttonProps={{
+              label: 'Action 1',
+              onClick: () => {}
+            }}
+          />
+          <CompositeInput
+            variant="button"
+            placeholder="Second input..."
+            buttonProps={{
+              label: 'Action 2',
+              onClick: () => {}
+            }}
+          />
+        </div>
+      </div>
+
+      <div>
+        <h3 className="mb-4 text-base font-semibold">Password Accessibility</h3>
+        <p className="mb-4 text-sm text-muted-foreground">
+          The password toggle button has proper ARIA attributes for screen readers.
+        </p>
+        <CompositeInput variant="default" type="password" placeholder="Enter password..." />
+      </div>
+    </div>
+  )
+}
+
+// All Size and Variant Combinations
+export const AllCombinations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      {/* Small Size */}
+      <div className="w-[500px]">
+        <h3 className="mb-4 text-base font-semibold">Small Size (sm)</h3>
+        <div className="space-y-3">
+          <CompositeInput variant="default" size="sm" placeholder="Default variant" />
+          <CompositeInput variant="email" type="email" size="sm" placeholder="example.com" prefix="user@" />
+          <CompositeInput
+            variant="select"
+            size="sm"
+            placeholder="0.00"
+            type="number"
+            selectProps={{
+              placeholder: 'USD',
+              groups: [
+                {
+                  label: 'Currency',
+                  items: [
+                    { label: 'USD', value: 'usd' },
+                    { label: 'EUR', value: 'eur' }
+                  ]
+                }
+              ]
+            }}
+          />
+          <CompositeInput
+            variant="button"
+            size="sm"
+            placeholder="Button variant"
+            buttonProps={{
+              label: 'Go',
+              onClick: () => {}
+            }}
+          />
+          <CompositeInput variant="default" type="password" size="sm" placeholder="Password" />
+        </div>
+      </div>
+
+      {/* Medium Size */}
+      <div className="w-[500px]">
+        <h3 className="mb-4 text-base font-semibold">Medium Size (md) - Default</h3>
+        <div className="space-y-3">
+          <CompositeInput variant="default" size="md" placeholder="Default variant" />
+          <CompositeInput variant="email" type="email" size="md" placeholder="example.com" prefix="user@" />
+          <CompositeInput
+            variant="select"
+            size="md"
+            placeholder="0.00"
+            type="number"
+            selectProps={{
+              placeholder: 'USD',
+              groups: [
+                {
+                  label: 'Currency',
+                  items: [
+                    { label: 'USD', value: 'usd' },
+                    { label: 'EUR', value: 'eur' }
+                  ]
+                }
+              ]
+            }}
+          />
+          <CompositeInput
+            variant="button"
+            size="md"
+            placeholder="Button variant"
+            buttonProps={{
+              label: 'Submit',
+              onClick: () => {}
+            }}
+          />
+          <CompositeInput variant="default" type="password" size="md" placeholder="Password" />
+        </div>
+      </div>
+
+      {/* Large Size */}
+      <div className="w-[500px]">
+        <h3 className="mb-4 text-base font-semibold">Large Size (lg)</h3>
+        <div className="space-y-3">
+          <CompositeInput variant="default" size="lg" placeholder="Default variant" />
+          <CompositeInput variant="email" type="email" size="lg" placeholder="example.com" prefix="user@" />
+          <CompositeInput
+            variant="select"
+            size="lg"
+            placeholder="0.00"
+            type="number"
+            selectProps={{
+              placeholder: 'USD',
+              groups: [
+                {
+                  label: 'Currency',
+                  items: [
+                    { label: 'USD', value: 'usd' },
+                    { label: 'EUR', value: 'eur' }
+                  ]
+                }
+              ]
+            }}
+          />
+          <CompositeInput
+            variant="button"
+            size="lg"
+            placeholder="Button variant"
+            buttonProps={{
+              label: 'Send',
+              onClick: () => {}
+            }}
+          />
+          <CompositeInput variant="default" type="password" size="lg" placeholder="Password" />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/ui/stories/components/primitives/Input.stories.tsx b/packages/ui/stories/components/primitives/Input.stories.tsx
new file mode 100644
index 000000000..98605486b
--- /dev/null
+++ b/packages/ui/stories/components/primitives/Input.stories.tsx
@@ -0,0 +1,629 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Mail, Search, User } from 'lucide-react'
+import { useState } from 'react'
+
+import { Input } from '../../../src/components/primitives/input'
+
+const meta: Meta<typeof Input> = {
+  title: 'Components/Primitives/Input',
+  component: Input,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A basic text input component with focus states, error handling, and file upload support. Built with accessibility in mind and styled with Tailwind CSS.'
+      }
+    }
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    type: {
+      control: { type: 'select' },
+      options: ['text', 'email', 'password', 'number', 'search', 'tel', 'url', 'date', 'time', 'file'],
+      description: 'The type of the input'
+    },
+    placeholder: {
+      control: { type: 'text' },
+      description: 'Placeholder text'
+    },
+    disabled: {
+      control: { type: 'boolean' },
+      description: 'Whether the input is disabled'
+    },
+    className: {
+      control: { type: 'text' },
+      description: 'Additional CSS classes'
+    }
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// Default
+export const Default: Story = {
+  args: {
+    placeholder: 'Enter text...'
+  }
+}
+
+// With Value
+export const WithValue: Story = {
+  args: {
+    defaultValue: 'Hello World',
+    placeholder: 'Enter text...'
+  }
+}
+
+// Types
+export const TextType: Story = {
+  args: {
+    type: 'text',
+    placeholder: 'Enter text...'
+  }
+}
+
+export const EmailType: Story = {
+  args: {
+    type: 'email',
+    placeholder: 'Enter email...'
+  }
+}
+
+export const PasswordType: Story = {
+  args: {
+    type: 'password',
+    placeholder: 'Enter password...'
+  }
+}
+
+export const NumberType: Story = {
+  args: {
+    type: 'number',
+    placeholder: 'Enter number...'
+  }
+}
+
+export const SearchType: Story = {
+  args: {
+    type: 'search',
+    placeholder: 'Search...'
+  }
+}
+
+// All Input Types
+export const AllInputTypes: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <div>
+        <label className="mb-1 block text-sm font-medium">Text</label>
+        <Input type="text" placeholder="Enter text..." />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Email</label>
+        <Input type="email" placeholder="email@example.com" />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Password</label>
+        <Input type="password" placeholder="Enter password..." />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Number</label>
+        <Input type="number" placeholder="0" />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Search</label>
+        <Input type="search" placeholder="Search..." />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">URL</label>
+        <Input type="url" placeholder="https://example.com" />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Tel</label>
+        <Input type="tel" placeholder="+1 (555) 000-0000" />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Date</label>
+        <Input type="date" />
+      </div>
+      <div>
+        <label className="mb-1 block text-sm font-medium">Time</label>
+        <Input type="time" />
+      </div>
+    </div>
+  )
+}
+
+// States
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    placeholder: 'Disabled input',
+    defaultValue: 'Cannot edit this'
+  }
+}
+
+export const ReadOnly: Story = {
+  args: {
+    readOnly: true,
+    defaultValue: 'Read-only value'
+  }
+}
+
+export const ErrorState: Story = {
+  render: () => (
+    <div className="w-80">
+      <Input placeholder="Invalid input..." aria-invalid />
+    </div>
+  )
+}
+
+// All States
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Normal</p>
+        <Input placeholder="Normal input" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">With Value</p>
+        <Input defaultValue="Input with value" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Disabled</p>
+        <Input disabled placeholder="Disabled input" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Read-only</p>
+        <Input readOnly defaultValue="Read-only value" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Error State</p>
+        <Input placeholder="Invalid input" aria-invalid />
+      </div>
+    </div>
+  )
+}
+
+// Controlled
+export const Controlled: Story = {
+  render: function ControlledExample() {
+    const [value, setValue] = useState('')
+
+    return (
+      <div className="flex w-80 flex-col gap-4">
+        <Input placeholder="Type something..." value={value} onChange={(e) => setValue(e.target.value)} />
+        <div className="text-sm text-muted-foreground">
+          Current value: <span className="font-mono">{value || '(empty)'}</span>
+        </div>
+        <div className="text-sm text-muted-foreground">Length: {value.length}</div>
+      </div>
+    )
+  }
+}
+
+// With Labels
+export const WithLabels: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <div>
+        <label htmlFor="username" className="mb-1 block text-sm font-medium">
+          Username
+        </label>
+        <Input id="username" placeholder="Enter username..." />
+      </div>
+      <div>
+        <label htmlFor="email" className="mb-1 block text-sm font-medium">
+          Email
+        </label>
+        <Input id="email" type="email" placeholder="email@example.com" />
+      </div>
+      <div>
+        <label htmlFor="password" className="mb-1 block text-sm font-medium">
+          Password
+        </label>
+        <Input id="password" type="password" placeholder="Enter password..." />
+      </div>
+    </div>
+  )
+}
+
+// With Helper Text
+export const WithHelperText: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <div>
+        <label htmlFor="email-helper" className="mb-1 block text-sm font-medium">
+          Email
+        </label>
+        <Input id="email-helper" type="email" placeholder="email@example.com" />
+        <p className="mt-1 text-xs text-muted-foreground">We'll never share your email with anyone else.</p>
+      </div>
+      <div>
+        <label htmlFor="password-helper" className="mb-1 block text-sm font-medium">
+          Password
+        </label>
+        <Input id="password-helper" type="password" placeholder="Enter password..." />
+        <p className="mt-1 text-xs text-muted-foreground">Must be at least 8 characters long.</p>
+      </div>
+    </div>
+  )
+}
+
+// With Error Message
+export const WithErrorMessage: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <div>
+        <label htmlFor="email-error" className="mb-1 block text-sm font-medium">
+          Email
+        </label>
+        <Input id="email-error" type="email" placeholder="email@example.com" aria-invalid />
+        <p className="mt-1 text-xs text-destructive">Please enter a valid email address.</p>
+      </div>
+      <div>
+        <label htmlFor="password-error" className="mb-1 block text-sm font-medium">
+          Password
+        </label>
+        <Input id="password-error" type="password" placeholder="Enter password..." aria-invalid />
+        <p className="mt-1 text-xs text-destructive">Password must be at least 8 characters.</p>
+      </div>
+    </div>
+  )
+}
+
+// Validation States
+export const ValidationStates: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm font-medium">Valid Input</p>
+        <Input type="email" placeholder="email@example.com" defaultValue="user@example.com" />
+        <p className="mt-1 text-xs text-green-600">✓ Email is valid</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Invalid Email Format</p>
+        <Input type="email" placeholder="email@example.com" defaultValue="invalid-email" aria-invalid />
+        <p className="mt-1 text-xs text-destructive">✗ Please enter a valid email address</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Required Field Empty</p>
+        <Input placeholder="Required field" aria-invalid aria-required />
+        <p className="mt-1 text-xs text-destructive">✗ This field is required</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Password Too Short</p>
+        <Input type="password" placeholder="Enter password..." defaultValue="123" aria-invalid />
+        <p className="mt-1 text-xs text-destructive">✗ Password must be at least 8 characters</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Number Out of Range</p>
+        <Input type="number" placeholder="1-100" defaultValue="150" min="1" max="100" aria-invalid />
+        <p className="mt-1 text-xs text-destructive">✗ Value must be between 1 and 100</p>
+      </div>
+    </div>
+  )
+}
+
+// Real-time Validation
+export const RealTimeValidation: Story = {
+  render: function RealTimeValidationExample() {
+    const [email, setEmail] = useState('')
+    const [emailError, setEmailError] = useState('')
+
+    const validateEmail = (value: string) => {
+      if (!value) {
+        setEmailError('Email is required')
+        return false
+      }
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+      if (!emailRegex.test(value)) {
+        setEmailError('Please enter a valid email address')
+        return false
+      }
+      setEmailError('')
+      return true
+    }
+
+    return (
+      <div className="w-80 space-y-4">
+        <h3 className="text-base font-semibold">Real-time Email Validation</h3>
+        <div>
+          <label htmlFor="realtime-email" className="mb-1 block text-sm font-medium">
+            Email Address
+          </label>
+          <Input
+            id="realtime-email"
+            type="email"
+            placeholder="email@example.com"
+            value={email}
+            onChange={(e) => {
+              setEmail(e.target.value)
+              validateEmail(e.target.value)
+            }}
+            aria-invalid={!!emailError}
+          />
+          {emailError ? (
+            <p className="mt-1 text-xs text-destructive">{emailError}</p>
+          ) : email ? (
+            <p className="mt-1 text-xs text-green-600">✓ Email is valid</p>
+          ) : (
+            <p className="mt-1 text-xs text-muted-foreground">Enter your email address</p>
+          )}
+        </div>
+      </div>
+    )
+  }
+}
+
+// File Input
+export const FileInput: Story = {
+  render: () => (
+    <div className="w-80">
+      <label htmlFor="file" className="mb-1 block text-sm font-medium">
+        Upload File
+      </label>
+      <Input id="file" type="file" />
+    </div>
+  )
+}
+
+// Multiple Files
+export const MultipleFiles: Story = {
+  render: () => (
+    <div className="w-80">
+      <label htmlFor="files" className="mb-1 block text-sm font-medium">
+        Upload Multiple Files
+      </label>
+      <Input id="files" type="file" multiple />
+    </div>
+  )
+}
+
+// Form Example
+export const FormExample: Story = {
+  render: function FormExample() {
+    const [formData, setFormData] = useState({
+      username: '',
+      email: '',
+      password: '',
+      confirmPassword: ''
+    })
+    const [errors, setErrors] = useState<Record<string, string>>({})
+    const [submitted, setSubmitted] = useState(false)
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+      const newErrors: Record<string, string> = {}
+
+      if (!formData.username) newErrors.username = 'Username is required'
+      if (!formData.email) newErrors.email = 'Email is required'
+      if (!formData.password) newErrors.password = 'Password is required'
+      if (formData.password !== formData.confirmPassword) newErrors.confirmPassword = 'Passwords do not match'
+
+      setErrors(newErrors)
+
+      if (Object.keys(newErrors).length === 0) {
+        setSubmitted(true)
+        setTimeout(() => setSubmitted(false), 3000)
+      }
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-80 space-y-4">
+        <h3 className="text-base font-semibold">Sign Up Form</h3>
+
+        <div>
+          <label htmlFor="form-username" className="mb-1 block text-sm font-medium">
+            Username
+          </label>
+          <Input
+            id="form-username"
+            placeholder="Enter username..."
+            value={formData.username}
+            onChange={(e) => setFormData({ ...formData, username: e.target.value })}
+            aria-invalid={!!errors.username}
+          />
+          {errors.username && <p className="mt-1 text-xs text-destructive">{errors.username}</p>}
+        </div>
+
+        <div>
+          <label htmlFor="form-email" className="mb-1 block text-sm font-medium">
+            Email
+          </label>
+          <Input
+            id="form-email"
+            type="email"
+            placeholder="email@example.com"
+            value={formData.email}
+            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+            aria-invalid={!!errors.email}
+          />
+          {errors.email && <p className="mt-1 text-xs text-destructive">{errors.email}</p>}
+        </div>
+
+        <div>
+          <label htmlFor="form-password" className="mb-1 block text-sm font-medium">
+            Password
+          </label>
+          <Input
+            id="form-password"
+            type="password"
+            placeholder="Enter password..."
+            value={formData.password}
+            onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+            aria-invalid={!!errors.password}
+          />
+          {errors.password && <p className="mt-1 text-xs text-destructive">{errors.password}</p>}
+        </div>
+
+        <div>
+          <label htmlFor="form-confirm" className="mb-1 block text-sm font-medium">
+            Confirm Password
+          </label>
+          <Input
+            id="form-confirm"
+            type="password"
+            placeholder="Confirm password..."
+            value={formData.confirmPassword}
+            onChange={(e) => setFormData({ ...formData, confirmPassword: e.target.value })}
+            aria-invalid={!!errors.confirmPassword}
+          />
+          {errors.confirmPassword && <p className="mt-1 text-xs text-destructive">{errors.confirmPassword}</p>}
+        </div>
+
+        <button
+          type="submit"
+          className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+          Sign Up
+        </button>
+
+        {submitted && <p className="text-center text-sm text-green-600">Form submitted successfully!</p>}
+      </form>
+    )
+  }
+}
+
+// Search Example
+export const SearchExample: Story = {
+  render: function SearchExample() {
+    const [query, setQuery] = useState('')
+    const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape']
+    const filtered = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()))
+
+    return (
+      <div className="w-80 space-y-4">
+        <div>
+          <label htmlFor="search" className="mb-1 flex items-center gap-2 text-sm font-medium">
+            <Search className="size-4" />
+            Search Fruits
+          </label>
+          <Input
+            id="search"
+            type="search"
+            placeholder="Type to search..."
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+          />
+        </div>
+
+        <div className="rounded-md border p-3">
+          <p className="mb-2 text-sm font-medium">Results ({filtered.length})</p>
+          {filtered.length > 0 ? (
+            <ul className="space-y-1">
+              {filtered.map((item) => (
+                <li key={item} className="text-sm text-muted-foreground">
+                  {item}
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="text-sm text-muted-foreground">No results found</p>
+          )}
+        </div>
+      </div>
+    )
+  }
+}
+
+// Real World Examples
+export const RealWorldExamples: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      {/* Login Form */}
+      <div className="w-80">
+        <h3 className="mb-4 text-base font-semibold">Login Form</h3>
+        <div className="space-y-3">
+          <div>
+            <label htmlFor="login-email" className="mb-1 flex items-center gap-2 text-sm font-medium">
+              <Mail className="size-4" />
+              Email
+            </label>
+            <Input id="login-email" type="email" placeholder="email@example.com" />
+          </div>
+          <div>
+            <label htmlFor="login-password" className="mb-1 block text-sm font-medium">
+              Password
+            </label>
+            <Input id="login-password" type="password" placeholder="Enter password..." />
+          </div>
+          <button
+            type="button"
+            className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+            Sign In
+          </button>
+        </div>
+      </div>
+
+      {/* Profile Form */}
+      <div className="w-80">
+        <h3 className="mb-4 text-base font-semibold">Profile Information</h3>
+        <div className="space-y-3">
+          <div>
+            <label htmlFor="profile-name" className="mb-1 flex items-center gap-2 text-sm font-medium">
+              <User className="size-4" />
+              Full Name
+            </label>
+            <Input id="profile-name" placeholder="John Doe" />
+          </div>
+          <div>
+            <label htmlFor="profile-email" className="mb-1 flex items-center gap-2 text-sm font-medium">
+              <Mail className="size-4" />
+              Email
+            </label>
+            <Input id="profile-email" type="email" placeholder="john@example.com" />
+          </div>
+          <div>
+            <label htmlFor="profile-phone" className="mb-1 block text-sm font-medium">
+              Phone
+            </label>
+            <Input id="profile-phone" type="tel" placeholder="+1 (555) 000-0000" />
+          </div>
+          <button
+            type="button"
+            className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+            Save Changes
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// Accessibility
+export const Accessibility: Story = {
+  render: () => (
+    <div className="w-80 space-y-6">
+      <div>
+        <h3 className="mb-4 text-base font-semibold">Keyboard Navigation</h3>
+        <p className="mb-4 text-sm text-muted-foreground">Use Tab to navigate between inputs.</p>
+        <div className="space-y-3">
+          <Input placeholder="First input" />
+          <Input placeholder="Second input" />
+          <Input placeholder="Third input" />
+        </div>
+      </div>
+
+      <div>
+        <h3 className="mb-4 text-base font-semibold">ARIA Labels</h3>
+        <p className="mb-4 text-sm text-muted-foreground">
+          Inputs include proper ARIA attributes for screen reader support.
+        </p>
+        <div className="space-y-3">
+          <Input placeholder="Input with aria-label" aria-label="Username input" />
+          <Input placeholder="Invalid input" aria-invalid aria-describedby="error-message" />
+          <p id="error-message" className="text-xs text-destructive">
+            This input has an error
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/ui/stories/components/primitives/InputGroup.stories.tsx b/packages/ui/stories/components/primitives/InputGroup.stories.tsx
new file mode 100644
index 000000000..b57049377
--- /dev/null
+++ b/packages/ui/stories/components/primitives/InputGroup.stories.tsx
@@ -0,0 +1,1083 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  AtSign,
+  Calendar,
+  ChevronDown,
+  Copy,
+  DollarSign,
+  Eye,
+  EyeOff,
+  Link,
+  Lock,
+  Mail,
+  Percent,
+  Search,
+  Send,
+  Settings,
+  User,
+  X
+} from 'lucide-react'
+import { useState } from 'react'
+
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+  InputGroupTextarea
+} from '../../../src/components/primitives/input-group'
+
+const meta: Meta<typeof InputGroup> = {
+  title: 'Components/Primitives/InputGroup',
+  component: InputGroup,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A flexible input group component that allows you to add icons, buttons, and text addons to inputs. Supports inline and block alignment for various layout needs.'
+      }
+    }
+  },
+  tags: ['autodocs']
+}
+
+// Shared arg types for stories that use InputGroupButton
+const buttonSizeArgType = {
+  control: 'select' as const,
+  options: ['xs', 'sm', 'icon-xs', 'icon-sm'],
+  description: 'Size of the button',
+  table: {
+    category: 'InputGroupButton'
+  }
+}
+
+const buttonVariantArgType = {
+  control: 'select' as const,
+  options: ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'],
+  description: 'Variant of the button',
+  table: {
+    category: 'InputGroupButton'
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// Playground - Interactive example with all controls
+interface PlaygroundArgs {
+  placeholder: string
+  disabled: boolean
+  showStartAddon: boolean
+  showEndAddon: boolean
+  startAddonAlign: 'inline-start' | 'block-start'
+  endAddonAlign: 'inline-end' | 'block-end'
+  startAddonType: 'icon' | 'text' | 'button'
+  endAddonType: 'icon' | 'text' | 'button'
+  buttonSize: 'xs' | 'sm' | 'icon-xs' | 'icon-sm'
+  buttonVariant: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+  inputType: 'text' | 'email' | 'password' | 'number' | 'search'
+}
+
+export const Playground: StoryObj<PlaygroundArgs> = {
+  argTypes: {
+    placeholder: {
+      control: 'text',
+      description: 'Input placeholder text',
+      table: { category: 'Input' }
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the input group is disabled',
+      table: { category: 'InputGroup' }
+    },
+    showStartAddon: {
+      control: 'boolean',
+      description: 'Show start addon',
+      table: { category: 'Addons' }
+    },
+    showEndAddon: {
+      control: 'boolean',
+      description: 'Show end addon',
+      table: { category: 'Addons' }
+    },
+    startAddonAlign: {
+      control: 'select',
+      options: ['inline-start', 'block-start'],
+      description: 'Start addon alignment',
+      table: { category: 'Addons' },
+      if: { arg: 'showStartAddon' }
+    },
+    endAddonAlign: {
+      control: 'select',
+      options: ['inline-end', 'block-end'],
+      description: 'End addon alignment',
+      table: { category: 'Addons' },
+      if: { arg: 'showEndAddon' }
+    },
+    startAddonType: {
+      control: 'select',
+      options: ['icon', 'text', 'button'],
+      description: 'Start addon content type',
+      table: { category: 'Addons' },
+      if: { arg: 'showStartAddon' }
+    },
+    endAddonType: {
+      control: 'select',
+      options: ['icon', 'text', 'button'],
+      description: 'End addon content type',
+      table: { category: 'Addons' },
+      if: { arg: 'showEndAddon' }
+    },
+    buttonSize: {
+      ...buttonSizeArgType,
+      description: 'Button size (when addon type is button)'
+    },
+    buttonVariant: {
+      ...buttonVariantArgType,
+      description: 'Button variant (when addon type is button)'
+    },
+    inputType: {
+      control: 'select',
+      options: ['text', 'email', 'password', 'number', 'search'],
+      description: 'Input type',
+      table: { category: 'Input' }
+    }
+  },
+  args: {
+    placeholder: 'Enter text...',
+    disabled: false,
+    showStartAddon: true,
+    showEndAddon: true,
+    startAddonAlign: 'inline-start',
+    endAddonAlign: 'inline-end',
+    startAddonType: 'icon',
+    endAddonType: 'button',
+    buttonSize: 'xs',
+    buttonVariant: 'ghost',
+    inputType: 'text'
+  },
+  render: (args) => {
+    const renderAddonContent = (type: string, isStart: boolean) => {
+      if (type === 'icon') {
+        return <InputGroupText>{isStart ? <User /> : <Search />}</InputGroupText>
+      }
+      if (type === 'text') {
+        return <InputGroupText>{isStart ? 'Label' : 'Suffix'}</InputGroupText>
+      }
+      return (
+        <InputGroupButton size={args.buttonSize} variant={args.buttonVariant}>
+          {isStart ? <Settings /> : <Send />}
+        </InputGroupButton>
+      )
+    }
+
+    return (
+      <div className="w-80">
+        <InputGroup data-disabled={args.disabled || undefined}>
+          {args.showStartAddon && (
+            <InputGroupAddon align={args.startAddonAlign}>
+              {renderAddonContent(args.startAddonType, true)}
+            </InputGroupAddon>
+          )}
+          <InputGroupInput type={args.inputType} placeholder={args.placeholder} disabled={args.disabled} />
+          {args.showEndAddon && (
+            <InputGroupAddon align={args.endAddonAlign}>{renderAddonContent(args.endAddonType, false)}</InputGroupAddon>
+          )}
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+// Basic Examples
+export const Default: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="Enter text..." />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithIconStart: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>
+            <User />
+          </InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Username" />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithIconEnd: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="Search..." />
+        <InputGroupAddon align="inline-end">
+          <InputGroupText>
+            <Search />
+          </InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithIconBoth: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>
+            <Mail />
+          </InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput type="email" placeholder="email@example.com" />
+        <InputGroupAddon align="inline-end">
+          <InputGroupText>
+            <AtSign />
+          </InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+// With Text Addons
+export const WithTextStart: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>https://</InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="example.com" />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithTextEnd: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="username" />
+        <InputGroupAddon align="inline-end">
+          <InputGroupText>@example.com</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithTextBoth: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>
+            <DollarSign />
+          </InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput type="number" placeholder="0.00" />
+        <InputGroupAddon align="inline-end">
+          <InputGroupText>USD</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+// With Buttons
+export const WithButtonEnd: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="Enter email..." />
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton>
+            <Send />
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithButtonStart: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupButton>
+            <Search />
+          </InputGroupButton>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Search..." />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const WithMultipleButtons: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="Enter text..." />
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton size="icon-xs">
+            <Copy />
+          </InputGroupButton>
+          <InputGroupButton size="icon-xs">
+            <X />
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+// Block Alignment
+export const BlockAlignmentStart: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="block-start">
+          <InputGroupText>Description</InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Enter description..." />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const BlockAlignmentEnd: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupInput placeholder="Enter message..." />
+        <InputGroupAddon align="block-end">
+          <InputGroupText>Character count: 0/500</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+export const BlockAlignmentBoth: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="block-start">
+          <InputGroupText>Message</InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Type your message..." />
+        <InputGroupAddon align="block-end">
+          <InputGroupText>Max 200 characters</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+// With Textarea
+export const WithTextarea: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupTextarea placeholder="Enter your comment..." rows={4} />
+        <InputGroupAddon align="block-end">
+          <InputGroupText>0/500 characters</InputGroupText>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+export const TextareaWithButtons: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="block-start">
+          <InputGroupText>Comment</InputGroupText>
+        </InputGroupAddon>
+        <InputGroupTextarea placeholder="Write your comment..." rows={4} />
+        <InputGroupAddon align="block-end">
+          <InputGroupButton size="sm">Cancel</InputGroupButton>
+          <InputGroupButton size="sm">Submit</InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+// Button Sizes
+export const ButtonSizes: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-4">
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Extra Small (xs)</p>
+        <InputGroup>
+          <InputGroupInput placeholder="Search..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="xs">Search</InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Small (sm)</p>
+        <InputGroup>
+          <InputGroupInput placeholder="Search..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="sm">Search</InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Icon Extra Small (icon-xs)</p>
+        <InputGroup>
+          <InputGroupInput placeholder="Search..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="icon-xs">
+              <Search />
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm text-muted-foreground">Icon Small (icon-sm)</p>
+        <InputGroup>
+          <InputGroupInput placeholder="Search..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="icon-sm">
+              <Search />
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    </div>
+  )
+}
+
+// States
+export const DisabledState: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup data-disabled="true">
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>
+            <User />
+          </InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Disabled input" disabled />
+      </InputGroup>
+    </div>
+  )
+}
+
+export const ErrorState: Story = {
+  render: () => (
+    <div className="w-80">
+      <InputGroup>
+        <InputGroupAddon align="inline-start">
+          <InputGroupText>
+            <Mail />
+          </InputGroupText>
+        </InputGroupAddon>
+        <InputGroupInput type="email" placeholder="email@example.com" aria-invalid />
+      </InputGroup>
+      <p className="mt-1 text-xs text-destructive">Please enter a valid email address.</p>
+    </div>
+  )
+}
+
+export const ValidationStates: Story = {
+  render: () => (
+    <div className="flex w-96 flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm font-medium">Valid Input</p>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Mail />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="email" placeholder="email@example.com" defaultValue="user@example.com" />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText className="text-green-600">✓</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <p className="mt-1 text-xs text-green-600">Email is valid</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Invalid Email</p>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Mail />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="email" placeholder="email@example.com" defaultValue="invalid-email" aria-invalid />
+        </InputGroup>
+        <p className="mt-1 text-xs text-destructive">Please enter a valid email address</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Required Field Empty</p>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <User />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput placeholder="Username (required)" aria-invalid aria-required />
+        </InputGroup>
+        <p className="mt-1 text-xs text-destructive">This field is required</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Password Too Short</p>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Lock />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="password" placeholder="Enter password..." defaultValue="123" aria-invalid />
+        </InputGroup>
+        <p className="mt-1 text-xs text-destructive">Password must be at least 8 characters</p>
+      </div>
+
+      <div>
+        <p className="mb-2 text-sm font-medium">Invalid Amount</p>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <DollarSign />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="number" placeholder="0.00" defaultValue="-10" aria-invalid />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>USD</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+        <p className="mt-1 text-xs text-destructive">Amount must be positive</p>
+      </div>
+    </div>
+  )
+}
+
+export const ValidationForm: Story = {
+  render: function ValidationFormExample() {
+    const [formData, setFormData] = useState({
+      email: '',
+      password: '',
+      amount: ''
+    })
+    const [errors, setErrors] = useState<Record<string, string>>({})
+    const [touched, setTouched] = useState<Record<string, boolean>>({})
+
+    const validateEmail = (email: string) => {
+      if (!email) return 'Email is required'
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+      if (!emailRegex.test(email)) return 'Please enter a valid email address'
+      return ''
+    }
+
+    const validatePassword = (password: string) => {
+      if (!password) return 'Password is required'
+      if (password.length < 8) return 'Password must be at least 8 characters'
+      return ''
+    }
+
+    const validateAmount = (amount: string) => {
+      if (!amount) return 'Amount is required'
+      const num = parseFloat(amount)
+      if (isNaN(num)) return 'Please enter a valid number'
+      if (num <= 0) return 'Amount must be positive'
+      return ''
+    }
+
+    const handleBlur = (field: string) => {
+      setTouched({ ...touched, [field]: true })
+      const newErrors = { ...errors }
+
+      if (field === 'email') {
+        const error = validateEmail(formData.email)
+        if (error) newErrors.email = error
+        else delete newErrors.email
+      } else if (field === 'password') {
+        const error = validatePassword(formData.password)
+        if (error) newErrors.password = error
+        else delete newErrors.password
+      } else if (field === 'amount') {
+        const error = validateAmount(formData.amount)
+        if (error) newErrors.amount = error
+        else delete newErrors.amount
+      }
+
+      setErrors(newErrors)
+    }
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault()
+
+      const newErrors: Record<string, string> = {}
+      const emailError = validateEmail(formData.email)
+      const passwordError = validatePassword(formData.password)
+      const amountError = validateAmount(formData.amount)
+
+      if (emailError) newErrors.email = emailError
+      if (passwordError) newErrors.password = passwordError
+      if (amountError) newErrors.amount = amountError
+
+      setErrors(newErrors)
+      setTouched({ email: true, password: true, amount: true })
+
+      if (Object.keys(newErrors).length === 0) {
+        alert('Form submitted successfully!')
+      }
+    }
+
+    return (
+      <form onSubmit={handleSubmit} className="w-96 space-y-4">
+        <h3 className="text-base font-semibold">Payment Form with Validation</h3>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Email <span className="text-destructive">*</span>
+          </label>
+          <InputGroup>
+            <InputGroupAddon align="inline-start">
+              <InputGroupText>
+                <Mail />
+              </InputGroupText>
+            </InputGroupAddon>
+            <InputGroupInput
+              type="email"
+              placeholder="email@example.com"
+              value={formData.email}
+              onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+              onBlur={() => handleBlur('email')}
+              aria-invalid={touched.email && !!errors.email}
+            />
+          </InputGroup>
+          {touched.email && errors.email && <p className="mt-1 text-xs text-destructive">{errors.email}</p>}
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Password <span className="text-destructive">*</span>
+          </label>
+          <InputGroup>
+            <InputGroupAddon align="inline-start">
+              <InputGroupText>
+                <Lock />
+              </InputGroupText>
+            </InputGroupAddon>
+            <InputGroupInput
+              type="password"
+              placeholder="Enter password..."
+              value={formData.password}
+              onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+              onBlur={() => handleBlur('password')}
+              aria-invalid={touched.password && !!errors.password}
+            />
+          </InputGroup>
+          {touched.password && errors.password && <p className="mt-1 text-xs text-destructive">{errors.password}</p>}
+        </div>
+
+        <div>
+          <label className="mb-1 block text-sm font-medium">
+            Amount <span className="text-destructive">*</span>
+          </label>
+          <InputGroup>
+            <InputGroupAddon align="inline-start">
+              <InputGroupText>
+                <DollarSign />
+              </InputGroupText>
+            </InputGroupAddon>
+            <InputGroupInput
+              type="number"
+              placeholder="0.00"
+              value={formData.amount}
+              onChange={(e) => setFormData({ ...formData, amount: e.target.value })}
+              onBlur={() => handleBlur('amount')}
+              aria-invalid={touched.amount && !!errors.amount}
+            />
+            <InputGroupAddon align="inline-end">
+              <InputGroupText>USD</InputGroupText>
+            </InputGroupAddon>
+          </InputGroup>
+          {touched.amount && errors.amount && <p className="mt-1 text-xs text-destructive">{errors.amount}</p>}
+        </div>
+
+        <button
+          type="submit"
+          className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+          Submit Payment
+        </button>
+
+        <p className="text-xs text-muted-foreground">* Required fields</p>
+      </form>
+    )
+  }
+}
+
+// Interactive Examples
+export const PasswordToggle: Story = {
+  render: function PasswordToggleExample() {
+    const [showPassword, setShowPassword] = useState(false)
+
+    return (
+      <div className="w-80">
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Lock />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type={showPassword ? 'text' : 'password'} placeholder="Enter password..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="icon-xs" onClick={() => setShowPassword(!showPassword)}>
+              {showPassword ? <EyeOff /> : <Eye />}
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+export const SearchWithClear: Story = {
+  render: function SearchWithClearExample() {
+    const [value, setValue] = useState('')
+
+    return (
+      <div className="w-80">
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Search />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput placeholder="Search..." value={value} onChange={(e) => setValue(e.target.value)} />
+          {value && (
+            <InputGroupAddon align="inline-end">
+              <InputGroupButton size="icon-xs" onClick={() => setValue('')}>
+                <X />
+              </InputGroupButton>
+            </InputGroupAddon>
+          )}
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+export const CopyToClipboard: Story = {
+  render: function CopyToClipboardExample() {
+    const [copied, setCopied] = useState(false)
+    const value = 'https://example.com/share/abc123'
+
+    const handleCopy = () => {
+      navigator.clipboard.writeText(value)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    }
+
+    return (
+      <div className="w-96">
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Link />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput value={value} readOnly />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="xs" onClick={handleCopy}>
+              {copied ? '✓ Copied' : <Copy />}
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+export const CharacterCounter: Story = {
+  render: function CharacterCounterExample() {
+    const [value, setValue] = useState('')
+    const maxLength = 100
+
+    return (
+      <div className="w-80">
+        <InputGroup>
+          <InputGroupInput
+            placeholder="Enter message..."
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+            maxLength={maxLength}
+          />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>
+              {value.length}/{maxLength}
+            </InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+// Real World Examples
+export const LoginForm: Story = {
+  render: () => (
+    <div className="w-80 space-y-4">
+      <h3 className="text-base font-semibold">Login</h3>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Email</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Mail />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="email" placeholder="email@example.com" />
+        </InputGroup>
+      </div>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Password</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Lock />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="password" placeholder="Enter password..." />
+        </InputGroup>
+      </div>
+
+      <button
+        type="button"
+        className="w-full rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
+        Sign In
+      </button>
+    </div>
+  )
+}
+
+export const PriceInput: Story = {
+  render: () => (
+    <div className="w-80 space-y-4">
+      <div>
+        <label className="mb-1 block text-sm font-medium">Amount (USD)</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <DollarSign />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="number" placeholder="0.00" step="0.01" />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>USD</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Discount (%)</label>
+        <InputGroup>
+          <InputGroupInput type="number" placeholder="0" min="0" max="100" />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>
+              <Percent />
+            </InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    </div>
+  )
+}
+
+export const UrlBuilder: Story = {
+  render: function UrlBuilderExample() {
+    const [protocol, setProtocol] = useState('https://')
+
+    return (
+      <div className="w-96 space-y-4">
+        <div>
+          <label className="mb-1 block text-sm font-medium">Website URL</label>
+          <InputGroup>
+            <InputGroupAddon align="inline-start">
+              <InputGroupButton size="xs" onClick={() => setProtocol(protocol === 'https://' ? 'http://' : 'https://')}>
+                {protocol}
+                <ChevronDown />
+              </InputGroupButton>
+            </InputGroupAddon>
+            <InputGroupInput placeholder="example.com" />
+          </InputGroup>
+        </div>
+      </div>
+    )
+  }
+}
+
+export const SearchBar: Story = {
+  render: function SearchBarExample() {
+    const [query, setQuery] = useState('')
+    const [loading, setLoading] = useState(false)
+
+    const handleSearch = () => {
+      setLoading(true)
+      setTimeout(() => {
+        setLoading(false)
+      }, 1000)
+    }
+
+    return (
+      <div className="w-96">
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Search />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput
+            placeholder="Search..."
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={(e) => e.key === 'Enter' && handleSearch()}
+          />
+          {query && (
+            <InputGroupAddon align="inline-end">
+              <InputGroupButton size="icon-xs" onClick={() => setQuery('')}>
+                <X />
+              </InputGroupButton>
+              <InputGroupButton size="sm" onClick={handleSearch} disabled={loading}>
+                {loading ? 'Searching...' : 'Search'}
+              </InputGroupButton>
+            </InputGroupAddon>
+          )}
+        </InputGroup>
+      </div>
+    )
+  }
+}
+
+export const DateTimeInput: Story = {
+  render: () => (
+    <div className="w-80 space-y-4">
+      <div>
+        <label className="mb-1 block text-sm font-medium">Event Date</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Calendar />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="date" />
+        </InputGroup>
+      </div>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Event Time</label>
+        <InputGroup>
+          <InputGroupInput type="time" />
+        </InputGroup>
+      </div>
+    </div>
+  )
+}
+
+export const SettingsPanel: Story = {
+  render: () => (
+    <div className="w-96 space-y-4">
+      <h3 className="text-base font-semibold">API Configuration</h3>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">API Key</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>
+              <Settings />
+            </InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput type="password" placeholder="sk-..." />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="icon-xs">
+              <Copy />
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+        <p className="mt-1 text-xs text-muted-foreground">Keep your API key secret and secure.</p>
+      </div>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Base URL</label>
+        <InputGroup>
+          <InputGroupAddon align="inline-start">
+            <InputGroupText>https://</InputGroupText>
+          </InputGroupAddon>
+          <InputGroupInput placeholder="api.example.com" />
+        </InputGroup>
+      </div>
+
+      <div>
+        <label className="mb-1 block text-sm font-medium">Timeout (seconds)</label>
+        <InputGroup>
+          <InputGroupInput type="number" placeholder="30" min="1" />
+          <InputGroupAddon align="inline-end">
+            <InputGroupText>seconds</InputGroupText>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    </div>
+  )
+}
+
+export const CommentBox: Story = {
+  render: function CommentBoxExample() {
+    const [comment, setComment] = useState('')
+    const maxLength = 500
+
+    return (
+      <div className="w-96">
+        <h3 className="mb-3 text-base font-semibold">Leave a Comment</h3>
+        <InputGroup>
+          <InputGroupTextarea
+            placeholder="Write your comment..."
+            rows={4}
+            value={comment}
+            onChange={(e) => setComment(e.target.value)}
+            maxLength={maxLength}
+          />
+          <InputGroupAddon align="block-end">
+            <InputGroupText>
+              {comment.length}/{maxLength}
+            </InputGroupText>
+            <InputGroupButton size="sm" disabled={!comment.trim()}>
+              Post Comment
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+    )
+  }
+}