diff --git a/README.md b/README.md
index 9a6ff83..177724b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,102 @@
 # tailscale-ui-components
 
 Tailscale UI component library used by tailscale/corp/adminhttp/panel and tailscale/tailscale/client/web React projects. Not maintained for external use.
+
+## Development Setup
+
+### Prerequisites
+
+Ensure you have the following tools installed:
+
+- **Node.js 22.14.0** (use `nvm` to manage Node versions)
+  ```bash
+  nvm use 22.14.0
+  ```
+- **Yarn 1.22.19** (package manager)
+  ```bash
+  npm install -g yarn@1.22.19
+  ```
+
+### Getting Started
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/tailscale/tailscale-ui-components.git
+   cd tailscale-ui-components
+   ```
+
+2. **Install dependencies**
+   ```bash
+   yarn install
+   ```
+
+3. **Start Storybook for development**
+   ```bash
+   yarn storybook
+   ```
+   This will start Storybook on `http://localhost:6006` (or the next available port)
+
+### Available Scripts
+
+- `yarn storybook` - Start Storybook development server
+- `yarn build-storybook` - Build Storybook for production
+- `yarn build` - Build the component library for production
+- `yarn test` - Run tests with Vitest
+
+### Environment Compatibility
+
+This project has been tested and works with:
+- **Node.js 22.14.0** (recommended for team consistency)
+
+### Package Management
+
+This project uses **Yarn v1** as the package manager. The `yarn.lock` file should be committed, and `package-lock.json` should be ignored/removed if present.
+
+### Component Development
+
+Components are located in `src/components/` and follow these patterns:
+
+1. **OSS-ready structure** with proper style mappings
+2. **Comprehensive TypeScript types** and exported constants
+3. **Accessibility features** with proper ARIA attributes
+4. **Storybook stories** for documentation and testing
+
+Example component structure:
+```
+src/components/button/
+├── button.tsx           # Main component
+├── button.stories.tsx   # Storybook stories
+└── index.ts            # Barrel export
+```
+
+### Styling Guidelines
+
+- Use the `.button`, `.input`, and other base CSS classes from `src/tailwind.css`
+- Follow the established design tokens and color system
+- Ensure components have rounded corners and consistent spacing
+- Support both light and dark themes
+
+### Contributing
+
+When adding or modifying components:
+
+1. Ensure TypeScript strict mode compliance
+2. Add comprehensive Storybook stories
+3. Include proper accessibility attributes
+4. Follow the established component patterns
+5. Export components from `src/index.ts`
+
+### Troubleshooting
+
+**Node.js Version Issues:**
+If you encounter build errors, ensure you're using Node.js 22.14.0:
+```bash
+node --version  # Should output v22.14.0
+```
+
+**Package Manager Issues:**
+If dependencies fail to install, try:
+```bash
+rm -rf node_modules yarn.lock
+yarn install
+```
\ No newline at end of file
diff --git a/src/components/button/button.tsx b/src/components/button/button.tsx
index 1d5a165..53b7d8f 100644
--- a/src/components/button/button.tsx
+++ b/src/components/button/button.tsx
@@ -1,21 +1,97 @@
 import cx from "classnames"
 import React, { HTMLProps } from "react"
-import { LoadingDots } from "src/components/loading-dots/loading-dots"
+import { LoadingDots } from "../loading-dots/loading-dots"
+
+export type ButtonVariant = "filled" | "minimal"
+export type ButtonIntent = "base" | "primary" | "warning" | "danger" | "black"
+export type ButtonSize = "xsmall" | "input" | "small" | "medium" | "large"
+
+export const BUTTON_VARIANTS = [
+  "filled",
+  "minimal",
+] as const satisfies readonly ButtonVariant[]
+
+export const BUTTON_INTENTS = [
+  "base",
+  "primary",
+  "warning",
+  "danger",
+  "black",
+] as const satisfies readonly ButtonIntent[]
+
+export const BUTTON_SIZES = [
+  "xsmall",
+  "input",
+  "small",
+  "medium",
+  "large",
+] as const satisfies readonly ButtonSize[]
+
+const BUTTON_FILLED_INTENT_STYLES: Record<ButtonIntent, string> = {
+  base: "bg-gray-0 dark:bg-gray-700 border-gray-300 dark:border-gray-600 enabled:hover:bg-gray-100 dark:enabled:hover:bg-gray-600 enabled:hover:border-gray-300 dark:enabled:hover:border-gray-500 enabled:focus-visible:bg-gray-100 dark:enabled:focus-visible:bg-gray-600 enabled:focus-visible:border-gray-300 dark:enabled:focus-visible:border-gray-500 enabled:hover:text-gray-900 dark:enabled:hover:text-gray-300 disabled:border-gray-200 dark:disabled:border-gray-600/30 disabled:text-text-disabled",
+  primary:
+    "bg-blue-500 dark:bg-blue-600 border-blue-500 dark:border-blue-600 text-white enabled:hover:bg-blue-600 dark:enabled:hover:bg-blue-500 enabled:hover:border-blue-600 dark:enabled:hover:border-blue-500 enabled:focus-visible:bg-blue-600 dark:enabled:focus-visible:bg-blue-500 disabled:text-blue-50 disabled:bg-blue-300 dark:disabled:bg-blue-600 disabled:border-blue-300 dark:disabled:border-blue-600 dark:disabled:opacity-40",
+  danger:
+    "bg-red-400 dark:bg-red-500 border-red-400 dark:border-red-500 text-white enabled:hover:bg-red-500 dark:enabled:hover:bg-red-400 enabled:hover:border-red-500 dark:enabled:hover:border-red-400 enabled:focus-visible:outline-outline-focus-danger enabled:focus-visible:bg-red-500 dark:enabled:focus-visible:bg-red-400 disabled:text-red-50 disabled:bg-red-300 dark:disabled:bg-red-500 disabled:border-red-300 dark:disabled:border-red-500 dark:disabled:opacity-40",
+  warning:
+    "bg-yellow-300 dark:bg-yellow-400 border-yellow-300 dark:border-yellow-400 text-white enabled:hover:bg-yellow-400 dark:enabled:hover:bg-yellow-300 enabled:hover:border-yellow-400 dark:enabled:hover:border-yellow-300 enabled:focus-visible:outline-outline-focus-warning enabled:focus-visible:bg-yellow-400 dark:enabled:focus-visible:bg-yellow-300 disabled:text-yellow-50 disabled:bg-yellow-200 dark:disabled:bg-yellow-400 disabled:border-yellow-200 dark:disabled:border-yellow-400 dark:disabled:opacity-40",
+  black:
+    "bg-gray-800 border-gray-800 text-white enabled:hover:bg-gray-900 dark:enabled:hover:bg-gray-700 enabled:hover:border-gray-900 dark:enabled:hover:border-gray-700 disabled:opacity-75",
+}
+
+const BUTTON_FILLED_ACTIVE_STYLES: Record<ButtonIntent, string> = {
+  base: "enabled:bg-gray-200 dark:enabled:bg-gray-800 enabled:border-gray-300 dark:enabled:border-gray-700",
+  primary: "",
+  danger: "",
+  warning: "",
+  black: "",
+}
+
+const BUTTON_MINIMAL_INTENT_STYLES: Record<ButtonIntent, string> = {
+  base: "text-text-base enabled:focus-visible:bg-gray-100 dark:enabled:focus-visible:bg-gray-500/10 enabled:hover:bg-gray-100 dark:enabled:hover:bg-gray-500/10",
+  black:
+    "text-text-base enabled:focus-visible:bg-gray-100 dark:enabled:focus-visible:bg-gray-500/10 enabled:hover:bg-gray-100 dark:enabled:hover:bg-gray-500/10",
+  primary:
+    "text-text-primary enabled:focus-visible:bg-blue-0 dark:enabled:focus-visible:bg-blue-400/10 enabled:hover:bg-blue-0 dark:enabled:hover:bg-blue-400/10",
+  danger:
+    "text-text-danger enabled:focus-visible:bg-red-0 dark:enabled:focus-visible:bg-red-400/10 enabled:focus-visible:outline-outline-focus-danger enabled:hover:bg-red-0 dark:enabled:hover:bg-red-400/10",
+  warning:
+    "text-text-warning enabled:focus-visible:bg-orange-0 dark:enabled:focus-visible:bg-orange-400/10 enabled:focus-visible:outline-outline-focus-warning enabled:hover:bg-orange-0 dark:enabled:hover:bg-orange-400/10",
+}
+
+const BUTTON_MINIMAL_ACTIVE_STYLES: Record<ButtonIntent, string> = {
+  base: "enabled:bg-gray-200 border-gray-300",
+  black: "enabled:bg-gray-200 border-gray-300",
+  primary: "",
+  danger: "",
+  warning: "",
+}
+
+const BUTTON_SIZE_STYLES: Record<
+  ButtonSize,
+  { height: string; padding?: string; text?: string }
+> = {
+  xsmall: { height: "h-6" },
+  input: { height: "h-9" },
+  small: { height: "h-8 text-sm", padding: "px-2.5 text-sm" },
+  medium: { height: "h-9", padding: "px-3" },
+  large: { height: "h-10", padding: "px-4" },
+}
 
 export type ButtonProps = {
   type?: "button" | "submit" | "reset"
-  sizeVariant?: "xsmall" | "input" | "small" | "medium" | "large"
+  sizeVariant?: ButtonSize
   /**
    * variant is the visual style of the button. By default, this is a filled
    * button. For a less prominent button, use minimal.
    */
-  variant?: Variant
+  variant?: ButtonVariant
   /**
    * intent describes the semantic meaning of the button's action. For
    * dangerous or destructive actions, use danger. For actions that should
    * be the primary focus, use primary.
    */
-  intent?: Intent
+  intent?: ButtonIntent
 
   active?: boolean
   /**
@@ -43,114 +119,142 @@ export type ButtonProps = {
   textAlign?: "center" | "left"
 } & HTMLProps<HTMLButtonElement>
 
-export type Variant = "filled" | "minimal"
-export type Intent = "base" | "primary" | "warning" | "danger" | "black"
-
 /**
  * Button is a clickable element that can be used to trigger actions. It can
  * have different visual styles and semantic meanings.
+ *
+ * @example
+ * ```tsx
+ * // Basic button
+ * <Button variant="filled" intent="base">Click me</Button>
+ *
+ * // Primary button
+ * <Button variant="filled" intent="primary">Save</Button>
+ *
+ * // Button with icon
+ * <Button prefixIcon={<Plus size={16} />}>Add Item</Button>
+ *
+ * // Minimal button
+ * <Button variant="minimal" intent="danger">Delete</Button>
+ *
+ * // Loading button
+ * <Button loading>Submitting...</Button>
+ * ```
  */
-export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
-  const {
-    className,
-    variant = "filled",
-    intent = "base",
-    sizeVariant = "medium",
-    disabled,
-    children,
-    loading,
-    active,
-    iconOnly,
-    prefixIcon,
-    suffixIcon,
-    textAlign,
-    ...rest
-  } = props
-
-  const hasIcon = Boolean(prefixIcon || suffixIcon)
-
-  return (
-    <button
-      className={cx(
-        "button",
-        {
-          // base filled
-          "bg-gray-0 dark:bg-gray-700 border-gray-300 dark:border-gray-600 enabled:hover:bg-gray-100 dark:enabled:hover:bg-gray-600 enabled:hover:border-gray-300 dark:enabled:hover:border-gray-500 enabled:focus-visible:bg-gray-100 dark:enabled:focus-visible:bg-gray-600 enabled:focus-visible:border-gray-300 dark:enabled:focus-visible:border-gray-500 enabled:hover:text-gray-900 dark:enabled:hover:text-gray-300 disabled:border-gray-200 dark:disabled:border-gray-600/30 disabled:text-text-disabled":
-            intent === "base" && variant === "filled",
-          "enabled:bg-gray-200 dark:enabled:bg-gray-800 enabled:border-gray-300 dark:enabled:border-gray-700":
-            intent === "base" && variant === "filled" && active,
-          // primary filled
-          "bg-blue-500 dark:bg-blue-600 border-blue-500 dark:border-blue-600 text-white enabled:hover:bg-blue-600 dark:enabled:hover:bg-blue-500 enabled:hover:border-blue-600 dark:enabled:hover:border-blue-500 enabled:focus-visible:bg-blue-600 dark:enabled:focus-visible:bg-blue-500 disabled:text-blue-50 disabled:bg-blue-300 dark:disabled:bg-blue-600 disabled:border-blue-300 dark:disabled:border-blue-600 dark:disabled:opacity-40":
-            intent === "primary" && variant === "filled",
-          // danger filled
-          "bg-red-400 dark:bg-red-500 border-red-400 dark:border-red-500 text-white enabled:hover:bg-red-500 dark:enabled:hover:bg-red-400 enabled:hover:border-red-500 dark:enabled:hover:border-red-400 enabled:focus-visible:outline-outline-focus-danger enabled:focus-visible:bg-red-500 dark:enabled:focus-visible:bg-red-400 disabled:text-red-50 disabled:bg-red-300 dark:disabled:bg-red-500 disabled:border-red-300 dark:disabled:border-red-500 dark:disabled:opacity-40":
-            intent === "danger" && variant === "filled",
-          // warning filled
-          "bg-yellow-300 dark:bg-yellow-400 border-yellow-300 dark:border-yellow-400 text-white enabled:hover:bg-yellow-400 dark:enabled:hover:bg-yellow-300 enabled:hover:border-yellow-400 dark:enabled:hover:border-yellow-300 enabled:focus-visible:outline-outline-focus-warning enabled:focus-visible:bg-yellow-400 dark:enabled:focus-visible:bg-yellow-300 disabled:text-yellow-50 disabled:bg-yellow-200 dark:disabled:bg-yellow-400 disabled:border-yellow-200 dark:disabled:border-yellow-400 dark:disabled:opacity-40":
-            intent === "warning" && variant === "filled",
-          // black filled
-          "bg-gray-800 border-gray-800 text-white enabled:hover:bg-gray-900 dark:enabled:hover:bg-gray-700 enabled:hover:border-gray-900 dark:enabled:hover:border-gray-700 disabled:opacity-75":
-            intent === "black" && variant === "filled",
-
-          // minimal button (base variant, black is also included because its not supported for minimal buttons)
-          "bg-transparent border-transparent shadow-none disabled:border-transparent disabled:text-text-disabled":
-            variant === "minimal",
-          "text-text-base enabled:focus-visible:bg-gray-100 dark:enabled:focus-visible:bg-gray-500/10 enabled:hover:bg-gray-100 dark:enabled:hover:bg-gray-500/10":
-            variant === "minimal" && (intent === "base" || intent === "black"),
-          "enabled:bg-gray-200 border-gray-300":
-            variant === "minimal" &&
-            (intent === "base" || intent === "black") &&
-            active,
-          // primary minimal
-          "text-text-primary enabled:focus-visible:bg-blue-0 dark:enabled:focus-visible:bg-blue-400/10 enabled:hover:bg-blue-0 dark:enabled:hover:bg-blue-400/10":
-            variant === "minimal" && intent === "primary",
-          // danger minimal
-          "text-text-danger enabled:focus-visible:bg-red-0 dark:enabled:focus-visible:bg-red-400/10 enabled:focus-visible:outline-outline-focus-danger enabled:hover:bg-red-0 dark:enabled:hover:bg-red-400/10":
-            variant === "minimal" && intent === "danger",
-          // warning minimal
-          "text-text-warning enabled:focus-visible:bg-orange-0 dark:enabled:focus-visible:bg-orange-400/10 enabled:focus-visible:outline-outline-focus-warning enabled:hover:bg-orange-0 dark:enabled:hover:bg-orange-400/10":
-            variant === "minimal" && intent === "warning",
-
-          // sizeVariants
-          "h-10": sizeVariant === "large",
-          "h-9": sizeVariant === "medium",
-          "h-8 text-sm": sizeVariant === "small",
-          "h-6": sizeVariant === "xsmall",
-          "px-4": sizeVariant === "large" && !iconOnly,
-          "px-3": sizeVariant === "medium" && !iconOnly,
-          "px-2.5 text-sm": sizeVariant === "small" && !iconOnly,
-
-          // iconOnly
-          "aspect-square": iconOnly,
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  (props, ref) => {
+    const {
+      className,
+      variant = "filled",
+      intent = "base",
+      sizeVariant = "medium",
+      disabled,
+      children,
+      loading,
+      active,
+      iconOnly,
+      prefixIcon,
+      suffixIcon,
+      textAlign,
+      type = "button",
+      ...rest
+    } = props
+
+    const hasIcon = Boolean(prefixIcon || suffixIcon)
+    const isDisabled = disabled || loading
+
+    // Get styles based on variant and intent
+    const intentStyles =
+      variant === "filled"
+        ? BUTTON_FILLED_INTENT_STYLES[intent]
+        : BUTTON_MINIMAL_INTENT_STYLES[intent]
+
+    const activeStyles =
+      active && variant === "filled"
+        ? BUTTON_FILLED_ACTIVE_STYLES[intent]
+        : active && variant === "minimal"
+        ? BUTTON_MINIMAL_ACTIVE_STYLES[intent]
+        : ""
+
+    const sizeStyles = BUTTON_SIZE_STYLES[sizeVariant]
+
+    return (
+      <button
+        className={cx(
+          "button",
+          "transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2",
+          // Variant-specific base styles
+          {
+            "bg-transparent border-transparent shadow-none disabled:border-transparent disabled:text-text-disabled":
+              variant === "minimal",
+          },
+
+          // Intent styles
+          intentStyles,
+
+          // Active styles
+          activeStyles,
+
+          // Size styles
+          sizeStyles.height,
+          {
+            [sizeStyles.padding || ""]: !iconOnly && sizeStyles.padding,
+            [sizeStyles.text || ""]: sizeStyles.text,
+          },
+
+          // Icon-only styles
+          {
+            "aspect-square": iconOnly,
+          },
 
           // Button with icons
-          "icon-parent gap-2": hasIcon,
-          "justify-start": hasIcon && !iconOnly,
+          {
+            "gap-2": hasIcon,
+            "justify-start": hasIcon && !iconOnly && textAlign === "left",
+          },
 
           // Active button
-          "button-active relative z-10": active === true,
-        },
-        className
-      )}
-      ref={ref}
-      disabled={disabled || loading}
-      {...rest}
-    >
-      {prefixIcon && <span className="flex-shrink-0">{prefixIcon}</span>}
-      {loading && (
-        <LoadingDots className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-current" />
-      )}
-      {children && (
-        <span
-          className={cx("max-w-full", {
-            "text-transparent": loading === true,
-            "text-left flex-1": textAlign === "left",
-          })}
-        >
-          {children}
-        </span>
-      )}
-      {suffixIcon && <span className="flex-shrink-0">{suffixIcon}</span>}
-    </button>
-  )
-})
\ No newline at end of file
+          {
+            "relative z-10": active === true,
+          },
+
+          className
+        )}
+        ref={ref}
+        type={type}
+        disabled={isDisabled}
+        aria-disabled={isDisabled}
+        aria-busy={loading}
+        {...rest}
+      >
+        {prefixIcon && (
+          <span className="flex-shrink-0" aria-hidden="true">
+            {prefixIcon}
+          </span>
+        )}
+        {loading && (
+          <LoadingDots
+            className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-current"
+            aria-hidden="true"
+          />
+        )}
+        {children && (
+          <span
+            className={cx("max-w-full", {
+              "text-transparent": loading === true,
+              "text-left flex-1": textAlign === "left",
+            })}
+          >
+            {children}
+          </span>
+        )}
+        {suffixIcon && (
+          <span className="flex-shrink-0" aria-hidden="true">
+            {suffixIcon}
+          </span>
+        )}
+        {loading && <span className="sr-only">Loading...</span>}
+      </button>
+    )
+  }
+)
diff --git a/src/components/dialog/dialog.stories.tsx b/src/components/dialog/dialog.stories.tsx
new file mode 100644
index 0000000..4e651e8
--- /dev/null
+++ b/src/components/dialog/dialog.stories.tsx
@@ -0,0 +1,427 @@
+import React, { useState } from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Plus, Settings, Trash2, AlertTriangle } from "lucide-react"
+import Dialog from "./dialog"
+import { Button } from "../button/button"
+
+const meta = {
+  title: "Components/Dialog",
+  component: Dialog,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    title: { control: "text" },
+    size: {
+      options: ["regular", "large", "xlarge", "2xlarge"],
+      control: { type: "select" },
+    },
+    position: {
+      options: [
+        "top-left",
+        "top-center",
+        "top-right",
+        "center-left",
+        "center-center",
+        "center-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right",
+      ],
+      control: { type: "select" },
+    },
+    hideCloseIcon: { control: "boolean" },
+    noPadding: { control: "boolean" },
+    restoreFocus: { control: "boolean" },
+    open: { control: "boolean" },
+    defaultOpen: { control: "boolean" },
+    // Exclude non-serializable props from controls
+    trigger: { table: { disable: true } },
+    children: { table: { disable: true } },
+    onOpenChange: { table: { disable: true } },
+  },
+} satisfies Meta<typeof Dialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: (args) => (
+    <Dialog trigger={<Button>Open Dialog</Button>} {...args}>
+      <div>
+        <p className="mb-4">
+          This is a basic dialog example. You can put any content here.
+        </p>
+        <p className="text-text-muted">
+          Click the X button or press Escape to close.
+        </p>
+      </div>
+    </Dialog>
+  ),
+  args: {
+    title: "Default Dialog",
+    size: "regular",
+    position: "top-center",
+    hideCloseIcon: false,
+    noPadding: false,
+    restoreFocus: true,
+    children: <div>Content</div>,
+  },
+}
+
+export const WithForm: Story = {
+  render: (args) => (
+    <Dialog
+      trigger={
+        <Button prefixIcon={<Settings size={16} />}>Open Settings</Button>
+      }
+      {...args}
+    >
+      <Dialog.Form
+        cancelButton="Cancel"
+        submitButton="Save Changes"
+        onSubmit={(e) => {
+          e.preventDefault()
+          alert("Form submitted!")
+        }}
+      >
+        <div className="space-y-4">
+          <div>
+            <label className="block text-sm font-medium mb-1">Name</label>
+            <input
+              type="text"
+              className="w-full px-3 py-2 border border-gray-300 rounded-md"
+              placeholder="Enter your name"
+            />
+          </div>
+          <div>
+            <label className="block text-sm font-medium mb-1">Email</label>
+            <input
+              type="email"
+              className="w-full px-3 py-2 border border-gray-300 rounded-md"
+              placeholder="Enter your email"
+            />
+          </div>
+        </div>
+      </Dialog.Form>
+    </Dialog>
+  ),
+  args: {
+    title: "User Settings",
+    children: <div>Content</div>,
+  },
+}
+
+export const DestructiveAction: Story = {
+  render: (args) => (
+    <Dialog
+      trigger={
+        <Button intent="danger" prefixIcon={<Trash2 size={16} />}>
+          Delete
+        </Button>
+      }
+      {...args}
+    >
+      <Dialog.Form
+        destructive
+        cancelButton="Cancel"
+        submitButton="Delete"
+        onSubmit={(e) => {
+          e.preventDefault()
+          alert("Item deleted!")
+        }}
+      >
+        <div className="flex items-center gap-3 mb-4">
+          <AlertTriangle className="text-red-500" size={24} />
+          <div>
+            <p className="font-medium">
+              Are you sure you want to delete this item?
+            </p>
+            <p className="text-sm text-text-muted">
+              This action cannot be undone.
+            </p>
+          </div>
+        </div>
+      </Dialog.Form>
+    </Dialog>
+  ),
+  args: {
+    title: "Delete Item",
+    children: <div>Content</div>,
+  },
+}
+
+export const Controlled: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false)
+
+    return (
+      <div className="space-y-4">
+        <Button onClick={() => setIsOpen(true)}>Open Controlled Dialog</Button>
+        <Dialog
+          title="Controlled Dialog"
+          open={isOpen}
+          onOpenChange={setIsOpen}
+        >
+          <div className="space-y-4">
+            <p>This dialog is controlled by React state.</p>
+            <Button onClick={() => setIsOpen(false)} intent="primary">
+              Close Dialog
+            </Button>
+          </div>
+        </Dialog>
+      </div>
+    )
+  },
+  args: {
+    title: "Controlled Dialog",
+    children: <div>Content</div>,
+  },
+}
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex gap-4 flex-wrap">
+      <Dialog
+        title="Regular Size"
+        size="regular"
+        trigger={<Button>Regular</Button>}
+      >
+        <p>This is a regular-sized dialog (max-w-lg).</p>
+      </Dialog>
+
+      <Dialog title="Large Size" size="large" trigger={<Button>Large</Button>}>
+        <p>This is a large-sized dialog (max-w-xl).</p>
+      </Dialog>
+
+      <Dialog
+        title="Extra Large Size"
+        size="xlarge"
+        trigger={<Button>XLarge</Button>}
+      >
+        <p>This is an extra large-sized dialog (max-w-2xl).</p>
+      </Dialog>
+
+      <Dialog
+        title="2X Large Size"
+        size="2xlarge"
+        trigger={<Button>2XLarge</Button>}
+      >
+        <p>This is a 2x large-sized dialog (max-w-3xl).</p>
+      </Dialog>
+    </div>
+  ),
+  args: {
+    title: "Size Examples",
+    children: <div>Content</div>,
+  },
+}
+
+export const Positions: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-4">
+      <Dialog
+        title="Top Left"
+        position="top-left"
+        trigger={<Button variant="minimal">Top Left</Button>}
+      >
+        <p>Dialog positioned at top-left of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Top Center"
+        position="top-center"
+        trigger={<Button variant="minimal">Top Center</Button>}
+      >
+        <p>Dialog positioned at top-center of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Top Right"
+        position="top-right"
+        trigger={<Button variant="minimal">Top Right</Button>}
+      >
+        <p>Dialog positioned at top-right of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Center Left"
+        position="center-left"
+        trigger={<Button variant="minimal">Center Left</Button>}
+      >
+        <p>Dialog positioned at center-left of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Center Center"
+        position="center-center"
+        trigger={<Button variant="minimal">Center Center</Button>}
+      >
+        <p>Dialog positioned at center-center of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Center Right"
+        position="center-right"
+        trigger={<Button variant="minimal">Center Right</Button>}
+      >
+        <p>Dialog positioned at center-right of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Bottom Left"
+        position="bottom-left"
+        trigger={<Button variant="minimal">Bottom Left</Button>}
+      >
+        <p>Dialog positioned at bottom-left of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Bottom Center"
+        position="bottom-center"
+        trigger={<Button variant="minimal">Bottom Center</Button>}
+      >
+        <p>Dialog positioned at bottom-center of viewport.</p>
+      </Dialog>
+
+      <Dialog
+        title="Bottom Right"
+        position="bottom-right"
+        trigger={<Button variant="minimal">Bottom Right</Button>}
+      >
+        <p>Dialog positioned at bottom-right of viewport.</p>
+      </Dialog>
+    </div>
+  ),
+  args: {
+    title: "Position Examples",
+    children: <div>Content</div>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Click any button to see dialogs positioned at different locations in the viewport.",
+      },
+    },
+  },
+}
+
+export const NoPadding: Story = {
+  render: (args) => (
+    <Dialog trigger={<Button>Open Gallery</Button>} {...args}>
+      <div className="bg-gray-100 dark:bg-gray-800 h-64 flex items-center justify-center">
+        <p className="text-gray-600 dark:text-gray-400">
+          This dialog has no padding, perfect for images or full-width content.
+        </p>
+      </div>
+    </Dialog>
+  ),
+  args: {
+    title: "Image Gallery",
+    noPadding: true,
+    size: "large",
+    children: <div>Content</div>,
+  },
+}
+
+export const NoCloseIcon: Story = {
+  render: (args) => (
+    <Dialog trigger={<Button>Open Notice</Button>} {...args}>
+      <Dialog.Form
+        cancelButton={false}
+        submitButton="I Understand"
+        onSubmit={(e) => {
+          e.preventDefault()
+          alert("Acknowledged!")
+        }}
+      >
+        <div className="space-y-4">
+          <p>
+            This dialog has no close icon, forcing users to interact with the
+            form.
+          </p>
+          <p className="text-sm text-text-muted">
+            This is useful for important notices or required acknowledgments.
+          </p>
+        </div>
+      </Dialog.Form>
+    </Dialog>
+  ),
+  args: {
+    title: "Important Notice",
+    hideCloseIcon: true,
+    children: <div>Content</div>,
+  },
+}
+
+export const ComplexForm: Story = {
+  render: (args) => (
+    <Dialog
+      trigger={
+        <Button intent="primary" prefixIcon={<Plus size={16} />}>
+          New Project
+        </Button>
+      }
+      {...args}
+    >
+      <Dialog.Form
+        cancelButton="Cancel"
+        submitButton="Create Project"
+        onSubmit={(e) => {
+          e.preventDefault()
+          alert("Project created!")
+        }}
+      >
+        <div className="space-y-6">
+          <div>
+            <label className="block text-sm font-medium mb-2">
+              Project Name
+            </label>
+            <input
+              type="text"
+              className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-800"
+              placeholder="Enter project name"
+            />
+          </div>
+
+          <div>
+            <label className="block text-sm font-medium mb-2">
+              Description
+            </label>
+            <textarea
+              className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-800"
+              rows={3}
+              placeholder="Enter project description"
+            />
+          </div>
+
+          <div>
+            <label className="block text-sm font-medium mb-2">
+              Project Type
+            </label>
+            <select className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-800">
+              <option>Web Application</option>
+              <option>Mobile App</option>
+              <option>Desktop Application</option>
+              <option>API Service</option>
+            </select>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <input type="checkbox" id="private" />
+            <label htmlFor="private" className="text-sm">
+              Make this project private
+            </label>
+          </div>
+        </div>
+      </Dialog.Form>
+    </Dialog>
+  ),
+  args: {
+    title: "Create New Project",
+    size: "large",
+    children: <div>Content</div>,
+  },
+}
diff --git a/src/components/dialog/dialog.tsx b/src/components/dialog/dialog.tsx
index 1c9616d..cb42488 100644
--- a/src/components/dialog/dialog.tsx
+++ b/src/components/dialog/dialog.tsx
@@ -1,10 +1,41 @@
 import * as DialogPrimitive from "@radix-ui/react-dialog"
 import cx from "classnames"
 import React, { Component, ComponentProps, FormEvent } from "react"
-import { Button, ButtonProps } from "src/components/button/button"
-import { X } from "src/icons"
-import { PortalContainerContext } from "src/components/portal-container-context"
-import { isObject } from "src/utils/util"
+import { Button } from "../button/button"
+import { X } from "../../icons"
+import { PortalContainerContext } from "../portal-container-context"
+import { isObject } from "../../utils/util"
+
+export type DialogSize = "regular" | "large" | "xlarge" | "2xlarge"
+export type DialogPosition =
+  | "top-left"
+  | "top-center"
+  | "top-right"
+  | "center-left"
+  | "center-center"
+  | "center-right"
+  | "bottom-left"
+  | "bottom-center"
+  | "bottom-right"
+
+export const DIALOG_SIZES = [
+  "regular",
+  "large",
+  "xlarge",
+  "2xlarge",
+] as const satisfies readonly DialogSize[]
+
+export const DIALOG_POSITIONS = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "center-left",
+  "center-center",
+  "center-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+] as const satisfies readonly DialogPosition[]
 
 type ButtonProp = boolean | string | Partial<ComponentProps<typeof Button>>
 
@@ -29,6 +60,37 @@ type PointerDownOutsideEvent = CustomEvent<{
   originalEvent: PointerEvent
 }>
 
+/**
+ * Dialog size style mappings
+ */
+const DIALOG_SIZE_STYLES: Record<DialogSize, string> = {
+  regular: "max-w-lg", // TODO(amrfouad): change to "medium" to follow the rest of the design system size tokens.
+  large: "max-w-xl",
+  xlarge: "max-w-2xl",
+  "2xlarge": "max-w-3xl",
+}
+
+/**
+ * Dialog position style mappings
+ */
+const DIALOG_POSITION_STYLES: Record<DialogPosition, string> = {
+  "top-left":
+    "top-0 md:left-0 md:translate-x-0 sm:left-1/2 sm:-translate-x-1/2 mt-8 md:ml-8",
+  "top-center": "top-0 left-1/2 -translate-x-1/2 mt-8",
+  "top-right":
+    "top-0 md:right-0 md:translate-x-0 sm:right-1/2 sm:translate-x-1/2 mt-8 md:mr-8",
+  "center-left":
+    "top-1/2 md:left-0 md:translate-x-0 -translate-y-1/2 sm:left-1/2 sm:-translate-x-1/2 md:ml-8",
+  "center-center": "top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2",
+  "center-right":
+    "top-1/2 md:right-0 md:translate-x-0 -translate-y-1/2 sm:right-1/2 sm:translate-x-1/2 md:mr-8",
+  "bottom-left":
+    "bottom-0 md:left-0 md:translate-x-0 sm:left-1/2 sm:-translate-x-1/2 mb-8 md:ml-8",
+  "bottom-center": "bottom-0 left-1/2 -translate-x-1/2 mb-8",
+  "bottom-right":
+    "bottom-0 md:right-0 md:translate-x-0 sm:right-1/2 sm:translate-x-1/2 mb-8 md:mr-8",
+}
+
 type Props = {
   className?: string
   /**
@@ -73,20 +135,11 @@ type Props = {
   /**
    * size determines how wide the dialog box is.
    */
-  size?: "regular" | "large" | "xlarge" | "2xlarge"
+  size?: DialogSize
   /**
    * position determines where the dialog is positioned relative to the viewport.
    */
-  position?:
-    | "top-left"
-    | "top-center"
-    | "top-right"
-    | "center-left"
-    | "center-center"
-    | "center-right"
-    | "bottom-left"
-    | "bottom-center"
-    | "bottom-right"
+  position?: DialogPosition
 
   /**
    * hideCloseIcon determines whether the close icon is shown in the dialog.
@@ -110,27 +163,42 @@ const dialogWindow = cx(
   "transform-gpu"
 )
 
-const positionClasses = {
-  "top-left":
-    "top-0 md:left-0 md:translate-x-0 sm:left-1/2 sm:-translate-x-1/2 mt-8 md:ml-8",
-  "top-center": "top-0 left-1/2 -translate-x-1/2 mt-8",
-  "top-right":
-    "top-0 md:right-0 md:translate-x-0 sm:right-1/2 sm:translate-x-1/2 mt-8 md:mr-8",
-  "center-left":
-    "top-1/2 md:left-0 md:translate-x-0 -translate-y-1/2 sm:left-1/2 sm:-translate-x-1/2 md:ml-8",
-  "center-center": "top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2",
-  "center-right":
-    "top-1/2 md:right-0 md:translate-x-0 -translate-y-1/2 sm:right-1/2 sm:translate-x-1/2 md:mr-8",
-  "bottom-left":
-    "bottom-0 md:left-0 md:translate-x-0 sm:left-1/2 sm:-translate-x-1/2 mb-8 md:ml-8",
-  "bottom-center": "bottom-0 left-1/2 -translate-x-1/2 mb-8",
-  "bottom-right":
-    "bottom-0 md:right-0 md:translate-x-0 sm:right-1/2 sm:translate-x-1/2 mb-8 md:mr-8",
-}
-
 /**
- * Dialog provides a modal dialog, for prompting a user for input or confirmation
- * before proceeding.
+ * Dialog provides a modal dialog for prompting a user for input or confirmation
+ * before proceeding. Built on top of Radix UI Dialog primitives.
+ *
+ * @example
+ * ```tsx
+ * // Basic dialog with trigger
+ * <Dialog
+ *   title="Confirm Action"
+ *   trigger={<Button>Open Dialog</Button>}
+ * >
+ *   <p>Are you sure you want to continue?</p>
+ * </Dialog>
+ *
+ * // Dialog with form
+ * <Dialog title="User Settings" trigger={<Button>Settings</Button>}>
+ *   <Dialog.Form
+ *     cancelButton="Cancel"
+ *     submitButton="Save"
+ *     onSubmit={handleSubmit}
+ *   >
+ *     <input type="text" placeholder="Enter name" />
+ *   </Dialog.Form>
+ * </Dialog>
+ *
+ * // Controlled dialog
+ * <Dialog
+ *   title="Custom Dialog"
+ *   open={isOpen}
+ *   onOpenChange={setIsOpen}
+ *   size="large"
+ *   position="center-center"
+ * >
+ *   <p>Dialog content here</p>
+ * </Dialog>
+ * ```
  */
 export default function Dialog(props: Props) {
   const {
@@ -167,14 +235,9 @@ export default function Dialog(props: Props) {
                 aria-describedby={undefined}
                 aria-label={title}
                 className={cx(
-                  positionClasses[position],
+                  DIALOG_POSITION_STYLES[position],
                   dialogWindow,
-                  {
-                    "max-w-lg": size === "regular", // TODO(amrfouad): change to "medium" to follow the rest of the design system size tokens.
-                    "max-w-xl": size === "large",
-                    "max-w-2xl": size === "xlarge",
-                    "max-w-3xl": size === "2xlarge",
-                  },
+                  DIALOG_SIZE_STYLES[size],
                   {
                     "p-4 md:p-6": !noPadding,
                   }
@@ -229,6 +292,9 @@ export default function Dialog(props: Props) {
  */
 Dialog.Form = DialogForm
 
+// Named export for consistency
+export { Dialog }
+
 export type FormProps = {
   /**
    * destructive declares whether the submit button should be styled as a danger
diff --git a/src/index.ts b/src/index.ts
index 88d35c1..59c3d92 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,3 +1,4 @@
-export * from './components/badge/badge'
-export * from './components/button/button'
-export * from './components/card/card'
\ No newline at end of file
+export * from "./components/badge/badge"
+export * from "./components/button/button"
+export * from "./components/card/card"
+export * from "./components/dialog/dialog"