npm package: @foundrykit/primitives
Description: A collection of accessible, unstyled UI primitives built on top of Radix UI primitives. These components provide the foundation for building consistent, accessible user interfaces.
Latest version: 1.0.14

# @foundrykit/primitives

A collection of accessible, unstyled UI primitives built on top of Radix UI
primitives. These components provide the foundation for building consistent,
accessible user interfaces.

## Features

- **Accessible by default** - Built on Radix UI primitives with proper ARIA
  attributes
- **Unstyled** - No default styling, allowing complete customization
- **TypeScript support** - Full type safety with comprehensive TypeScript
  definitions
- **Composable** - Components are built from sub-components for maximum
  flexibility
- **Themeable** - Designed to work with any styling solution

## Installation

```bash
pnpm add @foundrykit/primitives
```

## Available Components

### Form Components

- **Button** - Accessible button with various variants and states
- **Input** - Form input with proper labeling and validation states
- **Textarea** - Multi-line text input
- **Checkbox** - Accessible checkbox with proper keyboard navigation
- **Radio Group** - Radio button group with proper form integration
- **Select** - Dropdown select with search and keyboard navigation
- **Switch** - Toggle switch component
- **Label** - Accessible form labels

### Layout Components

- **Card** - Container component with header, content, and footer sections
- **Separator** - Visual divider for content organization
- **Skeleton** - Loading placeholder components

### Navigation Components

- **Tabs** - Tabbed interface with keyboard navigation
- **Breadcrumb** - Navigation breadcrumbs
- **Dropdown** - Dropdown menu with sub-menus

### Overlay Components

- **Dialog** - Modal dialog with proper focus management
- **Popover** - Floating content overlay
- **Avatar** - User avatar with fallback support

### Display Components

- **Badge** - Status indicators and labels

## Usage

### Basic Example

```tsx
import {
  Button,
  ButtonRoot,
  ButtonContent,
} from '@foundrykit/primitives/button';
import { Input, InputRoot, InputField } from '@foundrykit/primitives/input';

function MyForm() {
  return (
    <form>
      <Input>
        <InputRoot>
          <InputField placeholder='Enter your name' />
        </InputRoot>
      </Input>

      <Button>
        <ButtonRoot>
          <ButtonContent>Submit</ButtonContent>
        </ButtonRoot>
      </Button>
    </form>
  );
}
```

### Composable Pattern

All components follow a composable pattern where you can use either the complete
component or individual sub-components:

```tsx
// Complete component (recommended for most cases)
import { Button } from '@foundrykit/primitives/button';

// Individual sub-components (for maximum customization)
import {
  ButtonRoot,
  ButtonContent,
  ButtonIcon,
} from '@foundrykit/primitives/button';
```

### Styling

Since these are unstyled primitives, you'll need to add your own styling:

```tsx
import { Button } from '@foundrykit/primitives/button';
import { cn } from '@foundrykit/utils';

function StyledButton({ className, ...props }) {
  return (
    <Button
      className={cn(
        'rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600',
        className
      )}
      {...props}
    />
  );
}
```

## Component Structure

Each component is organized as follows:

```
component/
├── config.ts          # Component configuration and variants
├── index.tsx          # Main component exports
└── README.md          # Component-specific documentation
```

## Accessibility

All components follow WCAG guidelines and include:

- Proper ARIA attributes
- Keyboard navigation support
- Focus management
- Screen reader compatibility
- Color contrast considerations

## Dependencies

- **Radix UI** - For accessibility primitives
- **React** - UI framework
- **TypeScript** - Type safety
- **class-variance-authority** - For component variants
- **clsx** - For conditional class names
- **tailwind-merge** - For class merging

## Contributing

When adding new primitives:

1. Follow the existing component structure
2. Ensure proper accessibility
3. Add TypeScript definitions
4. Include usage examples
5. Update this README

## License

MIT