@foundrykit/primitives

@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

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

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:

// 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:

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:

• Follow the existing component structure
• Ensure proper accessibility
• Add TypeScript definitions
• Include usage examples
• Update this README

License

MIT