React

Create the main component source file with the component implementation. Export the component and its props type. Use React.forwardRef for the root element.

Pattern: Follow the structure in any existing component package (e.g., packages/react/accessible-icon or packages/react/avatar) — each has a src/ directory with a single main .tsx file named after the component

Create a barrel export file that re-exports everything from the main component file using 'export { ComponentName, type ComponentNameProps } from "./{component-name}"'

Pattern: See how packages/react/accessible-icon/src/index.ts re-exports from its main component file

Create package.json with name '@radix-ui/react-{component-name}', define 'source', 'main', 'module', and 'types' fields pointing to src/index.ts and dist/ outputs. Add peerDependencies on react and react-dom. Add dependencies on any @radix-ui primitives used (e.g., @radix-ui/react-primitive, @radix-ui/react-use-controllable-state).

Pattern: Copy the package.json structure from packages/react/avatar/package.json — it shows the standard field layout, scripts, and dependency declarations

Create a tsconfig.json that extends the shared base TypeScript config and sets compilerOptions and include paths for the src directory

Pattern: Copy the tsconfig.json from packages/react/avatar/tsconfig.json which extends the shared config

Add a re-export line for the new component: 'export { ComponentName, type ComponentNameProps } from "@radix-ui/react-{component-name}"' so it is available from the umbrella package

Pattern: See the existing re-export lines in packages/react/radix-ui/src/index.ts for every other component

Add '@radix-ui/react-{component-name}' as a dependency in the radix-ui umbrella package

Pattern: See how packages/react/radix-ui/package.json lists all @radix-ui/react-* packages as dependencies

Create the hook implementation file. Export the hook as a named export. The hook name should follow the 'use-*' convention (e.g., use-controllable-state).

Pattern: Follow the structure in packages/react/use-controllable-state or packages/react/use-callback-ref — each has a src/ directory with the hook implementation

Create a barrel export that re-exports the hook from the implementation file

Pattern: See how other hook packages like packages/react/use-callback-ref/src/index.ts handle their exports

Create package.json with name '@radix-ui/react-{hook-name}', standard source/main/module/types fields, and peerDependencies on react

Pattern: Copy the package.json structure from packages/react/use-callback-ref/package.json

Create tsconfig.json extending the shared base config

Pattern: Copy from packages/react/use-callback-ref/tsconfig.json

Create the utility implementation file. Export pure functions with TypeScript types. Core utilities must be framework-agnostic (no React imports).

Pattern: Follow the structure in packages/core/number — it exports pure utility functions with full TypeScript typing

Create barrel export re-exporting all public functions and types

Pattern: See packages/core/number/src/index.ts for the re-export pattern

Create package.json with name '@radix-ui/{utility-name}', no react peerDependencies since core packages are framework-agnostic

Pattern: Copy the package.json structure from packages/core/number/package.json

Create tsconfig.json extending the shared base config

Pattern: Copy from packages/core/number/tsconfig.json

Create a new stories file. Import the component from its package. Define a default export with title and component metadata. Create named exports for each story variant (e.g., Default, WithCustomProps, Controlled).

Pattern: Look at existing story files in apps/storybook/stories/ — each follows the CSF (Component Story Format) with a default meta export and named story exports

Create a new Cypress test file. Use describe/it blocks. Visit the component's test page and interact with it using Cypress commands. Assert on DOM state, ARIA attributes, and keyboard interactions.

Pattern: Look at existing test files in cypress/e2e/ — they use cy.visit(), cy.get(), cy.findByRole() and assert on accessibility attributes

If the component needs custom Cypress commands (e.g., for complex interactions), add them here using Cypress.Commands.add()

Pattern: See existing custom commands already registered in cypress/support/e2e.js

Create a new Next.js page that renders the component with typical props. The page should import the component from its @radix-ui package and render it in a basic layout. This verifies the component doesn't crash during server-side rendering.

Pattern: See existing pages in apps/ssr-testing/app/ — each is a simple page.tsx that imports and renders a component with minimal props

Add a navigation link to the new component's SSR test page in the root layout's nav section so it's accessible from the index

Pattern: See how apps/ssr-testing/app/layout.tsx already lists links to existing component test pages

Modify the build orchestration logic. This file handles compilation, bundling, and output generation for all packages. Add new build steps, modify output formats, or change compilation settings here.

Pattern: Read the existing build steps in internal/builder/builder.js to understand the pipeline stages: source reading, TypeScript compilation, bundling, and output writing

If adding new CLI flags or changing the build invocation interface, modify this entry point

Pattern: See how internal/builder/radix-build.js currently parses arguments and calls into builder.js

For rules that should apply to ALL packages in the monorepo, add them to the shared config here. This is the centralized config imported by every package.

Pattern: See how internal/eslint-config/index.js structures its rule definitions and plugin configurations

For rules specific to React component packages, add them to this React-specific preset

Pattern: See how internal/eslint-config/react-package.js extends the base config with React-specific rules

For rules specific to Vite-based projects, modify this config

Pattern: See how internal/eslint-config/vite.js layers Vite-specific rules on top of the base

For root-level overrides or workspace-wide ignores, modify the root ESLint config

Pattern: See how eslint.config.mjs imports from internal/eslint-config and adds project-level overrides

Create the primitive implementation. Primitives are low-level building blocks used by multiple higher-level components. They should be minimal, composable, and handle a single concern (e.g., focus management, slot rendering, collection tracking).

Pattern: Study packages/react/primitive or packages/react/slot — primitives export minimal components/hooks that handle one specific DOM or React concern

Create barrel export for the primitive

Pattern: See packages/react/primitive/src/index.ts

Create package.json. Primitives typically have minimal dependencies — only react, react-dom as peerDeps and possibly @radix-ui/react-primitive.

Pattern: Copy structure from packages/react/slot/package.json or packages/react/primitive/package.json

Create tsconfig.json extending the shared base

Pattern: Copy from packages/react/primitive/tsconfig.json

Add new global test utilities, custom matchers, or polyfills. This file runs before all Vitest tests across the monorepo.

Pattern: See how scripts/setup-tests.ts currently sets up matchers and polyfills — add new setup in the same style

If the new test utilities introduce new global types or augment existing ones, declare them here

Pattern: See how types/global.d.ts declares existing global type augmentations