@agent-ui-kit/web-components 0.0.15 → 0.0.17

package/dist/docs/components/agent-prompt.yaml

@@ -84,7 +84,7 @@ examples:
         <aui-textarea placeholder="Ask anything..."></aui-textarea>
         <div data-role="leading">
           <aui-button ghost>
-            <aui-icon name="sparkles"></aui-icon>
+            <aui-icon name="sparkle"></aui-icon>
           </aui-button>
         </div>
       </aui-agent-prompt>

package/dist/docs/components/agent-seeds.yaml

@@ -85,5 +85,5 @@ examples:
       </aui-agent-seeds>
   - description: Conversation starters with icons — used on an empty chat state to help users begin a session with common tasks
     html: |-
-      <aui-agent-seeds options='[{"value":"write-email","label":"Draft an email","icon":"mail"},{"value":"summarize","label":"Summarize a document","icon":"file-text"},{"value":"brainstorm","label":"Brainstorm ideas","icon":"lightbulb"},{"value":"analyze-data","label":"Analyze data","icon":"chart-bar"}]'>
+      <aui-agent-seeds options='[{"value":"write-email","label":"Draft an email","icon":"envelope"},{"value":"summarize","label":"Summarize a document","icon":"file-text"},{"value":"brainstorm","label":"Brainstorm ideas","icon":"lightbulb"},{"value":"analyze-data","label":"Analyze data","icon":"chart-bar"}]'>
       </aui-agent-seeds>

package/dist/docs/components/breadcrumb.yaml

@@ -1,9 +1,9 @@
 name: aui-breadcrumb
 tag: aui-breadcrumb
 type: component
-summary: Breadcrumb navigation trail.
+summary: Breadcrumb navigation trail with auto-current and depth collapse.
 description: |
-  Container for aui-breadcrumb-item children. Sets role="navigation" and aria-label. Separators are rendered via CSS between items.
+  Container for aui-breadcrumb-item children. Sets role="navigation" and aria-label. Separators are rendered via CSS between items using a --_joiner custom property. The last item is automatically marked [current] by JS. When max-depth is set, middle items collapse into an ellipsis trigger that expands on click.
 base: AgentElement
 attributes:
   label:
@@ -17,6 +17,12 @@ attributes:
     default: /
     description: |
       Separator character between breadcrumb items. Common values: "/" "›" "→" "·"
+  max-depth:
+    syntax: key-value
+    type: string
+    default: ""
+    description: |
+      When set, collapses middle items to keep only the first item and the last N items visible. Hidden items are replaced by an ellipsis button that expands them on click.
 a11y:
   role: navigation
   aria:
@@ -36,13 +42,24 @@ tokens:
   - name: --aui-breadcrumb-gap
     default: calc(var(--aui-space) * 2)
     description: Gap between breadcrumb items.
+  - name: --aui-breadcrumb-item-color-current
+    default: var(--aui-ink-strong)
+    description: Color of the current (last) breadcrumb item.
+  - name: --aui-breadcrumb-item-font-weight-current
+    default: var(--aui-font-weight-medium)
+    description: Font weight of the current breadcrumb item.
+behaviors:
+  auto-current: |
+    The last aui-breadcrumb-item child is automatically marked with the [current] attribute by JS. Any manually set [current] attributes on other items are removed.
+  max-depth-collapse: |
+    When max-depth is set and items exceed maxDepth + 1, middle items are hidden and replaced by an ellipsis button. Clicking the ellipsis expands all hidden items.
 examples:
   - description: Typical three-level breadcrumb trail
     html: |-
       <aui-breadcrumb>
         <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/settings">Settings</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>Profile</aui-breadcrumb-item>
+        <aui-breadcrumb-item >Profile</aui-breadcrumb-item>
       </aui-breadcrumb>
   - description: Deep breadcrumb trail with four levels
     html: |-
@@ -50,14 +67,14 @@ examples:
         <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/products">Products</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/products/widgets">Widgets</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>Deluxe Widget</aui-breadcrumb-item>
+        <aui-breadcrumb-item >Deluxe Widget</aui-breadcrumb-item>
       </aui-breadcrumb>
   - description: Custom joiner character (›)
     html: |-
       <aui-breadcrumb joiner="›">
         <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/docs">Docs</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>API</aui-breadcrumb-item>
+        <aui-breadcrumb-item >API</aui-breadcrumb-item>
       </aui-breadcrumb>
   - description: Deep breadcrumb trail with five levels
     html: |-
@@ -67,7 +84,7 @@ examples:
         <aui-breadcrumb-item href="/workspace/projects">Projects</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/workspace/projects/agent-ui">Agent UI</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/workspace/projects/agent-ui/components">Components</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>Breadcrumb</aui-breadcrumb-item>
+        <aui-breadcrumb-item >Breadcrumb</aui-breadcrumb-item>
       </aui-breadcrumb>
   - description: Breadcrumb items with leading icons
     html: |-
@@ -91,7 +108,7 @@ examples:
         <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/blog">Blog</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/blog/2026">2026</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>How to build a design system</aui-breadcrumb-item>
+        <aui-breadcrumb-item >How to build a design system</aui-breadcrumb-item>
       </aui-breadcrumb>
   - description: Deep breadcrumb with arrow joiner and six levels
     html: |-
@@ -101,5 +118,15 @@ examples:
         <aui-breadcrumb-item href="/admin/users">Users</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/admin/users/roles">Roles</aui-breadcrumb-item>
         <aui-breadcrumb-item href="/admin/users/roles/editor">Editor</aui-breadcrumb-item>
-        <aui-breadcrumb-item current>Permissions</aui-breadcrumb-item>
+        <aui-breadcrumb-item>Permissions</aui-breadcrumb-item>
+      </aui-breadcrumb>
+  - description: max-depth="2" collapses middle items into ellipsis (click to expand)
+    html: |-
+      <aui-breadcrumb max-depth="2">
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/workspace">Workspace</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/workspace/projects">Projects</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/workspace/projects/agent-ui">Agent UI</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/workspace/projects/agent-ui/components">Components</aui-breadcrumb-item>
+        <aui-breadcrumb-item>Breadcrumb</aui-breadcrumb-item>
       </aui-breadcrumb>

package/dist/docs/components/button.yaml

@@ -17,8 +17,9 @@ presentational:
       - md
       - lg
       - xl
+      - fill
     description: |
-      Controls dimensions, typography, icon size, and spacing simultaneously. Swaps 7 tokens at once.
+      Controls dimensions, typography, icon size, and spacing simultaneously. Swaps 7 tokens at once. The special "fill" value stretches the button to 100% width and height of its parent cell with no minimum constraints. Combine with hide-label and icon-size to create game board cells (e.g. aui-button size="fill" icon-size="half" hide-label label="X" icon-leading="x").
   radius:
     syntax: boolean
     exclusive: true
@@ -148,7 +149,17 @@ modifiers:
   hide-label:
     syntax: boolean
     description: |
-      Hides the label text and collapses the button to icon-only. Square button sized to --aui-size. Removes inline padding. Use with a slotted icon, icon-leading, or the icon attribute.
+      Hides the label text and collapses the button to icon-only. Square button sized to --aui-size with width/height = var(--aui-size) and padding: 0. Use with a slotted icon, icon-leading, or the icon attribute. Auto-detected when no label attribute and no child text nodes are present. When combined with size="fill", the button stretches to fill its grid cell while hiding the label — used for game board cells (tic-tac-toe, battleship, connect-four) where the button fills a square grid cell and shows only an icon or nothing.
+  icon-size:
+    syntax: key-value
+    values:
+      - half
+      - sm
+      - md
+      - lg
+      - full
+    description: |
+      Percentage-based icon sizing within fill-mode buttons (size="fill"). Maps to 50%, 62.5%, 75%, 87.5%, 100% respectively.
   text:
     syntax: key-value
     values:
@@ -338,6 +349,7 @@ use-cases:
   - Form submit/reset triggers.
   - Buttons with text adornments (e.g. "AI" badge via text-leading).
   - Resize-responsive buttons that collapse adornments as space shrinks.
+  - Game board cells using size="fill" + hide-label inside aui-grid square (tic-tac-toe, battleship, connect-four).
 examples:
   - description: Text only
     html: <aui-button>Default</aui-button>

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

@@ -29,8 +29,9 @@ attributes:
   format:
     syntax: key-value
     type: string
-    default: YYYY-MM-DD
-    description: Display format for the selected date (e.g. MM/DD/YYYY).
+    default: medium
+    description: |
+      Display format for the selected date. Named presets use Intl.DateTimeFormat: "long" (March 21, 2026), "medium" (Mar 21, 2026), "short" (03/21/2026). Token-based formats also supported: YYYY-MM-DD, MM/DD/YYYY, etc.
 modifiers:
   disabled:
     syntax: boolean

package/dist/docs/components/chip.yaml

@@ -101,7 +101,7 @@ examples:
   - description: Chip with leading icon
     html: |-
       <aui-chip>
-        <aui-icon name="tag" size="xs"></aui-icon>
+        <aui-icon name="star" size="xs"></aui-icon>
         Label
       </aui-chip>
 

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

@@ -92,13 +92,39 @@ composition:
     - any
   children: []
 examples:
-  - description: Basic color picker with initial blue value (hex input)
+  - description: Basic color picker with hex input (blue)
     html: <aui-color-picker value="#3b82f6"></aui-color-picker>
   - description: Color picker with OKLCH input
-    html: <aui-color-picker value="oklch(0.65 0.2 250)"></aui-color-picker>
-  - description: Color picker with alpha transparency slider
-    html: <aui-color-picker value="oklch(0.65 0.2 15 / 0.8)" alpha></aui-color-picker>
-  - description: Color picker with hex format output
-    html: <aui-color-picker value="#10b981" format="hex"></aui-color-picker>
+    html: |-
+      <aui-color-picker value="oklch(0.65 0.2 250)"></aui-color-picker>
+
+      <!-- ===============================================================
+           ALPHA
+           =============================================================== -->
+  - description: Color picker with alpha slider row visible
+    html: |-
+      <aui-color-picker value="oklch(0.65 0.2 15 / 0.8)" alpha></aui-color-picker>
+
+      <!-- ===============================================================
+           HEX OUTPUT FORMAT
+           =============================================================== -->
+  - description: Color picker serializing value as hex
+    html: |-
+      <aui-color-picker value="#10b981" format="hex"></aui-color-picker>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
   - description: Disabled color picker
-    html: <aui-color-picker value="#10b981" disabled></aui-color-picker>
+    html: |-
+      <aui-color-picker value="#10b981" disabled></aui-color-picker>
+
+      <!-- ===============================================================
+           MULTIPLE PICKERS
+           =============================================================== -->
+  - description: Two pickers side by side for comparison
+    html: |-
+      <div style="display: flex; gap: 2rem;">
+        <aui-color-picker value="oklch(0.7 0.25 145)"></aui-color-picker>
+        <aui-color-picker value="oklch(0.55 0.22 300)" alpha></aui-color-picker>
+      </div>

package/dist/docs/components/color-slider.yaml

@@ -131,7 +131,7 @@ examples:
            =============================================================== -->
   - description: Full-width hue slider
     html: |-
-      <aui-color-slider channel="hue" value="200" lightness="0.65" chroma="0.15" style="width: 100%;"></aui-color-slider>
+      <aui-color-slider channel="hue" value="200" lightness="0.65" chroma="0.15" width="full"></aui-color-slider>
 
       <!-- ===============================================================
            DISABLED
@@ -143,11 +143,11 @@ examples:
       <!-- ===============================================================
            GROUP -- all channels together
            =============================================================== -->
-  - description: All four channel sliders together
+  - description: All four OKLCH channel sliders together
     html: |-
-      <aui-stack gap="3">
-        <aui-color-slider channel="hue" value="250" lightness="0.65" chroma="0.2" style="width: 100%;"></aui-color-slider>
-        <aui-color-slider channel="chroma" value="0.2" hue="250" lightness="0.65" style="width: 100%;"></aui-color-slider>
-        <aui-color-slider channel="lightness" value="0.65" hue="250" chroma="0.2" style="width: 100%;"></aui-color-slider>
-        <aui-color-slider channel="alpha" value="1" hue="250" chroma="0.2" lightness="0.65" style="width: 100%;"></aui-color-slider>
+      <aui-stack gap="3" style="min-width: 20rem;">
+        <aui-color-slider channel="hue" value="250" lightness="0.65" chroma="0.2" width="full"></aui-color-slider>
+        <aui-color-slider channel="chroma" value="0.2" hue="250" lightness="0.65" width="full"></aui-color-slider>
+        <aui-color-slider channel="lightness" value="0.65" hue="250" chroma="0.2" width="full"></aui-color-slider>
+        <aui-color-slider channel="alpha" value="1" hue="250" chroma="0.2" lightness="0.65" width="full"></aui-color-slider>
       </aui-stack>

package/dist/docs/components/container.yaml

@@ -56,9 +56,10 @@ attributes:
       - widget
       - card
       - panel
+      - popover
     default: card
     description: |
-      Sets the padding and gap scale for all children. widget: 0.75rem (compact, 1/6–1/4 page). card: 1rem (default, 1/4–1/3 page). panel: 1.75rem (spacious, 1/3–3/4 page, modals).
+      Sets the padding and gap scale for all children. widget: 0.75rem (compact). card: 1rem (default). panel: 1.25rem (spacious). popover: 0.75rem with modal background, shadow, border, and auto-computed border-radius (radius + padding) so inner content corners don't clip.
   href:
     syntax: key-value
     type: string

package/dist/docs/components/heading.yaml

@@ -34,6 +34,10 @@ examples:
   - description: Full size scale
     html: |-
       <aui-stack gap="3">
+        <aui-heading size="6xl">Heading 6XL — Hero</aui-heading>
+        <aui-heading size="5xl">Heading 5XL — Display</aui-heading>
+        <aui-heading size="4xl">Heading 4XL — Landing</aui-heading>
+        <aui-heading size="3xl">Heading 3XL — Page hero</aui-heading>
         <aui-heading size="2xl">Heading 2XL — Page title</aui-heading>
         <aui-heading size="xl">Heading XL — Section title</aui-heading>
         <aui-heading size="lg">Heading LG — Card title</aui-heading>

package/dist/docs/components/index.yaml

@@ -49,10 +49,20 @@ aui-radio-group:
   uses: [plan selection in pricing, payment method chooser, frequency toggle in settings]
   children: [aui-radio]
 
+aui-checkbox-group:
+  summary: Container that coordinates checkbox multi-selection with min/max constraints.
+  uses: [multi-select form fields, feature toggles, preference checkboxes, filter groups]
+  children: [aui-checkbox]
+
 aui-field:
   summary: Form field wrapper with label, description, and error.
   uses: [labeled login input, settings form row, registration field with validation, inline error display]
-  children: [aui-input, aui-textarea, aui-select, aui-checkbox, aui-switch, aui-radio-group]
+  children: [aui-input, aui-textarea, aui-select, aui-checkbox, aui-switch, aui-radio-group, aui-checkbox-group]
+
+aui-form:
+  summary: Form coordinator with validation and structured submit events.
+  uses: [settings forms, registration pages, profile editors, search forms, inline data entry]
+  children: [aui-field, aui-button, aui-checkbox-group, aui-fieldset]
 
 aui-tooltip:
   summary: Hover/focus tooltip with popover-based positioning.

package/dist/docs/components/input.yaml

@@ -268,16 +268,9 @@ examples:
   - description: Read-only input with dashed border
     html: <aui-input value="Read only" readonly></aui-input>
   - description: Input with leading icon
-    html: |-
-      <aui-input placeholder="Search">
-        <span slot="leading">🔍</span>
-      </aui-input>
+    html: <aui-input placeholder="Search" icon-leading="magnifying-glass"></aui-input>
   - description: Input with leading and trailing icons
-    html: |-
-      <aui-input type="email" placeholder="Email">
-        <span slot="leading">✉</span>
-        <span slot="trailing">✓</span>
-      </aui-input>
+    html: <aui-input type="email" placeholder="Email" icon-leading="envelope" icon-trailing="check"></aui-input>
   - description: Input inside a labeled field
     html: |-
       <aui-field label="Email" required>
@@ -299,3 +292,11 @@ examples:
       <aui-field label="Filter">
         <aui-input type="search" placeholder="Filter items..." width="full"></aui-input>
       </aui-field>
+  - description: Input with text prefix (currency)
+    html: <aui-input placeholder="0.00" prefix="$"></aui-input>
+  - description: Input with text suffix (unit)
+    html: <aui-input placeholder="Weight" suffix="kg"></aui-input>
+  - description: Input with both prefix and suffix (URL)
+    html: <aui-input placeholder="example" prefix="https://" suffix=".com"></aui-input>
+  - description: Number input with stepper
+    html: <aui-input type="number" value="5" min="0" max="100" step="1"></aui-input>

package/dist/docs/components/meter.yaml

@@ -56,23 +56,46 @@ tokens:
   shape:
     - --aui-meter-radius
 examples:
-  - description: Default accent meter at 45%
-    html: <aui-meter value="45"></aui-meter>
-  - description: Warning meter at 75%
-    html: <aui-meter value="75" warning></aui-meter>
-  - description: Danger meter at 95%
-    html: <aui-meter value="95" danger></aui-meter>
-  - description: Three sizes with different values
+  - description: Labeled meters with values
+    html: |-
+      <aui-stack gap="4">
+        <aui-stack gap="2">
+          <aui-stack direction="row" gap="2" align-items="center">
+            <aui-text size="sm" spacer>CPU Usage</aui-text>
+            <aui-text size="sm" strong>45%</aui-text>
+          </aui-stack>
+          <aui-meter value="45" size="lg"></aui-meter>
+        </aui-stack>
+
+        <aui-stack gap="2">
+          <aui-stack direction="row" gap="2" align-items="center">
+            <aui-text size="sm" spacer>Memory</aui-text>
+            <aui-text size="sm" strong>75%</aui-text>
+          </aui-stack>
+          <aui-meter value="75" size="lg" warning></aui-meter>
+        </aui-stack>
+
+        <aui-stack gap="2">
+          <aui-stack direction="row" gap="2" align-items="center">
+            <aui-text size="sm" spacer>Disk</aui-text>
+            <aui-text size="sm" strong>95%</aui-text>
+          </aui-stack>
+          <aui-meter value="95" size="lg" danger></aui-meter>
+        </aui-stack>
+      </aui-stack>
+  - description: Size comparison
     html: |-
       <aui-stack gap="3">
-        <aui-meter value="30" size="sm"></aui-meter>
+        <aui-meter value="60" size="sm" success></aui-meter>
         <aui-meter value="60"></aui-meter>
-        <aui-meter value="85" size="lg" warning></aui-meter>
+        <aui-meter value="60" size="lg"></aui-meter>
       </aui-stack>
-  - description: Meter with context labels in a row
+  - description: Custom range (min/max)
     html: |-
-      <aui-stack direction="row" gap="2" align-items="center">
-        <aui-text size="xs" muted>Disk usage</aui-text>
-        <aui-meter value="82" warning style="flex: 1"></aui-meter>
-        <aui-text size="xs" muted>82%</aui-text>
+      <aui-stack gap="2">
+        <aui-stack direction="row" gap="2" align-items="center">
+          <aui-text size="sm" spacer>Temperature</aui-text>
+          <aui-text size="sm" strong>72°F</aui-text>
+        </aui-stack>
+        <aui-meter value="72" min="32" max="120" size="lg"></aui-meter>
       </aui-stack>

package/dist/docs/components/nav-item.yaml

@@ -62,20 +62,20 @@ examples:
   - description: Nav item with leading icon
     html: |-
       <aui-nav-item>
-        <aui-icon name="home"></aui-icon>
+        <aui-icon name="house"></aui-icon>
         Dashboard
       </aui-nav-item>
   - description: Active nav item with icon
     html: |-
       <aui-nav-item active>
-        <aui-icon name="settings"></aui-icon>
+        <aui-icon name="gear"></aui-icon>
         Settings
       </aui-nav-item>
   - description: Navigation list with mixed states
     html: |-
       <aui-stack gap="1">
         <aui-nav-item active>
-          <aui-icon name="home"></aui-icon>
+          <aui-icon name="house"></aui-icon>
           Dashboard
         </aui-nav-item>
         <aui-nav-item>
@@ -83,22 +83,22 @@ examples:
           Documents
         </aui-nav-item>
         <aui-nav-item>
-          <aui-icon name="users"></aui-icon>
+          <aui-icon name="users-three"></aui-icon>
           Team
         </aui-nav-item>
         <aui-nav-item>
-          <aui-icon name="settings"></aui-icon>
+          <aui-icon name="gear"></aui-icon>
           Settings
         </aui-nav-item>
         <aui-nav-item disabled>
-          <aui-icon name="lock"></aui-icon>
+          <aui-icon name="warning"></aui-icon>
           Admin
         </aui-nav-item>
       </aui-stack>
   - description: Nav item with trailing badge
     html: |-
       <aui-nav-item>
-        <aui-icon name="inbox"></aui-icon>
+        <aui-icon name="envelope"></aui-icon>
         Inbox
         <aui-badge>12</aui-badge>
       </aui-nav-item>

package/dist/docs/components/stat.yaml

@@ -0,0 +1,164 @@
+name: aui-stat
+tag: aui-stat
+type: component
+summary: Stat display with label, value, trend indicator, and optional animation.
+description: |
+  Displays a metric with label, formatted value, and optional trend arrow. Stamps three internal spans: [data-stat-label], [data-stat-value], [data-stat-change]. Supports count-up and character-scramble animations with configurable duration. Value formatting preserves prefixes, suffixes, commas, and decimals. Intent attributes (accent, success, warning, danger) color the value.
+base: AgentElement
+presentational:
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values:
+      - accent
+      - success
+      - warning
+      - danger
+    description: |
+      Colors the stat value text. Default is ink-strong (neutral).
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Stat label text shown above the value.
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: |
+      Formatted stat value (e.g. "$1,234.56", "89%", "12.4K"). Preserves prefix, suffix, commas, and decimals during animation.
+  trend:
+    syntax: key-value
+    type: enum
+    values:
+      - up
+      - down
+      - neutral
+    default: ""
+    description: |
+      Trend direction. "up" shows a green up-arrow, "down" shows a red down-arrow, "neutral" shows muted text with no arrow.
+  change:
+    syntax: key-value
+    type: string
+    default: ""
+    description: |
+      Change description text (e.g. "+12.5%", "-3 units"). Displayed next to the trend arrow.
+  animate-count:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: |
+      Enables count-up animation from animate-count-start to the target value. Uses ease-out cubic easing.
+  animate-count-start:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: |
+      Starting value for count-up animation. Can include prefix/suffix matching the value format.
+  animate-scramble:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: |
+      Enables character-scramble animation. Digit characters randomize and resolve left-to-right. Non-digit characters pass through unchanged.
+  duration-ms:
+    syntax: key-value
+    type: string
+    default: "2000"
+    description: |
+      Animation duration in milliseconds for both animate-count and animate-scramble.
+content:
+  model: block
+  accepts:
+    - aui-sparkline
+  required: false
+  description: |
+    Optional aui-sparkline child for inline chart below the stat value.
+composition:
+  parents:
+    - aui-container
+    - aui-inset
+    - aui-stack
+    - aui-grid
+    - div
+  children:
+    - aui-sparkline
+  context: |
+    Typically placed inside aui-container kind="widget" for KPI cards. Multiple stats in a grid for dashboard layouts.
+tokens:
+  - name: font-size (label)
+    default: var(--aui-font-xs)
+    description: Label font size.
+  - name: font-size (value)
+    default: var(--aui-font-2xl)
+    description: Value font size.
+  - name: font-size (change)
+    default: var(--aui-font-xs)
+    description: Change text font size.
+examples:
+  - description: Basic stat with label and value
+    html: |-
+      <aui-stat label="Total Users" value="12,450"></aui-stat>
+
+      <!-- ===============================================================
+           TREND -- up/down/neutral
+           =============================================================== -->
+  - description: Upward trend stat
+    html: <aui-stat label="Revenue" value="$48,200" trend="up" change="+12.5%"></aui-stat>
+  - description: Downward trend stat
+    html: <aui-stat label="Churn Rate" value="3.2%" trend="down" change="-0.8%"></aui-stat>
+  - description: Neutral trend stat
+    html: |-
+      <aui-stat label="Active Sessions" value="1,234" trend="neutral" change="0%"></aui-stat>
+
+      <!-- ===============================================================
+           INTENT VARIANTS
+           =============================================================== -->
+  - description: Success intent stat
+    html: <aui-stat label="Uptime" value="99.9%" success trend="up" change="+0.1%"></aui-stat>
+  - description: Danger intent stat
+    html: |-
+      <aui-stat label="Error Rate" value="4.7%" danger trend="up" change="+2.1%"></aui-stat>
+
+      <!-- ===============================================================
+           WITH SPARKLINE
+           =============================================================== -->
+  - description: Stat with inline sparkline
+    html: |-
+      <aui-stat label="Weekly Revenue" value="$12,450" trend="up" change="+12%">
+        <aui-sparkline values="3,5,4,7,6,8,9,11" color="1"></aui-sparkline>
+      </aui-stat>
+
+      <!-- ===============================================================
+           GROUP -- row of stats
+           =============================================================== -->
+  - description: Row of KPI stats in a grid
+    html: |-
+      <aui-grid cols="4" gap="4">
+        <aui-stat label="Revenue" value="$48,200" trend="up" change="+12.5%"></aui-stat>
+        <aui-stat label="Users" value="12,450" trend="up" change="+8.2%"></aui-stat>
+        <aui-stat label="Orders" value="1,234" trend="down" change="-3.1%"></aui-stat>
+        <aui-stat label="Conversion" value="3.2%" trend="neutral" change="0%"></aui-stat>
+      </aui-grid>
+
+      <!-- ===============================================================
+           ANIMATE COUNT -- smooth count-up animation
+           =============================================================== -->
+  - description: Count-up from 0 to $48,200 over 2s
+    html: <aui-stat label="Revenue" value="$48,200" animate-count></aui-stat>
+  - description: Count-up from 5,000 to 12,450 over 3s
+    html: <aui-stat label="Users" value="12,450" animate-count animate-count-start="5000" duration-ms="3000" trend="up" change="+8.2%"></aui-stat>
+  - description: Count-up percentage
+    html: |-
+      <aui-stat label="Conversion" value="87.3%" animate-count duration-ms="1500"></aui-stat>
+
+      <!-- ===============================================================
+           ANIMATE SCRAMBLE -- character scramble reveal
+           =============================================================== -->
+  - description: Scramble reveal of a revenue figure
+    html: <aui-stat label="Total Sales" value="$2,847,200" animate-scramble duration-ms="2500"></aui-stat>
+  - description: Scramble reveal of a percentage
+    html: <aui-stat label="Accuracy" value="99.7%" animate-scramble></aui-stat>