ark-ui-guidance

name	ark-ui-guidance
description	WHEN implementing or reviewing Ark UI components in React; focus on composition, state attributes, forms integration, and collection/tree primitives.

Ark UI Guidance

Use this skill for component architecture and behavior decisions around Ark UI primitives.

Priorities

• Composition patterns that keep semantics and accessibility intact.
• Styling through stateful data attributes instead of brittle DOM assumptions.
• Correct forms wiring and validation feedback.
• Correct collection and tree usage for list-like and hierarchical interactions.

Composition

• Prefer part-based composition (Root, Trigger, Content, Item) and avoid skipping required structural parts.
• Use asChild where custom elements are needed, while preserving Ark behavior and keyboard semantics.
• Keep trigger/content ownership clear for overlays (dialog, popover, menu, tooltip).

Component State

• Style and behavior should key off Ark data attributes and ARIA state.
• Ensure focus-visible, disabled, invalid, expanded/open, selected/checked states are represented in both style and interaction logic.
• Avoid hand-managed state that duplicates Ark internal state unless there is explicit business logic coupling.

Forms

• For form controls, ensure hidden input synchronization when provided by Ark patterns.
• Keep labels, descriptions, and error text associated through proper ids/aria attributes.
• Surface invalid state consistently in style and message copy.

Collections And Tree Patterns

• Use list collection primitives for filterable/selectable list experiences.
• Use tree collection primitives for nested navigation, disclosure, and hierarchical selection.
• Keep item identity stable across renders to avoid focus and selection bugs.

Verification Hints

• Validate keyboard flows first (tab, arrow keys, enter/space, escape).
• Validate screen reader naming for triggers and inputs.
• Validate interactions in both default and dense content states.