@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

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

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.):

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:

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 for details.

Development

Prerequisites

• Node.js 18+
• pnpm 10+

Setup

1. Clone the repository
2. Run setup:

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)

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:

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