Document component argument convention

Positional/named keywords are for component config, **kwargs are
for HTML attributes. Added to CLAUDE.md and README Customization section.

Author: bradgessler

CLAUDE.md

@@ -0,0 +1,46 @@
+# Superform Development Guide
+
+## Component Argument Convention
+
+HTML components follow a strict convention for arguments:
+
+- **Positional/named keyword arguments** are for component configuration (non-HTML concerns)
+- **`**kwargs`** are for HTML attributes that pass through to the rendered element
+
+```ruby
+# field is positional, value: is config, **attributes are HTML
+class Radio < Field
+  def initialize(field, value:, **attributes)
+    super(field, **attributes)
+    @value = value
+  end
+end
+
+# options: and multiple: are config, **attributes are HTML
+class Select < Field
+  def initialize(field, options:, multiple: false, **attributes)
+    super(field, **attributes)
+    @options = options
+    @multiple = multiple
+  end
+end
+```
+
+The Field methods mirror this: config args are explicit, HTML attributes flow through as `**kwargs`.
+
+```ruby
+def radio(value, **attributes)
+  Components::Radio.new(field, value:, **attributes)
+end
+
+def select(*options, multiple: false, **attributes, &)
+  Components::Select.new(field, options:, multiple:, **attributes, &)
+end
+```
+
+## Key Architecture
+
+- **Field** is a data binding object (model, key, value, DOM name) — not HTML
+- **Components** are HTML elements — their kwargs should be HTML attributes
+- **Form** is a Phlex component that contains fields and renders the `<form>` tag
+- Customization is through subclassing, not runtime options

README.md

@@ -165,6 +165,8 @@ This gives you complete control over markup, styling, and component composition
 
 Superforms are built out of [Phlex components](https://www.phlex.fun/html/components/). The method names correspond with the HTML tag, its arguments are attributes, and the blocks are the contents of the tag.
 
+When building custom components, follow this convention: **positional or named keyword arguments** are for component configuration (non-HTML concerns like `value:`, `options:`, `multiple:`), and **`**kwargs`** are for HTML attributes that pass through to the rendered element. This keeps the boundary between component logic and HTML clean.
+
 ```ruby
 # ./app/components/form.rb
 class Components::Form < Superform::Rails::Form