npm package: @folksam/ui-components
Description: A comprehensive, production-ready React component library built with TypeScript and Pigment CSS. This library provides a complete set of accessible, customizable, and performant UI components following modern design system principles.
Latest version: 0.8.1

# @folksam/ui-components

A comprehensive, production-ready React component library built with TypeScript and Pigment CSS. This library provides a complete set of accessible, customizable, and performant UI components following modern design system principles.

## Features

✨ **Modern Stack**: Built with TypeScript, React 19+, and Pigment CSS for zero-runtime CSS-in-JS  
🎨 **Design System Integration**: Seamlessly integrates with `@folksam/ui-design-tokens`  
🎯 **Type Safe**: Full TypeScript support with comprehensive prop typing  
⚡ **Performance Optimized**: Tree-shakeable exports and minimal bundle impact  
📚 **Comprehensive Documentation**: Extensive examples and API documentation

## Installation

```bash
# Using npm
npm install @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles

# Using pnpm
pnpm add @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles

# Using yarn
yarn add @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles
```

## Quick Start

```tsx
import { UiButton, UiForm, UiFormInput, UiModal } from '@folksam/ui-components';
import { globalCssBaseline } from '@folksam/ui-styles';
import '@folksam/ui-design-tokens/css/theme.css';

// This adds font styles and a very aggressive reset
globalCssBaseline();

function App() {
  return (
    <div>
      <UiButton uiVariant="primary" onClick={() => alert('Hello!')}>
        Click me
      </UiButton>

      <UiForm>
        <UiFormInput
          uiLabel="Email address"
          type="email"
          placeholder="Enter your email"
          required
        />
      </UiForm>
    </div>
  );
}
```

## Architecture & Design Principles

### Naming Convention

All components follow a consistent naming pattern: `Ui{Category!}{Name?}{Specifier?}`

```tsx
// Category-based naming
UiFormInput; // Form category, Input component
UiFormInputRadio; // Form category, Input component, Radio specifier
UiNavigationTabs; // Navigation category, Tabs component
UiTypographyHeading; // Typography category, Heading component

// Exception: When category equals name
UiForm; // Not UiFormForm
UiModal; // Not UiModalModal
```

**Benefits:**

- 🔍 **Excellent IntelliSense**: Type `Ui` and get categorized autocompletion
- 📁 **Clear Organization**: Components grouped by category in file structure
- 🎯 **Predictable API**: Easy to guess component names based on usage
- 🚫 **No Conflicts**: Unique naming prevents conflicts with other libraries

### Prop Naming Convention

All custom props are prefixed with `ui` to distinguish them from native HTML attributes:

```tsx
<UiButton
  uiVariant="primary" // Our custom variant prop
  uiSize="large" // Our custom size prop
  type="submit" // Native HTML attribute
  disabled // Native HTML attribute
  className="custom-class" // Standard React prop
>
  Submit Form
</UiButton>
```

**Benefits:**

- ✨ **Clear Separation**: Instantly identify custom vs. native props
- 📚 **Better Documentation**: API docs clearly show component-specific features
- 🔧 **Easier Maintenance**: Refactor custom props without affecting native behavior
- 🎯 **Enhanced Developer Experience**: Autocomplete groups related props together

### TypeScript Integration

Full TypeScript support with comprehensive type definitions:

```tsx
import type { UiButtonProps } from '@folksam/ui-components';

// Strict typing for component props
function MyButton(props: UiButtonProps) {
  return <UiButton {...props}>{children}</UiButton>;
}

// Union types for controlled APIs
type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'ghost';
type ButtonSize = 'small' | 'medium' | 'large';
```

### Accessibility Standards

- ♿ **WCAG 2.1 AA Compliant**: All components is actively worked on to meet accessibility guidelines and regulations
- ⌨️ **Keyboard Navigation**: Full keyboard support with proper focus management
- 🔊 **Screen Reader Support**: ARIA labels, descriptions, and live regions
- 🎯 **Focus Management**: Logical tab order and focus trapping in modals
- 🏷️ **Semantic HTML**: Proper HTML structure and landmark usage

```tsx
// Accessibility built-in
<UiFormInput
  uiLabel="Password"
  type="password"
  uiDescription="Must be at least 8 characters"
  uiErrorMessage="Password is too short"
  required
  aria-describedby="password-help"
/>
```

## Advanced Usage

### Theming & Customization

Components automatically inherit from your design token system:

```tsx
import { css } from '@pigment-css/react';
import { theme } from '@folksam/ui-design-tokens';

// Custom styling with design tokens
const customButton = css({
  backgroundColor: theme.button_primary_surface,
  borderRadius: theme.radius_l,
  padding: `${theme.spacing_m} ${theme.spacing_l}`,
  '&:hover': {
    backgroundColor: theme.button_primary_surface_hover,
  },
});

<UiButton className={customButton}>Custom Styled Button</UiButton>;
```

## Related Packages

- [`@folksam/ui-design-tokens`](https://www.npmjs.com/package/@folksam/ui-design-tokens) - Design system tokens
- [`@folksam/ui-styles`](https://www.npmjs.com/package/@folksam/ui-styles) - Utility styles and responsive helpers

---

**Built with ❤️ by the Folksam Design System Team**