npm package: @pmcx/ui
Description: A shared design system and UI component library built on Radix UI primitives and styled with Tailwind CSS, providing the visual foundation for pmcx applications.
Latest version: 0.3.0

# @pmcx/ui

A shared design system and UI component library built on Radix UI primitives and styled with Tailwind CSS, providing the visual foundation for pmcx applications.

## Purpose

This package serves as the centralized design system for the pmcx workspace, delivering consistent, accessible, and composable UI primitives for the web application. By maintaining a single source of truth for visual components, we ensure design coherence and reduce duplication while enabling rapid feature development.

## Architecture

### Component Structure

The package follows a layered composition model:

- **Primitives** – Unstyled, accessible components from Radix UI that provide keyboard navigation, focus management, and ARIA attributes
- **Components** – Styled implementations of primitives with design system tokens (colors, spacing, typography) applied through Tailwind CSS
- **Utilities** – Helper functions for class name composition, style merging, and variant management

Each component is exported as a standalone module, allowing consuming applications to import only what they need and enabling tree-shaking for optimal bundle sizes.

### Tailwind Configuration

The design system uses a **shared theme architecture** for consistency:

```
packages/ui/
├── tailwind.theme.ts        # Shared theme factory (single source of truth)
├── tailwind.config.ts       # UI package config (no prefix)
├── tailwind.preset.ts       # Consuming apps preset (ds- prefix)
└── src/styles/tokens.css    # Standalone CSS tokens (ds- prefix)
```

- **`tailwind.theme.ts`**: Exports `createThemeConfig(prefix)` function that generates theme configuration
- **`tailwind.config.ts`**: Uses `createThemeConfig('')` with no prefix for internal components
- **`tailwind.preset.ts`**: Uses `createThemeConfig('ds-')` with `ds-` prefix for consuming applications

This ensures zero duplication and automatic consistency between configurations.

## Design Principles

**Accessibility First** – All components meet WCAG 2.1 standards through Radix UI's built-in accessibility patterns, ensuring keyboard navigation, screen reader support, and proper focus management.

**Composability** – Components are designed to be composed together rather than configured through props, following the compound component pattern where appropriate.

**Theme Consistency** – Visual tokens (colors, typography, spacing) are defined through Tailwind's configuration and consumed via CSS variables, enabling runtime theme switching when needed.

**Type Safety** – Full TypeScript support with exported types for component props, variants, and composition patterns.

## Usage

### Component Usage

Import components directly from their respective paths:

```typescript
import {Button} from '@pmcx/ui/components/button'
import {Input} from '@pmcx/ui/components/input'
import {Stack} from '@pmcx/ui/components/stack'
```

Components support variant-based styling through `class-variance-authority`:

```typescript
<Button variant="primary" size="md">
  Click me
</Button>
```

### Sharing Design Tokens Across Apps

The design system can be consumed by other applications with the `ds-` prefix for namespace isolation.

#### Setup in Consuming App

```typescript
// apps/web/tailwind.config.ts
import dsPreset from '@pmcx/ui/tailwind.preset'

export default {
  presets: [dsPreset],
  prefix: 'ds-',
  content: [
    './src/**/*.{ts,tsx}',
    '../../packages/ui/src/**/*.{ts,tsx}', // Include UI components
  ],
}
```

```tsx
// apps/web/src/app/layout.tsx
import '@pmcx/ui/tokens.css'
```

#### Using Design System Classes

```tsx
<div className="ds-bg-surface-primary-base ds-text-content-strong ds-p-md ds-rounded-lg">
  <h1 className="ds-text-24 ds-font-bold">Hello Design System</h1>
  <button className="ds-bg-surface-info-base ds-text-content-invert-strong ds-px-xs ds-py-2xs">
    Click me
  </button>
</div>
```

#### Available Exports

- `@pmcx/ui` – Component library
- `@pmcx/ui/tailwind.preset` – Tailwind preset with design tokens
- `@pmcx/ui/tokens.css` – CSS custom properties with `--ds-` prefix

### Tailwind Naming Conventions

The configuration follows Tailwind's conventions for token keys:

- **`DEFAULT` (uppercase)**: Reserved Tailwind keyword for top-level colors that generate classes without suffixes
  - `primary: { DEFAULT: '...' }` → `bg-primary`
- **`base`**: Semantic key for nested tokens with multiple variants
  - `error: { base: '...', subdued: '...' }` → `bg-error-base`, `bg-error-subdued`
- **Numeric keys**: Color palette scales
  - `primary: { 500: '...' }` → `bg-primary-500`

CSS variables remain unchanged (e.g., `--color-surface-error-default`) regardless of Tailwind key naming.

## Development

### Building the package

```bash
pnpm build
```

Compiles TypeScript and generates type definitions for distribution.

### Development mode

```bash
pnpm dev
```

Runs in watch mode, rebuilding on file changes for rapid iteration.

### Component documentation

```bash
pnpm storybook:dev
```

Launches Storybook at `http://localhost:6006` to explore components, view usage examples, and test different states interactively.

### Code quality

```bash
pnpm lint        # Check for code issues
pnpm format      # Auto-fix and format code
```

## Integration

Applications consuming this package must:

1. **Install dependencies**: Ensure Tailwind CSS and required peer dependencies are installed
2. **Configure Tailwind**: Either use the preset (recommended) or configure Tailwind to include the design system's tokens manually
3. **Import styles**: Import component styles or token CSS as needed

For consuming the design system with namespace isolation, use the Tailwind preset approach documented in the Usage section above.