@agent-ui-kit/web-components 0.0.8 → 0.0.14

package/dist/docs/blocks/survey-card.yaml

@@ -2,12 +2,12 @@ name: survey-card
 type: block
 summary: Survey question card with checkbox options and submit action.
 description: >
-  A card presenting a multiple-choice survey question. Each option is
-  a labeled checkbox that users can toggle. Includes a submit button
-  so the card feels complete and actionable — not just a floating
-  question. Useful for onboarding flows, feedback, or preference selection.
+  A card presenting a multiple-choice survey question. Checkbox options
+  are grouped in an aui-fieldset legend="Sources" (borderless) for
+  semantic grouping. Footer uses aui-button-group for skip/continue
+  actions. Useful for onboarding flows, feedback, or preference selection.
 
-components: [aui-container, aui-header, aui-content, aui-footer, aui-inset, aui-stack, aui-heading, aui-text, aui-field, aui-checkbox, aui-button]
+components: [aui-container, aui-header, aui-content, aui-footer, aui-inset, aui-stack, aui-heading, aui-text, aui-field, aui-fieldset, aui-checkbox, aui-button, aui-button-group]
 kind: card
 
 examples:
@@ -23,7 +23,7 @@ examples:
         </aui-header>
         <aui-content>
           <aui-inset>
-            <aui-stack gap="3">
+            <aui-fieldset legend="Sources" borderless>
               <aui-field>
                 <aui-checkbox>Social Media</aui-checkbox>
               </aui-field>
@@ -39,14 +39,14 @@ examples:
               <aui-field>
                 <aui-checkbox>Other</aui-checkbox>
               </aui-field>
-            </aui-stack>
+            </aui-fieldset>
           </aui-inset>
         </aui-content>
         <aui-footer>
-          <aui-stack direction="row" gap="2">
+          <aui-button-group>
             <aui-button scrim grow="1">Skip</aui-button>
             <aui-button primary grow="1">Continue</aui-button>
-          </aui-stack>
+          </aui-button-group>
         </aui-footer>
       </aui-container>
     description: Survey with checkbox options, header/content/footer structure, and skip/continue actions.

package/dist/docs/blocks/tabbed-panel.yaml

@@ -35,7 +35,7 @@ examples:
           <aui-inset>
             <aui-stack gap="6" align-items="center" text="center" style="padding: 1.5rem 0;">
               <div style="width: 6rem; height: 6rem; border-radius: var(--aui-radius); background: linear-gradient(135deg, var(--aui-control) 0%, var(--aui-panel) 100%); display: flex; align-items: center; justify-content: center;">
-                <aui-icon name="gear" style="--aui-icon-size: 3rem;" muted></aui-icon>
+                <aui-icon name="gear" size="3xl" muted></aui-icon>
               </div>
               <aui-stack gap="1">
                 <aui-heading size="md">No codespaces</aui-heading>

package/dist/docs/blocks/team-empty.yaml

@@ -3,25 +3,17 @@ type: block
 summary: Empty state for team member lists with invite action.
 description: >
   An inviting empty state shown when a team or project has no members
-  yet. Features a large user icon in a contained avatar, a clear
-  heading, helpful description, and an invite action button. Simpler
-  than the generic empty-state block — purpose-built for team contexts.
+  yet. Uses aui-empty-state with a users icon, heading, description,
+  and an invite action button. Purpose-built for team contexts.
 
-components: [aui-container, aui-inset, aui-stack, aui-heading, aui-text, aui-avatar, aui-icon, aui-button]
+components: [aui-container, aui-empty-state, aui-button]
 kind: card
 
 examples:
   - html: |
       <aui-container kind="card" bordered max-width="prose">
-        <aui-inset>
-          <aui-stack gap="4" align-items="center" text="center">
-            <aui-avatar size="xl" square><aui-icon name="user"></aui-icon></aui-avatar>
-            <aui-stack gap="1">
-              <aui-heading size="lg">No Team Members</aui-heading>
-              <aui-text muted size="sm">Invite your team to collaborate on this project.</aui-text>
-            </aui-stack>
-            <aui-button primary accent>Invite Members</aui-button>
-          </aui-stack>
-        </aui-inset>
+        <aui-empty-state icon="users-three" heading="No Team Members" description="Invite your team to collaborate on this project.">
+          <aui-button accent>Invite Members</aui-button>
+        </aui-empty-state>
       </aui-container>
     description: Team empty state with icon, heading, description, and invite button.

package/dist/docs/blocks/usage-billing.yaml

@@ -1,14 +1,13 @@
 name: usage-billing
 type: block
-summary: Billing usage panel with SVG progress rings and cost breakdown.
+summary: Billing usage panel with progress circle rings and cost breakdown.
 description: >
   A card showing current billing cycle usage broken down by service line item.
-  Each row has a circular SVG progress ring showing utilization, a service
-  name, and a cost or usage/limit value. Rings use stroke-dashoffset to render
-  accurate fill levels. Use for billing dashboards, plan overviews, or
-  resource monitoring.
+  Each row has an aui-progress-circle size="sm" showing utilization, a service
+  name, and a cost or usage/limit value. Use for billing dashboards, plan
+  overviews, or resource monitoring.
 
-components: [aui-container, aui-header, aui-content, aui-inset, aui-stack, aui-heading, aui-text, aui-divider]
+components: [aui-container, aui-header, aui-content, aui-inset, aui-stack, aui-heading, aui-text, aui-divider, aui-progress-circle]
 kind: card
 
 examples:
@@ -23,11 +22,7 @@ examples:
 
               <!-- Edge Requests: 91% -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-1);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="4.5" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="91" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>Edge Requests</aui-text>
                 <aui-text size="sm" weight="medium">$1.83K</aui-text>
               </aui-stack>
@@ -35,11 +30,7 @@ examples:
 
               <!-- Fast Data Transfer: 73% -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-2);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="13.6" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="73" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>Fast Data Transfer</aui-text>
                 <aui-text size="sm" weight="medium">$952.51</aui-text>
               </aui-stack>
@@ -47,11 +38,7 @@ examples:
 
               <!-- Monitoring Data Points: 58% -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-3);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="21.1" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="58" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>Monitoring Data Points</aui-text>
                 <aui-text size="sm" weight="medium">$901.20</aui-text>
               </aui-stack>
@@ -59,11 +46,7 @@ examples:
 
               <!-- Web Analytics Events: 42% -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-4);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="29.2" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="42" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>Web Analytics Events</aui-text>
                 <aui-text size="sm" weight="medium">$603.71</aui-text>
               </aui-stack>
@@ -71,11 +54,7 @@ examples:
 
               <!-- ISR Writes: 26% (524K / 2M) -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-5);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="37.2" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="26" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>ISR Writes</aui-text>
                 <aui-text muted size="sm">524.52K / 2M</aui-text>
               </aui-stack>
@@ -83,11 +62,7 @@ examples:
 
               <!-- Function Duration: 0.5% (5.11 / 1K GB Hrs) -->
               <aui-stack direction="row" gap="2" align-items="center" style="padding: 0.625rem 0;">
-                <svg width="20" height="20" viewBox="0 0 20 20" style="flex-shrink: 0;" transform="rotate(-90)">
-                  <circle cx="10" cy="10" r="8" fill="none" stroke="var(--aui-border-muted)" stroke-width="2"/>
-                  <circle cx="10" cy="10" r="8" fill="none" style="stroke: var(--aui-chart-6);" stroke-width="2"
-                    stroke-dasharray="50.3" stroke-dashoffset="50" stroke-linecap="round"/>
-                </svg>
+                <aui-progress-circle value="1" size="sm"></aui-progress-circle>
                 <aui-text size="sm" spacer>Function Duration</aui-text>
                 <aui-text muted size="sm">5.11 GB Hrs / 1K GB Hrs</aui-text>
               </aui-stack>
@@ -96,4 +71,4 @@ examples:
           </aui-inset>
         </aui-content>
       </aui-container>
-    description: Six billing line items with SVG progress rings at varied fill levels across the color spectrum.
+    description: Six billing line items with aui-progress-circle size="sm" at varied fill levels.

package/dist/docs/components/alert.yaml

@@ -0,0 +1,79 @@
+name: aui-alert
+tag: aui-alert
+type: component
+summary: Contextual banner for status messages.
+description: >
+  Inline alert banner with intent-based coloring via boolean
+  attributes (info, success, warning, danger). Left border accent
+  stripe signals severity. Supports rich content including
+  headings and paragraphs. Optional dismissable behavior via JS.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: info
+    values: [accent, info, success, warning, danger]
+    description: Visual intent controlling background tint and border accent color.
+
+# ── Modifiers ─────────────────────────────────────────────
+
+modifiers:
+  dismissable:
+    syntax: boolean
+    description: >
+      Shows a close button area. JS removes the element on click.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: flow
+  accepts: [text, strong, p, aui-text, aui-link]
+  required: true
+  description: >
+    Message content. Can be plain text or rich HTML with
+    headings and paragraphs for multi-line alerts.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [text, strong, p, aui-text, aui-link]
+    required: true
+    description: Alert message content.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  spacing:
+    - --aui-alert-gap
+    - --aui-alert-padding-block
+    - --aui-alert-padding-inline
+  color:
+    - --aui-alert-background
+    - --aui-alert-border-color
+  typography:
+    - --aui-alert-font-size
+  shape:
+    - --aui-alert-radius
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-alert>Your session will expire in 5 minutes.</aui-alert>
+    description: Default info alert.
+
+  - html: <aui-alert success>Operation completed successfully.</aui-alert>
+    description: Success alert.
+
+  - html: |
+      <aui-alert danger>
+        <strong>Deployment failed</strong>
+        <p>Build step 3 returned exit code 1. Check logs for details.</p>
+      </aui-alert>
+    description: Rich content danger alert.

package/dist/docs/components/avatar-group.yaml

@@ -0,0 +1,86 @@
+name: aui-avatar-group
+tag: aui-avatar-group
+type: component
+summary: Overlapping avatar stack with automatic overflow counter.
+description: >
+  Displays child aui-avatar elements in an overlapping row with
+  descending z-index. When the max attribute is set and children
+  exceed that count, excess avatars are hidden and a +N counter
+  is stamped. Size attribute propagates to child avatars.
+
+base: AgentElement
+
+# -- Component attributes ------------------------------------------
+
+attributes:
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Maximum visible avatars. Remaining are hidden and a +N
+      overflow counter is shown.
+
+  size:
+    syntax: key-value
+    type: string
+    default: ""
+    values: [xs, sm, lg]
+    description: >
+      Passed through to child aui-avatar elements for consistent
+      sizing across the group.
+
+# -- Content model -------------------------------------------------
+
+content:
+  model: block
+  accepts: [aui-avatar]
+  required: true
+  description: >
+    One or more aui-avatar children. Order determines stacking
+    (first avatar on top, highest z-index).
+
+# -- Slots ---------------------------------------------------------
+
+slots:
+  default:
+    accepts: [aui-avatar]
+    required: true
+    description: Avatar children to display in the overlapping stack.
+
+# -- Composition ---------------------------------------------------
+
+composition:
+  parents: [aui-stack, aui-header, aui-footer, div, span]
+  children: [aui-avatar]
+  context: >
+    Inline-flex element. Use inside headers, cards, list items,
+    or stacks. Commonly paired with team/contributor displays.
+
+# -- Examples ------------------------------------------------------
+
+examples:
+  - html: |
+      <aui-avatar-group>
+        <aui-avatar>A</aui-avatar>
+        <aui-avatar>B</aui-avatar>
+        <aui-avatar>C</aui-avatar>
+      </aui-avatar-group>
+    description: Basic avatar group showing all avatars.
+
+  - html: |
+      <aui-avatar-group max="3">
+        <aui-avatar>A</aui-avatar>
+        <aui-avatar>B</aui-avatar>
+        <aui-avatar>C</aui-avatar>
+        <aui-avatar>D</aui-avatar>
+        <aui-avatar>E</aui-avatar>
+      </aui-avatar-group>
+    description: Avatar group with max=3 showing +2 overflow.
+
+  - html: |
+      <aui-avatar-group size="sm">
+        <aui-avatar>A</aui-avatar>
+        <aui-avatar>B</aui-avatar>
+      </aui-avatar-group>
+    description: Small size avatars.

package/dist/docs/components/calendar-picker.yaml

@@ -0,0 +1,142 @@
+name: aui-calendar-picker
+tag: aui-calendar-picker
+type: component
+summary: Compound date picker with trigger input and calendar popover.
+description: >
+  Combines a read-only trigger (styled like an input) with a popover
+  containing an aui-calendar for date selection. On date select the
+  popover closes, the trigger updates with a formatted date string,
+  and a change event fires. Supports min/max date constraints and
+  a configurable display format.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Selected date in ISO format (YYYY-MM-DD).
+  placeholder:
+    syntax: key-value
+    type: string
+    default: "Select date"
+    description: Placeholder text shown when no date is selected.
+  min:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Minimum selectable date in ISO format. Dates before this are disabled.
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Maximum selectable date in ISO format. Dates after this are disabled.
+  format:
+    syntax: key-value
+    type: string
+    default: "YYYY-MM-DD"
+    description: Display format for the selected date (e.g. MM/DD/YYYY).
+
+modifiers:
+  disabled:
+    syntax: boolean
+    description: Disables all interaction.
+  open:
+    syntax: boolean
+    description: Whether the calendar popover is currently open.
+
+a11y:
+  role: combobox (trigger)
+  keyboard:
+    Enter: Opens the calendar popover.
+    Space: Opens the calendar popover.
+    ArrowDown: Opens the calendar popover.
+    ArrowUp: Opens the calendar popover.
+    Escape: Closes the calendar popover and returns focus to trigger.
+
+tokens:
+  - name: --aui-calendar-picker-font-family
+    default: var(--aui-font-family)
+    description: Font family for the trigger.
+  - name: --aui-calendar-picker-font-size
+    default: var(--aui-font-size)
+    description: Font size for the trigger.
+  - name: --aui-calendar-picker-font-weight
+    default: var(--aui-control-font-weight)
+    description: Font weight for the trigger.
+  - name: --aui-calendar-picker-color
+    default: var(--aui-ink)
+    description: Text color of the trigger.
+  - name: --aui-calendar-picker-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Background color of the trigger.
+  - name: --aui-calendar-picker-border-color
+    default: var(--aui-stroke)
+    description: Border color of the trigger.
+  - name: --aui-calendar-picker-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the trigger.
+  - name: --aui-calendar-picker-size
+    default: var(--aui-size)
+    description: Height of the trigger.
+  - name: --aui-calendar-picker-padding-inline
+    default: var(--aui-pad-control-inline)
+    description: Inline padding of the trigger.
+  - name: --aui-calendar-picker-gap
+    default: var(--aui-pad-gap-control)
+    description: Gap between trigger elements.
+  - name: --aui-calendar-picker-icon-size
+    default: var(--aui-icon-size)
+    description: Size of the calendar icon and chevron.
+  - name: --aui-calendar-picker-placeholder-color
+    default: var(--aui-ink-placeholder, var(--aui-ink-muted))
+    description: Placeholder text color.
+  - name: --aui-calendar-picker-chevron-color
+    default: var(--aui-ink-muted)
+    description: Color of the calendar icon and chevron.
+  - name: --aui-calendar-picker-dropdown-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background of the calendar dropdown.
+  - name: --aui-calendar-picker-dropdown-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the calendar dropdown.
+  - name: --aui-calendar-picker-dropdown-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the calendar dropdown.
+  - name: --aui-calendar-picker-dropdown-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the calendar dropdown.
+
+events:
+  change:
+    description: Fired when a date is selected. Detail contains { value, date }.
+
+dependencies:
+  - aui-calendar
+
+examples:
+  - html: |
+      <aui-calendar-picker placeholder="Select date"></aui-calendar-picker>
+    description: Default date picker with placeholder.
+
+  - html: |
+      <aui-calendar-picker value="2026-03-15"></aui-calendar-picker>
+    description: Date picker with pre-selected date.
+
+  - html: |
+      <aui-calendar-picker
+        value="2026-03-21"
+        min="2026-01-01"
+        max="2026-12-31"
+        placeholder="Pick a date"
+      ></aui-calendar-picker>
+    description: Date picker with min/max constraints.
+
+  - html: |
+      <aui-calendar-picker value="2026-03-21" format="MM/DD/YYYY"></aui-calendar-picker>
+    description: Date picker with custom display format.
+
+  - html: |
+      <aui-calendar-picker value="2026-03-21" disabled></aui-calendar-picker>
+    description: Disabled date picker.

package/dist/docs/components/calendar-range-picker.yaml

@@ -0,0 +1,139 @@
+name: aui-calendar-range-picker
+tag: aui-calendar-range-picker
+type: component
+summary: Compound date range picker with trigger input and calendar popover.
+description: >
+  Combines a read-only trigger (styled like an input) with a popover
+  containing an aui-calendar in range selection mode. On range commit the
+  popover closes, the trigger updates with "Start -- End" text, and a
+  change event fires with { start, end } detail. Supports min/max date
+  constraints.
+
+base: AgentElement
+
+attributes:
+  start:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Range start date in ISO format (YYYY-MM-DD).
+  end:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Range end date in ISO format (YYYY-MM-DD).
+  placeholder:
+    syntax: key-value
+    type: string
+    default: "Select dates"
+    description: Placeholder text shown when no range is selected.
+  min:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Minimum selectable date in ISO format. Dates before this are disabled.
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Maximum selectable date in ISO format. Dates after this are disabled.
+
+modifiers:
+  disabled:
+    syntax: boolean
+    description: Disables all interaction.
+  open:
+    syntax: boolean
+    description: Whether the calendar popover is currently open.
+
+a11y:
+  role: combobox (trigger)
+  keyboard:
+    Enter: Opens the calendar popover.
+    Space: Opens the calendar popover.
+    ArrowDown: Opens the calendar popover.
+    ArrowUp: Opens the calendar popover.
+    Escape: Closes the calendar popover and returns focus to trigger.
+
+tokens:
+  - name: --aui-calendar-range-picker-font-family
+    default: var(--aui-font-family)
+    description: Font family for the trigger.
+  - name: --aui-calendar-range-picker-font-size
+    default: var(--aui-font-size)
+    description: Font size for the trigger.
+  - name: --aui-calendar-range-picker-font-weight
+    default: var(--aui-control-font-weight)
+    description: Font weight for the trigger.
+  - name: --aui-calendar-range-picker-color
+    default: var(--aui-ink)
+    description: Text color of the trigger.
+  - name: --aui-calendar-range-picker-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Background color of the trigger.
+  - name: --aui-calendar-range-picker-border-color
+    default: var(--aui-stroke)
+    description: Border color of the trigger.
+  - name: --aui-calendar-range-picker-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the trigger.
+  - name: --aui-calendar-range-picker-size
+    default: var(--aui-size)
+    description: Height of the trigger.
+  - name: --aui-calendar-range-picker-padding-inline
+    default: var(--aui-pad-control-inline)
+    description: Inline padding of the trigger.
+  - name: --aui-calendar-range-picker-gap
+    default: var(--aui-pad-gap-control)
+    description: Gap between trigger elements.
+  - name: --aui-calendar-range-picker-icon-size
+    default: var(--aui-icon-size)
+    description: Size of the calendar icon and chevron.
+  - name: --aui-calendar-range-picker-placeholder-color
+    default: var(--aui-ink-placeholder, var(--aui-ink-muted))
+    description: Placeholder text color.
+  - name: --aui-calendar-range-picker-chevron-color
+    default: var(--aui-ink-muted)
+    description: Color of the calendar icon and chevron.
+  - name: --aui-calendar-range-picker-dropdown-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background of the calendar dropdown.
+  - name: --aui-calendar-range-picker-dropdown-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the calendar dropdown.
+  - name: --aui-calendar-range-picker-dropdown-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the calendar dropdown.
+  - name: --aui-calendar-range-picker-dropdown-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the calendar dropdown.
+
+events:
+  change:
+    description: Fired when a range is fully selected. Detail contains { start, end }.
+
+dependencies:
+  - aui-calendar
+
+examples:
+  - html: |
+      <aui-calendar-range-picker placeholder="Select dates"></aui-calendar-range-picker>
+    description: Default range picker with placeholder.
+
+  - html: |
+      <aui-calendar-range-picker start="2026-03-01" end="2026-03-15"></aui-calendar-range-picker>
+    description: Range picker with pre-selected range.
+
+  - html: |
+      <aui-calendar-range-picker
+        start="2026-03-01"
+        end="2026-03-15"
+        min="2026-01-01"
+        max="2026-12-31"
+        placeholder="Pick a range"
+      ></aui-calendar-range-picker>
+    description: Range picker with min/max constraints.
+
+  - html: |
+      <aui-calendar-range-picker start="2026-03-01" end="2026-03-15" disabled></aui-calendar-range-picker>
+    description: Disabled range picker.