npm package: @plink/ui-library
Description: Reusable React UI component library with TypeScript and Tailwind CSS
Latest version: 0.5.0

# @plink/ui-library

A reusable React UI component library built with TypeScript and Tailwind CSS.

## Features

- 🎨 **Plink Brand Colors** - Consistent design tokens with auto-generated palettes
- 🎭 **Tailwind CSS v4** - Modern CSS-first configuration
- 📦 **Tree-shakeable** - ES modules with optimized bundles
- 🔷 **TypeScript** - Full type safety with advanced patterns
- ⚡ **Vite Powered** - Lightning-fast builds and HMR
- 🎯 **React 18+** - Modern React with hooks and memoization
- 🖋️ **Custom Fonts** - Montserrat (headings) + Open Sans (body)
- 🔧 **Node.js Ready** - Use color tokens in any project (`/tokens` export)

## Installation

```bash
# Using pnpm
pnpm add @plink/ui-library

# Using npm
npm install @plink/ui-library

# Using yarn
yarn add @plink/ui-library
```

## Usage

### React Projects

Import components in your React application. Styles are automatically included:

```tsx
import { Heading, Text, colors } from '@plink/ui-library';

function App() {
  return (
    <div>
      <Heading as="h1" color="primary">
        Plink Dashboard
      </Heading>

      <Text size="lg" color="neutral">
        Welcome back!
      </Text>

      {/* Use color tokens directly */}
      <div style={{ backgroundColor: colors.primary[50] }}>
        Custom styled component
      </div>
    </div>
  );
}
```

### Node.js Projects (Tokens Only)

Use Plink's brand colors in Node.js projects (emails, PDFs, etc.):

```js
import { colors } from '@plink/ui-library/tokens';

// Email templates
const emailHTML = `
  <div style="color: ${colors.primary[500]}">
    Hello from Plink!
  </div>
`;
```

> **Note:** CSS is automatically injected when you import components. No separate stylesheet import is needed!

## Adding Custom Colors

Edit `src/theme/tokens.ts` to add new colors:

```ts
export const colorDefinitions = {
  primary: '#334BC1',    // Plink primary blue
  accent: '#30CCD5',     // Plink accent cyan

  // Add your colors here:
  brand: '#FF5733',

  // ...
};
```

Then run `pnpm generate-theme` to regenerate theme files. See [`src/theme/README.md`](./src/theme/README.md) for details.

## Development

### Prerequisites

- Node.js 18+
- pnpm 10+

### Setup

1. Clone the repository
2. Run setup:

```bash
pnpm setup
```

This will install dependencies and auto-generate theme files.

### Available Scripts

- `pnpm setup` - Install dependencies + generate theme files (first time setup)
- `pnpm generate-theme` - Regenerate theme files from `src/theme/tokens.ts`
- `pnpm dev` - Start the development server with component playground
- `pnpm build` - Build the library for production
- `pnpm preview` - Preview the production build
- `pnpm lint` - Run ESLint

### Project Structure

```
ui-library/
├── src/
│   ├── components/         # React components (Text, Heading, etc.)
│   ├── theme/
│   │   ├── tokens.ts      # ← Edit colors/fonts here
│   │   ├── colors.ts      # Auto-generated
│   │   ├── colorClassMap.ts # Auto-generated
│   │   └── README.md      # Theme system docs
│   ├── styles/
│   │   └── index.css      # Auto-generated (Tailwind v4)
│   ├── typeHelpers.ts     # Advanced TypeScript utilities
│   ├── index.ts           # Main entry point
│   └── tokens-only.ts     # Node.js-only export
├── scripts/
│   └── generate-theme.ts  # Theme generator script
├── dist/                  # Built output (generated)
├── .github/
│   └── workflows/         # CI/CD workflows
├── vite.config.ts         # Vite configuration
└── tsconfig.json          # TypeScript configuration
```

## Building

The library is built using Vite in library mode, which generates:

- ESM format (`dist/index.js`) with CSS injected
- CommonJS format (`dist/index.cjs`) with CSS injected
- TypeScript declarations (`dist/index.d.ts`)

```bash
pnpm build
```

## Publishing

The library is automatically published to npm when a new release is created on GitHub. The CI/CD pipeline handles:

1. Running type checks
2. Building the library
3. Publishing to npm (on release events)

To publish manually:

```bash
pnpm build
pnpm publish
```

## CI/CD

This project uses GitHub Actions for continuous integration and deployment:

- **CI/CD Pipeline**: Runs on all pushes and pull requests, performs type checking and builds
- **Claude Code Review**: Automated PR reviews using Claude AI
- **Claude Interactive**: Trigger Claude by mentioning `@claude` in issues or PRs