diff --git a/docs/app/components/shared/components_list.rb b/docs/app/components/shared/components_list.rb
index a87ac08d5..37e66ea37 100644
--- a/docs/app/components/shared/components_list.rb
+++ b/docs/app/components/shared/components_list.rb
@@ -50,6 +50,7 @@ def components
           {name: "Shortcut Key", path: docs_shortcut_key_path},
           {name: "Sidebar", path: docs_sidebar_path},
           {name: "Skeleton", path: docs_skeleton_path},
+          {name: "Spinner", path: docs_spinner_path},
           {name: "Switch", path: docs_switch_path},
           {name: "Table", path: docs_table_path},
           {name: "Tabs", path: docs_tabs_path},
diff --git a/docs/app/controllers/docs_controller.rb b/docs/app/controllers/docs_controller.rb
index da3b0464e..63864bd48 100644
--- a/docs/app/controllers/docs_controller.rb
+++ b/docs/app/controllers/docs_controller.rb
@@ -226,6 +226,10 @@ def skeleton
     render Views::Docs::Skeleton.new
   end
 
+  def spinner
+    render Views::Docs::Spinner.new
+  end
+
   def switch
     render Views::Docs::Switch.new
   end
diff --git a/docs/app/lib/site_files.rb b/docs/app/lib/site_files.rb
index 94ef4ef81..b37c71f4e 100644
--- a/docs/app/lib/site_files.rb
+++ b/docs/app/lib/site_files.rb
@@ -123,6 +123,7 @@ class SiteFiles
     {title: "Shortcut Key", path: "/docs/shortcut_key", description: "Keyboard shortcut display component."},
     {title: "Sidebar", path: "/docs/sidebar", description: "Composable, themeable sidebar component."},
     {title: "Skeleton", path: "/docs/skeleton", description: "Placeholder for loading states."},
+    {title: "Spinner", path: "/docs/spinner", description: "Animated indicator for loading states."},
     {title: "Switch", path: "/docs/switch", description: "Toggle control for binary settings."},
     {title: "Table", path: "/docs/table", description: "Responsive table component."},
     {title: "Tabs", path: "/docs/tabs", description: "Layered tab panels displayed one at a time."},
diff --git a/docs/app/views/docs/spinner.rb b/docs/app/views/docs/spinner.rb
new file mode 100644
index 000000000..679fd2432
--- /dev/null
+++ b/docs/app/views/docs/spinner.rb
@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+class Views::Docs::Spinner < Views::Base
+  def view_template
+    component = "Spinner"
+
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      render Docs::Header.new(title: "Spinner", description: "An indicator that can be used to show a loading state.")
+
+      Heading(level: 2) { "Usage" }
+
+      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+        <<~RUBY
+          Spinner()
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Size", description: "The size is controlled from the outside with any size utility.", context: self) do
+        <<~RUBY
+          div(class: "flex items-center gap-6") do
+            Spinner(class: "size-3")
+            Spinner(class: "size-4")
+            Spinner(class: "size-6")
+            Spinner(class: "size-8")
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Color", description: "The spinner inherits the current text color.", context: self) do
+        <<~RUBY
+          div(class: "flex items-center gap-6") do
+            Spinner(class: "size-6 text-red-500")
+            Spinner(class: "size-6 text-green-500")
+            Spinner(class: "size-6 text-blue-500")
+            Spinner(class: "size-6 text-muted-foreground")
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Button", description: "The button carries the state, the spinner is decorative.", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap items-center gap-4") do
+            Button(disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil)
+              plain "Loading..."
+            end
+            Button(variant: :outline, disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil)
+              plain "Please wait"
+            end
+            Button(variant: :secondary, size: :sm, disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil, class: "size-3")
+              plain "Processing"
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Badge", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap items-center gap-4") do
+            Badge(class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Syncing"
+            end
+            Badge(variant: :outline, class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Updating"
+            end
+            Badge(variant: :destructive, class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Deleting"
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Empty", description: "Use a spinner as the media of an empty state to build a loading screen.", context: self) do
+        <<~RUBY
+          Empty(class: "w-full") do
+            EmptyHeader do
+              EmptyMedia(variant: :icon) do
+                Spinner()
+              end
+              EmptyTitle { "Processing your request" }
+              EmptyDescription { "Please wait while we process your request. Do not refresh the page." }
+            end
+            EmptyContent do
+              Button(variant: :outline, size: :sm) { "Cancel" }
+            end
+          end
+        RUBY
+      end
+
+      Heading(level: 2) { "Customization" }
+
+      Text do
+        plain "The generator copies "
+        InlineCode { "spinner.rb" }
+        plain " into "
+        InlineCode { "app/components/ruby_ui/spinner/" }
+        plain ", so the component belongs to your app. RubyUI inlines the SVG because the gem ships no icon dependency — but if your app has one, such as "
+        InlineLink(href: "https://github.com/AliOsm/phlex-icons", target: "_blank") { "phlex-icons" }
+        plain ", replace "
+        InlineCode { "view_template" }
+        plain " with the icon component and drop the two constants."
+      end
+
+      Codeblock(<<~RUBY, syntax: :ruby)
+        # app/components/ruby_ui/spinner/spinner.rb
+        module RubyUI
+          class Spinner < Base
+            include PhlexIcons
+
+            def view_template
+              Lucide::LoaderPinwheel(**attrs)
+            end
+
+            # initialize and default_attrs stay as they are;
+            # ICON_PATH and ICON_ATTRS are no longer needed
+          end
+        end
+      RUBY
+
+      Text do
+        plain "Without an icon gem, swap "
+        InlineCode { "ICON_PATH" }
+        plain " for the path data of any other 24x24 stroke icon. An icon drawn with more than one path needs those extra elements added to "
+        InlineCode { "view_template" }
+        plain " too."
+      end
+
+      Heading(level: 2) { "Accessibility" }
+
+      Text do
+        plain "A standalone spinner announces itself with "
+        InlineCode { 'role="status"' }
+        plain " and "
+        InlineCode { 'aria-label="Loading"' }
+        plain ". Pass "
+        InlineCode { "label:" }
+        plain " to describe the specific operation."
+      end
+
+      Text do
+        plain "Inside a button, badge or any other labelled control, pass "
+        InlineCode { "label: nil" }
+        plain " to render the spinner as decoration ("
+        InlineCode { 'aria-hidden="true"' }
+        plain ") and let the control announce the state with "
+        InlineCode { 'aria-busy="true"' }
+        plain ". A labelled spinner would otherwise be read out as part of the control's own name."
+      end
+
+      Codeblock(<<~RUBY, syntax: :ruby)
+        # announces itself
+        Spinner(label: "Saving changes")
+        # => <svg role="status" aria-label="Saving changes" ...>
+
+        # decorative, inside a control that announces the state
+        Spinner(label: nil)
+        # => <svg aria-hidden="true" ...>
+      RUBY
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      # components
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+end
diff --git a/docs/config/routes.rb b/docs/config/routes.rb
index 2eab1c1e7..749c6b06a 100644
--- a/docs/config/routes.rb
+++ b/docs/config/routes.rb
@@ -69,6 +69,7 @@
     get "sidebar/example", to: "docs/sidebar#example", as: :docs_sidebar_example
     get "sidebar/inset", to: "docs/sidebar#inset_example", as: :docs_sidebar_inset
     get "skeleton", to: "docs#skeleton", as: :docs_skeleton
+    get "spinner", to: "docs#spinner", as: :docs_spinner
     get "switch", to: "docs#switch", as: :docs_switch
     get "table", to: "docs#table", as: :docs_table
     get "tabs", to: "docs#tabs", as: :docs_tabs
diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index 5d98c5ae1..375f1b97b 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -303,6 +303,11 @@ This file expands the curated /llms.txt map into a compact reference that can be
 - URL: https://rubyui.com/docs/skeleton
 - Summary: Placeholder for loading states.
 
+### Spinner
+
+- URL: https://rubyui.com/docs/spinner
+- Summary: Animated indicator for loading states.
+
 ### Switch
 
 - URL: https://rubyui.com/docs/switch
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index c98b90362..bd476c918 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -65,6 +65,7 @@ Use the core docs first for installation, theming, dark mode, and customization
 - [Shortcut Key](https://rubyui.com/docs/shortcut_key): Keyboard shortcut display component.
 - [Sidebar](https://rubyui.com/docs/sidebar): Composable, themeable sidebar component.
 - [Skeleton](https://rubyui.com/docs/skeleton): Placeholder for loading states.
+- [Spinner](https://rubyui.com/docs/spinner): Animated indicator for loading states.
 - [Switch](https://rubyui.com/docs/switch): Toggle control for binary settings.
 - [Table](https://rubyui.com/docs/table): Responsive table component.
 - [Tabs](https://rubyui.com/docs/tabs): Layered tab panels displayed one at a time.
diff --git a/docs/public/sitemap.xml b/docs/public/sitemap.xml
index abb37124c..2988b7e18 100644
--- a/docs/public/sitemap.xml
+++ b/docs/public/sitemap.xml
@@ -280,6 +280,11 @@
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
+  <url>
+    <loc>https://rubyui.com/docs/spinner</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.7</priority>
+  </url>
   <url>
     <loc>https://rubyui.com/docs/switch</loc>
     <changefreq>monthly</changefreq>
diff --git a/gem/lib/ruby_ui/spinner/spinner.rb b/gem/lib/ruby_ui/spinner/spinner.rb
new file mode 100644
index 000000000..842843178
--- /dev/null
+++ b/gem/lib/ruby_ui/spinner/spinner.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RubyUI
+  class Spinner < Base
+    # lucide loader-circle
+    ICON_PATH = "M21 12a9 9 0 1 1-6.219-8.56"
+
+    ICON_ATTRS = {
+      xmlns: "http://www.w3.org/2000/svg",
+      viewbox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      stroke_width: "2",
+      stroke_linecap: "round",
+      stroke_linejoin: "round"
+    }.freeze
+
+    def initialize(label: "Loading", **attrs)
+      @label = label
+      super(**attrs)
+    end
+
+    def view_template
+      svg(**ICON_ATTRS, **attrs) do |s|
+        s.path(d: ICON_PATH)
+      end
+    end
+
+    private
+
+    def default_attrs
+      {
+        **announcement_attrs,
+        data: {slot: "spinner"},
+        class: "size-4 shrink-0 animate-spin"
+      }
+    end
+
+    # A spinner inside a labelled control is decorative — the control announces busy.
+    def announcement_attrs
+      return {aria: {hidden: "true"}} if @label.to_s.strip.empty?
+
+      {role: "status", aria: {label: @label}}
+    end
+  end
+end
diff --git a/gem/lib/ruby_ui/spinner/spinner_docs.rb b/gem/lib/ruby_ui/spinner/spinner_docs.rb
new file mode 100644
index 000000000..679fd2432
--- /dev/null
+++ b/gem/lib/ruby_ui/spinner/spinner_docs.rb
@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+class Views::Docs::Spinner < Views::Base
+  def view_template
+    component = "Spinner"
+
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      render Docs::Header.new(title: "Spinner", description: "An indicator that can be used to show a loading state.")
+
+      Heading(level: 2) { "Usage" }
+
+      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+        <<~RUBY
+          Spinner()
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Size", description: "The size is controlled from the outside with any size utility.", context: self) do
+        <<~RUBY
+          div(class: "flex items-center gap-6") do
+            Spinner(class: "size-3")
+            Spinner(class: "size-4")
+            Spinner(class: "size-6")
+            Spinner(class: "size-8")
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Color", description: "The spinner inherits the current text color.", context: self) do
+        <<~RUBY
+          div(class: "flex items-center gap-6") do
+            Spinner(class: "size-6 text-red-500")
+            Spinner(class: "size-6 text-green-500")
+            Spinner(class: "size-6 text-blue-500")
+            Spinner(class: "size-6 text-muted-foreground")
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Button", description: "The button carries the state, the spinner is decorative.", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap items-center gap-4") do
+            Button(disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil)
+              plain "Loading..."
+            end
+            Button(variant: :outline, disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil)
+              plain "Please wait"
+            end
+            Button(variant: :secondary, size: :sm, disabled: true, aria: {busy: "true"}, class: "gap-2") do
+              Spinner(label: nil, class: "size-3")
+              plain "Processing"
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Badge", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap items-center gap-4") do
+            Badge(class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Syncing"
+            end
+            Badge(variant: :outline, class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Updating"
+            end
+            Badge(variant: :destructive, class: "gap-1.5") do
+              Spinner(label: nil, class: "size-3")
+              plain "Deleting"
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Empty", description: "Use a spinner as the media of an empty state to build a loading screen.", context: self) do
+        <<~RUBY
+          Empty(class: "w-full") do
+            EmptyHeader do
+              EmptyMedia(variant: :icon) do
+                Spinner()
+              end
+              EmptyTitle { "Processing your request" }
+              EmptyDescription { "Please wait while we process your request. Do not refresh the page." }
+            end
+            EmptyContent do
+              Button(variant: :outline, size: :sm) { "Cancel" }
+            end
+          end
+        RUBY
+      end
+
+      Heading(level: 2) { "Customization" }
+
+      Text do
+        plain "The generator copies "
+        InlineCode { "spinner.rb" }
+        plain " into "
+        InlineCode { "app/components/ruby_ui/spinner/" }
+        plain ", so the component belongs to your app. RubyUI inlines the SVG because the gem ships no icon dependency — but if your app has one, such as "
+        InlineLink(href: "https://github.com/AliOsm/phlex-icons", target: "_blank") { "phlex-icons" }
+        plain ", replace "
+        InlineCode { "view_template" }
+        plain " with the icon component and drop the two constants."
+      end
+
+      Codeblock(<<~RUBY, syntax: :ruby)
+        # app/components/ruby_ui/spinner/spinner.rb
+        module RubyUI
+          class Spinner < Base
+            include PhlexIcons
+
+            def view_template
+              Lucide::LoaderPinwheel(**attrs)
+            end
+
+            # initialize and default_attrs stay as they are;
+            # ICON_PATH and ICON_ATTRS are no longer needed
+          end
+        end
+      RUBY
+
+      Text do
+        plain "Without an icon gem, swap "
+        InlineCode { "ICON_PATH" }
+        plain " for the path data of any other 24x24 stroke icon. An icon drawn with more than one path needs those extra elements added to "
+        InlineCode { "view_template" }
+        plain " too."
+      end
+
+      Heading(level: 2) { "Accessibility" }
+
+      Text do
+        plain "A standalone spinner announces itself with "
+        InlineCode { 'role="status"' }
+        plain " and "
+        InlineCode { 'aria-label="Loading"' }
+        plain ". Pass "
+        InlineCode { "label:" }
+        plain " to describe the specific operation."
+      end
+
+      Text do
+        plain "Inside a button, badge or any other labelled control, pass "
+        InlineCode { "label: nil" }
+        plain " to render the spinner as decoration ("
+        InlineCode { 'aria-hidden="true"' }
+        plain ") and let the control announce the state with "
+        InlineCode { 'aria-busy="true"' }
+        plain ". A labelled spinner would otherwise be read out as part of the control's own name."
+      end
+
+      Codeblock(<<~RUBY, syntax: :ruby)
+        # announces itself
+        Spinner(label: "Saving changes")
+        # => <svg role="status" aria-label="Saving changes" ...>
+
+        # decorative, inside a control that announces the state
+        Spinner(label: nil)
+        # => <svg aria-hidden="true" ...>
+      RUBY
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      # components
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+end
diff --git a/gem/test/ruby_ui/spinner_test.rb b/gem/test/ruby_ui/spinner_test.rb
new file mode 100644
index 000000000..31f4bd34c
--- /dev/null
+++ b/gem/test/ruby_ui/spinner_test.rb
@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class RubyUI::SpinnerTest < ComponentTest
+  def test_render
+    output = phlex do
+      RubyUI::Spinner()
+    end
+
+    assert_match(/<svg/, output)
+    assert_match(/viewbox="0 0 24 24"/, output)
+    assert_match(/stroke="currentColor"/, output)
+    assert_match(/role="status"/, output)
+    assert_match(/aria-label="Loading"/, output)
+    assert_match(/data-slot="spinner"/, output)
+    assert_match(/size-4/, output)
+    assert_match(/animate-spin/, output)
+  end
+
+  def test_render_with_custom_size
+    output = phlex do
+      RubyUI::Spinner(class: "size-6 text-blue-500")
+    end
+
+    assert_match(/size-6/, output)
+    refute_match(/size-4/, output)
+    assert_match(/text-blue-500/, output)
+    assert_match(/animate-spin/, output)
+  end
+
+  def test_render_with_custom_label
+    output = phlex do
+      RubyUI::Spinner(label: "Saving")
+    end
+
+    assert_match(/aria-label="Saving"/, output)
+    refute_match(/Loading/, output)
+  end
+
+  def test_render_decorative_when_label_is_nil
+    output = phlex do
+      RubyUI::Spinner(label: nil)
+    end
+
+    assert_match(/aria-hidden="true"/, output)
+    refute_match(/role="status"/, output)
+    refute_match(/aria-label/, output)
+  end
+
+  def test_render_decorative_when_label_is_blank
+    ["", "  "].each do |label|
+      output = phlex do
+        RubyUI::Spinner(label: label)
+      end
+
+      assert_match(/aria-hidden="true"/, output)
+      refute_match(/role="status"/, output)
+      refute_match(/aria-label/, output)
+    end
+  end
+
+  def test_render_with_arbitrary_attrs
+    output = phlex do
+      RubyUI::Spinner(data: {icon: "inline-start"}, id: "save-spinner")
+    end
+
+    assert_match(/data-icon="inline-start"/, output)
+    assert_match(/data-slot="spinner"/, output)
+    assert_match(/id="save-spinner"/, output)
+  end
+end
diff --git a/mcp/data/registry.json b/mcp/data/registry.json
index ed4cd153a..0bfd76e1c 100644
--- a/mcp/data/registry.json
+++ b/mcp/data/registry.json
@@ -1524,7 +1524,7 @@
         "gems": []
       },
       "install_command": "rails g ruby_ui:component Form",
-      "docs_markdown": "# Form\n\nBuilding forms with built-in client-side validations.\n\n## Usage\n\n### Example\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Default error\" }\n    Input(placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\n    FormFieldHint()\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Disabled\n\n```ruby\nFormField do\n  FormFieldLabel { \"Disabled\" }\n  Input(disabled: true, placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\nend\n```\n\n### Aria Disabled\n\n```ruby\nFormField do\n  FormFieldLabel { \"Aria Disabled\" }\n  Input(aria: {disabled: \"true\"}, placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\nend\n```\n\n### Custom error message\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Custom error message\" }\n    Input(placeholder: \"joel@drapper.me\", required: true, data_value_missing: \"Custom error message\")\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Backend error\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Backend error\" }\n    Input(placeholder: \"Joel Drapper\", required: true)\n    FormFieldError { \"Error from backend\" }\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Checkbox\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    Checkbox(required: true)\n      label(\n        class:\n          \"text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70\"\n      ) { \" Accept terms and conditions \" }\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Select\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Select\" }\n    Select do\n      SelectInput(required: true)\n      SelectTrigger do\n        SelectValue(placeholder: \"Select a fruit\")\n      end\n      SelectContent() do\n        SelectGroup do\n          SelectLabel { \"Fruits\" }\n          SelectItem(value: \"apple\") { \"Apple\" }\n          SelectItem(value: \"orange\") { \"Orange\" }\n          SelectItem(value: \"banana\") { \"Banana\" }\n          SelectItem(value: \"watermelon\") { \"Watermelon\" }\n        end\n      end\n    end\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Combobox\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Combobox\" }\n\n    Combobox do\n      ComboboxTrigger placeholder: \"Pick value\"\n\n      ComboboxPopover do\n        ComboboxSearchInput(placeholder: \"Pick value or type anything\")\n\n        ComboboxList do\n          ComboboxEmptyState { \"No result\" }\n\n          ComboboxListGroup label: \"Fruits\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"apple\", required: true)\n              span { \"Apple\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"banana\", required: true)\n              span { \"Banana\" }\n            end\n          end\n\n          ComboboxListGroup label: \"Vegetable\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"brocoli\", required: true)\n              span { \"Broccoli\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"carrot\", required: true)\n              span { \"Carrot\" }\n            end\n          end\n\n          ComboboxListGroup label: \"Others\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"chocolate\", required: true)\n              span { \"Chocolate\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"milk\", required: true)\n              span { \"Milk\" }\n            end\n          end\n        end\n      end\n    end\n\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n## Rails Integration\n\n### Minimal Rails form\n\n### Devise-style login form",
+      "docs_markdown": "# Form\n\nBuilding forms with built-in client-side validations.\n\n## Usage\n\n### Example\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Default error\" }\n    Input(placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\n    FormFieldHint()\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Disabled\n\n```ruby\nFormField do\n  FormFieldLabel { \"Disabled\" }\n  Input(disabled: true, placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\nend\n```\n\n### Aria Disabled\n\n```ruby\nFormField do\n  FormFieldLabel { \"Aria Disabled\" }\n  Input(aria: {disabled: \"true\"}, placeholder: \"Joel Drapper\", required: true, minlength: \"3\") { \"Joel Drapper\" }\nend\n```\n\n### Custom error message\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Custom error message\" }\n    Input(placeholder: \"joel@drapper.me\", required: true, data_value_missing: \"Custom error message\")\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Backend error\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Backend error\" }\n    Input(placeholder: \"Joel Drapper\", required: true)\n    FormFieldError { \"Error from backend\" }\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Checkbox\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    Checkbox(required: true)\n      label(\n        class:\n          \"text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70\"\n      ) { \" Accept terms and conditions \" }\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Select\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Select\" }\n    Select do\n      SelectInput(required: true)\n      SelectTrigger do\n        SelectValue(placeholder: \"Select a fruit\")\n      end\n      SelectContent() do\n        SelectGroup do\n          SelectLabel { \"Fruits\" }\n          SelectItem(value: \"apple\") { \"Apple\" }\n          SelectItem(value: \"orange\") { \"Orange\" }\n          SelectItem(value: \"banana\") { \"Banana\" }\n          SelectItem(value: \"watermelon\") { \"Watermelon\" }\n        end\n      end\n    end\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n### Combobox\n\n```ruby\nForm(class: \"w-2/3 space-y-6\") do\n  FormField do\n    FormFieldLabel { \"Combobox\" }\n\n    Combobox do\n      ComboboxTrigger placeholder: \"Pick value\"\n\n      ComboboxPopover do\n        ComboboxSearchInput(placeholder: \"Pick value or type anything\")\n\n        ComboboxList do\n          ComboboxEmptyState { \"No result\" }\n\n          ComboboxListGroup label: \"Fruits\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"apple\", required: true)\n              span { \"Apple\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"banana\", required: true)\n              span { \"Banana\" }\n            end\n          end\n\n          ComboboxListGroup label: \"Vegetable\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"brocoli\", required: true)\n              span { \"Broccoli\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"carrot\", required: true)\n              span { \"Carrot\" }\n            end\n          end\n\n          ComboboxListGroup label: \"Others\" do\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"chocolate\", required: true)\n              span { \"Chocolate\" }\n            end\n\n            ComboboxItem do\n              ComboboxRadio(name: \"food\", value: \"milk\", required: true)\n              span { \"Milk\" }\n            end\n          end\n        end\n      end\n    end\n\n    FormFieldError()\n  end\n  Button(type: \"submit\") { \"Save\" }\nend\n```\n\n## Rails Integration\n\n### Minimal Rails form\n\n```ruby\n# In your Phlex view, call form_with via helpers:\n# form_with(url: users_path, method: :post) passes action + CSRF automatically.\n#\n# You can also set action and the CSRF token manually:\nForm(action: helpers.users_path, method: \"post\", class: \"w-2/3 space-y-6\") do\n  input(type: \"hidden\", name: \"authenticity_token\", value: helpers.form_authenticity_token)\n\n  FormField do\n    FormFieldLabel(for: \"user_email\") { \"Email\" }\n    Input(\n      type: \"email\",\n      id: \"user_email\",\n      name: \"user[email]\",\n      placeholder: \"you@example.com\",\n      required: true\n    )\n    FormFieldError()\n  end\n\n  Button(type: \"submit\") { \"Continue\" }\nend\n```\n\n### Devise-style login form\n\n```ruby\n# Full sign-in form mirroring Devise session[email] / session[password] params.\n# Pass backend errors (e.g. \"Invalid email or password\") into FormFieldError.\nForm(action: helpers.user_session_path, method: \"post\", class: \"space-y-6\") do\n  input(type: \"hidden\", name: \"authenticity_token\", value: helpers.form_authenticity_token)\n\n  FormField do\n    FormFieldLabel(for: \"session_email\") { \"Email\" }\n    Input(\n      type: \"email\",\n      id: \"session_email\",\n      name: \"session[email]\",\n      placeholder: \"you@example.com\",\n      autocomplete: \"email\",\n      required: true\n    )\n    FormFieldError { @error_message }\n  end\n\n  FormField do\n    FormFieldLabel(for: \"session_password\") { \"Password\" }\n    Input(\n      type: \"password\",\n      id: \"session_password\",\n      name: \"session[password]\",\n      autocomplete: \"current-password\",\n      required: true,\n      minlength: \"8\"\n    )\n    FormFieldError()\n  end\n\n  FormField do\n    div(class: \"flex items-center gap-2\") do\n      Checkbox(id: \"session_remember_me\", name: \"session[remember_me]\", value: \"1\")\n      FormFieldLabel(for: \"session_remember_me\") { \"Remember me\" }\n    end\n  end\n\n  Button(type: \"submit\", class: \"w-full\") { \"Sign in\" }\nend\n```",
       "examples": [
         {
           "title": "Example",
@@ -1686,7 +1686,7 @@
         "gems": []
       },
       "install_command": "rails g ruby_ui:component InputOtp",
-      "docs_markdown": "# Input OTP\n\nAccessible one-time-password input with keyboard navigation and paste support.\n\n## Usage\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Composition\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n  end\n  InputOtpSeparator()\n  InputOtpGroup do\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n  end\n  InputOtpSeparator()\n  InputOtpGroup do\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Pattern\n\n### Alphanumeric\n\n```ruby\nInputOtp(length: 6, name: \"otp\", pattern: \"[0-9A-Za-z]\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Four digits\n\n### Example\n\n```ruby\nInputOtp(length: 4, name: \"pin\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n  end\nend\n```\n\n## Disabled\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\", disabled: true) do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Invalid\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0, aria_invalid: \"true\")\n    InputOtpSlot(index: 1, aria_invalid: \"true\")\n    InputOtpSlot(index: 2, aria_invalid: \"true\")\n    InputOtpSlot(index: 3, aria_invalid: \"true\")\n    InputOtpSlot(index: 4, aria_invalid: \"true\")\n    InputOtpSlot(index: 5, aria_invalid: \"true\")\n  end\nend\n```\n\n## Form\n\n### Verify your login\n\n```ruby\nCard(class: \"mx-auto max-w-md\") do\n  CardHeader do\n    CardTitle { \"Verify your login\" }\n    CardDescription do\n      plain \"Enter the verification code we sent to your email address: \"\n      span(class: \"font-medium\") { \"m@example.com\" }\n      plain \".\"\n    end\n  end\n  CardContent(class: \"space-y-4\") do\n    div(class: \"flex items-center justify-between\") do\n      label(class: \"text-sm font-medium\") { \"Verification code\" }\n      Button(variant: :outline, size: :sm) do\n        svg(\n          xmlns: \"http://www.w3.org/2000/svg\",\n          viewbox: \"0 0 24 24\",\n          fill: \"none\",\n          stroke: \"currentColor\",\n          stroke_width: \"2\",\n          stroke_linecap: \"round\",\n          stroke_linejoin: \"round\",\n          class: \"w-4 h-4 mr-2\"\n        ) do |s|\n          s.path(d: \"M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8\")\n          s.path(d: \"M21 3v5h-5\")\n          s.path(d: \"M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16\")\n          s.path(d: \"M8 16H3v5\")\n        end\n        plain \"Resend Code\"\n      end\n    end\n    InputOtp(length: 6, name: \"otp\", required: true) do\n      InputOtpGroup do\n        InputOtpSlot(index: 0, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 1, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 2, class: \"h-12 w-11 text-xl\")\n      end\n      InputOtpSeparator(class: \"mx-2\")\n      InputOtpGroup do\n        InputOtpSlot(index: 3, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 4, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 5, class: \"h-12 w-11 text-xl\")\n      end\n    end\n    InlineLink(href: \"#\") { \"I no longer have access to this email address.\" }\n  end\n  CardFooter(class: \"flex flex-col items-stretch gap-2\") do\n    Button(class: \"w-full\") { \"Verify\" }\n    Text(size: \"sm\", weight: \"muted\") do\n      plain \"Having trouble signing in? \"\n      InlineLink(href: \"#\") { \"Contact support\" }\n    end\n  end\nend\n```\n\n## Reacting to completion",
+      "docs_markdown": "# Input OTP\n\nAccessible one-time-password input with keyboard navigation and paste support.\n\n## Usage\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Composition\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n  end\n  InputOtpSeparator()\n  InputOtpGroup do\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n  end\n  InputOtpSeparator()\n  InputOtpGroup do\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Pattern\n\n### Alphanumeric\n\n```ruby\nInputOtp(length: 6, name: \"otp\", pattern: \"[0-9A-Za-z]\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Four digits\n\n### Example\n\n```ruby\nInputOtp(length: 4, name: \"pin\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n  end\nend\n```\n\n## Disabled\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\", disabled: true) do\n  InputOtpGroup do\n    InputOtpSlot(index: 0)\n    InputOtpSlot(index: 1)\n    InputOtpSlot(index: 2)\n    InputOtpSlot(index: 3)\n    InputOtpSlot(index: 4)\n    InputOtpSlot(index: 5)\n  end\nend\n```\n\n## Invalid\n\n### Example\n\n```ruby\nInputOtp(length: 6, name: \"otp\") do\n  InputOtpGroup do\n    InputOtpSlot(index: 0, aria_invalid: \"true\")\n    InputOtpSlot(index: 1, aria_invalid: \"true\")\n    InputOtpSlot(index: 2, aria_invalid: \"true\")\n    InputOtpSlot(index: 3, aria_invalid: \"true\")\n    InputOtpSlot(index: 4, aria_invalid: \"true\")\n    InputOtpSlot(index: 5, aria_invalid: \"true\")\n  end\nend\n```\n\n## Form\n\n### Verify your login\n\n```ruby\nCard(class: \"mx-auto max-w-md\") do\n  CardHeader do\n    CardTitle { \"Verify your login\" }\n    CardDescription do\n      plain \"Enter the verification code we sent to your email address: \"\n      span(class: \"font-medium\") { \"m@example.com\" }\n      plain \".\"\n    end\n  end\n  CardContent(class: \"space-y-4\") do\n    div(class: \"flex items-center justify-between\") do\n      label(class: \"text-sm font-medium\") { \"Verification code\" }\n      Button(variant: :outline, size: :sm) do\n        svg(\n          xmlns: \"http://www.w3.org/2000/svg\",\n          viewbox: \"0 0 24 24\",\n          fill: \"none\",\n          stroke: \"currentColor\",\n          stroke_width: \"2\",\n          stroke_linecap: \"round\",\n          stroke_linejoin: \"round\",\n          class: \"w-4 h-4 mr-2\"\n        ) do |s|\n          s.path(d: \"M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8\")\n          s.path(d: \"M21 3v5h-5\")\n          s.path(d: \"M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16\")\n          s.path(d: \"M8 16H3v5\")\n        end\n        plain \"Resend Code\"\n      end\n    end\n    InputOtp(length: 6, name: \"otp\", required: true) do\n      InputOtpGroup do\n        InputOtpSlot(index: 0, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 1, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 2, class: \"h-12 w-11 text-xl\")\n      end\n      InputOtpSeparator(class: \"mx-2\")\n      InputOtpGroup do\n        InputOtpSlot(index: 3, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 4, class: \"h-12 w-11 text-xl\")\n        InputOtpSlot(index: 5, class: \"h-12 w-11 text-xl\")\n      end\n    end\n    InlineLink(href: \"#\") { \"I no longer have access to this email address.\" }\n  end\n  CardFooter(class: \"flex flex-col items-stretch gap-2\") do\n    Button(class: \"w-full\") { \"Verify\" }\n    Text(size: \"sm\", weight: \"muted\") do\n      plain \"Having trouble signing in? \"\n      InlineLink(href: \"#\") { \"Contact support\" }\n    end\n  end\nend\n```\n\n## Reacting to completion\n\n```js\n// app/javascript/controllers/otp_form_controller.js\nimport { Controller } from \"@hotwired/stimulus\"\n\nexport default class extends Controller {\n  submit() {\n    this.element.requestSubmit()\n  }\n}\n```\n\n```html\n<form data-controller=\"otp-form\" data-action=\"ruby-ui--input-otp:complete->otp-form#submit\">\n  <!-- InputOtp(...) here -->\n</form>\n```",
       "examples": [
         {
           "title": "Example",
@@ -2511,6 +2511,55 @@
         }
       ]
     },
+    "spinner": {
+      "name": "Spinner",
+      "description": "An indicator that can be used to show a loading state.",
+      "files": [
+        {
+          "path": "spinner.rb",
+          "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class Spinner < Base\n    # lucide loader-circle\n    ICON_PATH = \"M21 12a9 9 0 1 1-6.219-8.56\"\n\n    ICON_ATTRS = {\n      xmlns: \"http://www.w3.org/2000/svg\",\n      viewbox: \"0 0 24 24\",\n      fill: \"none\",\n      stroke: \"currentColor\",\n      stroke_width: \"2\",\n      stroke_linecap: \"round\",\n      stroke_linejoin: \"round\"\n    }.freeze\n\n    def initialize(label: \"Loading\", **attrs)\n      @label = label\n      super(**attrs)\n    end\n\n    def view_template\n      svg(**ICON_ATTRS, **attrs) do |s|\n        s.path(d: ICON_PATH)\n      end\n    end\n\n    private\n\n    def default_attrs\n      {\n        **announcement_attrs,\n        data: {slot: \"spinner\"},\n        class: \"size-4 shrink-0 animate-spin\"\n      }\n    end\n\n    # A spinner inside a labelled control is decorative — the control announces busy.\n    def announcement_attrs\n      return {aria: {hidden: \"true\"}} if @label.to_s.strip.empty?\n\n      {role: \"status\", aria: {label: @label}}\n    end\n  end\nend\n"
+        }
+      ],
+      "dependencies": {
+        "components": [],
+        "js_packages": [],
+        "gems": []
+      },
+      "install_command": "rails g ruby_ui:component Spinner",
+      "docs_markdown": "# Spinner\n\nAn indicator that can be used to show a loading state.\n\n## Usage\n\n### Example\n\n```ruby\nSpinner()\n```\n\n### Size\n\n```ruby\ndiv(class: \"flex items-center gap-6\") do\n  Spinner(class: \"size-3\")\n  Spinner(class: \"size-4\")\n  Spinner(class: \"size-6\")\n  Spinner(class: \"size-8\")\nend\n```\n\n### Color\n\n```ruby\ndiv(class: \"flex items-center gap-6\") do\n  Spinner(class: \"size-6 text-red-500\")\n  Spinner(class: \"size-6 text-green-500\")\n  Spinner(class: \"size-6 text-blue-500\")\n  Spinner(class: \"size-6 text-muted-foreground\")\nend\n```\n\n### Button\n\n```ruby\ndiv(class: \"flex flex-wrap items-center gap-4\") do\n  Button(disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil)\n    plain \"Loading...\"\n  end\n  Button(variant: :outline, disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil)\n    plain \"Please wait\"\n  end\n  Button(variant: :secondary, size: :sm, disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Processing\"\n  end\nend\n```\n\n### Badge\n\n```ruby\ndiv(class: \"flex flex-wrap items-center gap-4\") do\n  Badge(class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Syncing\"\n  end\n  Badge(variant: :outline, class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Updating\"\n  end\n  Badge(variant: :destructive, class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Deleting\"\n  end\nend\n```\n\n### Empty\n\n```ruby\nEmpty(class: \"w-full\") do\n  EmptyHeader do\n    EmptyMedia(variant: :icon) do\n      Spinner()\n    end\n    EmptyTitle { \"Processing your request\" }\n    EmptyDescription { \"Please wait while we process your request. Do not refresh the page.\" }\n  end\n  EmptyContent do\n    Button(variant: :outline, size: :sm) { \"Cancel\" }\n  end\nend\n```\n\n## Customization\n\n```ruby\n# app/components/ruby_ui/spinner/spinner.rb\nmodule RubyUI\n  class Spinner < Base\n    include PhlexIcons\n\n    def view_template\n      Lucide::LoaderPinwheel(**attrs)\n    end\n\n    # initialize and default_attrs stay as they are;\n    # ICON_PATH and ICON_ATTRS are no longer needed\n  end\nend\n```\n\n## Accessibility\n\n```ruby\n# announces itself\nSpinner(label: \"Saving changes\")\n# => <svg role=\"status\" aria-label=\"Saving changes\" ...>\n\n# decorative, inside a control that announces the state\nSpinner(label: nil)\n# => <svg aria-hidden=\"true\" ...>\n```",
+      "examples": [
+        {
+          "title": "Example",
+          "code": "Spinner()\n",
+          "language": "ruby"
+        },
+        {
+          "title": "Size",
+          "code": "div(class: \"flex items-center gap-6\") do\n  Spinner(class: \"size-3\")\n  Spinner(class: \"size-4\")\n  Spinner(class: \"size-6\")\n  Spinner(class: \"size-8\")\nend\n",
+          "language": "ruby"
+        },
+        {
+          "title": "Color",
+          "code": "div(class: \"flex items-center gap-6\") do\n  Spinner(class: \"size-6 text-red-500\")\n  Spinner(class: \"size-6 text-green-500\")\n  Spinner(class: \"size-6 text-blue-500\")\n  Spinner(class: \"size-6 text-muted-foreground\")\nend\n",
+          "language": "ruby"
+        },
+        {
+          "title": "Button",
+          "code": "div(class: \"flex flex-wrap items-center gap-4\") do\n  Button(disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil)\n    plain \"Loading...\"\n  end\n  Button(variant: :outline, disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil)\n    plain \"Please wait\"\n  end\n  Button(variant: :secondary, size: :sm, disabled: true, aria: {busy: \"true\"}, class: \"gap-2\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Processing\"\n  end\nend\n",
+          "language": "ruby"
+        },
+        {
+          "title": "Badge",
+          "code": "div(class: \"flex flex-wrap items-center gap-4\") do\n  Badge(class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Syncing\"\n  end\n  Badge(variant: :outline, class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Updating\"\n  end\n  Badge(variant: :destructive, class: \"gap-1.5\") do\n    Spinner(label: nil, class: \"size-3\")\n    plain \"Deleting\"\n  end\nend\n",
+          "language": "ruby"
+        },
+        {
+          "title": "Empty",
+          "code": "Empty(class: \"w-full\") do\n  EmptyHeader do\n    EmptyMedia(variant: :icon) do\n      Spinner()\n    end\n    EmptyTitle { \"Processing your request\" }\n    EmptyDescription { \"Please wait while we process your request. Do not refresh the page.\" }\n  end\n  EmptyContent do\n    Button(variant: :outline, size: :sm) { \"Cancel\" }\n  end\nend\n",
+          "language": "ruby"
+        }
+      ]
+    },
     "switch": {
       "name": "Switch",
       "description": "A control that allows the user to toggle between checked and not checked.",
diff --git a/mcp/lib/ruby_ui/mcp/builders/registry_builder.rb b/mcp/lib/ruby_ui/mcp/builders/registry_builder.rb
index 521e0fb51..3541724eb 100644
--- a/mcp/lib/ruby_ui/mcp/builders/registry_builder.rb
+++ b/mcp/lib/ruby_ui/mcp/builders/registry_builder.rb
@@ -136,6 +136,15 @@ def parse_docs_source(src)
               next
             end
 
+            # Codeblock(<<~LANG, ...) — standalone sample, not a live example
+            if (m = line.match(/\bCodeblock\(<<~([A-Z]+)/))
+              lang = m[1]
+              code, k = heredoc_body(lines, i + 1, lang)
+              markdown << "```#{lang.downcase}\n#{code}```\n\n"
+              i = k + 1
+              next
+            end
+
             # VisualCodeExample.new(...)
             if line.match(/VisualCodeExample\.new\(/)
               # collect full invocation (may span multiple lines until closing paren + do)
@@ -164,15 +173,7 @@ def parse_docs_source(src)
               end
 
               if heredoc_lang
-                # accumulate heredoc body
-                body_lines = []
-                while k < lines.length
-                  break if lines[k].match(/^\s*#{Regexp.escape(heredoc_lang)}\s*$/)
-                  body_lines << lines[k]
-                  k += 1
-                end
-                # strip common leading whitespace (squiggly heredoc)
-                code = dedent(body_lines)
+                code, k = heredoc_body(lines, k, heredoc_lang)
                 lang = heredoc_lang.downcase == "ruby" ? "ruby" : heredoc_lang.downcase
 
                 examples << {title: title, code: code, language: lang}
@@ -203,6 +204,18 @@ def extract_kwarg(str, key)
           end
         end
 
+        # Collects a squiggly-heredoc body starting at `start`; returns [dedented code, terminator index].
+        def heredoc_body(lines, start, terminator)
+          k = start
+          body = []
+          while k < lines.length
+            break if lines[k].match?(/^\s*#{Regexp.escape(terminator)}\s*$/)
+            body << lines[k]
+            k += 1
+          end
+          [dedent(body), k]
+        end
+
         def dedent(lines)
           return "" if lines.empty?
           # find minimum indentation (ignore blank lines)