# Atelier UI — Full API Reference

> Complete component API for LLM consumption. 28 accessible components for Angular, React, and Vue with consistent prop naming across all frameworks.
> Version 0.1.2 | https://atelier.pieper.io

---

## Quick Start

### Install

  npm install @atelier-ui/angular   # Angular 21+
  npm install @atelier-ui/react     # React 18+
  npm install @atelier-ui/vue       # Vue 3+

### Design tokens (add to global styles)

  @import '@atelier-ui/angular/styles/tokens.css';
  @import '@atelier-ui/react/styles/tokens.css';
  @import '@atelier-ui/vue/styles/tokens.css';

### Framework-specific patterns

  Angular — signal inputs, two-way binding via [(value)], Signal Forms via [formField]
  React   — controlled props + callback (value + onValueChange), hooks for context
  Vue     — v-model:value, props + emits, provide/inject for compound components

---

## Framework Syntax Cheatsheet

Each component's Usage block below uses JSX-like syntax as a lingua franca.
Apply the following transformations for Angular or Vue:

  Construct           JSX / React            Angular                         Vue
  ---------           -------------          ---------------                 --------------
  Tag name            <LlmButton>            <llm-button>                    <LlmButton>
  Static attr         variant="primary"      variant="primary"               variant="primary"
  Bool attr           loading={true}         [loading]="true"                :loading="true"
  Expression          count={items.length}   [count]="items.length"          :count="items.length"
  Event               onClick={save}         (click)="save()"                @click="save"
  Two-way (value)     value + onValueChange  [(value)]="v"                   v-model:value="v"
  Signal Forms        (n/a)                  [formField]="form.email"        (n/a)
  Loop / iteration    {items.map(x => ...)}  @for (x of items; track x.id)   v-for="x in items"
  Conditional         {cond && <X/>}         @if (cond) { <X/> }             v-if="cond"

Import lines are identical across frameworks: adjust the package path.

  import { LlmButton } from '@atelier-ui/angular';
  import { LlmButton } from '@atelier-ui/react';
  import { LlmButton } from '@atelier-ui/vue';

---

## Component API

Each entry lists:
  Props: name | type | default | description
  Then a generic Usage example (apply the Framework Syntax Cheatsheet above).

---

### LlmButton

  A versatile button component with multiple variants and sizes. Supports loading and disabled states.

  Props:
    variant     'primary' | 'secondary' | 'outline' | 'danger'  'primary'  Visual style variant
    size        'sm' | 'md' | 'lg'                              'md'       Size of the button
    disabled    boolean                                         false      Disables the button
    loading     boolean                                         false      Shows a loading spinner, disables interaction
    aria-label  string                                          —          Accessible name. Required for icon-only buttons (no children). React enforces this at compile time via a discriminated union; Angular/Vue warn at runtime in dev mode.

  Usage:
    <LlmButton variant="primary">Primary</LlmButton>
    <LlmButton variant="secondary">Secondary</LlmButton>
    <LlmButton variant="outline">Outline</LlmButton>
    <LlmButton loading={true}>Loading</LlmButton>
    <LlmButton disabled={true}>Disabled</LlmButton>

---

### LlmInput

  A text input field that integrates with Signal Forms. Supports all standard HTML input types, validation states, and error display.

  Props:
    value          string                                                    ''      Controlled value
    onValueChange  (value: string) => void                                   —       Called when the input value changes
    type           'text' | 'email' | 'password' | 'number' | 'tel' | 'url'  'text'  Input type
    placeholder    string                                                    ''      Placeholder text
    disabled       boolean                                                   false   Disables the input
    readonly       boolean                                                   false   Makes the input read-only
    invalid        boolean                                                   false   Applies invalid/error styling
    required       boolean                                                   false   Marks field as required
    name           string                                                    ''      HTML name attribute for form submission

  Usage:
    <LlmInput type="email" placeholder="you@example.com" />
    <LlmInput type="password" placeholder="Password" />
    <LlmInput invalid={true} placeholder="Invalid state" />
    <LlmInput disabled={true} placeholder="Disabled" />

---

### LlmTextarea

  A multi-line text input. Supports auto-resize to fit content and integrates with Signal Forms.

  Props:
    value          string                   ''     Controlled value
    onValueChange  (value: string) => void  —      Called when the textarea value changes
    rows           number                   3      Initial number of visible rows
    placeholder    string                   ''     Placeholder text
    disabled       boolean                  false  Disables the textarea
    readonly       boolean                  false  Makes the textarea read-only
    invalid        boolean                  false  Applies invalid/error styling
    required       boolean                  false  Marks field as required
    name           string                   ''     HTML name attribute for form submission
    autoResize     boolean                  false  Grows height automatically as content grows

  Usage:
    <LlmTextarea placeholder="Tell us about yourself" rows={4} />
    <LlmTextarea autoResize={true} placeholder="Auto-resizes as you type..." />
    <LlmTextarea disabled={true} placeholder="Disabled" />

---

### LlmCheckbox

  A checkbox input that supports indeterminate state. Integrates with Signal Forms.

  Props:
    checked          boolean                     false  Controlled checked state
    onCheckedChange  (checked: boolean) => void  —      Called when the checked state changes
    value            boolean                     false  Alias for checked (Signal Forms integration)
    onValueChange    (checked: boolean) => void  —      Alias for onCheckedChange (Signal Forms integration)
    indeterminate    boolean                     false  Shows a dash (indeterminate state)
    disabled         boolean                     false  Disables the checkbox
    readonly         boolean                     false  Makes the checkbox read-only
    invalid          boolean                     false  Applies invalid/error styling
    required         boolean                     false  Marks field as required
    name             string                      ''     HTML name attribute for form submission

  Usage:
    <LlmCheckbox>I agree to the terms</LlmCheckbox>
    <LlmCheckbox checked={true}>Pre-checked</LlmCheckbox>
    <LlmCheckbox indeterminate={true}>Indeterminate</LlmCheckbox>
    <LlmCheckbox disabled={true}>Disabled</LlmCheckbox>

---

### LlmToggle

  A toggle switch for boolean settings. Integrates with Signal Forms.

  Props:
    checked          boolean                     false  Controlled checked state
    onCheckedChange  (checked: boolean) => void  —      Called when the checked state changes
    value            boolean                     false  Alias for checked (Signal Forms integration)
    onValueChange    (checked: boolean) => void  —      Alias for onCheckedChange (Signal Forms integration)
    disabled         boolean                     false  Disables the toggle
    readonly         boolean                     false  Makes the toggle read-only
    invalid          boolean                     false  Applies invalid/error styling
    required         boolean                     false  Marks field as required
    name             string                      ''     HTML name attribute for form submission

  Usage:
    <LlmToggle>Enable notifications</LlmToggle>
    <LlmToggle checked={true}>Active toggle</LlmToggle>
    <LlmToggle disabled={true}>Disabled</LlmToggle>

---

### LlmRadioGroup + LlmRadio

  A group of radio buttons with keyboard navigation. The group handles arrow key navigation and value management.

  Props:
    value          string                   ''     Currently selected value
    onValueChange  (value: string) => void  —      Called when selection changes
    disabled       boolean                  false  Disables all radios in the group
    readonly       boolean                  false  Makes all radios in the group read-only
    invalid        boolean                  false  Applies invalid/error styling
    required       boolean                  false  Marks field as required
    name           string                   ''     HTML name attribute (propagated to radios)

  Usage:
    <LlmRadioGroup name="plan" value="free" onValueChange={(v) => console.log(v)}>
      <LlmRadio radioValue="free">Free</LlmRadio>
      <LlmRadio radioValue="pro">Pro</LlmRadio>
      <LlmRadio radioValue="enterprise">Enterprise</LlmRadio>
    </LlmRadioGroup>

---

### LlmSelect + LlmOption

  A custom select dropdown built on the native Popover API. Supports keyboard navigation, type-ahead, and disabled options.

  Props:
    value          string                   ''     Currently selected value
    onValueChange  (value: string) => void  —      Called when selection changes
    placeholder    string                   ''     Placeholder text when no option is selected
    disabled       boolean                  false  Disables the select
    readonly       boolean                  false  Makes the select read-only
    invalid        boolean                  false  Applies invalid/error styling
    required       boolean                  false  Marks field as required
    name           string                   ''     HTML name attribute for form submission

  Usage:
    <LlmSelect placeholder="Select a country" onValueChange={(v) => console.log(v)}>
      <LlmOption optionValue="us">United States</LlmOption>
      <LlmOption optionValue="ca">Canada</LlmOption>
      <LlmOption optionValue="uk" disabled={true}>United Kingdom (unavailable)</LlmOption>
    </LlmSelect>

---

### LlmCombobox

  A filterable autocomplete input. The user can type to narrow down a large list of options.

  Props:
    value          string                   ''     Controlled value
    onValueChange  (value: string) => void  —      Called when selection changes
    options        LlmComboboxOption[]      []     Array of { label, value } objects
    placeholder    string                   ''     Placeholder text
    disabled       boolean                  false  Disables the combobox
    invalid        boolean                  false  Applies invalid/error styling

  Usage:
    <LlmCombobox
      placeholder="Search framework..."
      options={[
        { label: 'Angular', value: 'ng' },
        { label: 'React', value: 'react' },
        { label: 'Vue', value: 'vue' }
      ]}
    />

---

### LlmBadge

  A small inline label for status, categories, or counts. Use alongside cards, list items, and table cells.

  Props:
    variant  'default' | 'success' | 'warning' | 'danger' | 'info'  'default'  Color scheme of the badge
    size     'sm' | 'md'                                            'md'       Size of the badge

  Usage:
    <LlmBadge>Default</LlmBadge>
    <LlmBadge variant="success">Active</LlmBadge>
    <LlmBadge variant="warning">Pending</LlmBadge>
    <LlmBadge variant="danger">Error</LlmBadge>
    <LlmBadge variant="info">Info</LlmBadge>
    <LlmBadge size="sm" variant="success">Small</LlmBadge>

---

### LlmIcon

  Pictogram glyph icon. 21 named variants matching the Figma `LlmIcon` component set. Decorative by default; pass `label` to announce a meaning to assistive tech.

  Props:
    name   'success' | 'warning' | 'danger' | 'info' | 'error' | 'chevron-up' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'sort-asc' | 'sort-desc' | 'arrow-right' | 'arrow-left' | 'copy' | 'paste' | 'add' | 'edit' | 'delete' | 'close' | 'more' | 'default-toast'  —          The icon name. Required.
    size   'sm' | 'md' | 'lg'                                                                                                                                                                                                                                                    'md'       Icon size. Maps to the framework font-size scale.
    label  string                                                                                                                                                                                                                                                                undefined  Accessible label. When provided, the icon is announced as an image with this label. When omitted, the icon is hidden from assistive tech (treated as decorative).

  Usage:
    <LlmIcon name="success" />
    <LlmIcon name="warning" size="lg" label="Warning" />
    <LlmIcon name="chevron-down" size="sm" />

---

### LlmCard

  A container component for grouped content. Compose with LlmCardHeader, LlmCardContent, and LlmCardFooter.

  Props:
    variant  'elevated' | 'outlined' | 'flat'  'elevated'  Visual style of the card
    padding  'none' | 'sm' | 'md' | 'lg'       'md'        Padding size inside the card
    role     'article' | 'region' | 'section'  —           Opt-in landmark role. Default is no role (plain div). Use article for self-contained content, region for a perceivable area (pair with aria-label), section for HTML <section> semantics.

  Usage:
    <LlmCard variant="elevated" padding="md">
      <LlmCardHeader>Card Title</LlmCardHeader>
      <LlmCardContent>
        This is the card body content. It can contain anything.
      </LlmCardContent>
      <LlmCardFooter>
        <LlmButton variant="primary" size="sm">Action</LlmButton>
      </LlmCardFooter>
    </LlmCard>

---

### LlmTable

  A comprehensive data table component for displaying structured information. Supports sorting, row selection, sticky headers, and custom empty states.

  Props:
    variant       'default' | 'striped' | 'bordered'  'default'  Row background styling
    size          'sm' | 'md' | 'lg'                  'md'       Vertical padding of cells
    stickyHeader  boolean                             false      Makes header row stick to the top on scroll
    aria-label    string                              'Table'    Accessible name for the scrollable wrapper region. Announced by screen readers when keyboard users focus the wrapper to scroll horizontally.

  Usage:
    <LlmTable variant="striped">
      <LlmThead>
        <LlmTr>
          <LlmTh sortable>Name</LlmTh>
          <LlmTh>Status</LlmTh>
        </LlmTr>
      </LlmThead>
      <LlmTbody empty={rows.length === 0} colSpan={2}>
        {rows.map(row => (
          <LlmTr key={row.id} selectable>
            <LlmTd>{row.name}</LlmTd>
            <LlmTd>{row.status}</LlmTd>
          </LlmTr>
        ))}
        <div llmTableEmpty>No results found</div>
      </LlmTbody>
    </LlmTable>

---

### LlmAvatar + LlmAvatarGroup

  User avatar with image, initials fallback, and status indicator. Group avatars with LlmAvatarGroup.

  Props:
    src     string                                       ''        Image URL
    alt     string                                       ''        Alt text for the avatar image
    name    string                                       ''        Used for initials fallback and aria-label
    size    'xs' | 'sm' | 'md' | 'lg' | 'xl'             'md'      Size of the avatar
    shape   'circle' | 'square'                          'circle'  Shape of the avatar
    status  'online' | 'offline' | 'away' | 'busy' | ''  ''        Status dot indicator

  Usage:
    <LlmAvatar name="Jane Doe" size="md" status="online" />
    <LlmAvatar name="John Smith" size="lg" shape="square" />
    <LlmAvatarGroup max={3} size="md">
      <LlmAvatar name="Alice" />
      <LlmAvatar name="Bob" />
      <LlmAvatar name="Carol" />
      <LlmAvatar name="Dave" />
    </LlmAvatarGroup>

---

### LlmSkeleton

  Loading placeholder that mimics content shape. Compose multiple skeletons to match your layout.

  Props:
    variant   'text' | 'circular' | 'rectangular'  'text'  Shape of the skeleton
    width     string                               '100%'  CSS width (e.g. "200px", "60%")
    height    string                               ''      CSS height. Auto per variant if not set.
    animated  boolean                              true    Enables shimmer animation

  Usage:
    <LlmSkeleton variant="text" />
    <LlmSkeleton variant="text" width="60%" />
    <LlmSkeleton variant="circular" width="40px" />
    <LlmSkeleton variant="rectangular" height="200px" />

---

### LlmProgress

  A horizontal progress bar for showing completion percentage or indeterminate loading.

  Props:
    value          number                                        0          Progress value from 0 to 100
    max            number                                        100        Maximum value
    indeterminate  boolean                                       false      Shows animated indeterminate state
    variant        'default' | 'success' | 'warning' | 'danger'  'default'  Color variant
    size           'sm' | 'md' | 'lg'                            'md'       Size of the progress bar
    label          string                                        —          Accessible name (aria-label). Required by ARIA when no visible label is nearby.

  Usage:
    <LlmProgress value={25} label="Upload progress" />
    <LlmProgress value={60} variant="success" label="Form completion" />
    <LlmProgress value={85} variant="warning" label="Quota usage" />
    <LlmProgress indeterminate label="Loading…" />

---

### LlmCodeBlock

  Displays a block of code with an optional header, language label, filename, and copy-to-clipboard button. Designed for rendering LLM-generated code output, API examples, and inline snippets.

  Props:
    code             string   ''      The code string to display
    language         string   'text'  Language label shown in the header. Ignored when filename is set.
    filename         string   ''      Optional filename shown in the header instead of the language label
    copyable         boolean  true    Whether to show a copy-to-clipboard button
    showLineNumbers  boolean  false   Whether to display line numbers alongside the code

  Usage:
    <LlmCodeBlock code="const x = 1;" language="typescript" />
    <LlmCodeBlock code={tsCode} filename="app.ts" showLineNumbers={true} />
    <LlmCodeBlock code={shellCmd} language="shell" />
    <LlmCodeBlock code={jsonStr} filename="package.json" />

---

### LlmBreadcrumbs + LlmBreadcrumbItem

  Navigation breadcrumb trail showing the current page location within a hierarchy.

  Props:
    separator  string  '/'  Separator character between items

  Usage:
    <LlmBreadcrumbs>
      <LlmBreadcrumbItem href="/">Home</LlmBreadcrumbItem>
      <LlmBreadcrumbItem href="/components">Components</LlmBreadcrumbItem>
      <LlmBreadcrumbItem>Breadcrumbs</LlmBreadcrumbItem>
    </LlmBreadcrumbs>

---

### LlmTabGroup + LlmTab

  An accessible tabbed interface. Supports roving tabindex, arrow key navigation, and a pills variant.

  Props:
    selectedIndex          number                   0          Index of the selected tab
    onSelectedIndexChange  (index: number) => void  —          Called when selection changes
    variant                'default' | 'pills'      'default'  Visual style of the tab strip

  Usage:
    <LlmTabGroup selectedIndex={0}>
      <LlmTab label="Account">Account settings content.</LlmTab>
      <LlmTab label="Notifications">Notification preferences.</LlmTab>
      <LlmTab label="Billing" disabled={true}>Billing info.</LlmTab>
    </LlmTabGroup>

---

### LlmStepper + LlmStep

  A multi-step wizard for complex processes. Supports linear and non-linear navigation.

  Props:
    activeStep   number                     0             Currently active step index
    linear       boolean                    false         Forces user to complete steps in order
    orientation  'horizontal' | 'vertical'  'horizontal'  Stepper layout direction

  Usage:
    <LlmStepper activeStep={0}>
      <LlmStep label="Basic Info">Step 1 content</LlmStep>
      <LlmStep label="Verification">Step 2 content</LlmStep>
      <LlmStep label="Complete">Step 3 content</LlmStep>
    </LlmStepper>

---

### LlmPagination

  Page navigation control for paginated data. Shows page numbers with previous/next buttons.

  Props:
    page           number                  1     Current page (1-indexed)
    pageCount      number                  1     Total number of pages
    onPageChange   (page: number) => void  —     Called when the user navigates to a page
    siblingCount   number                  1     Number of page buttons on each side of current page
    showFirstLast  boolean                 true  Show first/last page jump buttons

  Usage:
    <LlmPagination
      page={3}
      pageCount={10}
      onPageChange={(p) => console.log(p)}
    />

---

### LlmMenu + LlmMenuItem + LlmMenuTrigger

  A dropdown context menu built on @angular/cdk/menu. Handles keyboard navigation, focus management, ARIA, and nested submenus.

  Props:
    variant  'default' | 'compact'  'default'  Density of the menu

  Usage:
    <LlmButton llmMenuTriggerFor={actionsMenu}>Actions ▾</LlmButton>
    {/* In template: */}
    <LlmMenu ref={actionsMenu}>
      <LlmMenuItem onTriggered={() => console.log('copy')}>Copy</LlmMenuItem>
      <LlmMenuItem onTriggered={() => console.log('paste')}>Paste</LlmMenuItem>
      <LlmMenuSeparator />
      <LlmMenuItem disabled={true}>Delete</LlmMenuItem>
    </LlmMenu>

---

### LlmDialog

  A modal dialog using the native <dialog> element. Includes focus trap, Escape to close, backdrop click to close, and smooth animations.

  Props:
    open             boolean                             false  Controls dialog visibility
    onOpenChange     (open: boolean) => void             —      Called when open state changes
    closeOnBackdrop  boolean                             true   Close when clicking the backdrop
    size             'sm' | 'md' | 'lg' | 'xl' | 'full'  'md'   Max-width of the dialog

  Usage:
    <LlmButton onClick={() => setOpen(true)}>Open Dialog</LlmButton>
    <LlmDialog open={open} onOpenChange={setOpen} size="sm">
      <LlmDialogHeader>Confirm Delete</LlmDialogHeader>
      <LlmDialogContent>Are you sure? This cannot be undone.</LlmDialogContent>
      <LlmDialogFooter>
        <LlmButton variant="outline" onClick={() => setOpen(false)}>Cancel</LlmButton>
        <LlmButton variant="primary" onClick={() => setOpen(false)}>Delete</LlmButton>
      </LlmDialogFooter>
    </LlmDialog>

---

### LlmDrawer

  A slide-in panel from the edge of the viewport. Useful for sidebars, filter panels, and detail views.

  Props:
    open             boolean                              false    Controls drawer visibility
    onOpenChange     (open: boolean) => void              —        Called when open state changes
    position         'left' | 'right' | 'top' | 'bottom'  'right'  Which edge the drawer slides from
    size             'sm' | 'md' | 'lg' | 'full'          'md'     Width (or height for top/bottom)
    closeOnBackdrop  boolean                              true     Close when clicking the backdrop

  Usage:
    <LlmButton onClick={() => setOpen(true)}>Open Drawer</LlmButton>
    <LlmDrawer open={open} onOpenChange={setOpen} position="right">
      <LlmDrawerHeader>Settings</LlmDrawerHeader>
      <LlmDrawerContent>
        <LlmInput placeholder="Search..." />
      </LlmDrawerContent>
      <LlmDrawerFooter>
        <LlmButton onClick={() => setOpen(false)}>Close</LlmButton>
      </LlmDrawerFooter>
    </LlmDrawer>

---

### [llmTooltip]

  An attribute directive that adds a tooltip to any element. Built on @angular/cdk/overlay for viewport-aware positioning.

  Props:
    llmTooltip           string                                —        Tooltip text content (required)
    llmTooltipPosition   'above' | 'below' | 'left' | 'right'  'above'  Preferred position
    llmTooltipDisabled   boolean                               false    Disables the tooltip
    llmTooltipShowDelay  number                                300      Delay in ms before showing
    llmTooltipHideDelay  number                                0        Delay in ms before hiding

  Usage:
    <LlmTooltip tooltip="Save your changes">
      <LlmButton>Save</LlmButton>
    </LlmTooltip>
    <LlmTooltip tooltip="Copy to clipboard" position="right">
      <LlmButton variant="outline">Copy</LlmButton>
    </LlmTooltip>

---

### LlmToastProvider + useLlmToast

  Transient notifications that auto-dismiss. Service/hook-based API — place LlmToastContainer once in app root.

  Props:
    variant      'default' | 'success' | 'warning' | 'danger' | 'info'          'default'       Color scheme of the toast
    duration     number                                                         5000            Auto-dismiss delay in ms. 0 = no auto-dismiss
    dismissible  boolean                                                        true            Show a dismiss button
    position     'top-right' | 'top-center' | 'bottom-right' | 'bottom-center'  'bottom-right'  Container position (on LlmToastContainer)

  Usage:
    // App root:
    <LlmToastProvider>
      <App />
      <LlmToastContainer position="bottom-right" />
    </LlmToastProvider>

    // In any component:
    const { show } = useLlmToast();
    show('Saved!', { variant: 'success' });
    show('Error occurred', { variant: 'danger', duration: 8000 });
    show('Persistent', { duration: 0 });

---

### LlmAccordionGroup + LlmAccordionItem

  Expandable/collapsible sections. Supports multi-expand mode and smooth CSS grid animations.

  Props:
    multi    boolean                               false      Allow multiple items expanded simultaneously
    variant  'default' | 'bordered' | 'separated'  'default'  Visual style of the group

  Usage:
    <LlmAccordionGroup variant="separated">
      <LlmAccordionItem>
        <span llmAccordionHeader>Question 1</span>
        Answer content goes here.
      </LlmAccordionItem>
      <LlmAccordionItem>
        <span llmAccordionHeader>Question 2</span>
        Another answer here.
      </LlmAccordionItem>
    </LlmAccordionGroup>

---

### LlmAlert

  Inline status messages for feedback, warnings, and errors. Optionally dismissible.

  Props:
    variant      'info' | 'success' | 'warning' | 'danger'  'info'  Color scheme and icon
    dismissible  boolean                                    false   Show a close button
    onDismissed  () => void                                 —       Called when the dismiss button is clicked

  Usage:
    <LlmAlert variant="info">This is an informational message.</LlmAlert>
    <LlmAlert variant="success">Your changes were saved successfully.</LlmAlert>
    <LlmAlert variant="warning" dismissible={true}>Your session expires in 5 minutes.</LlmAlert>
    <LlmAlert variant="danger">Something went wrong. Please try again.</LlmAlert>

---

### LlmChat

  Composable AI assistant surface. Three layout variants (drawer, popup, inline) share the same content slots and a status-driven Send/Stop button toggle. Provider-agnostic — wire it to CopilotKit, Vercel AI SDK, or your own backend by binding the Send/Stop events.

  Props:
    variant       'drawer' | 'popup' | 'inline'   'drawer'  Layout — slide-in drawer, floating bubble + popup window, or embedded inline card.
    status        'idle' | 'streaming' | 'error'  'idle'    Connection / response status. Drives the input footer button (Send → Stop) and disables the textarea while streaming.
    open          boolean                         false     Whether the chat is open. Only used by drawer and popup variants. Two-way bindable.
    onOpenChange  (open: boolean) => void         —         React: emitted when the open state should change. Vue uses v-model:open; Angular uses [(open)].

  Usage:
    <LlmChat variant="drawer" open={open} onOpenChange={setOpen} status="idle">
      <LlmChatHeader>
        <LlmAvatar size="sm" name="AI" />
        <span>AI Assistant</span>
        <LlmBadge variant="success" size="sm">Online</LlmBadge>
      </LlmChatHeader>
      <LlmChatMessages>
        <LlmChatMessage role="assistant">Hi! How can I help today?</LlmChatMessage>
        <LlmChatMessage role="user">Show me a sorting function.</LlmChatMessage>
        <LlmChatMessage role="assistant">
          <LlmCodeBlock language="ts" code={snippet} />
        </LlmChatMessage>
      </LlmChatMessages>
      <LlmChatInput onSend={onSend} onStop={onStop} />
    </LlmChat>

---

## Design Token System

All components use CSS custom properties. Override at :root or on any ancestor element.

  --ui-font-family          Font stack
  --ui-font-size-xs/sm/md/lg/xl  Type scale
  --ui-font-weight-normal/medium/semibold/bold  Weight scale

  --ui-spacing-1 through --ui-spacing-12  Spacing scale (0.25rem steps)

  --ui-radius-sm/md/lg/full  Border radii
  --ui-shadow-sm/md/lg       Box shadows

  --ui-color-primary         Brand color
  --ui-color-primary-light   Tinted brand (for selected states)
  --ui-color-text            Primary text
  --ui-color-text-muted      Secondary text
  --ui-color-background      Page background
  --ui-color-surface-raised  Card/panel background (elevated above page)
  --ui-color-surface-sunken  Hover/input background (recessed)
  --ui-color-border          Default borders
  --ui-color-input-bg        Input field background
  --ui-color-input-border    Input border
  --ui-color-input-border-focus  Focused input border
  --ui-color-input-border-invalid  Error state border
  --ui-color-placeholder     Placeholder text color
  --ui-color-error-text      Error message text

  --ui-focus-ring            Full focus ring box-shadow value

  --ui-z-dropdown            z-index for dropdowns/panels
  --ui-z-modal               z-index for dialogs/drawers

Dark mode: all tokens shift automatically via prefers-color-scheme, or set data-theme="dark" on <html>.

Custom theme example:
  :root {
    --ui-color-primary: #10b981;
    --ui-color-primary-light: #d1fae5;
    --ui-radius-md: 2px; /* sharp corners */
  }

---

## Accessibility Notes

- All interactive components have appropriate ARIA roles, states, and properties
- Keyboard navigation follows WAI-ARIA patterns (arrow keys for composite widgets)
- Focus is managed programmatically for dialogs (trap), select/combobox (active descendant), tabs (roving tabindex)
- Color is never the sole indicator of state — icons and text labels accompany color changes
- All form controls support invalid, disabled, required, and readonly states with proper aria- attributes