# Sona UI Agent Resources (Full)

> Detailed, machine-readable guidance for selecting and integrating Sona UI components.

## Freshness protocol

- Manifest: https://sonaui.com/agent/manifest.json
- This is a generated fallback snapshot. Fetch the manifest and then the selected component detail before relying on component guidance when network access is available.
- If the manifest is unavailable, state that the guidance may not match the deployed registry before continuing.

## Installation

Configure the Sona UI registry in the consumer project's components.json:

```json
{
  "registries": {
    "@sona-ui": "https://sonaui.com/r/{name}.json"
  }
}
```

Install a selected item with the consumer project's package runner:

```bash
bunx shadcn@latest add @sona-ui/<component>
```

## Selection guidance

### Fluid Tabs

- Category: components
- Status: stable
- Summary: An accessible tab selector for switching related views while preserving spatial continuity with a shared active surface.
- Documentation: https://sonaui.com/docs/fluid-tabs
- Registry item: https://sonaui.com/r/fluid-tabs.json

Use when:
- The interface switches between a small set of related views.
- The active selection should feel spatially connected to the previous selection.

Avoid when:
- The interface needs deep navigation rather than local view switching.
- There are too many options for a compact tab list.

Capabilities:
- Base UI tab primitives
- Controlled and uncontrolled selection
- Capsule and underline variants
- Keyboard navigation

Accessibility:
- Uses semantic tab roles and keyboard navigation through Base UI.
- Keep each tab label descriptive and preserve visible focus styles.

Motion: Connect the previous and next selections with a shared active surface.
Reduced motion: The active surface should switch without spatial animation.

### Animated Dialog

- Category: components
- Status: stable
- Summary: A composable dialog for focused decisions or short tasks, with direction-aware enter and exit motion.
- Documentation: https://sonaui.com/docs/animated-dialog
- Registry item: https://sonaui.com/r/animated-dialog.json

Use when:
- The user must complete or confirm a focused task without leaving the current page.
- The content needs an accessible modal boundary and explicit dismissal behavior.

Avoid when:
- The content is essential to the page and should not be hidden behind an overlay.
- A lightweight disclosure or popover is sufficient.

Capabilities:
- Base UI dialog primitives
- Controlled open state
- Direction-aware enter and exit motion
- Reduced-motion support

Accessibility:
- Preserves dialog semantics, focus management, and keyboard dismissal through Base UI.
- Provide an accessible title and description for every dialog instance.

Motion: Explain the dialog's relationship to the triggering surface.
Reduced motion: Remove transform and opacity choreography while preserving the modal state change.

### Mesh Gradient Shader

- Category: shaders
- Status: stable
- Summary: A decorative animated color field for expressive backgrounds, powered by Paper Design Shaders.
- Documentation: https://sonaui.com/docs/mesh-gradient-shader
- Registry item: https://sonaui.com/r/mesh-gradient-shader.json

Use when:
- A visual surface needs atmospheric depth behind readable foreground content.
- The experience can afford a WebGL-based decorative effect.

Avoid when:
- The effect would compete with primary content or reduce text contrast.
- The target device or environment cannot reliably support the shader dependency.

Capabilities:
- Paper Design Shaders integration
- Animated color spots and organic distortion
- Configurable visual composition

Accessibility:
- Treat as decorative and keep meaningful content outside the shader canvas.
- Verify foreground contrast against the complete animated background.

Motion: Add slow atmospheric depth without becoming the page's primary action.
Reduced motion: Use a static composition or disable the animated shader for reduced-motion users.

### Animated Dropdown

- Category: components
- Status: stable
- Summary: An accessible dropdown menu for choosing or revealing related actions with origin-aware enter motion.
- Documentation: https://sonaui.com/docs/animated-dropdown
- Registry item: https://sonaui.com/r/animated-dropdown.json

Use when:
- An accessible dropdown menu for choosing or revealing related actions with origin-aware enter motion.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Animated Switch

- Category: components
- Status: stable
- Summary: An iOS-style switch for immediate binary settings with tactile press feedback.
- Documentation: https://sonaui.com/docs/animated-switch
- Registry item: https://sonaui.com/r/animated-switch.json

Use when:
- An iOS-style switch for immediate binary settings with tactile press feedback.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Button

- Category: components
- Status: stable
- Summary: A simple action button with subtle press feedback and reduced-motion support.
- Documentation: https://sonaui.com/docs/button
- Registry item: https://sonaui.com/r/button.json

Use when:
- A simple action button with subtle press feedback and reduced-motion support.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Dot Orbit Shader

- Category: shaders
- Status: stable
- Summary: An animated field of orbiting dots for decorative surfaces and expressive backgrounds.
- Documentation: https://sonaui.com/docs/dot-orbit-shader
- Registry item: https://sonaui.com/r/dot-orbit-shader.json

Use when:
- An animated field of orbiting dots for decorative surfaces and expressive backgrounds.

Avoid when:
- The effect would compete with meaningful content or reduce readability.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Add restrained visual depth without competing with the primary task.
Reduced motion: Use a static or reduced visual treatment when motion is not preferred.

### Magnetic Button

- Category: effects
- Status: stable
- Summary: A bounded pointer-aware wrapper that adds restrained magnetic pull around an interactive element.
- Documentation: https://sonaui.com/docs/magnetic-button
- Registry item: https://sonaui.com/r/magnetic-button.json

Use when:
- A bounded pointer-aware wrapper that adds restrained magnetic pull around an interactive element.

Avoid when:
- The effect would compete with meaningful content or reduce readability.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Add restrained visual depth without competing with the primary task.
Reduced motion: Use a static or reduced visual treatment when motion is not preferred.

### Animated Tabs

- Category: components
- Status: stable
- Summary: A keyboard-accessible tab selector with controlled state, disabled items, and a shared hover indicator.
- Documentation: https://sonaui.com/docs/animated-tabs
- Registry item: https://sonaui.com/r/animated-tabs.json

Use when:
- A keyboard-accessible tab selector with controlled state, disabled items, and a shared hover indicator.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Expanding Action

- Category: components
- Status: stable
- Summary: A compact action that transforms in place to reveal two to four related choices while preserving context.
- Documentation: https://sonaui.com/docs/expanding-action
- Registry item: https://sonaui.com/r/expanding-action.json

Use when:
- A compact trigger should reveal two to four closely related choices in place.
- The choices should remain visually connected to the action that revealed them.

Avoid when:
- The choices perform navigation or require a long menu.
- The interaction contains a destructive action that needs deliberate confirmation.

Capabilities:
- Controlled and uncontrolled expanded state
- Disabled trigger and choice support
- Keyboard-accessible button semantics
- Shared-surface transition between trigger and choices

Accessibility:
- Uses button semantics and visible keyboard focus states for the trigger, back control, and choices.
- Keep choice labels specific enough to describe the resulting action.

Motion: Preserve spatial continuity as one compact action transforms into its related choices.
Reduced motion: Respect the user's reduced-motion preference while preserving the expanded and collapsed state change.

### Activity Graph

- Category: components
- Status: stable
- Summary: A keyboard-accessible calendar heatmap with normalized intensity levels and an interruptible shared focus surface.
- Documentation: https://sonaui.com/docs/activity-graph
- Registry item: https://sonaui.com/r/activity-graph.json

Use when:
- Daily activity needs to be compared across a calendar range.
- People need keyboard access to individual days and their values.

Avoid when:
- The data does not have a meaningful daily time dimension.
- Precise trend comparison would be clearer in a chart or table.

Capabilities:
- Normalized intensity levels
- Controlled day selection
- Custom metadata and tooltip content
- Roving keyboard focus

Accessibility:
- Supports visual-direction arrow keys, Home, End, Enter, and Space.
- Provides a range summary and larger targets for coarse pointers.

Motion: Move a shared focus surface between days without obscuring the selected value.
Reduced motion: Update the focus state immediately without spatial interpolation.

### Avatar Showcase

- Category: effects
- Status: stable
- Summary: A recording-friendly avatar strip with count-aware pacing, deterministic sampling, staggered lanes, and reduced-motion support.
- Documentation: https://sonaui.com/docs/avatar-showcase
- Registry item: https://sonaui.com/r/avatar-showcase.json

Use when:
- An ordered group of people should be presented as a moving visual strip.
- A recent sample needs to represent a larger community count.

Avoid when:
- Every person must remain individually readable or directly actionable.
- Motion would distract from the page's primary task.

Capabilities:
- Count-aware pacing
- Deterministic avatar sampling
- Configurable staggered lanes
- Static reduced-motion presentation

Accessibility:
- Provide a name for each person whenever it is available.
- Reduced-motion preferences show a static readable avatar group.

Motion: Convey the scale and activity of a community with restrained lane movement.
Reduced motion: Replace the moving lanes with a static readable avatar group.

### Fluid Slider

- Category: components
- Status: stable
- Summary: A labeled Base UI range control with direct surface selection, a draggable indicator, and restrained boundary resistance.
- Documentation: https://sonaui.com/docs/fluid-slider
- Registry item: https://sonaui.com/r/fluid-slider.json

Use when:
- A numeric value benefits from direct continuous adjustment.
- Reference marks or formatted values help explain meaningful thresholds.

Avoid when:
- The value must be entered with exact precision more efficiently as text.
- The options are discrete named choices rather than a numeric range.

Capabilities:
- Controlled and uncontrolled values
- Drag and direct track selection
- Reference marks and formatted values
- Form integration through Base UI

Accessibility:
- Uses Base UI range semantics and keyboard controls.
- Keeps the semantic value within constraints while visual resistance remains decorative.

Motion: Provide tactile feedback during direct manipulation and at range boundaries.
Reduced motion: Keep keyboard and value updates immediate and remove nonessential resistance motion.

### Fluid Tooltip

- Category: components
- Status: stable
- Summary: A grouped Base UI tooltip system with a deliberate first appearance and fast directional handoffs between related controls.
- Documentation: https://sonaui.com/docs/fluid-tooltip
- Registry item: https://sonaui.com/r/fluid-tooltip.json

Use when:
- A group of compact controls needs accessible supplementary labels.
- One tooltip surface should follow focus or pointer movement across related triggers.

Avoid when:
- The information is essential and should remain visible without interaction.
- The content requires interactive controls or a persistent popover.

Capabilities:
- Horizontal and vertical trigger groups
- Delayed first pointer appearance
- Immediate adjacent-trigger handoff
- Collision-aware Base UI positioning

Accessibility:
- Uses Base UI tooltip semantics and accessible descriptions.
- Keyboard focus opens the relevant label immediately without directional travel.

Motion: Preserve orientation as one tooltip surface moves between related controls.
Reduced motion: Remove directional content travel while preserving the tooltip label.

### Lightbox

- Category: components
- Status: stable
- Summary: An accessible image preview that expands from its thumbnail and returns to the same spatial origin when dismissed.
- Documentation: https://sonaui.com/docs/lightbox
- Registry item: https://sonaui.com/r/lightbox.json

Use when:
- An image needs an inspectable full-size view without leaving the current page.
- The preview should retain a visible relationship to its thumbnail.

Avoid when:
- The full image is primary page content and should remain visible.
- The experience needs gallery navigation that the component does not provide.

Capabilities:
- Controlled and uncontrolled open state
- Thumbnail-to-preview spatial transition
- Optional caption
- Backdrop and preview styling hooks

Accessibility:
- Uses Base UI for focus management, Escape dismissal, and scroll locking.
- Requires useful alternative text for the image.

Motion: Explain that the full-size preview originates from and returns to its thumbnail.
Reduced motion: Use a cross-fade instead of the thumbnail-to-preview spatial transition.

### Section Rail

- Category: components
- Status: stable
- Summary: A compact navigation rail that tracks progress through a long page and reveals labels or editorial context.
- Documentation: https://sonaui.com/docs/section-rail
- Registry item: https://sonaui.com/r/section-rail.json

Use when:
- A long page, case study, or multi-step flow needs compact section navigation.
- Readers benefit from seeing the active section and nearby context.

Avoid when:
- The page is too short to need persistent section navigation.
- The destinations lead to separate pages rather than sections in one experience.

Capabilities:
- Anchor-based scroll mode
- Externally controlled active section
- Optional labels and context cards
- Coarse-pointer presentation

Accessibility:
- Uses anchor links in scroll mode and buttons with current-state semantics in controlled mode.
- Shows visible labels for coarse pointers instead of relying on hover-only targets.

Motion: Connect the active indicator and contextual details to the reader's current section.
Reduced motion: Simplify indicator transitions and scrolling while preserving active-section feedback.

### Accordion

- Category: components
- Status: stable
- Summary: An accessible disclosure group for progressively revealing related content.
- Documentation: https://sonaui.com/docs/accordion
- Registry item: https://sonaui.com/r/accordion.json

Use when:
- An accessible disclosure group for progressively revealing related content.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Ripple Button

- Category: components
- Status: stable
- Summary: A button with localized press feedback that makes activation visible without changing the action's meaning.
- Documentation: https://sonaui.com/docs/ripple-button
- Registry item: https://sonaui.com/r/ripple-button.json

Use when:
- A button with localized press feedback that makes activation visible without changing the action's meaning.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Marquee

- Category: effects
- Status: stable
- Summary: A continuously moving content rail for decorative or low-priority repeated content.
- Documentation: https://sonaui.com/docs/marquee
- Registry item: https://sonaui.com/r/marquee.json

Use when:
- A continuously moving content rail for decorative or low-priority repeated content.

Avoid when:
- The effect would compete with meaningful content or reduce readability.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Add restrained visual depth without competing with the primary task.
Reduced motion: Use a static or reduced visual treatment when motion is not preferred.

### Spinning Text

- Category: text
- Status: stable
- Summary: A circular text treatment for short decorative labels and editorial accents.
- Documentation: https://sonaui.com/docs/spinning-text
- Registry item: https://sonaui.com/r/spinning-text.json

Use when:
- A circular text treatment for short decorative labels and editorial accents.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Stagger Text

- Category: text
- Status: stable
- Summary: A text entrance treatment that reveals short content progressively while preserving readability.
- Documentation: https://sonaui.com/docs/stagger-text
- Registry item: https://sonaui.com/r/stagger-text.json

Use when:
- A text entrance treatment that reveals short content progressively while preserving readability.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Link Preview

- Category: components
- Status: stable
- Summary: A contextual preview surface for supplied link metadata without relying on client-side scraping.
- Documentation: https://sonaui.com/docs/link-preview
- Registry item: https://sonaui.com/r/link-preview.json

Use when:
- A contextual preview surface for supplied link metadata without relying on client-side scraping.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Bubble Up Button

- Category: components
- Status: stable
- Summary: An expressive button treatment that changes label or content with a contained upward transition.
- Documentation: https://sonaui.com/docs/bubble-up-button
- Registry item: https://sonaui.com/r/bubble-up-button.json

Use when:
- An expressive button treatment that changes label or content with a contained upward transition.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Expandable Tabs

- Category: components
- Status: stable
- Summary: A compact tab control that expands its selected item to expose more context.
- Documentation: https://sonaui.com/docs/expandable-tabs
- Registry item: https://sonaui.com/r/expandable-tabs.json

Use when:
- A compact tab control that expands its selected item to expose more context.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Split Text

- Category: text
- Status: stable
- Summary: A text animation primitive that treats words or characters as individually addressable visual units.
- Documentation: https://sonaui.com/docs/split-text
- Registry item: https://sonaui.com/r/split-text.json

Use when:
- A text animation primitive that treats words or characters as individually addressable visual units.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Image Trail

- Category: effects
- Status: stable
- Summary: A pointer-driven sequence of images for decorative cursor-following moments on fine pointers.
- Documentation: https://sonaui.com/docs/image-trail
- Registry item: https://sonaui.com/r/image-trail.json

Use when:
- A pointer-driven sequence of images for decorative cursor-following moments on fine pointers.

Avoid when:
- The effect would compete with meaningful content or reduce readability.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Add restrained visual depth without competing with the primary task.
Reduced motion: Use a static or reduced visual treatment when motion is not preferred.

### Spotlight Card

- Category: components
- Status: stable
- Summary: A card that reveals localized pointer lighting while keeping content and hierarchy stable.
- Documentation: https://sonaui.com/docs/spotlight-card
- Registry item: https://sonaui.com/r/spotlight-card.json

Use when:
- A card that reveals localized pointer lighting while keeping content and hierarchy stable.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Hold To Delete Button

- Category: components
- Status: stable
- Summary: A deliberate destructive action that requires sustained input before completing deletion.
- Documentation: https://sonaui.com/docs/hold-to-delete-button
- Registry item: https://sonaui.com/r/hold-to-delete-button.json

Use when:
- A deliberate destructive action that requires sustained input before completing deletion.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Circular Dock Menu

- Category: components
- Status: stable
- Summary: A radial action menu for a small set of spatially related actions.
- Documentation: https://sonaui.com/docs/circular-dock-menu
- Registry item: https://sonaui.com/r/circular-dock-menu.json

Use when:
- A radial action menu for a small set of spatially related actions.

Avoid when:
- The interaction does not match the component's focused responsibility.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Communicate state, continuity, or feedback at the point of interaction.
Reduced motion: Reduce nonessential choreography while preserving the state change and feedback.

### Fan View

- Category: effects
- Status: stable
- Summary: A fan-like arrangement for browsing a small set of layered visual items.
- Documentation: https://sonaui.com/docs/fan-view
- Registry item: https://sonaui.com/r/fan-view.json

Use when:
- A fan-like arrangement for browsing a small set of layered visual items.

Avoid when:
- The effect would compete with meaningful content or reduce readability.

Capabilities:
- Source-owned Sona UI component
- Semantic theme tokens

Accessibility:
- Preserve the component's documented semantic structure, keyboard behavior, and visible focus state.

Motion: Add restrained visual depth without competing with the primary task.
Reduced motion: Use a static or reduced visual treatment when motion is not preferred.

### Smart Overflow

- Category: components
- Status: preview
- Summary: A priority-first responsive action group that keeps important actions visible and moves lower-priority actions into an accessible three-dot menu.
- Documentation: https://sonaui.com/docs/smart-overflow
- Registry item: https://sonaui.com/r/smart-overflow.json

Use when:
- A compact action group has one or more actions that should stay visible as available width decreases.
- Secondary management actions can remain available in a three-dot menu without harming the main task.

Avoid when:
- Every item has equal importance and needs to be scanned or compared, such as date ranges or tabs.
- The content is navigation, a long command list, or a full application toolbar.

Capabilities:
- Composable SmartOverflowAction children
- Primary, secondary, and always-overflow priorities
- Responsive action measurement and focus recovery
- Base UI menu keyboard navigation
- Destructive action separation

Accessibility:
- Visible actions retain button semantics and visible focus states.
- Hidden actions remain reachable through a labelled three-dot menu with Base UI focus management.
- Focus returns to the three-dot trigger when a focused action moves into overflow after resize.

Motion: Preserve spatial continuity as actions reflow and the overflow trigger appears or disappears.
Reduced motion: Update visible actions and the overflow trigger without layout travel or scale transitions.

### Circular Context Menu

- Category: components
- Status: preview
- Summary: An edge-aware contextual action menu that fans a small, focused set of actions out from a selected object.
- Documentation: https://sonaui.com/docs/circular-context-menu
- Registry item: https://sonaui.com/r/circular-context-menu.json

Use when:
- A selected canvas object, media item, or compact control needs a few immediate contextual actions.
- The actions are spatially related to one anchor and can be represented by concise icons or labels.

Avoid when:
- The user needs to scan, compare, or search a long list of commands.
- A conventional toolbar, dropdown, or keyboard command palette would make the actions clearer.

Capabilities:
- Composable Root, Anchor, Content, and Item API
- Controlled and uncontrolled open state
- Top, right, bottom, and left placements
- Configurable arc radius and spread
- Destructive action styling

Accessibility:
- Uses a button anchor with expanded state and a labelled menu with menuitem actions.
- Arrow keys move between actions, Escape closes the menu, and focus returns to the anchor.
- Use concise accessible labels for icon-only actions and keep the action count small.

Motion: Show that contextual actions originate from the selected object while preserving the selection's spatial relationship.
Reduced motion: Open and close actions without spring travel, blur, hover scaling, or press scaling.

## Integration principles

- Inspect the consumer project before changing aliases, tokens, layout, or global styles.
- Preserve semantic HTML, keyboard behavior, focus visibility, and reduced-motion behavior.
- Keep decorative effects separate from meaningful content and verify contrast against the complete visual surface.
- Use the registry item as the installation authority; do not copy component source into prompts or skill files.