The Complete Production SOP: How to Deploy and Run Radix UI Unstyled Accessible Headless UI Primitives in Autonomous AI Agents
Production SOP to install and run Radix UI accessible primitives in Codex, Claude Code, and Cursor. Master focus traps, ARIA rules, and headless UI patterns.
Technical Overview & Architectural Context
Modern AI coding agents frequently struggle when implementing headless UI components like Radix UI. Typical LLM failures include omitting the mandatory `@radix-ui/react-dialog` Title or Description subcomponents required by WAI-ARIA specs, improperly nesting Portal components inside transformed CSS containers, or breaking keyboard navigation by overriding internal pointer/focus event handlers without calling `event.preventDefault()` correctly. These subtle bugs degrade web accessibility (a11y) audits and produce non-compliant markup. The `radix-ui-accessible-primitives` skill eliminates these non-deterministic failure modes by enforcing strict structural blueprints and execution gates. It compels autonomous agents across Codex, Claude Code, Cursor, and Windsurf to install atomic packages, construct full component hierarchies (Root, Trigger, Portal, Overlay, Content, Title, Description), and bind Tailwind CSS state animations directly to Radix data attributes (`data-[state=open]`). By establishing procedural guards prior to code emission, the skill guarantees complete screen reader compliance and resilient focus-trap behavior out of the box.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into the active runtime directory to expose Radix UI procedural triggers.
Agent runtimes monitor specific discovery directories (`~/.cursor/skills`, `.claude/skills`, or `.codex/skills`) to detect behavioral SOPs. Installing this skill registers trigger phrases such as 'create accessible dialog radix' and 'radix dropdown menu keyboard navigation', binding agent behavior to deterministic ARIA execution guidelines.
mkdir -p .cursor/skills/radix-ui-accessible-primitives && curl -fsSL https://askills.dev/api/skills/radix-ui-accessible-primitives/raw -o .cursor/skills/radix-ui-accessible-primitives/SKILL.md---
name: "radix-ui-accessible-primitives"
description: "Build accessible, customizable design systems using WAI-ARIA compliant Radix UI primitives."
metadata:
author: "Radix UI"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create accessible dialog radix"
- "radix dropdown menu keyboard navigation"
- "focus trap radix ui"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Place the SKILL.md inside `.claude/skills` or `.cursor/skills` at the repository root. This scopes rules locally and avoids consuming global LLM context during unrelated tasks.
Ensure `fs_write` is limited to 'workspace'. Do not allow global filesystem write access when executing automated headless UI refactoring commands.
Dependency Installation & Component Scaffolding
Ensure atomic Radix UI packages are installed rather than importing deprecated monolithic bundles.
Radix UI uses individual micro-packages (e.g., `@radix-ui/react-dialog`, `@radix-ui/react-dropdown-menu`, `@radix-ui/react-slot`) to optimize bundle sizes and tree-shaking. The agent must verify existing `package.json` dependencies before generating component boilerplates.
pnpm add @radix-ui/react-dialog @radix-ui/react-slot clsx tailwind-merge lucide-reactimport * as React from 'react';
import * as DialogPrimitive from '@radix-ui/react-dialog';
import { X } from 'lucide-react';
import { cn } from '@/lib/utils';
const Dialog = DialogPrimitive.Root;
const DialogTrigger = DialogPrimitive.Trigger;
const DialogPortal = DialogPrimitive.Portal;
const DialogClose = DialogPrimitive.Close;
const DialogOverlay = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Overlay>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
>(({ className, ...props }, ref) => (
<DialogPrimitive.Overlay
ref={ref}
className={cn(
'fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
className
)}
{...props}
/>
));
DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
const DialogContent = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Content>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
>(({ className, children, ...props }, ref) => (
<DialogPortal>
<DialogOverlay />
<DialogPrimitive.Content
ref={ref}
className={cn(
'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg',
className
)}
{...props}
>
{children}
<DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
<X className="h-4 w-4" />
<span className="sr-only">Close</span>
</DialogPrimitive.Close>
</DialogPrimitive.Content>
</DialogPortal>
));
DialogContent.displayName = DialogPrimitive.Content.displayName;
const DialogTitle = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Title>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
>(({ className, ...props }, ref) => (
<DialogPrimitive.Title ref={ref} className={cn('text-lg font-semibold leading-none tracking-tight', className)} {...props} />
));
DialogTitle.displayName = DialogPrimitive.Title.displayName;
const DialogDescription = React.forwardRef<
React.ElementRef<typeof DialogPrimitive.Description>,
React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
>(({ className, ...props }, ref) => (
<DialogPrimitive.Description ref={ref} className={cn('text-sm text-muted-foreground', className)} {...props} />
));
DialogDescription.displayName = DialogPrimitive.Description.displayName;
export { Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose };Instruct the agent to leverage `React.forwardRef` and pass through `ref` and `...props` across all subcomponents. Omitting refs breaks Radix UI internal collision detection and positioning engines.
Never place `DialogOverlay` outside `DialogPortal`. If unportaled, the modal can get clipped by ancestor containers with `overflow: hidden` or `transform` properties.
Intent Matching & Trigger Invocation
Verify natural language trigger parsing and enforce mandatory subcomponent checks.
When invoking dialog generation, the agent must check its internal execution checklist. The prompt triggers trigger matching in the frontmatter, compelling the agent to generate compliant accessible containers including explicit `DialogTitle` and `DialogDescription` primitives.
Explicitly mention screen-reader requirements or keyboard interactions to reinforce trigger weights and prevent agents from defaulting to non-accessible generic HTML5 `div` elements.
Verification, Linting & Output Quality Gate
Execute automated accessibility assertions and compile checks before finalizing file writes.
The agent must run type checking (`tsc --noEmit`) and ESLint with `eslint-plugin-jsx-a11y` to verify that all Radix trigger-to-content mappings adhere strictly to WAI-ARIA standards before reporting completion.
pnpm tsc --noEmit && pnpm eslint src/components/ui/dialog.tsx --rule 'jsx-a11y/aria-props: error'Use `git diff --stat` after agent generation to ensure the agent did not unintentionally modify unrelated files or override Tailwind configuration settings.
Real-World Scenario: Accessible User Profile Edit Modal with Keyboard Trap & Form State
“create accessible dialog radix for updating user profile settings. Ensure focus trap radix ui is active, escape closes the dialog, and screen reader announcements for title and description pass axe-core audits.”
Runtime Troubleshooting & Failure Modes
Root Cause: Radix UI Dialog enforces accessibility by default. When `Dialog.Content` renders without an inner `Dialog.Description` or without setting `aria-describedby={undefined}`, Radix logs an a11y violation in development mode.
Ensure `<DialogDescription>Explanation text</DialogDescription>` exists within `<DialogContent>`. If a visual description is explicitly not desired, hide it accessibly using `<DialogDescription className="sr-only">Descriptive summary</DialogDescription>` or pass `<DialogContent aria-describedby={undefined}>`.Root Cause: The agent controlled the `open` state using `useState` but didn't manage focus restoration correctly when conditional rendering unmounted the trigger element upon modal closure.
Pass `onCloseAutoFocus={(event) => { event.preventDefault(); fallbackRef.current?.focus(); }}` to `DialogContent` to explicitly redirect post-close focus to a stable DOM node.Frequently Asked Questions (Radix UI Unstyled Accessible Headless UI Primitives SOP)
Q:Can I use Radix UI Unstyled Accessible Headless UI Primitives across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres to the open SKILL.md specification. By placing the manifest in `.agents/skills`, `.claude/skills`, or `.cursor/skills`, any modern agent runtime parses the YAML frontmatter triggers and adopts the execution SOP.
Q:How does Radix UI Unstyled Accessible Headless UI Primitives prevent context window overflow during long agent sessions?
Instead of re-explaining the entire WAI-ARIA modal or dropdown specification in prompt history, the skill provides compressed, deterministic component maps. The agent executes against strict structural constraints without consuming repetitive conversational tokens.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a Security Score of 98/100. It requires only standard workspace filesystem write permissions (`fs_write: 'workspace'`) and operates safely without root execution or open network sockets.
Ready to equip your autonomous agent with Radix UI Unstyled Accessible Headless UI Primitives?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.