Skip to content

AGENTS.md

Latest commit

 

History

History
198 lines (152 loc) · 8.96 KB

AGENTS.md

File metadata and controls

198 lines (152 loc) · 8.96 KB

AGENTS.md — Radix Themes

Context file for AI agents working in this repository.

Project Overview

Radix Themes (@radix-ui/themes) is an open-source React component library optimized for fast development, easy maintenance, and accessibility. It provides a comprehensive set of pre-styled, themeable UI components built on top of Radix Primitives.

Documentation

The full docs for this project are hosted at:

When you need to understand a component's API, intended behavior, or usage patterns, consult the docs at the URLs above rather than guessing. The documentation site lives in a separate repository.

Repository Structure

This is a pnpm monorepo managed with Turborepo.

themes/
├── packages/
│   └── radix-ui-themes/          # The core library (published as @radix-ui/themes)
│       ├── src/
│       │   ├── components/       # All component source files
│       │   │   ├── _internal/    # Shared base components (not exported)
│       │   │   ├── *.tsx         # Component implementations
│       │   │   ├── *.props.tsx   # Component prop definitions
│       │   │   ├── *.css         # Component styles
│       │   │   └── index.tsx     # Public component exports
│       │   ├── helpers/          # Utility functions (prop extraction, responsive styles, etc.)
│       │   ├── props/            # Shared prop definitions (color, margin, radius, etc.)
│       │   ├── styles/
│       │   │   ├── tokens/       # Design tokens (colors, typography, radius, shadow, spacing)
│       │   │   └── utilities/    # CSS utility classes (layout, typography)
│       │   └── index.ts          # Package entry point
│       ├── scripts/              # Build scripts (esbuild CJS/ESM)
│       ├── postcss.config.cjs    # PostCSS config with custom plugins
│       ├── tsconfig.json
│       └── package.json
├── apps/
│   └── playground/               # Next.js App Router playground for development
│       ├── app/
│       │   ├── (themeable)/sink/ # Main component showcase (http://localhost:3000/sink)
│       │   ├── (themeable)/test/ # Test pages for specific scenarios
│       │   └── (themeable)/demo/ # Demo pages
│       ├── tests/                # Playwright visual regression tests
│       └── playwright.config.ts
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                # Build, lint, format check, visual regression
│   │   └── publish.yml           # Publish to npm on GitHub release
│   └── CONTRIBUTING.md
├── package.json                  # Root monorepo config
├── pnpm-workspace.yaml
└── turbo.json

Tech Stack

Concern Tool
Package manager pnpm 10 (see .npmrc)
Node version 24 (see .nvmrc)
Monorepo orchestration Turborepo
Language TypeScript (strict)
Framework React (16.8+, 17, 18, 19 supported)
JS bundler esbuild (dual CJS + ESM output)
CSS processing PostCSS (nesting, custom-media, breakpoints, autoprefixer)
Linting ESLint (flat config), Stylelint (for CSS)
Formatting Prettier (single quotes, 100 print width, 120 for CSS)
Playground Next.js (App Router)
Testing Playwright (visual regression)

Key Commands

Run all commands from the repository root unless stated otherwise:

# Install dependencies
pnpm install

# Start development (playground + watch mode)
pnpm dev
# Then visit http://localhost:3000/sink

# Build the library
pnpm build

# Build only the themes package
pnpm build:pkg

# Lint everything
pnpm lint

# Format code
pnpm format

# Check formatting
pnpm format:check

# Run visual regression tests
pnpm test:vr

# Update visual regression snapshots
pnpm test:vr:update

# Clean all build artifacts
pnpm clean

Component Architecture

File Convention

Each component typically consists of three co-located files:

  • component-name.tsx — React component implementation
  • component-name.props.tsx — Prop type definitions and default values
  • component-name.css — Component styles using CSS custom properties and data attributes

Some complex components also have a .primitive.tsx file for lower-level behavior (e.g., checkbox-cards.primitive.tsx).

Styling Approach

  • Components use CSS custom properties (CSS variables) for theming
  • Design tokens are defined in src/styles/tokens/ and include 27+ color scales from @radix-ui/colors
  • Responsive props use breakpoint-based classes generated via a custom PostCSS plugin (postcss-breakpoints.cjs)
  • Layout utility classes are generated from src/styles/utilities/
  • The Theme component wraps the app and provides theming context (appearance, accent color, gray color, radius, scaling)

Prop System

  • Components use a typed prop definition system in src/props/prop-def.ts
  • Most visual props support responsive objects (e.g., size={{ initial: '1', md: '3' }})
  • Common shared props: color, highContrast, radius, variant, size, weight, asChild
  • Margin props (m, mx, my, mt, mr, mb, ml) are extracted via extractMarginProps()

Build System

The package produces:

  1. CJS output → dist/cjs/ (via esbuild)
  2. ESM output → dist/esm/ (via esbuild)
  3. Type declarations → dist/cjs/ and dist/esm/ (via tsc)
  4. CSS output → multiple CSS files at package root:
    • styles.css — Full styles (tokens + components + utilities)
    • components.css — Component styles only
    • utilities.css — Utility classes only
    • tokens.css — Design tokens only
    • tokens/base.css, tokens/colors/*.css — Granular token files
    • layout.css, layout/*.css — Layout-only subset

Development Workflow

  1. Run pnpm dev to start the playground and watch mode
  2. Visit http://localhost:3000/sink to see all components
  3. Test pages are at http://localhost:3000/test/* for specific scenarios
  4. Demo pages at http://localhost:3000/demo
  5. Always run pnpm build before submitting a PR to ensure the build succeeds
  6. Visual regression tests compare screenshots across browsers (Chromium, Firefox, WebKit)

Coding Conventions

  • Prettier for formatting (single quotes, 100 char width, 120 for CSS)
  • ESLint with TypeScript, React Hooks, and jsx-a11y rules
  • Stylelint for CSS (enforces selector specificity, class naming patterns)
  • CSS class names follow the pattern .rt-ComponentName (e.g., .rt-Button, .rt-DialogContent)
  • CSS custom properties use -- prefix namespacing
  • Component files use kebab-case naming (e.g., alert-dialog.tsx)
  • Props files export a *PropDefs object defining allowed values and defaults
  • Use classnames library for conditional class merging

Release Process

  1. PRs that fix bugs or add features should update packages/radix-ui-themes/CHANGELOG.md
  2. Releases follow semver and are published via GitHub Releases
  3. The publish.yml workflow automatically publishes to npm when a GitHub release is created
  4. Pre-releases use pnpm publish -r --tag <alpha|beta|rc>

See release-process.md for the full release checklist.

Important Notes for Agents

  • The documentation site is in a separate repo (radix-ui/website), not this one
  • Built CSS files at the package root (e.g., styles.css, components.css) are gitignored — they are build artifacts
  • The dist/, tokens/, and layout/ directories are also gitignored build artifacts
  • When modifying a component, update all three files (.tsx, .props.tsx, .css) as needed
  • The Theme component (theme.tsx) is the root provider — all other components must be used within it