diff --git a/AGENTS.md b/AGENTS.md
index a6faa28..9fde436 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,7 +76,10 @@
- Do not include React-only APIs such as `asChild`.
- Do not add "Composition" sections unless they describe stable Basecoat markup.
- Do not add API Reference sections for native/CSS-only components unless there is a real Basecoat API.
+- Structure component docs as: title and preview, `## Usage`, optional `### HTML structure` for stable markup requirements, optional `### JavaScript API` for components with Basecoat JS methods/events/options, then `## Examples`.
+- Keep `Usage` focused on the minimal working snippet and important Basecoat/upstream differences; put variants, states, RTL, and richer patterns under `Examples`.
- Keep snippets minimal and aligned with current behavior.
+- In HTML snippets, keep text-only elements on one line, such as `
Yes. It comes with default styles that matches the other components' aesthetic.
-
-
-
-
-
- Is it animated?
-
-
+
+
+ What are your shipping options?
+
-
Yes. It's animated by default, but you can disable it if you prefer.
+ We offer standard (5-7 days), express (2-3 days), and overnight shipping. Free shipping on international orders.
+
+
+
+
+ What is your return policy?
+
+
+
+ You can return items within 30 days of delivery. Items must be unused and in their original packaging.
+
+
+
+
+ How can I contact customer support?
+
+
+
+ Email support@example.com or use live chat during business hours.
-
## Usage
-Basecoat styles native `` disclosure animations. Use semantic `` and `` markup, then add your own utility classes for the visual treatment.
+
+
```html
-
- Is it accessible?
-
Yes. It uses native disclosure semantics.
-
+
+
```
-The example above show you how to use a small script to create an accordion with a group of `` elements.
+
+
+
+```html
+
+
+
+ Is it accessible?
+
+
+
+ Yes. It uses native disclosure semantics.
+
+
+
+```
+
+
+
+
+Basecoat uses native `` and `` elements for disclosure semantics. The accordion JavaScript only enforces single-item behavior by default and prevents disabled items from toggling. Add `data-multiple` to the root when more than one item can be open at a time.
+
+### HTML structure
+
+
+
<section class="accordion">
+
+ Root accordion container. Add data-multiple to allow multiple open items.
+
+
<details open>
+
+ Accordion item. Use the native open attribute for the default expanded item. Add aria-disabled="true" when an item should not toggle.
+
+
<summary>
+
Accordion trigger. Keep the trigger text visible and add an optional trailing icon.
+
<section>
+
Accordion content. Use any semantic element that fits your content.
+
+
+
+
+
+
+### JavaScript API
+
+Accordion does not expose custom methods or events. Programmatically open or close an item with the native `details.open` boolean.
+
+```js
+document.querySelector("#billing").open = true
+```
+
+## Examples
+
+### Basic
+
+A basic accordion that shows one item at a time. The first item is open by default.
+
+
+
+
+
+ How do I reset my password?
+
+
+
+ Click on 'Forgot Password' on the login page, enter your email address, and we'll send you a link to reset your password. The link will expire in 24 hours.
+
+
+
+
+ Can I change my subscription plan?
+
+
+
+ Yes. You can upgrade or downgrade your plan from the billing settings page.
+
+
+
+
+ What payment methods do you accept?
+
+
+
+ We accept all major credit cards, PayPal, and bank transfers for annual plans.
+
+
+
+
+
+### Multiple
+
+Use `data-multiple` to allow multiple items to be open at the same time.
+
+
+
+
+
+ Notification Settings
+
+
+
+ Manage how you receive notifications. You can enable email alerts for updates or push notifications for mobile devices.
+
+
+
+
+ Privacy & Security
+
+
+
+ Control account security, session history, and privacy preferences.
+
+
+
+
+ Billing & Subscription
+
+
+
+ Review invoices, change plans, and update payment methods.
+
+
+
+
+
+### Disabled
+
+Use `aria-disabled="true"` on an item to disable it.
+
+
+
+
+
+ Can I access my account history?
+
+
+
+ Yes. Your account history is available from the activity page.
+
+
+
+
+ Premium feature information
+
+
+
+ This item is disabled.
+
+
+
+
+ How do I update my email address?
+
+
+
+ Go to account settings, update your email, then confirm the change from your inbox.
+
+
+
+
+
+### Borders
+
+Add horizontal padding to the rows when using a bordered root.
+
+
+
+
+
+ How does billing work?
+
+
+
+ We offer monthly and annual subscription plans. Billing is charged at the beginning of each cycle, and you can cancel anytime. All plans include automatic backups, 24/7 support, and unlimited team members.
+
+
+
+
+ Is my data secure?
+
+
+
+ Data is encrypted in transit and at rest.
+
+
+
+
+ What integrations do you support?
+
+
+
+ We support Slack, GitHub, Google Workspace, and webhooks.
+
+
+
+
+
+### Card
+
+Wrap the accordion in a card for grouped support or billing content.
+
+
+
+
+
Subscription & Billing
+
Common questions about your account, plans, payments and cancellations.
+
+
+
+
+
+ What subscription plans do you offer?
+
+
+
+ We offer three subscription tiers: Starter ($9/month), Professional ($29/month), and Enterprise ($99/month). Each plan includes increasing storage limits, API access, priority support, and team collaboration features.
+
+
+
+
+ How does billing work?
+
+
+
+ Billing is charged at the beginning of each cycle.
+
+
+
+
+ How do I cancel my subscription?
+
+
+
+ Cancel from billing settings. Your plan remains active until the end of the current cycle.
+
+
+
+
+
+
+
+### RTL
+
+Accordion spacing uses logical properties. Set `dir="rtl"` on the accordion or a parent element.
+
+
+
+
+
+ كيف يمكنني إعادة تعيين كلمة المرور؟
+
+
+
+ انقر على 'نسيت كلمة المرور' في صفحة تسجيل الدخول، أدخل عنوان بريدك الإلكتروني، وسنرسل لك رابطا لإعادة تعيين كلمة المرور. سينتهي صلاحية الرابط خلال 24 ساعة.
+
+
+
+
+ هل يمكنني تغيير خطة الاشتراك الخاصة بي؟
+
+
+
+ نعم، يمكنك تغيير الخطة من إعدادات الفوترة.
+
+
+
+
+ ما هي طرق الدفع التي تقبلونها؟
+
+
+
+ نقبل بطاقات الائتمان الرئيسية والتحويلات البنكية.
+
+
+
+
diff --git a/docs/src/components/alert-dialog.mdx b/docs/src/components/alert-dialog.mdx
index 58a6ea9..b743e0c 100644
--- a/docs/src/components/alert-dialog.mdx
+++ b/docs/src/components/alert-dialog.mdx
@@ -1,16 +1,18 @@
# Alert Dialog
+A modal dialog that interrupts the user with important content and expects a response.
+
-
-