@pmcx/ui

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

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:

<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

// 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
  ],
}

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

Using Design System Classes

<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

pnpm build

Compiles TypeScript and generates type definitions for distribution.

Development mode

pnpm dev

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

Component documentation

pnpm storybook:dev

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

Code quality

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

Integration

Applications consuming this package must:

• Install dependencies: Ensure Tailwind CSS and required peer dependencies are installed
• Configure Tailwind: Either use the preset (recommended) or configure Tailwind to include the design system's tokens manually
• 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.